# code-quality-mcp

**Stop asking your LLM if your Python is clean. Let it actually check.**

An MCP server that gives Claude, Cursor, VS Code (or any MCP-compatible client) a real, deterministic view of your Python code quality — powered by the tools you already trust: **flake8**, **mypy**, **McCabe**, and **vulture**.

No more "looks good to me" from an LLM that never ran a linter. This is ground truth.

---

## Why

LLMs hallucinate code reviews. They miss style violations, invent complexity numbers, and confidently declare your dead code "actively used."

`code-quality-mcp` plugs the gap: it runs the canonical Python quality tools and hands the LLM a clean, structured report. The model stops guessing and starts citing.

It also ships with a hard instruction baked into the server: **never modify, refactor, or fix your code unless you explicitly ask**. It reports. You decide.

---

## What it gives you

| Tool | What it checks | MCP function |
|---|---|---|
| **flake8** | PEP8 style, line length, unused imports | `analyze_style` |
| **McCabe** | Cyclomatic complexity per function | `analyze_complexity` |
| **vulture** | Dead code, unused variables and functions | `analyze_dead_code` |
| **mypy** | Static type errors | `analyze_types` |
| All-in-one | flake8 + McCabe + vulture, parallel | `analyze_all` |
| Snippet mode | Paste raw source, no file needed | `analyze_content` |

Reports come back as markdown tables — readable for you, parseable for the model.

---

## Install

```bash
git clone https://github.com/Javier-Morenosa/code-quality-mcp.git
cd code-quality-mcp
pip install -e .
```

Requires Python 3.10+.

---

## Wire it up

### Cursor

Add to your Cursor MCP settings (or copy `cursor_mcp.json`):

```json
{
  "mcpServers": {
    "code-quality": {
      "command": "python",
      "args": ["-m", "code_quality_mcp.server"],
      "env": {
        "PYTHONPATH": "C:/path/to/code-quality-mcp/src"
      }
    }
  }
}
```

### VS Code

See `vscode_mcp.json` for a ready-to-use config.

### Claude Code

```bash
claude mcp add code-quality -- python -m code_quality_mcp.server
```

---

## Use it

Once the server is wired up, just talk to your LLM:

> *"Run a full quality analysis on `src/my_module.py`."*

> *"Is there dead code in this project?"*

> *"Which functions are too complex?"*

The model will call the right tools, get real output from real linters, and give you a report grounded in facts — not vibes.

### Pro tip

Call `set_workspace` once at the start of a session to point the server at your project root. After that, you can pass relative paths and everything Just Works.

---

## What it will NOT do

By design, this server is **read-only**. It will not:

- Edit your files
- Refactor your code
- Auto-fix style issues
- Suggest changes unless you explicitly ask for them

If you want fixes, run `black`, `ruff --fix`, or ask your LLM directly. This server's job is to tell the truth about your code, nothing more.

---

## Roadmap

- `ruff` backend as a faster drop-in for flake8
- Per-file complexity heatmap
- Configurable rule sets via `pyproject.toml`

---

## License

MIT. Use it, ship it, fork it.