@actiondock/mcp 2.0.12 → 2.2.1

package/README.md

@@ -2,7 +2,7 @@
 
 ActionDock 2.0 模型上下文协议适配器。
 
-[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D22-green?logo=node.js)](https://nodejs.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D24.12.0-green?logo=node.js)](https://nodejs.org/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue?logo=typescript)](https://www.typescriptlang.org/)
 [![MCP](https://img.shields.io/badge/MCP-Protocol%20Compliant-purple)](https://modelcontextprotocol.io/)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
@@ -15,12 +15,12 @@ ActionDock 2.0 模型上下文协议适配器。
 
 ### 双协议传输通道
 
-- **STDIO 标准输入输出通道**：专为本地客户端（如 Claude Code、Cursor、Windsurf 等开发工具）设计，直接通过子进程标准流双向通信，安全且免配置端口。
-- **HTTP 传输通道**：专为远程服务与容器化部署设计，基于 Web 标准请求与响应实现流式传输，支持跨域策略配置与鉴权令牌校验。
+- STDIO 标准输入输出通道：专为本地客户端设计，直接通过子进程标准流双向通信，安全且免配置端口。
+- HTTP 传输通道：专为远程服务与容器化部署设计，基于 Web 标准请求与响应实现流式传输，支持跨域策略配置与鉴权令牌校验。
 
 ### 工具模式自动转换
 
-- 自动解析每个 Action 的 `inputSchema` 与 `outputSchema`，转换为标准 MCP Tool 契约。
+- 自动解析每个 Action 的模式规范，转换为标准 MCP Tool 契约。
 - 智能处理多包聚合场景下的动作标识冲突，自动使用包命名空间前缀消除歧义。
 - 严格遵循输入格式校验，在参数违规时向模型返回结构化诊断提示。
 - 执行结果自动封装为包含文本内容块与结构化数据的 MCP 格式信封，并在异常时正确标记错误标识。
@@ -28,16 +28,16 @@ ActionDock 2.0 模型上下文协议适配器。
 ### 协同取消信号向下传播
 
 - 当 MCP 客户端发起取消请求时，适配层自动捕获中断事件。
-- 取消信号直接传递至底层的 `ActionRunner` 调度器，并联动激活当前任务上下文中的 `ctx.signal`。
-- 业务代码可通过监听 `AbortSignal` 安全释放资源或提前终止执行。
+- 取消信号直接传递至底层的 ActionRunner 调度器，并联动激活当前任务上下文中的 `ctx.signal`。
+- 业务代码可通过监听 AbortSignal 安全释放资源或提前终止执行。
 
 ### Tasks 异步任务映射扩展
 
 针对长周期、重资源消耗的复杂任务，完整适配 MCP Tasks 异步协议扩展：
 
-- **任务状态查询**：通过 `tasks/get` 端点根据任务标识检索当前运行状态、执行进度与部分输出快照。
-- **任务主动取消**：通过 `tasks/cancel` 端点向正在后台执行的长周期任务发出中止指令。
-- **任务清单列举**：通过 `tasks/list` 端点批量查询当前会话及宿主下的活跃与历史任务列表。
+- 任务状态查询：通过 `tasks/get` 端点根据任务标识检索当前运行状态、执行进度与部分输出快照。
+- 任务主动取消：通过 `tasks/cancel` 端点向正在后台执行的长周期任务发出中止指令。
+- 任务清单列举：通过 `tasks/list` 端点批量查询当前会话及宿主下的活跃与历史任务列表。
 
 ---
 
@@ -50,7 +50,7 @@ ActionDock 2.0 模型上下文协议适配器。
 ad mcp
 
 # 以 HTTP 协议启动并在指定端口监听
-ad mcp --transport http --port 8080
+ad mcp serve --port 8080
 ```
 
 也可以在代码中通过编程方式创建适配器服务：

package/dist/adapter.d.ts

@@ -1,6 +1,7 @@
+import type { ActionDockApp, ActionDockHost, ActionDockTarget } from "@actiondock/core";
 import type { ExecutionResult } from "@actiondock/sdk";
 import { McpServer } from "@modelcontextprotocol/server";
-import { type ActionDockMcpOptions } from "./types";
+import type { ActionDockMcpOptions } from "./types.js";
 /**
  * 判断目标值是否为普通对象（Plain Object）。
  *
@@ -27,10 +28,24 @@ export declare function toMcpResult(result: ExecutionResult): {
     }[];
     structuredContent?: undefined;
 };
+/**
+ * 解析或基于选项创建底层 ActionDockTarget 统一门面。
+ */
+export declare function resolveTarget(options: ActionDockMcpOptions): Promise<{
+    target: ActionDockTarget;
+    ownsTarget: boolean;
+}>;
 export type ActionDockMcpServer = McpServer & {
     close: () => Promise<void>;
+    target: ActionDockTarget;
+    host?: ActionDockHost;
+    app?: ActionDockApp;
+    events?: (runId: string, options?: {
+        after?: number;
+        signal?: AbortSignal;
+    }) => AsyncIterable<Record<string, unknown>>;
 };
 /**
- * Creates and configures an McpServer instance bound to one or more ActionDock packages with Tasks extension support.
+ * 创建并配置基于 ActionDockTarget 的 McpServer 适配层实例。
  */
 export declare function createActionDockMcpServer(options?: ActionDockMcpOptions): Promise<ActionDockMcpServer>;

package/dist/adapter.js

@@ -0,0 +1,395 @@
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { ACTIONDOCK_VERSION, ActionResolver, createActionDockTarget, findProjectRoot, resolvePackageRoot, } from "@actiondock/core";
+import { McpServer } from "@modelcontextprotocol/server";
+import { registerTasksExtension } from "./register-tasks-extension.js";
+import { toMcpSchema } from "./schemas.js";
+import { isAsyncExecutionRequested, stripExecutionWrapper, } from "./execution-mode.js";
+/**
+ * 判断目标值是否为普通对象（Plain Object）。
+ *
+ * @param value 待检查的值
+ */
+export function isPlainObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/**
+ * 将 ActionDock 标准的 ExecutionResult 信封结构转换为 MCP 协议规范的 Tool Call 返回结果。
+ *
+ * @param result ExecutionResult 结果对象
+ */
+export function toMcpResult(result) {
+    if (result.ok) {
+        const structuredContent = isPlainObject(result.data)
+            ? result.data
+            : { value: result.data };
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(result),
+                },
+            ],
+            structuredContent,
+        };
+    }
+    return {
+        isError: true,
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(result),
+            },
+        ],
+    };
+}
+/** 适配层统一结构化错误码：MCP 工具名冲突。 */
+const MCP_TOOL_NAME_COLLISION = "MCP_TOOL_NAME_COLLISION";
+/**
+ * 构造外部注入 storage 的非接管视图。
+ *
+ * 默认（ownStorageLifecycle 为 false）时外部 storage 生命周期由注入方管理，
+ * 适配层仅委托读写而不接管关闭：所有成员函数与属性原样转发到原始实例并绑定原 this，
+ * 仅 close 收敛为显式声明的无操作边界，确保 target.close() 级联关闭时不会误伤外部实例。
+ *
+ * @param storage 外部注入的存储实例
+ */
+function createExternalStorageView(storage) {
+    return new Proxy(storage, {
+        get(target, prop) {
+            if (prop === "close") {
+                return () => undefined;
+            }
+            const value = Reflect.get(target, prop, target);
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+    });
+}
+/**
+ * 构造携带结构化错误码的工具名冲突异常。
+ *
+ * @param toolName 冲突的工具名
+ */
+function toolNameCollisionError(toolName) {
+    const err = new Error(`MCP tool name collision detected for tool '${toolName}'`);
+    err.code = MCP_TOOL_NAME_COLLISION;
+    return err;
+}
+/**
+ * 解析或基于选项创建底层 ActionDockTarget 统一门面。
+ */
+export async function resolveTarget(options) {
+    if (options.target) {
+        return { target: options.target, ownsTarget: false };
+    }
+    if (options.host) {
+        const target = await createActionDockTarget({ type: "local", host: options.host });
+        return { target, ownsTarget: false };
+    }
+    if (options.app) {
+        const target = await createActionDockTarget({ type: "local", app: options.app });
+        return { target, ownsTarget: false };
+    }
+    const packages = [];
+    // 外部注入的 storage 生命周期默认由注入方管理，适配层不伪造 close 语义；
+    // 仅当显式声明 ownStorageLifecycle 时才向包配置透传原始实例（随 target.close() 级联关闭）
+    // 外部注入的 storage 生命周期默认由注入方管理，适配层仅委托读写不接管关闭；
+    // 显式声明 ownStorageLifecycle 时透传原始实例，随 target.close() 级联关闭
+    const appStorage = options.storage
+        ? options.ownStorageLifecycle
+            ? options.storage
+            : createExternalStorageView(options.storage)
+        : undefined;
+    if (options.actions) {
+        packages.push({
+            projectConfig: {
+                id: options.packageId || "default",
+                name: options.packageId || "default",
+                version: ACTIONDOCK_VERSION,
+            },
+            actions: options.actions,
+            storage: appStorage,
+            inMemory: true,
+            customHome: options.customHome,
+            configOverrides: options.configOverrides,
+        });
+    }
+    if (options.projectRoots && options.projectRoots.length > 0) {
+        for (const root of options.projectRoots) {
+            const abs = resolve(root);
+            const detected = findProjectRoot(abs);
+            if (!detected) {
+                throw new Error(`Project root '${root}' is not a valid ActionDock package (actiondock.json not found)`);
+            }
+            packages.push({
+                packageRoot: detected,
+                storage: appStorage,
+                customHome: options.customHome,
+                configOverrides: options.configOverrides,
+            });
+        }
+    }
+    if (options.packageIds && options.packageIds.length > 0) {
+        for (const pkgId of options.packageIds) {
+            const root = resolvePackageRoot(pkgId, undefined, options.customHome);
+            if (!root || !existsSync(root)) {
+                throw new Error(`Package '${pkgId}' not found in registry`);
+            }
+            packages.push({
+                packageRoot: root,
+                storage: appStorage,
+                customHome: options.customHome,
+                configOverrides: options.configOverrides,
+            });
+        }
+    }
+    let projectRoot = options.projectRoot;
+    if (options.projectRoot) {
+        const abs = resolve(options.projectRoot);
+        const detected = findProjectRoot(abs);
+        if (!detected) {
+            throw new Error(`Project root '${options.projectRoot}' is not a valid ActionDock package (actiondock.json not found)`);
+        }
+        projectRoot = detected;
+    }
+    if (!projectRoot &&
+        packages.length === 0 &&
+        !options.all &&
+        !options.packageId) {
+        const currentRoot = findProjectRoot(process.cwd());
+        if (!currentRoot) {
+            throw new Error("No ActionDock project root found. Run inside an ActionDock package or specify --dir / --package / --all.");
+        }
+        projectRoot = currentRoot;
+    }
+    if (options.packageId && !options.actions && packages.length === 0) {
+        const root = resolvePackageRoot(options.packageId, undefined, options.customHome);
+        if (!root || !existsSync(root)) {
+            throw new Error(`Package '${options.packageId}' not found in registry`);
+        }
+        packages.push({
+            packageRoot: root,
+            customHome: options.customHome,
+            configOverrides: options.configOverrides,
+        });
+    }
+    const target = await createActionDockTarget({
+        type: "local",
+        projectRoot,
+        packages: packages.length > 0 ? packages : undefined,
+        scanLinkedPackages: Boolean(options.all),
+        hostOptions: {
+            autoLoadCurrentProject: packages.length === 0,
+        },
+        customHome: options.customHome,
+    });
+    return { target, ownsTarget: true };
+}
+/**
+ * 创建并配置基于 ActionDockTarget 的 McpServer 适配层实例。
+ */
+export async function createActionDockMcpServer(options = {}) {
+    const { target } = await resolveTarget(options);
+    let serverName = "actiondock";
+    let serverVersion = ACTIONDOCK_VERSION;
+    try {
+        const info = await target.info();
+        if (info) {
+            serverName = info.name || info.id || "actiondock";
+            serverVersion = info.protocolVersion || ACTIONDOCK_VERSION;
+            if (info.packages && info.packages.length === 1) {
+                serverName = info.packages[0].name || info.packages[0].id || serverName;
+                serverVersion = info.packages[0].version || serverVersion;
+            }
+        }
+    }
+    catch {
+        // 忽略元数据读取失败，使用默认值
+    }
+    const server = new McpServer({
+        name: serverName,
+        version: serverVersion,
+    });
+    // 任务规范扩展注册集中隔离在独立模块，本层不再直接操作 SDK 内层实例
+    registerTasksExtension(server, target);
+    // 工具注册与模式映射：tools/list 纯粹委托 target.listActions()
+    const actions = await target.listActions();
+    // 统计 Action 基础 ID 出现频次，用于同名冲突命名空间隔离
+    const baseCounts = new Map();
+    for (const act of actions) {
+        let baseId = act.id;
+        if (act.id.includes("/")) {
+            try {
+                const parsed = ActionResolver.parseRef(act.id);
+                baseId = parsed.actionId;
+            }
+            catch {
+                const idx = act.id.lastIndexOf("/");
+                baseId = act.id.slice(idx + 1);
+            }
+        }
+        baseCounts.set(baseId, (baseCounts.get(baseId) || 0) + 1);
+    }
+    const registeredToolNames = new Set();
+    for (const action of actions) {
+        let baseId = action.id;
+        let packageId = action.packageId;
+        if (action.id.includes("/")) {
+            try {
+                const parsed = ActionResolver.parseRef(action.id);
+                packageId = parsed.packageId || packageId;
+                baseId = parsed.actionId;
+            }
+            catch {
+                const idx = action.id.lastIndexOf("/");
+                packageId = packageId || action.id.slice(0, idx);
+                baseId = action.id.slice(idx + 1);
+            }
+        }
+        const count = baseCounts.get(baseId) || 1;
+        let toolName = baseId;
+        if (count > 1 && packageId) {
+            const cleanPkgId = packageId.replace(/^@/, "").replace(/[^a-zA-Z0-9_-]+/g, "_");
+            toolName = `${cleanPkgId}_${baseId}`;
+        }
+        else if (toolName.includes("/") && packageId) {
+            const cleanPkgId = packageId.replace(/^@/, "").replace(/[^a-zA-Z0-9_-]+/g, "_");
+            toolName = `${cleanPkgId}_${baseId}`;
+        }
+        if (toolName.length > 64) {
+            const hash = createHash("sha256").update(toolName).digest("hex").slice(0, 8);
+            toolName = `${toolName.slice(0, 55)}_${hash}`;
+        }
+        if (registeredToolNames.has(toolName)) {
+            throw toolNameCollisionError(toolName);
+        }
+        registeredToolNames.add(toolName);
+        const isMultiPackage = actions.some((a) => a.id.includes("/") || (a.packageId && a.packageId !== actions[0].packageId));
+        const description = isMultiPackage
+            ? `[${action.id}] ${action.description || ""}`.trim()
+            : action.description;
+        // 工具执行：tools/call 委托 target.runAction() 或 target.startAction()
+        server.registerTool(toolName, {
+            description,
+            inputSchema: toMcpSchema(action.inputSchema),
+            outputSchema: action.outputSchema ? toMcpSchema(action.outputSchema) : undefined,
+        }, async (input, ctx) => {
+            // 异步执行模式只认显式约定字段 execution.mode，旧版 __async 仅作只读兼容探测
+            const isAsync = isAsyncExecutionRequested(input);
+            const signal = ctx.mcpReq?.signal;
+            // 分发前仅剥离适配层注入的包装字段，业务自有字段（含名为 async 的入参）原样透传
+            const cleanInput = stripExecutionWrapper(input);
+            if (isAsync) {
+                const ticket = await target.startAction(action.id, cleanInput, {
+                    signal,
+                    timeoutMs: options.timeoutMs,
+                });
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                ok: true,
+                                runId: ticket.runId,
+                                taskId: ticket.runId,
+                                status: "running",
+                            }),
+                        },
+                    ],
+                };
+            }
+            const result = await target.runAction(action.id, cleanInput, {
+                signal,
+                timeoutMs: options.timeoutMs,
+            });
+            return toMcpResult(result);
+        });
+    }
+    // 任务规范映射（tasks/get、tasks/cancel、tasks/list）已收敛至 registerTasksExtension 隔离模块
+    // 资源与规程映射：规程映射为只读 MCP Resource 与 Prompt
+    try {
+        const playbooks = await target.listPlaybooks();
+        for (const pb of playbooks) {
+            server.registerResource(pb.id, `playbook://${pb.id}`, {
+                title: pb.id,
+                description: pb.description,
+                mimeType: "text/markdown",
+            }, async (uri) => {
+                const spec = await target.describePlaybook(pb.id);
+                return {
+                    contents: [
+                        {
+                            uri: uri.href,
+                            text: spec.content,
+                            mimeType: "text/markdown",
+                        },
+                    ],
+                };
+            });
+            server.registerPrompt(pb.id, {
+                title: pb.id,
+                description: pb.description,
+            }, async () => {
+                const spec = await target.describePlaybook(pb.id);
+                return {
+                    messages: [
+                        {
+                            role: "user",
+                            content: {
+                                type: "text",
+                                text: spec.content,
+                            },
+                        },
+                    ],
+                };
+            });
+        }
+    }
+    catch {
+        // 忽略规程获取或注册异常
+    }
+    // 服务生命周期：默认 close 仅关闭 MCP 服务本身，不级联 target——
+    // SDK 传输层（HTTP 每请求 / stdio 探测回落）会销毁工厂产物，若 close 级联会误杀共享 target；
+    // 需要「一次 close 同时释放 target」的独立持有方显式传 cascadeTargetClose
+    const originalClose = server.close.bind(server);
+    let isClosed = false;
+    const closeFn = async () => {
+        if (isClosed)
+            return;
+        isClosed = true;
+        // 清理异常不吞没：先关服务再级联目标，server 关闭失败也继续释放 target 并聚合上抛
+        let closeError;
+        try {
+            await originalClose();
+        }
+        catch (err) {
+            closeError = err;
+        }
+        if (options.cascadeTargetClose) {
+            try {
+                await target.close();
+            }
+            catch (err) {
+                if (closeError !== undefined) {
+                    throw new AggregateError([closeError, err], "Failed to close MCP server and target");
+                }
+                throw err;
+            }
+        }
+        if (closeError !== undefined) {
+            throw closeError;
+        }
+    };
+    const decorated = server;
+    decorated.close = closeFn;
+    decorated.target = target;
+    decorated.host = options.host;
+    decorated.app = options.app;
+    decorated.events = (runId, opts) => target.events(runId, opts);
+    return decorated;
+}

package/dist/execution-mode.d.ts

@@ -0,0 +1,30 @@
+/**
+ * MCP 工具调用的异步执行模式探测与包装字段剥离。
+ *
+ * 单一显式约定：异步执行模式只认 input.execution.mode === "async"。
+ * 旧版魔法字段（__async 布尔）保留只读兼容探测，但不再参与 schema 注入，
+ * 也不再吞没业务自有的 async 入参字段：
+ * - 探测阶段仅读取 execution.mode 与 __async，语义不变；
+ * - 剥离阶段仅删除适配层实际注入的包装字段 execution 与 __async，
+ *   名为 async 的业务字段原样透传给 Action。
+ *
+ * 保留命名空间权衡：`execution` 与 `__async` 是适配层声明的前缀保留字段；
+ * 业务 Action 入参若恰好撞名 `__async: true`，会被误判为异步意图并在转发前剥离。
+ * 这是旧版兼容通道的已知代价，新代码统一使用 execution.mode 声明异步，
+ * 业务字段命名应避开该前缀保留命名空间。
+ */
+/**
+ * 从工具调用入参中提取显式声明的异步执行模式。
+ *
+ * @param input 工具调用入参
+ * @returns 是否显式声明了异步执行（execution.mode 为 async，或旧版 __async 为 true）
+ */
+export declare function isAsyncExecutionRequested(input: unknown): boolean;
+/**
+ * 剥离适配层注入的执行控制包装字段，返回纯净的业务入参。
+ *
+ * 仅删除 WRAPPER_KEYS 中声明的包装字段；业务自有字段（含名为 async 的入参）原样保留。
+ *
+ * @param input 工具调用入参
+ */
+export declare function stripExecutionWrapper<T>(input: T): T;

package/dist/execution-mode.js

@@ -0,0 +1,63 @@
+/**
+ * MCP 工具调用的异步执行模式探测与包装字段剥离。
+ *
+ * 单一显式约定：异步执行模式只认 input.execution.mode === "async"。
+ * 旧版魔法字段（__async 布尔）保留只读兼容探测，但不再参与 schema 注入，
+ * 也不再吞没业务自有的 async 入参字段：
+ * - 探测阶段仅读取 execution.mode 与 __async，语义不变；
+ * - 剥离阶段仅删除适配层实际注入的包装字段 execution 与 __async，
+ *   名为 async 的业务字段原样透传给 Action。
+ *
+ * 保留命名空间权衡：`execution` 与 `__async` 是适配层声明的前缀保留字段；
+ * 业务 Action 入参若恰好撞名 `__async: true`，会被误判为异步意图并在转发前剥离。
+ * 这是旧版兼容通道的已知代价，新代码统一使用 execution.mode 声明异步，
+ * 业务字段命名应避开该前缀保留命名空间。
+ */
+/** 适配层注入到工具 schema 的执行控制包装字段名集合。 */
+const WRAPPER_KEYS = ["execution", "__async"];
+/**
+ * 从工具调用入参中提取显式声明的异步执行模式。
+ *
+ * @param input 工具调用入参
+ * @returns 是否显式声明了异步执行（execution.mode 为 async，或旧版 __async 为 true）
+ */
+export function isAsyncExecutionRequested(input) {
+    if (typeof input !== "object" || input === null || Array.isArray(input)) {
+        return false;
+    }
+    const record = input;
+    const execution = record.execution;
+    if (typeof execution === "object" &&
+        execution !== null &&
+        !Array.isArray(execution) &&
+        execution.mode === "async") {
+        return true;
+    }
+    // 旧版魔法字段兼容探测：仅只读，不再注入 schema 也不再参与剥离以外的影响
+    if (record.__async === true)
+        return true;
+    return false;
+}
+/**
+ * 剥离适配层注入的执行控制包装字段，返回纯净的业务入参。
+ *
+ * 仅删除 WRAPPER_KEYS 中声明的包装字段；业务自有字段（含名为 async 的入参）原样保留。
+ *
+ * @param input 工具调用入参
+ */
+export function stripExecutionWrapper(input) {
+    if (typeof input !== "object" || input === null || Array.isArray(input)) {
+        return input;
+    }
+    const record = input;
+    const hasWrapper = WRAPPER_KEYS.some((key) => key in record);
+    if (!hasWrapper)
+        return input;
+    const rest = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (WRAPPER_KEYS.includes(key))
+            continue;
+        rest[key] = value;
+    }
+    return rest;
+}

package/dist/http.d.ts

@@ -1,4 +1,4 @@
-import type { ActionDockMcpHttpOptions, ActionDockMcpHttpServerInstance } from "./types";
+import type { ActionDockMcpHttpOptions, ActionDockMcpHttpServerInstance } from "./types.js";
 /**
  * Starts an ActionDock MCP server over HTTP transport.
  */