PyCheckMCP

PyCheckMCP is a Model Context Protocol (MCP) server that bundles popular Python formatting and linting tools behind a single FastMCP endpoint. It can be run as a standalone server for MCP-compatible clients or imported as a regular Python module.

Features

• Unified pipeline that optionally reforms code with Black and isort before running Ruff and Pylint.
• FastMCP HTTP server exposing a check_python_code tool that works with any MCP-compatible client.
• Typed request/response models built with Pydantic for predictable integration.
• Scriptable helper (check_code) for direct use inside automation, CI jobs, or notebooks.

Requirements

• Python 3.10+
• uv for dependency management and virtualenv handling

Installation & Setup

1. Clone the repository and move into it:

   git clone <your-fork-url>
   cd PyCheckMCP

2. Install dependencies with uv:

   uv sync

Running the MCP server

Start the FastMCP HTTP transport (defaults to 127.0.0.1:8000):

uv run python main.py

Optional flags:

• --host 0.0.0.0 to listen on every interface
• --port 9000 (or any free port) to customise the binding
• --test to execute the built-in demonstration instead of starting the server

When running, the MCP server exposes the check_python_code tool. Clients following the MCP spec can invoke it over the Streamable HTTP transport implemented by FastMCP.

Tool contract (check_python_code)

Input parameters:

• code (str, required) – Python source text to analyse
• style_fixes (bool, default: true) – Run Black and isort before linting
• type_check (bool, default: false) – Reserved for future type-checking support

Typical JSON response (values vary depending on the supplied code):

{
  "formatted_code": "def greet():\n    print('Hello, World!')\n",
  "issues": [
    {
      "code": "W0612",
      "message": "Unused variable 'unused_var'",
      "line": 3,
      "column": 5,
      "severity": "warning"
    }
  ],
  "error_count": 0,
  "warning_count": 1,
  "success": true,
  "error": null
}

Programmatic usage

The underlying pipeline can be imported directly:

from pycheckmcp.core import check_code

sample = """
def bad_function():
    unused_var = 1
    print('hi')
"""

result = check_code(sample)
print(result["formatted_code"])
print(result["issues"])  # list of dictionaries with code, message, severity, etc.

Development

• Run the local demo: uv run python main.py --test
• Format code: uv run black . and uv run isort .
• Lint quickly: uv run ruff check .
• Run static analysis: uv run pylint pycheckmcp
• Execute tests: uv run pytest

Project layout

PyCheckMCP/
├── main.py              # CLI entry point that launches the FastMCP server
├── pycheckmcp/
│   ├── core.py          # Formatting and linting pipeline
│   └── server.py        # FastMCP tool registration
├── pyproject.toml       # Project metadata and dependency definitions
└── tests/               # Test scaffolding

License

MIT License