# 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:

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

### Using `pip`

```bash
pip install -e .
```

---

## Usage & MCP Client Configuration

### CLI Usage

Run the server over stdio transport:

```bash
wemake-python-mcp --transport stdio
```

Check version:

```bash
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)

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

#### Direct Executable

```json
{
  "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`)

```json
{
  "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:

```bash
# 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
```