Metadata-Version: 2.4
Name: repomap-mcp
Version: 0.1.0
Summary: Role-aware repository map MCP server — tree-sitter parsing + PageRank ranking + incremental cache
Author: worktpwls
License: MIT License
        
        Copyright (c) 2026 worktpwls
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/worktpwls/repomap-mcp
Project-URL: Repository, https://github.com/worktpwls/repomap-mcp
Keywords: mcp,repo-map,tree-sitter,pagerank,code-intelligence,llm
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp
Requires-Dist: tree-sitter-language-pack<2,>=1.12
Requires-Dist: networkx>=3
Requires-Dist: msgpack
Requires-Dist: pathspec
Requires-Dist: platformdirs
Dynamic: license-file

# repomap-mcp

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

[![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)
<!-- 공개 후 활성화 / enable after PyPI release: ![PyPI](https://img.shields.io/pypi/v/repomap-mcp) -->

---

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

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

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