@midscene/shared 1.9.8-beta-20260618014851.0 → 1.9.8

package/dist/es/cli/cli-runner.mjs

@@ -2,8 +2,8 @@ import { existsSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import dotenv from "dotenv";
-import { stripBehaviorFlags } from "../agent-tools/tool-defaults.mjs";
 import { getDebug } from "../logger.mjs";
+import { stripBehaviorFlags } from "../mcp/tool-defaults.mjs";
 import { canonicalizeCliArgKeys, formatCliValidationError, getCliOptionDisplay, parseCliArgs, parseValue } from "./cli-args.mjs";
 import { CLIError, reportCLIError } from "./cli-error.mjs";
 const debug = getDebug('cli-runner');

package/dist/es/env/parse-model-config.mjs

@@ -5,7 +5,7 @@ import { assert } from "../utils.mjs";
 import { maskConfig, parseJson } from "./helper.mjs";
 import { initDebugConfig } from "./init-debug.mjs";
 const MODEL_CONFIG_DOC_URL = 'https://midscenejs.com/model-common-config.html';
-const getCurrentVersion = ()=>"1.9.8-beta-20260618014851.0";
+const getCurrentVersion = ()=>"1.9.8";
 const getInvalidModelFamilyMessage = (modelFamily)=>`Invalid MIDSCENE_MODEL_FAMILY value: ${modelFamily}. Current version v${getCurrentVersion()} accepts the following model families: ${MODEL_FAMILY_VALUES.join(', ')}. You can also visit ${MODEL_CONFIG_DOC_URL} for the latest configuration information.`;
 const KEYS_MAP = {
     insight: INSIGHT_MODEL_CONFIG_KEYS,

package/dist/es/env/types.mjs

@@ -5,8 +5,9 @@ const MIDSCENE_DEBUG_MODEL_PROFILE = 'MIDSCENE_DEBUG_MODEL_PROFILE';
 const MIDSCENE_DEBUG_MODEL_RESPONSE = 'MIDSCENE_DEBUG_MODEL_RESPONSE';
 const MIDSCENE_DANGEROUSLY_PRINT_ALL_CONFIG = 'MIDSCENE_DANGEROUSLY_PRINT_ALL_CONFIG';
 const MIDSCENE_DEBUG_MODE = 'MIDSCENE_DEBUG_MODE';
-const MIDSCENE_CHROME_PATH = 'MIDSCENE_CHROME_PATH';
+const MIDSCENE_MCP_USE_PUPPETEER_MODE = 'MIDSCENE_MCP_USE_PUPPETEER_MODE';
 const MIDSCENE_MCP_CHROME_PATH = 'MIDSCENE_MCP_CHROME_PATH';
+const MIDSCENE_MCP_ANDROID_MODE = 'MIDSCENE_MCP_ANDROID_MODE';
 const DOCKER_CONTAINER = 'DOCKER_CONTAINER';
 const MIDSCENE_LANGSMITH_DEBUG = 'MIDSCENE_LANGSMITH_DEBUG';
 const MIDSCENE_LANGFUSE_DEBUG = 'MIDSCENE_LANGFUSE_DEBUG';
@@ -89,6 +90,8 @@ const BASIC_ENV_KEYS = [
 ];
 const BOOLEAN_ENV_KEYS = [
     MIDSCENE_CACHE,
+    MIDSCENE_MCP_USE_PUPPETEER_MODE,
+    MIDSCENE_MCP_ANDROID_MODE,
     MIDSCENE_LANGSMITH_DEBUG,
     MIDSCENE_LANGFUSE_DEBUG,
     MIDSCENE_REPORT_QUIET
@@ -107,7 +110,6 @@ const STRING_ENV_KEYS = [
     MIDSCENE_REPORT_TAG_NAME,
     MIDSCENE_PREFERRED_LANGUAGE,
     MATCH_BY_POSITION,
-    MIDSCENE_CHROME_PATH,
     MIDSCENE_MCP_CHROME_PATH,
     DOCKER_CONTAINER
 ];
@@ -206,4 +208,4 @@ var types_UITarsModelVersion = /*#__PURE__*/ function(UITarsModelVersion) {
     UITarsModelVersion["DOUBAO_1_5_20B"] = "doubao-1.5-20B";
     return UITarsModelVersion;
 }({});
-export { ALL_ENV_KEYS, BASIC_ENV_KEYS, BOOLEAN_ENV_KEYS, DOCKER_CONTAINER, GLOBAL_ENV_KEYS, MATCH_BY_POSITION, MIDSCENE_ADB_PATH, MIDSCENE_ADB_REMOTE_HOST, MIDSCENE_ADB_REMOTE_PORT, MIDSCENE_ANDROID_IME_STRATEGY, MIDSCENE_CACHE, MIDSCENE_CACHE_MAX_FILENAME_LENGTH, MIDSCENE_CHROME_PATH, MIDSCENE_DANGEROUSLY_PRINT_ALL_CONFIG, MIDSCENE_DEBUG_MODE, MIDSCENE_DEBUG_MODEL_PROFILE, MIDSCENE_DEBUG_MODEL_RESPONSE, MIDSCENE_INSIGHT_MODEL_API_KEY, MIDSCENE_INSIGHT_MODEL_BASE_URL, MIDSCENE_INSIGHT_MODEL_EXTRA_BODY_JSON, MIDSCENE_INSIGHT_MODEL_FAMILY, MIDSCENE_INSIGHT_MODEL_HTTP_PROXY, MIDSCENE_INSIGHT_MODEL_INIT_CONFIG_JSON, MIDSCENE_INSIGHT_MODEL_NAME, MIDSCENE_INSIGHT_MODEL_REASONING_BUDGET, MIDSCENE_INSIGHT_MODEL_REASONING_EFFORT, MIDSCENE_INSIGHT_MODEL_REASONING_ENABLED, MIDSCENE_INSIGHT_MODEL_RETRY_COUNT, MIDSCENE_INSIGHT_MODEL_RETRY_INTERVAL, MIDSCENE_INSIGHT_MODEL_SOCKS_PROXY, MIDSCENE_INSIGHT_MODEL_TEMPERATURE, MIDSCENE_INSIGHT_MODEL_TIMEOUT, MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE, MIDSCENE_IOS_DEVICE_UDID, MIDSCENE_IOS_SIMULATOR_UDID, MIDSCENE_LANGFUSE_DEBUG, MIDSCENE_LANGSMITH_DEBUG, MIDSCENE_MCP_CHROME_PATH, MIDSCENE_MODEL_API_KEY, MIDSCENE_MODEL_BASE_URL, MIDSCENE_MODEL_EXTRA_BODY_JSON, MIDSCENE_MODEL_FAMILY, MIDSCENE_MODEL_HTTP_PROXY, MIDSCENE_MODEL_INIT_CONFIG_JSON, MIDSCENE_MODEL_NAME, MIDSCENE_MODEL_REASONING_BUDGET, MIDSCENE_MODEL_REASONING_EFFORT, MIDSCENE_MODEL_REASONING_ENABLED, MIDSCENE_MODEL_RETRY_COUNT, MIDSCENE_MODEL_RETRY_INTERVAL, MIDSCENE_MODEL_SOCKS_PROXY, MIDSCENE_MODEL_TEMPERATURE, MIDSCENE_MODEL_TIMEOUT, MIDSCENE_OPENAI_HTTP_PROXY, MIDSCENE_OPENAI_INIT_CONFIG_JSON, MIDSCENE_OPENAI_SOCKS_PROXY, MIDSCENE_PLANNING_MODEL_API_KEY, MIDSCENE_PLANNING_MODEL_BASE_URL, MIDSCENE_PLANNING_MODEL_EXTRA_BODY_JSON, MIDSCENE_PLANNING_MODEL_FAMILY, MIDSCENE_PLANNING_MODEL_HTTP_PROXY, MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON, MIDSCENE_PLANNING_MODEL_NAME, MIDSCENE_PLANNING_MODEL_REASONING_BUDGET, MIDSCENE_PLANNING_MODEL_REASONING_EFFORT, MIDSCENE_PLANNING_MODEL_REASONING_ENABLED, MIDSCENE_PLANNING_MODEL_RETRY_COUNT, MIDSCENE_PLANNING_MODEL_RETRY_INTERVAL, MIDSCENE_PLANNING_MODEL_SOCKS_PROXY, MIDSCENE_PLANNING_MODEL_TEMPERATURE, MIDSCENE_PLANNING_MODEL_TIMEOUT, MIDSCENE_PREFERRED_LANGUAGE, MIDSCENE_REPLANNING_CYCLE_LIMIT, MIDSCENE_REPORT_QUIET, MIDSCENE_REPORT_TAG_NAME, MIDSCENE_RUN_DIR, MIDSCENE_USE_DOUBAO_VISION, MIDSCENE_USE_GEMINI, MIDSCENE_USE_QWEN3_VL, MIDSCENE_USE_QWEN_VL, MIDSCENE_USE_VLM_UI_TARS, MIDSCENE_USE_VL_MODEL, MODEL_ENV_KEYS, MODEL_FAMILY_VALUES, NUMBER_ENV_KEYS, OPENAI_API_KEY, OPENAI_BASE_URL, STRING_ENV_KEYS, types_UITarsModelVersion as UITarsModelVersion, UNUSED_ENV_KEYS };
+export { ALL_ENV_KEYS, BASIC_ENV_KEYS, BOOLEAN_ENV_KEYS, DOCKER_CONTAINER, GLOBAL_ENV_KEYS, MATCH_BY_POSITION, MIDSCENE_ADB_PATH, MIDSCENE_ADB_REMOTE_HOST, MIDSCENE_ADB_REMOTE_PORT, MIDSCENE_ANDROID_IME_STRATEGY, MIDSCENE_CACHE, MIDSCENE_CACHE_MAX_FILENAME_LENGTH, MIDSCENE_DANGEROUSLY_PRINT_ALL_CONFIG, MIDSCENE_DEBUG_MODE, MIDSCENE_DEBUG_MODEL_PROFILE, MIDSCENE_DEBUG_MODEL_RESPONSE, MIDSCENE_INSIGHT_MODEL_API_KEY, MIDSCENE_INSIGHT_MODEL_BASE_URL, MIDSCENE_INSIGHT_MODEL_EXTRA_BODY_JSON, MIDSCENE_INSIGHT_MODEL_FAMILY, MIDSCENE_INSIGHT_MODEL_HTTP_PROXY, MIDSCENE_INSIGHT_MODEL_INIT_CONFIG_JSON, MIDSCENE_INSIGHT_MODEL_NAME, MIDSCENE_INSIGHT_MODEL_REASONING_BUDGET, MIDSCENE_INSIGHT_MODEL_REASONING_EFFORT, MIDSCENE_INSIGHT_MODEL_REASONING_ENABLED, MIDSCENE_INSIGHT_MODEL_RETRY_COUNT, MIDSCENE_INSIGHT_MODEL_RETRY_INTERVAL, MIDSCENE_INSIGHT_MODEL_SOCKS_PROXY, MIDSCENE_INSIGHT_MODEL_TEMPERATURE, MIDSCENE_INSIGHT_MODEL_TIMEOUT, MIDSCENE_IOS_DEVICE_CLASS_OVERRIDE, MIDSCENE_IOS_DEVICE_UDID, MIDSCENE_IOS_SIMULATOR_UDID, MIDSCENE_LANGFUSE_DEBUG, MIDSCENE_LANGSMITH_DEBUG, MIDSCENE_MCP_ANDROID_MODE, MIDSCENE_MCP_CHROME_PATH, MIDSCENE_MCP_USE_PUPPETEER_MODE, MIDSCENE_MODEL_API_KEY, MIDSCENE_MODEL_BASE_URL, MIDSCENE_MODEL_EXTRA_BODY_JSON, MIDSCENE_MODEL_FAMILY, MIDSCENE_MODEL_HTTP_PROXY, MIDSCENE_MODEL_INIT_CONFIG_JSON, MIDSCENE_MODEL_NAME, MIDSCENE_MODEL_REASONING_BUDGET, MIDSCENE_MODEL_REASONING_EFFORT, MIDSCENE_MODEL_REASONING_ENABLED, MIDSCENE_MODEL_RETRY_COUNT, MIDSCENE_MODEL_RETRY_INTERVAL, MIDSCENE_MODEL_SOCKS_PROXY, MIDSCENE_MODEL_TEMPERATURE, MIDSCENE_MODEL_TIMEOUT, MIDSCENE_OPENAI_HTTP_PROXY, MIDSCENE_OPENAI_INIT_CONFIG_JSON, MIDSCENE_OPENAI_SOCKS_PROXY, MIDSCENE_PLANNING_MODEL_API_KEY, MIDSCENE_PLANNING_MODEL_BASE_URL, MIDSCENE_PLANNING_MODEL_EXTRA_BODY_JSON, MIDSCENE_PLANNING_MODEL_FAMILY, MIDSCENE_PLANNING_MODEL_HTTP_PROXY, MIDSCENE_PLANNING_MODEL_INIT_CONFIG_JSON, MIDSCENE_PLANNING_MODEL_NAME, MIDSCENE_PLANNING_MODEL_REASONING_BUDGET, MIDSCENE_PLANNING_MODEL_REASONING_EFFORT, MIDSCENE_PLANNING_MODEL_REASONING_ENABLED, MIDSCENE_PLANNING_MODEL_RETRY_COUNT, MIDSCENE_PLANNING_MODEL_RETRY_INTERVAL, MIDSCENE_PLANNING_MODEL_SOCKS_PROXY, MIDSCENE_PLANNING_MODEL_TEMPERATURE, MIDSCENE_PLANNING_MODEL_TIMEOUT, MIDSCENE_PREFERRED_LANGUAGE, MIDSCENE_REPLANNING_CYCLE_LIMIT, MIDSCENE_REPORT_QUIET, MIDSCENE_REPORT_TAG_NAME, MIDSCENE_RUN_DIR, MIDSCENE_USE_DOUBAO_VISION, MIDSCENE_USE_GEMINI, MIDSCENE_USE_QWEN3_VL, MIDSCENE_USE_QWEN_VL, MIDSCENE_USE_VLM_UI_TARS, MIDSCENE_USE_VL_MODEL, MODEL_ENV_KEYS, MODEL_FAMILY_VALUES, NUMBER_ENV_KEYS, OPENAI_API_KEY, OPENAI_BASE_URL, STRING_ENV_KEYS, types_UITarsModelVersion as UITarsModelVersion, UNUSED_ENV_KEYS };

package/dist/es/mcp/base-server.mjs

@@ -0,0 +1,295 @@
+import { randomUUID } from "node:crypto";
+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 from "express";
+import { getErrorMessage } from "./error-formatter.mjs";
+import { TOOL_BEHAVIOR_FLAGS, mergeToolDefaults, resolveToolDefaults } from "./tool-defaults.mjs";
+function _define_property(obj, key, value) {
+    if (key in obj) Object.defineProperty(obj, key, {
+        value: value,
+        enumerable: true,
+        configurable: true,
+        writable: true
+    });
+    else obj[key] = value;
+    return obj;
+}
+const CLI_ARGS_CONFIG = {
+    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'
+            }
+        ]))
+};
+function launchMCPServer(server, args) {
+    server.setToolDefaults(resolveToolDefaults((cli)=>true === args[cli]));
+    if ('http' === args.mode) return server.launchHttp({
+        port: Number.parseInt(args.port || '3000', 10),
+        host: args.host || 'localhost'
+    });
+    return server.launch();
+}
+const SESSION_TIMEOUT_MS = 1800000;
+const CLEANUP_INTERVAL_MS = 300000;
+const MAX_SESSIONS = 100;
+class BaseMCPServer {
+    setToolDefaults(toolDefaults) {
+        this.toolDefaults = mergeToolDefaults(this.toolDefaults, toolDefaults);
+    }
+    async initializeToolsManager() {
+        setIsMcp(true);
+        this.toolsManager = this.providedToolsManager || this.createToolsManager();
+        this.toolsManager.setToolDefaults?.(this.toolDefaults);
+        try {
+            await this.toolsManager.initTools();
+        } catch (error) {
+            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);
+    }
+    async performCleanup() {
+        console.error(`${this.config.name} closing...`);
+        this.mcpServer.close();
+        await this.toolsManager?.destroy?.().catch(console.error);
+    }
+    async launch() {
+        console.log = (...args)=>{
+            console.error('[LOG]', ...args);
+        };
+        console.info = (...args)=>{
+            console.error('[INFO]', ...args);
+        };
+        console.debug = (...args)=>{
+            console.error('[DEBUG]', ...args);
+        };
+        await this.initializeToolsManager();
+        const transport = new StdioServerTransport();
+        try {
+            await this.mcpServer.connect(transport);
+        } catch (error) {
+            const message = getErrorMessage(error);
+            console.error(`Failed to connect MCP stdio transport: ${message}`);
+            throw new Error(`Failed to initialize MCP stdio transport: ${message}`);
+        }
+        let isShuttingDown = false;
+        const cleanup = ()=>{
+            if (isShuttingDown) return;
+            isShuttingDown = true;
+            console.error(`${this.config.name} shutting down...`);
+            this.performCleanup().finally(()=>process.exit(0));
+        };
+        process.on('uncaughtException', (error)=>{
+            if ('EPIPE' === error.code || 'ERR_STREAM_DESTROYED' === error.code) return void cleanup();
+            console.error(`[${this.config.name}] Uncaught Exception:`, error);
+            console.error('Stack:', error.stack);
+        });
+        process.on('unhandledRejection', (reason)=>{
+            console.error(`[${this.config.name}] Unhandled Rejection:`, reason);
+            if (reason instanceof Error) console.error('Stack:', reason.stack);
+        });
+        process.stdin.on('close', cleanup);
+        process.stdin.on('end', cleanup);
+        process.stdout.on('error', cleanup);
+        process.once('SIGINT', cleanup);
+        process.once('SIGTERM', cleanup);
+        process.once('SIGHUP', cleanup);
+        return {
+            close: async ()=>{
+                this.performCleanup();
+            }
+        };
+    }
+    async launchHttp(options) {
+        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 = express();
+        app.use(express.json({
+            limit: '10mb'
+        }));
+        const sessions = new Map();
+        app.all('/mcp', async (req, res)=>{
+            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) : void 0;
+                if (!session && 'POST' === req.method) {
+                    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) {
+                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';
+        const server = app.listen(options.port, host, ()=>{
+            console.log(`${this.config.name} HTTP server listening on http://${host}:${options.port}/mcp`);
+        }).on('error', (error)=>{
+            if ('EADDRINUSE' === error.code) 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 ('EACCES' === error.code) 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}\nReason: ${error.message}\nCode: ${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) {
+                    const message = getErrorMessage(error);
+                    console.error(`Failed to close session ${session.transport.sessionId}: ${message}`);
+                }
+                sessions.clear();
+                return new Promise((resolve)=>{
+                    server.close(async (err)=>{
+                        if (err) console.error('Error closing HTTP server:', err);
+                        await this.performCleanup();
+                        resolve();
+                    });
+                });
+            }
+        };
+    }
+    async createHttpSession(sessions) {
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: ()=>randomUUID(),
+            onsessioninitialized: (sid)=>{
+                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) {
+            const message = getErrorMessage(error);
+            console.error(`[${new Date().toISOString()}] Failed to connect MCP transport: ${message}`);
+            if (transport.sessionId) sessions.delete(transport.sessionId);
+            throw new Error(`Failed to initialize MCP session: ${message}`);
+        }
+        return {
+            transport,
+            createdAt: new Date(),
+            lastAccessedAt: new Date()
+        };
+    }
+    startSessionCleanup(sessions) {
+        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) {
+                const message = getErrorMessage(error);
+                console.error(`[${new Date().toISOString()}] Failed to close session ${sid} during cleanup: ${message}`);
+                sessions.delete(sid);
+            }
+        }, CLEANUP_INTERVAL_MS);
+    }
+    setupHttpShutdownHandlers(server, sessions, cleanupInterval) {
+        const cleanup = ()=>{
+            console.error(`${this.config.name} shutting down...`);
+            clearInterval(cleanupInterval);
+            for (const session of sessions.values())try {
+                session.transport.close();
+            } catch (error) {
+                const message = getErrorMessage(error);
+                console.error(`Error closing session during shutdown: ${message}`);
+            }
+            sessions.clear();
+            try {
+                server.close(()=>{
+                    this.performCleanup().finally(()=>process.exit(0));
+                });
+                setTimeout(()=>{
+                    console.error('Forcefully shutting down after timeout');
+                    this.performCleanup().finally(()=>process.exit(1));
+                }, 5000);
+            } catch (error) {
+                const message = getErrorMessage(error);
+                console.error(`Error closing HTTP server: ${message}`);
+                this.performCleanup().finally(()=>process.exit(1));
+            }
+        };
+        process.once('SIGINT', cleanup);
+        process.once('SIGTERM', cleanup);
+    }
+    getServer() {
+        return this.mcpServer;
+    }
+    getToolsManager() {
+        return this.toolsManager;
+    }
+    constructor(config, toolsManager){
+        _define_property(this, "mcpServer", void 0);
+        _define_property(this, "toolsManager", void 0);
+        _define_property(this, "config", void 0);
+        _define_property(this, "providedToolsManager", void 0);
+        _define_property(this, "toolDefaults", {});
+        this.config = config;
+        this.mcpServer = new McpServer({
+            name: config.name,
+            version: config.version,
+            description: config.description
+        });
+        this.providedToolsManager = toolsManager;
+    }
+}
+export { BaseMCPServer, CLI_ARGS_CONFIG, launchMCPServer };

package/dist/es/{agent-tools → mcp}/base-tools.mjs

@@ -15,7 +15,7 @@ function _define_property(obj, key, value) {
     else obj[key] = value;
     return obj;
 }
-const debug = getDebug('agent-tools:base-tools');
+const debug = getDebug('mcp:base-tools');
 class BaseMidsceneTools {
     getInitArgKeys() {
         return this.initArgSpec ? Object.keys(this.initArgSpec.shape) : [];
@@ -104,6 +104,12 @@ class BaseMidsceneTools {
         this.toolDefinitions.push(...actionTools, ...commonTools);
         debug('Total tools prepared:', this.toolDefinitions.length);
     }
+    attachToServer(server) {
+        this.mcpServer = server;
+        if (0 === this.toolDefinitions.length) 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');
+    }
     async destroy() {
         await this.agent?.destroy?.();
     }
@@ -149,6 +155,7 @@ class BaseMidsceneTools {
         };
     }
     constructor(){
+        _define_property(this, "mcpServer", void 0);
         _define_property(this, "agent", void 0);
         _define_property(this, "toolDefinitions", []);
         _define_property(this, "toolDefaults", {});

package/dist/es/{agent-tools → mcp}/chrome-path.mjs

@@ -1,10 +1,5 @@
 import { existsSync } from "node:fs";
-import { MIDSCENE_CHROME_PATH, MIDSCENE_MCP_CHROME_PATH, globalConfigManager } from "../env/index.mjs";
-import { getDebug } from "../logger.mjs";
-const warnChromePath = getDebug('agent-tools:chrome-path', {
-    console: true
-});
-let hasWarnedLegacyChromePath = false;
+import { MIDSCENE_MCP_CHROME_PATH, globalConfigManager } from "../env/index.mjs";
 function getSystemChromePath() {
     const platform = process.platform;
     const chromePaths = {
@@ -31,16 +26,10 @@ function getSystemChromePath() {
     return paths.find((p)=>existsSync(p));
 }
 function resolveChromePath() {
-    const primaryEnvPath = globalConfigManager.getEnvConfigValue(MIDSCENE_CHROME_PATH);
-    const legacyEnvPath = 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;
-    }
+    const envPath = globalConfigManager.getEnvConfigValue(MIDSCENE_MCP_CHROME_PATH);
     if (envPath && 'auto' !== envPath && existsSync(envPath)) return envPath;
     const systemPath = getSystemChromePath();
     if (systemPath) return systemPath;
-    throw new Error('Chrome not found. Install Google Chrome or set MIDSCENE_CHROME_PATH environment variable.');
+    throw new Error('Chrome not found. Install Google Chrome or set MIDSCENE_MCP_CHROME_PATH environment variable.');
 }
 export { getSystemChromePath, resolveChromePath };

package/dist/es/{agent-tools → mcp}/index.mjs

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

package/dist/es/mcp/inject-report-html-plugin.mjs

@@ -0,0 +1,53 @@
+import node_fs from "node:fs";
+import node_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\*\/.*/;
+function injectReportHtmlFromCore(packageDir) {
+    return {
+        name: 'inject-report-html-from-core',
+        setup (api) {
+            api.onAfterBuild(()=>{
+                const coreUtilsPath = node_path.resolve(packageDir, '..', 'core', 'dist', 'lib', 'utils.js');
+                if (!node_fs.existsSync(coreUtilsPath)) return void console.warn('[inject-report-html] @midscene/core dist not found, skipping');
+                const coreContent = node_fs.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 = node_path.join(packageDir, 'dist');
+                if (!node_fs.existsSync(distDir)) return;
+                const jsFiles = node_fs.readdirSync(distDir).filter((f)=>f.endsWith('.js'));
+                let injectedCount = 0;
+                for (const file of jsFiles){
+                    const filePath = node_path.join(distDir, file);
+                    const content = node_fs.readFileSync(filePath, 'utf-8');
+                    if (content.includes(REPLACED_MARK)) {
+                        if (REG_EXP_FOR_REPLACE.test(content)) {
+                            node_fs.writeFileSync(filePath, content.replace(REG_EXP_FOR_REPLACE, ()=>finalContent));
+                            console.log(`[inject-report-html] Updated: ${file}`);
+                            injectedCount++;
+                        }
+                    } else if (content.includes(`'${MAGIC_STRING}'`)) {
+                        node_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)`);
+            });
+        }
+    };
+}
+export { injectReportHtmlFromCore };

package/dist/es/mcp/launcher-helper.mjs

@@ -0,0 +1,52 @@
+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;
+        }
+    };
+}
+export { createMCPServerLauncher };

package/dist/es/{agent-tools → mcp}/tool-generator.mjs

@@ -3,7 +3,7 @@ import { z } from "zod";
 import { getZodDescription, getZodTypeName, isMidsceneLocatorField, unwrapZodField } from "../zod-schema-utils.mjs";
 import { getErrorMessage } from "./error-formatter.mjs";
 import { composeUserPrompt, promptInputExtraSchema } from "./user-prompt.mjs";
-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);
@@ -75,7 +75,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)));
 }
@@ -327,7 +327,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/es/utils.mjs

@@ -34,8 +34,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);
@@ -65,4 +69,4 @@ function mergeAndNormalizeAppNameMapping(defaultMapping, userMapping) {
     if (userMapping) for (const [key, value] of Object.entries(userMapping))result[normalizeForComparison(key)] = value;
     return result;
 }
-export { antiEscapeScriptTag, assert, escapeScriptTag, generateHashId, ifInBrowser, ifInNode, ifInWorker, isPlainObject, logMsg, mergeAndNormalizeAppNameMapping, normalizeForComparison, repeat, replaceIllegalPathCharsAndSpace, uuid };
+export { antiEscapeScriptTag, assert, escapeScriptTag, generateHashId, ifInBrowser, ifInNode, ifInWorker, isPlainObject, logMsg, mergeAndNormalizeAppNameMapping, normalizeForComparison, repeat, replaceIllegalPathCharsAndSpace, setIsMcp, uuid };

package/dist/lib/cli/cli-runner.js

@@ -45,8 +45,8 @@ const external_node_os_namespaceObject = require("node:os");
 const external_node_path_namespaceObject = require("node:path");
 const external_dotenv_namespaceObject = require("dotenv");
 var external_dotenv_default = /*#__PURE__*/ __webpack_require__.n(external_dotenv_namespaceObject);
-const tool_defaults_js_namespaceObject = require("../agent-tools/tool-defaults.js");
 const external_logger_js_namespaceObject = require("../logger.js");
+const tool_defaults_js_namespaceObject = require("../mcp/tool-defaults.js");
 const external_cli_args_js_namespaceObject = require("./cli-args.js");
 const external_cli_error_js_namespaceObject = require("./cli-error.js");
 const debug = (0, external_logger_js_namespaceObject.getDebug)('cli-runner');

package/dist/lib/env/parse-model-config.js

@@ -37,7 +37,7 @@ const external_utils_js_namespaceObject = require("../utils.js");
 const external_helper_js_namespaceObject = require("./helper.js");
 const external_init_debug_js_namespaceObject = require("./init-debug.js");
 const MODEL_CONFIG_DOC_URL = 'https://midscenejs.com/model-common-config.html';
-const getCurrentVersion = ()=>"1.9.8-beta-20260618014851.0";
+const getCurrentVersion = ()=>"1.9.8";
 const getInvalidModelFamilyMessage = (modelFamily)=>`Invalid MIDSCENE_MODEL_FAMILY value: ${modelFamily}. Current version v${getCurrentVersion()} accepts the following model families: ${external_types_js_namespaceObject.MODEL_FAMILY_VALUES.join(', ')}. You can also visit ${MODEL_CONFIG_DOC_URL} for the latest configuration information.`;
 const KEYS_MAP = {
     insight: external_constants_js_namespaceObject.INSIGHT_MODEL_CONFIG_KEYS,