@midscene/shared 1.9.8-beta-20260618014851.0 → 1.9.8

package/src/mcp/base-server.ts

@@ -0,0 +1,529 @@
+import { randomUUID } from 'node:crypto';
+import type { ParseArgsConfig } from 'node:util';
+import { setIsMcp } from '@midscene/shared/utils';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import express, {
+  type Application,
+  type Request,
+  type Response,
+} from 'express';
+import { getErrorMessage } from './error-formatter';
+import {
+  TOOL_BEHAVIOR_FLAGS,
+  type ToolDefaults,
+  mergeToolDefaults,
+  resolveToolDefaults,
+} from './tool-defaults';
+import type { IMidsceneTools } from './types';
+
+export interface BaseMCPServerConfig {
+  name: string;
+  version: string;
+  description: string;
+}
+
+export interface HttpLaunchOptions {
+  port: number;
+  host?: string;
+}
+
+export interface LaunchMCPServerResult {
+  /**
+   * The MCP server port (for HTTP mode)
+   */
+  port?: number;
+
+  /**
+   * The server host (for HTTP mode)
+   */
+  host?: string;
+
+  /**
+   * Function to gracefully shutdown the MCP server
+   */
+  close: () => Promise<void>;
+}
+
+interface SessionData {
+  transport: StreamableHTTPServerTransport;
+  createdAt: Date;
+  lastAccessedAt: Date;
+}
+
+/**
+ * CLI argument configuration for MCP servers. Behavior flags (e.g.
+ * `--deep-locate`) are generated from {@link TOOL_BEHAVIOR_FLAGS}, so adding a
+ * new flag there exposes it here automatically.
+ */
+export const CLI_ARGS_CONFIG: ParseArgsConfig['options'] = {
+  mode: { type: 'string', default: 'stdio' },
+  port: { type: 'string', default: '3000' },
+  host: { type: 'string', default: 'localhost' },
+  ...Object.fromEntries(
+    TOOL_BEHAVIOR_FLAGS.map((flag) => [flag.cli, { type: 'boolean' as const }]),
+  ),
+};
+
+export interface CLIArgs {
+  mode?: string;
+  port?: string;
+  host?: string;
+  /** Behavior flags such as `deep-locate` / `deep-think` (see TOOL_BEHAVIOR_FLAGS). */
+  [flag: string]: string | boolean | undefined;
+}
+
+/**
+ * Launch an MCP server based on CLI arguments
+ * Shared helper to reduce duplication across platform CLI entry points
+ */
+export function launchMCPServer(
+  server: BaseMCPServer,
+  args: CLIArgs,
+): Promise<LaunchMCPServerResult> {
+  server.setToolDefaults(resolveToolDefaults((cli) => args[cli] === true));
+  if (args.mode === 'http') {
+    return server.launchHttp({
+      port: Number.parseInt(args.port || '3000', 10),
+      host: args.host || 'localhost',
+    });
+  }
+  return server.launch();
+}
+
+const SESSION_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+const CLEANUP_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+const MAX_SESSIONS = 100; // Maximum concurrent sessions to prevent DoS
+
+/**
+ * Base MCP Server class with programmatic launch() API
+ * Each platform extends this to provide their own tools manager
+ */
+export abstract class BaseMCPServer {
+  protected mcpServer: McpServer;
+  protected toolsManager?: IMidsceneTools;
+  protected config: BaseMCPServerConfig;
+  protected providedToolsManager?: IMidsceneTools;
+  protected toolDefaults: ToolDefaults = {};
+
+  constructor(config: BaseMCPServerConfig, toolsManager?: IMidsceneTools) {
+    this.config = config;
+    this.mcpServer = new McpServer({
+      name: config.name,
+      version: config.version,
+      description: config.description,
+    });
+    this.providedToolsManager = toolsManager;
+  }
+
+  /**
+   * Set the default options injected into generated tool calls (e.g. forced
+   * deep locate / deep think). Must be called before `launch()` /
+   * `launchHttp()` so they are applied to the tools manager before its tools
+   * are generated. Merges with any previously set defaults.
+   */
+  public setToolDefaults(toolDefaults: ToolDefaults): void {
+    this.toolDefaults = mergeToolDefaults(this.toolDefaults, toolDefaults);
+  }
+
+  /**
+   * Platform-specific: create tools manager instance
+   * This is only called if no tools manager was provided in constructor
+   */
+  protected abstract createToolsManager(): IMidsceneTools;
+
+  /**
+   * Initialize tools manager and attach to MCP server
+   */
+  private async initializeToolsManager(): Promise<void> {
+    setIsMcp(true);
+
+    // Use provided tools manager if available, otherwise create new one
+    this.toolsManager = this.providedToolsManager || this.createToolsManager();
+
+    // Apply the tool defaults before tools are generated so they are baked
+    // into the generated tool handlers.
+    this.toolsManager.setToolDefaults?.(this.toolDefaults);
+
+    try {
+      await this.toolsManager.initTools();
+    } catch (error: unknown) {
+      const message = getErrorMessage(error);
+      console.error(`Failed to initialize tools: ${message}`);
+      console.error('Tools will be initialized on first use');
+    }
+
+    this.toolsManager.attachToServer(this.mcpServer);
+  }
+
+  /**
+   * Perform cleanup on shutdown
+   */
+  private async performCleanup(): Promise<void> {
+    console.error(`${this.config.name} closing...`);
+    this.mcpServer.close();
+    await this.toolsManager?.destroy?.().catch(console.error);
+  }
+
+  /**
+   * Initialize and launch the MCP server with stdio transport
+   */
+  public async launch(): Promise<LaunchMCPServerResult> {
+    // Hijack stdout-based console methods to stderr for stdio mode
+    // This prevents them from breaking MCP JSON-RPC protocol on stdout
+    // Note: console.warn and console.error already output to stderr
+    console.log = (...args: unknown[]) => {
+      console.error('[LOG]', ...args);
+    };
+    console.info = (...args: unknown[]) => {
+      console.error('[INFO]', ...args);
+    };
+    console.debug = (...args: unknown[]) => {
+      console.error('[DEBUG]', ...args);
+    };
+
+    await this.initializeToolsManager();
+
+    const transport = new StdioServerTransport();
+
+    try {
+      await this.mcpServer.connect(transport);
+    } catch (error: unknown) {
+      const message = getErrorMessage(error);
+      console.error(`Failed to connect MCP stdio transport: ${message}`);
+      throw new Error(`Failed to initialize MCP stdio transport: ${message}`);
+    }
+
+    // Setup signal handlers for graceful shutdown
+    let isShuttingDown = false;
+    const cleanup = () => {
+      if (isShuttingDown) return;
+      isShuttingDown = true;
+      console.error(`${this.config.name} shutting down...`);
+      this.performCleanup().finally(() => process.exit(0));
+    };
+
+    // Setup process-level error handlers to prevent crashes
+    process.on('uncaughtException', (error: Error & { code?: string }) => {
+      // Exit on pipe errors — parent process is gone
+      if (error.code === 'EPIPE' || error.code === 'ERR_STREAM_DESTROYED') {
+        cleanup();
+        return;
+      }
+      console.error(`[${this.config.name}] Uncaught Exception:`, error);
+      console.error('Stack:', error.stack);
+    });
+
+    process.on('unhandledRejection', (reason: unknown) => {
+      console.error(`[${this.config.name}] Unhandled Rejection:`, reason);
+      if (reason instanceof Error) {
+        console.error('Stack:', reason.stack);
+      }
+    });
+
+    // Exit when stdin closes (parent process gone) or reaches EOF
+    process.stdin.on('close', cleanup);
+    process.stdin.on('end', cleanup);
+
+    // Exit when stdout/stderr pipe breaks (parent process gone)
+    process.stdout.on('error', cleanup);
+
+    process.once('SIGINT', cleanup);
+    process.once('SIGTERM', cleanup);
+    process.once('SIGHUP', cleanup);
+
+    return {
+      close: async () => {
+        this.performCleanup();
+      },
+    };
+  }
+
+  /**
+   * Launch MCP server with HTTP transport
+   * Supports stateful sessions for web applications and service integration
+   */
+  public async launchHttp(
+    options: HttpLaunchOptions,
+  ): Promise<LaunchMCPServerResult> {
+    // Validate port number
+    if (
+      !Number.isInteger(options.port) ||
+      options.port < 1 ||
+      options.port > 65535
+    ) {
+      throw new Error(
+        `Invalid port number: ${options.port}. Port must be between 1 and 65535.`,
+      );
+    }
+
+    await this.initializeToolsManager();
+
+    const app: Application = express();
+
+    // Add JSON body parser with size limit
+    app.use(express.json({ limit: '10mb' }));
+
+    const sessions = new Map<string, SessionData>();
+
+    app.all('/mcp', async (req: Request, res: Response) => {
+      const startTime = Date.now();
+      const requestId = randomUUID().substring(0, 8);
+
+      try {
+        const rawSessionId = req.headers['mcp-session-id'];
+        const sessionId = Array.isArray(rawSessionId)
+          ? rawSessionId[0]
+          : rawSessionId;
+        let session = sessionId ? sessions.get(sessionId) : undefined;
+
+        if (!session && req.method === 'POST') {
+          // Check session limit to prevent DoS
+          if (sessions.size >= MAX_SESSIONS) {
+            console.error(
+              `[${new Date().toISOString()}] [${requestId}] Session limit reached: ${sessions.size}/${MAX_SESSIONS}`,
+            );
+            res.status(503).json({
+              error: 'Too many active sessions',
+              message: 'Server is at maximum capacity. Please try again later.',
+            });
+            return;
+          }
+          session = await this.createHttpSession(sessions);
+          console.log(
+            `[${new Date().toISOString()}] [${requestId}] New session created: ${session.transport.sessionId}`,
+          );
+        }
+
+        if (session) {
+          session.lastAccessedAt = new Date();
+          await session.transport.handleRequest(req, res, req.body);
+          const duration = Date.now() - startTime;
+          console.log(
+            `[${new Date().toISOString()}] [${requestId}] Request completed in ${duration}ms`,
+          );
+        } else {
+          console.error(
+            `[${new Date().toISOString()}] [${requestId}] Invalid session or GET without session`,
+          );
+          res
+            .status(400)
+            .json({ error: 'Invalid session or GET without session' });
+        }
+      } catch (error: unknown) {
+        const message = getErrorMessage(error);
+        const duration = Date.now() - startTime;
+        console.error(
+          `[${new Date().toISOString()}] [${requestId}] MCP request error after ${duration}ms: ${message}`,
+        );
+        if (!res.headersSent) {
+          res.status(500).json({
+            error: 'Internal server error',
+            message: 'Failed to process MCP request',
+          });
+        }
+      }
+    });
+
+    const host = options.host || 'localhost';
+
+    // Create server with error handling
+    const server = app
+      .listen(options.port, host, () => {
+        console.log(
+          `${this.config.name} HTTP server listening on http://${host}:${options.port}/mcp`,
+        );
+      })
+      .on('error', (error: NodeJS.ErrnoException) => {
+        if (error.code === 'EADDRINUSE') {
+          console.error(
+            `ERROR: Port ${options.port} is already in use.\nPlease try a different port: --port=<number>\nExample: --mode=http --port=${options.port + 1}`,
+          );
+        } else if (error.code === 'EACCES') {
+          console.error(
+            `ERROR: Permission denied to bind to port ${options.port}.\nPorts below 1024 require root/admin privileges.\nPlease use a port above 1024 or run with elevated privileges.`,
+          );
+        } else {
+          console.error(
+            `ERROR: Failed to start HTTP server on ${host}:${options.port}\n` +
+              `Reason: ${error.message}\n` +
+              `Code: ${error.code || 'unknown'}`,
+          );
+        }
+        process.exit(1);
+      });
+
+    const cleanupInterval = this.startSessionCleanup(sessions);
+    this.setupHttpShutdownHandlers(server, sessions, cleanupInterval);
+
+    return {
+      port: options.port,
+      host,
+      close: async () => {
+        clearInterval(cleanupInterval);
+        for (const session of sessions.values()) {
+          try {
+            await session.transport.close();
+          } catch (error: unknown) {
+            const message = getErrorMessage(error);
+            console.error(
+              `Failed to close session ${session.transport.sessionId}: ${message}`,
+            );
+          }
+        }
+        sessions.clear();
+
+        return new Promise<void>((resolve) => {
+          server.close(async (err) => {
+            if (err) {
+              console.error('Error closing HTTP server:', err);
+            }
+            await this.performCleanup();
+            resolve();
+          });
+        });
+      },
+    };
+  }
+
+  /**
+   * Create a new HTTP session with transport
+   */
+  private async createHttpSession(
+    sessions: Map<string, SessionData>,
+  ): Promise<SessionData> {
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: () => randomUUID(),
+      onsessioninitialized: (sid: string) => {
+        sessions.set(sid, {
+          transport,
+          createdAt: new Date(),
+          lastAccessedAt: new Date(),
+        });
+        console.log(
+          `[${new Date().toISOString()}] Session ${sid} initialized (total: ${sessions.size})`,
+        );
+      },
+    });
+
+    transport.onclose = () => {
+      if (transport.sessionId) {
+        sessions.delete(transport.sessionId);
+        console.log(
+          `[${new Date().toISOString()}] Session ${transport.sessionId} closed (remaining: ${sessions.size})`,
+        );
+      }
+    };
+
+    try {
+      await this.mcpServer.connect(transport);
+    } catch (error: unknown) {
+      const message = getErrorMessage(error);
+      console.error(
+        `[${new Date().toISOString()}] Failed to connect MCP transport: ${message}`,
+      );
+      // Clean up the failed transport
+      if (transport.sessionId) {
+        sessions.delete(transport.sessionId);
+      }
+      throw new Error(`Failed to initialize MCP session: ${message}`);
+    }
+
+    return {
+      transport,
+      createdAt: new Date(),
+      lastAccessedAt: new Date(),
+    };
+  }
+
+  /**
+   * Start periodic session cleanup for inactive sessions
+   */
+  private startSessionCleanup(
+    sessions: Map<string, SessionData>,
+  ): ReturnType<typeof setInterval> {
+    return setInterval(() => {
+      const now = Date.now();
+      for (const [sid, session] of sessions) {
+        if (now - session.lastAccessedAt.getTime() > SESSION_TIMEOUT_MS) {
+          try {
+            session.transport.close();
+            sessions.delete(sid);
+            console.log(
+              `[${new Date().toISOString()}] Session ${sid} cleaned up due to inactivity (remaining: ${sessions.size})`,
+            );
+          } catch (error: unknown) {
+            const message = getErrorMessage(error);
+            console.error(
+              `[${new Date().toISOString()}] Failed to close session ${sid} during cleanup: ${message}`,
+            );
+            // Still delete from map to prevent retry loops
+            sessions.delete(sid);
+          }
+        }
+      }
+    }, CLEANUP_INTERVAL_MS);
+  }
+
+  /**
+   * Setup shutdown handlers for HTTP server
+   */
+  private setupHttpShutdownHandlers(
+    server: ReturnType<Application['listen']>,
+    sessions: Map<string, SessionData>,
+    cleanupInterval: ReturnType<typeof setInterval>,
+  ): void {
+    const cleanup = () => {
+      console.error(`${this.config.name} shutting down...`);
+      clearInterval(cleanupInterval);
+
+      // Close all sessions with error handling
+      for (const session of sessions.values()) {
+        try {
+          session.transport.close();
+        } catch (error: unknown) {
+          const message = getErrorMessage(error);
+          console.error(`Error closing session during shutdown: ${message}`);
+        }
+      }
+      sessions.clear();
+
+      // Close HTTP server gracefully
+      try {
+        server.close(() => {
+          // Server closed callback - all connections finished
+          this.performCleanup().finally(() => process.exit(0));
+        });
+
+        // Set a timeout in case server.close() hangs
+        setTimeout(() => {
+          console.error('Forcefully shutting down after timeout');
+          this.performCleanup().finally(() => process.exit(1));
+        }, 5000);
+      } catch (error: unknown) {
+        const message = getErrorMessage(error);
+        console.error(`Error closing HTTP server: ${message}`);
+        this.performCleanup().finally(() => process.exit(1));
+      }
+    };
+
+    // Use once() to prevent multiple registrations
+    process.once('SIGINT', cleanup);
+    process.once('SIGTERM', cleanup);
+  }
+
+  /**
+   * Get the underlying MCP server instance
+   */
+  public getServer(): McpServer {
+    return this.mcpServer;
+  }
+
+  /**
+   * Get the tools manager instance
+   */
+  public getToolsManager(): IMidsceneTools | undefined {
+    return this.toolsManager;
+  }
+}

package/src/{agent-tools → mcp}/base-tools.ts

@@ -1,5 +1,6 @@
 import { parseBase64 } from '@midscene/shared/img';
 import { getDebug } from '@midscene/shared/logger';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { z } from 'zod';
 import { camelToKebab, getKeyAliases } from '../key-alias-utils';
 import {
@@ -28,7 +29,7 @@ import type {
   ToolSchema,
 } from './types';
 
-const debug = getDebug('agent-tools:base-tools');
+const debug = getDebug('mcp:base-tools');
 
 /**
  * Declarative description of a platform's agent init args.
@@ -38,11 +39,11 @@ const debug = getDebug('agent-tools:base-tools');
 export interface InitArgSpec<TInitParam> {
   /** Arg namespace, e.g. `android`, `ios`. */
   namespace: string;
-  /** Zod shape describing the init args. Field names drive the tool schema. */
+  /** Zod shape describing the init args. Field names drive the MCP schema. */
   shape: Record<string, z.ZodTypeAny>;
   /**
    * Optional CLI presentation hints. These affect `--help` output for
-   * single-platform CLIs but do not alter YAML protocol keys.
+   * single-platform CLIs but do not alter MCP/YAML protocol keys.
    */
   cli?: {
     /** Prefer bare `--device-id`-style options in platform CLI help output. */
@@ -60,7 +61,7 @@ export interface InitArgSpec<TInitParam> {
 }
 
 /**
- * Base class for platform-specific Midscene tools.
+ * Base class for platform-specific MCP tools.
  * @typeParam TAgent - Platform-specific agent type.
  * @typeParam TInitParam - Platform-specific init parameter consumed by
  *   `ensureAgent`. Defaults to `undefined` for platforms that take no args.
@@ -70,19 +71,20 @@ export abstract class BaseMidsceneTools<
   TInitParam = unknown,
 > implements IMidsceneTools
 {
+  protected mcpServer?: McpServer;
   protected agent?: TAgent;
   protected toolDefinitions: ToolDefinition[] = [];
 
   /**
    * Default options injected into every generated tool call (e.g. forced deep
-   * locate / deep think). Set from startup/CLI behavior flags before
+   * locate / deep think). Set from server/CLI behavior flags before
    * `initTools()` so they are baked into the generated tool handlers.
    * See https://github.com/web-infra-dev/midscene/issues/2446.
    */
   protected toolDefaults: ToolDefaults = {};
 
   /**
-   * Declarative init-arg spec. Subclasses that accept CLI init args should
+   * Declarative init-arg spec. Subclasses that accept CLI/MCP init args should
    * set this once and get `extractAgentInitParam` / `sanitizeToolArgs` /
    * `getAgentInitArgSchema` auto-implemented.
    *
@@ -106,7 +108,7 @@ export abstract class BaseMidsceneTools<
   }
 
   /**
-   * Extract a platform-specific agent init parameter from CLI tool args.
+   * Extract a platform-specific agent init parameter from CLI/MCP tool args.
    */
   protected extractAgentInitParam(
     args: Record<string, unknown>,
@@ -159,7 +161,7 @@ export abstract class BaseMidsceneTools<
    * show ergonomic bare flags while the underlying schema stays namespaced.
    * When `preferBareKeys` is enabled, single-platform CLIs only accept the
    * bare spellings; namespaced dotted spellings remain available through the
-   * YAML schema instead of the platform CLI surface.
+   * MCP/YAML schema instead of the platform CLI surface.
    */
   protected getAgentInitArgCliMetadata(): ToolCliMetadata | undefined {
     if (!this.initArgSpec?.cli) {
@@ -270,6 +272,7 @@ export abstract class BaseMidsceneTools<
     this.toolDefinitions.push(...platformTools);
 
     // 2. Get action space: use pre-set agent if available, otherwise temp device.
+    //    When called via mcpKitForAgent(), agent is set before initTools().
     //    For CLI usage, agent is deferred to the first real command.
     let actionSpace: ActionSpaceItem[];
     if (this.agent) {
@@ -310,6 +313,28 @@ export abstract class BaseMidsceneTools<
     debug('Total tools prepared:', this.toolDefinitions.length);
   }
 
+  /**
+   * Attach to MCP server and register all tools
+   */
+  public attachToServer(server: McpServer): void {
+    this.mcpServer = server;
+
+    if (this.toolDefinitions.length === 0) {
+      debug('Warning: No tools to register. Tools may be initialized lazily.');
+    }
+
+    for (const toolDef of this.toolDefinitions) {
+      this.mcpServer.tool(
+        toolDef.name,
+        toolDef.description,
+        toolDef.schema,
+        toolDef.handler,
+      );
+    }
+
+    debug('Registered', this.toolDefinitions.length, 'tools');
+  }
+
   /**
    * Cleanup method - destroy agent and release resources
    */

package/src/{agent-tools → mcp}/chrome-path.ts

@@ -1,13 +1,5 @@
 import { existsSync } from 'node:fs';
-import {
-  MIDSCENE_CHROME_PATH,
-  MIDSCENE_MCP_CHROME_PATH,
-  globalConfigManager,
-} from '../env';
-import { getDebug } from '../logger';
-
-const warnChromePath = getDebug('agent-tools:chrome-path', { console: true });
-let hasWarnedLegacyChromePath = false;
+import { MIDSCENE_MCP_CHROME_PATH, globalConfigManager } from '../env';
 
 export function getSystemChromePath(): string | undefined {
   const platform = process.platform;
@@ -41,18 +33,9 @@ export function getSystemChromePath(): string | undefined {
 }
 
 export function resolveChromePath(): string {
-  const primaryEnvPath =
-    globalConfigManager.getEnvConfigValue(MIDSCENE_CHROME_PATH);
-  const legacyEnvPath = globalConfigManager.getEnvConfigValue(
+  const envPath = globalConfigManager.getEnvConfigValue(
     MIDSCENE_MCP_CHROME_PATH,
   );
-  const envPath = primaryEnvPath || legacyEnvPath;
-  if (!primaryEnvPath && legacyEnvPath && !hasWarnedLegacyChromePath) {
-    warnChromePath(
-      'MIDSCENE_MCP_CHROME_PATH is deprecated. Use MIDSCENE_CHROME_PATH instead.',
-    );
-    hasWarnedLegacyChromePath = true;
-  }
   if (envPath && envPath !== 'auto' && existsSync(envPath)) {
     return envPath;
   }
@@ -60,6 +43,6 @@ export function resolveChromePath(): string {
   if (systemPath) return systemPath;
 
   throw new Error(
-    'Chrome not found. Install Google Chrome or set MIDSCENE_CHROME_PATH environment variable.',
+    'Chrome not found. Install Google Chrome or set MIDSCENE_MCP_CHROME_PATH environment variable.',
   );
 }

package/src/{agent-tools → mcp}/index.ts

@@ -1,3 +1,4 @@
+export * from './base-server';
 export * from './base-tools';
 export * from './tool-defaults';
 export * from './agent-behavior-init-args';
@@ -5,4 +6,6 @@ export * from './init-arg-utils';
 export * from './error-formatter';
 export * from './tool-generator';
 export * from './types';
+export * from './inject-report-html-plugin';
+export * from './launcher-helper';
 export * from './chrome-path';