@midscene/shared 1.9.8-beta-20260618014851.0 → 1.9.8

package/dist/lib/mcp/inject-report-html-plugin.js

@@ -0,0 +1,98 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.n = (module)=>{
+        var getter = module && module.__esModule ? ()=>module['default'] : ()=>module;
+        __webpack_require__.d(getter, {
+            a: getter
+        });
+        return getter;
+    };
+})();
+(()=>{
+    __webpack_require__.d = (exports1, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    injectReportHtmlFromCore: ()=>injectReportHtmlFromCore
+});
+const external_node_fs_namespaceObject = require("node:fs");
+var external_node_fs_default = /*#__PURE__*/ __webpack_require__.n(external_node_fs_namespaceObject);
+const external_node_path_namespaceObject = require("node:path");
+var external_node_path_default = /*#__PURE__*/ __webpack_require__.n(external_node_path_namespaceObject);
+const MAGIC_STRING = 'REPLACE_ME_WITH_REPORT_HTML';
+const REPLACED_MARK = '/*REPORT_HTML_REPLACED*/';
+const REG_EXP_FOR_REPLACE = /\/\*REPORT_HTML_REPLACED\*\/.*/;
+function injectReportHtmlFromCore(packageDir) {
+    return {
+        name: 'inject-report-html-from-core',
+        setup (api) {
+            api.onAfterBuild(()=>{
+                const coreUtilsPath = external_node_path_default().resolve(packageDir, '..', 'core', 'dist', 'lib', 'utils.js');
+                if (!external_node_fs_default().existsSync(coreUtilsPath)) return void console.warn('[inject-report-html] @midscene/core dist not found, skipping');
+                const coreContent = external_node_fs_default().readFileSync(coreUtilsPath, 'utf-8');
+                if (!coreContent.includes(REPLACED_MARK)) return void console.warn('[inject-report-html] HTML not found in core dist. Ensure report builds first.');
+                const markerIndex = coreContent.indexOf(REPLACED_MARK);
+                const jsonStart = markerIndex + REPLACED_MARK.length;
+                let jsonEnd = jsonStart;
+                if ('"' === coreContent[jsonStart]) {
+                    jsonEnd = jsonStart + 1;
+                    while(jsonEnd < coreContent.length)if ('\\' === coreContent[jsonEnd]) jsonEnd += 2;
+                    else if ('"' === coreContent[jsonEnd]) {
+                        jsonEnd += 1;
+                        break;
+                    } else jsonEnd += 1;
+                }
+                const jsonString = coreContent.slice(jsonStart, jsonEnd);
+                if (!jsonString || jsonString.length < 10) return void console.warn('[inject-report-html] Failed to extract HTML from core');
+                const finalContent = `${REPLACED_MARK}${jsonString}`;
+                const distDir = external_node_path_default().join(packageDir, 'dist');
+                if (!external_node_fs_default().existsSync(distDir)) return;
+                const jsFiles = external_node_fs_default().readdirSync(distDir).filter((f)=>f.endsWith('.js'));
+                let injectedCount = 0;
+                for (const file of jsFiles){
+                    const filePath = external_node_path_default().join(distDir, file);
+                    const content = external_node_fs_default().readFileSync(filePath, 'utf-8');
+                    if (content.includes(REPLACED_MARK)) {
+                        if (REG_EXP_FOR_REPLACE.test(content)) {
+                            external_node_fs_default().writeFileSync(filePath, content.replace(REG_EXP_FOR_REPLACE, ()=>finalContent));
+                            console.log(`[inject-report-html] Updated: ${file}`);
+                            injectedCount++;
+                        }
+                    } else if (content.includes(`'${MAGIC_STRING}'`)) {
+                        external_node_fs_default().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)`);
+            });
+        }
+    };
+}
+exports.injectReportHtmlFromCore = __webpack_exports__.injectReportHtmlFromCore;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "injectReportHtmlFromCore"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/lib/mcp/launcher-helper.js

@@ -0,0 +1,86 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    createMCPServerLauncher: ()=>createMCPServerLauncher
+});
+function createMCPServerLauncher(config) {
+    const { agent, platformName, ToolsManagerClass, MCPServerClass } = config;
+    function validateAgent() {
+        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.`);
+    }
+    function createToolsManager() {
+        const toolsManager = new ToolsManagerClass();
+        toolsManager.agent = agent;
+        return toolsManager;
+    }
+    function logStartupInfo(mode, additionalInfo) {
+        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 !== void 0) console.log(`Port: ${additionalInfo.port}`);
+        if (additionalInfo?.host) console.log(`Host: ${additionalInfo.host}`);
+    }
+    return {
+        async launch (options = {}) {
+            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;
+        },
+        async launchHttp (options) {
+            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;
+        }
+    };
+}
+exports.createMCPServerLauncher = __webpack_exports__.createMCPServerLauncher;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "createMCPServerLauncher"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/lib/{agent-tools → mcp}/tool-generator.js

@@ -33,7 +33,7 @@ const external_zod_namespaceObject = require("zod");
 const external_zod_schema_utils_js_namespaceObject = require("../zod-schema-utils.js");
 const external_error_formatter_js_namespaceObject = require("./error-formatter.js");
 const external_user_prompt_js_namespaceObject = require("./user-prompt.js");
-function describeActionForTool(action) {
+function describeActionForMCP(action) {
     const actionDesc = action.description || `Execute ${action.name} action`;
     if (!action.paramSchema) return `${action.name} action, ${actionDesc}`;
     const shape = getZodObjectShape(action.paramSchema);
@@ -105,7 +105,7 @@ function extractActionSchema(paramSchema, actionName) {
     const shape = getZodObjectShape(paramSchema);
     if (!shape) {
         const typeName = paramSchema?._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.`);
+        throw new Error(`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.`);
     }
     return Object.fromEntries(Object.entries(shape).map(([key, value])=>transformSchemaField(key, value)));
 }
@@ -357,7 +357,7 @@ function generateToolsFromActionSpace(actionSpace, getAgent, sanitizeArgs = (arg
         };
         return {
             name: action.name,
-            description: describeActionForTool(action),
+            description: describeActionForMCP(action),
             schema,
             cli: initArgCliMetadata,
             handler: async (args)=>{

package/dist/lib/utils.js

@@ -24,19 +24,20 @@ var __webpack_require__ = {};
 var __webpack_exports__ = {};
 __webpack_require__.r(__webpack_exports__);
 __webpack_require__.d(__webpack_exports__, {
+    uuid: ()=>uuid,
+    isPlainObject: ()=>isPlainObject,
+    ifInBrowser: ()=>ifInBrowser,
+    repeat: ()=>repeat,
+    mergeAndNormalizeAppNameMapping: ()=>mergeAndNormalizeAppNameMapping,
+    ifInNode: ()=>ifInNode,
+    assert: ()=>assert,
     escapeScriptTag: ()=>escapeScriptTag,
     logMsg: ()=>logMsg,
-    isPlainObject: ()=>isPlainObject,
     replaceIllegalPathCharsAndSpace: ()=>replaceIllegalPathCharsAndSpace,
-    uuid: ()=>uuid,
-    ifInBrowser: ()=>ifInBrowser,
     generateHashId: ()=>generateHashId,
     normalizeForComparison: ()=>normalizeForComparison,
-    mergeAndNormalizeAppNameMapping: ()=>mergeAndNormalizeAppNameMapping,
-    ifInNode: ()=>ifInNode,
     ifInWorker: ()=>ifInWorker,
-    repeat: ()=>repeat,
-    assert: ()=>assert,
+    setIsMcp: ()=>setIsMcp,
     antiEscapeScriptTag: ()=>antiEscapeScriptTag
 });
 const external_js_sha256_namespaceObject = require("js-sha256");
@@ -75,8 +76,12 @@ function generateHashId(rect, content = '') {
 function assert(condition, message) {
     if (!condition) throw new Error(message || 'Assertion failed');
 }
+let isMcp = false;
+function setIsMcp(value) {
+    isMcp = value;
+}
 function logMsg(...message) {
-    console.log(...message);
+    if (!isMcp) console.log(...message);
 }
 async function repeat(times, fn) {
     for(let i = 0; i < times; i++)await fn(i);
@@ -119,6 +124,7 @@ exports.mergeAndNormalizeAppNameMapping = __webpack_exports__.mergeAndNormalizeA
 exports.normalizeForComparison = __webpack_exports__.normalizeForComparison;
 exports.repeat = __webpack_exports__.repeat;
 exports.replaceIllegalPathCharsAndSpace = __webpack_exports__.replaceIllegalPathCharsAndSpace;
+exports.setIsMcp = __webpack_exports__.setIsMcp;
 exports.uuid = __webpack_exports__.uuid;
 for(var __rspack_i in __webpack_exports__)if (-1 === [
     "antiEscapeScriptTag",
@@ -134,6 +140,7 @@ for(var __rspack_i in __webpack_exports__)if (-1 === [
     "normalizeForComparison",
     "repeat",
     "replaceIllegalPathCharsAndSpace",
+    "setIsMcp",
     "uuid"
 ].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
 Object.defineProperty(exports, '__esModule', {

package/dist/types/cli/cli-args.d.ts

@@ -1,4 +1,4 @@
-import type { ToolCliOption, ToolDefinition } from '../agent-tools/types';
+import type { ToolCliOption, ToolDefinition } from '../mcp/types';
 export declare function parseValue(raw: string): unknown;
 export declare function parseCliArgs(args: string[]): Record<string, unknown>;
 export declare function getCliOptionDisplay(key: string, cliOption?: ToolCliOption): {

package/dist/types/cli/cli-runner.d.ts

@@ -1,5 +1,5 @@
-import type { BaseMidsceneTools } from '../agent-tools/base-tools';
-import type { ToolDefinition } from '../agent-tools/types';
+import type { BaseMidsceneTools } from '../mcp/base-tools';
+import type { ToolDefinition } from '../mcp/types';
 export interface CLIExtraCommand {
     name: string;
     def: ToolDefinition;

package/dist/types/env/types.d.ts

@@ -5,11 +5,9 @@ export declare const MIDSCENE_DEBUG_MODEL_PROFILE = "MIDSCENE_DEBUG_MODEL_PROFIL
 export declare const MIDSCENE_DEBUG_MODEL_RESPONSE = "MIDSCENE_DEBUG_MODEL_RESPONSE";
 export declare const MIDSCENE_DANGEROUSLY_PRINT_ALL_CONFIG = "MIDSCENE_DANGEROUSLY_PRINT_ALL_CONFIG";
 export declare const MIDSCENE_DEBUG_MODE = "MIDSCENE_DEBUG_MODE";
-export declare const MIDSCENE_CHROME_PATH = "MIDSCENE_CHROME_PATH";
-/**
- * @deprecated Use MIDSCENE_CHROME_PATH instead. This is kept for backward compatibility.
- */
+export declare const MIDSCENE_MCP_USE_PUPPETEER_MODE = "MIDSCENE_MCP_USE_PUPPETEER_MODE";
 export declare const MIDSCENE_MCP_CHROME_PATH = "MIDSCENE_MCP_CHROME_PATH";
+export declare const MIDSCENE_MCP_ANDROID_MODE = "MIDSCENE_MCP_ANDROID_MODE";
 export declare const DOCKER_CONTAINER = "DOCKER_CONTAINER";
 export declare const MIDSCENE_LANGSMITH_DEBUG = "MIDSCENE_LANGSMITH_DEBUG";
 export declare const MIDSCENE_LANGFUSE_DEBUG = "MIDSCENE_LANGFUSE_DEBUG";
@@ -106,22 +104,22 @@ export declare const UNUSED_ENV_KEYS: string[];
  * can not be override by overrideAIConfig
  */
 export declare const BASIC_ENV_KEYS: readonly ["MIDSCENE_DEBUG_MODE", "MIDSCENE_DEBUG_MODEL_PROFILE", "MIDSCENE_DEBUG_MODEL_RESPONSE", "MIDSCENE_RUN_DIR"];
-export declare const BOOLEAN_ENV_KEYS: readonly ["MIDSCENE_CACHE", "MIDSCENE_LANGSMITH_DEBUG", "MIDSCENE_LANGFUSE_DEBUG", "MIDSCENE_REPORT_QUIET"];
+export declare const BOOLEAN_ENV_KEYS: readonly ["MIDSCENE_CACHE", "MIDSCENE_MCP_USE_PUPPETEER_MODE", "MIDSCENE_MCP_ANDROID_MODE", "MIDSCENE_LANGSMITH_DEBUG", "MIDSCENE_LANGFUSE_DEBUG", "MIDSCENE_REPORT_QUIET"];
 export declare const NUMBER_ENV_KEYS: readonly ["MIDSCENE_CACHE_MAX_FILENAME_LENGTH", "MIDSCENE_REPLANNING_CYCLE_LIMIT"];
-export declare const STRING_ENV_KEYS: readonly ["MIDSCENE_ADB_PATH", "MIDSCENE_ADB_REMOTE_HOST", "MIDSCENE_ADB_REMOTE_PORT", "MIDSCENE_ANDROID_IME_STRATEGY", "MIDSCENE_IOS_DEVICE_UDID", "MIDSCENE_IOS_SIMULATOR_UDID", "MIDSCENE_REPORT_TAG_NAME", "MIDSCENE_PREFERRED_LANGUAGE", "MATCH_BY_POSITION", "MIDSCENE_CHROME_PATH", "MIDSCENE_MCP_CHROME_PATH", "DOCKER_CONTAINER"];
+export declare const STRING_ENV_KEYS: readonly ["MIDSCENE_ADB_PATH", "MIDSCENE_ADB_REMOTE_HOST", "MIDSCENE_ADB_REMOTE_PORT", "MIDSCENE_ANDROID_IME_STRATEGY", "MIDSCENE_IOS_DEVICE_UDID", "MIDSCENE_IOS_SIMULATOR_UDID", "MIDSCENE_REPORT_TAG_NAME", "MIDSCENE_PREFERRED_LANGUAGE", "MATCH_BY_POSITION", "MIDSCENE_MCP_CHROME_PATH", "DOCKER_CONTAINER"];
 /**
  * Non model related env keys, used for globally controlling the behavior of midscene
  * Can not be override by agent.modelConfig but can be override by overrideAIConfig
  * Can be access at any time
  */
-export declare const GLOBAL_ENV_KEYS: readonly ["MIDSCENE_CACHE", "MIDSCENE_LANGSMITH_DEBUG", "MIDSCENE_LANGFUSE_DEBUG", "MIDSCENE_REPORT_QUIET", "MIDSCENE_CACHE_MAX_FILENAME_LENGTH", "MIDSCENE_REPLANNING_CYCLE_LIMIT", "MIDSCENE_ADB_PATH", "MIDSCENE_ADB_REMOTE_HOST", "MIDSCENE_ADB_REMOTE_PORT", "MIDSCENE_ANDROID_IME_STRATEGY", "MIDSCENE_IOS_DEVICE_UDID", "MIDSCENE_IOS_SIMULATOR_UDID", "MIDSCENE_REPORT_TAG_NAME", "MIDSCENE_PREFERRED_LANGUAGE", "MATCH_BY_POSITION", "MIDSCENE_CHROME_PATH", "MIDSCENE_MCP_CHROME_PATH", "DOCKER_CONTAINER"];
+export declare const GLOBAL_ENV_KEYS: readonly ["MIDSCENE_CACHE", "MIDSCENE_MCP_USE_PUPPETEER_MODE", "MIDSCENE_MCP_ANDROID_MODE", "MIDSCENE_LANGSMITH_DEBUG", "MIDSCENE_LANGFUSE_DEBUG", "MIDSCENE_REPORT_QUIET", "MIDSCENE_CACHE_MAX_FILENAME_LENGTH", "MIDSCENE_REPLANNING_CYCLE_LIMIT", "MIDSCENE_ADB_PATH", "MIDSCENE_ADB_REMOTE_HOST", "MIDSCENE_ADB_REMOTE_PORT", "MIDSCENE_ANDROID_IME_STRATEGY", "MIDSCENE_IOS_DEVICE_UDID", "MIDSCENE_IOS_SIMULATOR_UDID", "MIDSCENE_REPORT_TAG_NAME", "MIDSCENE_PREFERRED_LANGUAGE", "MATCH_BY_POSITION", "MIDSCENE_MCP_CHROME_PATH", "DOCKER_CONTAINER"];
 /**
  * Model related eve keys, used for declare which model to use.
  * Can be override by both agent.modelConfig and overrideAIConfig
  * Can only be access after agent.constructor
  */
 export declare const MODEL_ENV_KEYS: readonly ["MIDSCENE_MODEL_NAME", "MIDSCENE_MODEL_INIT_CONFIG_JSON", "MIDSCENE_MODEL_EXTRA_BODY_JSON", "MIDSCENE_MODEL_API_KEY", "MIDSCENE_MODEL_BASE_URL", "MIDSCENE_MODEL_SOCKS_PROXY", "MIDSCENE_MODEL_HTTP_PROXY", "MIDSCENE_MODEL_TIMEOUT", "MIDSCENE_MODEL_TEMPERATURE", "MIDSCENE_MODEL_RETRY_COUNT", "MIDSCENE_MODEL_RETRY_INTERVAL", "MIDSCENE_MODEL_REASONING_EFFORT", "MIDSCENE_MODEL_REASONING_ENABLED", "MIDSCENE_MODEL_REASONING_BUDGET", "MIDSCENE_USE_VLM_UI_TARS", "MIDSCENE_USE_QWEN_VL", "MIDSCENE_USE_QWEN3_VL", "MIDSCENE_USE_DOUBAO_VISION", "MIDSCENE_USE_GEMINI", "MIDSCENE_USE_VL_MODEL", "OPENAI_API_KEY", "OPENAI_BASE_URL", "MIDSCENE_OPENAI_INIT_CONFIG_JSON", "MIDSCENE_OPENAI_HTTP_PROXY", "MIDSCENE_OPENAI_SOCKS_PROXY", "MIDSCENE_INSIGHT_MODEL_NAME", "MIDSCENE_INSIGHT_MODEL_SOCKS_PROXY", "MIDSCENE_INSIGHT_MODEL_HTTP_PROXY", "MIDSCENE_INSIGHT_MODEL_BASE_URL", "MIDSCENE_INSIGHT_MODEL_API_KEY", "MIDSCENE_INSIGHT_MODEL_INIT_CONFIG_JSON", "MIDSCENE_INSIGHT_MODEL_EXTRA_BODY_JSON", "MIDSCENE_INSIGHT_MODEL_TIMEOUT", "MIDSCENE_INSIGHT_MODEL_TEMPERATURE", "MIDSCENE_INSIGHT_MODEL_RETRY_COUNT", "MIDSCENE_INSIGHT_MODEL_RETRY_INTERVAL", "MIDSCENE_INSIGHT_MODEL_FAMILY", "MIDSCENE_INSIGHT_MODEL_REASONING_EFFORT", "MIDSCENE_INSIGHT_MODEL_REASONING_ENABLED", "MIDSCENE_INSIGHT_MODEL_REASONING_BUDGET", "MIDSCENE_PLANNING_MODEL_NAME", "MIDSCENE_PLANNING_MODEL_SOCKS_PROXY", "MIDSCENE_PLANNING_MODEL_HTTP_PROXY", "MIDSCENE_PLANNING_MODEL_BASE_URL", "MIDSCENE_PLANNING_MODEL_API_KEY", "MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON", "MIDSCENE_PLANNING_MODEL_EXTRA_BODY_JSON", "MIDSCENE_PLANNING_MODEL_TIMEOUT", "MIDSCENE_PLANNING_MODEL_TEMPERATURE", "MIDSCENE_PLANNING_MODEL_RETRY_COUNT", "MIDSCENE_PLANNING_MODEL_RETRY_INTERVAL", "MIDSCENE_PLANNING_MODEL_FAMILY", "MIDSCENE_PLANNING_MODEL_REASONING_EFFORT", "MIDSCENE_PLANNING_MODEL_REASONING_ENABLED", "MIDSCENE_PLANNING_MODEL_REASONING_BUDGET", "MIDSCENE_MODEL_FAMILY"];
-export declare const ALL_ENV_KEYS: readonly [...string[], "MIDSCENE_DEBUG_MODE", "MIDSCENE_DEBUG_MODEL_PROFILE", "MIDSCENE_DEBUG_MODEL_RESPONSE", "MIDSCENE_RUN_DIR", "MIDSCENE_CACHE", "MIDSCENE_LANGSMITH_DEBUG", "MIDSCENE_LANGFUSE_DEBUG", "MIDSCENE_REPORT_QUIET", "MIDSCENE_CACHE_MAX_FILENAME_LENGTH", "MIDSCENE_REPLANNING_CYCLE_LIMIT", "MIDSCENE_ADB_PATH", "MIDSCENE_ADB_REMOTE_HOST", "MIDSCENE_ADB_REMOTE_PORT", "MIDSCENE_ANDROID_IME_STRATEGY", "MIDSCENE_IOS_DEVICE_UDID", "MIDSCENE_IOS_SIMULATOR_UDID", "MIDSCENE_REPORT_TAG_NAME", "MIDSCENE_PREFERRED_LANGUAGE", "MATCH_BY_POSITION", "MIDSCENE_CHROME_PATH", "MIDSCENE_MCP_CHROME_PATH", "DOCKER_CONTAINER", "MIDSCENE_MODEL_NAME", "MIDSCENE_MODEL_INIT_CONFIG_JSON", "MIDSCENE_MODEL_EXTRA_BODY_JSON", "MIDSCENE_MODEL_API_KEY", "MIDSCENE_MODEL_BASE_URL", "MIDSCENE_MODEL_SOCKS_PROXY", "MIDSCENE_MODEL_HTTP_PROXY", "MIDSCENE_MODEL_TIMEOUT", "MIDSCENE_MODEL_TEMPERATURE", "MIDSCENE_MODEL_RETRY_COUNT", "MIDSCENE_MODEL_RETRY_INTERVAL", "MIDSCENE_MODEL_REASONING_EFFORT", "MIDSCENE_MODEL_REASONING_ENABLED", "MIDSCENE_MODEL_REASONING_BUDGET", "MIDSCENE_USE_VLM_UI_TARS", "MIDSCENE_USE_QWEN_VL", "MIDSCENE_USE_QWEN3_VL", "MIDSCENE_USE_DOUBAO_VISION", "MIDSCENE_USE_GEMINI", "MIDSCENE_USE_VL_MODEL", "OPENAI_API_KEY", "OPENAI_BASE_URL", "MIDSCENE_OPENAI_INIT_CONFIG_JSON", "MIDSCENE_OPENAI_HTTP_PROXY", "MIDSCENE_OPENAI_SOCKS_PROXY", "MIDSCENE_INSIGHT_MODEL_NAME", "MIDSCENE_INSIGHT_MODEL_SOCKS_PROXY", "MIDSCENE_INSIGHT_MODEL_HTTP_PROXY", "MIDSCENE_INSIGHT_MODEL_BASE_URL", "MIDSCENE_INSIGHT_MODEL_API_KEY", "MIDSCENE_INSIGHT_MODEL_INIT_CONFIG_JSON", "MIDSCENE_INSIGHT_MODEL_EXTRA_BODY_JSON", "MIDSCENE_INSIGHT_MODEL_TIMEOUT", "MIDSCENE_INSIGHT_MODEL_TEMPERATURE", "MIDSCENE_INSIGHT_MODEL_RETRY_COUNT", "MIDSCENE_INSIGHT_MODEL_RETRY_INTERVAL", "MIDSCENE_INSIGHT_MODEL_FAMILY", "MIDSCENE_INSIGHT_MODEL_REASONING_EFFORT", "MIDSCENE_INSIGHT_MODEL_REASONING_ENABLED", "MIDSCENE_INSIGHT_MODEL_REASONING_BUDGET", "MIDSCENE_PLANNING_MODEL_NAME", "MIDSCENE_PLANNING_MODEL_SOCKS_PROXY", "MIDSCENE_PLANNING_MODEL_HTTP_PROXY", "MIDSCENE_PLANNING_MODEL_BASE_URL", "MIDSCENE_PLANNING_MODEL_API_KEY", "MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON", "MIDSCENE_PLANNING_MODEL_EXTRA_BODY_JSON", "MIDSCENE_PLANNING_MODEL_TIMEOUT", "MIDSCENE_PLANNING_MODEL_TEMPERATURE", "MIDSCENE_PLANNING_MODEL_RETRY_COUNT", "MIDSCENE_PLANNING_MODEL_RETRY_INTERVAL", "MIDSCENE_PLANNING_MODEL_FAMILY", "MIDSCENE_PLANNING_MODEL_REASONING_EFFORT", "MIDSCENE_PLANNING_MODEL_REASONING_ENABLED", "MIDSCENE_PLANNING_MODEL_REASONING_BUDGET", "MIDSCENE_MODEL_FAMILY"];
+export declare const ALL_ENV_KEYS: readonly [...string[], "MIDSCENE_DEBUG_MODE", "MIDSCENE_DEBUG_MODEL_PROFILE", "MIDSCENE_DEBUG_MODEL_RESPONSE", "MIDSCENE_RUN_DIR", "MIDSCENE_CACHE", "MIDSCENE_MCP_USE_PUPPETEER_MODE", "MIDSCENE_MCP_ANDROID_MODE", "MIDSCENE_LANGSMITH_DEBUG", "MIDSCENE_LANGFUSE_DEBUG", "MIDSCENE_REPORT_QUIET", "MIDSCENE_CACHE_MAX_FILENAME_LENGTH", "MIDSCENE_REPLANNING_CYCLE_LIMIT", "MIDSCENE_ADB_PATH", "MIDSCENE_ADB_REMOTE_HOST", "MIDSCENE_ADB_REMOTE_PORT", "MIDSCENE_ANDROID_IME_STRATEGY", "MIDSCENE_IOS_DEVICE_UDID", "MIDSCENE_IOS_SIMULATOR_UDID", "MIDSCENE_REPORT_TAG_NAME", "MIDSCENE_PREFERRED_LANGUAGE", "MATCH_BY_POSITION", "MIDSCENE_MCP_CHROME_PATH", "DOCKER_CONTAINER", "MIDSCENE_MODEL_NAME", "MIDSCENE_MODEL_INIT_CONFIG_JSON", "MIDSCENE_MODEL_EXTRA_BODY_JSON", "MIDSCENE_MODEL_API_KEY", "MIDSCENE_MODEL_BASE_URL", "MIDSCENE_MODEL_SOCKS_PROXY", "MIDSCENE_MODEL_HTTP_PROXY", "MIDSCENE_MODEL_TIMEOUT", "MIDSCENE_MODEL_TEMPERATURE", "MIDSCENE_MODEL_RETRY_COUNT", "MIDSCENE_MODEL_RETRY_INTERVAL", "MIDSCENE_MODEL_REASONING_EFFORT", "MIDSCENE_MODEL_REASONING_ENABLED", "MIDSCENE_MODEL_REASONING_BUDGET", "MIDSCENE_USE_VLM_UI_TARS", "MIDSCENE_USE_QWEN_VL", "MIDSCENE_USE_QWEN3_VL", "MIDSCENE_USE_DOUBAO_VISION", "MIDSCENE_USE_GEMINI", "MIDSCENE_USE_VL_MODEL", "OPENAI_API_KEY", "OPENAI_BASE_URL", "MIDSCENE_OPENAI_INIT_CONFIG_JSON", "MIDSCENE_OPENAI_HTTP_PROXY", "MIDSCENE_OPENAI_SOCKS_PROXY", "MIDSCENE_INSIGHT_MODEL_NAME", "MIDSCENE_INSIGHT_MODEL_SOCKS_PROXY", "MIDSCENE_INSIGHT_MODEL_HTTP_PROXY", "MIDSCENE_INSIGHT_MODEL_BASE_URL", "MIDSCENE_INSIGHT_MODEL_API_KEY", "MIDSCENE_INSIGHT_MODEL_INIT_CONFIG_JSON", "MIDSCENE_INSIGHT_MODEL_EXTRA_BODY_JSON", "MIDSCENE_INSIGHT_MODEL_TIMEOUT", "MIDSCENE_INSIGHT_MODEL_TEMPERATURE", "MIDSCENE_INSIGHT_MODEL_RETRY_COUNT", "MIDSCENE_INSIGHT_MODEL_RETRY_INTERVAL", "MIDSCENE_INSIGHT_MODEL_FAMILY", "MIDSCENE_INSIGHT_MODEL_REASONING_EFFORT", "MIDSCENE_INSIGHT_MODEL_REASONING_ENABLED", "MIDSCENE_INSIGHT_MODEL_REASONING_BUDGET", "MIDSCENE_PLANNING_MODEL_NAME", "MIDSCENE_PLANNING_MODEL_SOCKS_PROXY", "MIDSCENE_PLANNING_MODEL_HTTP_PROXY", "MIDSCENE_PLANNING_MODEL_BASE_URL", "MIDSCENE_PLANNING_MODEL_API_KEY", "MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON", "MIDSCENE_PLANNING_MODEL_EXTRA_BODY_JSON", "MIDSCENE_PLANNING_MODEL_TIMEOUT", "MIDSCENE_PLANNING_MODEL_TEMPERATURE", "MIDSCENE_PLANNING_MODEL_RETRY_COUNT", "MIDSCENE_PLANNING_MODEL_RETRY_INTERVAL", "MIDSCENE_PLANNING_MODEL_FAMILY", "MIDSCENE_PLANNING_MODEL_REASONING_EFFORT", "MIDSCENE_PLANNING_MODEL_REASONING_ENABLED", "MIDSCENE_PLANNING_MODEL_REASONING_BUDGET", "MIDSCENE_MODEL_FAMILY"];
 export type TEnvKeys = (typeof ALL_ENV_KEYS)[number];
 export type TGlobalConfig = Record<TEnvKeys, string | undefined>;
 /**

package/dist/types/key-alias-utils.d.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 declare function kebabToCamel(str: string): string;
 export declare function camelToKebab(str: string): string;

package/dist/types/mcp/base-server.d.ts

@@ -0,0 +1,106 @@
+import type { ParseArgsConfig } from 'node:util';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type ToolDefaults } 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>;
+}
+/**
+ * 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 declare const CLI_ARGS_CONFIG: ParseArgsConfig['options'];
+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 declare function launchMCPServer(server: BaseMCPServer, args: CLIArgs): Promise<LaunchMCPServerResult>;
+/**
+ * Base MCP Server class with programmatic launch() API
+ * Each platform extends this to provide their own tools manager
+ */
+export declare abstract class BaseMCPServer {
+    protected mcpServer: McpServer;
+    protected toolsManager?: IMidsceneTools;
+    protected config: BaseMCPServerConfig;
+    protected providedToolsManager?: IMidsceneTools;
+    protected toolDefaults: ToolDefaults;
+    constructor(config: BaseMCPServerConfig, toolsManager?: IMidsceneTools);
+    /**
+     * 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.
+     */
+    setToolDefaults(toolDefaults: ToolDefaults): void;
+    /**
+     * 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 initializeToolsManager;
+    /**
+     * Perform cleanup on shutdown
+     */
+    private performCleanup;
+    /**
+     * Initialize and launch the MCP server with stdio transport
+     */
+    launch(): Promise<LaunchMCPServerResult>;
+    /**
+     * Launch MCP server with HTTP transport
+     * Supports stateful sessions for web applications and service integration
+     */
+    launchHttp(options: HttpLaunchOptions): Promise<LaunchMCPServerResult>;
+    /**
+     * Create a new HTTP session with transport
+     */
+    private createHttpSession;
+    /**
+     * Start periodic session cleanup for inactive sessions
+     */
+    private startSessionCleanup;
+    /**
+     * Setup shutdown handlers for HTTP server
+     */
+    private setupHttpShutdownHandlers;
+    /**
+     * Get the underlying MCP server instance
+     */
+    getServer(): McpServer;
+    /**
+     * Get the tools manager instance
+     */
+    getToolsManager(): IMidsceneTools | undefined;
+}

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

@@ -1,3 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { z } from 'zod';
 import { type CliReportSession } from './cli-report-session';
 import { type ToolDefaults } from './tool-defaults';
@@ -10,11 +11,11 @@ import type { BaseAgent, BaseDevice, IMidsceneTools, ToolCliMetadata, ToolDefini
 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. */
@@ -29,23 +30,24 @@ export interface InitArgSpec<TInitParam> {
     adapt?: (extracted: Record<string, unknown> | undefined) => TInitParam | undefined;
 }
 /**
- * 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.
  */
 export declare abstract class BaseMidsceneTools<TAgent extends BaseAgent = BaseAgent, 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.
      *
@@ -64,7 +66,7 @@ export declare abstract class BaseMidsceneTools<TAgent extends BaseAgent = BaseA
     protected abstract ensureAgent(initParam?: TInitParam): Promise<TAgent>;
     private getInitArgKeys;
     /**
-     * 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>): TInitParam | undefined;
     /**
@@ -80,7 +82,7 @@ export declare abstract class BaseMidsceneTools<TAgent extends BaseAgent = BaseA
      * 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;
     /**
@@ -107,6 +109,10 @@ export declare abstract class BaseMidsceneTools<TAgent extends BaseAgent = BaseA
      * 2. Create temporary device instance to read actionSpace (always succeeds)
      */
     initTools(): Promise<void>;
+    /**
+     * Attach to MCP server and register all tools
+     */
+    attachToServer(server: McpServer): void;
     /**
      * Cleanup method - destroy agent and release resources
      */

package/dist/types/{agent-tools → mcp}/index.d.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';

package/dist/types/{agent-tools → mcp}/init-arg-utils.d.ts

@@ -3,11 +3,11 @@ import type { ToolSchema } from './types';
 export declare function extractNamespacedArgs<TFieldName extends string, TArgs extends Record<string, unknown> = Record<string, unknown>>(args: Record<string, unknown>, namespace: string, keys: readonly TFieldName[]): TArgs | undefined;
 export declare function sanitizeNamespacedArgs(args: Record<string, unknown>, namespace: string, keys: readonly string[]): Record<string, unknown>;
 /**
- * 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 declare function createNamespacedInitArgSchema(namespace: string, shape: Record<string, z.ZodTypeAny>): ToolSchema;

package/dist/types/mcp/inject-report-html-plugin.d.ts

@@ -0,0 +1,18 @@
+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 declare function injectReportHtmlFromCore(packageDir: string): {
+    name: string;
+    setup(api: RslibPluginApi): void;
+};
+export {};