refactor(percy): drop unused fetchPercyToken calls in setup paths

The token was fetched server-side then discarded (replaced with
placeholder instructions). Removing the dead fetch in runPercyScan
and setUpPercyHandler eliminates a wasted API call per setup, drops
the void percyToken; smell from the SDK handlers, and removes the
last code path that sent privileged credentials across the function
boundary just to throw them away. fetchPercyToken stays for
fetchPercyChanges, which still uses it for legitimate server-side
calls. Setup instructions now point users at .env or shell export.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: manoj-k04

src/tools/run-percy-scan.ts

@@ -1,8 +1,6 @@
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { PercyIntegrationTypeEnum } from "./sdk-utils/common/types.js";
 import { BrowserStackConfig } from "../lib/types.js";
-import { getBrowserStackAuth } from "../lib/get-auth.js";
-import { fetchPercyToken } from "./sdk-utils/percy-web/fetchPercyToken.js";
 import { storedPercyResults } from "../lib/inmemory-store.js";
 import {
   getFrameworkTestCommand,
@@ -16,13 +14,9 @@ export async function runPercyScan(
     integrationType: PercyIntegrationTypeEnum;
     instruction?: string;
   },
-  config: BrowserStackConfig,
+  _config: BrowserStackConfig,
 ): Promise<CallToolResult> {
-  const { projectName, integrationType, instruction } = args;
-  const authorization = getBrowserStackAuth(config);
-  const percyToken = await fetchPercyToken(projectName, authorization, {
-    type: integrationType,
-  });
+  const { projectName, instruction } = args;
 
   // Check if we have stored data and project matches
   const stored = storedPercyResults.get();
@@ -31,8 +25,6 @@ export async function runPercyScan(
   const hasUpdatedFiles = checkForUpdatedFiles(stored, projectName);
   const updatedFiles = hasUpdatedFiles ? getUpdatedFiles(stored) : [];
 
-  void percyToken;
-
   // Build steps array with conditional spread
   const steps = [
     generatePercyTokenInstructions(),
@@ -58,11 +50,13 @@ export async function runPercyScan(
 }
 
 function generatePercyTokenInstructions(): string {
-  return `Set the PERCY_TOKEN environment variable for your project. Retrieve your project's token from the Percy dashboard (https://percy.io → Project Settings → Project Token), then export it locally — do not paste it into chat or commit it:
+  return `Set the PERCY_TOKEN environment variable for your project. Retrieve your project's token from the Percy dashboard (https://percy.io → Project Settings → Project Token) and add it to your project's .env file (PERCY_TOKEN=<your Percy project token>) or export it in your shell:
 
   - macOS/Linux:    export PERCY_TOKEN="<your Percy project token>"
   - Windows (PS):   $env:PERCY_TOKEN="<your Percy project token>"
-  - Windows (CMD):  set PERCY_TOKEN=<your Percy project token>`;
+  - Windows (CMD):  set PERCY_TOKEN=<your Percy project token>
+
+Do not paste the token into chat or commit it.`;
 }
 
 const toAbs = (p: string): string | undefined =>

src/tools/sdk-utils/handler.ts

@@ -2,8 +2,6 @@ import { formatToolResult } from "./common/utils.js";
 import { BrowserStackConfig } from "../../lib/types.js";
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { PercyIntegrationTypeEnum } from "./common/types.js";
-import { getBrowserStackAuth } from "../../lib/get-auth.js";
-import { fetchPercyToken } from "./percy-web/fetchPercyToken.js";
 import { runPercyWeb } from "./percy-web/handler.js";
 import { runPercyAutomateOnly } from "./percy-automate/handler.js";
 import { runBstackSDKOnly } from "./bstack/sdkHandler.js";
@@ -60,8 +58,6 @@ export async function setUpPercyHandler(
       testFiles: {},
     });
 
-    const authorization = getBrowserStackAuth(config);
-
     const folderPaths = input.folderPaths || [];
     const filePaths = input.filePaths || [];
 
@@ -86,14 +82,7 @@ export async function setUpPercyHandler(
         );
       }
 
-      // Fetch the Percy token
-      const percyToken = await fetchPercyToken(
-        input.projectName,
-        authorization,
-        { type: PercyIntegrationTypeEnum.WEB },
-      );
-
-      const result = runPercyWeb(percyInput, percyToken);
+      const result = runPercyWeb(percyInput);
       return await formatToolResult(result, "percy-web");
     } else if (input.integrationType === PercyIntegrationTypeEnum.AUTOMATE) {
       // First try Percy with BrowserStack SDK
@@ -142,15 +131,7 @@ export async function setUpPercyHandler(
         };
         const sdkResult = await runBstackSDKOnly(sdkInput, config, true);
         // Percy Automate instructions
-        const percyToken = await fetchPercyToken(
-          input.projectName,
-          authorization,
-          { type: PercyIntegrationTypeEnum.AUTOMATE },
-        );
-        const percyAutomateResult = runPercyAutomateOnly(
-          percyInput,
-          percyToken,
-        );
+        const percyAutomateResult = runPercyAutomateOnly(percyInput);
 
         // Combine steps: warning, SDK steps, Percy Automate steps
         const steps = [

src/tools/sdk-utils/percy-automate/handler.ts

@@ -5,12 +5,9 @@ import { SDKSupportedLanguage } from "../common/types.js";
 
 export function runPercyAutomateOnly(
   input: SetUpPercyInput,
-  percyToken: string,
 ): RunTestsInstructionResult {
   const steps: RunTestsStep[] = [];
 
-  void percyToken;
-
   // Assume configuration is supported due to guardrails at orchestration layer
   const languageConfig =
     SUPPORTED_CONFIGURATIONS[input.detectedLanguage as SDKSupportedLanguage];
@@ -28,7 +25,7 @@ export function runPercyAutomateOnly(
   steps.push({
     type: "instruction",
     title: "Set Percy Token in Environment",
-    content: `Retrieve your project's token from the Percy dashboard (https://percy.io → Project Settings → Project Token), then set PERCY_TOKEN in your environment (e.g. export PERCY_TOKEN="<your Percy project token>"). Do not paste the token into chat or commit it.`,
+    content: `Retrieve your project's token from the Percy dashboard (https://percy.io → Project Settings → Project Token) and add it to your project's .env file (PERCY_TOKEN=<your Percy project token>) or export it in your shell (e.g. export PERCY_TOKEN="<your Percy project token>"). Do not paste the token into chat or commit it.`,
   });
 
   steps.push({

src/tools/sdk-utils/percy-web/handler.ts

@@ -12,12 +12,9 @@ export let percyWebSetupInstructions = "";
 
 export function runPercyWeb(
   input: SetUpPercyInput,
-  percyToken: string,
 ): RunTestsInstructionResult {
   const steps: RunTestsStep[] = [];
 
-  void percyToken;
-
   // Assume configuration is supported due to guardrails at orchestration layer
   const languageConfig =
     SUPPORTED_CONFIGURATIONS[input.detectedLanguage as SDKSupportedLanguage];
@@ -34,10 +31,12 @@ export function runPercyWeb(
   steps.push({
     type: "instruction",
     title: "Set Percy Token in Environment",
-    content: `Retrieve your project's token from the Percy dashboard (https://percy.io → Project Settings → Project Token), then set it locally:
+    content: `Retrieve your project's token from the Percy dashboard (https://percy.io → Project Settings → Project Token) and add it to your project's .env file (PERCY_TOKEN=<your Percy project token>) or export it in your shell:
         macOS/Linux:    export PERCY_TOKEN="<your Percy project token>"
         Windows (PS):   $env:PERCY_TOKEN="<your Percy project token>"
-        Windows (CMD):  set PERCY_TOKEN=<your Percy project token>`,
+        Windows (CMD):  set PERCY_TOKEN=<your Percy project token>
+
+Do not paste the token into chat or commit it.`,
   });
 
   steps.push({

tests/tools/percyTokenLeak.test.ts

@@ -1,15 +1,8 @@
 import { describe, it, expect, vi, beforeEach, Mock } from "vitest";
 import { runPercyScan } from "../../src/tools/run-percy-scan";
-import { fetchPercyToken } from "../../src/tools/sdk-utils/percy-web/fetchPercyToken";
 import { storedPercyResults } from "../../src/lib/inmemory-store";
 import { PercyIntegrationTypeEnum } from "../../src/tools/sdk-utils/common/types";
 
-vi.mock("../../src/lib/get-auth", () => ({
-  getBrowserStackAuth: vi.fn().mockReturnValue("fake-user:fake-key"),
-}));
-vi.mock("../../src/tools/sdk-utils/percy-web/fetchPercyToken", () => ({
-  fetchPercyToken: vi.fn(),
-}));
 vi.mock("../../src/lib/inmemory-store", () => ({
   storedPercyResults: { get: vi.fn(), set: vi.fn() },
 }));
@@ -29,9 +22,7 @@ const mockConfig = {
 describe("runPercyScan", () => {
   beforeEach(() => vi.clearAllMocks());
 
-  it("SECURITY: never echoes the fetched Percy token in output", async () => {
-    const SECRET = "percy-secret-token-DO-NOT-LEAK";
-    (fetchPercyToken as Mock).mockResolvedValue(SECRET);
+  it("renders PERCY_TOKEN setup instructions with placeholder", async () => {
     (storedPercyResults.get as Mock).mockReturnValue(null);
 
     const result = await runPercyScan(
@@ -43,14 +34,12 @@ describe("runPercyScan", () => {
     );
 
     const text = result.content[0].text as string;
-    expect(text).not.toContain(SECRET);
     expect(text).toContain("PERCY_TOKEN");
     expect(text).toContain("<your Percy project token>");
+    expect(text).toContain(".env");
   });
 
-  it("SUCCESS: includes updated file instructions when available", async () => {
-    const SECRET = "percy-secret-token-DO-NOT-LEAK";
-    (fetchPercyToken as Mock).mockResolvedValue(SECRET);
+  it("includes updated file instructions when available", async () => {
     (storedPercyResults.get as Mock).mockReturnValue({
       projectName: "my-project",
       testFiles: { "/tests/login.test.js": true },
@@ -67,13 +56,10 @@ describe("runPercyScan", () => {
     );
 
     const text = result.content[0].text as string;
-    expect(text).not.toContain(SECRET);
     expect(text).toContain("Updated files to run");
   });
 
-  it("SUCCESS: includes custom instruction steps", async () => {
-    const SECRET = "percy-secret-token-DO-NOT-LEAK";
-    (fetchPercyToken as Mock).mockResolvedValue(SECRET);
+  it("includes custom instruction steps", async () => {
     (storedPercyResults.get as Mock).mockReturnValue(null);
 
     const result = await runPercyScan(
@@ -86,24 +72,6 @@ describe("runPercyScan", () => {
     );
 
     const text = result.content[0].text as string;
-    expect(text).not.toContain(SECRET);
     expect(text).toContain("npx percy exec");
   });
-
-  it("FAIL: throws when Percy token fetch fails", async () => {
-    (fetchPercyToken as Mock).mockRejectedValue(
-      new Error("Percy token not found"),
-    );
-    (storedPercyResults.get as Mock).mockReturnValue(null);
-
-    await expect(
-      runPercyScan(
-        {
-          projectName: "bad-project",
-          integrationType: PercyIntegrationTypeEnum.WEB,
-        },
-        mockConfig,
-      ),
-    ).rejects.toThrow("Percy token not found");
-  });
 });