Pytest Mcp Server

Pytest MCP 服务

一个用于依据系统化调试原则调试 pytest 故障的模型上下文协议（MCP）服务。

✅ 状态：已可用于生产环境

此 MCP 服务功能齐全，可直接使用。全部 8 个工具均可正常工作，并具备完善的错误处理和响应格式，符合官方 MCP 规范。

🧪 测试状态

✅ 服务功能：完美

• 所有工具都能使用有效输入正常工作
• 对无效输入进行适当的错误处理
• 符合 MCP 错误报告标准
• 已通过直接 JSON-RPC 调用成功测试
• 兼容 MCP Inspector 和实际 MCP 客户端

⚠️ 框架测试限制：已知问题

• 由于 mcp-framework 0.2.13 中的一个错误，MCP Testing Framework 显示 1 个验证错误
• 根本原因：mcp-framework 返回的验证错误使用 "type": "error"，而非符合 MCP 规范的 "type": "text"
• 影响：测试框架验证失败，但服务在实际使用中运行完美
• 状态：已记录的问题，仅影响测试，不影响生产功能

这是《模型上下文协议服务的标准化错误报告格式》官方文档中提及的一种已知模式，涉及 SDK 实现方面的挑战。

🛠 可用工具

1. register_pytest_failure - 注册新的测试故障
2. list_failures - 列出所有已注册的故障
3. get_failure_info - 获取特定故障的详细信息
4. debug_with_principle - 系统地应用调试原则
5. analyze_failures - 分析测试故障中的模式
6. generate_debug_prompt - 生成用于调试的大模型提示词
7. pytest_docs_guide - 获取 pytest 文档指南
8. example_tool - 用于测试的示例工具

🚀 快速开始

安装

npm install -g pytest-mcp-server

在 Claude Desktop 中使用

将以下内容添加到 Claude Desktop MCP 配置中：

{
  "mcpServers": {
    "pytest-mcp-server": {
      "command": "pytest-mcp-server",
      "args": ["start"],
      "env": {
        "DATA_DIR": "./pytest-data"
      }
    }
  }
}

作为 HTTP 服务使用

# Start HTTP server on port 3001
pytest-mcp-server start-http

# Or specify custom port
PORT=8080 pytest-mcp-server start-http

直接使用

# Start MCP server (stdio mode)
pytest-mcp-server start

# Test with MCP Inspector
npx @modelcontextprotocol/inspector pytest-mcp-server start

📋 使用示例

1. 注册测试故障

{
  "name": "register_pytest_failure",
  "arguments": {
    "test_name": "test_user_authentication",
    "file_path": "/tests/test_auth.py",
    "line_number": 45,
    "error_message": "AssertionError: Expected status 200, got 401",
    "traceback": "Full traceback here..."
  }
}

2. 应用调试原则

{
  "name": "debug_with_principle",
  "arguments": {
    "failure_id": "1234567890",
    "principle_number": 1,
    "analysis": "This test is checking user authentication flow. The system expects a valid JWT token but seems to be receiving an invalid or expired token."
  }
}

3. 获取故障分析

{
  "name": "analyze_failures",
  "arguments": {
    "analysis_type": "patterns"
  }
}

🔧 开发

前置条件

• Node.js 18.19.0 或更高版本
• npm 或 yarn

设置

# Clone the repository
git clone <repository-url>
cd pytest-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Start development server
npm run watch

测试

# Test with simple script
./test-simple.sh

# Test with MCP Testing Framework (shows known validation issue)
mcp-test --test-config mcp-test-config.json --test-mcp-servers

# Test with Dagger (containerized testing)
./test-dagger-simple.sh

📁 数据存储

服务会将数据存储在 JSON 文件中：

• failures.json - 测试故障记录
• debug_sessions.json - 调试会话数据

默认位置：./data/（可通过 DATA_DIR 环境变量配置）

🐛 已知问题

MCP 框架验证错误

• 问题：mcp-framework 0.2.13 返回的验证错误使用了不符合规范的 "type": "error"
• 预期：MCP 规范要求所有错误内容使用 "type": "text"
• 影响：MCP Testing Framework 验证失败（假阴性）
• 解决方法：使用直接测试或 MCP Inspector 进行验证
• 状态：已向框架维护者报告

详细技术分析请参阅 framework-issue-report.md。

🤝 参与贡献

1. Fork 此仓库
2. 创建功能分支
3. 进行更改
4. 如适用，添加测试
5. 提交拉取请求

📄 许可证

MIT 许可证，详情请参阅 LICENSE 文件。

🔗 相关链接

• 模型上下文协议
• MCP Testing Framework
• Pytest 文档

---

注意：此服务已可用于生产环境，且功能齐全。测试框架验证问题是当前 mcp-framework 实现的已知限制，不会影响实际使用。