Refactoring SDK Tool

src/index.ts

@@ -48,6 +48,5 @@ process.on("exit", () => {
   logger.flush();
 });
 
-
 export { setLogger } from "./logger.js";
 export { BrowserStackMcpServer } from "./server-factory.js";

src/server-factory.ts

@@ -7,6 +7,7 @@ const require = createRequire(import.meta.url);
 const packageJson = require("../package.json");
 import logger from "./logger.js";
 import addSDKTools from "./tools/bstack-sdk.js";
+import addPercyTools from "./tools/percy-sdk.js";
 import addBrowserLiveTools from "./tools/live.js";
 import addAccessibilityTools from "./tools/accessibility.js";
 import addTestManagementTools from "./tools/testmanagement.js";
@@ -48,6 +49,7 @@ export class BrowserStackMcpServer {
     const toolAdders = [
       addAccessibilityTools,
       addSDKTools,
+      addPercyTools,
       addAppLiveTools,
       addBrowserLiveTools,
       addTestManagementTools,
@@ -80,7 +82,7 @@ export class BrowserStackMcpServer {
   public getTools(): Record<string, RegisteredTool> {
     return this.tools;
   }
-  
+
   public getTool(name: string): RegisteredTool | undefined {
     return this.tools[name];
   }

src/tools/bstack-sdk.ts

@@ -1,254 +1,26 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
-import { z } from "zod";
-import { trackMCP } from "../lib/instrumentation.js";
-import { getSDKPrefixCommand } from "./sdk-utils/commands.js";
-
-import {
-  SDKSupportedBrowserAutomationFramework,
-  SDKSupportedLanguage,
-  SDKSupportedTestingFramework,
-  SDKSupportedLanguageEnum,
-  SDKSupportedBrowserAutomationFrameworkEnum,
-  SDKSupportedTestingFrameworkEnum,
-} from "./sdk-utils/types.js";
-
-import {
-  generateBrowserStackYMLInstructions,
-  getInstructionsForProjectConfiguration,
-  formatInstructionsWithNumbers,
-} from "./sdk-utils/instructions.js";
-
-import {
-  formatPercyInstructions,
-  getPercyInstructions,
-} from "./sdk-utils/percy/instructions.js";
-import { getBrowserStackAuth } from "../lib/get-auth.js";
 import { BrowserStackConfig } from "../lib/types.js";
+import { RunTestsOnBrowserStackParamsShape } from "./sdk-utils/common/schema.js";
+import { runTestsOnBrowserStackHandler } from "./sdk-utils/handler.js";
 
-/**
- * BrowserStack SDK hooks into your test framework to seamlessly run tests on BrowserStack.
- * This tool gives instructions to setup a browserstack.yml file in the project root and installs the necessary dependencies.
- */
-export async function bootstrapProjectWithSDK({
-  detectedBrowserAutomationFramework,
-  detectedTestingFramework,
-  detectedLanguage,
-  desiredPlatforms,
-  enablePercy,
-  config,
-}: {
-  detectedBrowserAutomationFramework: SDKSupportedBrowserAutomationFramework;
-  detectedTestingFramework: SDKSupportedTestingFramework;
-  detectedLanguage: SDKSupportedLanguage;
-  desiredPlatforms: string[];
-  enablePercy: boolean;
-  config: BrowserStackConfig;
-}): Promise<CallToolResult> {
-  // Get credentials from config
-  const authString = getBrowserStackAuth(config);
-  const [username, accessKey] = authString.split(":");
-
-  // Handle frameworks with unique setup instructions that don't use browserstack.yml
-  if (
-    detectedBrowserAutomationFramework === "cypress" ||
-    detectedTestingFramework === "webdriverio"
-  ) {
-    let combinedInstructions = getInstructionsForProjectConfiguration(
-      detectedBrowserAutomationFramework,
-      detectedTestingFramework,
-      detectedLanguage,
-      username,
-      accessKey,
-    );
-
-    if (enablePercy) {
-      const percyInstructions = getPercyInstructions(
-        detectedLanguage,
-        detectedBrowserAutomationFramework,
-        detectedTestingFramework,
-      );
+const RUN_ON_BROWSERSTACK_DESCRIPTION =
+  "Set up and run automated web-based tests on BrowserStack using the BrowserStack SDK. Use this tool for functional or integration test setup on BrowserStack only. For any visual testing or Percy integration, use the dedicated Percy setup tool. Example prompts: run this test on browserstack; set up this project for browserstack.";
 
-      if (percyInstructions) {
-        combinedInstructions +=
-          "\n\n" + formatPercyInstructions(percyInstructions);
-      } else {
-        throw new Error(
-          `Percy is currently not supported through MCP for ${detectedLanguage} with ${detectedTestingFramework}. If you want to run the test cases without Percy, disable Percy and run it again.`,
-        );
-      }
-    }
-
-    // Apply consistent formatting for all configurations
-    return formatFinalInstructions(combinedInstructions);
-  }
-
-  // Handle default flow using browserstack.yml
-  const sdkSetupCommand = getSDKPrefixCommand(
-    detectedLanguage,
-    detectedTestingFramework,
-    username,
-    accessKey,
-  );
-
-  const ymlInstructions = generateBrowserStackYMLInstructions(
-    desiredPlatforms,
-    enablePercy,
-  );
-
-  const instructionsForProjectConfiguration =
-    getInstructionsForProjectConfiguration(
-      detectedBrowserAutomationFramework,
-      detectedTestingFramework,
-      detectedLanguage,
-      username,
-      accessKey,
-    );
-
-  let combinedInstructions = "";
-
-  // Step 1: Add SDK setup command
-  if (sdkSetupCommand) {
-    combinedInstructions += sdkSetupCommand;
-  }
-
-  // Step 2: Add browserstack.yml setup
-  if (ymlInstructions) {
-    combinedInstructions += "\n\n---STEP---\n" + ymlInstructions;
-  }
-
-  // Step 3: Add language/framework-specific setup
-  if (instructionsForProjectConfiguration) {
-    combinedInstructions += "\n\n" + instructionsForProjectConfiguration;
-  }
-
-  // Step 4: Add Percy setup if applicable
-  if (enablePercy) {
-    const percyInstructions = getPercyInstructions(
-      detectedLanguage,
-      detectedBrowserAutomationFramework,
-      detectedTestingFramework,
-    );
-
-    if (percyInstructions) {
-      combinedInstructions +=
-        "\n\n" + formatPercyInstructions(percyInstructions);
-    } else {
-      throw new Error(
-        `Percy is currently not supported through MCP for ${detectedLanguage} with ${detectedTestingFramework}. If you want to run the test cases without Percy, disable Percy and run it again.`,
-      );
-    }
-  }
-
-  // Apply consistent formatting for all configurations
-  return formatFinalInstructions(combinedInstructions);
-}
-
-// Helper function to apply consistent formatting to all instruction types
-function formatFinalInstructions(combinedInstructions: string): CallToolResult {
-  const fullInstructions = `⚠️ IMPORTANT: DO NOT SKIP ANY STEP
-  All the setup steps described in this file MUST be executed regardless of any existing configuration or setup.
-  This ensures proper BrowserStack SDK setup.
-
-  ${formatInstructionsWithNumbers(combinedInstructions)}`;
-
-  return {
-    content: [
-      {
-        type: "text",
-        text: fullInstructions,
-        isError: false,
-      },
-    ],
-  };
-}
-
-export default function addSDKTools(
+export function registerRunBrowserStackTestsTool(
   server: McpServer,
   config: BrowserStackConfig,
 ) {
   const tools: Record<string, any> = {};
-
-  tools.runTestsOnBrowserStack = server.tool(
-    "runTestsOnBrowserStack",
-    "Use this tool to get instructions for running tests on BrowserStack and BrowserStack Percy. It sets up the BrowserStack SDK and runs your test cases on BrowserStack.",
-    {
-      detectedBrowserAutomationFramework: z
-        .nativeEnum(SDKSupportedBrowserAutomationFrameworkEnum)
-        .describe(
-          "The automation framework configured in the project. Example: 'playwright', 'selenium'",
-        ),
-
-      detectedTestingFramework: z
-        .nativeEnum(SDKSupportedTestingFrameworkEnum)
-        .describe(
-          "The testing framework used in the project. Be precise with framework selection Example: 'webdriverio', 'jest', 'pytest', 'junit4', 'junit5', 'mocha'",
-        ),
-
-      detectedLanguage: z
-        .nativeEnum(SDKSupportedLanguageEnum)
-        .describe(
-          "The programming language used in the project. Example: 'nodejs', 'python', 'java', 'csharp'",
-        ),
-
-      desiredPlatforms: z
-        .array(z.enum(["windows", "macos", "android", "ios"]))
-        .describe(
-          "The platforms the user wants to test on. Always ask this to the user, do not try to infer this.",
-        ),
-
-      enablePercy: z
-        .boolean()
-        .optional()
-        .default(false)
-        .describe(
-          "Set to true if the user wants to enable Percy for visual testing. Defaults to false.",
-        ),
-    },
-
+  tools.setupBrowserStackAutomateTests = server.tool(
+    "setupBrowserStackAutomateTests",
+    RUN_ON_BROWSERSTACK_DESCRIPTION,
+    RunTestsOnBrowserStackParamsShape,
     async (args) => {
-      try {
-        trackMCP(
-          "runTestsOnBrowserStack",
-          server.server.getClientVersion()!,
-          undefined,
-          config,
-        );
-
-        return await bootstrapProjectWithSDK({
-          detectedBrowserAutomationFramework:
-            args.detectedBrowserAutomationFramework as SDKSupportedBrowserAutomationFramework,
-
-          detectedTestingFramework:
-            args.detectedTestingFramework as SDKSupportedTestingFramework,
-
-          detectedLanguage: args.detectedLanguage as SDKSupportedLanguage,
-
-          desiredPlatforms: args.desiredPlatforms,
-          enablePercy: args.enablePercy,
-          config,
-        });
-      } catch (error) {
-        trackMCP(
-          "runTestsOnBrowserStack",
-          server.server.getClientVersion()!,
-          error,
-          config,
-        );
-
-        return {
-          content: [
-            {
-              type: "text",
-              text: `Failed to bootstrap project with BrowserStack SDK. Error: ${error}. Please open an issue on GitHub if the problem persists`,
-              isError: true,
-            },
-          ],
-          isError: true,
-        };
-      }
+      return runTestsOnBrowserStackHandler(args, config);
     },
   );
 
   return tools;
 }
+
+export default registerRunBrowserStackTestsTool;

src/tools/percy-sdk.ts

@@ -0,0 +1,32 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BrowserStackConfig } from "../lib/types.js";
+import { SetUpPercyParamsShape } from "./sdk-utils/common/schema.js";
+import { setUpPercyHandler } from "./sdk-utils/handler.js";
+
+/**
+ * Tool description for standalone Percy visual testing
+ */
+const SETUP_PERCY_DESCRIPTION =
+  "Set up Percy visual testing for your project. This supports both Percy Web Standalone and Percy Automate.";
+
+/**
+ * Registers the standalone Percy setup tool with the MCP server.
+ * Focuses on Percy Web and Percy Automate without BrowserStack integration.
+ */
+export function registerPercySetupTool(
+  server: McpServer,
+  config: BrowserStackConfig,
+) {
+  const tools: Record<string, any> = {};
+  tools.setupPercyVisualTesting = server.tool(
+    "setupPercyVisualTesting",
+    SETUP_PERCY_DESCRIPTION,
+    SetUpPercyParamsShape,
+    async (args) => {
+      return setUpPercyHandler(args, config);
+    },
+  );
+  return tools;
+}
+
+export default registerPercySetupTool;