AI导哈

子代理MCP服务器

该服务是一个MCP服务器，允许用户通过Markdown文件定义任务特定的AI代理（如代码审查员或测试编写器），并通过Cursor CLI或Claude Code CLI后端执行这些代理。

  • by nickmisasi
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 nickmisasi/sub-agents-mcp

使用说明

子代理MCP服务器

将克劳德代码风格的子代理带到任何兼容MCP的工具中。

此MCP服务器允许您在markdown文件中定义特定任务的AI代理（如“测试编写者”或“代码审阅者”），并通过Cursor CLI或Claude code CLI后端执行它们。

为什么？

不同的代码代理具有不同的功能，我还没有找到一个可以“包揽一切”的代理。我更喜欢基于IDE的开发和Cursor的界面作为我的主要代理。但游标不支持子代理或技能。Claude Code对这些东西有很大的支持，但它错过了Cursor为不同任务利用不同基础模型的灵活性，以及执行语义代码搜索的能力。此项目允许您将所有工具中最好的工具整合到主驱动程序中。Claude Code可以访问一个语义搜索代理，该代理会启动Cursor来做一些工作，或者通过Cursor要求Gemini 3 Pro提出一个大型重构计划。游标可以暴露给已经存在的子代理，如Playwright MCP服务器。该工具的灵活性允许无限的可能性

目录

先决条件

  • Node.js 20或更高版本
  • 其中一个执行引擎（它们实际上运行子代理）：
    • cursor-agent CLI（来自Cursor）
    • claude CLI（来自Claude Code）
  • MCP兼容工具（Cursor IDE、Claude Desktop、Windsurf等）

快速开始

1.创建您的第一个代理

为您的代理创建一个文件夹并添加 code-reviewer.md。您可以使用frontmatter YAML配置代理，包括它应该以哪种类型的代理运行：

---
name: code-reviewer
description: Reviews code for bugs and issues
agentType: claude # or "cursor"
---

# Code Reviewer

You are a specialized AI assistant that reviews code.
Focus on:
- Finding bugs and potential issues
- Suggesting improvements
- Checking code quality

2.安装执行引擎

根据您使用的工具选择一个：

对于Cursor用户：

# Install Cursor CLI (includes cursor-agent)
curl https://cursor.com/install -fsS | bash

# Authenticate (required before first use)
cursor-agent login

对于Claude Code用户：

# Option 1: Native install (recommended)
curl -fsSL https://claude.ai/install.sh | bash

# Option 2: NPM (requires Node.js 18+)
npm install -g @anthropic-ai/claude-code

注意：Claude Code安装 claude CLI命令。

3.配置MCP

由于此包尚未发布到npm，您需要从本地源代码运行它。

  1. 构建项目:

    npm run build

  2. 添加到MCP配置:

    光标： ~/.cursor/mcp.json 克劳德桌面： ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）

    {
  "mcpServers": {
    "sub-agents": {
      "command": "npx",
      "args": ["/absolute/path/to/sub-agents-mcp"],
      "env": {
        "AGENTS_DIR": "/absolute/path/to/your/agents-folder",
        "AGENT_TYPE": "cursor"  // Fallback only. agentType in agent.md takes precedence.
      }
    }
  }
}

    重要提示： 仅使用绝对路径。

    • ✅ /Users/john/Documents/my-agents （Mac/Linux）
    • ✅ C:\\Users\\john\\Documents\\my-agents （Windows）
    • ❌ ./agents 或 ~/agents 不会工作

  3. 重新启动IDE，您就可以开始了。

4.修复运行Shell命令时出现的“权限被拒绝”错误

子代理可能无法执行shell命令，并出现权限错误。这是因为子代理无法响应交互式权限提示。

推荐方法：

  1. 直接使用您希望子代理处理的任务运行CLI工具：

    # For Cursor users
cursor-agent

# For Claude Code users
claude

  2. 当系统提示允许命令时（例如，“添加Shell（cd）、Shell（make）以允许列表？”），批准它们

  3. 这会自动更新您的配置文件，这些命令现在可以在通过MCP子代理调用时工作

手动配置（备选）：

如果您更喜欢手动配置权限，请编辑：

  • 光标: <project>/.cursor/cli.json 或 ~/.cursor/cli-config.json
  • 克劳德代码: .claude/settings.json 或 .claude/settings.local.json
{
  "permissions": {
    "allow": [
      "Shell(cd)",
      "Shell(make)",
      "Shell(git)"
    ]
  }
}

注意：代理通常将命令作为单行程序运行，如 cd /path && make build，因此您需要允许命令的所有部分。

使用示例

每个代理都作为自己的MCP工具公开。只需告诉你的AI使用代理：

"Use the agent_code-reviewer tool to check my UserService class"

"Use the agent_test-writer tool to create unit tests for the auth module"

"Use the agent_doc-writer tool to add JSDoc comments to all public methods"

你的AI会自动调用专门的代理并返回结果。

高级：自定义输出指令

您可以控制代理如何格式化其响应：

"Use the agent_code-reviewer tool with output_instructions set to 'Return only a JSON array of issues'"

如果您没有指定output_instructions，代理将提供他们所完成工作的简要总结，并建议下一步行动。

配置参考

所需的环境变量

AGENTS_DIR 代理文件夹的路径。必须是绝对的。

AGENT_TYPE 如果代理文件中未指定，则使用默认执行引擎：

  • "cursor" -用途 cursor-agent 命令行界面
  • "claude" -用途 claude 命令行界面

注意：这只是一个回退。这 agentType 代理的markdown文件中指定的优先权。

可选设置

EXECUTION_TIMEOUT_MS 代理在超时前可以运行多长时间（默认值：5分钟，最大值：10分钟）

超时示例：

{
  "mcpServers": {
    "sub-agents": {
      "command": "npx",
      "args": ["/absolute/path/to/sub-agents-mcp"],
      "env": {
        "AGENTS_DIR": "/absolute/path/to/agents",
        "AGENT_TYPE": "cursor",
        "EXECUTION_TIMEOUT_MS": "600000"
      }
    }
  }
}

安全说明

代理可以访问您的项目目录。仅使用来自可信来源的代理定义。

故障排除

超时错误或身份验证失败

如果使用Cursor CLI： 跑 cursor-agent login 以进行身份验证。会话可能会过期，因此如果看到身份验证错误，请再次运行此命令。

验证安装：

which cursor-agent

如果使用克劳德代码： 确保CLI已正确安装且可访问。

未找到代理

检查：

  • AGENTS_DIR 指向正确的目录（使用绝对路径）
  • 您的代理文件有 .md 或 .txt 扩展
  • 文件名使用连字符或下划线（无空格）

其他执行错误

  1. 验证 AGENT_TYPE 设置正确(cursor 或 claude)
  2. 确保您选择的CLI工具已安装且可访问
  3. 仔细检查MCP配置中是否设置了所有环境变量

多个客户端和并发使用

我可以同时使用多个工具吗？

对！您可以让Cursor、Claude Desktop和任何其他MCP客户端都使用相同的 sub-agents-mcp 同时配置。每个客户端都会自动获得自己的隔离服务器实例。

它是如何工作的：

  • 每个MCP客户端都会生成自己的 sub-agents-mcp 过程通过 npx
  • MCP服务器使用 标准 （stdin/stdout）用于通信，本质上是1:1
  • 光标开始时→ 它在运行 npx sub-agents-mcp → 获取进程A
  • 当Claude Code启动时→ 它在运行 npx sub-agents-mcp → 获取进程B
  • 这些过程是完全独立的

这意味着：

  • ✅ 客户之间没有冲突
  • ✅ 无端口绑定或资源争用
  • ✅ 每个客户都会从您的 AGENTS_DIR
  • ✅ 代理可以在不同的客户端上并行运行
  • ℹ️ 每个实例在启动时加载代理（重新启动客户端以重新加载更改）
  • ℹ️ 实例之间没有共享状态（设计为无状态）

例子：

// Same config in both ~/.cursor/mcp.json AND ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "sub-agents": {
      "command": "npx",
      "args": ["/absolute/path/to/sub-agents-mcp"],
      "env": {
        "AGENTS_DIR": "/Users/you/shared-agents",
        "AGENT_TYPE": "cursor"
      }
    }
  }
}

Cursor和Claude Desktop将同时完美运行，每个都有自己的服务器进程。

设计理念

为什么独立背景很重要

每个子代理都从一个新的上下文开始。这为每次调用增加了一些启动开销，但它确保了每个任务独立运行，没有前一次运行的剩余状态。

上下文隔离

  • 每个代理只接收与其任务相关的信息
  • 运行之间没有上下文泄漏
  • 主代理保持专注和轻量级

准确性和可靠性

  • 子代理可以专注于单一目标而不受干扰
  • 来自无关背景的混淆风险较小
  • 在复杂的多步骤工作流程中获得更一致的结果

可扩展性

  • 大型任务可以安全地拆分为较小的子任务
  • 每个子代理都在自己的令牌限制内运行
  • 主代理在不达到全局上下文限制的情况下进行协调

启动开销是一种有意的权衡：系统更倾向于清晰度和准确性，而不是原始执行速度。

运作原理

此MCP服务器充当您的AI工具和支持的执行引擎（Cursor CLI或Claude Code CLI）之间的桥梁。

流程：

  1. 您可以在客户端（Cursor、Claude Desktop等）中配置MCP服务器
  2. 客户端自动启动 sub-agents-mcp 启动时作为后台进程
  3. 当你的主AI助手需要一个子代理时，它会调用MCP工具
  4. MCP服务器读取代理定义（markdown文件）并调用所选CLI(cursor-agent 或 claude)
  5. 执行引擎运行代理，并通过MCP服务器将结果流式传输回来
  6. 您的主要助理收到结果并继续工作

这种架构使任何与MCP兼容的工具都能从专门的子代理中受益，即使它没有本机支持。

许可证

麻省理工学院

通过模型上下文协议实现AI到AI的协作

相关 MCP