PyMCPEvals

⚠️ 正在开发中 - API可能会发生变化。生产环境中请谨慎使用。

针对MCP（模型上下文协议）服务器的评估框架。

🚀 测试您的MCP服务器功能，而不是LLM对话模式。

“我的MCP服务器工具是否按预期工作？”

PyMCPEvals 分离了您可以控制（服务器）和无法控制（LLM行为）的内容：

✅ 您可以控制的（我们测试这些）

• 工具实现正确性
• 工具参数验证
• 错误处理与恢复
• 工具结果格式化
• 多轮状态管理

❌ 您无法控制的（我们忽略这些）

• LLM对话模式
• LLM如何选择使用工具
• LLM响应格式化
• LLM是否提供中间响应

解决的关键痛点

• 🚫 手动工具测试：自动化断言验证精确的工具调用
• ❓ 多步骤失败：跟踪跨对话回合的工具链
• 🐛 静默工具错误：当预期工具未被调用时立即反馈
• 📊 CI/CD集成：JUnit XML输出用于自动化测试流水线

快速开始

pip install pymcpevals
pymcpevals init                    # 创建模板配置
pymcpevals run evals.yaml         # 运行评估

示例配置

model:
  provider: openai
  name: gpt-4

server:
  command: ["python", "my_server.py"]

evaluations:
  - name: "weather_check"
    prompt: "波士顿的天气怎么样？"
    expected_tools: ["get_weather"]  # ✅ 验证工具使用
    expected_result: "应调用天气API并返回条件"
    threshold: 3.5
    
  - name: "multi_step"
    turns:
      - role: "user"
        content: "伦敦的天气怎么样？"
        expected_tools: ["get_weather"]
      - role: "user"  
        content: "巴黎呢？"
        expected_tools: ["get_weather"]
    expected_result: "应提供两个城市的天气"
    threshold:  4.0

输出：通过/失败状态、工具验证、执行指标和服务器评分。

它是如何工作的

1. 连接到您的MCP服务器通过FastMCP
2. 执行提示并跟踪工具调用
3. 验证预期工具是否被调用（即时反馈）
4. 评估服务器性能（忽略LLM风格）
5. 报告结果并提供可操作见解

有何不同

精确工具断言：与传统的评估判断LLM响应不同，PyMCPEvals 验证：

• ✅ 精确工具调用：assert_tools_called(result, ["add", "multiply"])
• ✅ 工具执行成功：assert_no_tool_errors(result)
• ✅ 多轮轨迹：测试跨对话步骤的工具链
• ✅ 即时故障检测：无需昂贵的LLM评估即可检测明显故障

使用方法

命令行界面

# 基本用法
pymcpevals run evals.yaml

# 覆盖服务器/模型
pymcpevals run evals.yaml --server "node server.js" --model gpt-4

# 不同输出
pymcpevals run evals.yaml --output table    # 简单表格
pymcpevals run evals.yaml --output json     # 完整JSON
pymcpevals run evals.yaml --output junit    # CI/CD格式

Pytest集成

from pymcpevals import (
    assert_tools_called, 
    assert_evaluation_passed,
    assert_min_score,
    assert_no_tool_errors,
    ConversationTurn
)

# 简单标记测试
@pytest.mark.mcp_eval(
    prompt="15加27等于多少？",
    expected_tools=["add"],
    min_score=4.0
)
async def test_basic_addition(mcp_result):
    assert_evaluation_passed(mcp_result)
    assert_tools_called(mcp_result, ["add"])
    assert "42" in mcp_result.server_response

# 多轮轨迹测试
async def test_math_sequence(mcp_evaluator):
    turns = [
        ConversationTurn(role="user", content="10加5等于多少？", expected_tools=["add"]),
        ConversationTurn(role="user", content="现在乘以2", expected_tools=["multiply"])
    ]
    result = await mcp_evaluator.evaluate_trajectory(turns, min_score=4.0)
    
    # 丰富的断言
    assert_evaluation_passed(result)
    assert_tools_called(result, ["add", "multiply"])
    assert_no_tool_errors(result)
    assert_min_score(result, 4.0, dimension="accuracy")
    assert "30" in str(result.conversation_history)

# 运行：pytest -m mcp_eval

示例

查看examples/目录中的内容：

• calculator_server.py - 用于测试的简单MCP服务器
• local_server_basic.yaml - 基本评估配置示例
• trajectory_evaluation.yaml - 多轮对话示例
• test_simple_plugin_example.py - Pytest集成示例

运行示例：

# 使用示例计算器服务器进行测试
pymcpevals run examples/local_server_basic.yaml

# 运行pytest示例
cd examples && pytest test_simple_plugin_example.py

安装

pip install pymcpevals

环境设置

export OPENAI_API_KEY="sk-..."        # 或 ANTHROPIC_API_KEY
export GEMINI_API_KEY="..."           # 用于Gemini模型

输出格式

表格视图（默认）

┌──────────────────────────────────────────┬────────┬─────┬──────┬─────┬──────┬──────┬──────┬───────┐
│ 名称                                     │ 状态 │ 准确度 │ 完整度 │ 相关度 │ 清晰度 │ 合理性 │ 平均分 │ 工具 │
├──────────────────────────────────────────┼────────┼─────┼──────┼─────┼──────┼──────┼──────┼───────┤
│ 15加27等于多少？                         │ 通过   │ 4.5 │ 4.2  │ 5.0 │ 4.8  │ 4.1  │ 4.52 │ ✓     │
│ 如果我将10除以0会发生什么？              │ 通过   │ 4.0 │ 4.1  │ 4.5 │ 4.2  │ 3.8  │ 4.12 │ ✓     │
│ 多轮测试                                 │ 通过   │ 4.2 │ 4.5  │ 4.8 │ 4.1  │ 4.3  │ 4.38 │ ✓     │
└──────────────────────────────────────────┴────────┴─────┴──────┴─────┴──────┴──────┴──────┴───────┘

总结：3/3通过（100.0%）- 平均分：4.34/5.0

详细视图（--output detailed）

┌─────────────────────────┬────────┬──────┬────────────────────┬────────────────────┬────────┬────────┬──────────────────────────────┐
│ 测试                    │ 状态 │ 得分│ 预期工具     │ 实际使用的工具         │ 时间   │ 错误数 │ 备注                        │
├─────────────────────────┼────────┼──────┼────────────────────┼────────────────────┼────────┼────────┼──────────────────────────────┤
│ 15加27等于多少？        │ 通过   │ 4.5  │ add                │ add                │ 12ms   │ 0      │ 正常                           │
│ 如果我将10除以0会……     │ 通过   │ 4.1  │ divide             │ divide             │ 8ms    │ 1      │ 正确处理错误                  │
│ 多轮测试               │ 通过   │ 4.4  │ add, multiply      │ add, multiply      │ 23ms   │ 0      │ 工具链成功                     │
└─────────────────────────┴────────┴──────┴────────────────────┴────────────────────┴────────┴────────┴──────────────────────────────┘

🔧 工具执行详情：
• add: 调用2次，平均10ms，100%成功率
• divide: 调用1次，8ms，优雅处理错误  
• multiply: 调用1次，13ms，100%成功率

总结：3/3通过（100.0%）- 平均分：4.33/5.0

关键优势

对于MCP服务器开发者

• 🎯 服务器聚焦测试：测试您的服务器功能，而不是LLM行为
• ✅ 即时工具验证：如果调用了错误的工具，立即获得反馈（无需LLM）
• 🔧 工具执行洞察：查看成功率、时间以及错误处理
• 🔄 多轮验证：测试工具链和状态管理
• 📊 功能评分：LLM评判服务器工具性能，忽略对话风格
• 🛠️ 易于集成：通过FastMCP与任何MCP服务器兼容

对于开发团队

• 🚀 CI/CD集成：JUnit XML输出用于自动化测试流水线
• 📈 进展追踪：随着时间推移，通过一致评分监控改进
• 🔄 回归测试：确保新更改不会破坏现有功能
• ⚖️ 模型比较：跨不同LLM提供商进行测试

致谢

🙏 特别感谢mcp-evals - 这个Python包深受@mclenhard的出色Node.js实现的启发。

如果您在Node.js环境中工作，请务必查看原始的mcp-evals项目，它还包括GitHub Actions集成和监控功能。

贡献

1. 分叉仓库
2. 创建功能分支
3. 为新功能添加测试
4. 确保所有测试通过
5. 提交拉取请求

许可证

MIT - 查看LICENSE文件。 </中文翻译>