AI导哈

MCP代理命令行工具

一个无头的、支持模型上下文协议（MCP）的命令行界面，用于对Anthropic驱动的代理运行进行基准测试和比较，并管理完整的运行循环。

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

使用说明

mcp代理cli

mcp-agent-cli 是一个无头、支持模型上下文协议（MCP）的命令行界面，允许您对Anthropic驱动的代理运行与本地托管的MCP服务器进行基准测试和比较。它管理整个循环：加载配置、通过stdio实例化MCP传输、编排工具调用以及收集每次运行的延迟/令牌使用指标。

为什么存在

  • 针对不同的MCP服务器拓扑（直接工具访问与exec代理）驱动Anthropic驱动的代理。
  • 捕获可比较的遥测数据(reports/*.json, reports/ab_runs.csv)用于A/B风格的提示。
  • 提供MCP+Anthropic集成的精简、可检查的参考实现，无需UI依赖。

关键组件

  • mcp_agent_cli/cli.py –参数解析， .env 引导和子命令(run, compare).
  • mcp_agent_cli/runner/run_once.py –加载YAML配置，构建工具规范(registry/*)，并通过以下方式执行Anthropic消息循环 anthropic_client.loop.run_tool_loop.
  • mcp_agent_cli/mcp_client/stdio.py –通过stdio生成MCP服务器，使用JSON-RPC，并公开 list_tools/call_tool.
  • mcp_agent_cli/runner/metrics.py –保存每次运行的JSON报告并附加CSV摘要。
  • mcp_agent_cli/config/*.yaml –运行时设置(settings.yaml)加上MCP服务器定义(servers.yaml, servers.example.yaml).

安装

  1. 创建并激活Python 3.11+虚拟环境。
  2. 安装依赖项：
    pip install -r requirements.txt
  3. 确保您可以访问Anthropic消息API和您计划运行的任何MCP服务器。

配置

人类学证书

cli.load_env_if_present() 从第一个加载环境变量 .env 它找到的文件（首选项目根）。最小密钥：

ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_API_URL=https://api.anthropic.com/v1/messages        # optional override
ANTHROPIC_VERSION=2023-06-01                                   # optional override

代理设置

mcp_agent_cli/config/settings.yaml 控制模型行为：

  • model, max_tokens, temperature, anthropic_request_timeout_ms
  • max_turn：最大辅助转弯次数（0由模型决定）
  • system_prompt：在每次运行中注入可选的系统上下文
  • enable_prompt_caching：切换 anthropic-beta 符合条件的工具的标题(run_once._mark_tool_cacheable)

您可以通过以下方式提供备用设置文件 --settings path/to/file.yaml.

MCP服务器注册表

mcp_agent_cli/config/servers.yaml 带有占位符路径的船只。复制它（或更详细的 servers.example.yaml)通过您的环境，而不是硬编码，将路径和参考机密发送到私人位置：

case_a:
  servers:
    - name: finance-mcp
      command: /abs/path/to/finance-mcp/.venv/bin/python
      args: ["-m", "finance_mcp.server"]
      cwd: /abs/path/to/finance-mcp
      env:
        PYTHONPATH: /abs/path/to/finance-mcp/src
        NEWS_LANG: "en"

CLI复制当前环境(MCPClient.__init__)，所以按键如 FINNHUB_API_KEY, MARKETAUX_KEY，以及 NEWSAPI_KEY 可以住 .env。若要将机密置于版本控制之外，请创建 config/servers.local.yaml，将其添加到 .gitignore，并调用：

mcp-agent run --case A --prompt "$(cat prompt.txt)" --servers config/servers.local.yaml

用法

单次运行

mcp-agent run \
  --case A \
  --prompt "Summarize BTC and ETH price action over the last 24h." \
  --save-transcript \
  --pass-through-payloads
  • case 选择要使用的服务器组(runner.modes.servers_for_case).
  • --save-transcript 在JSON报告中保留原始提示/系统消息。
  • --pass-through-payloads 将原始工具有效载荷转发回响应日志以供检查。

A/B比较

mcp-agent compare --prompt "$(cat prompt.txt)"

两者都运行 case A （直接MCP工具）和 case B （exec代理过滤工具）背靠背，编写两个JSON报告，并打印并排的令牌摘要(runner.metrics.print_summary_table).

报告

每次运行都会在以下位置附加数据 reports/:

  • YYYYMMDDTHHMMSS_<CASE>.json –原始最终响应、工具使用计数、延迟、可选转录。
  • ab_runs.csv –适用于电子表格跟踪的聚合指标。

Git会忽略报告(.gitignore)因此，您可以在没有遥测泄漏的情况下发布repo。

测试

  • 单元/占位符测试上线 mcp_agent_cli/tests/.
  • pytest -m integration 使用API实时调用练习Anthropic客户端（需要 ANTHROPIC_API_KEY).
  • 其他确定性测试可以模拟 AnthropicClient.create_message 和 MCPClient.call_tool 以避免网络依赖性。

操作护栏

  • 秘密留在里面 .env 或者你的shell，从来没有内置过被跟踪的YAML。
  • 查看中的大型成绩单 reports/ 或 try_*.txt 在对外分享之前；如果它们包含专有提示，请清除。
  • 确保本地MCP服务器执行自己的身份验证/授权；此CLI假定使用受信任的本地传输。

贡献

  1. 分叉、分支并保持提交历史干净（没有提交的秘密或遥测）。
  2. 运行您添加的lint/tests；该项目有意保持轻量级。
  3. 提交PR，其中包含MCP服务器行为的上下文以及您引入的任何Anthropic/MCP协议假设。

相关 MCP