PyMCPEvals
⚠️ 仍在开发中 -API可能会发生变化。生产中请谨慎使用。
MCP（模型上下文协议）服务器的以服务器为中心的评估框架。
🚀 测试您的MCP服务器功能，而不是LLM对话模式。
“我的MCP服务器的工具是否正常工作并按预期使用？”
PyMCPEvals将您的 控制 （服务器）从你 不能 （LLM行为）：
✅ 你控制什么（我们测试一下）
- 工具实施正确性
- 工具参数验证
- 错误处理和恢复
- 工具结果格式化
- 多转弯状态管理
❌ 你无法控制的事情（我们忽略了这一点）
- LLM对话模式
- LLM如何选择使用工具
- LLM响应格式
- LLM是否提供中间响应
关键痛点已解决
- 🚫 手动工具测试：自动断言验证确切的工具调用
- ❓ 多步故障：跨对话回合跟踪工具链
- 🐛 无声工具错误：未调用预期工具时的即时反馈
- 📊 CI/CD集成：用于自动化测试管道的JUnitXML输出
快速开始
pip install pymcpevals
pymcpevals init # Create template config
pymcpevals run evals.yaml # Run evaluations配置示例
model:
provider: openai
name: gpt-4
server:
command: ["python", "my_server.py"]
evaluations:
- name: "weather_check"
prompt: "What's the weather in Boston?"
expected_tools: ["get_weather"] # ✅ Validates tool usage
expected_result: "Should call weather API and return conditions"
threshold: 3.5
- name: "multi_step"
turns:
- role: "user"
content: "What's the weather in London?"
expected_tools: ["get_weather"]
- role: "user"
content: "And in Paris?"
expected_tools: ["get_weather"]
expected_result: "Should provide weather for both cities"
threshold: 4.0输出：通过/失败状态、工具验证、执行指标和以服务器为中心的评分。
运作原理
- 连接 通过FastMCP连接到您的MCP服务器
- 执行 提示和跟踪工具调用
- 验证 预期的工具被称为（即时反馈）
- 评估 服务器性能（忽略LLM样式）
- 报告 具有可操作见解的结果
是什么让这与众不同
精确的工具断言：与判断LLM反应的传统评估不同，PyMCPEvals验证：
- ✅ 精确的工具调用:
assert_tools_called(result, ["add", "multiply"]) - ✅ 工具执行成功:
assert_no_tool_errors(result) - ✅ 多转弯轨迹：跨对话步骤的测试工具链接
- ✅ 即时故障检测：无需对明显故障进行昂贵的法学硕士评估
用法
命令行界面
# Basic usage
pymcpevals run evals.yaml
# Override server/model
pymcpevals run evals.yaml --server "node server.js" --model gpt-4
# Different outputs
pymcpevals run evals.yaml --output table # Simple table
pymcpevals run evals.yaml --output json # Full JSON
pymcpevals run evals.yaml --output junit # CI/CD formatPytest集成
from pymcpevals import (
assert_tools_called,
assert_evaluation_passed,
assert_min_score,
assert_no_tool_errors,
ConversationTurn
)
# Simple marker-based test
@pytest.mark.mcp_eval(
prompt="What is 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
# Multi-turn trajectory testing
async def test_math_sequence(mcp_evaluator):
turns = [
ConversationTurn(role="user", content="What is 10 + 5?", expected_tools=["add"]),
ConversationTurn(role="user", content="Now multiply by 2", expected_tools=["multiply"])
]
result = await mcp_evaluator.evaluate_trajectory(turns, min_score=4.0)
# Rich assertions
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)
# Run with: pytest -m mcp_eval例子
看看 examples/ 目录：
calculator_server.py-用于测试的简单MCP服务器local_server_basic.yaml-基本评估配置示例trajectory_evaluation.yaml-多回合对话示例test_simple_plugin_example.py-Pytest集成示例
运行示例：
# Test with the example calculator server
pymcpevals run examples/local_server_basic.yaml
# Run pytest examples
cd examples && pytest test_simple_plugin_example.py安装
pip install pymcpevals环境设置
export OPENAI_API_KEY="sk-..." # or ANTHROPIC_API_KEY
export GEMINI_API_KEY="..." # for Gemini models输出格式
表视图（默认）
┌──────────────────────────────────────────┬────────┬─────┬──────┬─────┬──────┬──────┬──────┬───────┐
│ Name │ Status │ Acc │ Comp │ Rel │ Clar │ Reas │ Avg │ Tools │
├──────────────────────────────────────────┼────────┼─────┼──────┼─────┼──────┼──────┼──────┼───────┤
│ What is 15 + 27? │ PASS │ 4.5 │ 4.2 │ 5.0 │ 4.8 │ 4.1 │ 4.52 │ ✓ │
│ What happens if I divide 10 by 0? │ PASS │ 4.0 │ 4.1 │ 4.5 │ 4.2 │ 3.8 │ 4.12 │ ✓ │
│ Multi-turn test │ PASS │ 4.2 │ 4.5 │ 4.8 │ 4.1 │ 4.3 │ 4.38 │ ✓ │
└──────────────────────────────────────────┴────────┴─────┴──────┴─────┴──────┴──────┴──────┴───────┘
Summary: 3/3 passed (100.0%) - Average: 4.34/5.0详细视图（--输出详细）
┌─────────────────────────┬────────┬──────┬────────────────────┬────────────────────┬────────┬────────┬──────────────────────────────┐
│ Test │ Status │ Score│ Expected Tools │ Tools Used │ Time │ Errors │ Notes │
├─────────────────────────┼────────┼──────┼────────────────────┼────────────────────┼────────┼────────┼──────────────────────────────┤
│ What is 15 + 27? │ PASS │ 4.5 │ add │ add │ 12ms │ 0 │ OK │
│ What happens if I div...│ PASS │ 4.1 │ divide │ divide │ 8ms │ 1 │ Handled error correctly │
│ Multi-turn test │ PASS │ 4.4 │ add, multiply │ add, multiply │ 23ms │ 0 │ Tool chaining successful │
└─────────────────────────┴────────┴──────┴────────────────────┴────────────────────┴────────┴────────┴──────────────────────────────┘
🔧 Tool Execution Details:
• add: Called 2 times, avg 10ms, 100% success rate
• divide: Called 1 time, 8ms, handled error gracefully
• multiply: Called 1 time, 13ms, 100% success rate
Summary: 3/3 passed (100.0%) - Average: 4.33/5.0关键利益
面向MCP服务器开发人员
- 🎯 以服务器为中心的测试：测试服务器功能，而不是LLM行为
- ✅ 即时工具验证：如果调用了错误的工具，请立即获得反馈（不需要LLM）
- 🔧 工具执行见解：查看成功率、时间和错误处理
- 🔄 多回合验证：测试工具链和状态管理
- 📊 能力评分：LLM判断服务器工具性能，忽略对话风格
- 🛠️ 易于集成：通过FastMCP与任何MCP服务器配合使用
对于开发团队
- 🚀 CI/CD集成：用于自动化测试管道的JUnitXML输出
- 📈 进度跟踪：通过一致的评分监控随时间的改进
- 🔄 回归测试：确保新更改不会破坏现有功能
- ⚖️ 模型比较：跨不同LLM提供商进行测试
致谢
如果你在Node.js环境中工作，一定要查看原始版本 mcp评估 该项目还包括GitHub Action集成和监控功能。
贡献
- 分叉存储库
- 创建要素分支
- 添加新功能的测试
- 确保所有测试通过
- 提交拉取请求
许可证
MIT-请参阅许可证文件。