@midscene/shared 1.7.4 → 1.7.5-beta-20260420031652.0

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

@@ -4,6 +4,7 @@ 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";
 function _define_property(obj, key, value) {
     if (key in obj) Object.defineProperty(obj, key, {
         value: value,
@@ -45,7 +46,7 @@ class BaseMCPServer {
         try {
             await this.toolsManager.initTools();
         } catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
+            const message = getErrorMessage(error);
             console.error(`Failed to initialize tools: ${message}`);
             console.error('Tools will be initialized on first use');
         }
@@ -71,7 +72,7 @@ class BaseMCPServer {
         try {
             await this.mcpServer.connect(transport);
         } catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
+            const message = getErrorMessage(error);
             console.error(`Failed to connect MCP stdio transport: ${message}`);
             throw new Error(`Failed to initialize MCP stdio transport: ${message}`);
         }
@@ -142,7 +143,7 @@ class BaseMCPServer {
                     });
                 }
             } catch (error) {
-                const message = error instanceof Error ? error.message : String(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({
@@ -170,7 +171,7 @@ class BaseMCPServer {
                 for (const session of sessions.values())try {
                     await session.transport.close();
                 } catch (error) {
-                    const message = error instanceof Error ? error.message : String(error);
+                    const message = getErrorMessage(error);
                     console.error(`Failed to close session ${session.transport.sessionId}: ${message}`);
                 }
                 sessions.clear();
@@ -205,7 +206,7 @@ class BaseMCPServer {
         try {
             await this.mcpServer.connect(transport);
         } catch (error) {
-            const message = error instanceof Error ? error.message : String(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}`);
@@ -224,7 +225,7 @@ class BaseMCPServer {
                 sessions.delete(sid);
                 console.log(`[${new Date().toISOString()}] Session ${sid} cleaned up due to inactivity (remaining: ${sessions.size})`);
             } catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
+                const message = getErrorMessage(error);
                 console.error(`[${new Date().toISOString()}] Failed to close session ${sid} during cleanup: ${message}`);
                 sessions.delete(sid);
             }
@@ -237,7 +238,7 @@ class BaseMCPServer {
             for (const session of sessions.values())try {
                 session.transport.close();
             } catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
+                const message = getErrorMessage(error);
                 console.error(`Error closing session during shutdown: ${message}`);
             }
             sessions.clear();
@@ -250,7 +251,7 @@ class BaseMCPServer {
                     this.performCleanup().finally(()=>process.exit(1));
                 }, 5000);
             } catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
+                const message = getErrorMessage(error);
                 console.error(`Error closing HTTP server: ${message}`);
                 this.performCleanup().finally(()=>process.exit(1));
             }

package/dist/es/mcp/error-formatter.mjs

@@ -0,0 +1,19 @@
+function getErrorMessage(error) {
+    if (error instanceof Error) return error.message;
+    if (null == error) return String(error);
+    if ('object' != typeof error) return String(error);
+    const candidate = extractStringMessage(error);
+    if (candidate) return candidate;
+    try {
+        return JSON.stringify(error);
+    } catch  {
+        return Object.prototype.toString.call(error);
+    }
+}
+function extractStringMessage(error) {
+    const anyError = error;
+    if ('string' == typeof anyError.message && anyError.message) return anyError.message;
+    if (anyError.error && 'string' == typeof anyError.error.message && anyError.error.message) return anyError.error.message;
+    if (anyError.cause && 'string' == typeof anyError.cause.message && anyError.cause.message) return anyError.cause.message;
+}
+export { getErrorMessage };

package/dist/es/mcp/index.mjs

@@ -1,5 +1,6 @@
 export * from "./base-server.mjs";
 export * from "./base-tools.mjs";
+export * from "./error-formatter.mjs";
 export * from "./tool-generator.mjs";
 export * from "./types.mjs";
 export * from "./inject-report-html-plugin.mjs";

package/dist/es/mcp/tool-generator.mjs

@@ -1,9 +1,7 @@
 import { parseBase64 } from "@midscene/shared/img";
 import { z } from "zod";
 import { getZodDescription, getZodTypeName, isMidsceneLocatorField, unwrapZodField } from "../zod-schema-utils.mjs";
-function getErrorMessage(error) {
-    return error instanceof Error ? error.message : String(error);
-}
+import { getErrorMessage } from "./error-formatter.mjs";
 function describeActionForMCP(action) {
     const actionDesc = action.description || `Execute ${action.name} action`;
     if (!action.paramSchema) return `${action.name} action, ${actionDesc}`;

package/dist/lib/mcp/base-server.js

@@ -44,6 +44,7 @@ const stdio_js_namespaceObject = require("@modelcontextprotocol/sdk/server/stdio
 const streamableHttp_js_namespaceObject = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
 const external_express_namespaceObject = require("express");
 var external_express_default = /*#__PURE__*/ __webpack_require__.n(external_express_namespaceObject);
+const external_error_formatter_js_namespaceObject = require("./error-formatter.js");
 function _define_property(obj, key, value) {
     if (key in obj) Object.defineProperty(obj, key, {
         value: value,
@@ -85,7 +86,7 @@ class BaseMCPServer {
         try {
             await this.toolsManager.initTools();
         } catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
+            const message = (0, external_error_formatter_js_namespaceObject.getErrorMessage)(error);
             console.error(`Failed to initialize tools: ${message}`);
             console.error('Tools will be initialized on first use');
         }
@@ -111,7 +112,7 @@ class BaseMCPServer {
         try {
             await this.mcpServer.connect(transport);
         } catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
+            const message = (0, external_error_formatter_js_namespaceObject.getErrorMessage)(error);
             console.error(`Failed to connect MCP stdio transport: ${message}`);
             throw new Error(`Failed to initialize MCP stdio transport: ${message}`);
         }
@@ -182,7 +183,7 @@ class BaseMCPServer {
                     });
                 }
             } catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
+                const message = (0, external_error_formatter_js_namespaceObject.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({
@@ -210,7 +211,7 @@ class BaseMCPServer {
                 for (const session of sessions.values())try {
                     await session.transport.close();
                 } catch (error) {
-                    const message = error instanceof Error ? error.message : String(error);
+                    const message = (0, external_error_formatter_js_namespaceObject.getErrorMessage)(error);
                     console.error(`Failed to close session ${session.transport.sessionId}: ${message}`);
                 }
                 sessions.clear();
@@ -245,7 +246,7 @@ class BaseMCPServer {
         try {
             await this.mcpServer.connect(transport);
         } catch (error) {
-            const message = error instanceof Error ? error.message : String(error);
+            const message = (0, external_error_formatter_js_namespaceObject.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}`);
@@ -264,7 +265,7 @@ class BaseMCPServer {
                 sessions.delete(sid);
                 console.log(`[${new Date().toISOString()}] Session ${sid} cleaned up due to inactivity (remaining: ${sessions.size})`);
             } catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
+                const message = (0, external_error_formatter_js_namespaceObject.getErrorMessage)(error);
                 console.error(`[${new Date().toISOString()}] Failed to close session ${sid} during cleanup: ${message}`);
                 sessions.delete(sid);
             }
@@ -277,7 +278,7 @@ class BaseMCPServer {
             for (const session of sessions.values())try {
                 session.transport.close();
             } catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
+                const message = (0, external_error_formatter_js_namespaceObject.getErrorMessage)(error);
                 console.error(`Error closing session during shutdown: ${message}`);
             }
             sessions.clear();
@@ -290,7 +291,7 @@ class BaseMCPServer {
                     this.performCleanup().finally(()=>process.exit(1));
                 }, 5000);
             } catch (error) {
-                const message = error instanceof Error ? error.message : String(error);
+                const message = (0, external_error_formatter_js_namespaceObject.getErrorMessage)(error);
                 console.error(`Error closing HTTP server: ${message}`);
                 this.performCleanup().finally(()=>process.exit(1));
             }

package/dist/lib/mcp/error-formatter.js

@@ -0,0 +1,53 @@
+"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__, {
+    getErrorMessage: ()=>getErrorMessage
+});
+function getErrorMessage(error) {
+    if (error instanceof Error) return error.message;
+    if (null == error) return String(error);
+    if ('object' != typeof error) return String(error);
+    const candidate = extractStringMessage(error);
+    if (candidate) return candidate;
+    try {
+        return JSON.stringify(error);
+    } catch  {
+        return Object.prototype.toString.call(error);
+    }
+}
+function extractStringMessage(error) {
+    const anyError = error;
+    if ('string' == typeof anyError.message && anyError.message) return anyError.message;
+    if (anyError.error && 'string' == typeof anyError.error.message && anyError.error.message) return anyError.error.message;
+    if (anyError.cause && 'string' == typeof anyError.cause.message && anyError.cause.message) return anyError.cause.message;
+}
+exports.getErrorMessage = __webpack_exports__.getErrorMessage;
+for(var __rspack_i in __webpack_exports__)if (-1 === [
+    "getErrorMessage"
+].indexOf(__rspack_i)) exports[__rspack_i] = __webpack_exports__[__rspack_i];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/lib/mcp/index.js

@@ -9,6 +9,9 @@ var __webpack_modules__ = {
     "./chrome-path" (module) {
         module.exports = require("./chrome-path.js");
     },
+    "./error-formatter" (module) {
+        module.exports = require("./error-formatter.js");
+    },
     "./inject-report-html-plugin" (module) {
         module.exports = require("./inject-report-html-plugin.js");
     },
@@ -73,25 +76,29 @@ var __webpack_exports__ = {};
     var __rspack_reexport = {};
     for(const __rspack_import_key in _base_tools__rspack_import_1)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_base_tools__rspack_import_1[__rspack_import_key];
     __webpack_require__.d(__webpack_exports__, __rspack_reexport);
-    var _tool_generator__rspack_import_2 = __webpack_require__("./tool-generator");
+    var _error_formatter__rspack_import_2 = __webpack_require__("./error-formatter");
+    var __rspack_reexport = {};
+    for(const __rspack_import_key in _error_formatter__rspack_import_2)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_error_formatter__rspack_import_2[__rspack_import_key];
+    __webpack_require__.d(__webpack_exports__, __rspack_reexport);
+    var _tool_generator__rspack_import_3 = __webpack_require__("./tool-generator");
     var __rspack_reexport = {};
-    for(const __rspack_import_key in _tool_generator__rspack_import_2)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_tool_generator__rspack_import_2[__rspack_import_key];
+    for(const __rspack_import_key in _tool_generator__rspack_import_3)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_tool_generator__rspack_import_3[__rspack_import_key];
     __webpack_require__.d(__webpack_exports__, __rspack_reexport);
-    var _types__rspack_import_3 = __webpack_require__("./types");
+    var _types__rspack_import_4 = __webpack_require__("./types");
     var __rspack_reexport = {};
-    for(const __rspack_import_key in _types__rspack_import_3)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_types__rspack_import_3[__rspack_import_key];
+    for(const __rspack_import_key in _types__rspack_import_4)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_types__rspack_import_4[__rspack_import_key];
     __webpack_require__.d(__webpack_exports__, __rspack_reexport);
-    var _inject_report_html_plugin__rspack_import_4 = __webpack_require__("./inject-report-html-plugin");
+    var _inject_report_html_plugin__rspack_import_5 = __webpack_require__("./inject-report-html-plugin");
     var __rspack_reexport = {};
-    for(const __rspack_import_key in _inject_report_html_plugin__rspack_import_4)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_inject_report_html_plugin__rspack_import_4[__rspack_import_key];
+    for(const __rspack_import_key in _inject_report_html_plugin__rspack_import_5)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_inject_report_html_plugin__rspack_import_5[__rspack_import_key];
     __webpack_require__.d(__webpack_exports__, __rspack_reexport);
-    var _launcher_helper__rspack_import_5 = __webpack_require__("./launcher-helper");
+    var _launcher_helper__rspack_import_6 = __webpack_require__("./launcher-helper");
     var __rspack_reexport = {};
-    for(const __rspack_import_key in _launcher_helper__rspack_import_5)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_launcher_helper__rspack_import_5[__rspack_import_key];
+    for(const __rspack_import_key in _launcher_helper__rspack_import_6)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_launcher_helper__rspack_import_6[__rspack_import_key];
     __webpack_require__.d(__webpack_exports__, __rspack_reexport);
-    var _chrome_path__rspack_import_6 = __webpack_require__("./chrome-path");
+    var _chrome_path__rspack_import_7 = __webpack_require__("./chrome-path");
     var __rspack_reexport = {};
-    for(const __rspack_import_key in _chrome_path__rspack_import_6)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_chrome_path__rspack_import_6[__rspack_import_key];
+    for(const __rspack_import_key in _chrome_path__rspack_import_7)if ("default" !== __rspack_import_key) __rspack_reexport[__rspack_import_key] = ()=>_chrome_path__rspack_import_7[__rspack_import_key];
     __webpack_require__.d(__webpack_exports__, __rspack_reexport);
 })();
 for(var __rspack_i in __webpack_exports__)exports[__rspack_i] = __webpack_exports__[__rspack_i];

package/dist/lib/mcp/tool-generator.js

@@ -30,9 +30,7 @@ __webpack_require__.d(__webpack_exports__, {
 const img_namespaceObject = require("@midscene/shared/img");
 const external_zod_namespaceObject = require("zod");
 const external_zod_schema_utils_js_namespaceObject = require("../zod-schema-utils.js");
-function getErrorMessage(error) {
-    return error instanceof Error ? error.message : String(error);
-}
+const external_error_formatter_js_namespaceObject = require("./error-formatter.js");
 function describeActionForMCP(action) {
     const actionDesc = action.description || `Execute ${action.name} action`;
     if (!action.paramSchema) return `${action.name} action, ${actionDesc}`;
@@ -173,7 +171,7 @@ function serializeArgsToDescription(args) {
             return `${key}: "${value}"`;
         }).join(', ');
     } catch (error) {
-        const errorMessage = getErrorMessage(error);
+        const errorMessage = (0, external_error_formatter_js_namespaceObject.getErrorMessage)(error);
         console.error('Error serializing args:', errorMessage);
         return `[args serialization failed: ${errorMessage}]`;
     }
@@ -241,7 +239,7 @@ async function captureScreenshotResult(agent, actionName, actionResult) {
             content
         };
     } catch (error) {
-        const errorMessage = getErrorMessage(error);
+        const errorMessage = (0, external_error_formatter_js_namespaceObject.getErrorMessage)(error);
         console.error('Error capturing screenshot:', errorMessage);
         content[0] = {
             type: 'text',
@@ -323,13 +321,13 @@ function generateToolsFromActionSpace(actionSpace, getAgent) {
                     try {
                         actionResult = await executeAction(agent, action.name, normalizedArgs);
                     } catch (error) {
-                        const errorMessage = getErrorMessage(error);
+                        const errorMessage = (0, external_error_formatter_js_namespaceObject.getErrorMessage)(error);
                         console.error(`Error executing action "${action.name}":`, errorMessage);
                         return await captureFailureResult(agent, action.name, errorMessage);
                     }
                     return await captureScreenshotResult(agent, action.name, actionResult);
                 } catch (error) {
-                    const errorMessage = getErrorMessage(error);
+                    const errorMessage = (0, external_error_formatter_js_namespaceObject.getErrorMessage)(error);
                     console.error(`Error in handler for "${action.name}":`, errorMessage);
                     return createErrorResult(`Failed to get agent or execute action "${action.name}": ${errorMessage}`);
                 }
@@ -359,7 +357,7 @@ function generateCommonTools(getAgent) {
                         ]
                     };
                 } catch (error) {
-                    const errorMessage = getErrorMessage(error);
+                    const errorMessage = (0, external_error_formatter_js_namespaceObject.getErrorMessage)(error);
                     console.error('Error taking screenshot:', errorMessage);
                     return createErrorResult(`Failed to capture screenshot: ${errorMessage}`);
                 }
@@ -389,7 +387,7 @@ function generateCommonTools(getAgent) {
                     }
                     return screenshotResult;
                 } catch (error) {
-                    const errorMessage = getErrorMessage(error);
+                    const errorMessage = (0, external_error_formatter_js_namespaceObject.getErrorMessage)(error);
                     console.error('Error executing act:', errorMessage);
                     return createErrorResult(`Failed to execute act: ${errorMessage}`);
                 }

package/dist/types/mcp/error-formatter.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Extract a human-readable message from an unknown thrown value.
+ *
+ * Many SDK/transport layers reject with structured objects (e.g.
+ * `{ code, message }`, `{ error: { message } }`, `{ cause: { message } }`)
+ * rather than `Error` instances. `String(obj)` collapses those to
+ * `"[object Object]"`, which is useless for diagnostics. This helper walks
+ * the common shapes, falls back to `JSON.stringify`, and finally to
+ * `Object.prototype.toString.call` so that callers always get something
+ * actionable in logs and surfaced tool results.
+ */
+export declare function getErrorMessage(error: unknown): string;

package/dist/types/mcp/index.d.ts

@@ -1,5 +1,6 @@
 export * from './base-server';
 export * from './base-tools';
+export * from './error-formatter';
 export * from './tool-generator';
 export * from './types';
 export * from './inject-report-html-plugin';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@midscene/shared",
-  "version": "1.7.4",
+  "version": "1.7.5-beta-20260420031652.0",
   "repository": "https://github.com/web-infra-dev/midscene",
   "homepage": "https://midscenejs.com/",
   "types": "./dist/types/index.d.ts",

package/src/mcp/base-server.ts

@@ -9,6 +9,7 @@ import express, {
   type Request,
   type Response,
 } from 'express';
+import { getErrorMessage } from './error-formatter';
 import type { IMidsceneTools } from './types';
 
 export interface BaseMCPServerConfig {
@@ -119,7 +120,7 @@ export abstract class BaseMCPServer {
     try {
       await this.toolsManager.initTools();
     } catch (error: unknown) {
-      const message = error instanceof Error ? error.message : String(error);
+      const message = getErrorMessage(error);
       console.error(`Failed to initialize tools: ${message}`);
       console.error('Tools will be initialized on first use');
     }
@@ -160,7 +161,7 @@ export abstract class BaseMCPServer {
     try {
       await this.mcpServer.connect(transport);
     } catch (error: unknown) {
-      const message = error instanceof Error ? error.message : String(error);
+      const message = getErrorMessage(error);
       console.error(`Failed to connect MCP stdio transport: ${message}`);
       throw new Error(`Failed to initialize MCP stdio transport: ${message}`);
     }
@@ -282,7 +283,7 @@ export abstract class BaseMCPServer {
             .json({ error: 'Invalid session or GET without session' });
         }
       } catch (error: unknown) {
-        const message = error instanceof Error ? error.message : String(error);
+        const message = getErrorMessage(error);
         const duration = Date.now() - startTime;
         console.error(
           `[${new Date().toISOString()}] [${requestId}] MCP request error after ${duration}ms: ${message}`,
@@ -336,8 +337,7 @@ export abstract class BaseMCPServer {
           try {
             await session.transport.close();
           } catch (error: unknown) {
-            const message =
-              error instanceof Error ? error.message : String(error);
+            const message = getErrorMessage(error);
             console.error(
               `Failed to close session ${session.transport.sessionId}: ${message}`,
             );
@@ -390,7 +390,7 @@ export abstract class BaseMCPServer {
     try {
       await this.mcpServer.connect(transport);
     } catch (error: unknown) {
-      const message = error instanceof Error ? error.message : String(error);
+      const message = getErrorMessage(error);
       console.error(
         `[${new Date().toISOString()}] Failed to connect MCP transport: ${message}`,
       );
@@ -425,8 +425,7 @@ export abstract class BaseMCPServer {
               `[${new Date().toISOString()}] Session ${sid} cleaned up due to inactivity (remaining: ${sessions.size})`,
             );
           } catch (error: unknown) {
-            const message =
-              error instanceof Error ? error.message : String(error);
+            const message = getErrorMessage(error);
             console.error(
               `[${new Date().toISOString()}] Failed to close session ${sid} during cleanup: ${message}`,
             );
@@ -455,8 +454,7 @@ export abstract class BaseMCPServer {
         try {
           session.transport.close();
         } catch (error: unknown) {
-          const message =
-            error instanceof Error ? error.message : String(error);
+          const message = getErrorMessage(error);
           console.error(`Error closing session during shutdown: ${message}`);
         }
       }
@@ -475,7 +473,7 @@ export abstract class BaseMCPServer {
           this.performCleanup().finally(() => process.exit(1));
         }, 5000);
       } catch (error: unknown) {
-        const message = error instanceof Error ? error.message : String(error);
+        const message = getErrorMessage(error);
         console.error(`Error closing HTTP server: ${message}`);
         this.performCleanup().finally(() => process.exit(1));
       }

package/src/mcp/error-formatter.ts

@@ -0,0 +1,52 @@
+/**
+ * Extract a human-readable message from an unknown thrown value.
+ *
+ * Many SDK/transport layers reject with structured objects (e.g.
+ * `{ code, message }`, `{ error: { message } }`, `{ cause: { message } }`)
+ * rather than `Error` instances. `String(obj)` collapses those to
+ * `"[object Object]"`, which is useless for diagnostics. This helper walks
+ * the common shapes, falls back to `JSON.stringify`, and finally to
+ * `Object.prototype.toString.call` so that callers always get something
+ * actionable in logs and surfaced tool results.
+ */
+export function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  if (error === null || error === undefined) return String(error);
+  if (typeof error !== 'object') return String(error);
+
+  const candidate = extractStringMessage(error);
+  if (candidate) return candidate;
+
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return Object.prototype.toString.call(error);
+  }
+}
+
+function extractStringMessage(error: object): string | undefined {
+  const anyError = error as {
+    message?: unknown;
+    error?: { message?: unknown };
+    cause?: { message?: unknown };
+  };
+
+  if (typeof anyError.message === 'string' && anyError.message) {
+    return anyError.message;
+  }
+  if (
+    anyError.error &&
+    typeof anyError.error.message === 'string' &&
+    anyError.error.message
+  ) {
+    return anyError.error.message;
+  }
+  if (
+    anyError.cause &&
+    typeof anyError.cause.message === 'string' &&
+    anyError.cause.message
+  ) {
+    return anyError.cause.message;
+  }
+  return undefined;
+}

package/src/mcp/index.ts

@@ -1,5 +1,6 @@
 export * from './base-server';
 export * from './base-tools';
+export * from './error-formatter';
 export * from './tool-generator';
 export * from './types';
 export * from './inject-report-html-plugin';

package/src/mcp/tool-generator.ts

@@ -6,6 +6,7 @@ import {
   isMidsceneLocatorField,
   unwrapZodField,
 } from '../zod-schema-utils';
+import { getErrorMessage } from './error-formatter';
 import type {
   ActionSpaceItem,
   BaseAgent,
@@ -13,13 +14,6 @@ import type {
   ToolResult,
 } from './types';
 
-/**
- * Extract error message from unknown error type
- */
-function getErrorMessage(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
-}
-
 /**
  * Generate MCP tool description from ActionSpaceItem
  * Format: "actionName action, description. Parameters: param1 (type) - desc; param2 (type) - desc"