Benchmark GitHub MCP

GitHub MCP基准测试

比较使用GitHub的模型上下文协议（MCP）服务器的架构方法中的令牌使用情况、成本和DIRT（远程传输数据）。

支持的MCP服务器

两种情景

1.常规-完整MCP上下文

LangGraph代理将所有可用的MCP工具加载到上下文中。GPT-5.1选择并执行适当的工具。

• 权衡：完全控制+可观察性，高令牌成本
• 泥土：约170 KB| 成本：约0.015美元/请求

2.TSBX-直接委托

直接委派TaskSandbox。TSBX代理具有本地MCP工具调用功能，可以直接调用MCP工具。

• 权衡：最低令牌/DIRT，自主执行
• 泥土：约10-20kb| 成本：~0.001-0.003/请求

体系结构比较

┌─────────────────────────────────────────────────────────────┐
│ Scenario 1: Conventional                                    │
│   LangGraph → list ALL tools → GPT-5.1 selects → MCP        │
│   Trade-off: Full control, high tokens                      │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ Scenario 2: TSBX                                            │
│   Script → TSBX agent (with MCP) → MCP Server → Result      │
│   Trade-off: Lowest cost, black box                         │
└─────────────────────────────────────────────────────────────┘

快速开始

TL；DR-通过自动比较运行两种场景

# Activate environment
source .venv/bin/activate

# Run both scenarios (conventional + TSBX) and auto-generate comparison
python run_benchmark_suite.py \
  --manifest github-data/manifest.json \
  --scenario both

# Output:
# - results/benchmark_suite/github/conventional_TIMESTAMP/
# - results/benchmark_suite/github/tsbx_TIMESTAMP/
# - results/comparison_github_TIMESTAMP.json (auto-generated!)

1.先决条件

# Python 3.13+ required
python3 --version

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

2.配置环境

创建 .env 文件：

# Required: OpenAI (GPT-5.1 for conventional scenario)
OPENAI_API_KEY=sk-proj-xxxxx

# MCP Server API Keys
# GitHub MCP
GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxx

# Required for Scenario 2: TaskSandbox (local instance)
TASKSANDBOX_API_KEY=your_local_token_here
TASKSANDBOX_BASE_URL=http://localhost:3000
INFERENCE_PROVIDER=Hyperbolic
INFERENCE_API_KEY=your_hyperbolic_key_here

# Optional: LangSmith observability
LANGCHAIN_API_KEY=lsv2_pt_xxxxx
LANGCHAIN_TRACING_V2=true
LANGCHAIN_PROJECT=mcp-benchmark

获取API密钥

GitHub个人访问令牌:

1. 访问https://github.com/settings/tokens
2. 生成新令牌（经典）
3. 选择范围： repo, read:org, read:user

3.在本地运行TSBX

备注：目前没有可用的TSBX托管版本。要运行TSBX场景，您需要在本地运行TSBX。

克隆并运行支持MCP的TSBX:

# Clone the TSBX repository with MCP support
git clone -b feature/mcp https://github.com/RactorLabs/tsbx.git
cd tsbx

# Follow the build instructions in the TSBX README
# (Mac-specific build instructions are documented there)

# Start TSBX (typically on port 3000)
# Refer to TSBX README for specific startup commands

更新您的 .env 对于本地TSBX:

# Point to your local TSBX instance
TASKSANDBOX_BASE_URL=http://localhost:3000
TASKSANDBOX_API_KEY=your_local_token_here

# Other required variables remain the same
INFERENCE_PROVIDER=Hyperbolic
INFERENCE_API_KEY=your_hyperbolic_key_here

重要：The feature/mcp 分支包含此基准测试所需的MCP支持。在构建之前，请确保您已使用此分支。

4.测试MCP连接

# Test GitHub MCP client
python test_github_mcp.py

5.运行Benchmark Suite

基准套件运行者(run_benchmark_suite.py)自动从清单中检测MCP服务器类型并运行所有任务。

运行GitHub基准测试

# Run all GitHub tasks with conventional scenario
python run_benchmark_suite.py \
  --manifest github-data/manifest.json \
  --scenario conventional

# Run specific GitHub tasks
python run_benchmark_suite.py \
  --manifest github-data/manifest.json \
  --tasks GH-SIMPLE-001,GH-SIMPLE-002,GH-SIMPLE-003

# Quick test with simple tasks only
python run_benchmark_suite.py \
  --manifest github-data/manifest.json \
  --level 1

建筑

run_benchmark_suite.py
  └─> For each task:
        │
        ├─> Scenario 1: Conventional
        │     └─> run_conventional_scenario(task, mcp_type)
        │           └─> LangGraph workflow (GPT-5.1)
        │                 ├─ load_tools (dynamically from MCP server)
        │                 ├─ select_tool (pick appropriate tool)
        │                 ├─ execute_tool (call MCP)
        │                 └─ process_response (format result)
        │
        └─> Scenario 2: TSBX
              └─> run_tsbx_programmatic_scenario(task, mcp_type)
                    └─> TaskSandbox agent (native MCP support)
                          ├─ Autonomous tool discovery
                          ├─ Direct MCP tool calling
                          └─ Answer synthesis

筛选选项

按级别 （1=简单，6=复杂）：

--level 1              # Only Level 1 tasks
--level 1-3            # Level 1, 2, and 3 tasks
--level 4-6            # Complex tasks only

按难度 （1=容易，6=难）：

--difficulty 1-2       # Easy tasks
--difficulty 5-6       # Hard tasks

按类型:

--type read            # Read-only operations
--type write           # Operations that modify data

输出和结果

按MCP服务器类型组织的结果:

• GitHub: results/benchmark_suite/github/{scenario}_{timestamp}/

每个任务JSON (task_GH-SIMPLE-001_conventional.json):

{
  "task_id": "GH-SIMPLE-001",
  "task_name": "List repositories for user",
  "scenario": "conventional",
  "execution_model": "gpt-5.1",
  "total_metrics": {
    "total_tokens": 8765,
    "total_cost": 0.0987,
    "total_latency_seconds": 2.5
  },
  "success": true,
  "accuracy_score": 1.0
}

汇总统计 (summary.json):

{
  "total_tasks": 10,
  "successful_tasks": 9,
  "success_rate": 0.90,
  "total_tokens": 87650,
  "total_cost": 5.50,
  "avg_tokens_per_task": 8765,
  "avg_cost_per_task": 0.55,
  "by_level": {
    "1": {"count": 5, "success_rate": 1.0, "avg_cost": 0.25},
    "2": {"count": 3, "success_rate": 0.83, "avg_cost": 0.35}
  }
}

常见工作流

运行多个场景：

# Run both conventional and TSBX scenarios together
python run_benchmark_suite.py --manifest github-data/manifest.json --scenario both

比较场景（传统与TSBX）：

# Run BOTH scenarios and auto-generate comparison (recommended!)
python run_benchmark_suite.py \
  --manifest github-data/manifest.json \
  --scenario both

# This will:
# 1. Run conventional scenario
# 2. Run TSBX scenario
# 3. Auto-generate timestamped comparison file: results/comparison_github_TIMESTAMP.json
# 4. Print comparison summary to console

# Or run scenarios individually:
# Conventional only
python run_benchmark_suite.py --manifest github-data/manifest.json

# TSBX only
python run_benchmark_suite.py --manifest github-data/manifest.json --scenario tsbx

# Manual comparison of individual runs
python compare_scenarios.py \
  results/benchmark_suite/github/conventional_TIMESTAMP \
  results/benchmark_suite/github/tsbx_TIMESTAMP

6.查看结果

基准套件结果:

# View summary statistics
cat results/benchmark_suite/github/conventional_TIMESTAMP/summary.json

# View individual task result
cat results/benchmark_suite/github/conventional_TIMESTAMP/task_GH-SIMPLE-001_conventional.json

# Compare metrics across scenarios
jq '.total_cost' results/benchmark_suite/github/*/summary.json

衡量指标

DIRT故障

DIRT跟踪通过网络传输的所有数据：

• LLM KB：发送到/来自OpenAI API的数据
• 工具知识库：发送到MCP服务器/从MCP服务器发送的数据
• LangSmith KB：估计可观测性开销（1.5倍LLM流量）

为什么要估计LangSmith？ LangSmith在后台自动运行（当 LANGCHAIN_TRACING_V2=true).如果没有网络拦截，我们无法直接测量它，但我们知道它发送的跟踪数据大致等于LLM流量加元数据，所以我们估计它是1.5倍。

MCP服务器工具

GitHub MCP（10+工具）

这 @modelcontextprotocol/server-github 提供以下工具：

存储库：

• 列出用户/组织的存储库
• 获取存储库元数据
• 创建/更新存储库

问题：

• 列出问题（带过滤器）
• 按标签搜索问题
• 创建/更新问题

拉取请求：

• 列出拉取请求
• 获取PR审核状态
• 创建/更新PR

承诺：

• 列表提交
• 获取提交详细信息

还有更多 -快跑 python test_github_mcp.py 查看所有可用工具。

CLI选项

Benchmark Suite Runner(run_benchmark_suite.py)

python run_benchmark_suite.py [OPTIONS]

Options:
  --manifest TEXT         Path to benchmark manifest JSON (required)
  --scenario TEXT         conventional | tsbx | tsbx-pg | both | all (default: conventional)
  --level TEXT           Filter by level (e.g., "1", "1-3", "4-6")
  --difficulty TEXT      Filter by difficulty (e.g., "1-3")
  --type TEXT            Filter by type (read | write)
  --tasks TEXT           Comma-separated task IDs (e.g., "GH-SIMPLE-001,GH-MEDIUM-005")
  --iterations INT       Number of times to run each task (default: 1)
  --output-dir TEXT      Output directory (default: results/benchmark_suite)

备注：从清单元数据中自动检测MCP服务器类型。

LangSmith的可观察性

当 LANGCHAIN_TRACING_V2=true 设置后，所有LangGraph/LangChain操作都会自动跟踪到LangSmith：

• 查看完整的执行跟踪
• 查看所有带有提示/响应的LLM呼叫
• 跟踪工具执行情况
• 分析延迟瓶颈

查看痕迹: https://smith.langchain.com/（项目： mcp-benchmark)

故障排除

身份验证错误（401）

Error: Authentication credentials not found

解决方案：验证您的GitHub个人访问令牌：

• 检查它开始于 ghp_ 或 github_pat_
• 验证范围包括 repo, read:org, read:user
• 如果需要，重新生成令牌

未找到MCP服务器

Error: @
/mcp-server not found

解决方案：MCP服务器通过以下方式运行 npx，按需下载。确保你已经安装了Node.js/npm：

node --version  # Should be v18+
npm --version

错误：“未知MCP类型：'github'”

工厂找不到GitHub客户端。确保：

• github_mcp_client.py 存在于 src/clients/
• 文件中没有语法错误
• 跑 python test_github_mcp.py 测试

Python版本错误

SyntaxError: invalid syntax

解决方案：确保你使用的是Python 3.13+：

python3 --version
source .venv/bin/activate  # Use the venv

型号定价

执行模型

成本跟踪：结果跟踪每个场景的总代币和成本，以便直接比较。

研究问题

1. 全工具环境是否证明成本合理？

- 常规将所有工具传递给LLM（~11K+令牌） - TSBX的编排开销最小 - 实践中的成本差异是什么？

1. 控制与效率

- 常规：完全控制、完全可观察性、高成本 - TSBX：自主执行，成本最低 - 哪种方法更适合不同的任务类型？

1. 本地MCP支持影响

- TSBX的原生MCP工具调用与LangGraph编排相比如何？ - 性能和成本影响是什么？

项目结构

github-mcp-benchmark/
├── src/
│   ├── clients/
│   │   ├── base_mcp_client.py          # Abstract base class
│   │   ├── mcp_client_factory.py       # Factory pattern
│   │   ├── github_mcp_client.py        # GitHub implementation
│   │   └── tasksandbox_client.py       # TaskSandbox client
│   ├── scenarios/
│   │   ├── scenario1_conventional.py   # Conventional approach
│   │   └── scenario3_tsbx_direct.py    # TSBX delegation
│   ├── measurement/
│   │   └── dirt_tracker.py             # DIRT metrics
│   └── utils/
│       ├── config.py                   # Configuration
│       └── validator.py                # Ground truth validation
├── github-data/                        # GitHub manifests & ground truth
├── results/
│   └── benchmark_suite/
│       └── github/                     # GitHub results
├── run_benchmark_suite.py              # Main runner
├── test_github_mcp.py                  # Test GitHub client
└── README.md                           # This file

参考文献

• 模型上下文协议
• LangGraph文档
• GAIA基准 -参考实施

______________________________________________________________________

建于：Python 3.13、LangGraph、OpenAI GPT-5.1、多个MCP服务器 2025年12月