mcp-intelligence-context
MCP 인텔리전스 컨텍스트
코드베이스의 파일, 심볼, 의존성 그래프를 인덱싱하고, 에이전트가 전체 저장소를 스캔하는 대신 작고 집중된 컨텍스트 패키지를 받을 수 있게 해주는 저장소 인텔리전스 MCP 서버입니다.
왜 필요한가
에이전트가 대규모 저장소에 대해 모호한 질문을 받으면, 관련 코드를 찾기 전에 디렉터리를 반복적으로 나열하고, 관련 없는 파일을 열고, 구조를 다시 파악해야 하는 경우가 많습니다 — 이는 토큰과 시간을 낭비합니다. 이 프로젝트는 저장소의 지속적이고 증분 업데이트되는 인덱스(파일, 심볼, 임포트, 역의존성)를 구축하고, 쿼리와 관련된 컨텍스트만 대략적인 토큰 예산에 맞춰 반환하는 MCP 도구를 제공합니다.
Related MCP server: lens
작동 방식
index_repository는 저장소를 탐색하고(.gitignore존중), Python 파일은ast로, JS/TS 파일은 가벼운 정규식 휴리스틱으로 파싱하여 함수/클래스/임포트/익스포트를 추출하고 역의존성 그래프를 구축합니다. 인덱스는.mcp_intel_cache/index.json에 캐시되며, 변경된 파일만(mtime/크기 기준) 다시 파싱하는 방식으로 증분 갱신됩니다.search_code/get_relevant_context는 심볼 이름, 파일 이름, docstring/요약, 임포트 매칭을 기준으로 파일을 순위화하고(어휘/심볼 검색 — 이 MVP에는 임베딩 없음), 토큰 예산에 맞는 컨텍스트 패키지(심볼 테이블 + 작은 코드 발췌문, 전체 파일 아님)를 반환합니다.get_relevant_context는 또한 전체 저장소를 단순 스캔하는 방식과 비교한token_savings수치를 도구 응답 자체에 보고합니다.get_file_summary/get_dependencies는 에이전트가 전체 파일을 읽지 않고도 특정 파일의 심볼이나 영향 범위(임포터/임포트)를 파고들 수 있게 해줍니다.캐시된 인덱스가 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이 스크립트가 수행하는 작업:
pipx로mcp-intelligence-context를 설치(또는 업데이트)합니다.이 워크스페이스에
.vscode/mcp.json을 작성합니다.MCP_INTEL_ALLOWED_ROOTS=${workspaceFolder}를 설정하여 인덱싱을 현재 워크스페이스 폴더로 제한합니다.
그런 다음 VS Code에서:
명령 팔레트 →
MCP: List Servers.mcp-intelligence-context시작/재시작.Copilot Chat 도구 선택기에서
mcp-intelligence-context활성화.
pipx가 없다고 표시되면 한 번 설치하세요:
brew install pipx
pipx ensurepathMCP 서버 단독 실행
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/mcp-intelligence-context # or: python -m mcp_intelligence_context.serverMCP_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-contextmcp-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.pyhit@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 엔드포인트로 노출하지 마세요.
의존성 버전이 고정되어 있지 않습니다(
>=만 사용) — 재현 가능하고 검증된 프로덕션 설치를 위해 정확한 버전을 고정하거나 잠금 파일을 사용하세요(이미mcp1.x → 2.0의 breaking API 변경으로 한 번 문제가 발생한 적이 있습니다).이 코드베이스 자체에 대한 자동화된 회귀 테스트가 아직 없습니다 — 변경 사항은 현재 수동
eval/하네스와 임시 실행으로 검증되며, CI 기반 테스트 스위트가 아닙니다.
Available Tools
6 toolsget_dependenciesA
Return what a file imports and which files import it (reverse deps), to understand blast radius before changing a file.
Inputs: path (required), repo_root.
get_file_summaryB
Return the symbol table (functions/classes/methods with signatures and docstrings), imports, and exports for a single indexed file — without returning the entire file body.
Inputs: path (required), repo_root.
get_relevant_contextA
Build a focused, token-budgeted context package (symbol tables + small code excerpts) for the files most relevant to a query. This is the main entry point for "help me find/fix X" style requests — use it instead of reading whole files or globbing the repo.
Inputs: query (required), repo_root, token_budget.
get_repo_overviewA
Return a high-level architecture summary: top-level directories, language breakdown, and the files with the most symbols (likely core modules). Use this to orient before drilling into specific files.
Inputs: repo_root.
index_repositoryA
Index (or re-index) a repository: extracts files, symbols, imports and a reverse dependency graph. Call this first, and again with refresh=true after significant file changes. Uses an on-disk cache for fast re-runs.
Inputs: refresh, repo_root.
search_codeA
Search the indexed repository for files/symbols relevant to a natural language or keyword query (e.g. "authentication middleware", "parseConfig"). Returns ranked file hits with the matching symbol/reason — much cheaper than scanning the whole repo.
Inputs: query (required), top_k, repo_root.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a largely distinct purpose (index, overview, search, file details, dependencies, context), and the descriptive text flags get_relevant_context as the main entry point. However, search_code and get_relevant_context could both serve as the starting point for a 'find X' request, creating minor selection ambiguity.
All tools follow a consistent verb_noun snake_case pattern (index_, get_, search_), making the API predictable and scannable. The only minor nitpick is abbreviating 'repository' as 'repo' in get_repo_overview, but this does not affect the overall pattern.
Six tools sit at the sweet spot for a code-intelligence server, each earning its place in the index-query workflow. The set covers setup, orientation, discovery, drill-down, and impact analysis without bloat.
The core indexing-to-context pipeline is well covered, including re-indexing via refresh and reverse-dependency analysis for safe edits. Minor gaps exist (no full-file body reader, no way to list indexed repositories or explicitly purge the cache), but these seem like intentional scope decisions for a token-budget-focused tool.
Related MCP Connectors
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Related MCP Servers
AlicenseNot gradedqualityDmaintenanceProvides AI coding agents with structured access to indexed codebases via semantic search, symbol analysis, and file reading tools.13Server Side Public , v 1- AlicenseNot gradedqualityCmaintenanceProvides token-efficient code retrieval for coding agents by indexing repositories and enabling ranked snippet search, symbol outlines, and surgical line reads.5 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables LLM agents to efficiently understand and navigate a codebase by providing semantic search over symbols and a reference graph, replacing expensive grep/glob calls with structured tools like definition lookup, caller/callee queries, and change-impact analysis.4MIT
- FlicenseNot gradedqualityBmaintenanceProvides efficient code navigation and graph-based analysis for AI agents, enabling symbol resolution, callers, implementations, and type schemas with minimal token usage.-