Polyagent MCP

🚀 Polyagent MCP

Polyagent MCP 是一個 MCP 服務器，它能將 Claude Code 代理集成到 Codex、Gemini CLI 等 AI 代碼編寫助手之中。藉助該服務器，任何兼容 MCP 的客戶端都能直接使用現有的 .claude/agents/ 定義，無需額外配置。

🚀 快速開始

安裝

使用 uvx 快速啟動（推薦）

可直接從 GitHub 運行，無需克隆倉庫：

# 默認標準輸入輸出傳輸
uvx --from git+https://github.com/execveat/polyagent-mcp polyagent-mcp

# 自定義端口的 HTTP 傳輸
uvx --from git+https://github.com/execveat/polyagent-mcp polyagent-mcp --transport http --port 8000

本地開發

克隆倉庫並安裝以進行開發：

git clone https://github.com/execveat/polyagent-mcp.git
cd polyagent-mcp
uv sync

可通過以下任一方式在本地運行：

# 使用控制檯腳本
uv run polyagent-mcp

# 使用 fastmcp CLI（用於開發時自動重載）
uv run fastmcp dev polyagent_mcp.server:mcp

配置

Codex

在 Codex 配置中添加以下內容，超時時間至少設置為 15 分鐘：

[mcp_servers.agents]
command = "uvx"
args = ["--from", "git+https://github.com/execveat/polyagent-mcp", "polyagent-mcp"]
tool_timeout_sec = 900

本地開發時（如果你已克隆倉庫）：

[mcp_servers.agents]
command = "uv"
args = ["--directory", "/path/to/polyagent-mcp", "run", "polyagent-mcp"]
tool_timeout_sec = 900

重要提示：

• 使用 tool_timeout_sec = 900 或更高的值。較低的超時時間會導致代理調用過早失敗。
• uvx 方法會自動從 GitHub 安裝和更新。
• 本地開發時，將 /path/to/polyagent-mcp 替換為你實際的克隆路徑。

Gemini CLI

在 settings.json 中添加以下內容：

{
  "mcpServers": {
    "agents": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/execveat/polyagent-mcp",
        "polyagent-mcp"
      ],
      "timeout": 900000
    }
  }
}

本地開發時：

{
  "mcpServers": {
    "agents": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/polyagent-mcp",
        "run",
        "polyagent-mcp"
      ],
      "timeout": 900000
    }
  }
}

重要提示：

• 超時時間以毫秒為單位：900000 即 15 分鐘。
• 本地開發時，將 /path/to/polyagent-mcp 替換為你實際的克隆路徑。

環境變量

可通過環境變量進行配置（均為可選）：

• POLYAGENT_MCP_DIR – 包含代理 Markdown 文件的目錄（默認：.claude/agents）
• POLYAGENT_MCP_CONFIG – 用於覆蓋運行器/代理配置的可選 YAML/JSON 文件
• POLYAGENT_MCP_WORKSPACE – 代理執行的工作目錄
• POLYAGENT_MCP_TIMEOUT – 默認超時時間（秒）（默認：900）
• POLYAGENT_MCP_LOG_LEVEL – Python 日誌級別（默認：INFO）
• POLYAGENT_MCP_DEBUG – 啟用 FastMCP 調試模式

使用

配置完成後，你的 MCP 客戶端將自動發現 .claude/agents/ 中的所有代理：

1. 列出可用代理：查看 resource://agents/manifest 或使用客戶端的工具列表。
2. 查看代理說明：在委託任務前，閱讀 agent://<代理名稱>。
3. 調用代理：調用以代理命名的工具（例如，commit-agent）。

工具調用示例：

{
  "tool": "commit-agent",
  "arguments": {
    "task": "Review and commit the changes with an appropriate message",
    "context": "Fixed authentication bug in login flow"
  }
}

可選參數：

• runner – 強制使用特定的 CLI（codex、claude、gemini）
• model – 運行器特定的模型別名
• timeout_seconds – 延長長時間操作的超時時間

✨ 主要特性

為何存在此項目

擁有 Claude Code 代理的團隊希望使用 Codex 或 Gemini 的同事能夠複用相同的代理，而無需進行任何移植工作。Polyagent MCP 為使用 Codex 或 Gemini 且可能無法訪問 Claude Code 的貢獻者提供了零配置體驗，使他們能夠享受與 Claude Code 相同的基於代理的工作流程。該項目專為那些已經在設計 Claude Code 優化子代理方面投入大量精力的項目而設計，可直接作為這些項目的一項功能使用。

工作原理

在 Codex 或 Gemini 中運行此 MCP 服務器時，它會通過單獨的 CLI 會話生成代理，使其表現與 Claude Code 代理類似，具備以下優點：

• 上下文優化：由於代理在單獨的上下文中初始化，主進程使用的上下文更少，且僅返回重要信息，而非所有中間輸出和思考標記。
• 性能提升：每個代理都可以擁有自己的知識和規則。由於在新會話中運行，與將相同指令交給承擔多項職責的單個 AI 代理相比，通常能更好地遵循提示（單一職責原則）。

📚 詳細文檔

要求

• Python 3.10 及以上版本
• 至少安裝以下其中一個 CLI：codex、claude 或 gemini
• 存在包含代理定義的 .claude/agents/ 目錄

📄 許可證

本項目採用 MIT 許可證。