@actiondock/mcp 2.0.12 → 2.2.0

package/dist/stdio-host.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { serveParentIpc } from "@actiondock/core";
+import { resolveTarget } from "./adapter.js";
+try {
+    const rawOptions = process.env.ACTIONDOCK_MCP_OPTIONS;
+    const options = rawOptions ? JSON.parse(rawOptions) : {};
+    const { target } = await resolveTarget(options);
+    await serveParentIpc(target);
+}
+catch (err) {
+    process.stderr.write(`[MCP Host Error] ${err?.stack || err?.message || String(err)}\n`);
+    process.exit(1);
+}

package/dist/stdio.d.ts

@@ -1,5 +1,10 @@
-import type { ActionDockMcpOptions } from "./types";
+import type { ActionDockMcpOptions } from "./types.js";
 /**
- * Starts an ActionDock MCP server over STDIO transport.
+ * 启动 ActionDock MCP STDIO 协议服务。
+ * 建立监督进程物理边界：
+ * 1. 监督父进程独占标准输入/输出通道，专用于承载 JSON-RPC 协议；
+ * 2. 子进程承载 Action 运行时，通过 Node IPC 通信；
+ * 3. 子进程输出被重定向并进行限流排空（转入受控诊断流 stderr），彻底杜绝业务 console.log 破坏 MCP STDIO 流；
+ * 4. 子进程异常退出时，转换为结构化 JSON-RPC 错误，保障协议稳定性。
  */
 export declare function startMcpStdio(options?: ActionDockMcpOptions): Promise<void>;

package/dist/stdio.js

@@ -0,0 +1,114 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { IpcActionDockTarget } from "@actiondock/core";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { createActionDockMcpServer, resolveTarget } from "./adapter.js";
+/**
+ * 启动 ActionDock MCP STDIO 协议服务。
+ * 建立监督进程物理边界：
+ * 1. 监督父进程独占标准输入/输出通道，专用于承载 JSON-RPC 协议；
+ * 2. 子进程承载 Action 运行时，通过 Node IPC 通信；
+ * 3. 子进程输出被重定向并进行限流排空（转入受控诊断流 stderr），彻底杜绝业务 console.log 破坏 MCP STDIO 流；
+ * 4. 子进程异常退出时，转换为结构化 JSON-RPC 错误，保障协议稳定性。
+ */
+export async function startMcpStdio(options = {}) {
+    let activeServer;
+    let targetToUse;
+    let childProcess;
+    // 若显式传入了已构造的 target 或不可序列化的内存对象，直接复用或解析目标实例
+    if (options.target || options.actions || options.storage || options.app || options.host) {
+        targetToUse = options.target ?? (await resolveTarget(options)).target;
+    }
+    else {
+        // 建立隔离的监督子进程
+        const currentDir = dirname(fileURLToPath(import.meta.url));
+        const hostScript = resolve(currentDir, existsSync(join(currentDir, "stdio-host.ts")) ? "stdio-host.ts" : "stdio-host.js");
+        childProcess = spawn(process.execPath, [hostScript], {
+            cwd: options.projectRoot || process.cwd(),
+            env: {
+                ...process.env,
+                ACTIONDOCK_MCP_OPTIONS: JSON.stringify({
+                    projectRoot: options.projectRoot,
+                    projectRoots: options.projectRoots,
+                    packageId: options.packageId,
+                    packageIds: options.packageIds,
+                    all: options.all,
+                    customHome: options.customHome,
+                    configOverrides: options.configOverrides,
+                    timeoutMs: options.timeoutMs,
+                }),
+            },
+            stdio: ["pipe", "pipe", "pipe", "ipc"],
+        });
+        // 标准输出物理隔离与受控限流排空转入 stderr 诊断流
+        targetToUse = new IpcActionDockTarget({
+            childProcess,
+            maxDiagnosticBytes: 512 * 1024,
+            maxDiagnosticRate: 64 * 1024,
+            diagnosticTarget: process.stderr,
+        });
+    }
+    const stdioHandler = serveStdio(async () => {
+        const server = await createActionDockMcpServer({
+            ...options,
+            target: targetToUse,
+        });
+        activeServer = server;
+        targetToUse = targetToUse || server.target;
+        return server;
+    }, {
+        onerror: (err) => {
+            process.stderr.write(`[MCP Error] ${err?.message || String(err)}\n`);
+        },
+    });
+    const cleanup = async () => {
+        // 清理链路逐层释放，错误不吞没：收集首个异常向上透传，后续层继续尽力释放
+        let firstError;
+        const swallow = (err) => {
+            if (firstError === undefined)
+                firstError = err;
+            process.stderr.write(`[MCP Cleanup Error] ${err instanceof Error ? err.message : String(err)}\n`);
+        };
+        if (activeServer) {
+            try {
+                await activeServer.close();
+            }
+            catch (err) {
+                swallow(err);
+            }
+        }
+        if (targetToUse) {
+            try {
+                await targetToUse.close();
+            }
+            catch (err) {
+                swallow(err);
+            }
+        }
+        try {
+            await stdioHandler.close();
+        }
+        catch (err) {
+            swallow(err);
+        }
+        if (firstError !== undefined) {
+            throw firstError;
+        }
+    };
+    const handleSignal = (signalName) => {
+        cleanup()
+            .then(() => {
+            // 正常关闭退出码为 0
+            process.exit(0);
+        })
+            .catch((err) => {
+            // 清理失败退出非零退出码，异常详情已写入 stderr 诊断流
+            process.stderr.write(`[MCP ${signalName} Cleanup Failed] ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        });
+    };
+    process.once("SIGINT", () => handleSignal("SIGINT"));
+    process.once("SIGTERM", () => handleSignal("SIGTERM"));
+}

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { ExecutionManager, RuntimeStorage, ServerRuntimeRegistry } from "@actiondock/core";
+import type { ActionDockApp, ActionDockHost, ActionDockTarget, RuntimeStorage } from "@actiondock/core";
 import type { ActionDefinition, RunRecord, RunStatus } from "@actiondock/sdk";
 /**
  * MCP 任务状态枚举（兼容 Model Context Protocol Task 规范）。
@@ -26,8 +26,15 @@ export declare function toMcpTaskStatus(status: RunStatus): McpTaskStatus;
 export declare function toMcpTaskPayload(run: RunRecord): McpTaskPayload;
 /**
  * ActionDock MCP 适配层初始化选项。
+ * 统一以 target（及可选 host, app）为核心。
  */
 export interface ActionDockMcpOptions {
+    /** 目标 ActionDockTarget 门面实例（最高优先级） */
+    target?: ActionDockTarget;
+    /** 目标 ActionDockHost 宿主实例 */
+    host?: ActionDockHost;
+    /** 目标 ActionDockApp 应用实例 */
+    app?: ActionDockApp;
     /** 单个目标项目根目录 */
     projectRoot?: string;
     /** 多个项目根目录（用于多包聚合提供） */
@@ -44,14 +51,28 @@ export interface ActionDockMcpOptions {
     configOverrides?: Record<string, unknown>;
     /** 单个 Tool 执行超时时间（毫秒） */
     timeoutMs?: number;
-    /** 预加载的 Action 映射表 */
-    actions?: Map<string, ActionDefinition>;
-    /** 底层存储实例 */
+    /** 预加载的 Action 集合（单元测试或内存模式使用） */
+    actions?: Map<string, ActionDefinition> | Array<{
+        id: string;
+        action: ActionDefinition;
+    } | (ActionDefinition & {
+        id: string;
+    })> | Record<string, ActionDefinition>;
+    /** 底层存储实例（单元测试或特定场景注入） */
     storage?: RuntimeStorage;
-    /** 服务端运行时注册表 */
-    runtimeRegistry?: ServerRuntimeRegistry;
-    /** 活跃执行任务管理器 */
-    executionManager?: ExecutionManager;
+    /**
+     * 是否由适配层接管外部注入 storage 的生命周期。
+     * 默认 false：外部注入的 storage 由注入方自行管理，适配层不具各 close 语义；
+     * 置为 true 时透传原始实例，随 target.close() 级联关闭。
+     */
+    ownStorageLifecycle?: boolean;
+    /**
+     * 实例 close 是否级联关闭 target 门面。
+     * 默认 false：适配层产物可能被 SDK 传输层按请求（或按连接）创建与销毁，
+     * 级联语义会误杀共享 target，生命周期统一由外层入口的 stop/cleanup 收敛；
+     * 仅在调用方自行持有实例并需要一次 close 同时释放 target 时置 true。
+     */
+    cascadeTargetClose?: boolean;
 }
 /**
  * HTTP 传输协议安全配置项。
@@ -61,14 +82,18 @@ export interface HttpSecurityOptions {
     port?: number;
     token?: string;
     allowInsecureNoAuth?: boolean;
+    allowQueryToken?: boolean;
+    allowInsecureHttp?: boolean;
     corsOrigins?: string[];
     maxBodyBytes?: number;
 }
-export interface ActionDockMcpHttpOptions extends ActionDockMcpOptions, HttpSecurityOptions {
+export interface ActionDockMcpHttpOptions extends Omit<ActionDockMcpOptions, "host">, Omit<HttpSecurityOptions, "host"> {
+    host?: string | ActionDockHost;
 }
 export interface ActionDockMcpHttpServerInstance {
     port: number;
     host: string;
     url: string;
+    target?: ActionDockTarget;
     stop: () => Promise<void>;
 }

package/dist/types.js

@@ -0,0 +1,33 @@
+/**
+ * 将 ActionDock 内部的 RunStatus 转换为 MCP 标准的 TaskStatus。
+ */
+export function toMcpTaskStatus(status) {
+    switch (status) {
+        case "running":
+            return "working";
+        case "success":
+            return "completed";
+        case "failed":
+        case "timed_out":
+        case "interrupted":
+            return "failed";
+        case "cancelled":
+            return "cancelled";
+        default:
+            return "failed";
+    }
+}
+/**
+ * 将内部 RunRecord 实体转换为向 MCP 客户端暴露的 McpTaskPayload。
+ */
+export function toMcpTaskPayload(run) {
+    return {
+        taskId: run.id,
+        status: toMcpTaskStatus(run.status),
+        createdAt: run.startedAt,
+        finishedAt: run.finishedAt,
+        input: run.input,
+        output: run.output,
+        error: run.error,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actiondock/mcp",
-  "version": "2.0.12",
+  "version": "2.2.0",
   "description": "ActionDock MCP Adapter for exposing Actions as Model Context Protocol (MCP) Tools",
   "type": "module",
   "main": "./dist/index.js",
@@ -18,19 +18,19 @@
     "README.md"
   ],
   "engines": {
-    "node": ">=22.13.0"
+    "node": ">=24.12.0"
   },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
   "scripts": {
-    "build": "bun run ../../scripts/build.ts",
-    "test": "bun test"
+    "build": "node ../../scripts/build.ts",
+    "test": "node ../../scripts/run-tests.ts"
   },
   "dependencies": {
-    "@actiondock/core": "^2.0.12",
-    "@actiondock/sdk": "^2.0.12",
+    "@actiondock/core": "^2.2.0",
+    "@actiondock/sdk": "^2.2.0",
     "@modelcontextprotocol/server": "^2.0.0"
   },
   "devDependencies": {