codelens-mcp

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.

Related MCP server: code-analyze-mcp

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.