PyProject Doctor

A local MCP server for inspecting Python projects and checking their code with Ruff.

Give your MCP client the path to one project. PyProject Doctor detects package manager signals, reports the project's local Python environment, and runs lint and formatting checks. Results are returned as structured Pydantic models.

Features

• Detects uv, Poetry, Pipenv, and pip project files.

• Reports the version of detected package managers available on the server's PATH.

• Finds a local .venv or venv and reports its actual Python version.

• Reads the declared version from .python-version, when present.

• Runs ruff check and ruff format --check using Ruff installed with the server.

• Uses the project's Ruff configuration, or Ruff defaults when no configuration is found.

• Reports failures, missing tools, and command timeouts.

Checks do not apply fixes or reformat source files. The server does not install dependencies in the analyzed project.

Related MCP server: AgentForge MCP

Requirements

• Python 3.12 or newer for the server.

• A local MCP client with stdio support.

• Access to the directory being analyzed.

Ruff, Pydantic, and MCP SDK 2.x are included as package dependencies. The analyzed project does not need its own Ruff installation.

Install from source

Clone the repository and enter its directory. Replace <repository-url> with the repository's Git URL:

git clone <repository-url> pyproject-doctor
cd pyproject-doctor

From the repository directory, install the server as an isolated tool:

uv tool install .

For development, use an editable installation:

uv tool install --editable .

An editable installation uses the source files in your checkout. Restart the MCP process after changing code. Reinstall after changing dependencies or entry points, and keep the checkout at its original location.

Make sure the tool executable directory is on PATH. If needed, run uv tool update-shell, then restart your terminal and MCP client.

You can also install into an existing Python environment:

python -m pip install .

The installed command is:

pyproject-doctor

This starts a stdio MCP server that waits for a client on stdin. It is not an interactive command-line project checker. The MCP client normally launches and manages this process.

Connect to an MCP client

OpenCode

Add the server to the mcp section of your opencode.json or opencode.jsonc:

{
  "mcp": {
    "pyproject-doctor": {
      "type": "local",
      "command": ["pyproject-doctor"],
      "enabled": true,
      "timeout": 30000
    }
  }
}

Codex

Add this section to your user configuration at ~/.codex/config.toml:

[mcp_servers.pyproject_doctor]
command = "pyproject-doctor"
enabled = true

On Windows, the default user configuration location is %USERPROFILE%\.codex\config.toml.

Restart your client after configuring the server. If the command cannot be found, check the client's PATH or use the full path to the installed executable.

Run directly from a checkout

During development, you can use uv run instead of a tool installation:

uv sync
uv run pyproject-doctor

For a client launched outside the repository, use uv as the executable and pass these arguments:

run --directory /absolute/path/to/pyproject-doctor pyproject-doctor

Tools

All tools accept a single path argument pointing to an existing local directory. Use an absolute path so it resolves consistently across clients.

Example arguments for analyze:

{"path": "/path/to/python-project"}

On Windows:

{"path": "F:\\Projects\\example-project"}

Example client prompt:

Use pyproject-doctor to analyze /path/to/python-project. Report the package manager, Python version, and Ruff check results.

Results

AnalysisResult contains two nested reports:

• inspection: resolved project path, recognized project files, detected package managers and their versions, Python environment, and the Ruff version probe.

• checks: Ruff version, lint result, formatting result, and overall status.

Each command result includes a status, exit code, captured output, and optional error or timeout details. Lint violations include parsed Ruff JSON diagnostics when parsing succeeds.

Command statuses are passed, issues_found, error, timeout, and unavailable. The overall Ruff status is passed, fail, or unavailable.

Detection and execution details

When no manager file markers are found, a pyproject.toml without [tool.poetry] currently falls back to pip. This is a heuristic, not proof of how the project was installed. If multiple managers are detected, all are reported and selected is null.

The Python search checks .venv/Scripts/python.exe, .venv/bin/python, venv/Scripts/python.exe, and venv/bin/python, in that order. Environments stored outside the project are not discovered. The declared version from .python-version is reported separately from the actual interpreter version.

Ruff runs through the server's Python interpreter with the analyzed directory as its working directory. Inspection also runs version probes for available managers and the discovered project interpreter.

Each subprocess has a 60-second timeout. Captured stdout and stderr are each limited to their last 20,000 characters in the report. Large lint output may therefore be truncated and unavailable as parsed diagnostics. Nonzero subprocess exit codes are currently reported as issues_found; consult stderr and the exit code to distinguish configuration failures from code violations.

The server handles one directory per call. It does not discover and separately report projects inside a monorepo. Ruff may still check files recursively under the supplied directory according to its configuration.