wemake-python-mcp

Model Context Protocol (MCP) server providing automated code linting, rule explanations, and configuration templates for wemake-python-styleguide (WPS).

---

Features

• Automatic Venv Resolution: Automatically detects project virtualenvs (.venv, venv, uv) to execute flake8 --select=WPS.
• Structured Violation Output: Returns JSON violation reports with file, line, column, rule code, title, category, and message.
• Offline WPS Rule Database: Bundled offline lookup database covering all 263 WPS rules (WPS000–WPS699).
• Live Scraper & Updater: Scrapes official documentation to keep rule definitions and links up to date.
• FastMCP Protocol Support: Implements tools and resources via standard stdio transport.

---

Prerequisites

• Python 3.10+
• wemake-python-styleguide (installed in target project virtual environment or system environment)
• uv (recommended) or pip

---

Installation

Using uv (Recommended)

Clone the repository and install dependencies into a local virtualenv:

git clone https://github.com/your-org/wemake-python-mcp.git
cd wemake-python-mcp
uv venv
uv pip install -e .

Using pip

pip install -e .

---

Usage & MCP Client Configuration

CLI Usage

Run the server over stdio transport:

wemake-python-mcp --transport stdio

Check version:

wemake-python-mcp --version

Claude Desktop / Cursor / MCP Client Configuration

Add the following to your MCP client configuration file (e.g., claude_desktop_config.json):

Using uv (Recommended)

{
  "mcpServers": {
    "wemake-python": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/wemake-python-mcp",
        "run",
        "wemake-python-mcp"
      ]
    }
  }
}

Direct Executable

{
  "mcpServers": {
    "wemake-python": {
      "command": "/absolute/path/to/wemake-python-mcp/.venv/bin/wemake-python-mcp",
      "args": []
    }
  }
}

---

Tools Reference

Tool Name	Parameters	Description
lint_file	path: str	Lints a single .py file using wemake-python-styleguide rules.
lint_project	directory: str = "."	Recursively lints a Python project directory.
lint_code	code: str	Lints a raw Python code string snippet.
explain_rule	code: str	Returns documentation, title, category, and URL for a rule (e.g. WPS432 or 432).
update_rule_db	None	Scrapes official readthedocs documentation and updates the local rule database.

Sample Tool Output (lint_file / lint_code)

{
  "success": false,
  "violation_count": 1,
  "violations": [
    {
      "file": "example.py",
      "line": 1,
      "column": 5,
      "code": "WPS432",
      "title": "Forbid magic numbers",
      "category": "Best practices",
      "message": "Found magic number: 42"
    }
  ],
  "summary": "Found 1 wemake-python-styleguide violation across 1 file."
}

---

Resources Reference

Resource URI	Mime Type	Description
wemake://rules	application/json	Categorized index of all WPS rule codes and titles.
wemake://rules/{code}	text/markdown	Full Markdown documentation for a specific rule (e.g., wemake://rules/WPS432).
wemake://config/template	text/plain	Recommended setup.cfg configuration template for wemake-python-styleguide.

---

Environment Variables

• WPS_FLAKE8_PATH: Explicit path to flake8 executable. Overrides auto-detection logic.

---

Development & Testing

Run tests and type checks:

# Run unit tests
uv run pytest

# Type check
uv run mypy src/ tests/

# Ruff linting
uv run ruff check src/ tests/ scripts/

# WPS styleguide compliance check
uv run flake8 src/ tests/ --select=WPS