Skip to main content
Glama
worktpwls

repomap-mcp

by worktpwls

repomap-mcp

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

PyPI License: MIT Python 3.10+


소개 / 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: omni-rag-mcp

Features

  • 역할별 맵 / role-aware mapsplanner(진입점 가중) · 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.

  • 역할별 personalizationrole/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_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.jsonmcpServers 에 다음 블록을 추가한다. 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 differencesplanner 는 진입점(다른 파일에서 많이 참조되는 파일)을 위로 끌어올리고, implementerfocus_files 로 지정한 파일과 그 이웃을, reviewerchanged_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

Available Tools

3 tools
get_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}

ParametersJSON Schema
NameRequiredDescriptionDefault
roleNoplanner
repo_pathYes
focus_filesNo
token_budgetNo
changed_filesNo

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses the return structure with stats and warnings, caching behavior, role-specific behavior, and indicates it is read-only (compressed map). Could mention non-destructiveness more explicitly.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is structured with bullet points and front-loads the main purpose. However, it mixes Korean and English and is somewhat verbose; could be more succinct while retaining clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, but the description adequately specifies the return structure (repo_map, stats with fields, warnings) and covers caching and role-specific behavior. Given the complexity (5 params, role logic), it is complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 0% description coverage, so description compensates fully. Every parameter (repo_path, token_budget, focus_files, role, changed_files) is explained with detailed role-based behavior, adding meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'retourne une carte compressée du dépôt' with specific verb and resource, and explains the role-based behavior. It differentiates from sibling tools `hello` and `refresh_cache` which are unrelated, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for getting a repo map but does not explicitly state when to use this tool versus alternatives. It lacks guidance on when not to use it, e.g., for simple file retrieval.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

helloA

헬스체크용 인사 반환 / return a greeting for a health check.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.1/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It states the tool returns a greeting, implying read-only non-destructive behavior, but does not explicitly confirm safety or disclose any side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise—a single short sentence in two languages. Every word is meaningful with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters, an output schema exists, and the low complexity of a health check endpoint, the description fully covers what the agent needs to know.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so schema coverage is 100%. The description adds no parameter info because none are needed. Baseline 4 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns a greeting for health check, with both Korean and English. It unambiguously identifies the tool's purpose and distinguishes it from siblings like get_repo_map and refresh_cache.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool vs alternatives, but given its trivial health check nature, it's inherently a test endpoint. Siblings serve different purposes, reducing confusion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
fullNo
repo_pathYes

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, but the description discloses behavioral traits: incremental mode only re-parses changes, full mode discards and rebuilds cache. It also describes the return values. However, it does not mention potential side effects beyond cache modification.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is succinct and well-structured: a one-line summary followed by explanations of each mode and the return format. The bilingual text adds redundancy but remains clear and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity, lack of output schema, and no annotations, the description covers the purpose, behavior, and return values adequately. It lacks examples or error conditions but is reasonably complete for its complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 2 parameters with 0% description coverage. The description adds meaning for the 'full' parameter (explaining its default and the two modes), but does not explain 'repo_path' beyond its name. This partially compensates for the schema gap but not fully.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool refreshes the cache, with two distinct modes: incremental (default) and full rebuild (recovery). It specifies the operation on a cache resource and, given the context of sibling tools (get_repo_map, hello), it is clearly differentiated from them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explains when to use full=True (recovery) and full=False (default, incremental). It provides clear guidance on the two modes, though it does not explicitly state prerequisites or when not to use the tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

TDQS

A4.3/5.0
Disambiguation5/5

Each tool has a distinct purpose: get_repo_map returns a repo map, hello is a health check, refresh_cache manages caching. No overlap.

Naming Consistency4/5

Two tools follow verb_noun pattern (get_repo_map, refresh_cache), but 'hello' is a single word without underscore. Minor inconsistency, but still clear.

Tool Count5/5

3 tools is well-scoped for a focused repo mapping utility. Each tool serves a necessary function without bloat.

Completeness4/5

Covers core functionality (map retrieval, health check, cache management). Minor gap: no explicit status tool for cache, but refresh_cache covers maintenance.

Maintenance

ActivityStale
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    B
    quality
    C
    maintenance
    Enables token-efficient semantic search and analysis over any directory of files through hybrid search, directory overview, structural analysis, and dependency graphs.
    14
    MIT
  • A
    license
    Not graded
    quality
    B
    maintenance
    Provides token-efficient code retrieval for coding agents by indexing repositories and enabling ranked snippet search, symbol outlines, and surgical line reads.
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/worktpwls/repomap-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server