pymcpevals (Akshay5995)

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

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

运作原理

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

是什么让这与众不同

精确的工具断言：与判断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 format

Pytest集成

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集成和监控功能。

贡献

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

许可证

MIT-请参阅许可证文件。