Context Bench

上下文工作台

衡量MCP服务器向编码代理提供上下文的准确性的基准

Context Bench衡量不同的MCP服务器如何有效地帮助AI代理理解和实现复杂的AI框架工作流程。它侧重于 onehot场景 其中单个MCP工具调用为编码代理提供文档上下文。

______________________________________________________________________

这个基准是什么

问题: *在实施现代人工智能框架时，哪个MCP服务器提供了最有效的上下文？*

• 任务：AI框架集成（Autogen、LangGraph、OpenAI代理、Agno、OpenRouter）
• MCP服务器已测试:

- 国家移民管理局：混合包搜索和文档回退 - 背景7：图书馆特定文档检索 - Deepcon：跨代码库的深入上下文理解 - Exa：语义网搜索和代码发现

______________________________________________________________________

基准测试是如何工作的

概述

Context Bench评估MCP服务器是否提供 充分的背景 用于实现复杂的AI框架工作流。与测试代码执行的传统基准不同，此基准衡量 文件完整性 -MCP服务器提供的上下文的质量和充分性。

场景设计

每个场景都经过精心设计 现实而富有挑战性

• 复杂查询场景需要分散在多个文档页面上的信息，模拟真实世界的开发任务，开发人员需要综合来自各种来源的知识（例如，在单个实现中结合流媒体、工具调用和错误处理）。

• Oracle代码创建：对于每个场景查询，我们根据场景中引用的官方文档创建oracle实现代码 sources 现场。此oracle代码表示 典型工作示例 如何使用框架推荐的模式和最佳实践来实现所请求的功能。

• 实际要求：查询指定了具体的任务（例如，“构建具有团队终止条件的多智能体系统”），而不是简单的API查找，测试MCP服务器是否可以为多方面实现提供全面的上下文。

目标是测试MCP服务器是否能够检索和呈现文档，使开发人员能够实现复杂的多组件功能，而不仅仅是查找单个API签名。

基准过程

┌─────────────────────────────────────────────────────────────────┐
│ Step 1: Query MCP Server (Oneshot Mode)                        │
│ • Send scenario query to MCP server                            │
│ • MCP server returns documentation/code examples               │
│ • Single tool call per scenario                                │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ Step 2: Multi-Model Evaluation                                 │
│ • 3 LLMs evaluate in parallel:                                 │
│   - GPT-5 (OpenAI)                                             │
│   - Grok-4 (xAI)                                               │
│   - Deepseek-v3.2 (Deepseek)                                   │
│ • Each model compares MCP context against oracle code          │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ Step 3: Scoring Criteria                                       │
│ • Completeness (Boolean): Can all requirements be inferred?    │
│   - API names, parameter types, return values                  │
│   - Usage patterns, error handling                             │
│ • Relevance (Boolean): Does context address the task?          │
│ • Overall Score (1-5): Quality assessment                      │
│ • Confidence (high/medium/low): Evaluator certainty            │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│ Step 4: Majority Vote Decision                                 │
│ • Completeness: 2/3 models must agree = PASS                   │
│ • Relevance: 2/3 models must agree = PASS                      │
│ • Final Verdict: BOTH must pass for scenario to pass           │
└─────────────────────────────────────────────────────────────────┘

评价哲学

我们评估的内容：

• ✅ MCP上下文是否包含足够的信息来实现oracle代码？
• ✅ API签名、参数和返回类型是否可以从示例中推断出来？
• ✅ 使用模式是否得到了清晰的展示？
• ✅ 文档是否涵盖了所有用户要求？

我们不评估的内容：

• ❌ 实现是否与oracle完全匹配（功能等效是可以的）
• ❌ 代码质量或风格
• ❌ 性能或效率

______________________________________________________________________

基准结果

MCP服务器的准确性

跨20个AI框架集成场景的多模型评估（GPT-5、Grok-4、Deepseek-v3.2）

关键发现Deepcon为AI框架集成任务提供了最有效的文档环境，成功率达到90%。

备注：基线测试使用Claude Sonnet 4.5，没有任何工具。如果没有外部工具，该模型无法成功实现20个AI框架集成场景中的任何一个（因为知识截止）。

MCP服务器的令牌使用情况

基于最近在20个场景中的基准测试：

关键发现：更多的令牌并不能保证更好的准确性。Deepcon仅用2365个平均令牌实现了90%的成功，而Context7提供了5626个令牌，但实现了65%的成功。

效率分析

上面的效率图显示了准确性和令牌使用之间的关系。Deepcon在理想象限（高精度、低令牌）中脱颖而出，展示了卓越的上下文质量和效率。

查看完整结果

完整的基准测试结果，包括详细的评估、MCP响应和每个场景的细分，可在 sample_workspace/。每个运行目录包含：

• 具有完整MCP上下文的单个场景结果
• 多模型评估分数和推理
• 每个场景的令牌使用统计
• MCP服务器汇总报告

示例：浏览 sample_workspace/run-2025-11-06-1653/ 查看4台MCP服务器上所有20个场景的完整基准运行。

______________________________________________________________________

快速开始

先决条件

• Node.js 18+ (下载)
• MCP服务器API密钥 （参见 配置)

安装

git clone https://github.com/your-org/context-bench.git
cd context-bench
npm install

设置

# Create environment file
cp .env.example .env

# Add your API keys
nano .env

所需的环境变量:

# MCP Server Credentials
NIA_API_KEY=your_nia_api_key
CONTEXT7_API_KEY=your_context7_api_key
DEEPCON_API_KEY=your_deepcon_api_key

# Evaluation
OPENROUTER_API_KEY=your_openrouter_api_key  # For multi-model evaluation

运行第一个基准测试

单一场景

# Test with NIA server
npx tsx harness/cli.ts \
  --scenario autogen:streaming-tools \
  --mode oneshot \
  --config nia

# Test with Context7 server
npx tsx harness/cli.ts \
  --scenario autogen:streaming-tools \
  --mode oneshot \
  --config context7

# Test with Deepcon server
npx tsx harness/cli.ts \
  --scenario autogen:streaming-tools \
  --mode oneshot \
  --config deepcon

多个场景

# Run all autogen scenarios with NIA
npx tsx harness/cli.ts \
  --package autogen \
  --mode oneshot \
  --config nia

# Run specific scenarios
npx tsx harness/cli.ts \
  --scenarios autogen:streaming-tools,langgraph:parallel-brief \
  --mode oneshot \
  --config context7

比较所有MCP服务器

# Run single scenario across all MCP configs
npx tsx harness/cli.ts \
  --scenario autogen:streaming-tools \
  --mode oneshot \
  --all-configs

# Run all scenarios with all configs (parallel execution)
npx tsx harness/cli.ts \
  --all-packages \
  --mode oneshot \
  --all-configs \
  --max-workers 4

预期输出:

Context Bench v1.0.0

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Run ID: run-2025-11-07-0900
Mode: oneshot
Scenarios: autogen:streaming-tools
Configs: nia
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

▶ Running config: nia

  ▶ Scenario: autogen:streaming-tools
    [1/8] Loading scenario specification... ✓
    [2/8] Validating environment variables... ✓
    [3/8] Initializing workspace... ✓
    [4/8] Applying MCP configuration... ✓
    [5/8] Running oneshot mode (single MCP tool call)... ✓
    [7.6/8] Evaluating result against oracle... ✓
    [8/8] Generating report... ✓

    ✓ PASS: 1/1 passed

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Results: 1/1 scenarios passed (100%)
Elapsed: 45.2s
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

______________________________________________________________________

基准结构

包和场景

基准包括 5个AI框架包 随着 20种情景:

scenarios/
├── autogen.yaml                  # Package definition
├── autogen/                      # Oracle implementations
│   ├── streaming_tools.py
│   ├── selector_groupchat.py
│   ├── team_termination.py
│   └── hitl_persist.py
├── langgraph.yaml
├── langgraph/
│   ├── parallel_brief.py
│   ├── hil_writer.py
│   ├── functional_review.py
│   └── two_agent_subgraphs.py
├── openai-agents.yaml
├── openai-agents/
│   ├── streaming_tools.py
│   ├── handoffs_guardrails.py
│   ├── sessions_context.py
│   └── realtime_agent.py
├── agno.yaml
├── agno/
│   ├── trend_scout.py
│   ├── content_team.py
│   ├── visual_explainer.py
│   └── copy_workflow.py
├── openrouter-sdk.yaml
└── openrouter-sdk/               # TypeScript implementations
    ├── usage_and_keys.ts
    ├── models_and_providers.ts
    ├── structured_tools.ts
    └── auto_router_stream.ts

包定义格式

每个包的定义见 .yaml 在 scenarios/ 根：

package-id: autogen
language: python                   # Runtime language
registry: py_pi                    # Package registry (py_pi, npm, for Nia)
context7-id: /microsoft/autogen    # Context7 library identifier
deepcon-id: autogen                # Deepcon package name (optional)

scenarios:
  - id: streaming-tools
    query: "Using the Autogen Python library, build an agent with tool
            calling and streaming capabilities. Plan a 30-second 'market
            brief' for EUR→KRW travelers..."
    oracle: scenarios/autogen/streaming_tools.py
    sources:
      - https://microsoft.github.io/autogen/dev/user-guide/agentchat-user-guide/quickstart.html
      - https://microsoft.github.io/autogen/dev/user-guide/agentchat-user-guide/tutorial/agents.html

  - id: selector-groupchat
    query: "Using the Autogen Python library with selector-based group
            chat, create a small research 'crew': (1) Plan subtasks;
            (2) run a mock web search; (3) compute a percentage change..."
    oracle: scenarios/autogen/selector_groupchat.py
    sources:
      - https://microsoft.github.io/autogen/dev/user-guide/agentchat-user-guide/tutorial/selector-group-chat.html

runtime:
  version: "python3.11"

env_vars:
  OPENAI_API_KEY: "${OPENAI_API_KEY}"

Oracle文件

每个场景都有一个oracle实现文件（Python .py 或TypeScript .ts)其中包含参考实现代码。多模型评估系统使用这些oracle实现来评估MCP提供的文档是否包含足够的信息来实现所需的功能。

备注：大多数软件包都使用Python，但是 openrouter-sdk 使用TypeScript，因为它是一个npm包。

______________________________________________________________________

了解结果

目录结构

workspace/
└── run-2025-11-07-0900/
    ├── oneshot/                          # Oneshot execution results
    │   ├── nia/                          # NIA MCP server results
    │   │   ├── autogen:streaming-tools/
    │   │   │   ├── oneshot_result.md    # Raw MCP response
    │   │   │   ├── final_result.md      # Full report with evaluation
    │   │   │   └── evaluation_oneshot.json
    │   │   └── autogen:selector-groupchat/
    │   ├── context7/                     # Context7 results
    │   └── deepcon/                      # Deepcon results
    ├── nia/
    │   └── nia_result.md                 # Config summary + token stats
    ├── context7/
    │   └── context7_result.md
    └── deepcon/
        └── deepcon_result.md

______________________________________________________________________

CLI参考

主CLI选项

npx tsx harness/cli.ts [options]

Options:
  --package          Run all scenarios in a package
  --scenario 
      Run specific scenario (format: package:scenario)
  --scenarios         Comma-separated scenario IDs
  --mode             Execution mode: oneshot or agent (default: agent)
  --config           MCP configuration (nia, context7, deepcon)
  --all-configs            Run with all MCP configurations
  --all-packages           Run all packages
  --max-workers         Parallel execution limit (default: 1)
  --timeout       Timeout per scenario (default: 120)
  --verbose                Detailed logging to stdout
  --list-packages          List all available packages
  --list-scenarios         List all available scenarios
  --list-configs           List all available MCP configs
  --show-package     Show package details
  --show-scenario      Show scenario details

列出命令

# List all packages
npx tsx harness/cli.ts --list-packages

# List all scenarios
npx tsx harness/cli.ts --list-scenarios

# List all MCP configs
npx tsx harness/cli.ts --list-configs

# Show package details
npx tsx harness/cli.ts --show-package autogen

# Show scenario details
npx tsx harness/cli.ts --show-scenario autogen:streaming-tools

______________________________________________________________________

令牌计数

在一个热门结果中计数令牌：

# Count tokens for specific config and run
npx tsx scripts/count-tokens.ts workspace/run-2025-11-07-0900 nia

# Count tokens for all configs in a run
npx tsx scripts/count-tokens.ts workspace/run-2025-11-07-0900

# Output
============================================================
Processing config: nia
============================================================
Counting tokens for nia/autogen:streaming-tools...
Counting tokens for nia/autogen:selector-groupchat...
...
✅ Token statistics appended to workspace/run-2025-11-07-0900/nia/nia_result.md
   Total scenarios: 20
   Total tokens: 37,457
   Average tokens: 1,873

令牌统计信息会自动附加到配置摘要标记文件中。

______________________________________________________________________

添加新场景

1.创建包目录

mkdir -p scenarios/new-framework

2.定义包

创建 scenarios/new-framework.yaml 在 scenarios/ 根目录：

package-id: new-framework
language: python
registry: py_pi
context7-id: /company/new-framework
deepcon-id: new-framework

scenarios:
  - id: basic-agent
    query: "Using the New Framework, create a basic agent that can respond
            to user queries with streaming output."
    oracle: scenarios/new-framework/basic_agent.py
    sources:
      - https://docs.new-framework.ai/quickstart
      - https://docs.new-framework.ai/streaming

  - id: multi-agent-team
    query: "Build a multi-agent team with task delegation and result
            aggregation."
    oracle: scenarios/new-framework/multi_agent_team.py
    sources:
      - https://docs.new-framework.ai/multi-agent

runtime:
  version: "python3.11"

env_vars:
  OPENAI_API_KEY: "${OPENAI_API_KEY}"

3.创建Oracle文件

创建 scenarios/new-framework/basic_agent.py:

"""
Oracle implementation for basic-agent scenario.
This is the reference implementation used for evaluation.
"""
from new_framework import Agent

def main():
    # Initialize agent with streaming
    agent = Agent(
        model="gpt-4",
        streaming=True
    )

    # Handle user query
    for chunk in agent.stream("Tell me about AI"):
        print(chunk, end="", flush=True)

if __name__ == "__main__":
    main()

4.测试

# Test with single MCP server
npx tsx harness/cli.ts \
  --scenario new-framework:basic-agent \
  --mode oneshot \
  --config nia

# Test with all servers
npx tsx harness/cli.ts \
  --scenario new-framework:basic-agent \
  --mode oneshot \
  --all-configs

5.添加NIA回退（如果需要）

如果包不在PyPI/NMP注册表中，请在中添加回退映射 harness/oneshot-runner.ts:

const NIA_DOC_FALLBACK_MAP: Record = {
  'autogen': '5cc05f18-2f15-4046-885d-4dd9cb4c5f59',
  'openrouter-sdk': 'https://openrouter.ai/docs',
  'new-framework': 'https://docs.new-framework.ai',  // Add this
};

6.Deepcon ID覆盖（可选）

如果Deepcon MCP服务器需要的包名与 package-id，添加 deepcon-id 到你的YAML：

package-id: openai-agents
deepcon-id: agents-sdk    # Deepcon uses "agents-sdk" instead of "openai-agents"

当 deepcon-id 如果指定了，它将用作 name 调用Deepcon时的参数 search_documentation 工具。否则， package-id 默认情况下使用。

______________________________________________________________________

🛠️ 配置

MCP服务器配置

MCP服务器定义 mcp-configs/:

// mcp-configs/nia.ts
export const niaConfig: MCPConfig = {
  config_name: 'nia',
  description: 'Claude Code + NIA MCP (stdio)',
  mcp_servers: {
    nia: {
      command: 'uvx',
      args: ['nia-mcp-server'],
      env: {
        NIA_API_KEY: process.env.NIA_API_KEY!,
      },
    },
  },
  env_requirements: ['NIA_API_KEY'],
};

环境变量

创建 .env 文件：

# MCP Server API Keys
NIA_API_KEY=your_nia_api_key_here
CONTEXT7_API_KEY=your_context7_api_key_here
DEEPCON_API_KEY=your_deepcon_api_key_here

# Evaluation
OPENROUTER_API_KEY=your_openrouter_api_key_here

# Optional: Specific evaluation models
EVALUATOR_MODELS=openai/gpt-5,x-ai/grok-4,deepseek/deepseek-v3.2-exp

______________________________________________________________________

贡献

欢迎投稿！拜托：

1. 在包结构之后添加新场景
2. 包含全面的oracle文件
3. 使用所有MCP配置进行测试
4. 添加场景后更新令牌统计信息

______________________________________________________________________

许可证

MIT许可证-请参阅 许可证 了解详情。

______________________________________________________________________

链接

• 模型上下文协议
• NIA MCP服务器
• 上下文7文档
• Deepcon MCP

______________________________________________________________________

专为AI框架文档研究而构建