<div align="center"> <img src="docs/assets/codelens-mark.svg" width="112" height="112" alt="CodeLens logo">

CodeLens MCP

코딩 에이전트를 위한 살아 있는 코드 인덱스 — 더 적게 읽고, 더 정확하게 찾고, 안전하게 수정합니다.

_{A live code index for coding agents — bounded context, verifiable structure, and safer edits.}

설치 · 문서 · 아키텍처 · 최신 릴리스

</div>

CodeLens MCP는 에이전트나 에디터를 대체하지 않습니다. Codex, Claude Code, Cursor 같은 MCP host가 대화를 소유하는 동안, CodeLens는 저장소의 현재 구조를 인덱싱하고 필요한 맥락만 제한된 크기로 반환하며 변경 전후 검증을 연결하는 코드 인텔리전스 보조 계층입니다.

기본 바이너리는 tree-sitter, BM25/sparse retrieval, graph/LSP 탐색, mutation gate를 제공합니다. Semantic search는 별도의 model sidecar가 있을 때 지연 활성화됩니다. GitHub Release에는 모델이 포함되며, crates.io 설치는 Install Channel Matrix의 추가 설정을 따릅니다. Host 연결 방법은 Platform setup에 정리되어 있습니다.

30초 소개

_{English: CodeLens in 30 seconds.}

| 목표 | CodeLens가 제공하는 것 | | --- | --- | | 더 적게 읽기 | 문제 중심 verb와 profile/preset으로 tool 표면과 응답 크기를 제한합니다. | | 더 정확하게 찾기 | live symbol index, BM25, graph/LSP, 선택적 semantic retrieval을 한 project binding에 결합합니다. | | 현재 상태 검증 | index freshness, daemon drift, output schema, 분석 handle로 근거와 신선도를 드러냅니다. | | 안전하게 수정 | host-neutral session, single-writer runtime, role/mutation gate, audit와 readiness 검증을 적용합니다. |

cargo install codelens-mcp
codelens-mcp . --cmd get_capabilities --args '{}'

아키텍처 한눈에 보기

_{English: Architecture at a glance.}

flowchart LR
  Host["Host agents<br/>Claude Code / Codex / Cursor"] --> Transport["MCP transport<br/>stdio or HTTP daemon"]
  Transport --> Server["codelens-mcp<br/>tool surface / session binding / response envelope"]
  Server --> Dispatch["dispatch pipeline<br/>rate limit / role gate / mutation gate"]
  Dispatch --> Tools["problem-first tools<br/>explore / trace / review / verify"]
  Dispatch --> Engine["codelens-engine<br/>symbols / graph / search / LSP / edits"]
  Engine --> Index["project index<br/>tree-sitter / BM25 / SQLite / SCIP* / semantic*"]
  Server --> Ops["observability<br/>surface manifest / audit sink / tool metrics"]

  classDef host fill:#eef6ff,stroke:#4d7fb8
  classDef core fill:#f7f7f7,stroke:#777
  classDef data fill:#fff7df,stroke:#a77d20
  class Host host
  class Server,Dispatch,Tools,Engine core
  class Index,Ops data

CodeLens는 host가 대화를 소유하고, codelens-mcp가 MCP tool 표면과 session policy를 관리하며, codelens-engine이 실제 코드 index와 graph/search/edit primitive를 제공하는 구조입니다. mutation은 engine primitive를 직접 호출하지 않고 MCP dispatch pipeline을 통과해야 role gate, preflight, audit, cache invalidation이 일관되게 적용됩니다.

_{English: The host owns the conversation, codelens-mcp owns the MCP surface and session policy, and codelens-engine owns repository indexing and code-intelligence primitives. Mutations are expected to pass through the MCP dispatch pipeline so gates, audits, and cache invalidation stay consistent.}

| 영역 | 핵심 코드 | 역할 | | --- | --- | --- | | 서버 부팅/transport | crates/codelens-mcp/src/main.rs | stdio, HTTP/HTTPS, one-shot CLI, profile/preset, semantic banner, daemon mode를 선택합니다. | | MCP 요청 처리 | crates/codelens-mcp/src/server/router.rs, crates/codelens-mcp/src/dispatch/mod.rs | JSON-RPC tool call을 파싱하고 rate limit, role gate, access check, mutation gate, response shaping을 적용합니다. | | tool 표면 | crates/codelens-mcp/src/tools/mod.rs, crates/codelens-mcp/src/tool_defs/ | 100개 tool 정의, profile/preset별 visible surface, workflow alias, schema output을 관리합니다. | | session bootstrap | crates/codelens-mcp/src/tools/session/project_ops/prepare_harness.rs | prepare_harness_session(project=...)로 project binding, index recovery, host/skill hint, visible tool context를 반환합니다. | | runtime state | crates/codelens-mcp/src/state.rs, crates/codelens-mcp/src/state/ | project context cache, watcher, LSP pool, analysis artifacts, coordination claims, audit sinks, semantic engine 상태를 보관합니다. | | engine primitive | crates/codelens-engine/src/lib.rs, crates/codelens-engine/src/symbols/, crates/codelens-engine/src/search.rs | tree-sitter symbol index, sparse/BM25 ranking, hybrid search, graph/LSP/read primitive를 제공합니다. | | semantic lane | crates/codelens-mcp/src/dispatch/semantic/, crates/codelens-engine/src/embedding/ | semantic feature와 model sidecar가 있을 때 embedding indexing/search를 활성화합니다. | | 검증/감사 | crates/codelens-mcp/src/tools/reports/verifier_reports.rs, crates/codelens-mcp/src/audit_sink.rs | verify_change_readiness, analysis handle, mutation audit, session report를 제공합니다. |

<!-- SURFACE_MANIFEST_README_SNAPSHOT:BEGIN -->

Surface Snapshot

• Workspace version: 1.13.35
• Workspace members: 2 (crates/codelens-engine, crates/codelens-mcp)
• Registered tool definitions: 100
• Tool output schemas: 71 / 100
• Supported language families: 34 across 56 extensions
• Profiles: readonly (40), builder (40), review (20)
• Presets: minimal (22), balanced (69), full (95)
• Canonical manifest: docs/generated/surface-manifest.json

<!-- SURFACE_MANIFEST_README_SNAPSHOT:END -->

---

왜 필요한가

multi-agent 코딩 환경은 각 agent가 너무 많은 tool, 너무 많은 원본 코드, 너무 많은 중간 결과를 한꺼번에 보면 쉽게 느려집니다. tools/list, 반복적인 파일 읽기, 가치 낮은 raw graph expansion에 token이 낭비되고, 실제 수정에 필요한 판단 맥락은 오히려 흐려집니다.

_{English: Multi-agent coding harnesses waste tokens and attention when every agent receives too many tools, raw files, and intermediate graph results.}

CodeLens가 하는 일

CodeLens는 코드베이스의 살아 있는 index와 구조 이해를 유지하고, 이를 MCP host가 바로 사용할 수 있는 최적화 계층으로 노출합니다. 모델은 정확한 질문을 던지고, 필요한 만큼 제한된 답변과 후속 확장 handle을 받습니다. 큰 코드베이스에서도 처음부터 전체 파일을 읽지 않고 “어디를 봐야 하는지”를 먼저 좁힐 수 있습니다.

_{English: CodeLens keeps a live indexed model of the repository and returns bounded, expandable answers instead of forcing the model to read everything up front.}

Without CodeLens                                    With CodeLens (with semantic feature on)
────────────────────────────────────────────────────────────────────────────────────────────
Read file + grep references   → 4,600 tokens       get_impact_analysis    → 1,500 tokens  (67% saved)
Read manifest + entry + files → 5,000 tokens       onboard_project        →   660 tokens  (87% saved)
Read + grep × 3 files         → 3,200 tokens       get_ranked_context     →   800 tokens  (75% saved)

Measured with tiktoken (cl100k_base) on real projects with --features semantic enabled and the bundled CodeSearchNet model loaded. Reproducible via benchmarks/token-efficiency.py. The default crates.io build (BM25 + AST only) still hits the bounded-output and workflow-shape benefits but does not run the hybrid semantic ranker.

빠른 설치

_{English: Quick install options.}

기본 설치 (BM25 + AST + call-graph, model sidecar 없음) — 추가 설정 없이 바로 동작합니다:

_{English: Default install. BM25 + AST + call graph, no model sidecar required.}

cargo install codelens-mcp

Hybrid retrieval (semantic + bundled CodeSearchNet model) — semantic 검색까지 쓰려면 아래 중 하나를 선택하세요:

_{English: Pick one of these channels when you want semantic retrieval with the bundled CodeSearchNet model.}

# Option A: GitHub Release tarball — 모델이 번들되어 있고 CI에서 검증됩니다.
curl -fsSL https://raw.githubusercontent.com/mupozg823/codelens-mcp-plugin/main/install.sh | bash

# Option B: semantic feature로 cargo install 후 CODELENS_MODEL_DIR를 모델 payload로 지정합니다.
#          crates.io 10 MB 제한 때문에 모델은 별도로 받아야 합니다.
cargo install codelens-mcp --features semantic
export CODELENS_MODEL_DIR=/path/to/codesearch/model

# Option C: Homebrew tap (macOS / Linux) — release tarball과 같은 구성입니다.
brew install mupozg823/tap/codelens-mcp

HTTP daemon mode — 위 설치 경로에 --features http를 추가하면 됩니다. Source build 예시는 다음과 같습니다:

_{English: Add --features http when you want shared HTTP daemon mode.}

cargo install --git https://github.com/mupozg823/codelens-mcp-plugin codelens-mcp
cargo install --git https://github.com/mupozg823/codelens-mcp-plugin codelens-mcp --features semantic,http

The default cargo install codelens-mcp build was switched to default = [] in 1.10.0 (ADR-0012) so a fresh install boots without the ~80 MB ONNX sidecar. Existing users running cargo install --force will see the change in the startup banner.

최신 릴리스: GitHub Releases. 로컬에서 릴리스를 비교할 때는 문서에 고정 태그를 그대로 복사하지 말고 git tag --sort=-v:refname | head -1을 사용하세요.

_{English: Latest release: GitHub Releases. For local release comparisons, use git tag --sort=-v:refname | head -1 instead of copying a fixed tag into docs.}

런타임 smoke 증빙: docs/quickstart-transcript.md는 격리된 임시 prefix에서 install -> doctor/status -> index -> coverage -> retrieve 흐름을 기록합니다.

_{English: Runtime smoke proof: docs/quickstart-transcript.md captures install -> doctor/status -> index -> coverage -> retrieve from an isolated temp prefix.}

공개 저장소, 릴리스 페이지, plugin marketplace 설명은 이 README와 동일한 짧은 제품 소개 문구를 사용해야 합니다. 국가/언어별 페이지용 현지화 배포 문구는 docs/release-distribution.md#localized-deployment-page-copy에 있습니다.

_{English: Public repo, release-page, and plugin-marketplace descriptions should use the same short product line as this README. Localized deployment copy for country/language-specific pages lives in docs/release-distribution.md#localized-deployment-page-copy.}

Install Channel Matrix

| Channel | What you get | Good for | Extra install needed? | | ------------------------------------------------ | ----------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | cargo install codelens-mcp