# codelens-mcp
Harness-native Model Context Protocol (MCP) server binary for
[CodeLens](https://github.com/mupozg823/codelens-mcp-plugin) — a
compressed-context and verification layer for multi-agent coding harnesses
like Claude Code, Codex, Cursor, and Continue.
Built on [codelens-engine](https://crates.io/crates/codelens-engine).
Exposes ~107 tools over JSON-RPC stdio or streamable HTTP, with role-
based tool surfaces, adaptive token compression, mutation gates, and
durable analysis job handles.
## What problem it solves
Multi-agent coding harnesses burn tokens on `tools/list`, repeated file
reads, and unbounded graph expansion. `codelens-mcp` keeps a live,
indexed view of the codebase and answers precise questions with bounded
responses plus a handle for optional drill-down — typically cutting
6-170× fewer tokens than a `rg + cat` loop on the same task.
See [docs/benchmarks.md](https://github.com/mupozg823/codelens-mcp-plugin/blob/main/docs/benchmarks.md)
for reproducible numbers (tiktoken cl100k_base).
## Architecture
```text
┌───────────────────────────────────────────────────────────┐
│ MCP client (Claude Code · Codex · Cursor · Continue) │
└──────────────────────────┬────────────────────────────────┘
│ JSON-RPC over stdio / HTTP
▼
┌───────────────────────────────────────────────────────────┐
│ server/ router · oneshot · transport_stdio · http│
│ dispatch/ envelope · table · rate_limit · response │
│ tool_defs/ surfaces · presets · profiles · schemas │
│ tools/ 107 tool handlers (symbols · reports · │
│ mutation · lsp · memory · session …) │
│ state/ session_host · embedding_host · metrics │
│ access · mutation_gate · telemetry · analysis_queue │
└──────────────────────────┬────────────────────────────────┘
▼
codelens-engine (data plane)
▼
.codelens/{symbols.db, vec.db, memories, audit} per project
```
Control plane here, data plane in `codelens-engine`. The server is a
thin policy layer: it normalises tool calls, enforces surface/profile
visibility, runs mutation preflight gates, shapes responses to a token
budget, and persists durable analysis handles. All semantic work is
delegated to the engine crate.
## Tool surfaces
Five role-based surfaces bound what each agent can see in `tools/list`:
| `planner-readonly` | task decomposition, impact review | no | small |
| `builder-minimal` | implementation with preflight gates | yes | medium |
| `reviewer-graph` | diff + impact + references | no | medium |
| `refactor-full` | rename/move/extract multi-file ops | yes | larger |
| `ci-audit` | deterministic machine-schema report | no | medium |
Switch surfaces with `set_profile`. Bootstrap the whole preflight chain
with `prepare_harness_session` — the canonical entrypoint for harness
authors. See `docs/multi-agent-integration.md` for the fixed 4-step
preflight contract.
## Tool families
| Symbols | `find_symbol`, `get_symbols_overview`, `get_ranked_context` |
| References / impact | `find_referencing_symbols`, `impact_report`, `diff_aware_references` |
| Workflows (high-level) | `analyze_change_request`, `verify_change_readiness`, `safe_rename_report` |
| Async analysis | `start_analysis_job`, `get_analysis_job`, `get_analysis_section` |
| Mutation (gated) | `rename_symbol`, `replace_symbol_body`, `refactor_extract_function` |
| Session & coordination | `prepare_harness_session`, `register_agent_work`, `claim_files` |
| Memory | `read_memory`, `write_memory`, `list_memories` |
| LSP bridge | `get_file_diagnostics`, `plan_symbol_rename`, `check_lsp_status` |
## Quick start
```bash
# stdio (default). Good for a single-agent local MCP session.
cargo install codelens-mcp
# HTTP transport (shared daemon for multi-agent setups).
cargo install codelens-mcp --features http
# One-shot call from the CLI (no MCP client needed):
codelens-mcp . --cmd get_ranked_context --args '{"query":"http session bootstrap"}'
```
### MCP client config
```json
{
"mcpServers": {
"codelens": { "command": "codelens-mcp", "args": [] }
}
}
```
### Shared HTTP daemon (multi-agent)
```bash
# one read-only daemon for planners/reviewers
codelens-mcp /path/to/project --transport http --profile reviewer-graph --daemon-mode read-only --port 7837
# one mutation-enabled daemon for refactor agents
codelens-mcp /path/to/project --transport http --profile refactor-full --daemon-mode mutation-enabled --port 7838
```
See `docs/multi-agent-integration.md` for the full protocol.
## Feature flags
| `semantic` | yes | Embedding-based hybrid retrieval (via codelens-engine) |
| `http` | no | `axum` + `tokio` streamable HTTP transport |
| `otel` | no | OpenTelemetry OTLP span exporter (see `docs/observability.md`) |
| `scip-backend` | no | SCIP precise navigation backend |
| `model-bakeoff` | no | Alternative embedding-model benchmark harness |
## Non-goals
- Not a general-purpose IDE backend. No completion, no hover, no quick-fix.
- Not a replacement for rustfmt / clippy / cargo. Wraps them only as
part of the harness integration surface.
- Not a chatbot. No natural-language generation, no LLM calls, no model
hosting. CodeLens only _compresses context_ so the model can think
better.
## License
Apache-2.0. See [LICENSE](https://github.com/mupozg823/codelens-mcp-plugin/blob/main/LICENSE).