# codelens-mcp

> ## ⚠️ Superseded by [lens-mcp](https://github.com/segentic-lab/lens-mcp)
>
> **codelens has merged into [`lens-mcp`](https://github.com/segentic-lab/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.

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

## Languages

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

## 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

```bash
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:

```json
{
  "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](LICENSE).