Lens MCP server

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:

the file it lives in.

• functionbody reads one function** — often ~99% less context than Reading

subsections, nothing else.

• heading reads one doc section — the referenced heading and its

and every doc's outline — in a single call.

• map returns the whole project's surface — every code file's structure

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

parseErrors, still extracting what it can; unparseable files in map/find appear with an inline error, never vanish.

• Never silent data loss — a file with syntax errors returns hasErrors +

is reported with the true total. A context-saving tool with unbounded output is self-refuting.

• Caps everywhere — every list is bounded (see info.limits) and every cap

readable; escaping symlinks are rejected. info reports the root.

• Path sandbox — only files under the server's working directory are

• Errors name the fix — {error, path, hint}, with isError set.

Install

Shortened. The full README is on GitHub.