Feat : Local MCP library

package.json

@@ -61,4 +61,4 @@
     "vite": "^6.3.5",
     "vitest": "^3.1.3"
   }
-}
+}

src/config.ts

@@ -36,20 +36,18 @@ for (const key of BROWSERSTACK_LOCAL_OPTION_KEYS) {
  */
 export class Config {
   constructor(
-    public readonly browserstackUsername: string,
-    public readonly browserstackAccessKey: string,
     public readonly DEV_MODE: boolean,
     public readonly browserstackLocalOptions: Record<string, any>,
     public readonly USE_OWN_LOCAL_BINARY_PROCESS: boolean,
+    public readonly REMOTE_MCP: boolean,
   ) {}
 }
 
 const config = new Config(
-  process.env.BROWSERSTACK_USERNAME!,
-  process.env.BROWSERSTACK_ACCESS_KEY!,
   process.env.DEV_MODE === "true",
   browserstackLocalOptions,
   process.env.USE_OWN_LOCAL_BINARY_PROCESS === "true",
+  process.env.REMOTE_MCP === "true",
 );
 
 export default config;

src/index.ts

@@ -1,53 +1,43 @@
 #!/usr/bin/env node
 
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { createRequire } from "module";
 const require = createRequire(import.meta.url);
 const packageJson = require("../package.json");
 import "dotenv/config";
 import logger from "./logger.js";
-import addSDKTools from "./tools/bstack-sdk.js";
-import addAppLiveTools from "./tools/applive.js";
-import addBrowserLiveTools from "./tools/live.js";
-import addAccessibilityTools from "./tools/accessibility.js";
-import addTestManagementTools from "./tools/testmanagement.js";
-import addAppAutomationTools from "./tools/appautomate.js";
-import addFailureLogsTools from "./tools/getFailureLogs.js";
-import addAutomateTools from "./tools/automate.js";
-import addSelfHealTools from "./tools/selfheal.js";
-import { setupOnInitialized } from "./oninitialized.js";
-
-function registerTools(server: McpServer) {
-  addAccessibilityTools(server);
-  addSDKTools(server);
-  addAppLiveTools(server);
-  addBrowserLiveTools(server);
-  addTestManagementTools(server);
-  addAppAutomationTools(server);
-  addFailureLogsTools(server);
-  addAutomateTools(server);
-  addSelfHealTools(server);
-}
-
-// Create an MCP server
-const server: McpServer = new McpServer({
-  name: "BrowserStack MCP Server",
-  version: packageJson.version,
-});
-
-setupOnInitialized(server);
-
-registerTools(server);
+import { createMcpServer } from "./server-factory.js";
 
 async function main() {
   logger.info(
     "Launching BrowserStack MCP server, version %s",
     packageJson.version,
   );
 
-  // Start receiving messages on stdin and sending messages on stdout
+  const remoteMCP = process.env.REMOTE_MCP === "true";
+  if (remoteMCP) {
+    logger.info("Running in remote MCP mode");
+    return;
+  }
+
+  const username = process.env.BROWSERSTACK_USERNAME;
+  const accessKey = process.env.BROWSERSTACK_ACCESS_KEY;
+
+  if (!username) {
+    throw new Error("BROWSERSTACK_USERNAME environment variable is required");
+  }
+
+  if (!accessKey) {
+    throw new Error("BROWSERSTACK_ACCESS_KEY environment variable is required");
+  }
+
   const transport = new StdioServerTransport();
+
+  const server = createMcpServer({
+    "browserstack-username": username,
+    "browserstack-access-key": accessKey,
+  });
+
   await server.connect(transport);
 }
 
@@ -57,3 +47,6 @@ main().catch(console.error);
 process.on("exit", () => {
   logger.flush();
 });
+
+export { default as logger } from "./logger.js";
+export { createMcpServer } from "./server-factory.js";

src/lib/api.ts

@@ -1,18 +1,23 @@
-import config from "../config.js";
+import { getBrowserStackAuth } from "./get-auth.js";
+import { BrowserStackConfig } from "../lib/types.js";
+import { apiClient } from "./apiClient.js";
 
 export async function getLatestO11YBuildInfo(
   buildName: string,
   projectName: string,
+  config: BrowserStackConfig,
 ) {
   const buildsUrl = `https://api-observability.browserstack.com/ext/v1/builds/latest?build_name=${encodeURIComponent(
     buildName,
   )}&project_name=${encodeURIComponent(projectName)}`;
 
-  const buildsResponse = await fetch(buildsUrl, {
+  const authString = getBrowserStackAuth(config);
+  const auth = Buffer.from(authString).toString("base64");
+
+  const buildsResponse = await apiClient.get({
+    url: buildsUrl,
     headers: {
-      Authorization: `Basic ${Buffer.from(
-        `${config.browserstackUsername}:${config.browserstackAccessKey}`,
-      ).toString("base64")}`,
+      Authorization: `Basic ${auth}`,
     },
   });
 
@@ -25,5 +30,5 @@ export async function getLatestO11YBuildInfo(
     throw new Error(`Failed to fetch builds: ${buildsResponse.statusText}`);
   }
 
-  return buildsResponse.json();
+  return buildsResponse;
 }

src/lib/apiClient.ts

@@ -0,0 +1,118 @@
+import axios, { AxiosRequestConfig, AxiosResponse } from "axios";
+
+type RequestOptions = {
+  url: string;
+  headers?: Record<string, string>;
+  params?: Record<string, string | number>;
+  body?: any;
+};
+
+class ApiResponse<T = any> {
+  private _response: AxiosResponse<T>;
+
+  constructor(response: AxiosResponse<T>) {
+    this._response = response;
+  }
+
+  get data(): T {
+    return this._response.data;
+  }
+
+  get status(): number {
+    return this._response.status;
+  }
+
+  get statusText(): string {
+    return this._response.statusText;
+  }
+
+  get headers(): Record<string, string> {
+    const raw = this._response.headers;
+    const sanitized: Record<string, string> = {};
+
+    for (const key in raw) {
+      const value = raw[key];
+      if (typeof value === "string") {
+        sanitized[key] = value;
+      }
+    }
+
+    return sanitized;
+  }
+
+  get config(): AxiosRequestConfig {
+    return this._response.config;
+  }
+
+  get url(): string | undefined {
+    return this._response.config.url;
+  }
+
+  get ok(): boolean {
+    return this._response.status >= 200 && this._response.status < 300;
+  }
+}
+
+class ApiClient {
+  private instance = axios.create();
+
+  async get<T = any>({
+    url,
+    headers,
+    params,
+  }: RequestOptions): Promise<ApiResponse<T>> {
+    const res = await this.instance.get<T>(url, {
+      headers,
+      params,
+    });
+    return new ApiResponse<T>(res);
+  }
+
+  async post<T = any>({
+    url,
+    headers,
+    body,
+  }: RequestOptions): Promise<ApiResponse<T>> {
+    const res = await this.instance.post<T>(url, body, {
+      headers,
+    });
+    return new ApiResponse<T>(res);
+  }
+
+  async put<T = any>({
+    url,
+    headers,
+    body,
+  }: RequestOptions): Promise<ApiResponse<T>> {
+    const res = await this.instance.put<T>(url, body, {
+      headers,
+    });
+    return new ApiResponse<T>(res);
+  }
+
+  async patch<T = any>({
+    url,
+    headers,
+    body,
+  }: RequestOptions): Promise<ApiResponse<T>> {
+    const res = await this.instance.patch<T>(url, body, {
+      headers,
+    });
+    return new ApiResponse<T>(res);
+  }
+
+  async delete<T = any>({
+    url,
+    headers,
+    params,
+  }: RequestOptions): Promise<ApiResponse<T>> {
+    const res = await this.instance.delete<T>(url, {
+      headers,
+      params,
+    });
+    return new ApiResponse<T>(res);
+  }
+}
+
+export const apiClient = new ApiClient();
+export type { ApiResponse, RequestOptions };

src/lib/device-cache.ts

@@ -1,6 +1,7 @@
 import fs from "fs";
 import os from "os";
 import path from "path";
+import { apiClient } from "./apiClient.js";
 
 const CACHE_DIR = path.join(os.homedir(), ".browserstack", "combined_cache");
 const CACHE_FILE = path.join(CACHE_DIR, "data.json");
@@ -48,18 +49,16 @@ export async function getDevicesAndBrowsers(
     }
   }
 
-  const liveRes = await fetch(URLS[type]);
+  const liveRes = await apiClient.get({ url: URLS[type] });
 
   if (!liveRes.ok) {
     throw new Error(
       `Failed to fetch configuration from BrowserStack : ${type}=${liveRes.statusText}`,
     );
   }
 
-  const data = await liveRes.json();
-
   cache = {
-    [type]: data,
+    [type]: liveRes,
   };
   fs.writeFileSync(CACHE_FILE, JSON.stringify(cache), "utf8");
 

src/lib/get-auth.ts

@@ -0,0 +1,10 @@
+import { BrowserStackConfig } from "../lib/types.js";
+
+export function getBrowserStackAuth(config: BrowserStackConfig): string {
+  const username = config["browserstack-username"];
+  const accessKey = config["browserstack-access-key"];
+  if (!username || !accessKey) {
+    throw new Error("BrowserStack credentials not set on server.authHeaders");
+  }
+  return `${username}:${accessKey}`;
+}

src/lib/instrumentation.ts

@@ -1,5 +1,5 @@
 import logger from "../logger.js";
-import config from "../config.js";
+import { getBrowserStackAuth } from "./get-auth.js";
 import { createRequire } from "module";
 const require = createRequire(import.meta.url);
 const packageJson = require("../../package.json");
@@ -21,12 +21,8 @@ export function trackMCP(
   toolName: string,
   clientInfo: { name?: string; version?: string },
   error?: unknown,
+  config?: any,
 ): void {
-  if (config.DEV_MODE) {
-    logger.info("Tracking MCP is disabled in dev mode");
-    return;
-  }
-
   const instrumentationEndpoint = "https://api.browserstack.com/sdk/v1/event";
   const isSuccess = !error;
   const mcpClient = clientInfo?.name || "unknown";
@@ -58,13 +54,17 @@ export function trackMCP(
       error instanceof Error ? error.constructor.name : "Unknown";
   }
 
+  let authHeader = undefined;
+  if (config) {
+    const authString = getBrowserStackAuth(config);
+    authHeader = `Basic ${Buffer.from(authString).toString("base64")}`;
+  }
+
   axios
     .post(instrumentationEndpoint, event, {
       headers: {
         "Content-Type": "application/json",
-        Authorization: `Basic ${Buffer.from(
-          `${config.browserstackUsername}:${config.browserstackAccessKey}`,
-        ).toString("base64")}`,
+        ...(authHeader ? { Authorization: authHeader } : {}),
       },
       timeout: 2000,
     })

src/lib/local.ts

@@ -74,6 +74,8 @@ export async function killExistingBrowserStackLocalProcesses() {
 }
 
 export async function ensureLocalBinarySetup(
+  username: string,
+  password: string,
   localIdentifier?: string,
 ): Promise<void> {
   logger.info(
@@ -104,8 +106,8 @@ export async function ensureLocalBinarySetup(
   // Use a single options object from config and extend with required fields
   const bsLocalArgs: Record<string, any> = {
     ...(config.browserstackLocalOptions || {}),
-    key: config.browserstackAccessKey,
-    username: config.browserstackUsername,
+    key: password,
+    username,
   };
 
   if (localIdentifier) {

src/lib/types.ts

@@ -0,0 +1,4 @@
+export type BrowserStackConfig = {
+  "browserstack-username": string;
+  "browserstack-access-key": string;
+};

src/lib/utils.ts

@@ -1,4 +1,5 @@
 import sharp from "sharp";
+import type { ApiResponse } from "./apiClient.js";
 
 export function sanitizeUrlParam(param: string): string {
   // Remove any characters that could be used for command injection
@@ -24,7 +25,10 @@ export async function maybeCompressBase64(base64: string): Promise<string> {
   return compressedBuffer.toString("base64");
 }
 
-export async function assertOkResponse(response: Response, action: string) {
+export async function assertOkResponse(
+  response: Response | ApiResponse,
+  action: string,
+) {
   if (!response.ok) {
     if (response.status === 404) {
       throw new Error(`Invalid session ID for ${action}`);