repo-map-mcp

MCP server that maintains a self-updating, per-file JSON index of a repo (directory, filename, description, function names, timestamps) so an agent can query "what's probably relevant" instead of grepping/reading the whole tree.

File exploration and path annotation computed locally; Description and file purpose are dictated by the agent, which provides them even better context.

Install

uv sync

Tools

• index_repository(root_path, force=False) — walk root_path (respecting .gitignore + hardcoded excludes), hash each file, re-parse function names for changed files, update the on-disk index at <root_path>/.repo-index/index.json. Returns a summary string.
• get_repo_map(root_path, dir_prefix=None) — return the JSON index, optionally scoped to a subdirectory.
• search_files(root_path, query) — substring match against filename, description, and function names.
• get_stale_files(root_path) — files whose descriptionStale flag is set, with their function names, so the calling agent can write a description without opening the file.
• set_description(root_path, path, description) — writes the description back and clears the stale flag.

Supported languages for function extraction (via tree-sitter): Python, JavaScript, TypeScript, TSX, Java, Rust. Other file types still get indexed, with funcs: [].

Requirements:

• Python
• uv

Run

uv run repo-map-mcp

Runs on stdio — add it to an MCP client config (e.g. Claude Code) pointing command at uv run repo-map-mcp (cwd set to this directory, or use an absolute path).

Test

uv run pytest -q
uv run python3 scripts/smoke_client.py   # end-to-end tool call smoke test