codenav-mcp

An MCP server that gives AI agents type-resolved Python navigation, backed by ty's language server. Definitions, references and call sites go through real type inference (imports, dependency-injected parameters, dataclass fields), not text grep.

Quick start

ty is installed with the package, so all you need is uv (or pipx):

uvx codenav-mcp

Register it with your MCP host. For Claude Code, from the project root:

claude mcp add codenav -- uvx codenav-mcp

Or add it to a project .mcp.json (Claude Code) or .cursor/mcp.json (Cursor):

{
	"mcpServers": {
		"codenav": {
			"command": "uvx",
			"args": ["codenav-mcp"],
			"env": {
				"CODENAV_MCP_SOURCE_ROOT": "src"
			}
		}
	}
}

In Cursor, also set "CODENAV_MCP_WORKSPACE": "${workspaceFolder}", because Cursor may start MCP servers with your home directory as the working directory.

Tools

Start with the name-based tools:

Then use the position tools once you have a path:line:col:

name and query are accepted as aliases on the name-based tools (port_name / name / query on implementations). A missing or wrong parameter gets a short hint back instead of a validation error. Dotted names may nest (Outer.Inner.method). implementations also takes file_path to pick one port when the name exists in several files, and counts inherited members and dataclass/self.x fields toward a port's required names.

Write tools: change code with a type check before every write

The navigation tools above are read-only. These change code, and share one rule: the edit is applied to in-memory copies first, ty re-checks the edited files and the files importing them, and the response says which diagnostics the edit would add or fix. Nothing is written until that is on the table.

One rule for every write tool: it writes when the edit adds no more than max_new_errors (default 0) type errors in the edited files and their importers. Otherwise nothing is written and you get the diagnostics plus an id for apply_edit. apply=false always previews. Hint-level diagnostics (unused, deprecated) are not counted.

Safety rules, enforced in code:

• Only .py/.pyi files inside the workspace are written; virtualenvs, site-packages, typeshed and symlinks that leave the workspace are refused.
• A preview remembers the exact bytes of every file; apply_edit refuses if any file changed since. Files are replaced atomically, and a failure part-way restores the ones already written.
• Every applied edit is undoable (undo_edit) unless the files were changed after it.
• Output is never written if it is not valid Python.
• Edits touching more than 40 files need allow_large=true.
• CODENAV_MCP_READ_ONLY=1 turns every write into a refusal (previews still work).

New files an edit would create are written to disk for the few moments of the type check (ty finds modules through the file system) and removed again, even on errors.

Positions are 1-indexed. column is a UTF-16 character offset (a leading tab counts as one character).

Python only (.py / .pyi).

Which ty runs

1. The project's own .venv/bin/ty (.venv\Scripts\ty.exe on Windows), so the ty version matches the project's pin and config.
2. The ty installed alongside codenav-mcp.
3. ty on PATH.
4. uvx ty server as a last resort.

Environment

Requirements

• Python ≥ 3.11
• Installed automatically: mcp, ty, ruff (sorts imports in files a move touched, only where they were already sorted), mcp-nav-shared

Related

• webnav-mcp: the same kind of navigation for JS/TS/HTML/CSS.
• Design notes (Protocol conformance probe, positioning, output formats): docs/agent-tooling.md.

Development

Source: github.com/illescasDaniel/codenav-mcp. From a checkout: uv sync --group dev, then uv run codenav-mcp.

License

MIT. See LICENSE.