@actiondock/mcp 2.2.1 → 2.3.0

package/dist/adapter.js

@@ -5,7 +5,7 @@ import { ACTIONDOCK_VERSION, ActionResolver, createActionDockTarget, findProject
 import { McpServer } from "@modelcontextprotocol/server";
 import { registerTasksExtension } from "./register-tasks-extension.js";
 import { toMcpSchema } from "./schemas.js";
-import { isAsyncExecutionRequested, stripExecutionWrapper, } from "./execution-mode.js";
+import { extractExecutionTimeoutMs, isAsyncExecutionRequested, stripExecutionWrapper, } from "./execution-mode.js";
 /**
  * 判断目标值是否为普通对象（Plain Object）。
  *
@@ -174,6 +174,7 @@ export async function resolveTarget(options) {
         }
         packages.push({
             packageRoot: root,
+            storage: appStorage,
             customHome: options.customHome,
             configOverrides: options.configOverrides,
         });
@@ -277,17 +278,26 @@ export async function createActionDockMcpServer(options = {}) {
         server.registerTool(toolName, {
             description,
             inputSchema: toMcpSchema(action.inputSchema),
-            outputSchema: action.outputSchema ? toMcpSchema(action.outputSchema) : undefined,
+            // 出参 schema 不注入 execution 包装字段：实际 structuredContent 不含该字段，注入会与真实返回结构不符
+            outputSchema: action.outputSchema
+                ? toMcpSchema(action.outputSchema, false)
+                : undefined,
         }, async (input, ctx) => {
             // 异步执行模式只认显式约定字段 execution.mode，旧版 __async 仅作只读兼容探测
             const isAsync = isAsyncExecutionRequested(input);
             const signal = ctx.mcpReq?.signal;
             // 分发前仅剥离适配层注入的包装字段，业务自有字段（含名为 async 的入参）原样透传
             const cleanInput = stripExecutionWrapper(input);
+            // 超时组合策略：客户端声明与服务端配置同时存在时取较小值（更防御），
+            // 任一方单独存在则直接生效，双方均缺省时不设置超时
+            const clientTimeoutMs = extractExecutionTimeoutMs(input);
+            const effectiveTimeoutMs = typeof options.timeoutMs === "number" && typeof clientTimeoutMs === "number"
+                ? Math.min(options.timeoutMs, clientTimeoutMs)
+                : clientTimeoutMs ?? options.timeoutMs;
             if (isAsync) {
                 const ticket = await target.startAction(action.id, cleanInput, {
                     signal,
-                    timeoutMs: options.timeoutMs,
+                    timeoutMs: effectiveTimeoutMs,
                 });
                 return {
                     content: [
@@ -305,7 +315,7 @@ export async function createActionDockMcpServer(options = {}) {
             }
             const result = await target.runAction(action.id, cleanInput, {
                 signal,
-                timeoutMs: options.timeoutMs,
+                timeoutMs: effectiveTimeoutMs,
             });
             return toMcpResult(result);
         });

package/dist/execution-mode.d.ts

@@ -28,3 +28,10 @@ export declare function isAsyncExecutionRequested(input: unknown): boolean;
  * @param input 工具调用入参
  */
 export declare function stripExecutionWrapper<T>(input: T): T;
+/**
+ * 从工具调用入参的 execution 包装字段中提取客户端显式声明的超时时间。
+ *
+ * @param input 工具调用入参
+ * @returns 客户端声明的超时毫秒数，未声明或非法时返回 undefined
+ */
+export declare function extractExecutionTimeoutMs(input: unknown): number | undefined;

package/dist/execution-mode.js

@@ -61,3 +61,24 @@ export function stripExecutionWrapper(input) {
     }
     return rest;
 }
+/**
+ * 从工具调用入参的 execution 包装字段中提取客户端显式声明的超时时间。
+ *
+ * @param input 工具调用入参
+ * @returns 客户端声明的超时毫秒数，未声明或非法时返回 undefined
+ */
+export function extractExecutionTimeoutMs(input) {
+    if (typeof input !== "object" || input === null || Array.isArray(input)) {
+        return undefined;
+    }
+    const execution = input.execution;
+    if (typeof execution !== "object" ||
+        execution === null ||
+        Array.isArray(execution)) {
+        return undefined;
+    }
+    const timeoutMs = execution.timeoutMs;
+    return typeof timeoutMs === "number" && Number.isFinite(timeoutMs) && timeoutMs > 0
+        ? timeoutMs
+        : undefined;
+}

package/dist/http.js

@@ -12,6 +12,12 @@ export function startMcpHttpServer(options = {}) {
     const port = options.port ?? 5178;
     const host = hostString;
     const token = options.token;
+    // 死选项透明化：allowInsecureHttp 是客户端侧豁免开关，服务端明文 HTTP 监听
+    // 由 allowInsecureNoAuth 与 token 策略约束，传入该字段不会产生任何效果，
+    // 检测到时输出警告避免调用方误以为已生效
+    if (options.allowInsecureHttp === true) {
+        process.stderr.write("[MCP HTTP Warning] allowInsecureHttp has no effect on the server side and is deprecated; it only applies to remote ActionDockTarget clients.\n");
+    }
     // Non-loopback address requires token authentication by default
     if (!isLoopbackHost(host) && !token && !options.allowInsecureNoAuth) {
         throw new Error("Authentication token is required when binding to a non-loopback address. Use --allow-insecure-no-auth to override.");
@@ -196,24 +202,26 @@ export function startMcpHttpServer(options = {}) {
             url,
             target,
             stop: async () => {
-                let targetError;
+                // 先停 HTTP 服务（等待在途请求收尾）再释放 target：
+                // 若先关 target，在途请求的后续 Action 调用会全部异常
+                let serverError;
                 try {
-                    await target.close();
+                    await server.stop(true);
                 }
                 catch (err) {
-                    targetError = err;
+                    serverError = err;
                 }
                 try {
-                    await server.stop(true);
+                    await target.close();
                 }
-                catch (serverErr) {
-                    if (targetError) {
-                        throw new AggregateError([targetError, serverErr], "Failed to stop MCP HTTP server and target");
+                catch (targetErr) {
+                    if (serverError) {
+                        throw new AggregateError([serverError, targetErr], "Failed to stop MCP HTTP server and target");
                     }
-                    throw serverErr;
+                    throw targetErr;
                 }
-                if (targetError) {
-                    throw targetError;
+                if (serverError) {
+                    throw serverError;
                 }
             },
         };

package/dist/register-tasks-extension.js

@@ -1,5 +1,30 @@
 import { fromJsonSchema } from "@modelcontextprotocol/server";
 import { toMcpTaskPayload, toMcpTaskStatus } from "./types.js";
+/** JSON-RPC 保留码段：协议保留区为 -32000 至 -32099，服务端自定义错误码必须落在该区段内。 */
+const TASK_NOT_FOUND_CODE = -32001;
+/** 无效的 limit 参数错误码，同样落在服务端自定义码段。 */
+const INVALID_LIMIT_CODE = -32002;
+/** tasks/list 允许的最大单页数量上限。 */
+const MAX_TASK_LIST_LIMIT = 500;
+/**
+ * 构造携带 JSON-RPC 语义码的任务不存在异常。
+ *
+ * MCP SDK 对处理器抛出的异常会读取数字型 code 字段并原样透传到错误响应，
+ * 裸 Error 缺少 code 会被映射为内部错误（-32603），丢失调用方可分辨的语义。
+ *
+ * @param taskId 未找到的任务标识
+ */
+function taskNotFoundError(taskId) {
+    return Object.assign(new Error(`Task '${taskId}' not found`), { code: TASK_NOT_FOUND_CODE });
+}
+/**
+ * 构造携带 JSON-RPC 语义码的非法 limit 参数异常。
+ *
+ * @param limit 非法的 limit 入参
+ */
+function invalidLimitError(limit) {
+    return Object.assign(new Error(`Invalid tasks/list limit: expected an integer between 1 and ${MAX_TASK_LIST_LIMIT}, got ${JSON.stringify(limit)}`), { code: INVALID_LIMIT_CODE });
+}
 const TASK_ID_PARAMS = fromJsonSchema({
     type: "object",
     properties: {
@@ -40,7 +65,8 @@ export function registerTasksExtension(server, target) {
     server.server.setRequestHandler("tasks/get", { params: TASK_ID_PARAMS }, async (params) => {
         const run = await target.getRun(params.taskId);
         if (!run) {
-            throw new Error(`Task '${params.taskId}' not found`);
+            // 携带语义码透传，避免被 SDK 映射为内部错误
+            throw taskNotFoundError(params.taskId);
         }
         return { task: toMcpTaskPayload(run) };
     });
@@ -55,12 +81,20 @@ export function registerTasksExtension(server, target) {
         }
         const run = await target.getRun(params.taskId);
         if (!run) {
-            throw new Error(`Task '${params.taskId}' not found`);
+            // 携带语义码透传，避免被 SDK 映射为内部错误
+            throw taskNotFoundError(params.taskId);
         }
         return { taskId: params.taskId, status: toMcpTaskStatus(run.status) };
     });
     server.server.setRequestHandler("tasks/list", { params: TASK_LIST_PARAMS }, async (params) => {
-        const limit = typeof params.limit === "number" ? params.limit : 50;
+        // 边界防御：limit 必须为整数，缺省取 50；超限钳制到 [1, 500]，非法值抛带语义码的参数错误
+        let limit = 50;
+        if (params.limit !== undefined) {
+            if (typeof params.limit !== "number" || !Number.isInteger(params.limit)) {
+                throw invalidLimitError(params.limit);
+            }
+            limit = Math.min(Math.max(params.limit, 1), MAX_TASK_LIST_LIMIT);
+        }
         const actionId = params.actionId;
         const runs = await target.listRuns({ limit, actionId });
         const ordered = [...runs].sort((a, b) => toTimeMillis(b.startedAt) - toTimeMillis(a.startedAt));

package/dist/schemas.d.ts

@@ -2,5 +2,10 @@ import type { JsonSchema } from "@actiondock/sdk";
 /**
  * 将 ActionDock 标准 JSON Schema 归一化为 MCP 标准 Tool Schema。
  * 布尔分支已穷尽（true / false / 对象），无其余可达路径。
+ *
+ * @param schema 原始 JSON Schema 定义
+ * @param injectExecution 是否向 schema 注入适配层的 execution 执行控制包装字段：
+ *   入参 schema 需要注入（客户端借此声明执行模式与超时），
+ *   出参 schema 不注入（实际 structuredContent 不含该字段，注入会与真实返回结构不符）
  */
-export declare function toMcpSchema(schema?: JsonSchema): import("@modelcontextprotocol/server").StandardSchemaWithJSON<unknown, unknown>;
+export declare function toMcpSchema(schema?: JsonSchema, injectExecution?: boolean): import("@modelcontextprotocol/server").StandardSchemaWithJSON<unknown, unknown>;

package/dist/schemas.js

@@ -2,8 +2,13 @@ import { fromJsonSchema } from "@modelcontextprotocol/server";
 /**
  * 将 ActionDock 标准 JSON Schema 归一化为 MCP 标准 Tool Schema。
  * 布尔分支已穷尽（true / false / 对象），无其余可达路径。
+ *
+ * @param schema 原始 JSON Schema 定义
+ * @param injectExecution 是否向 schema 注入适配层的 execution 执行控制包装字段：
+ *   入参 schema 需要注入（客户端借此声明执行模式与超时），
+ *   出参 schema 不注入（实际 structuredContent 不含该字段，注入会与真实返回结构不符）
  */
-export function toMcpSchema(schema) {
+export function toMcpSchema(schema, injectExecution = true) {
     if (schema === undefined || schema === true) {
         return fromJsonSchema({});
     }
@@ -15,7 +20,7 @@ export function toMcpSchema(schema) {
     // JSON Schema 为纯数据结构，structuredClone 深拷贝避免污染调用方原始定义；布尔分支已穷尽，收窄为对象模式
     const cloned = structuredClone(schema);
     const properties = (cloned.properties ?? {});
-    if (cloned.type === "object" || cloned.properties) {
+    if ((cloned.type === "object" || cloned.properties) && injectExecution) {
         cloned.properties = properties;
         properties.execution = {
             type: "object",

package/dist/stdio.js

@@ -111,4 +111,24 @@ export async function startMcpStdio(options = {}) {
     };
     process.once("SIGINT", () => handleSignal("SIGINT"));
     process.once("SIGTERM", () => handleSignal("SIGTERM"));
+    // MCP 客户端断开链路：serveStdio 在 stdin 关闭后仅关闭传输层，不退出进程，
+    // 监督进程与 IPC 宿主子进程会永久悬挂。这里监听 stdin 的 end 与 close 事件，
+    // 触发与信号一致的清理退出路径；exitCode 模式确保异步 cleanup 完成后再真正退出。
+    // 幂等防护：cleanup 已被信号或先到的 stdin 事件触发过时不重复执行
+    let cleanupTriggered = false;
+    const triggerCleanupOnce = () => {
+        if (cleanupTriggered)
+            return;
+        cleanupTriggered = true;
+        cleanup()
+            .then(() => {
+            process.exitCode = 0;
+        })
+            .catch((err) => {
+            process.stderr.write(`[MCP Stdio Cleanup Failed] ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exitCode = 1;
+        });
+    };
+    process.stdin.once("end", triggerCleanupOnce);
+    process.stdin.once("close", triggerCleanupOnce);
 }

package/dist/types.d.ts

@@ -83,6 +83,11 @@ export interface HttpSecurityOptions {
     token?: string;
     allowInsecureNoAuth?: boolean;
     allowQueryToken?: boolean;
+    /**
+     * 已废弃：该选项仅适用于远程 ActionDockTarget 客户端侧的明文 HTTP 豁免，
+     * 服务端监听安全性由 allowInsecureNoAuth 与 token 策略约束，传入不会产生任何效果；
+     * 服务端检测到该字段时仅输出警告日志
+     */
     allowInsecureHttp?: boolean;
     corsOrigins?: string[];
     maxBodyBytes?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actiondock/mcp",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "description": "ActionDock MCP Adapter for exposing Actions as Model Context Protocol (MCP) Tools",
   "type": "module",
   "main": "./dist/index.js",
@@ -29,8 +29,8 @@
     "test": "node ../../scripts/run-tests.ts"
   },
   "dependencies": {
-    "@actiondock/core": "^2.2.1",
-    "@actiondock/sdk": "^2.2.1",
+    "@actiondock/core": "^2.3.0",
+    "@actiondock/sdk": "^2.3.0",
     "@modelcontextprotocol/server": "^2.0.0"
   },
   "devDependencies": {