codelens-mcp-1.9.43 is not a library.

codelens-mcp

Harness-native Model Context Protocol (MCP) server binary for CodeLens — a compressed-context and verification layer for multi-agent coding harnesses like Claude Code, Codex, Cursor, and Continue.

Built on 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 for reproducible numbers (tiktoken cl100k_base).

Architecture

┌───────────────────────────────────────────────────────────┐
│   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:

Surface	Intended role	Mutation?	Response cap
`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

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

# 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

{
  "mcpServers": {
    "codelens": { "command": "codelens-mcp", "args": [] }
  }
}

Shared HTTP daemon (multi-agent)

# 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

Feature	Default	Adds
`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.

codelens-mcp 1.9.43