repomap-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@repomap-mcp map the repo at /home/user/project as a planner with 2000 tokens"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
repomap-mcp
역할 인식 레포지토리 맵을 제공하는 MCP 서버. A role-aware repository map MCP server for LLM agents.
소개 / Why use it
큰 레포를 LLM 에이전트에게 통째로 먹이는 건 비싸고 노이즈도 많다. repomap-mcp 는
코드베이스를 훑어 심볼(함수·클래스 등) 그래프를 만들고 PageRank 로 중요도를 매긴 뒤,
토큰 예산 안에서 "이 레포가 무엇으로 이루어져 있는지" 를 압축한 맵을 돌려준다.
에이전트가 전역 구조를 저비용으로 파악하도록 돕는 게 목적이다.
Feeding a whole large repo to an LLM agent is expensive and noisy. repomap-mcp
walks a codebase, builds a symbol graph, ranks files by PageRank, and returns a
compact map of "what this repo is made of" within a token budget — so an agent
can grasp the global structure cheaply.
Related MCP server: Aider RepoMapper MCP Server
Features
역할별 맵 / role-aware maps —
planner(진입점 가중) ·implementer(focus 파일 집중) ·reviewer(변경 파일 + 의존자 가중) 로 랭킹을 조정. / tailor rankings per role.증분 캐시 / incremental cache — 매 호출 변경된 파일만 재파싱. / re-parse only changed files each call.
8개 언어 / 8 languages — python, csharp, javascript, go, rust, java, c, cpp.
무의존 경량 / lightweight — PageRank 를 순수 파이썬으로 구현해 numpy/scipy 불필요. / pure-Python PageRank, no numpy/scipy.
.gitignore존중 / honors.gitignore— pathspec 로 무시 규칙 반영. / respects ignore rules via pathspec.레포·소스 비오염 / non-invasive — 캐시는 OS 표준 유저 캐시에 저장, 대상 레포도 이 패키지 소스도 건드리지 않음. / cache lives in the OS user-cache dir; touches neither the target repo nor this source tree.
동작 원리 / How it works
walk → parse (tree-sitter) → graph → PageRank → compose (token budget)walk —
.gitignore(pathspec) 를 존중하며 파일을 탐색한다. / walk files, honoring.gitignore.parse — tree-sitter 로 각 파일의 tags(정의·참조 심볼)를 추출한다. / extract tags (defined/referenced symbols) per file.
graph — 심볼 이름 기반으로 파일 간 의존 그래프를 만든다. / build a file-to-file dependency graph from symbol names.
PageRank — 파일 중요도를 매긴다(순수 파이썬 구현). / rank file importance (pure-Python).
compose — 토큰 예산 안에서 상위 심볼을 골라 맵을 조립한다. / assemble the map within the token budget.
여기에 두 가지가 더 얹힌다 / Two extras sit on top:
증분 캐시 — 매 호출 디스크 스냅샷과 캐시를 diff 하여 변경된 파일만 재파싱한다. / diff disk vs. cache each call and re-parse only changed files.
역할별 personalization —
role/focus_files/changed_files로 PageRank 텔레포트 질량을 조정해 역할 맞춤 랭킹을 만든다. / steer PageRank teleport mass to tailor rankings per role.
설치 / Installation
PyPI
pip install repomap-mcp
# 또는 / or
uvx repomap-mcp # 격리 실행 / isolated run
pipx install repomap-mcp소스에서 / From source
git clone https://github.com/worktpwls/repomap-mcp.git
cd repomap-mcp
pip install . # 일반 설치 / regular install
# 또는 개발용 / or for development
pip install -e .설치하면 repomap-mcp 콘솔 스크립트와 python -m repomap_mcp 모듈 실행이 모두 활성화된다
(둘 다 stdio MCP 서버를 기동). / Both the repomap-mcp console script and
python -m repomap_mcp become available (each launches the stdio MCP server).
MCP 클라이언트 설정 / MCP client setup
이 서버는 stdio 트랜스포트 로 동작한다. / This server speaks the stdio transport. 아래 실행 경로/명령은 본인 환경에 맞게 대체하라(남의 절대경로 하드코딩 금지). Replace the launch command with your own (don't hard-code someone else's absolute path).
Claude Code
# 콘솔 스크립트로 등록 / register via the console script
claude mcp add --scope user --transport stdio repomap -- repomap-mcp
# 또는 특정 파이썬의 모듈로 등록(venv 등) / or via a specific Python's module (venv, etc.)
claude mcp add --scope user --transport stdio repomap -- /path/to/python -m repomap_mcprepomap-mcp 대신 설치 위치의 실행파일 절대경로를 써도 된다(venv 라면 그 venv 의
Scripts/(Windows) 또는 bin/(Unix) 안). / You may substitute the absolute path to the
installed executable (inside your venv's Scripts/ on Windows or bin/ on Unix).
Claude Desktop
claude_desktop_config.json 의 mcpServers 에 다음 블록을 추가한다.
Add the following block under mcpServers in claude_desktop_config.json.
{
"mcpServers": {
"repomap": {
"command": "repomap-mcp"
}
}
}콘솔 스크립트가 PATH 에 없거나 특정 venv 를 쓰려면 절대경로/모듈 형태로 바꾼다. If the console script isn't on PATH, or you want a specific venv, use an absolute path or the module form:
{
"mcpServers": {
"repomap": {
"command": "python",
"args": ["-m", "repomap_mcp"]
}
}
}설정 파일 위치 / config file location — macOS: ~/Library/Application Support/Claude/claude_desktop_config.json,
Windows: %APPDATA%\Claude\claude_desktop_config.json.
기타 클라이언트 / Other clients
Cursor 등 다른 MCP 클라이언트도 동일한 stdio 서버(repomap-mcp 또는
python -m repomap_mcp)로 등록하면 된다. / Register the same stdio server in other
MCP clients (Cursor, etc.) the same way.
사용 예시 / Usage
에이전트/클라이언트는 아래처럼 get_repo_map 을 호출한다. / An agent calls get_repo_map:
// 도구 인자 / tool arguments
{
"repo_path": "/path/to/your/repo",
"token_budget": 1500,
"role": "planner"
}반환값 실제 출력의 앞부분 발췌(이 레포 자체에 대해 token_budget=1500, role="planner" 로 실행 — 전체는 파일 12개·73라인, 아래는 앞 3개 파일만):
Excerpt of the actual output (run against this very repo with token_budget=1500, role="planner" — full output is 12 files / 73 lines; only the first 3 files are shown below):
src/repomap_mcp/cache.py:
class FileEntry:
class CacheState:
def normalize_repo_path(repo_path: str) -> str:
def cache_dir_for(repo_path: str) -> Path:
def current_query_hash() -> str:
def content_hash_of(abs_path: str) -> str:
def load_cache(repo_path: str) -> CacheState | None:
def save_cache(state: CacheState) -> None:
def clear_cache(repo_path: str) -> bool:
src/repomap_mcp/server.py:
def hello() -> str:
def build_repo_map(
def get_repo_map(
def refresh_cache(repo_path: str, full: bool = False) -> dict:
def main() -> None:
src/repomap_mcp/walker.py:
def supported_langs() -> set[str]:
def walk_repo(repo_path: str) -> list[FileEntry]:
...동반되는 stats / accompanying stats (콜드 빌드 / cold build):
{
"files": 15,
"files_parsed_now": 15,
"files_from_cache": 0,
"cache_hit_ratio": 0.0,
"moved": 0,
"deleted": 0,
"symbols_total": 50,
"symbols_included": 50,
"est_tokens": 545,
"elapsed_ms": 64.5
}같은 레포를 다시 호출하면 캐시가 히트해 재파싱이 사라진다(cache_hit_ratio: 1.0,
files_from_cache: 15). / A second call hits the cache, so nothing is re-parsed.
role 별 차이 / role differences — planner 는 진입점(다른 파일에서 많이 참조되는
파일)을 위로 끌어올리고, implementer 는 focus_files 로 지정한 파일과 그 이웃을,
reviewer 는 changed_files 와 그 의존자(변경 영향권)를 상위에 배치한다.
planner surfaces entry points; implementer boosts your focus_files and their
neighbors; reviewer boosts changed_files and their dependents.
도구 / Tools
도구 / tool | 반환 / returns | 설명 / description |
|
| 레포 맵을 빌드해 반환(증분 캐시 사용) / build & return the repo map (uses the incremental cache) |
|
| 캐시를 갱신, |
|
| 헬스체크 / health check |
get_repo_map 인자 / arguments:
인자 / arg | 기본값 / default | 설명 / description |
| (필수 / required) | 대상 레포 경로 / target repo path |
|
| 출력 토큰 예산 / output token budget |
|
|
|
|
| implementer 역할에서 텔레포트 질량을 집중할 파일 목록 / files to focus on (implementer) |
|
| reviewer 역할에서 변경 파일 + 의존자 가중 / changed files (+ dependents) to weight (reviewer) |
refresh_cache 인자 / arguments — repo_path(필수 / required), full(기본 False;
True 면 캐시 폐기 후 전체 재빌드 / discard cache then rebuild from scratch).
설정 / Configuration
항목 / item | 기본값 / default | 설명 / description |
| platformdirs | 캐시 루트 override / override the cache root |
|
| 클수록 더 많은 심볼 포함 / larger = more symbols included |
캐시 위치 / cache location — 기본값은 OS 표준 유저 캐시 디렉토리다. / defaults to the OS-standard per-user cache dir:
Linux:
~/.cache/repomap-mcp/cache/macOS:
~/Library/Caches/repomap-mcp/cache/Windows:
%LOCALAPPDATA%\repomap-mcp\Cache\cache\
레포별로 sha1(정규화 절대경로)[:12] 서브디렉토리에 manifest.json(메타 + 파일 엔트리)
과 tags.msgpack(파일별 tags)이 저장된다. 대상 레포도, 이 패키지 소스트리도 건드리지
않는다. / Each repo gets a sha1(normalized abspath)[:12] subdir holding
manifest.json + tags.msgpack; neither the target repo nor this source tree is touched.
지원 언어 / Supported languages
python, csharp, javascript, go, rust, java, c, cpp
python 은 로컬 tags 쿼리(queries/*.scm)를, 나머지는 tree-sitter-language-pack 이
번들한 쿼리를 사용한다. / Python uses local tags queries (queries/*.scm); the others
use queries bundled by tree-sitter-language-pack.
한계 / Limitations
이름 기반 근사 그래프 — 의존 그래프는 심볼 이름 매칭으로 근사한다. 정확한 정의·참조 추적(스코프·타입 해석)은 하지 않으므로, 정밀 추적이 필요하면 LSP 기반 도구를 써야 한다. / the dependency graph is approximated by symbol name matching, not precise definition/reference resolution — use a dedicated LSP-based tool for precise tracking.
graph/rank/compose 는 비캐시 — 캐시는 파싱 만 줄인다. 그래프 구성·PageRank·조립은 매 호출 전체를 다시 수행한다. / the cache only avoids re-parsing; graph/rank/compose run in full each call.
.gitignore처리 제한 — 중첩.gitignore와 negation(!pattern) 규칙은 처리하지 않는다. / nested per-directory.gitignoreand negation (!pattern) rules are not handled.
개발 / Development
git clone https://github.com/worktpwls/repomap-mcp.git
cd repomap-mcp
pip install -e .
# 단계별 동작 검증 스크립트 / phase-by-phase verification scripts
python verify_phase1.py # 콜드 빌드 · stats · repo_map 샘플 출력
python verify_phase2.py # 증분 캐시(변경분만 재파싱) 검증
python verify_phase3.py # 역할별 personalization 검증
python verify_phase4.py # 언어 확장 검증각 verify_phase*.py 는 대상 레포에 대해 해당 단계 동작을 실행·검증하는 스크립트다.
대상 레포는 CLI 인자 또는 환경변수 REPOMAP_TEST_REPO 로 지정한다.
Each verify_phase*.py runs and checks that phase's behavior against a target repo,
selected via a CLI arg or the REPOMAP_TEST_REPO env var.
License
MIT — see LICENSE.
작성자 / author: worktpwls · 저장소 / repo: https://github.com/worktpwls/repomap-mcp
Available Tools
3 toolsget_repo_mapA
레포의 압축 맵을 반환 / return a compressed map of the repo.
repo_path: 대상 레포 절대경로 / absolute path to the target repo. token_budget: 출력 토큰 예산(기본 4000) / output token budget (default 4000). focus_files / role / changed_files: Phase 3 역할별 personalization 입력 / Phase 3 inputs for role-based personalization. role="planner": 진입점 가중 / entry-point boost. role="implementer": focus_files 에 텔레포트 질량 집중 / teleport mass on focus_files. role="reviewer": changed_files + 의존자(predecessors) 가중 / changed_files + their dependents (predecessors).
반환 / returns: {repo_map, stats:{files, files_parsed_now, files_from_cache, cache_hit_ratio, moved, deleted, symbols_total, symbols_included, est_tokens, elapsed_ms}, warnings}
Inputs: repo_path (required), role, focus_files, token_budget, +1 more.
helloA
헬스체크용 인사 반환 / return a greeting for a health check.
Inputs: no named parameters. Returns: result
refresh_cacheA
캐시를 갱신 / refresh the cache.
full=False(기본): 증분 스캔 — 변경분만 재파싱 후 캐시 저장. full=False (default): incremental scan — re-parse only changes, then persist. full=True: 캐시 폐기 후 전체 재빌드(복구용). full=True: discard cache then rebuild from scratch (recovery).
반환 / returns: {reparsed, invalidated, elapsed_ms} reparsed: 이번에 재파싱된 파일 수 / files re-parsed this run. invalidated: 무효화(삭제)된 캐시 엔트리 수 / cache entries invalidated/removed.
Inputs: repo_path (required), full.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a distinct purpose: get_repo_map returns a repo map, hello is a health check, refresh_cache manages caching. No overlap.
Two tools follow verb_noun pattern (get_repo_map, refresh_cache), but 'hello' is a single word without underscore. Minor inconsistency, but still clear.
3 tools is well-scoped for a focused repo mapping utility. Each tool serves a necessary function without bloat.
Covers core functionality (map retrieval, health check, cache management). Minor gap: no explicit status tool for cache, but refresh_cache covers maintenance.
Maintenance
Related MCP Connectors
Code-map tools for AI agents: see a repo's structure first, then edit only what matters.
Give your AI agent a persistent map of your project's structure, dependencies, and bugs.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Codebase intelligence for AI agents — dead code, blast radius, ownership.
Related MCP Servers
- AlicenseAqualityCmaintenanceProvides AI coding agents with durable architecture memory for repositories by generating structured project maps of responsibilities, relationships, and risks.615 npmMIT
- AlicenseNot gradedqualityDmaintenanceGenerates optimized repository maps and enables identifier search with graph-ranking, designed for efficient LLM context caching and codebase navigation.1MIT
- AlicenseNot gradedqualityCmaintenanceDeterministic, local-first repository context for coding agents. Maps an issue, prompt, or git diff to ranked files to read first, likely test commands, and review-risk notes—no API key required.21MIT
- AlicenseAqualityBmaintenanceEnables coding agents to get a compact, token-budgeted map of any repository in one call, including file tree, language stats, entry points, and key symbols, so they read only what they need.41MIT