lens-mcp

Deterministic navigation maps over code AND markdown — for AI agents. One MCP server, two lenses: tree-sitter for source (TypeScript / JavaScript / Python) and a markdown lens for docs. It answers "where is X and what's the shape of this project?" in one cheap call — so an agent spends context on thinking, not on browsing files.

Speaks the Model Context Protocol; works with any MCP client — Claude Code, Cursor, Codex, or your own agent.

Why

An agent orienting in an unfamiliar repo otherwise burns tokens ls-ing, grep-ing, and Reading whole files to find the one function or the right doc. lens returns the map instead of the territory:

• function_body reads one function — often ~99% less context than Reading the file it lives in.
• heading reads one doc section — the referenced heading and its subsections, nothing else.
• map returns the whole project's surface — every code file's structure and every doc's outline — in a single call.

Every output is deterministic (real parsing, not a model summarizing), capped with an honest truncated flag, and framed by one contract:

lens is a navigation map. Use it to locate, then Read the real source/section before judging or modifying it. A signature is not the body; an outline is not the section.

Tools (13)

Orientation

Code (tree-sitter — .ts .tsx .mts .cts .js .jsx .mjs .cjs .py) + Prisma (.prisma)

Docs (markdown — .md .markdown .mdx)

overview/find/map also cover Prisma schemas (schema.prisma → models, enums, fields, relations). JSON config/i18n isn't structurally mapped — lens says so honestly and points you to grep.

Call a code tool on a .md (or a doc tool on a .ts) and it fails with a helpful pointer to the right tool — no silent confusion.

Honest by construction

• Never silent data loss — a file with syntax errors returns hasErrors + parseErrors, still extracting what it can; unparseable files in map/find appear with an inline error, never vanish.
• Caps everywhere — every list is bounded (see info.limits) and every cap is reported with the true total. A context-saving tool with unbounded output is self-refuting.
• Path sandbox — only files under the server's working directory are readable; escaping symlinks are rejected. info reports the root.
• Errors name the fix — {error, path, hint}, with isError set.

Install

One line clones, installs, and writes a ready-to-paste MCP co

... View full README on GitHub