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 的協作