mcp-agents

使用说明内容（Markdown格式）

项目简介

• mcp-agents 是一个基于 MCP（Model Context Protocol）的服务端实现。它在服务端将不同 CLI 工具包装成 MCP 工具，允许 MCP 客户端通过标准化的 JSON-RPC 接口调用这些工具并获取输出结果。当前支持的提供者包括 Claude Code、Gemini CLI 以及 Codex（透传）。服务通过标准输入输出（stdio）进行通信，便于与 LLM 客户端集成。

主要功能点

• MCP 服务端实现：实现 ListTools 与 CallTool 请求的处理，符合 MCP 的请求和响应模式。
• 资源与工具暴露：为每个 provider 暴露一个工具，支持 ping 之类的连通性测试以及实际的 CLI 调用。
• CLI 包装与执行：将选择的 CLI 工具作为子进程执行，输出其 stdout（或 stderr）作为工具的返回结果。
• 传输支持：以 StdioServerTransport 作为沟通渠道，便于与 LLM 客户端通过标准输入输出通信；兼容 MCP 的 stdio 传输规范。
• 可选代理模式：提供 codex 透传模式，直接将 Codex 的 MCP 服务端作为中间层，保持最小改动的集成。

安装步骤

• 先决条件
  • Node.js 版本至少为 18
  • 至少一个 CLI（ Claude Code、Gemini、Codex）安装并在 PATH 中
• 安装与运行
  • 直接使用 npm/npx 运行（示例中的默认 provider 为 codex）：
    • npx mcp-agents
  • 指定 provider 运行某个 CLI：
    • npx mcp-agents --provider claude
    • npx mcp-agents --provider gemini
  • 如果选择 Codex 透传模式，则会以 codex mcp-server 作为子进程直接运行对应的 Codex 服务端。

服务器配置（MCP 客户端需要的连接信息）

• 说明：MCP 客户端需要知道服务器的启动命令与参数来与 MCP 服务器建立连接。下面给出基于仓库信息可用的配置示例，包含服务器名称、启动命令与参数等信息。客户端不需要修改服务端实现，只需按此配置启动服务器即可。
• 示例（JSON 格式，客户端需要的连接信息）: { "mcpServers": { "codex": { "command": "npx", "args": ["-y", "mcp-agents@latest", "--provider", "codex"] }, "gemini": { "command": "npx", "args": ["-y", "mcp-agents@latest", "--provider", "gemini"] } } } 注释：
• codex 条目表示通过 npx 启动 mcp-agents，提供方设为 codex（透传模式时启动对应的 Codex MCP 服务端）。
• gemini 条目表示通过 npx 启动 mcp-agents，提供方设为 gemini。
• 若要使用 claude 作为提供方，请将相应条目添加到 mcpServers 中，命令和参数与上述类似，只需将 --provider 的值改为 claude 即可。

基本使用方法

• 启动与连接
  • 通过命令行启动服务器（默认提供方 codex）：
    • npx mcp-agents
  • 也可指定提供方，例如 claude 或 gemini：
    • npx mcp-agents --provider claude
    • npx mcp-agents --provider gemini
  • 服务器以 stdio 方式监听并输出就绪信息到标准错误流（stderr）。
• 如何调用工具
  • 客户端向服务器发送 ListTools 请求以获取可用工具清单（包括 ping 测试工具与实际 CLI 包装工具）。
  • 使用 CallTool 请求调用所需工具，传入参数 prompts 等信息，服务器将 CLI 作为子进程执行并返回输出。
• 运行时参数
  • 每个工具支持特定参数，如 prompt、timeout_ms（毫秒）、以及提供方特定的额外属性（如 sandbox 等）。
  • 当超时未返回时，服务器会根据传入 timeout_ms 或默认超时去中止执行并返回错误信息。