@actiondock/mcp 2.0.11 → 2.2.0

package/dist/http.js

@@ -0,0 +1,221 @@
+import { ACTIONDOCK_VERSION, DEFAULT_MAX_BODY_BYTES, formatHostForUrl, isLoopbackHost, launchHttpServer, resolveCorsHeaders, verifyBearerToken, UNAUTHORIZED, } from "@actiondock/core";
+import { createMcpHandler } from "@modelcontextprotocol/server";
+import { createActionDockMcpServer, resolveTarget } from "./adapter.js";
+/**
+ * Starts an ActionDock MCP server over HTTP transport.
+ */
+export function startMcpHttpServer(options = {}) {
+    const hostInstance = typeof options.host === "object" && options.host !== null
+        ? options.host
+        : undefined;
+    const hostString = typeof options.host === "string" ? options.host : "127.0.0.1";
+    const port = options.port ?? 5178;
+    const host = hostString;
+    const token = options.token;
+    // 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.");
+    }
+    return (async () => {
+        // 先一次性解析 target，工厂闭包直接捕获已解析产物，消除选项重复展开
+        const { target } = await resolveTarget({
+            ...options,
+            host: hostInstance ?? (typeof options.host === "object" ? options.host : undefined),
+        });
+        const handler = createMcpHandler(() => createActionDockMcpServer({ target }), {
+            onerror: (err) => {
+                process.stderr.write(`[MCP HTTP Error] ${err?.message || String(err)}\n`);
+            },
+        });
+        const server = await launchHttpServer(port, host, async (req) => {
+            const origin = req.headers.get("origin");
+            const corsHeaders = resolveCorsHeaders(origin, options.corsOrigins);
+            if (req.method === "OPTIONS") {
+                return new Response(null, {
+                    status: 204,
+                    headers: corsHeaders,
+                });
+            }
+            const url = new URL(req.url);
+            const pathname = url.pathname;
+            const verifyOptions = { allowQueryToken: options.allowQueryToken };
+            // 1. Health check
+            if (pathname === "/health" || pathname === "/api/v1/health") {
+                if (!verifyBearerToken(req, token, verifyOptions)) {
+                    return new Response(JSON.stringify({
+                        ok: false,
+                        error: {
+                            code: UNAUTHORIZED,
+                            message: "Invalid or missing Bearer token",
+                        },
+                    }), {
+                        status: 401,
+                        headers: {
+                            "Content-Type": "application/json",
+                            ...corsHeaders,
+                        },
+                    });
+                }
+                return new Response(JSON.stringify({
+                    status: "ok",
+                    protocol: "mcp",
+                    version: ACTIONDOCK_VERSION,
+                    timestamp: new Date().toISOString(),
+                }), {
+                    status: 200,
+                    headers: {
+                        "Content-Type": "application/json",
+                        ...corsHeaders,
+                    },
+                });
+            }
+            // 2. Authentication check
+            if (!verifyBearerToken(req, token, verifyOptions)) {
+                return new Response(JSON.stringify({
+                    jsonrpc: "2.0",
+                    error: {
+                        code: -32000,
+                        message: "Unauthorized: Invalid or missing Bearer token",
+                    },
+                    id: null,
+                }), {
+                    status: 401,
+                    headers: {
+                        "Content-Type": "application/json",
+                        ...corsHeaders,
+                    },
+                });
+            }
+            // 3. Delegate MCP endpoint
+            if (pathname === "/mcp" || pathname === "/") {
+                const maxBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+                const contentLengthHeader = req.headers.get("content-length");
+                if (contentLengthHeader) {
+                    const parsedLength = parseInt(contentLengthHeader, 10);
+                    if (!isNaN(parsedLength) && parsedLength > maxBytes) {
+                        return new Response(JSON.stringify({
+                            ok: false,
+                            error: {
+                                code: "REQUEST_TOO_LARGE",
+                                message: "Request body exceeds maximum allowed size",
+                            },
+                        }), {
+                            status: 413,
+                            headers: {
+                                "Content-Type": "application/json",
+                                ...corsHeaders,
+                            },
+                        });
+                    }
+                }
+                let currentReq = req;
+                if (req.body && req.method !== "GET" && req.method !== "HEAD") {
+                    const reader = req.body.getReader();
+                    const chunks = [];
+                    let totalBytes = 0;
+                    let tooLarge = false;
+                    try {
+                        while (true) {
+                            const { done, value } = await reader.read();
+                            if (done)
+                                break;
+                            if (value) {
+                                totalBytes += value.byteLength;
+                                if (totalBytes > maxBytes) {
+                                    tooLarge = true;
+                                    await reader.cancel();
+                                    break;
+                                }
+                                chunks.push(value);
+                            }
+                        }
+                    }
+                    finally {
+                        reader.releaseLock();
+                    }
+                    if (tooLarge) {
+                        return new Response(JSON.stringify({
+                            ok: false,
+                            error: {
+                                code: "REQUEST_TOO_LARGE",
+                                message: "Request body exceeds maximum allowed size",
+                            },
+                        }), {
+                            status: 413,
+                            headers: {
+                                "Content-Type": "application/json",
+                                ...corsHeaders,
+                            },
+                        });
+                    }
+                    const merged = new Uint8Array(totalBytes);
+                    let offset = 0;
+                    for (const chunk of chunks) {
+                        merged.set(chunk, offset);
+                        offset += chunk.byteLength;
+                    }
+                    currentReq = new Request(req.url, {
+                        method: req.method,
+                        headers: req.headers,
+                        body: merged,
+                        signal: req.signal,
+                    });
+                }
+                const mcpResponse = await handler.fetch(currentReq);
+                if (Object.keys(corsHeaders).length > 0) {
+                    const newHeaders = new Headers(mcpResponse.headers);
+                    for (const [k, v] of Object.entries(corsHeaders)) {
+                        newHeaders.set(k, String(v));
+                    }
+                    return new Response(mcpResponse.body, {
+                        status: mcpResponse.status,
+                        statusText: mcpResponse.statusText,
+                        headers: newHeaders,
+                    });
+                }
+                return mcpResponse;
+            }
+            return new Response(JSON.stringify({
+                error: "Not Found",
+            }), {
+                status: 404,
+                headers: {
+                    "Content-Type": "application/json",
+                    ...corsHeaders,
+                },
+            });
+        });
+        if (server.ready) {
+            await server.ready;
+        }
+        const actualHost = host === "0.0.0.0" ? "127.0.0.1" : host;
+        const url = `http://${formatHostForUrl(actualHost)}:${server.port}`;
+        return {
+            port: server.port ?? port,
+            host,
+            url,
+            target,
+            stop: async () => {
+                let targetError;
+                try {
+                    await target.close();
+                }
+                catch (err) {
+                    targetError = err;
+                }
+                try {
+                    await server.stop(true);
+                }
+                catch (serverErr) {
+                    if (targetError) {
+                        throw new AggregateError([targetError, serverErr], "Failed to stop MCP HTTP server and target");
+                    }
+                    throw serverErr;
+                }
+                if (targetError) {
+                    throw targetError;
+                }
+            },
+        };
+    })();
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./schemas.js";
+export * from "./execution-mode.js";
+export * from "./adapter.js";
+export * from "./stdio.js";
+export * from "./http.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from "./types.js";
+export * from "./schemas.js";
+export * from "./execution-mode.js";
+export * from "./adapter.js";
+export * from "./stdio.js";
+export * from "./http.js";

package/dist/register-tasks-extension.d.ts

@@ -0,0 +1,9 @@
+import type { ActionDockTarget } from "@actiondock/core";
+import { McpServer } from "@modelcontextprotocol/server";
+/**
+ * 在低层 Server 实例上注册 tasks 能力声明与三个请求处理器。
+ *
+ * @param server MCP 高层服务实例
+ * @param target ActionDockTarget 公共契约门面
+ */
+export declare function registerTasksExtension(server: McpServer, target: ActionDockTarget): void;

package/dist/register-tasks-extension.js

@@ -0,0 +1,69 @@
+import { fromJsonSchema } from "@modelcontextprotocol/server";
+import { toMcpTaskPayload, toMcpTaskStatus } from "./types.js";
+const TASK_ID_PARAMS = fromJsonSchema({
+    type: "object",
+    properties: {
+        taskId: { type: "string" },
+        reason: { type: "string" },
+    },
+    required: ["taskId"],
+});
+const TASK_LIST_PARAMS = fromJsonSchema({
+    type: "object",
+    properties: {
+        limit: { type: "number" },
+        actionId: { type: "string" },
+    },
+});
+/**
+ * 将内部 RunRecord 的 ISO 时间字符串转为毫秒时间戳，用于任务排序比较。
+ *
+ * @param value 待解析的时间字符串
+ */
+function toTimeMillis(value) {
+    const parsed = Date.parse(value);
+    return Number.isNaN(parsed) ? 0 : parsed;
+}
+/**
+ * 在低层 Server 实例上注册 tasks 能力声明与三个请求处理器。
+ *
+ * @param server MCP 高层服务实例
+ * @param target ActionDockTarget 公共契约门面
+ */
+export function registerTasksExtension(server, target) {
+    server.server.registerCapabilities({
+        tasks: {
+            list: {},
+            cancel: {},
+        },
+    });
+    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`);
+        }
+        return { task: toMcpTaskPayload(run) };
+    });
+    server.server.setRequestHandler("tasks/cancel", { params: TASK_ID_PARAMS }, async (params) => {
+        const reason = params.reason || "Cancelled via MCP tasks/cancel";
+        const cancelRes = await target.cancelRun(params.taskId, reason);
+        if (cancelRes.outcome === "requested") {
+            return { taskId: params.taskId, status: "cancelled" };
+        }
+        if (cancelRes.outcome === "already_terminal") {
+            return { taskId: params.taskId, status: toMcpTaskStatus(cancelRes.status) };
+        }
+        const run = await target.getRun(params.taskId);
+        if (!run) {
+            throw new Error(`Task '${params.taskId}' not found`);
+        }
+        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;
+        const actionId = params.actionId;
+        const runs = await target.listRuns({ limit, actionId });
+        const ordered = [...runs].sort((a, b) => toTimeMillis(b.startedAt) - toTimeMillis(a.startedAt));
+        return { tasks: ordered.slice(0, limit).map(toMcpTaskPayload) };
+    });
+}

package/dist/schemas.d.ts

@@ -0,0 +1,6 @@
+import type { JsonSchema } from "@actiondock/sdk";
+/**
+ * 将 ActionDock 标准 JSON Schema 归一化为 MCP 标准 Tool Schema。
+ * 布尔分支已穷尽（true / false / 对象），无其余可达路径。
+ */
+export declare function toMcpSchema(schema?: JsonSchema): import("@modelcontextprotocol/server").StandardSchemaWithJSON<unknown, unknown>;

package/dist/schemas.js

@@ -0,0 +1,30 @@
+import { fromJsonSchema } from "@modelcontextprotocol/server";
+/**
+ * 将 ActionDock 标准 JSON Schema 归一化为 MCP 标准 Tool Schema。
+ * 布尔分支已穷尽（true / false / 对象），无其余可达路径。
+ */
+export function toMcpSchema(schema) {
+    if (schema === undefined || schema === true) {
+        return fromJsonSchema({});
+    }
+    if (schema === false) {
+        return fromJsonSchema({
+            not: {},
+        });
+    }
+    // JSON Schema 为纯数据结构，structuredClone 深拷贝避免污染调用方原始定义；布尔分支已穷尽，收窄为对象模式
+    const cloned = structuredClone(schema);
+    const properties = (cloned.properties ?? {});
+    if (cloned.type === "object" || cloned.properties) {
+        cloned.properties = properties;
+        properties.execution = {
+            type: "object",
+            description: "Execution options",
+            properties: {
+                mode: { type: "string", enum: ["sync", "async"] },
+                timeoutMs: { type: "number" },
+            },
+        };
+    }
+    return fromJsonSchema(cloned);
+}

package/dist/stdio-host.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

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

@@ -0,0 +1,10 @@
+import type { ActionDockMcpOptions } from "./types.js";
+/**
+ * 启动 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

@@ -0,0 +1,99 @@
+import type { ActionDockApp, ActionDockHost, ActionDockTarget, RuntimeStorage } from "@actiondock/core";
+import type { ActionDefinition, RunRecord, RunStatus } from "@actiondock/sdk";
+/**
+ * MCP 任务状态枚举（兼容 Model Context Protocol Task 规范）。
+ */
+export type McpTaskStatus = "working" | "completed" | "failed" | "cancelled";
+/**
+ * MCP 任务状态数据载荷结构体。
+ */
+export interface McpTaskPayload {
+    taskId: string;
+    status: McpTaskStatus;
+    createdAt: string;
+    finishedAt?: string;
+    input?: unknown;
+    output?: unknown;
+    error?: unknown;
+}
+/**
+ * 将 ActionDock 内部的 RunStatus 转换为 MCP 标准的 TaskStatus。
+ */
+export declare function toMcpTaskStatus(status: RunStatus): McpTaskStatus;
+/**
+ * 将内部 RunRecord 实体转换为向 MCP 客户端暴露的 McpTaskPayload。
+ */
+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;
+    /** 多个项目根目录（用于多包聚合提供） */
+    projectRoots?: string[];
+    /** 目标 Package ID */
+    packageId?: string;
+    /** 多个 Package ID 列表 */
+    packageIds?: string[];
+    /** 是否聚合暴露全局 Registry 中的所有 Package */
+    all?: boolean;
+    /** 自定义家目录路径 */
+    customHome?: string;
+    /** 配置动态覆盖项 */
+    configOverrides?: Record<string, unknown>;
+    /** 单个 Tool 执行超时时间（毫秒） */
+    timeoutMs?: number;
+    /** 预加载的 Action 集合（单元测试或内存模式使用） */
+    actions?: Map<string, ActionDefinition> | Array<{
+        id: string;
+        action: ActionDefinition;
+    } | (ActionDefinition & {
+        id: string;
+    })> | Record<string, ActionDefinition>;
+    /** 底层存储实例（单元测试或特定场景注入） */
+    storage?: RuntimeStorage;
+    /**
+     * 是否由适配层接管外部注入 storage 的生命周期。
+     * 默认 false：外部注入的 storage 由注入方自行管理，适配层不具各 close 语义；
+     * 置为 true 时透传原始实例，随 target.close() 级联关闭。
+     */
+    ownStorageLifecycle?: boolean;
+    /**
+     * 实例 close 是否级联关闭 target 门面。
+     * 默认 false：适配层产物可能被 SDK 传输层按请求（或按连接）创建与销毁，
+     * 级联语义会误杀共享 target，生命周期统一由外层入口的 stop/cleanup 收敛；
+     * 仅在调用方自行持有实例并需要一次 close 同时释放 target 时置 true。
+     */
+    cascadeTargetClose?: boolean;
+}
+/**
+ * HTTP 传输协议安全配置项。
+ */
+export interface HttpSecurityOptions {
+    host?: string;
+    port?: number;
+    token?: string;
+    allowInsecureNoAuth?: boolean;
+    allowQueryToken?: boolean;
+    allowInsecureHttp?: boolean;
+    corsOrigins?: string[];
+    maxBodyBytes?: number;
+}
+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,
+    };
+}