adamryczkowski/pyright-mcp

= pyright-mcp: Pyright MCP server :toc: macro :toclevels: 3 :sectanchors:

toc::[]

== What is MCP?

MCP is a small, JSON‑RPC based way for tools to talk to AIs (and each other). Servers expose “tools”; clients call them and get structured results over stdio.

== What this server does

• Runs Pyright on a file, directory, or project.
• Returns stable, machine‑friendly diagnostics (sorted, normalized severities).
• Ships three tools over stdio using the official Python SDK (FastMCP).
• Works well in CI and editor integrations.

== Quick start

Install (recommended with pipx)

[source,shell]

pipx install pyright-mcp

Run

• pyright-mcp-server
• poetry run pyright
• poetry run pytest -q

== Tools and API

=== pyright_check

Run Pyright with JSON output and return normalized diagnostics.

Arguments

• target: string (required). File or directory to analyze.
• cwd: optional string. Working directory to run from.
• include: optional [glob] patterns resolved under the target root.
• exclude: optional [glob] patterns filtered from the include set.
• extra_args: optional list of strings, e.g., ["--pythonversion","3.12"].
• timeout_sec: int (default 60). Subprocess timeout.
• fail_on_severity: one of "none" | "information" | "warning" | "error". If any diagnostic meets/exceeds this level, ok=false (diagnostics are still returned).

Result

• ok: bool
• fail_reason: optional string
• command: list[str] (exact argv)
• exit_code: int
• summary: { files_analyzed, error_count, warning_count, information_count, time_sec }
• diagnostics[]: ** file: absolute path ** range: { start{line,character}, end{line,character} } ** severity: information | warning | error ** severity_level: 1 | 2 | 3 (information=1, warning=2, error=3) ** message: string ** rule, code: optional
• pyright_version: string
• analyzed_root: string
• checked_paths: list[str] — the exact absolute paths sent to Pyright
• venv_path: string — the Python environment path used; always present

Notes

• venv_path is not an argument. The server auto‑detects it and always returns it.
• To influence the environment, launch via Poetry (poetry run ...) or pass an interpreter with extra_args like ["--pythonpath","/path/to/venv/bin/python"].

Example request

[source,json]

{ "name": "pyright_check", "arguments": { "target": ".", "fail_on_severity": "warning" } }

Example result (abridged)

[source,json]

{ "ok": false, "fail_reason": "fail_on_severity 'warning' breached (max_severity_level=3).", "command": ["pyright","--outputjson","/path/to/proj"], "exit_code": 1, "summary": { "files_analyzed": 3, "error_count": 1, "warning_count": 0, "information_count": 0, "time_sec": 0.11 }, "diagnostics": [ { "file": "/path/to/proj/bad.py", "severity": "error", "severity_level": 3, "message": "...", "range": { "start": {"line":1, "character":4}, "end": {"line":1, "character":5} }, "rule": "reportGeneralTypeIssues", "code": "reportGeneralTypeIssues" } ], "pyright_version": "1.1.3xx", "analyzed_root": "/path/to/proj", "checked_paths": ["/path/to/proj"], "venv_path": "/home/you/.cache/pypoetry/virtualenvs/..." }

=== pyright_version

Return the Pyright CLI version and resolved executable path.

Result

• version: string
• executable_path: string
• supports_outputjson: bool

=== find_pyright_config

Find the nearest Pyright config from a starting directory (or CWD).

Arguments

• start_dir: optional string

Search order

. pyrightconfig.json . pyproject.toml with a [tool.pyright] section

Result

• found: bool
• config_path: optional string
• kind: "pyrightconfig.json" | "pyproject.toml" | "unknown" | null
• resolve_dir: string
• searched_from: string

== Errors you can expect

• Missing target: ok=false, helpful fail_reason. checked_paths=[], venv_path present.
• No Pyright on PATH: ok=false with remediation and pointers. venv_path present.
• Timeout: ok=false with suggestions to increase timeout or reduce scope.
• Unparseable JSON: ok=false with tail excerpt to debug.

== Architecture (short)

• Console script: pyright-mcp-server
• Server/tools: src/pyright_mcp/server_main.py
• Runner: src/pyright_mcp/runner.py
• Models: src/pyright_mcp/models.py
• Config discovery: src/pyright_mcp/config.py
• Tests: tests/

Flow

. Client calls a tool. . Tool gathers params and invokes the runner. . Runner shells out to pyright --outputjson, parses, normalizes, sorts, enforces threshold, returns a typed payload. . Tool returns structured content to the client.

== Development

• poetry install
• poetry run pyright
• poetry run pytest -q
• poetry run pyright-mcp-server

== MCP Client Integration

• Typical launch: ["pyright-mcp-server"]

MCP.json example

[source,json]

{ "servers": { "pyright-mcp": { "command": ["pyright-mcp-server"], "env": {}, "enabled": true } } }

== Testing

• Unit tests cover runner success/edge cases (missing paths, JSON parse failure, missing executable, timeout).
• Integration test drives the server over stdio using the official MCP client.

== Logging & debugging

• Add ["--verbose"] in extra_args to make Pyright chatty.
• Timeouts and parse failures surface actionable messages.

== Performance & caveats

• Use include to restrict scope in large repos.
• Pyright caches; repeated runs get faster.
• Include/exclude globbing is done in the server and may not reflect every Pyright nuance.
• Pyright must be on PATH for the Poetry environment that launches the server.

== Research notes

• MCP Python SDK (FastMCP): https://github.com/modelcontextprotocol/python-sdk
• MCP overview: https://modelcontextprotocol.io/
• Pyright CLI: https://github.com/microsoft/pyright/blob/main/docs/command-line.md
• Pyright project: https://github.com/microsoft/pyright

== Local CI commands

• poetry install
• poetry run pyright
• poetry run pytest -q