Pytest MCP Server

A Model Context Protocol (MCP) server for debugging pytest failures using systematic debugging principles.

✅ Status: Production Ready

This MCP server is fully functional and ready for use. All 8 tools work correctly with proper error handling and response formatting that complies with the official MCP specification.

Related MCP server: qa-toolkit-mcp

🧪 Testing Status

✅ Server Functionality: Perfect

• All tools work correctly with valid inputs

• Proper error handling for invalid inputs

• Compliant with MCP error reporting standards

• Successfully tested with direct JSON-RPC calls

• Compatible with MCP Inspector and real MCP clients

⚠️ Framework Testing Limitation: Known Issue

• MCP Testing Framework shows 1 validation error due to a bug in mcp-framework 0.2.13

• Root Cause: mcp-framework returns validation errors with "type": "error" instead of MCP-compliant "type": "text"

• Impact: Testing framework validation fails, but server works perfectly in real usage

• Status: Documented issue, affects testing only, not production functionality

This is a known pattern documented in the official Standardized Error Reporting Formats for Model Context Protocol Servers document regarding SDK implementation challenges.

🛠 Tools Available

1. register_pytest_failure - Register a new test failure

2. list_failures - List all registered failures

3. get_failure_info - Get detailed information about a specific failure

4. debug_with_principle - Apply debugging principles systematically

5. analyze_failures - Analyze patterns in test failures

6. generate_debug_prompt - Generate LLM prompts for debugging

7. pytest_docs_guide - Get pytest documentation guidance

8. example_tool - Example tool for testing

🚀 Quick Start

Installation

npm install -g pytest-mcp-server

Usage with Claude Desktop

Add to your Claude Desktop MCP configuration:

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

Usage as HTTP Server

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

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

Direct Usage

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

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

📋 Example Usage

1. Register a Test Failure

{
  "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. Apply Debugging Principles

{
  "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. Get Failure Analytics

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

🔧 Development

Prerequisites

• Node.js 18.19.0 or higher

• npm or yarn

Setup

# 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

Testing

# 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

📁 Data Storage

The server stores data in JSON files:

• failures.json - Test failure records

• debug_sessions.json - Debugging session data

Default location: ./data/ (configurable via DATA_DIR environment variable)

🐛 Known Issues

MCP Framework Validation Error

• Issue: mcp-framework 0.2.13 returns validation errors with non-compliant "type": "error"

• Expected: MCP specification requires "type": "text" for all error content

• Impact: MCP Testing Framework validation fails (false negative)

• Workaround: Use direct testing or MCP Inspector for validation

• Status: Reported to framework maintainers

See framework-issue-report.md for detailed technical analysis.

🤝 Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🔗 Related

• Model Context Protocol

• MCP Testing Framework

• Pytest Documentation

Note: This server is production-ready and fully functional. The testing framework validation issue is a known limitation of the current mcp-framework implementation and does not affect real-world usage.