MCP 인텔리전스 컨텍스트

코드베이스의 파일, 심볼, 의존성 그래프를 인덱싱하고, 에이전트가 전체 저장소를 스캔하는 대신 작고 집중된 컨텍스트 패키지를 받을 수 있게 해주는 저장소 인텔리전스 MCP 서버입니다.

왜 필요한가

에이전트가 대규모 저장소에 대해 모호한 질문을 받으면, 관련 코드를 찾기 전에 디렉터리를 반복적으로 나열하고, 관련 없는 파일을 열고, 구조를 다시 파악해야 하는 경우가 많습니다 — 이는 토큰과 시간을 낭비합니다. 이 프로젝트는 저장소의 지속적이고 증분 업데이트되는 인덱스(파일, 심볼, 임포트, 역의존성)를 구축하고, 쿼리와 관련된 컨텍스트만 대략적인 토큰 예산에 맞춰 반환하는 MCP 도구를 제공합니다.

Related MCP server: lens

작동 방식

1. index_repository는 저장소를 탐색하고(.gitignore 존중), Python 파일은 ast로, JS/TS 파일은 가벼운 정규식 휴리스틱으로 파싱하여 함수/클래스/임포트/익스포트를 추출하고 역의존성 그래프를 구축합니다. 인덱스는 .mcp_intel_cache/index.json에 캐시되며, 변경된 파일만(mtime/크기 기준) 다시 파싱하는 방식으로 증분 갱신됩니다.

2. search_code / get_relevant_context는 심볼 이름, 파일 이름, docstring/요약, 임포트 매칭을 기준으로 파일을 순위화하고(어휘/심볼 검색 — 이 MVP에는 임베딩 없음), 토큰 예산에 맞는 컨텍스트 패키지(심볼 테이블 + 작은 코드 발췌문, 전체 파일 아님)를 반환합니다. get_relevant_context는 또한 전체 저장소를 단순 스캔하는 방식과 비교한 token_savings 수치를 도구 응답 자체에 보고합니다.

3. get_file_summary / get_dependencies는 에이전트가 전체 파일을 읽지 않고도 특정 파일의 심볼이나 영향 범위(임포터/임포트)를 파고들 수 있게 해줍니다.

4. 캐시된 인덱스가 5분 이상 지났고 라이브 watcher가 활성화되어 있지 않은 경우 도구는 staleness 경고를 보고합니다. 실제로는 저장소에 대한 첫 도구 호출 시 백그라운드 파일 watcher(watchdog 기반)가 시작되어 생성/수정/삭제 이벤트를 메모리 내 인덱스에 즉시 적용하므로, 코드가 변경되어도 세션 중에 수동 재인덱싱이 필요 없습니다. 온디스크 캐시는 디바운스(~2초) 후 플러시되므로 빠른 저장에도 키 입력마다 쓰기가 발생하지 않습니다.

저장소 구조

src/mcp_intelligence_context/   Python MCP server package
  walker.py                     gitignore-aware file walker
  parsers/                      Python (ast) and JS/TS (regex) symbol extraction
  indexer.py                    builds/caches the RepoIndex, resolves imports
  watcher.py                    background file watcher that keeps the index live
  search.py                     lexical/symbol search + reverse-dep lookups
  context_builder.py            token-budgeted context package assembly
  server.py                     MCP tool definitions (stdio server)
vscode-extension/                VS Code extension wrapper (setup/reindex/status commands)
scripts/                         one-command bootstrap for new users

빠른 시작 (신규 사용자)

MCP를 처음 사용하고 VS Code에서 바로 작동시키고 싶다면:

git clone https://github.com/LeoChimal09/MCP-INTELLIGENCE-CONTEXT.git
cd MCP-INTELLIGENCE-CONTEXT
bash scripts/setup_mcp_workspace.sh

이 스크립트가 수행하는 작업:

1. pipx로 mcp-intelligence-context를 설치(또는 업데이트)합니다.

2. 이 워크스페이스에 .vscode/mcp.json을 작성합니다.

3. MCP_INTEL_ALLOWED_ROOTS=${workspaceFolder}를 설정하여 인덱싱을 현재 워크스페이스 폴더로 제한합니다.

그런 다음 VS Code에서:

1. 명령 팔레트 → MCP: List Servers.

2. mcp-intelligence-context 시작/재시작.

3. Copilot Chat 도구 선택기에서 mcp-intelligence-context 활성화.

pipx가 없다고 표시되면 한 번 설치하세요:

brew install pipx
pipx ensurepath

MCP 서버 단독 실행

python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/mcp-intelligence-context        # or: python -m mcp_intelligence_context.server

MCP_INTEL_REPO_ROOT를 설정하여 인덱싱할 저장소를 지정하거나, 도구 호출 시 repo_root 인자로 명시적으로 전달할 수 있습니다(기본값은 서버의 현재 작업 디렉터리).

이 저장소를 클론하지 않고 설치하기

다른 사용자는 로컬 체크아웃이 필요 없습니다 — git 저장소에서 직접 설치하거나(또는 게시된 경우 PyPI에서):

python3 -m venv .venv
.venv/bin/pip install "git+https://github.com/LeoChimal09/MCP-INTELLIGENCE-CONTEXT.git"
# once published: .venv/bin/pip install mcp-intelligence-context

mcp-intelligence-context 콘솔 스크립트와 MCP_INTEL_REPO_ROOT 환경 변수는 어느 쪽이든 동일하게 작동합니다 — pip install 소스만 다를 뿐입니다.

MCP 클라이언트(예: VS Code)에 등록

대상 워크스페이스의 .vscode/mcp.json에 추가:

{
  "servers": {
    "mcp-intelligence-context": {
      "type": "stdio",
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "mcp_intelligence_context.server"],
      "env": { "MCP_INTEL_REPO_ROOT": "${workspaceFolder}" }
    }
  }
}

VS Code 확장

vscode-extension/은 세 가지 명령을 제공하는 얇은 래퍼 번들입니다:

• MCP Intelligence: Setup Server — Python 패키지를 설치하기 위한 venv를 생성하고 위의 .vscode/mcp.json 항목을 작성합니다.

• MCP Intelligence: Reindex Repository — 열린 워크스페이스의 인덱스를 강제로 다시 구축합니다.

• MCP Intelligence: Show Status — 캐시된 인덱스의 파일 수, git 커밋, 경과 시간을 출력합니다.

기본적으로 "Setup Server"는 이 프로젝트의 git 저장소에서 확장의 private storage 아래 venv로 패키지를 설치합니다 — 로컬 클론이 필요 없습니다. 두 가지 설정으로 제어합니다:

• mcpIntelligenceContext.serverPath — 로컬 편집 가능한 체크아웃을 가리킬 때 사용(이 저장소 개발용); 비어 있으면 기본 동작.

• mcpIntelligenceContext.pythonPackageSource — serverPath가 비어 있을 때 pip 설치 대상을 재정의합니다(예: PyPI 패키지 이름).

빌드 방법:

cd vscode-extension
npm install
npm run compile

그런 다음 VS Code에서 F5를 눌러(vscode-extension/이 열린 상태에서) 확장 개발 호스트를 시작합니다.

사용 가능한 MCP 도구

실제 효과 평가

eval/에는 이 코드베이스 자체에 대한 작고 정직한 벤치마크가 포함되어 있습니다(LLM 호출 없음, 조작된 수치 없음): 10개의 수작업 쿼리와 알려진 ground-truth 파일로, 인덱스 기반 도구를 단순 기준선(트리 나열, grep, 일치하는 전체 파일 읽기)과 비교합니다.

.venv/bin/python eval/run_eval.py

hit@1/hit@3(상위 결과가 올바른 파일인가), 평균 토큰 절감, 지연 시간을 보고합니다. 이는 검색/토큰 효율성만 측정합니다 — 실제 Copilot 답변 품질이 더 나은지는 측정하지 않습니다. 실제 모델 응답 품질을 평가하려면 LLM 호출이 필요하기 때문입니다.

현재 한계 (MVP)

• JS/TS 파싱은 정규식 기반(완전한 AST 아님)이므로 특이한 문법은 놓칠 수 있습니다. Python 파싱은 표준 ast 모듈을 사용하므로 정확합니다.

• 검색은 어휘/심볼 기반뿐입니다(불용어 필터링과 누적 다중 신호 점수 사용); 임베딩/의미 기반 검색은 아직 없습니다.

• 파일 watcher는 개별 파일 변경은 적용하지만 .gitignore 자체의 변경은 다시 탐색하지 않습니다 — .gitignore가 수정된 경우 index_repository를 refresh=true로 한 번 실행하여 새 규칙을 반영하세요.

프로덕션/광범위한 사용 전 보안 고려사항

이미 해결됨:

• 셸 인젝션 — VS Code 확장이 이전에 워크스페이스 설정을 셸 명령 문자열에 직접 보간하던 것을, 이제 execFile과 인자 배열을 사용하고(셸 없음), 신뢰할 수 없는 워크스페이스에서는 "Setup Server" 실행을 거부합니다.

• 심볼릭 링크 탈출 — 탐색기가 저장소 루트 외부로 해석되는 심볼릭 링크를 건너뜁니다(예: /etc/passwd를 노출하는 심볼릭 링크 차단).

• 비밀 정보 누출 — 일반적인 자격 증명 패턴과 일치하는 파일명(.env, *.pem, id_rsa, credentials.json 등, config.py의 SENSITIVE_FILENAME_PATTERNS 참조)은 gitignore 여부와 관계없이 건너뛰므로 내용이 도구 출력에 포함되지 않습니다.

• 손상된 캐시 크래시 — 변조/손상된 .mcp_intel_cache/index.json이 있으면 서버가 시작 시 크래시하는 대신 깨끗하게 재구축합니다.

• ReDoS — JS/TS 정규식 파서는 병리적으로 긴 단일 라인(난독화/압축 파일)을 건너뛰어 catastrophic-backtracking DoS를 방지합니다.

• 무제한 repo_root — MCP_INTEL_ALLOWED_ROOTS(:로 구분된 절대 경로 목록)를 설정하여 서버가 인덱싱할 디렉터리를 제한할 수 있습니다. 기본값은 미설정으로, 현재의 유연한 단일 사용자 동작을 유지합니다.

아직 아키텍처 수준의 문제로 완전히 해결되지 않음 — 단일 로컬 사용자 이상으로 배포하기 전에 반드시 읽어보세요:

• 공유/멀티테넌트 네트워크 서비스로는 안전하지 않습니다. 이는 로컬, 프로세스당 한 사용자의 stdio 서버로 설계되었습니다. 메모리 내 인덱스/watcher 캐시에는 사용자별 격리나 인증이 없습니다. 호출자별 샌드박싱과 인증을 추가하지 않고 공유 HTTP/SSE 엔드포인트로 노출하지 마세요.

• 의존성 버전이 고정되어 있지 않습니다(>=만 사용) — 재현 가능하고 검증된 프로덕션 설치를 위해 정확한 버전을 고정하거나 잠금 파일을 사용하세요(이미 mcp 1.x → 2.0의 breaking API 변경으로 한 번 문제가 발생한 적이 있습니다).

• 이 코드베이스 자체에 대한 자동화된 회귀 테스트가 아직 없습니다 — 변경 사항은 현재 수동 eval/ 하네스와 임시 실행으로 검증되며, CI 기반 테스트 스위트가 아닙니다.