repomap-mcp 0.1.0

Role-aware repository map MCP server — tree-sitter parsing + PageRank ranking + incremental cache

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.

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)

1. walk — .gitignore(pathspec) 를 존중하며 파일을 탐색한다. / walk files, honoring .gitignore.
2. parse — tree-sitter 로 각 파일의 tags(정의·참조 심볼)를 추출한다. / extract tags (defined/referenced symbols) per file.
3. graph — 심볼 이름 기반으로 파일 간 의존 그래프를 만든다. / build a file-to-file dependency graph from symbol names.
4. PageRank — 파일 중요도를 매긴다(순수 파이썬 구현). / rank file importance (pure-Python).
5. 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 (공개 후 / after release)

pip install repomap-mcp
# 또는 / or
uvx repomap-mcp        # 격리 실행 / isolated run
pipx install repomap-mcp

PyPI 배포 전까지는 아래 "소스에서" 방식을 쓴다. / Until published to PyPI, use "From source" below.

소스에서 / 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_mcp

repomap-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
get_repo_map	{repo_map, stats, warnings}	레포 맵을 빌드해 반환(증분 캐시 사용) / build & return the repo map (uses the incremental cache)
refresh_cache	{reparsed, invalidated, elapsed_ms}	캐시를 갱신, full=True 면 전체 재빌드 / refresh the cache; full=True forces a full rebuild
hello	str	헬스체크 / health check

get_repo_map 인자 / arguments:

인자 / arg	기본값 / default	설명 / description
repo_path	(필수 / required)	대상 레포 경로 / target repo path
token_budget	4000	출력 토큰 예산 / output token budget
role	"planner"	planner(진입점 가중) / implementer(focus_files 집중) / reviewer(changed_files + 의존자)
focus_files	None	implementer 역할에서 텔레포트 질량을 집중할 파일 목록 / files to focus on (implementer)
changed_files	None	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
REPOMAP_CACHE_DIR (env)	platformdirs user_cache_dir("repomap-mcp")/cache	캐시 루트 override / override the cache root
token_budget (arg)	4000	클수록 더 많은 심볼 포함 / 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 .gitignore and 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