mcplens

AI 코딩 어시스턴트를 위한 의미론적 코드베이스 검색 — 토큰 70-85% 절감, 100% 로컬, 클라우드 의존성 제로.

Claude Code, Cursor, Codex와 같은 AI 코딩 어시스턴트는 강력하지만 근본적인 문제가 있습니다. 질문을 하면 경로와 파일 이름 휴리스틱에 기반하여 관련이 있을 법한 파일을 추측하여 읽습니다. 중간 규모 프로젝트에서 단일 쿼리는 관련조차 없을 수 있는 파일을 로드하는 데만 10,000~20,000개의 컨텍스트 토큰을 소비할 수 있습니다.

claude-context-optimizer는 AI 어시스턴트에게 코드베이스에 대한 의미론적 검색 기능을 제공하여 이 문제를 해결합니다. 파일을 무작위로 읽는 대신 search_code("결제 기능은 어떻게 작동하나요?")를 호출하여 가장 관련성이 높은 5개의 코드 청크만 가져옵니다. 이는 로컬에서 임베딩을 사용하여 인덱싱되고 SQLite에 저장되므로 데이터가 기기 밖으로 나가지 않습니다.

작동 방식

프로젝트에서 AI 어시스턴트를 열면:

1. MCP 서버가 자동으로 시작됩니다 (어시스턴트에 의해 stdio를 통해 생성됨)

2. 파일 해시를 이전 인덱스와 비교하여 변경된 파일만 다시 인덱싱합니다 (델타 인덱싱)

3. 파일 감시자가 코딩하는 동안 인덱스를 동기화 상태로 유지합니다

4. 이제 어시스턴트는 원시 파일을 읽는 대신 3가지 의미론적 검색 도구에 액세스할 수 있습니다

You ask: "how does the Asaas webhook work?"

Without cco:                          With cco:
  Read AsaasWebhookController.php       search_code("asaas webhook")
  Read AsaasWebhookService.php          → returns 5 relevant chunks
  Read PaymentService.php               → ~800 tokens total
  Read BillingModule.php
  Read ...8 more files
  → ~15,000 tokens total

내부 구조

• 임베딩: nomic-embed-text (768-dim)를 사용하는 Ollama — 100% 로컬, 무료, API 키 불필요

• 벡터 저장소: 프로세스 내에서 코사인 유사도를 계산하는 SQLite — 추가 인프라 불필요

• 청킹: tree-sitter를 통한 AST 인식 (함수/클래스별 분할) 및 슬라이딩 윈도우 폴백

• 전송: MCP stdio — 어시스턴트가 프로세스를 생성하고 파이프를 통해 통신

• 지속성: 인덱스는 .claude-context/index.db에 저장되며 세션 간 유지됨

Related MCP server: LocalNest MCP

호환성

claude-context-optimizer는 모든 MCP 호환 AI 코딩 어시스턴트와 작동합니다. MCP(Model Context Protocol)는 개방형 표준이므로 동일한 서버가 수정 없이 모든 클라이언트에서 작동합니다.

init 명령은 사용 중인 어시스턴트를 감지하고 올바른 위치에 서버를 자동으로 등록합니다.

토큰 절감 효과

인덱스는 로컬에 저장됩니다. 어시스턴트는 관련 있는 내용만 가져옵니다. 수치가 이를 증명합니다:

이는 사용자가 제어하는 컨텍스트 토큰입니다. 프로젝트 규모가 클수록 기본적으로 휴리스틱 파일 읽기가 더 많이 발생하므로 절감 효과는 프로젝트 규모에 따라 커집니다.

제공 도구

어시스턴트에게 가이드를 제공하려면 프로젝트의 CLAUDE.md(또는 이에 상응하는 파일)에 다음을 추가하세요:

## Context Search

Always use MCP tools before reading files:

- search_code() — for conceptual or natural language queries
- get_symbol() — for exact class/function/method lookups
  Only read full files if both tools return insufficient context.

설치 옵션

옵션 A — npm (Ollama 필요)

오버헤드 없음. 이미 Ollama가 설치된 개발자에게 가장 적합합니다.

npm install -g @vmsfigueredo/mcplens
ollama pull nomic-embed-text:latest
cd your-project && mcplens init

전체 설정 지침은 INSTALL.md를 참조하세요.

옵션 B — Docker

아직 지원되지 않음. Docker 배포(Node + Ollama + 모델 번들링)가 계획되어 있으나 아직 구현되지 않았습니다. 로드맵에서 진행 상황을 확인하세요.

설정

.claude-context/config.json은 init에 의해 자동으로 생성됩니다. 동작을 사용자 정의하려면 편집하세요:

{
  "embeddings": {
    "provider": "ollama",
    "ollamaUrl": "http://localhost:11434",
    "ollamaModel": "nomic-embed-text:latest"
  },
  "search": {
    "topK": 5,
    "minScore": 0.3
  },
  "ignore": [
    "**/tests/fixtures/**"
  ]
}

OpenAI 임베딩을 대신 사용하려면:

{
  "embeddings": {
    "provider": "openai",
    "openaiApiKey": "sk-...",
    "openaiModel": "text-embedding-3-small"
  }
}

인덱싱 대상

기본 포함: .ts .tsx .js .jsx .mjs .php .svelte .vue .py .rb .go .rs .css .scss .json .yaml .yml .md .sql

기본 제외: node_modules, .git, vendor, dist, build, .next, .claude-context

.claude-context/ 디렉토리는 자동으로 .gitignore에 추가됩니다.

인덱스 크기 참조

대시보드

서버가 실행되는 동안 http://localhost:3000에서 가벼운 웹 대시보드를 사용할 수 있습니다:

• 개요 — 인덱싱된 파일, 청크, 인덱스 크기, Ollama 상태

• 활동 — 재인덱싱 이벤트 실시간 피드

• 검색 — 수동으로 쿼리를 테스트하고 점수 확인 ( minScore 보정에 유용)

• 파일 — 청크 수를 포함한 인덱싱된 파일 전체 목록

대시보드는 기본적으로 3333 포트에서 실행됩니다. 해당 포트가 이미 사용 중인 경우(예: 두 프로젝트를 동시에 여는 경우), 포트는 프로젝트 이름에서 자동으로 계산됩니다. 열려면:

mcplens dashboard

비활성화하려면: MCP 설정의 서버 인수에 --no-dashboard를 추가하세요.

개인정보 보호

모든 작업은 사용자 기기에서 실행됩니다:

• 임베딩은 Ollama를 통해 로컬에서 생성되므로 코드가 외부로 유출되지 않습니다

• 인덱스는 프로젝트 내 .claude-context/index.db에 저장됩니다

• 텔레메트리, 분석, 계정 정보 없음

⚠️ OpenAI 임베딩 옵션을 사용하는 경우, 청크가 OpenAI API로 전송됩니다.

왜 기존 도구를 사용하지 않나요?

목표는 가장 기능이 완벽한 도구가 아니라 JS/TS 개발자가 가장 쉽게 접근할 수 있는 옵션이 되는 것입니다. Node.js가 이미 설치되어 있다면 명령어 하나로 설치할 수 있습니다.

로드맵

• [x] tree-sitter를 통한 AST 기반 청킹

• [x] 파일 해시별 델타 인덱싱

• [x] 실시간 파일 감시자

• [x] 대시보드

• [x] 멀티 클라이언트 초기화 (Claude Code, Cursor, Windsurf, Trae)

• [x] 하이브리드 검색 (BM25 + 의미론적)

• [ ] Ollama 번들 포함 Docker 옵션

• [ ] 컨텍스트 검색 (LLM 생성 청크 요약)

• [ ] Claude Code 훅을 통한 토큰 사용량 분석

기여

PR을 환영합니다. 로컬 개발 설정은 INSTALL.md를 참조하세요.

제작 도구

이 프로젝트는 Claude Code를 사용하여 제작되었으며, 바로 그 이유 때문에 이 프로젝트가 존재합니다.

라이선스

MIT