code-quality-mcp

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