# repomap-mcp

역할 인식 레포지토리 맵을 제공하는 MCP 서버.
A role-aware repository map MCP server for LLM agents.

[![PyPI](https://img.shields.io/pypi/v/repomap-mcp)](https://pypi.org/project/repomap-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)

---

## 소개 / 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

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

### 소스에서 / From source

```bash
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

```bash
# 콘솔 스크립트로 등록 / 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`.

```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:

```json
{
  "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`:

```jsonc
// 도구 인자 / 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):

```text
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):

```json
{
  "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

```bash
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](LICENSE).

작성자 / author: [worktpwls](https://github.com/worktpwls) ·
저장소 / repo: https://github.com/worktpwls/repomap-mcp