THE IDEA

SpaceMaker is a hexagonal-architecture Python app with a TypeScript/HTML/CSS web UI. AI agents working in it kept doing the same slow thing: using the grep tool for symbols and guessing who calls what. So we built two small MCP servers that put a real language server behind a handful of agent-friendly tools.

codenav (Python, backed by Astral's ty)
webnav (TS/HTML/CSS, backed by TypeScript 7's native language server and vscode-langservers-extracted for HTML and CSS)

For those unfamiliar, an MCP (Model Context Protocol) server acts as a standardized bridge between an AI model and external tools, software, or data sources. Instead of writing custom integration code for every new application, developers use MCP to expose functions—like reading a local file system, querying a database, or analyzing a codebase—in a universal format. This gives AI agents a secure, plug-and-play way to interact with real-world developer environments and fetch the exact context they need to complete complex tasks.

THE TOOLS

The core design relies on bundled, name-based tool calls. For example, when an agent executes symbol_info("JobsMixin.start_convert"), the tool should handle everything in a single go: returning the function's signature, a definition snippet, and grouped references. This completely eliminates the need for the agent to calculate line and column numbers. Furthermore, if a tool call fails, it should return a readable error message with actionable next steps so the agent can course-correct on its own.

HOW GOOD ARE THEY? (evaluated by Claude Opus 5.5)

We evaluated both servers the way an agent uses them: through the real MCP connection, on this repo, with every answer cross-checked against grep. Our opinion is that they are very good for the job they were built for, and that they change how an agent works in a codebase.

They are accurate. Results matched grep exactly. FileSystemPort has 37 references in 17 files from both, and callers stays precise because it leaves out imports and annotations.

They understand the code, which grep does not. From services.start_convert(...) in a FastAPI route, definition lands on the mixin method that implements it. implementations answers "which adapters implement this port?", which plain LSP cannot. css_var and selector answer questions about themes and class names that no single-file language server can, and grep only approximates.

They are cheap for the agent to read. Answers are small, typically 0.3 to 1.5 KB, and structured, so they use far fewer tokens than grep output the agent still has to interpret.

They can be trusted inside an edit, check, edit loop. After the agent changes, adds or deletes files, the next call reflects it, so a result is never a stale picture of the disk.

They are forgiving. Ambiguous names list their candidates, wrong file types and out-of-range positions explain themselves, and the server says when it restarted after a config change or when its own code is out of date.

They are fast. Warm calls are faster than a single grep -r over the repo.

PERFORMANCE

HOW WE TESTED

- Every result was compared with grep on this repo.

- Freshness was tested with temporary edits, new files and deletions, all reverted afterwards.

- Latency was measured with a stdio MCP client that launched each server from scratch and timed repeated calls per tool.

- The servers have their own test suite of 313 fast tests (158 for the shared LSP layer, 42 for codenav, 113 for webnav), including tests against a real ty and a real tsserver. The whole suite runs in about 17 seconds.

WHERE THEY STOP

- selector matches ids and classes with patterns, so selectors built from template literals or several variables are not resolved. None exist in our web code today.

- A running stdio MCP server cannot reload its own code. It shows a "restart the MCP servers" line when its source has changed.

- Both are young and have been used on this one project so far.

TAKEAWAY

For an AI agent, the most expensive part of working in an unfamiliar codebase is building an accurate picture of who calls what. These servers give it that picture in tens of milliseconds, with type-aware precision and less output than grep. In our experience they are a clear win for Python and web code, and the tools with no grep equivalent (implementations, css_var, selector) are the ones we would miss most.

LINKS

SpaceMaker — A desktop app to transfer files from your phone to your PC. Includes media compression and a Gallery.
Webnav — Our Python MCP
Codenav — Our Web MCP
mcp-nav-shared — A shared helper dependency for our MCPs

Giving AI coding agents a code map