lens-mcp

lens-mcp is a Model Context Protocol server that gives an AI agent deterministic navigation maps over source code and markdown docs — one server, two lenses: tree-sitter for TypeScript / JavaScript / Python, and a markdown lens for docs.

The point is context economy. 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 — and because it’s real parsing, not a model summarizing, the map is the same every time.

What makes it different

• map in one call. The whole project’s surface — every code file’s structure and every doc’s outline — in a single response. Start here instead of browsing.
• Read the minimum. function_body returns one function’s source (often ~99% less context than the file it lives in); heading returns one doc section by heading, slug, or line number.
• Honest by construction. Syntax errors surface (hasErrors + parseErrors) instead of vanishing; every list is capped with the true total; a code tool called on a .md (or vice versa) fails with a pointer to the right tool. The contract is explicit: lens is a navigation map — locate with it, then Read the real source before judging or modifying.
• Zero-friction install. No system packages, no native build — tree-sitter runs as WebAssembly, so it works anywhere Node 18+ runs. One line clones, builds, self-tests (138 tests), and writes your client config.
• Self-maintaining. A lens_system tool reports its version, fetches the current AGENTS.md to refresh a stale pasted guide, and self-updates in place.

Two servers, merged

lens is the consolidation of two earlier servers — codelens (code) and docslens (docs) — into one. Same battle-tested parsing engines, now a single server with one release pipeline and a unified map that spans both. Fewer, sharper tools instead of two near-duplicates.

Get it

Open-source under AGPL-3.0 → github.com/segentic-lab/lens-mcp. Works with any MCP client — Claude Code, Cursor, Codex, or your own agent.

git clone https://github.com/segentic-lab/lens-mcp && cd lens-mcp && ./install.sh

It ships with an AGENTS.md you paste into your agent’s system prompt — the map → drill → read workflow and the “map, not the territory” rule. If it’s useful, a ⭐ on the repo helps.