Whole-project surface in ONE call — the orientation tool over a mixed tree of code AND docs. Walks a directory recursively (skipping node_modules, .git, dist, build, venv, pycache, target, vendor, hidden dirs) and returns JSON {path, code:{files[{path, language, totalLines, classes[], functions[], hasErrors?, error?}], totalSupportedFiles, filesParsed, truncated}, docs:{docs[{path, title, headingCount, outlinePreview[], bytes}], totalDocs, truncated}, summary:{codeFiles, docFiles}}. Code files (.ts .tsx .mts .cts .js .jsx .mjs .cjs .py) report structure; doc files (.md .markdown .mdx) report title + shallow outline. Caps: 200 code files and 200 docs per call (truncated flags carry the true totals — map a subtree to go deeper). Unparseable files appear with an inline error, never vanish. Use FIRST to decide which files matter, then the drill-down tools (overview/functions for code, outline/heading for docs). lens is a navigation map over code and docs: use it to LOCATE things, then Read the actual source/section before judging or modifying it. A signature is not the body; an outline is not the section.

Server self-description: version, working directory (the path sandbox root — every path you pass must resolve inside it), supported code languages and doc extensions, the tool list, and every output cap. Returns JSON {name, version, workingDirectory, code:{languages}, docs:{extensions}, tools[], limits, contract}. Read-only, no parameters. Call this first if a path is rejected or to learn what the server can see.

Structural map of a source file: imports, exports, classes (with method names, incl. class-field arrow methods), and top-level functions — each with 1-based line/endLine to jump straight to a Read. Returns JSON {path, language, totalLines, hasErrors, imports[], exports[], classes[{name,line,endLine,methods[]}], functions[{name,line,endLine,exported}]}. hasErrors:true means syntax errors and items may be missing (parseErrors lists offending ranges). Nested functions are in the functions tool. Lists cap at 500 (truncated. holds the true total). Languages: TS/TSX/JS/JSX/Python (Python exports from all). For markdown files use outline instead. Use FIRST to orient in an unfamiliar source file. lens is a navigation map over code and docs: use it to LOCATE things, then Read the actual source/section before judging or modifying it. A signature is not the body; an outline is not the section.

Every addressable function in a source file — nested functions, class methods, getters/setters, class-field arrows, namespace members, object-literal methods, default-export functions — with reconstructed signatures. NOT listed: anonymous callbacks, TS overload signatures (only implementations), Python lambdas. Returns JSON {path, language, hasErrors, functions[{name, signature, params[{name,type}], returnType, line, endLine, async, exported, kind, parent}]}. kind is function|method|arrow|getter|setter; parent is the enclosing scope, dotted for nesting ('Widget.render'), null at top level; default exports are named 'default'. Caps at 500 (truncated.functions = true total). Use to pick a line range to Read or read one body with function_body. lens is a navigation map over code and docs: use it to LOCATE things, then Read the actual source/section before judging or modifying it. A signature is not the body; an outline is not the section.

Verbatim source of ONE function — the focused read. Instead of Reading a whole file, get exactly that function's source (signature + decorators + body). Returns JSON {path, name, parent, kind, signature, line, endLine, async, exported, hasErrors, body}. name matches the bare or dotted-qualified form from functions/find ('Widget.render'); if ambiguous the call FAILS listing candidates with lines — pass the qualified name or line, it never guesses. body is real source, capped at 20000 chars (truncated.bodyChars = true length — Read line..endLine for the rest). The body IS the territory for this one function (reason about its internals) — but re-Read before editing. Languages: TS/TSX/JS/JSX/Python.

All comments in a source file with 1-based line ranges, kind (line | block | doc — doc covers /** */ and Python docstrings), and marker detection. Returns JSON {path, language, hasErrors, comments[{line, endLine, text, kind, marker}]}. marker is TODO|FIXME|FIX|BUG|HACK|NOTE|XXX when the comment contains that UPPERCASE word (case-sensitive, avoids prose false-positives), else null. markersOnly:true returns only marked comments (the debt list). Text clips at 600 chars; list caps at 500. Languages: TS/TSX/JS/JSX/Python. lens is a navigation map over code and docs: use it to LOCATE things, then Read the actual source/section before judging or modifying it. A signature is not the body; an outline is not the section.

Locate a DEFINITION by name across a directory — "where is X defined?" without grepping. Finds functions, methods, classes, AND non-callable top-level symbols: const/let/var bindings, type aliases, interfaces, and enums (a codebase's source-of-truth often lives in export const …). For text inside markdown docs use search; for who USES a symbol use references. Returns JSON {query, path, matches[{file, name, kind, line, signature, parent}], filesScanned, totalSupportedFiles, truncated, skipped?}. kind is function|method|arrow|getter|setter|class|const|let|var|type|interface|enum|variable. Matching is case-insensitive substring by default; exact:true for exact-name. Unsearchable files are listed in skipped with the reason. Caps: scans up to 300 files, returns up to 100 matches (truncated:true = more exist). Definitions only, not call sites. Languages: TS/TSX/JS/JSX/Python. lens is a navigation map over code and docs: use it to LOCATE things, then Read the actual source/section before judging or modifying it. A signature is not the body; an outline is not the section.

Find who USES a symbol across a directory — the inverse of find. "Who calls X", "what imports it", "where is it used as a type". The reference workflow lens otherwise sends you to grep for, but tree-sitter-backed so a same-named string or comment is never a false positive. Returns JSON {symbol, path, references[{file, line, kind, context}], byKind, filesScanned, totalSupportedFiles, truncated, skipped?}. kind is call | instantiation | import | type-ref | reference | definition (the definition site is included, labelled). context is the source line. Matching is EXACT (references need precision). Caps: scans up to 400 files, returns up to 300 references (truncated:true = more exist — narrow the path). Languages: TS/TSX/JS/JSX/Python. lens is a navigation map over code and docs: use it to LOCATE things, then Read the actual source/section before judging or modifying it. A signature is not the body; an outline is not the section.

Full heading hierarchy of one markdown file with 1-based line numbers — its table of contents. Recognizes ATX (#…) and setext (===/---) headings; skips headings inside fenced code blocks and YAML frontmatter; handles CRLF. Returns {path, totalHeadings, truncated, headings:[{depth, text, line}], totalLines}; capped at 500. For source code use overview instead. Pick a section here, then read only it with heading(). lens is a navigation map over code and docs: use it to LOCATE things, then Read the actual source/section before judging or modifying it. A signature is not the body; an outline is not the section.

Read ONE section of a markdown file instead of the whole file: the referenced heading plus everything under it (subsections included), stopping at the next heading of the same or higher level. ref accepts the exact heading text, its slug ("advanced-usage"), or ANY 1-based line number — a heading line from outline() or a content line from a search hit (resolves to its enclosing section, a note says so). Returns {file, heading, level, startLine, endLine, content}; on multiple matches a note says which was returned and how to pick another. The most token-frugal way to read docs — prefer it over reading whole files.

Extract every link from one markdown file: inline text, images (badge constructs yield both image and outer link), [[wikilinks]], , and reference-style [text][id] resolved via their [id]: url definitions. Skips example links inside fenced code blocks. Returns {path, totalLinks, truncated, links:[{type: markdown|image|wikilink|autolink|reference, text, target, line}]} in document order, capped at 200. Map cross-references or collect URLs without reading the file.

Case-insensitive full-text substring search across MARKDOWN docs (for code symbol definitions use find). Returns matches {path, line, snippet (≤200 chars), inHeading}, heading matches ranked first, capped at max_results (default 50, max 200) with totalMatches and truncated:true when capped. Empty/whitespace queries are rejected (they would match everything). Locate the right doc, then outline/heading to read it.

Install status, self-update, and the current agent guide — lens's self-maintenance tool. action='status' (read-only): running vs on-disk version, git commit, install type, install directory, Node version, and whether an update is available. action='agents_md' (read-only): returns the CURRENT AGENTS.md so you can refresh a stale pasted copy of your operating guide. action='update': dry-run by default (commits behind + incoming changes); apply=true runs update.sh (git pull + npm ci + build + self-test) — new code loads only after the MCP server restarts, and the response says so. force=true stashes local edits. Managed installs (no .git) refuse with guidance. Note: this operates on the lens INSTALL directory, not your project (the code tools' sandbox). Returns JSON.