Prospector

An MCP (Model Context Protocol) server that exposes Prospector — the Python static analysis tool — through its native Python API.

Features

• Run Prospector on a single file or an entire directory.
• Return structured, machine-readable results (messages with severity, location, rule code).
• Layered TOML configuration with sensible defaults.
• Supports both stdio and SSE transports via FastMCP.
• Secure by default: respects .gitignore, ignores .env / .venv, validates paths, enforces timeouts.

Installation

Via uvx (recommended)

uvx run prospector-mcp

Via pip

pip install prospector-mcp
prospector-mcp

Development setup

git clone https://github.com/yourname/prospector-mcp.git
cd prospector-mcp
pip install -e ".[dev]"
pytest

Usage

Claude Desktop / OpenCode

Add the server to your MCP settings:

{
  "mcpServers": {
    "prospector": {
      "command": "uvx",
      "args": ["run", "prospector-mcp"]
    }
  }
}

SSE transport

prospector-mcp --transport sse
# or
prospector-mcp --sse

Configuration

Configuration is layered (later layers override earlier ones):

1. Built-in defaults
2. Global config: ~/.config/prospector-mcp/config.toml
3. Project config: .prospector-mcp.toml in the project root

Example .prospector-mcp.toml

[prospector]
timeout = 60
strictness = "medium"
profile = "default"
ignore = [".tox", "build", "dist"]

[server]
transport = "stdio"

Tools

prospector.run

Run Prospector on a target path.

Parameters:

• target (string, required): Path to a Python file or directory.
• profile (string, optional): Override the Prospector profile.
• strictness (string, optional): Override strictness (verylow to veryhigh).

Returns: Structured dict with summary, messages, and execution_time.

prospector.check_ready

Check if Prospector is installed and available.

License

MIT