The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Codelens MCP listing page.
⚠️ Superseded by lens-mcp
codelens has merged into
lens-mcp— one MCP server that maps both code and markdown docs. It carries every codelens tool (map,overview,functions,function_body,comments,find,info) unchanged, plus doc tools (outline,heading,links,search) and a unifiedmapthat returns a whole project's code structure and doc outlines in one call.Use lens-mcp instead —
git clone https://github.com/segentic-lab/lens-mcp. This repo remains only so existing links resolve; it is no longer developed.(The description below is retained for reference.)
Deterministic structural code maps for AI agents. An MCP server (stdio) that gives agents the shape of a codebase — imports, exports, classes, functions, signatures, comments, TODO-markers — without reading whole files into context. Powered by tree-sitter WASM grammars: no native build step, installs anywhere Node 18+ runs.
The contract: codelens is a navigation map. Use it to locate code, then
Read the actual source before judging or modifying it. A signature is not
the body; an outline is not the section.
7 read-only tools. Every list in every response is capped, and every cap is
reported with an explicit truncated flag — no silent cutoffs.
| Tool | What it does |
|---|---|
map | Per-file structural overview of a whole directory tree in one call. Skips node_modules, dist, venv, hidden dirs, etc. The orientation tool. |
overview | One file's top-level structure: imports, exports, classes (with method names), functions — all with 1-based line/endLine. |
functions | Every addressable function in a file — nested functions, methods, getters/setters, class-field arrows, object-literal properties, default exports — with reconstructed signatures, param types, return type, async/exported flags, and parent scope. (Anonymous callbacks passed as arguments and Python lambdas are not listed — they have no name to navigate to.) |
comments | All comments with line ranges, kind (line/block/doc), and TODO/FIXME/FIX/BUG/HACK/NOTE/XXX marker detection (uppercase-only, no prose false-positives). markersOnly: true returns just the debt list. |
function_body | Verbatim source of one function (with decorators) by bare or dotted name (Widget.render) — the focused read that replaces whole-file Reads. Ambiguous names fail listing the candidates; it never guesses. |
find | "Where is X defined?" — locate function/method/class definitions by name across a directory. Definitions only, not call sites. |
info | Server self-description: version, working directory (the path sandbox root), languages, caps. |
overview, functions, and comments accept a single path or an array of up
to 20 paths per call.
| Extension | Language | Grammar |
|---|---|---|
.ts, .mts, .cts | TypeScript | tree-sitter-typescript |
.tsx | TypeScript + JSX | tree-sitter-tsx (dedicated grammar — JSX parses correctly) |
.js, .jsx, .mjs, .cjs | JavaScript | tree-sitter-javascript |
.py | Python | tree-sitter-python |
The server only reads files under its own working directory (the directory
it was launched from). Relative paths resolve against it; absolute paths are
accepted only if they point inside it; symlinks that escape it are rejected.
The info tool reports the root, and every rejection names it. Launch the
server from the project you want mapped.
hasErrors: true plus parseErrors line ranges, because tree-sitter
error-recovery can drop code near the error.isError on the MCP result and return
{error, path, hint} — the hint says how to fix the call.{requested, succeeded, failed} summary; isError only when every file failed.truncated flags carry the true totals.MCP client config:
AGENTS.md in this repo is a paste-ready guide for teaching an agent to use
these tools well — core model, per-tool tips, and the pitfalls (path sandbox,
language coverage, the map-vs-territory rule).
AGPL-3.0 — see LICENSE.