codelens-mcp

⚠️ 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 unified map that 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.

Tools

7 read-only tools. Every list in every response is capped, and every cap is reported with an explicit truncated flag — no silent cutoffs.

overview, functions, and comments accept a single path or an array of up to 20 paths per call.

Languages

Path sandbox

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.

Honesty guarantees

• A file with syntax errors is never reported as a clean success: hasErrors: true plus parseErrors line ranges, because tree-sitter error-recovery can drop code near the error.
• Errors set isError on the MCP result and return {error, path, hint} — the hint says how to fix the call.
• Batch calls return per-file results plus an honest {requested, succeeded, failed} summary; isError only when every file failed.
• Every cap is visible: truncated flags carry the true totals.

Install & run

npm install
npm run build    # tsc → dist/
npm test         # build + 62 tests (51 unit, 11 stdio e2e)
node dist/index.js   # stdio MCP server (launch from the project to analyze)

MCP client config:

{
  "mcpServers": {
    "codelens": {
      "command": "node",
      "args": ["/path/to/codelens-mcp/dist/index.js"],
      "cwd": "/path/to/project-to-analyze"
    }
  }
}

For agent authors

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).

License

AGPL-3.0 — see LICENSE.