@actiondock/mcp 2.0.0

package/README.md

@@ -0,0 +1,43 @@
+# @actiondock/mcp
+
+Model Context Protocol (MCP) adapter for ActionDock 2.0.
+
+[![Bun](https://img.shields.io/badge/Bun-%3E%3D1.2-black?logo=bun)](https://bun.sh/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue?logo=typescript)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
+
+> **Runtime requirement**: [Bun](https://bun.sh/) >= 1.2.0 is required.
+
+`@actiondock/mcp` connects ActionDock Actions directly to the Model Context Protocol (MCP), exposing Actions as fully-typed MCP Tools over STDIO and HTTP transports.
+
+---
+
+## Installation
+
+```bash
+bun add @actiondock/mcp
+# or
+npm install @actiondock/mcp
+```
+
+---
+
+## Features
+
+- **STDIO & HTTP Transport**: Run locally via STDIO (for Claude Code, Cursor, Windsurf) or over HTTP with authentication and CORS.
+- **Dynamic Tool Mapping**: Automatically converts Action `inputSchema` / `outputSchema` into standard MCP Tool contracts.
+- **Cancellation Propagation**: Propagates MCP client cancellations directly to `ctx.signal` (`AbortSignal`).
+- **Tasks Extension**: Supports asynchronous background tool calls via MCP Tasks extension (`tasks/get`, `tasks/cancel`, `tasks/list`).
+
+---
+
+## 📖 Documentation
+
+- [MCP Integration Guide](https://github.com/team4u/actiondock/blob/main/docs/guides/mcp.md)
+- [Action API Reference](https://github.com/team4u/actiondock/blob/main/docs/reference/action-api.md)
+
+---
+
+## License
+
+[Apache-2.0](LICENSE) © team4u

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@actiondock/mcp",
+  "version": "2.0.0",
+  "description": "ActionDock MCP Adapter for exposing Actions as Model Context Protocol (MCP) Tools",
+  "type": "module",
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "bun": ">=1.2.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@actiondock/core": "^2.0.0",
+    "@actiondock/sdk": "^2.0.0",
+    "@modelcontextprotocol/server": "^2.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.7.0"
+  },
+  "keywords": ["actiondock", "mcp", "model-context-protocol", "tools", "agent"],
+  "author": "team4u",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/team4u/actiondock.git",
+    "directory": "packages/mcp"
+  },
+  "homepage": "https://github.com/team4u/actiondock#readme",
+  "bugs": {
+    "url": "https://github.com/team4u/actiondock/issues"
+  }
+}

package/src/adapter.ts

@@ -0,0 +1,363 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import {
+  ActionRunner,
+  createStorage,
+  ExecutionManager,
+  findProjectRoot,
+  listLinkedPackages,
+  loadActions,
+  loadProjectConfig,
+  resolvePackageRoot,
+  ServerRuntimeRegistry,
+} from "@actiondock/core";
+import type { ProjectConfig, RuntimeStorage } from "@actiondock/core";
+import type { ActionDefinition, ExecutionResult, RunRecord } from "@actiondock/sdk";
+import { McpServer } from "@modelcontextprotocol/server";
+import { toMcpSchema } from "./schemas";
+import { toMcpTaskPayload, type ActionDockMcpOptions } from "./types";
+
+/**
+ * 将 ActionDock 标准的 ExecutionResult 信封结构转换为 MCP 协议规范的 Tool Call 返回结果。
+ * 
+ * @param result ExecutionResult 结果对象
+ */
+export function toMcpResult(result: ExecutionResult) {
+  if (result.ok) {
+    return {
+      content: [
+        {
+          type: "text" as const,
+          text: JSON.stringify(result),
+        },
+      ],
+      structuredContent: result.data as Record<string, unknown>,
+    };
+  }
+
+  return {
+    isError: true,
+    content: [
+      {
+        type: "text" as const,
+        text: JSON.stringify(result),
+      },
+    ],
+  };
+}
+
+interface ResolvedTarget {
+  projectRoot: string;
+  config: ProjectConfig;
+  actions: Map<string, ActionDefinition>;
+  storage: RuntimeStorage;
+  runner: ActionRunner;
+}
+
+function createMcpToolCallback(
+  runner: ActionRunner,
+  actionId: string,
+  executionManager: ExecutionManager,
+  timeoutMs?: number
+) {
+  return async (input: any, ctx: any) => {
+    const isAsync = Boolean(
+      input &&
+        typeof input === "object" &&
+        (input.execution?.mode === "async" ||
+          input.__async === true ||
+          input.async === true)
+    );
+    const signal = ctx.mcpReq?.signal;
+
+    if (isAsync) {
+      const handle = runner.start(actionId, input, {
+        signal,
+        timeoutMs,
+      });
+      executionManager.register(handle);
+
+      return {
+        content: [
+          {
+            type: "text" as const,
+            text: JSON.stringify({
+              ok: true,
+              runId: handle.runId,
+              taskId: handle.runId,
+              status: "running",
+            }),
+          },
+        ],
+      };
+    }
+
+    const handle = runner.start(actionId, input, {
+      signal,
+      timeoutMs,
+    });
+    executionManager.register(handle);
+    const result = await handle.result;
+    return toMcpResult(result);
+  };
+}
+
+/**
+ * Creates and configures an McpServer instance bound to one or more ActionDock packages with Tasks extension support.
+ */
+export async function createActionDockMcpServer(
+  options: ActionDockMcpOptions = {}
+): Promise<McpServer> {
+  const targetRoots: string[] = [];
+  if (options.projectRoot) {
+    targetRoots.push(options.projectRoot);
+  }
+  if (options.projectRoots) {
+    targetRoots.push(...options.projectRoots);
+  }
+
+  const targetPackages: string[] = [];
+  if (options.packageId) {
+    targetPackages.push(options.packageId);
+  }
+  if (options.packageIds) {
+    targetPackages.push(...options.packageIds);
+  }
+
+  const resolvedRoots = new Set<string>();
+
+  // 1. Handle --all: discover all linked packages from registry
+  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));
+    }
+  }
+
+  // 2. Handle specific package IDs
+  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));
+  }
+
+  // 3. Handle specific directory paths
+  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));
+  }
+
+  // 4. Default fallback: current working directory
+  if (resolvedRoots.size === 0 && !options.all) {
+    const currentRoot = findProjectRoot(process.cwd());
+    if (currentRoot) {
+      resolvedRoots.add(resolve(currentRoot));
+    }
+  }
+
+  const runtimeRegistry = options.runtimeRegistry ?? new ServerRuntimeRegistry();
+  const executionManager = options.executionManager ?? runtimeRegistry.executionManager;
+  const targets: ResolvedTarget[] = [];
+
+  // Handle case where options.actions is provided directly (e.g. unit tests or virtual packages)
+  if (resolvedRoots.size === 0 && options.actions) {
+    const dummyConfig: ProjectConfig = {
+      id: "virtual",
+      name: "Virtual Package",
+      version: "2.0.0",
+      description: "In-memory virtual package",
+      actionsDir: "actions",
+      playbooksDir: "playbooks",
+    };
+    const storage = options.storage ?? runtimeRegistry.getStorage("virtual");
+    const runner = new ActionRunner({
+      packageId: dummyConfig.id,
+      storage,
+      projectConfig: dummyConfig,
+      configOverrides: options.configOverrides,
+      actions: options.actions,
+    });
+    targets.push({
+      projectRoot: "virtual",
+      config: dummyConfig,
+      actions: options.actions,
+      storage,
+      runner,
+    });
+  } else {
+    if (resolvedRoots.size === 0) {
+      throw new Error(
+        "No ActionDock project root found. Run inside an ActionDock package or specify --dir / --package / --all."
+      );
+    }
+
+    for (const root of resolvedRoots) {
+      const projectConfig = loadProjectConfig(root);
+      const actions =
+        options.actions && resolvedRoots.size === 1
+          ? options.actions
+          : await loadActions(root, projectConfig.actionsDir);
+
+      const storage =
+        options.storage && resolvedRoots.size === 1
+          ? options.storage
+          : runtimeRegistry.getStorage(projectConfig.id, root);
+
+      const runner = new ActionRunner({
+        packageId: projectConfig.id,
+        storage,
+        projectConfig,
+        configOverrides: options.configOverrides,
+        actions,
+      });
+
+      targets.push({
+        projectRoot: root,
+        config: projectConfig,
+        actions,
+        storage,
+        runner,
+      });
+    }
+  }
+
+  const isMultiPackage = targets.length > 1;
+
+  // Check action ID collision across packages
+  const actionIdCounts = new Map<string, number>();
+  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 || "2.0.0" : "2.0.0";
+
+  const server = new McpServer({
+    name: serverName,
+    version: serverVersion,
+  });
+
+  (server.server as any).registerCapabilities({
+    tasks: {
+      listChanged: true,
+      cancel: {},
+    },
+  });
+
+  // 1. Register Action Tools across all targets
+  for (const target of targets) {
+    for (const action of target.actions.values()) {
+      const count = actionIdCounts.get(action.id) || 1;
+      const toolName = count > 1 ? `${target.config.id}_${action.id}` : action.id;
+      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.runner,
+          action.id,
+          executionManager,
+          options.timeoutMs
+        )
+      );
+    }
+  }
+
+  const storages = targets.map((t) => t.storage);
+
+  // 2. Register Tasks extension endpoints: tasks/get
+  (server.server as any).setRequestHandler("tasks/get", async (req: any) => {
+    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`);
+  });
+
+  // 3. Register Tasks extension endpoints: tasks/cancel
+  (server.server as any).setRequestHandler("tasks/cancel", async (req: any) => {
+    const taskId = req.params?.taskId;
+    if (!taskId) {
+      throw new Error("taskId parameter is required for tasks/cancel");
+    }
+    const activeHandle = executionManager.get(taskId);
+    if (activeHandle) {
+      executionManager.cancel(taskId, req.params?.reason || "Cancelled via MCP tasks/cancel");
+      return {
+        taskId,
+        status: "cancelled",
+      };
+    }
+    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",
+        };
+      }
+    }
+    throw new Error(`Task '${taskId}' not found`);
+  });
+
+  // 4. Register Tasks extension endpoints: tasks/list
+  (server.server as any).setRequestHandler("tasks/list", async (req: any) => {
+    const limit = typeof req.params?.limit === "number" ? req.params.limit : 50;
+    const actionId = req.params?.actionId;
+    const allRuns: RunRecord[] = [];
+    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),
+    };
+  });
+
+  return server;
+}

package/src/http.ts

@@ -0,0 +1,166 @@
+import {
+  isLoopbackHost,
+  resolveCorsHeaders,
+  ServerRuntimeRegistry,
+  verifyBearerToken,
+} from "@actiondock/core";
+import { createMcpHandler } from "@modelcontextprotocol/server";
+import { createActionDockMcpServer } from "./adapter";
+import type { ActionDockMcpHttpOptions, ActionDockMcpHttpServerInstance } from "./types";
+
+/**
+ * Starts an ActionDock MCP server over HTTP transport.
+ */
+export function startMcpHttpServer(
+  options: ActionDockMcpHttpOptions = {}
+): ActionDockMcpHttpServerInstance {
+  const port = options.port ?? 5178;
+  const host = options.host ?? "127.0.0.1";
+  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."
+    );
+  }
+
+  const runtimeRegistry = new ServerRuntimeRegistry();
+
+  const handler = createMcpHandler(
+    () => {
+      return createActionDockMcpServer({
+        ...options,
+        runtimeRegistry,
+        executionManager: runtimeRegistry.executionManager,
+      });
+    },
+    {
+      onerror: (err) => {
+        process.stderr.write(`[MCP HTTP Error] ${err?.message || String(err)}\n`);
+      },
+    }
+  );
+
+
+  const server = Bun.serve({
+    port,
+    hostname: host,
+    async fetch(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;
+
+      // 1. Health check
+      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: "2.0.0",
+            timestamp: new Date().toISOString(),
+          }),
+          {
+            status: 200,
+            headers: {
+              "Content-Type": "application/json",
+              ...corsHeaders,
+            },
+          }
+        );
+      }
+
+      // 2. Authentication check
+      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,
+            },
+          }
+        );
+      }
+
+      // 3. Delegate MCP endpoint
+      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: () => {
+      runtimeRegistry.close();
+      server.stop(true);
+    },
+  };
+}
+

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./types";
+export * from "./schemas";
+export * from "./adapter";
+export * from "./stdio";
+export * from "./http";

package/src/schemas.ts

@@ -0,0 +1,19 @@
+import type { JsonSchema } from "@actiondock/sdk";
+import { fromJsonSchema } from "@modelcontextprotocol/server";
+
+/**
+ * Normalizes an ActionDock JSON Schema into a standard MCP Tool Schema.
+ */
+export function toMcpSchema(schema?: JsonSchema) {
+  if (schema === undefined || schema === true) {
+    return fromJsonSchema({});
+  }
+
+  if (schema === false) {
+    return fromJsonSchema({
+      not: {},
+    });
+  }
+
+  return fromJsonSchema(schema as Record<string, unknown>);
+}

package/src/stdio.ts

@@ -0,0 +1,16 @@
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { createActionDockMcpServer } from "./adapter";
+import type { ActionDockMcpOptions } from "./types";
+
+/**
+ * Starts an ActionDock MCP server over STDIO transport.
+ */
+export async function startMcpStdio(
+  options: ActionDockMcpOptions = {}
+): Promise<void> {
+  serveStdio(() => createActionDockMcpServer(options), {
+    onerror: (err) => {
+      process.stderr.write(`[MCP Error] ${err?.message || String(err)}\n`);
+    },
+  });
+}

package/src/types.ts

@@ -0,0 +1,105 @@
+import type { ExecutionManager, RuntimeStorage, ServerRuntimeRegistry } from "@actiondock/core";
+import type { ActionDefinition, ExecutionResult, 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 function toMcpTaskStatus(status: RunStatus): McpTaskStatus {
+  switch (status) {
+    case "running":
+      return "working";
+    case "success":
+      return "completed";
+    case "failed":
+      return "failed";
+    case "cancelled":
+      return "cancelled";
+    default:
+      return "working";
+  }
+}
+
+/**
+ * 将内部 RunRecord 实体转换为向 MCP 客户端暴露的 McpTaskPayload。
+ */
+export function toMcpTaskPayload(run: RunRecord): McpTaskPayload {
+  return {
+    taskId: run.id,
+    status: toMcpTaskStatus(run.status),
+    createdAt: run.startedAt,
+    finishedAt: run.finishedAt,
+    input: run.input,
+    output: run.output,
+    error: run.error,
+  };
+}
+
+/**
+ * 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: () => void;
+}
+