Sub Agents MCP

🚀 Sub - Agents MCP 服务器

Sub - Agents MCP 服务器能够将 Claude Code 风格的子代理功能引入到任何与 MCP 兼容的工具中。通过该服务器，你可以在 Markdown 文件中定义特定任务的 AI 代理，并借助 Cursor CLI、Claude Code CLI 或 Gemini CLI 等后端来执行这些代理，实现跨工具的代理复用。

🚀 快速开始

1. 创建你的第一个代理

为你的代理创建一个文件夹，并添加 code - reviewer.md 文件：

# 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 用户：

# 安装 Cursor CLI（包含 cursor - agent）
curl https://cursor.com/install -fsS | bash

# 认证（首次使用前需要）
cursor - agent login

对于 Claude Code 用户：

# 选项 1：原生安装（推荐）
curl -fsSL https://claude.ai/install.sh | bash

# 选项 2：使用 NPM（需要 Node.js 18+）
npm install -g @anthropic - ai/claude - code

注意：Claude Code 会安装 claude CLI 命令。 对于 Gemini CLI 用户：

# 安装 Gemini CLI
npm install -g @google/gemini - cli

# 通过浏览器进行认证（首次使用前需要）
gemini

注意：Gemini CLI 使用 OAuth 认证。运行一次 gemini 命令，通过浏览器进行认证。

3. 配置 MCP

将以下内容添加到你的 MCP 配置文件中： Cursor：~/.cursor/mcp.json Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json（macOS）

{
  "mcpServers": {
    "sub - agents": {
      "command": "npx",
      "args": ["-y", "sub - agents - mcp"],
      "env": {
        "AGENTS_DIR": "/absolute/path/to/your/agents - folder",
        "AGENT_TYPE": "cursor"  // 或者 "claude" 或 "gemini"
      }
    }
  }
}

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

• ✅ /Users/john/Documents/my - agents（Mac/Linux）
• ✅ C:\\Users\\john\\Documents\\my - agents（Windows）
• ❌ ./agents 或 ~/agents 无效

重启你的 IDE，即可开始使用。

4. 解决运行 shell 命令时的“权限被拒绝”错误

子代理在执行 shell 命令时可能会因权限错误而失败。这是因为子代理无法响应交互式权限提示。 推荐方法：

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

# 对于 Cursor 用户
cursor - agent

# 对于 Claude Code 用户
claude

# 对于 Gemini CLI 用户
gemini

2. 当提示允许命令时（例如，“将 Shell(cd)、Shell(make) 添加到允许列表？”），批准它们。
3. 这将自动更新你的配置文件，这些命令现在可以通过 MCP 子代理调用。 手动配置（替代方法）： 如果你更喜欢手动配置权限，请编辑：

• Cursor：<project>/.cursor/cli.json 或 ~/.cursor/cli - config.json
• Claude Code：.claude/settings.json 或 .claude/settings.local.json

{
  "permissions": {
    "allow": [
      "Shell(cd)",
      "Shell(make)",
      "Shell(git)"
    ]
  }
}

注意：代理通常以单行命令的形式运行，例如 cd /path && make build，因此你需要允许命令的所有部分。

✨ 主要特性

• 跨工具复用：只需定义一次可复用的代理，即可在多个工具中使用。
• 团队共享：团队成员可以共享代理定义，而无需考虑使用的 IDE。
• 多引擎支持：可以从任何 MCP 客户端利用 Cursor CLI、Claude Code CLI 或 Gemini CLI 的功能。

💻 使用示例

基础用法

只需告诉你的 AI 使用代理：

"Use the code - reviewer agent to check my UserService class"

"Use the test - writer agent to create unit tests for the auth module"

"Use the doc - writer agent to add JSDoc comments to all public methods"

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

📦 安装指南

前提条件

• Node.js 20 或更高版本
• 以下执行引擎之一（用于实际运行子代理）：
  • cursor - agent CLI（来自 Cursor）
  • claude CLI（来自 Claude Code）
  • gemini CLI（来自 Gemini CLI）
• 一个与 MCP 兼容的工具（Cursor IDE、Claude Desktop、Windsurf 等）

安装步骤

按照“快速开始”部分的步骤 2 安装执行引擎。

📚 详细文档

代理示例

每个位于代理文件夹中的 .md 或 .txt 文件都会成为一个代理。文件名即为代理名称（例如，test - writer.md → “test - writer”）。

测试编写器

test - writer.md

# Test Writer
You specialize in writing comprehensive unit tests.
- Cover edge cases
- Follow project testing patterns
- Ensure good coverage

SQL 专家

sql - expert.md

# SQL Expert
You're a database specialist who helps with queries.
- Optimize for performance
- Suggest proper indexes
- Help with complex JOINs

安全检查器

security - checker.md

# Security Checker
You focus on finding security vulnerabilities.
- Check for SQL injection risks
- Identify authentication issues
- Find potential data leaks

配置参考

必需的环境变量

可选设置

示例（包含超时设置）：

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

安全注意事项

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

会话管理

会话管理允许子代理记住之前的执行情况，这在你希望代理基于早期工作或在多次调用中保持上下文时非常有用。

会话的重要性

默认情况下，每个子代理执行都没有上下文。启用会话后：

• 代理可以引用其早期工作。
• 你可以获得执行历史记录，用于调试。
• 相关任务可以共享上下文。

启用会话

在 MCP 配置中添加以下环境变量：

{
  "mcpServers": {
    "sub - agents": {
      "command": "npx",
      "args": ["-y", "sub - agents - mcp"],
      "env": {
        "AGENTS_DIR": "/absolute/path/to/agents",
        "AGENT_TYPE": "cursor",
        "SESSION_ENABLED": "true",
        "SESSION_DIR": "/absolute/path/to/session - storage",
        "SESSION_RETENTION_DAYS": "1"
      }
    }
  }
}

配置选项

安全考虑

会话文件包含执行历史记录，可能包含敏感信息。请为 SESSION_DIR 使用绝对路径。

何时使用会话

会话适用于：

• 迭代开发：“根据你之前的发现，现在修复问题”
• 多步骤工作流：将复杂任务分解为多个子代理调用
• 调试：查看确切的执行内容和返回结果

注意：会话需要额外的存储和处理开销。

会话连续性的工作原理

启用会话后，MCP 响应将包含一个 session_id 字段。要继续同一会话，请在下次请求中传递此 ID。 重要提示：你的 AI 助手必须在后续请求中明确包含 session_id。虽然有些助手可能会自动执行此操作，但不能保证。为了确保会话连续性，请在提示或项目规则中添加明确的说明。 示例提示说明：

When using sub - agents with sessions enabled, always include the session_id
from the previous response in your next request to maintain context.

示例项目规则（例如，AGENTS.md）：

# Sub - Agent Session Guidelines

When calling the same sub - agent multiple times:
1. Extract the session_id from the MCP response
2. Pass it as a parameter in subsequent calls
3. This preserves context between executions

故障排除

超时错误或认证失败

如果使用 Cursor CLI： 运行 cursor - agent login 进行认证。会话可能会过期，如果你遇到认证错误，只需再次运行此命令。 验证安装：

which cursor - agent

如果使用 Claude Code： 确保 CLI 已正确安装并可访问。

未找到代理

检查以下内容：

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

其他执行错误

1. 验证 AGENT_TYPE 设置正确（cursor、claude 或 gemini）。
2. 确保你选择的 CLI 工具已安装并可访问。
3. 仔细检查 MCP 配置中所有环境变量是否已设置。

🔧 技术细节

设计理念

独立上下文的重要性

每个子代理都从全新的上下文开始。这会为每次调用增加一些启动开销，但确保每个任务独立运行，不受之前运行的残留状态影响。 上下文隔离：

• 每个代理仅接收与其任务相关的信息。
• 运行之间无上下文泄漏。
• 主代理保持专注和轻量级。 准确性和可靠性：
• 子代理可以专注于单个目标，不受无关上下文的干扰。
• 减少因无关上下文导致的混淆风险。
• 在复杂的多步骤工作流中获得更一致的结果。 可扩展性：
• 大型任务可以安全地拆分为较小的子任务。
• 每个子代理在其自己的令牌限制内运行。
• 主代理可以协调而不会达到全局上下文限制。

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

工作原理

此 MCP 服务器充当你的 AI 工具与受支持的执行引擎（Cursor CLI、Claude Code CLI 或 Gemini CLI）之间的桥梁。 流程如下：

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

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

📄 许可证

本项目采用 MIT 许可证。

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