@midscene/shared 1.9.8-beta-20260618014851.0 → 1.9.8

package/src/{agent-tools → mcp}/init-arg-utils.ts

@@ -88,11 +88,11 @@ export function sanitizeNamespacedArgs(
 }
 
 /**
- * Build a flat tool schema whose keys are dotted `"<namespace>.<field>"`.
+ * Build a flat MCP tool schema whose keys are dotted `"<namespace>.<field>"`.
  *
  * We intentionally stay flat (rather than `{ namespace: z.object({...}) }`) so
- * that CLI (`--android.device-id`) and `--help` output share the same spelling.
- * `readNamespacedArg` understands all three input shapes:
+ * that CLI (`--android.device-id`), MCP clients, and `--help` output all share
+ * the same spelling. `readNamespacedArg` understands all three input shapes:
  * nested namespace object, dotted flat key, and bare key fallback.
  */
 export function createNamespacedInitArgSchema(

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;
+    },
+  };
+}

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

@@ -1,10 +1,10 @@
 /**
  * Unified, declarative mechanism for "force a default option on every tool
- * call" behaviors exposed by device and Agent Skill CLIs.
+ * call" behaviors exposed by MCP servers and the device / Agent Skill CLIs.
  *
  * Adding a new behavior flag (e.g. `--deep-search`) is a one-line change to
  * {@link TOOL_BEHAVIOR_FLAGS}: declare which default-option "bag" it fills.
- * The tool generator, tools managers and CLI parsing are all generic
+ * The tool generator, servers, tools managers and CLI parsing are all generic
  * over {@link ToolDefaults} and never need to learn about individual flags.
  *
  * See https://github.com/web-infra-dev/midscene/issues/2446.
@@ -91,12 +91,13 @@ export function resolveToolDefaults(
  *
  * Behavior flags (e.g. `--deep-locate`) are global: they may appear anywhere
  * in argv and are not tied to a specific sub-command. They are recognized by
- * exact kebab-case match and removed so a strict per-command parser never sees them. Every other
+ * exact kebab-case match — the same surface the MCP `parseArgs` config exposes
+ * — and removed so a strict per-command parser never sees them. Every other
  * token is returned untouched and in order for that per-command parser.
  *
  * This is the single place that knows how a behavior flag looks on the command
- * line; the device / Agent Skill CLI resolves defaults from
- * {@link TOOL_BEHAVIOR_FLAGS} through here / {@link resolveToolDefaults}.
+ * line; both the device / Agent Skill CLI and the MCP launch path resolve their
+ * defaults from {@link TOOL_BEHAVIOR_FLAGS} through here / {@link resolveToolDefaults}.
  */
 export function stripBehaviorFlags(argv: readonly string[]): {
   rawArgs: string[];

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

@@ -21,10 +21,10 @@ import { composeUserPrompt, promptInputExtraSchema } from './user-prompt';
 export { composeUserPrompt };
 
 /**
- * Generate tool description from ActionSpaceItem.
+ * Generate MCP tool description from ActionSpaceItem
  * Format: "actionName action, description. Parameters: param1 (type) - desc; param2 (type) - desc"
  */
-function describeActionForTool(action: ActionSpaceItem): string {
+function describeActionForMCP(action: ActionSpaceItem): string {
   const actionDesc = action.description || `Execute ${action.name} action`;
 
   if (!action.paramSchema) {
@@ -166,7 +166,7 @@ function transformSchemaField(
 /**
  * Extract and transform schema from action's paramSchema.
  *
- * CLI tools expose parameters as named fields, so the only schema
+ * CLI and MCP both expose parameters as named fields, so the only schema
  * shapes we can surface are ZodObject (any number of fields) or undefined
  * (the action takes no parameters). A primitive schema like `z.string()`
  * silently degraded to leaking the ZodString instance's prototype methods
@@ -188,7 +188,7 @@ function extractActionSchema(
       (paramSchema as unknown as { _def?: { typeName?: string } })?._def
         ?.typeName ?? 'unknown';
     throw new Error(
-      `Action "${actionName}" declared a non-object paramSchema (${typeName}). CLI tool schemas must be a ZodObject (e.g. z.object({ uri: z.string() })) or undefined. Wrap primitive fields in an object schema.`,
+      `Action "${actionName}" declared a non-object paramSchema (${typeName}). CLI and MCP tool schemas must be a ZodObject (e.g. z.object({ uri: z.string() })) or undefined. Wrap primitive fields in an object schema.`,
     );
   }
 
@@ -543,7 +543,7 @@ function mergeToolCliMetadata(
 }
 
 /**
- * Converts DeviceAction from actionSpace into ToolDefinition.
+ * Converts DeviceAction from actionSpace into MCP ToolDefinition
  * This is the core logic that removes need for hardcoded tool definitions
  */
 export function generateToolsFromActionSpace(
@@ -564,7 +564,7 @@ export function generateToolsFromActionSpace(
 
     return {
       name: action.name,
-      description: describeActionForTool(action),
+      description: describeActionForMCP(action),
       schema,
       cli: initArgCliMetadata,
       handler: async (args: Record<string, unknown>) => {

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

@@ -1,3 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { z } from 'zod';
 import type { ToolDefaults } from './tool-defaults';
 
@@ -11,7 +12,7 @@ export const defaultAppLoadingTimeoutMs = 10000;
 export const defaultAppLoadingCheckIntervalMs = 2000;
 
 /**
- * Content item types for tool results.
+ * Content item types for tool results (MCP compatible)
  */
 export type ToolResultContent =
   | { type: 'text'; text: string }
@@ -25,7 +26,7 @@ export type ToolResultContent =
     };
 
 /**
- * Result type for tool execution.
+ * Result type for tool execution (MCP compatible)
  */
 export interface ToolResult {
   [x: string]: unknown;
@@ -57,7 +58,7 @@ export interface ToolCliMetadata {
 }
 
 /**
- * Tool definition for Midscene CLI and Skill surfaces.
+ * Tool definition for MCP server
  */
 export interface ToolDefinition<T = Record<string, unknown>> {
   name: string;
@@ -67,6 +68,9 @@ export interface ToolDefinition<T = Record<string, unknown>> {
   cli?: ToolCliMetadata;
 }
 
+/**
+ * Tool type for mcpKitForAgent return value
+ */
 export type Tool = ToolDefinition;
 
 /**
@@ -156,9 +160,10 @@ export interface BaseDevice {
 }
 
 /**
- * Interface for platform-specific tools manager.
+ * Interface for platform-specific MCP tools manager
  */
 export interface IMidsceneTools {
+  attachToServer(server: McpServer): void;
   initTools(): Promise<void>;
   destroy?(): Promise<void>;
   setToolDefaults?(toolDefaults: ToolDefaults): void;

package/src/utils.ts

@@ -64,8 +64,17 @@ export function assert(condition: any, message?: string): asserts condition {
   }
 }
 
+let isMcp = false;
+
+export function setIsMcp(value: boolean) {
+  isMcp = value;
+}
+
+//mcp need use obj format to console msg: https://github.com/modelcontextprotocol/typescript-sdk/issues/244
 export function logMsg(...message: Parameters<typeof console.log>) {
-  console.log(...message);
+  if (!isMcp) {
+    console.log(...message);
+  }
 }
 
 export async function repeat(