@xiuchang-midscene/shared 2.0.2

package/src/mcp/chrome-path.ts

@@ -0,0 +1,48 @@
+import { existsSync } from 'node:fs';
+import { MIDSCENE_MCP_CHROME_PATH, globalConfigManager } from '../env';
+
+export function getSystemChromePath(): string | undefined {
+  const platform = process.platform;
+
+  const chromePaths: Record<string, string[]> = {
+    darwin: [
+      '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+      '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    ],
+    win32: [
+      'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+      'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+      `C:\\Users\\${process.env.USERNAME ?? process.env.USER}\\AppData\\Local\\Google\\Chrome\\Application\\chrome.exe`,
+    ],
+    linux: [
+      // Prefer actual binaries over wrapper scripts.
+      // Wrappers in /usr/bin may strip --user-data-dir, causing
+      // "DevTools remote debugging requires a non-default data directory" errors.
+      '/opt/google/chrome/chrome',
+      '/opt/google/chrome/google-chrome',
+      '/usr/bin/google-chrome-stable',
+      '/usr/bin/google-chrome',
+      '/usr/bin/chromium-browser',
+      '/usr/bin/chromium',
+      '/snap/bin/chromium',
+    ],
+  };
+
+  const paths = chromePaths[platform] ?? [];
+  return paths.find((p) => existsSync(p));
+}
+
+export function resolveChromePath(): string {
+  const envPath = globalConfigManager.getEnvConfigValue(
+    MIDSCENE_MCP_CHROME_PATH,
+  );
+  if (envPath && envPath !== 'auto' && existsSync(envPath)) {
+    return envPath;
+  }
+  const systemPath = getSystemChromePath();
+  if (systemPath) return systemPath;
+
+  throw new Error(
+    'Chrome not found. Install Google Chrome or set MIDSCENE_MCP_CHROME_PATH environment variable.',
+  );
+}

package/src/mcp/index.ts

@@ -0,0 +1,7 @@
+export * from './base-server';
+export * from './base-tools';
+export * from './tool-generator';
+export * from './types';
+export * from './inject-report-html-plugin';
+export * from './launcher-helper';
+export * from './chrome-path';

package/src/mcp/inject-report-html-plugin.ts

@@ -0,0 +1,119 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const MAGIC_STRING = 'REPLACE_ME_WITH_REPORT_HTML';
+const REPLACED_MARK = '/*REPORT_HTML_REPLACED*/';
+const REG_EXP_FOR_REPLACE = /\/\*REPORT_HTML_REPLACED\*\/.*/;
+
+interface RslibPluginApi {
+  onAfterBuild: (callback: () => void) => void;
+}
+
+/**
+ * Rslib plugin to inject report HTML from @midscene/core dist into MCP bundle.
+ * This runs after build and reads the already-injected HTML from core.
+ *
+ * Prerequisites:
+ * - @midscene/report must be in devDependencies to ensure correct build order
+ * - @midscene/core dist must exist with injected HTML
+ *
+ * @param packageDir - The directory of the MCP package (use __dirname)
+ */
+export function injectReportHtmlFromCore(packageDir: string) {
+  return {
+    name: 'inject-report-html-from-core',
+    setup(api: RslibPluginApi) {
+      api.onAfterBuild(() => {
+        const coreUtilsPath = path.resolve(
+          packageDir,
+          '..',
+          'core',
+          'dist',
+          'lib',
+          'utils.js',
+        );
+
+        if (!fs.existsSync(coreUtilsPath)) {
+          console.warn(
+            '[inject-report-html] @midscene/core dist not found, skipping',
+          );
+          return;
+        }
+
+        const coreContent = fs.readFileSync(coreUtilsPath, 'utf-8');
+        if (!coreContent.includes(REPLACED_MARK)) {
+          console.warn(
+            '[inject-report-html] HTML not found in core dist. Ensure report builds first.',
+          );
+          return;
+        }
+
+        // Extract the JSON string after the marker
+        // JSON strings can contain escaped quotes, so we need to properly parse it
+        const markerIndex = coreContent.indexOf(REPLACED_MARK);
+        const jsonStart = markerIndex + REPLACED_MARK.length;
+
+        // Find the end of the JSON string by tracking quote escaping
+        let jsonEnd = jsonStart;
+        if (coreContent[jsonStart] === '"') {
+          jsonEnd = jsonStart + 1;
+          while (jsonEnd < coreContent.length) {
+            if (coreContent[jsonEnd] === '\\') {
+              jsonEnd += 2; // Skip escaped character
+            } else if (coreContent[jsonEnd] === '"') {
+              jsonEnd += 1; // Include closing quote
+              break;
+            } else {
+              jsonEnd += 1;
+            }
+          }
+        }
+
+        const jsonString = coreContent.slice(jsonStart, jsonEnd);
+        if (!jsonString || jsonString.length < 10) {
+          console.warn('[inject-report-html] Failed to extract HTML from core');
+          return;
+        }
+
+        const finalContent = `${REPLACED_MARK}${jsonString}`;
+        const distDir = path.join(packageDir, 'dist');
+
+        if (!fs.existsSync(distDir)) return;
+
+        const jsFiles = fs
+          .readdirSync(distDir)
+          .filter((f) => f.endsWith('.js'));
+        let injectedCount = 0;
+
+        for (const file of jsFiles) {
+          const filePath = path.join(distDir, file);
+          const content = fs.readFileSync(filePath, 'utf-8');
+
+          if (content.includes(REPLACED_MARK)) {
+            if (REG_EXP_FOR_REPLACE.test(content)) {
+              fs.writeFileSync(
+                filePath,
+                content.replace(REG_EXP_FOR_REPLACE, () => finalContent),
+              );
+              console.log(`[inject-report-html] Updated: ${file}`);
+              injectedCount++;
+            }
+          } else if (content.includes(`'${MAGIC_STRING}'`)) {
+            fs.writeFileSync(
+              filePath,
+              content.replace(`'${MAGIC_STRING}'`, () => finalContent),
+            );
+            console.log(`[inject-report-html] Injected: ${file}`);
+            injectedCount++;
+          }
+        }
+
+        if (injectedCount > 0) {
+          console.log(
+            `[inject-report-html] Completed: ${injectedCount} file(s)`,
+          );
+        }
+      });
+    },
+  };
+}

package/src/mcp/launcher-helper.ts

@@ -0,0 +1,200 @@
+import type { BaseMCPServer } from './base-server';
+import type { HttpLaunchOptions, LaunchMCPServerResult } from './base-server';
+import type { IMidsceneTools } from './types';
+
+export interface LaunchMCPServerOptions extends HttpLaunchOptions {
+  /**
+   * Whether to show server logs
+   * @default true
+   */
+  verbose?: boolean;
+}
+
+/**
+ * Generic agent type (avoid importing from @midscene/core to prevent circular deps)
+ */
+export interface GenericAgent<TDevice = any> {
+  interface: TDevice;
+  constructor: { name: string };
+}
+
+/**
+ * Additional information for logging server startup
+ */
+export interface StartupInfo {
+  port?: number;
+  host?: string;
+}
+
+export interface MCPServerLauncherConfig<
+  AgentType extends GenericAgent = GenericAgent,
+  ToolsManagerType extends IMidsceneTools = IMidsceneTools,
+> {
+  agent: AgentType;
+  platformName: string;
+  ToolsManagerClass: new (...args: any[]) => ToolsManagerType;
+  MCPServerClass: new (toolsManager?: ToolsManagerType) => BaseMCPServer;
+}
+
+/**
+ * Create a generic MCP server launcher for a given agent, tools manager, and MCP server.
+ *
+ * This helper centralizes the common wiring logic used by platform-specific launchers:
+ * it constructs a tools manager, attaches the provided `agent` to it, then instantiates
+ * the `MCPServerClass` and exposes convenience methods to start the server over stdio
+ * (`launch`) or HTTP (`launchHttp`).
+ *
+ * Use this helper when adding a new platform-specific launcher or when you want to
+ * avoid duplicating boilerplate code for starting an MCP server. Typically, callers
+ * provide:
+ * - an `agent` instance that contains the underlying device on its `interface` property
+ * - a `ToolsManagerClass` that knows how to expose tools for that agent
+ * - an `MCPServerClass` that implements the MCP protocol and supports `launch` and
+ *   `launchHttp` methods.
+ *
+ * The returned object has two methods:
+ * - `launch(options?)` to start the server using stdio transport
+ * - `launchHttp(options)` to start the server using HTTP transport
+ * Both methods accept a `verbose` flag to control console logging.
+ *
+ * @param config Configuration describing the agent, platform name (for logging),
+ *               tools manager implementation, and MCP server implementation.
+ *
+ * @returns An object with `launch` and `launchHttp` methods to start the MCP server.
+ *
+ * @example
+ * ```typescript
+ * import { createMCPServerLauncher } from '@midscene/shared/mcp';
+ * import { Agent } from '@midscene/core/agent';
+ * import { WebMidsceneTools } from './web-tools';
+ * import { WebMCPServer } from './server';
+ *
+ * const agent = new Agent();
+ * const launcher = createMCPServerLauncher({
+ *   agent,
+ *   platformName: 'Web',
+ *   ToolsManagerClass: WebMidsceneTools,
+ *   MCPServerClass: WebMCPServer,
+ * });
+ *
+ * // Start with stdio
+ * await launcher.launch({ verbose: true });
+ *
+ * // Or start with HTTP
+ * await launcher.launchHttp({ port: 3000, host: 'localhost' });
+ * ```
+ *
+ * @internal
+ */
+export function createMCPServerLauncher<
+  AgentType extends GenericAgent,
+  ToolsManagerType extends IMidsceneTools,
+>(config: MCPServerLauncherConfig<AgentType, ToolsManagerType>) {
+  const { agent, platformName, ToolsManagerClass, MCPServerClass } = config;
+
+  /**
+   * Validate that the agent has the required interface property
+   * @throws {Error} If agent.interface is missing
+   */
+  function validateAgent(): void {
+    const device = agent.interface;
+    if (!device) {
+      throw new Error(
+        `Agent must have an 'interface' property that references the underlying device.
+Please ensure your agent instance is properly initialized with a device interface.
+Expected: agent.interface to be defined, but got: ${typeof device}
+Solution: Check that your agent constructor properly sets the interface property.`,
+      );
+    }
+  }
+
+  /**
+   * Create and configure a tools manager with the agent
+   * @returns Configured tools manager instance
+   */
+  function createToolsManager(): ToolsManagerType {
+    const toolsManager = new ToolsManagerClass();
+    // Type-safe agent injection: define explicit interface for tools manager with agent
+    interface ToolsManagerWithAgent extends IMidsceneTools {
+      agent: AgentType;
+    }
+    (toolsManager as unknown as ToolsManagerWithAgent).agent = agent;
+    return toolsManager;
+  }
+
+  /**
+   * Log server startup information
+   * @param mode - Transport mode ('stdio' or 'HTTP')
+   * @param additionalInfo - Additional info to log (e.g., port, host)
+   */
+  function logStartupInfo(
+    mode: 'stdio' | 'HTTP',
+    additionalInfo?: StartupInfo,
+  ): void {
+    const device = agent.interface;
+    console.log(`Starting Midscene ${platformName} MCP Server (${mode})...`);
+    console.log(`Agent: ${agent.constructor.name}`);
+    console.log(`Device: ${device.constructor.name}`);
+
+    if (additionalInfo?.port !== undefined) {
+      console.log(`Port: ${additionalInfo.port}`);
+    }
+    if (additionalInfo?.host) {
+      console.log(`Host: ${additionalInfo.host}`);
+    }
+  }
+
+  return {
+    /**
+     * Launch the MCP server with stdio transport
+     */
+    async launch(
+      options: { verbose?: boolean } = {},
+    ): Promise<LaunchMCPServerResult> {
+      const { verbose = true } = options;
+
+      validateAgent();
+
+      if (verbose) {
+        logStartupInfo('stdio');
+      }
+
+      const toolsManager = createToolsManager();
+      const server = new MCPServerClass(toolsManager);
+      const result = await server.launch();
+
+      if (verbose) {
+        console.log(`${platformName} MCP Server started (stdio mode)`);
+      }
+
+      return result;
+    },
+
+    /**
+     * Launch the MCP server with HTTP transport
+     */
+    async launchHttp(
+      options: LaunchMCPServerOptions,
+    ): Promise<LaunchMCPServerResult> {
+      const { port, host = 'localhost', verbose = true } = options;
+
+      validateAgent();
+
+      if (verbose) {
+        logStartupInfo('HTTP', { port, host });
+      }
+
+      const toolsManager = createToolsManager();
+      const server = new MCPServerClass(toolsManager);
+      const result = await server.launchHttp({ port, host });
+
+      if (verbose) {
+        console.log(
+          `${platformName} MCP Server started on http://${result.host}:${result.port}/mcp`,
+        );
+      }
+
+      return result;
+    },
+  };
+}