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.

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, 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

Developed in the SpaceMaker repository as a uv workspace member (mcp-servers/codenav_mcp). From a checkout: uv sync --group dev, then uv run codenav-mcp.

License

MIT. See LICENSE.