AI导哈

代理MCP服务器

一个高层工具代理服务器，通过自主代理循环连接多个下游MCP服务器，使用LLM智能委派任务。

  • by dragosboca
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 dragosboca/agent-mcp

使用说明

mcp探员

一个MCP（模型上下文协议）外观服务器，它公开了由自治代理循环支持的高级工具。该项目充当客户端应用程序和多个下游MCP服务器之间的桥梁，使用LLM将任务智能地委托为自然语言指令。

概述

agent-mcp 是一个元MCP服务器，它：

  1. 聚合多个MCP服务器 -连接到任意数量的下游MCP服务器
  2. 公开统一的工具 -每个下游服务器都成为一个高级工具
  3. 使用代理为工具供电 -当调用工具时，自主代理（由 谷歌ADK)运行以使用下游服务器的功能来执行指令
  4. 内部处理复杂性 -客户保持简单；代理处理工具选择、错误恢复和多步骤操作

用例

而不是客户需要：

  • 知道哪个MCP服务器有哪些工具
  • 了解工具参数和模式
  • 处理工具调用序列和错误

客户可以说：

Tool: "my-server"
Input: "Create a task 'Buy groceries' and add it to the Groceries project"

代理处理查找项目、调用正确工具和返回结果的复杂性。

建筑

┌──────────────────┐
│   Client (e.g.   │
│   Claude Code)   │
└────────┬─────────┘
         │ MCP Protocol
         ▼
┌─────────────────────┐
│  agent-mcp Server   │
├─────────────────────┤
│  Tool 1: server-a   ├──→ ADK Agent ─→ LLM (via LiteLLM)
│  Tool 2: server-b   ├──→ ADK Agent ─→ LLM (via LiteLLM)
│  Tool 3: server-c   ├──→ ADK Agent ─→ LLM (via LiteLLM)
│  ...                │
└─────────┬───────────┘
          │
          │ MCP Protocol (stdio/http)
          ▼
    ┌─────────────┐
    │ Downstream  │
    │ MCP Servers │
    └─────────────┘

安装

先决条件

  • Python 3.10+
  • 紫外线 （可选，但推荐）
  • 要使用的LLM提供程序的API密钥（例如。 ANTHROPIC_API_KEY)
  • 您配置的任何下游MCP服务器的API令牌（可选）

设置

  1. 克隆存储库：
git clone https://github.com/yourusername/agent-mcp.git
cd agent-mcp
  1. 安装依赖项：
# Using uv (recommended)
uv sync

# Or using pip
pip install -e .
  1. 创建配置文件：
# Create .mcp.json from the example
cp .mcp.json.example .mcp.json

# Edit with your API keys and paths
nano .mcp.json
  1. 在中配置下游MCP服务器 config.yaml:
model: anthropic/claude-sonnet-4-20250514
max_tokens: 8096
max_llm_calls: 20

servers:
  my-server:
    description: "Description of what this server does"
    transport: stdio
    command: uv
    args:
      - run
      - --directory
      - /path/to/my-mcp-server
      - my-mcp-server
    env:
      MY_API_TOKEN: ${MY_API_TOKEN}

这 model 现场使用 LiteLLM格式 (provider/model-name)，因此您可以使用任何受支持的LLM提供程序。

配置

.mcp.json

这 .mcp.json 该文件配置了Claude Code（或其他MCP客户端）的启动方式 agent-mcp:

{
  "mcpServers": {
    "agent-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/agent-mcp", "agent-mcp"],
      "env": {
        "ANTHROPIC_API_KEY": "your-key",
        "MY_API_TOKEN": "your-token"
      }
    }
  }
}

重要提示： 永不承诺 .mcp.json 到git。使用 .mcp.json.example 作为模板。

config.yaml

这 config.yaml 文件定义：

  • 代理设置 -模型（LiteLLM格式）、最大令牌、LLM调用限制
  • 下游服务器 -要聚合的MCP服务器
    • 传输类型（stdio、http）
    • 如何启动它们（stdio使用command+args，http使用url）
    • 环境变量（支持 ${VAR} 替代）
    • 身份验证（静态标头或OAuth浏览器流）

用法

作为MCP服务器

曾经 agent-mcp 正在运行，客户端通过MCP和调用工具连接：

# Pseudocode example
response = await client.call_tool("my-server", {
    "instruction": "List all my projects and tasks due today"
})

独立运行

uv run agent-mcp

服务器在stdin/stdout上监听MCP协议消息。

使用克劳德代码

  1. 复制您的 .mcp.json 配置到 ~/.config/Claude/claude_desktop_config.json
  2. 重新启动Claude代码
  3. 您配置的下游服务器工具在对话中可用

运作原理

  1. 初始化 - agent-mcp 负载 config.yaml 并为每个下游服务器注册工具
  2. 工具注册 -每个下游服务器都将成为一个具有其配置名称的工具
  3. 请求处理 -当使用自然语言指令调用工具时：
    • agent-mcp 创建ADK McpToolset 连接到下游服务器
    • ADK LlmAgent 使用下游服务器的工具运行
    • 代理读取指令并决定调用哪些工具
    • 代理处理工具调用、错误和重试
    • 结果返回给客户端，工具集关闭
  4. 每次调用生命周期 -每次工具调用都会获得一个新的MCP连接，避免连接状态过时

项目结构

agent-mcp/
├── README.md                 # This file
├── .gitignore              # Git exclusions
├── .mcp.json.example       # Template for .mcp.json
├── config.yaml             # Downstream server configuration
├── pyproject.toml          # Python project metadata
├── uv.lock                 # Locked dependencies
├── src/
│   └── agent_mcp/
│       ├── __init__.py
│       ├── server.py       # MCP server entrypoint
│       ├── agent.py        # ADK agent orchestration
│       ├── oauth.py        # OAuth browser-based authentication
│       └── config.py       # Configuration loading and parsing
└── tests/
    ├── test_agent.py       # Agent unit tests
    ├── test_config.py      # Config parsing tests
    ├── test_oauth.py       # OAuth flow tests
    ├── test_server.py      # Server CLI tests
    └── test_e2e_oauth.py   # End-to-end OAuth tests (require cached tokens)

模块概述

  • 服务器.py -FastMCP服务器实现，处理MCP协议
  • agent.py -基于ADK的代理编排使用 LlmAgent, Runner，以及 McpToolset
  • oauth.py -下游MCP服务器的基于OAuth浏览器的身份验证
  • config.py -YAML解析、环境变量替换、验证

发展

运行测试

uv run pytest -m "not e2e"

运行端到端测试

E2E测试需要缓存OAuth令牌（首先手动运行OAuth流）：

uv run pytest -m e2e

代码风格

  • Python 3.10+
  • 异步优先（asyncio）
  • 全程键入提示
  • 最小依赖性

局限性和未来工作

  • 仅支持stdio和http传输
  • 不缓存工具模式（每次调用时重新加载）
  • 错误消息由代理生成（可能不一致）

贡献

欢迎投稿！感兴趣的领域：

  • 工具模式缓存以提高性能
  • 更好的错误恢复策略
  • 附加测试覆盖率

许可证

麻省理工学院

致谢

内置：

相关 MCP