Metadata-Version: 2.4
Name: jons-mcp-pyright
Version: 0.0.1
Summary: FastMCP stdio server for Pyright code intelligence
Author: Jon Mease
License-Expression: MIT
Project-URL: Homepage, https://github.com/jonmmease/jons-pyright-mcp
Project-URL: Repository, https://github.com/jonmmease/jons-pyright-mcp
Project-URL: Issues, https://github.com/jonmmease/jons-pyright-mcp/issues
Keywords: code-intelligence,development,fastmcp,language-server,language-server-protocol,lsp,mcp,model-context-protocol,pyright,python
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Text Editors :: Integrated Development Environments (IDE)
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=3.3.1
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyright>=1.1.402
Requires-Dist: tomli>=2.0.0; python_version < "3.11"
Dynamic: license-file

# jons-mcp-pyright

A FastMCP stdio server that exposes Pyright language intelligence through MCP.
It starts Pyright as a subprocess, keeps LSP document state fresh with disk
contents, and provides root-bound tools for navigating and understanding Python
projects.

## Installation

Run directly from PyPI:

```bash
uvx jons-mcp-pyright /path/to/python/project
```

Install as a CLI tool:

```bash
uv tool install jons-mcp-pyright
jons-mcp-pyright /path/to/python/project
```

Run an unreleased version directly from GitHub:

```bash
uvx --from git+https://github.com/jonmmease/jons-pyright-mcp.git jons-mcp-pyright /path/to/python/project
```

Run from a local checkout:

```bash
git clone https://github.com/jonmmease/jons-pyright-mcp.git
cd jons-pyright-mcp
uv sync --group dev
uv run jons-mcp-pyright /path/to/python/project
```

The command is `jons-mcp-pyright`. The final optional argument is the target
project root. If omitted, the server uses its current working directory.

## MCP Client Setup

### Claude Code

From the Python project you want Pyright to analyze:

```bash
claude mcp add --scope project jons-mcp-pyright -- \
  uvx jons-mcp-pyright "$(pwd)"
```

For a local server checkout:

```bash
claude mcp add --scope project jons-mcp-pyright -- \
  uv run --project /path/to/jons-pyright-mcp \
  jons-mcp-pyright "$(pwd)"
```

### Codex CLI

```bash
codex mcp add jons-mcp-pyright -- \
  uvx jons-mcp-pyright /path/to/python/project
```

### `.mcp.json`

```json
{
  "mcpServers": {
    "jons-mcp-pyright": {
      "command": "uvx",
      "args": [
        "jons-mcp-pyright",
        "/absolute/path/to/python/project"
      ]
    }
  }
}
```

### Codex TOML

```toml
[mcp_servers.jons-mcp-pyright]
command = "uvx"
args = [
  "jons-mcp-pyright",
  "/absolute/path/to/python/project",
]
```

## Project Root Semantics

The configured project root is the filesystem boundary for all MCP tool file
inputs.

- Relative paths resolve from the configured project root, not the MCP process
  cwd.
- Absolute paths and `file://` URIs must resolve inside the configured root.
- `..` escapes, symlink escapes, missing files, and directories are rejected
  before Pyright or the filesystem is touched.
- LSP responses may include external locations, but the server does not open or
  read external files for enrichment.

Pyright reads `pyrightconfig.json` or `[tool.pyright]` from the selected root
and discovered nested project roots. If a discovered project is inside a uv
workspace, the server uses the nearest enclosing `[tool.uv.workspace]` root as
the Pyright environment so shared workspace dependencies and `.venv` settings
resolve correctly. Virtual environments are detected from common names such as
`.venv`, `venv`, `.env`, and Pixi environments under `.pixi/envs/<name>`.

For uv workspaces, the public `diagnostics` tool also applies diagnostics-only
output filtering from in-root member `pyrightconfig.json` or `[tool.pyright]`
files. This honors explicit top-level `report*` overrides such as
`reportMissingImports = "none"` for files under that member without splitting
the workspace into separate Pyright processes. The filter affects returned MCP
diagnostics only; Pyright analysis, readiness, references, and rename previews
continue to use the shared workspace process.

## Prerequisites

- Python 3.10 or newer.
- `uv` for the documented install commands.
- A Python target project. For best results, include `pyrightconfig.json` or
  `pyproject.toml`.
- Target-project dependencies should be installed in the environment Pyright
  should analyze. The server can also be pointed at a specific Pyright command
  with `PYRIGHT_PATH`.

## Tools

Navigation and discovery:

- `document_symbols`
- `definition`
- `type_definition`
- `references`

Understanding code:

- `symbol_info`
- `type_info`

Code intelligence and refactoring:

- `diagnostics`
- `preview_rename`

Server management:

- `list_environments`
- `restart_server`

All public `line` and `character` inputs and returned ranges are one-based.
`preview_rename` is preview-only: it returns sorted text edits and never writes
files. `type_info` works best when called on a value reference such as `obj` in
`obj.method()`, rather than on a class or variable declaration, when member
discovery is desired.

`references` and `preview_rename` are scoped to the active Pyright
workspace/environment for the input file. `preview_rename` supplements Pyright's
rename edit with reference locations from the same workspace so imported callers
are included in the preview. By default, `preview_rename` also prewarms unopened
Python files in the active environment before collecting references; tune this
with `prewarm`, `prewarm_limit`, and `prewarm_timeout_seconds`. If prewarm is
disabled or partial, the result includes `warnings`. In monorepos, callers that
need results beyond the active workspace should iterate environments or combine
the preview with external search before applying edits.

Paginated tools return `items`, `totalItems`, `offset`, `limit`, `hasMore`, and
`nextOffset`. Navigation tools return `items` and `totalItems`. Errors use a
structured `error.code`, `error.message`, and `error.retryable` shape.

## Development

```bash
uv sync --group dev
uv run pytest
uv run pytest --cov=src/jons_mcp_pyright --cov-report=term-missing
uv run ruff check .
uv run mypy src
uv build --wheel --out-dir /tmp/jons-mcp-pyright-wheel
```

Inspect a built wheel:

```bash
uv run python -m zipfile -l /tmp/jons-mcp-pyright-wheel/jons_mcp_pyright-*.whl
```

The wheel should contain top-level `jons_mcp_pyright`, not a packaged top-level
`src` module, and should not include build artifacts or `node_modules`.
