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 config with this install's absolute path:

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

No system packages and no native build — tree-sitter runs as WebAssembly, so it works anywhere Node 18+ runs (Linux, macOS, Windows via WSL/Git Bash). The installer checks Node, runs npm ci, builds (tsc → dist/), self-tests the full suite (143 tests), and generates mcp-config.json.

Register it with your client — the generated mcp-config.json looks like:

{
  "mcpServers": {
    "lens": { "command": "node", "args": ["/abs/path/lens-mcp/dist/index.js"] }
  }
}

• Claude Code: claude mcp add lens -- node /abs/path/lens-mcp/dist/index.js (or copy mcp-config.json into a project as .mcp.json)
• Cursor / Windsurf: merge mcp-config.json into ~/.cursor/mcp.json
• Codex CLI: add [mcp_servers.lens] with the same command/args to ~/.codex/config.toml

lens reads files under its working directory — the project your client launches it in. Point it at a project and call map("."). Nothing outside the working directory is readable.

Update later, in place:

./update.sh          # git pull --ff-only + reinstall + self-test

_{Prefer to do it by hand? npm install && npm run build && npm test, then run node dist/index.js.}

Lineage

lens-mcp supersedes the earlier split servers codelens-mcp (code) and docslens-mcp (docs) — same engines, one server, one pipeline. Sibling of periscope-mcp (web-app QA); built to the same standard: honest errors, caps + truncated flags everywhere, docs == behavior, tests before release.

Built by Segentic Lab. AGPL-3.0.