@midscene/shared 1.9.8-beta-20260618014851.0 → 1.9.8

package/dist/types/mcp/launcher-helper.d.ts

@@ -0,0 +1,94 @@
+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 declare function createMCPServerLauncher<AgentType extends GenericAgent, ToolsManagerType extends IMidsceneTools>(config: MCPServerLauncherConfig<AgentType, ToolsManagerType>): {
+    /**
+     * Launch the MCP server with stdio transport
+     */
+    launch(options?: {
+        verbose?: boolean;
+    }): Promise<LaunchMCPServerResult>;
+    /**
+     * Launch the MCP server with HTTP transport
+     */
+    launchHttp(options: LaunchMCPServerOptions): Promise<LaunchMCPServerResult>;
+};

package/dist/types/{agent-tools → mcp}/tool-defaults.d.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.
@@ -50,12 +50,13 @@ export declare function resolveToolDefaults(isEnabled: (cli: string) => boolean)
  *
  * 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 declare function stripBehaviorFlags(argv: readonly string[]): {
     rawArgs: string[];

package/dist/types/{agent-tools → mcp}/tool-generator.d.ts

@@ -3,7 +3,7 @@ import type { ActionSpaceItem, BaseAgent, ToolCliMetadata, ToolDefinition, ToolS
 import { composeUserPrompt } from './user-prompt';
 export { composeUserPrompt };
 /**
- * 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 declare function generateToolsFromActionSpace(actionSpace: ActionSpaceItem[], getAgent: (args?: Record<string, unknown>) => Promise<BaseAgent>, sanitizeArgs?: (args: Record<string, unknown>) => Record<string, unknown>, initArgSchema?: ToolSchema, initArgCliMetadata?: ToolCliMetadata, toolDefaults?: ToolDefaults): ToolDefinition[];

package/dist/types/{agent-tools → mcp}/types.d.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';
 /**
@@ -6,7 +7,7 @@ import type { ToolDefaults } from './tool-defaults';
 export declare const defaultAppLoadingTimeoutMs = 10000;
 export declare const defaultAppLoadingCheckIntervalMs = 2000;
 /**
- * Content item types for tool results.
+ * Content item types for tool results (MCP compatible)
  */
 export type ToolResultContent = {
     type: 'text';
@@ -32,7 +33,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 {
     options?: Record<string, ToolCliOption>;
 }
 /**
- * Tool definition for Midscene CLI and Skill surfaces.
+ * Tool definition for MCP server
  */
 export interface ToolDefinition<T = Record<string, unknown>> {
     name: string;
@@ -66,6 +67,9 @@ export interface ToolDefinition<T = Record<string, unknown>> {
     handler: ToolHandler<T>;
     cli?: ToolCliMetadata;
 }
+/**
+ * Tool type for mcpKitForAgent return value
+ */
 export type Tool = ToolDefinition;
 /**
  * Action space item definition
@@ -133,9 +137,10 @@ export interface BaseDevice {
     destroy?(): Promise<void>;
 }
 /**
- * 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/dist/types/utils.d.ts

@@ -11,6 +11,7 @@ export declare function generateHashId(rect: any, content?: string): string;
  * @throws Error with the provided message if the condition is false
  */
 export declare function assert(condition: any, message?: string): asserts condition;
+export declare function setIsMcp(value: boolean): void;
 export declare function logMsg(...message: Parameters<typeof console.log>): void;
 export declare function repeat(times: number, fn: (index: number) => Promise<void>): Promise<void>;
 export declare const escapeScriptTag: (html: string) => string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midscene/shared",
-  "version": "1.9.8-beta-20260618014851.0",
+  "version": "1.9.8",
   "repository": "https://github.com/web-infra-dev/midscene",
   "homepage": "https://midscenejs.com/",
   "types": "./dist/types/index.d.ts",
@@ -57,26 +57,16 @@
       "import": "./dist/es/common.mjs",
       "require": "./dist/lib/common.js"
     },
-    "./agent-tools": {
-      "types": "./dist/types/agent-tools/index.d.ts",
-      "import": "./dist/es/agent-tools/index.mjs",
-      "require": "./dist/lib/agent-tools/index.js"
-    },
-    "./agent-tools/*": {
-      "types": "./dist/types/agent-tools/*.d.ts",
-      "import": "./dist/es/agent-tools/*.mjs",
-      "require": "./dist/lib/agent-tools/*.js"
+    "./mcp": {
+      "types": "./dist/types/mcp/index.d.ts",
+      "import": "./dist/es/mcp/index.mjs",
+      "require": "./dist/lib/mcp/index.js"
     },
     "./cli": {
       "types": "./dist/types/cli/index.d.ts",
       "import": "./dist/es/cli/index.mjs",
       "require": "./dist/lib/cli/index.js"
     },
-    "./recorder": {
-      "types": "./dist/types/recorder.d.ts",
-      "import": "./dist/es/recorder.mjs",
-      "require": "./dist/lib/recorder.js"
-    },
     "./logger": {
       "types": "./dist/types/logger.d.ts",
       "import": "./dist/es/logger.mjs",
@@ -94,9 +84,11 @@
     "README.md"
   ],
   "dependencies": {
+    "@modelcontextprotocol/sdk": "1.10.2",
     "@silvia-odwyer/photon": "0.3.3",
     "@silvia-odwyer/photon-node": "0.3.3",
     "debug": "4.4.0",
+    "express": "^4.21.2",
     "js-sha256": "0.11.0",
     "sharp": "^0.34.3",
     "dotenv": "^16.4.5",
@@ -106,6 +98,7 @@
   "devDependencies": {
     "@rslib/core": "^0.18.3",
     "@types/debug": "4.1.12",
+    "@types/express": "^4.17.21",
     "@types/node": "^18.0.0",
     "@ui-tars/shared": "1.2.0",
     "openai": "6.3.0",

package/src/cli/cli-args.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
-import type { ToolCliOption, ToolDefinition } from '../agent-tools/types';
 import { getKeyAliases } from '../key-alias-utils';
+import type { ToolCliOption, ToolDefinition } from '../mcp/types';
 import { CLIError } from './cli-error';
 
 export function parseValue(raw: string): unknown {

package/src/cli/cli-runner.ts

@@ -2,14 +2,14 @@ import { existsSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import dotenv from 'dotenv';
-import type { BaseMidsceneTools } from '../agent-tools/base-tools';
-import { stripBehaviorFlags } from '../agent-tools/tool-defaults';
+import { getDebug } from '../logger';
+import type { BaseMidsceneTools } from '../mcp/base-tools';
+import { stripBehaviorFlags } from '../mcp/tool-defaults';
 import type {
   ToolDefinition,
   ToolResult,
   ToolResultContent,
-} from '../agent-tools/types';
-import { getDebug } from '../logger';
+} from '../mcp/types';
 import {
   canonicalizeCliArgKeys,
   formatCliValidationError,

package/src/env/types.ts

@@ -8,11 +8,10 @@ export const MIDSCENE_DEBUG_MODEL_RESPONSE = 'MIDSCENE_DEBUG_MODEL_RESPONSE';
 export const MIDSCENE_DANGEROUSLY_PRINT_ALL_CONFIG =
   'MIDSCENE_DANGEROUSLY_PRINT_ALL_CONFIG';
 export const MIDSCENE_DEBUG_MODE = 'MIDSCENE_DEBUG_MODE';
-export const MIDSCENE_CHROME_PATH = 'MIDSCENE_CHROME_PATH';
-/**
- * @deprecated Use MIDSCENE_CHROME_PATH instead. This is kept for backward compatibility.
- */
+export const MIDSCENE_MCP_USE_PUPPETEER_MODE =
+  'MIDSCENE_MCP_USE_PUPPETEER_MODE';
 export const MIDSCENE_MCP_CHROME_PATH = 'MIDSCENE_MCP_CHROME_PATH';
+export const MIDSCENE_MCP_ANDROID_MODE = 'MIDSCENE_MCP_ANDROID_MODE';
 export const DOCKER_CONTAINER = 'DOCKER_CONTAINER';
 
 // Observability
@@ -167,6 +166,8 @@ export const BASIC_ENV_KEYS = [
 
 export const BOOLEAN_ENV_KEYS = [
   MIDSCENE_CACHE,
+  MIDSCENE_MCP_USE_PUPPETEER_MODE,
+  MIDSCENE_MCP_ANDROID_MODE,
   MIDSCENE_LANGSMITH_DEBUG,
   MIDSCENE_LANGFUSE_DEBUG,
   MIDSCENE_REPORT_QUIET,
@@ -187,7 +188,6 @@ export const STRING_ENV_KEYS = [
   MIDSCENE_REPORT_TAG_NAME,
   MIDSCENE_PREFERRED_LANGUAGE,
   MATCH_BY_POSITION,
-  MIDSCENE_CHROME_PATH,
   MIDSCENE_MCP_CHROME_PATH,
   DOCKER_CONTAINER,
 ] as const;

package/src/key-alias-utils.ts

@@ -1,7 +1,7 @@
 /**
- * Internal-only helpers for CLI argument key aliasing.
+ * Internal-only helpers for CLI/MCP argument key aliasing.
  * Not re-exported from the package entry point — keep consumers within
- * `cli/`.
+ * `cli/` and `mcp/`.
  */
 
 export function kebabToCamel(str: string): string {