mcp-dynamic-orchestrator

概述

使用此技能可以：

• 发现有哪些 MCP 服务可用，以及它们的用途。
• 检查特定 MCP 的功能，而无需加载所有工具架构。
• 执行通过生成的 mcp-clients/* 模块调用 MCP 工具的 TypeScript/JavaScript 代码。

如果未配置 MCP 服务，list_mcp_capabilities 将返回空列表，并提示用户前往 skills/mcp-dynamic-orchestrator/mcp.registry.json 添加 MCP 条目。

此技能会读取 mcp.registry.json，因此在其中添加 MCP 条目（例如 Cloudflare MCP）后， 无需更改工具接线即可自动发现该 MCP。

Cloudflare MCP 示例

可以像这样在 mcp.registry.json 中配置 Cloudflare MCP 服务：

{
  "id": "cloudflare",
  "title": "Cloudflare platform MCP",
  "summary": "Interact with Cloudflare's MCP endpoint for documentation, examples, and platform operations exposed via the official Cloudflare MCP server.",
  "mcp": {
    "transport": "stdio",
    "command": "npx",
    "args": [
      "mcp-remote",
      "https://docs.mcp.cloudflare.com/sse"
    ]
  },
  "domains": ["cloudflare", "workers", "kv", "r2", "queues", "zero_trust", "networking", "security", "observability"],
  "tags": ["cloudflare", "platform", "infra", "docs", "workers", "mcp"],
  "examples": [
    "Fetch Cloudflare Workers documentation for a specific API.",
    "Search Cloudflare platform docs for queues or KV usage patterns.",
    "Look up configuration guidance for Zero Trust or networking features."
  ],
  "sensitivity": "low",
  "visibility": "default",
  "priority": 10,
  "autoDiscoverTools": true
}

添加此条目后：

• 查询中提及 Cloudflare、Workers、KV、R2、Queues 等内容时，list_mcp_capabilities 会返回 cloudflare。
• 使用 id: "cloudflare" 调用 describe_mcp 时，会显示 Cloudflare MCP 服务的简明工具摘要。
• execute_mcp_code 支持 Agent 编写如下 TypeScript：

import * as cloudflare from "mcp-clients/cloudflare";

async function main() {
  const docs = await cloudflare.search_docs({ query: "Workers KV" });
  console.log(docs.summary);
}

mcp-clients/cloudflare 中实际可用的函数会根据 MCP 工具定义动态生成；Agent 应始终：

1. 通过 list_mcp_capabilities 进行发现。
2. 通过 describe_mcp 检查可用操作。
3. 通过 execute_mcp_code 使用这些操作。

使用方法

1. 使用自然语言查询或筛选条件调用 list_mcp_capabilities，查看有哪些 MCP。
2. 对选定的 MCP（例如 cloudflare），调用 describe_mcp 以了解其操作。
3. 编写从 mcp-clients/<id> 导入内容并调用导出函数的 TypeScript/JavaScript 代码。
4. 使用 execute_mcp_code 运行代码；出于安全考虑，也可以限制 allowedMcpIds。

规则

• 不要假设各个 MCP 工具是顶层工具。
• 始终按以下顺序操作：发现 → 描述 → 生成代码 → execute_mcp_code。
• 只有在需要确切的参数结构时，才在 describe_mcp 中请求 detail: "schema"。

已知限制

沙盒安全（严重）

⚠️ 当前沙盒实现对不可信代码并不安全。

⚠️ 基于 vm 的沙盒并非安全边界。 Node 的 vm 模块可以被逃逸（请参阅 Node 文档）。此设置只能减少意外损害。对于不可信的 MCP 条目，请在具备适当操作系统级隔离的独立进程/容器中运行。

• 使用 vm.createContext()，但它并非安全边界
• 可通过原型污染、篡改 require() 等方式逃逸
• 仅对 Claude 生成的代码启用（可信来源）
• 需要设置 MCP_ORCH_ENABLE_SANDBOX=1 环境变量
• 完整的安全详情请参阅 references/security-model.md

进程启动加固（命令和环境变量允许列表）

向 mcp.registry.json 添加条目时，编排器会强制执行以下规则：

1. 命令允许列表 — 仅允许 npx, npm, pnpm, yarn, bunx, bun, node, deno, uvx, uv, python, python3, cargo, go（不带路径的名称通过 PATH 解析）。绝对/相对路径和 Shell 命令均会被拒绝。设置 MCP_ORCH_ALLOW_RAW_COMMANDS=1 可选择退出此限制（会在 stderr 输出醒目警告；仅适用于完全可信的注册表）。
2. 环境变量拒绝列表 — 启动进程前，会从 mcp.env 中移除 PATH、NODE_OPTIONS、LD_PRELOAD、DYLD_INSERT_LIBRARIES、PYTHONPATH 等变量（每移除一个键都会在 stderr 输出警告）。

其他限制

• 不支持 TypeScript 编译：.ts 格式的用户代码将无法运行
• 不支持模块解析：无法解析从 mcp-clients/* 导入的模块；请使用 $call() API
• 静态注册表：添加/移除 MCP 需要重启
• 错误处理能力有限：MCP 连接失败时只会返回通用错误

详细的故障排除说明请参阅 references/troubleshooting.md。

生产状态

已正常运行 ✅：

• 通过 list_mcp_capabilities 发现（功能完整）
• 通过 describe_mcp 检查（功能完整）
• 注册表管理（已配置 16 个 MCP）
• MCP 客户端（stdio + HTTP 传输）
• 安全控制（可见性、敏感度、策略）

存在限制 🟡：

• 代码执行（需要环境标志，沙箱不安全）
• 测试（仅基本冒烟测试）

计划中 🔮：

• 使用 Worker 线程的安全沙箱（v1.1）
• 支持 TypeScript 编译（v1.1）
• 模块解析（v1.1）
• 动态更新注册表（v1.2）

完整路线图请参阅仓库根目录中的 plan.md。