# 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

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

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

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