@actiondock/mcp 2.0.11 → 2.0.12

package/dist/adapter.d.ts

@@ -0,0 +1,36 @@
+import type { ExecutionResult } from "@actiondock/sdk";
+import { McpServer } from "@modelcontextprotocol/server";
+import { type ActionDockMcpOptions } from "./types";
+/**
+ * 判断目标值是否为普通对象（Plain Object）。
+ *
+ * @param value 待检查的值
+ */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * 将 ActionDock 标准的 ExecutionResult 信封结构转换为 MCP 协议规范的 Tool Call 返回结果。
+ *
+ * @param result ExecutionResult 结果对象
+ */
+export declare function toMcpResult(result: ExecutionResult): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: Record<string, unknown>;
+    isError?: undefined;
+} | {
+    isError: boolean;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent?: undefined;
+};
+export type ActionDockMcpServer = McpServer & {
+    close: () => Promise<void>;
+};
+/**
+ * Creates and configures an McpServer instance bound to one or more ActionDock packages with Tasks extension support.
+ */
+export declare function createActionDockMcpServer(options?: ActionDockMcpOptions): Promise<ActionDockMcpServer>;

package/dist/http.d.ts

@@ -0,0 +1,5 @@
+import type { ActionDockMcpHttpOptions, ActionDockMcpHttpServerInstance } from "./types";
+/**
+ * Starts an ActionDock MCP server over HTTP transport.
+ */
+export declare function startMcpHttpServer(options?: ActionDockMcpHttpOptions): Promise<ActionDockMcpHttpServerInstance>;

package/dist/index.js

@@ -0,0 +1,574 @@
+// packages/mcp/src/types.ts
+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";
+  }
+}
+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
+  };
+}
+// packages/mcp/src/schemas.ts
+import { fromJsonSchema } from "@modelcontextprotocol/server";
+function toMcpSchema(schema) {
+  if (schema === undefined || schema === true) {
+    return fromJsonSchema({});
+  }
+  if (schema === false) {
+    return fromJsonSchema({
+      not: {}
+    });
+  }
+  if (typeof schema === "object" && schema !== null) {
+    const cloned = JSON.parse(JSON.stringify(schema));
+    if (cloned.type === "object" || cloned.properties) {
+      cloned.properties = cloned.properties || {};
+      cloned.properties.__async = { type: "boolean", description: "Execute action asynchronously" };
+      cloned.properties.execution = {
+        type: "object",
+        description: "Execution options",
+        properties: {
+          mode: { type: "string", enum: ["sync", "async"] },
+          timeoutMs: { type: "number" }
+        }
+      };
+    }
+    return fromJsonSchema(cloned);
+  }
+  return fromJsonSchema(schema);
+}
+// packages/mcp/src/adapter.ts
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import {
+  ACTIONDOCK_VERSION,
+  ensureDependencyClosure,
+  findProjectRoot,
+  listLinkedPackages,
+  loadActions,
+  loadProjectConfig,
+  resolvePackageRoot,
+  ServerRuntimeRegistry
+} from "@actiondock/core";
+import { McpServer } from "@modelcontextprotocol/server";
+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;
+}
+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)
+      }
+    ]
+  };
+}
+function createMcpToolCallback(executionService, actionId, timeoutMs) {
+  return async (input, ctx) => {
+    const isAsync = Boolean(input && typeof input === "object" && (input.execution?.mode === "async" || input.__async === true || input.async === true));
+    const signal = ctx.mcpReq?.signal;
+    let cleanInput = input;
+    if (input && typeof input === "object" && !Array.isArray(input)) {
+      const { execution, __async, async: _async, ...rest } = input;
+      cleanInput = rest;
+    }
+    if (isAsync) {
+      const ticket = await executionService.start(actionId, cleanInput, {
+        signal,
+        timeoutMs
+      });
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              ok: true,
+              runId: ticket.runId,
+              taskId: ticket.runId,
+              status: "running"
+            })
+          }
+        ]
+      };
+    }
+    const result = await executionService.execute(actionId, cleanInput, {
+      signal,
+      timeoutMs
+    });
+    return toMcpResult(result);
+  };
+}
+async function createActionDockMcpServer(options = {}) {
+  const targetRoots = [];
+  if (options.projectRoot) {
+    targetRoots.push(options.projectRoot);
+  }
+  if (options.projectRoots) {
+    targetRoots.push(...options.projectRoots);
+  }
+  const targetPackages = [];
+  if (options.packageId) {
+    targetPackages.push(options.packageId);
+  }
+  if (options.packageIds) {
+    targetPackages.push(...options.packageIds);
+  }
+  const resolvedRoots = new Set;
+  if (options.all) {
+    const linked = listLinkedPackages(options.customHome);
+    for (const pkg of linked) {
+      if (existsSync(pkg.path)) {
+        resolvedRoots.add(resolve(pkg.path));
+      }
+    }
+    const currentRoot = findProjectRoot(process.cwd());
+    if (currentRoot) {
+      resolvedRoots.add(resolve(currentRoot));
+    }
+  }
+  for (const pkgId of targetPackages) {
+    const root = resolvePackageRoot(pkgId, undefined, options.customHome);
+    if (!root || !existsSync(root)) {
+      throw new Error(`Package '${pkgId}' not found in registry`);
+    }
+    resolvedRoots.add(resolve(root));
+  }
+  for (const dir of targetRoots) {
+    const absPath = resolve(dir);
+    const root = findProjectRoot(absPath);
+    if (!root) {
+      throw new Error(`Project root '${dir}' is not a valid ActionDock package (actiondock.json not found)`);
+    }
+    resolvedRoots.add(resolve(root));
+  }
+  if (resolvedRoots.size === 0 && !options.all) {
+    const currentRoot = findProjectRoot(process.cwd());
+    if (currentRoot) {
+      resolvedRoots.add(resolve(currentRoot));
+    }
+  }
+  const isInternalRegistry = !options.runtimeRegistry;
+  const runtimeRegistry = options.runtimeRegistry ?? new ServerRuntimeRegistry(options.customHome);
+  const executionManager = options.executionManager ?? runtimeRegistry.executionManager;
+  const targets = [];
+  if (resolvedRoots.size === 0 && options.actions) {
+    const dummyConfig = {
+      id: "virtual",
+      name: "Virtual Package",
+      version: ACTIONDOCK_VERSION,
+      description: "In-memory virtual package",
+      actionsDir: "actions",
+      playbooksDir: "playbooks"
+    };
+    const storage = options.storage ?? runtimeRegistry.getStorage("virtual");
+    const executionService = runtimeRegistry.getExecutionService("virtual", undefined, dummyConfig, {
+      storage,
+      actions: options.actions,
+      configOverrides: options.configOverrides
+    });
+    targets.push({
+      projectRoot: "virtual",
+      config: dummyConfig,
+      actions: options.actions,
+      storage,
+      executionService
+    });
+  } else {
+    if (resolvedRoots.size === 0) {
+      throw new Error("No ActionDock project root found. Run inside an ActionDock package or specify --dir / --package / --all.");
+    }
+    await ensureDependencyClosure(Array.from(resolvedRoots), {
+      customHome: options.customHome
+    });
+    for (const root of resolvedRoots) {
+      const projectConfig = loadProjectConfig(root);
+      const actions = options.actions && resolvedRoots.size === 1 ? options.actions : await loadActions(root, projectConfig.actionsDir, { autoInstall: false });
+      const storage = options.storage && resolvedRoots.size === 1 ? options.storage : runtimeRegistry.getStorage(projectConfig.id, root);
+      const executionService = runtimeRegistry.getExecutionService(projectConfig.id, root, projectConfig, {
+        storage,
+        actions,
+        configOverrides: options.configOverrides
+      });
+      targets.push({
+        projectRoot: root,
+        config: projectConfig,
+        actions,
+        storage,
+        executionService
+      });
+    }
+  }
+  const isMultiPackage = targets.length > 1;
+  const actionIdCounts = new Map;
+  for (const target of targets) {
+    for (const actionId of target.actions.keys()) {
+      actionIdCounts.set(actionId, (actionIdCounts.get(actionId) || 0) + 1);
+    }
+  }
+  const serverName = targets.length === 1 ? targets[0].config.id || targets[0].config.name || "actiondock" : "actiondock";
+  const serverVersion = targets.length === 1 ? targets[0].config.version || ACTIONDOCK_VERSION : ACTIONDOCK_VERSION;
+  const server = new McpServer({
+    name: serverName,
+    version: serverVersion
+  });
+  server.server.registerCapabilities({
+    tasks: {
+      listChanged: true,
+      cancel: {}
+    }
+  });
+  for (const target of targets) {
+    for (const action of target.actions.values()) {
+      const count = actionIdCounts.get(action.id) || 1;
+      const cleanPkgId = target.config.id.replace(/^@/, "").replace(/[^a-zA-Z0-9_-]+/g, "_");
+      let toolName = count > 1 ? `${cleanPkgId}_${action.id}` : action.id;
+      if (toolName.length > 64) {
+        const hash = createHash("sha256").update(toolName).digest("hex").slice(0, 8);
+        toolName = `${toolName.slice(0, 55)}_${hash}`;
+      }
+      const description = isMultiPackage ? `[${target.config.id}] ${action.description || ""}` : action.description;
+      server.registerTool(toolName, {
+        description,
+        inputSchema: toMcpSchema(action.inputSchema),
+        outputSchema: action.outputSchema ? toMcpSchema(action.outputSchema) : undefined
+      }, createMcpToolCallback(target.executionService, action.id, options.timeoutMs));
+    }
+  }
+  const storages = targets.map((t) => t.storage);
+  server.server.setRequestHandler("tasks/get", async (req) => {
+    const taskId = req.params?.taskId;
+    if (!taskId) {
+      throw new Error("taskId parameter is required for tasks/get");
+    }
+    for (const storage of storages) {
+      const run = storage.getRun(taskId);
+      if (run) {
+        return {
+          task: toMcpTaskPayload(run)
+        };
+      }
+    }
+    throw new Error(`Task '${taskId}' not found`);
+  });
+  server.server.setRequestHandler("tasks/cancel", async (req) => {
+    const taskId = req.params?.taskId;
+    if (!taskId) {
+      throw new Error("taskId parameter is required for tasks/cancel");
+    }
+    for (const target of targets) {
+      const cancelRes = await target.executionService.cancel(taskId, req.params?.reason || "Cancelled via MCP tasks/cancel");
+      if (cancelRes.outcome === "requested") {
+        return {
+          taskId,
+          status: "cancelled"
+        };
+      }
+      if (cancelRes.outcome === "already_terminal") {
+        return {
+          taskId,
+          status: toMcpTaskStatus(cancelRes.status)
+        };
+      }
+    }
+    for (const storage of storages) {
+      const run = storage.getRun(taskId);
+      if (run) {
+        if (run.status === "running") {
+          storage.updateRun(taskId, "cancelled", undefined, {
+            code: "ACTION_CANCELLED",
+            message: req.params?.reason || "Cancelled via MCP tasks/cancel"
+          });
+          return {
+            taskId,
+            status: "cancelled"
+          };
+        }
+        return {
+          taskId,
+          status: toMcpTaskStatus(run.status)
+        };
+      }
+    }
+    throw new Error(`Task '${taskId}' not found`);
+  });
+  server.server.setRequestHandler("tasks/list", async (req) => {
+    const limit = typeof req.params?.limit === "number" ? req.params.limit : 50;
+    const actionId = req.params?.actionId;
+    const allRuns = [];
+    for (const storage of storages) {
+      const runs = storage.listRuns({ limit, actionId });
+      allRuns.push(...runs);
+    }
+    allRuns.sort((a, b) => new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime());
+    const trimmed = allRuns.slice(0, limit);
+    return {
+      tasks: trimmed.map(toMcpTaskPayload)
+    };
+  });
+  const originalClose = server.close.bind(server);
+  let isClosed = false;
+  const closeFn = async () => {
+    if (isClosed)
+      return;
+    isClosed = true;
+    process.removeListener("exit", onProcessExit);
+    if (isInternalRegistry) {
+      for (const target of targets) {
+        if (target.storage !== options.storage) {
+          try {
+            target.storage.close();
+          } catch {}
+        }
+      }
+      try {
+        await runtimeRegistry.close();
+      } catch {}
+    }
+    try {
+      await originalClose();
+    } catch {}
+  };
+  const onProcessExit = () => {
+    if (isInternalRegistry) {
+      for (const target of targets) {
+        if (target.storage !== options.storage) {
+          try {
+            target.storage.close();
+          } catch {}
+        }
+      }
+      try {
+        runtimeRegistry.close();
+      } catch {}
+    }
+  };
+  process.once("exit", onProcessExit);
+  server.close = closeFn;
+  return server;
+}
+// packages/mcp/src/stdio.ts
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+async function startMcpStdio(options = {}) {
+  let activeServer;
+  const stdioHandler = serveStdio(async () => {
+    const server = await createActionDockMcpServer(options);
+    activeServer = server;
+    return server;
+  }, {
+    onerror: (err) => {
+      process.stderr.write(`[MCP Error] ${err?.message || String(err)}
+`);
+    }
+  });
+  const cleanup = async () => {
+    if (activeServer) {
+      try {
+        await activeServer.close();
+      } catch {}
+    }
+  };
+  process.once("SIGINT", async () => {
+    await cleanup();
+    try {
+      await stdioHandler.close();
+    } catch {}
+    process.exit(0);
+  });
+  process.once("SIGTERM", async () => {
+    await cleanup();
+    try {
+      await stdioHandler.close();
+    } catch {}
+    process.exit(0);
+  });
+}
+// packages/mcp/src/http.ts
+import {
+  ACTIONDOCK_VERSION as ACTIONDOCK_VERSION2,
+  isLoopbackHost,
+  launchHttpServer,
+  resolveCorsHeaders,
+  ServerRuntimeRegistry as ServerRuntimeRegistry2,
+  verifyBearerToken
+} from "@actiondock/core";
+import { createMcpHandler } from "@modelcontextprotocol/server";
+function startMcpHttpServer(options = {}) {
+  const port = options.port ?? 5178;
+  const host = options.host ?? "127.0.0.1";
+  const token = options.token;
+  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 () => {
+    const isInternalRegistry = !options.runtimeRegistry;
+    const runtimeRegistry = options.runtimeRegistry ?? new ServerRuntimeRegistry2(options.customHome);
+    const handler = createMcpHandler(() => {
+      return createActionDockMcpServer({
+        ...options,
+        runtimeRegistry,
+        executionManager: runtimeRegistry.executionManager
+      });
+    }, {
+      onerror: (err) => {
+        process.stderr.write(`[MCP HTTP Error] ${err?.message || String(err)}
+`);
+      }
+    });
+    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;
+      if (pathname === "/health" || pathname === "/api/v1/health") {
+        if (!verifyBearerToken(req, token)) {
+          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_VERSION2,
+          timestamp: new Date().toISOString()
+        }), {
+          status: 200,
+          headers: {
+            "Content-Type": "application/json",
+            ...corsHeaders
+          }
+        });
+      }
+      if (!verifyBearerToken(req, token)) {
+        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
+          }
+        });
+      }
+      if (pathname === "/mcp" || pathname === "/") {
+        const mcpResponse = await handler.fetch(req);
+        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
+        }
+      });
+    });
+    const actualHost = host === "0.0.0.0" ? "127.0.0.1" : host;
+    const url = `http://${actualHost}:${server.port}`;
+    return {
+      port: server.port ?? port,
+      host,
+      url,
+      stop: async () => {
+        let registryError;
+        if (isInternalRegistry) {
+          try {
+            await runtimeRegistry.close();
+          } catch (err) {
+            registryError = err;
+          }
+        }
+        try {
+          await server.stop(true);
+        } catch (serverErr) {
+          if (registryError) {
+            throw new AggregateError([registryError, serverErr], "Failed to stop MCP HTTP server and runtime registry");
+          }
+          throw serverErr;
+        }
+        if (registryError) {
+          throw registryError;
+        }
+      }
+    };
+  })();
+}
+export {
+  createActionDockMcpServer,
+  isPlainObject,
+  startMcpHttpServer,
+  startMcpStdio,
+  toMcpResult,
+  toMcpSchema,
+  toMcpTaskPayload,
+  toMcpTaskStatus
+};

package/dist/schemas.d.ts

@@ -0,0 +1,5 @@
+import type { JsonSchema } from "@actiondock/sdk";
+/**
+ * Normalizes an ActionDock JSON Schema into a standard MCP Tool Schema.
+ */
+export declare function toMcpSchema(schema?: JsonSchema): import("@modelcontextprotocol/server").StandardSchemaWithJSON<unknown, unknown>;

package/dist/stdio.d.ts

@@ -0,0 +1,5 @@
+import type { ActionDockMcpOptions } from "./types";
+/**
+ * Starts an ActionDock MCP server over STDIO transport.
+ */
+export declare function startMcpStdio(options?: ActionDockMcpOptions): Promise<void>;

package/dist/types.d.ts

@@ -0,0 +1,74 @@
+import type { ExecutionManager, RuntimeStorage, ServerRuntimeRegistry } 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 适配层初始化选项。
+ */
+export interface ActionDockMcpOptions {
+    /** 单个目标项目根目录 */
+    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>;
+    /** 底层存储实例 */
+    storage?: RuntimeStorage;
+    /** 服务端运行时注册表 */
+    runtimeRegistry?: ServerRuntimeRegistry;
+    /** 活跃执行任务管理器 */
+    executionManager?: ExecutionManager;
+}
+/**
+ * HTTP 传输协议安全配置项。
+ */
+export interface HttpSecurityOptions {
+    host?: string;
+    port?: number;
+    token?: string;
+    allowInsecureNoAuth?: boolean;
+    corsOrigins?: string[];
+    maxBodyBytes?: number;
+}
+export interface ActionDockMcpHttpOptions extends ActionDockMcpOptions, HttpSecurityOptions {
+}
+export interface ActionDockMcpHttpServerInstance {
+    port: number;
+    host: string;
+    url: string;
+    stop: () => Promise<void>;
+}