Content
# Aider RepoMapper MCP Server
A standalone Model Context Protocol (MCP) server wrapping Aider's graph-ranking repository mapping engine. This server is explicitly hardened for high-efficiency LLM development workflows by optimizing text payloads for strict **byte-for-byte Prompt Caching** (e.g., Anthropic Prompt Caching via OpenRouter).
## Key Features
- **Cache-Locked Architecture Summarization:** Intercepts volatile file parsing outputs and swaps mutating line numbers for static pipe (`|`) tokens.
- **Rank Score Stripping:** Removes fluctuating PageRank floating-point scores (`(Rank value: X.XXXX)`) generated dynamically in memory, preventing prefix cache invalidation loops across code changes.
- **Path Blacklisting Heuristics:** Automatically intercepts and filters untracked runtime assets, database dumps, localized state subtrees (`data/`), and compiled frontend asset bundles (`*.min.js`) from corrupting the tool context window.
- **JSON-RPC Schema Compliant:** Plugs natively into agent frameworks like ZooCode, RooCode, and Cursor-agent extension environments out of the box.
## Server Layout & Core Modules
The repository structures the port across these primary utilities:
- `repomap_server.py`: Async JSON-RPC server harness exposing tool schemas and managing filesystem parameter inputs.
- `repomap_class.py` & `repomap.py`: Local interface adapters wrapping the core Abstract Syntax Tree (AST) tree-sitter parser hooks.
- `importance.py` & `scm.py`: Heuristic logic for assessing file contribution ranks and structural tracking states.
- `utils.py`: Local counting frameworks and atomic file reader fallbacks.
- `test_matrix.py`: Regression framework validating formatting state guarantees.
## Installation & Environment Configuration
Ensure the engine is running within a Python 3.10+ environment containing the core dependency stack (`mcp`, `tiktoken`, `aider-chat`).
### Agent Settings Integration
Add the server entry point configuration to your global or project-level MCP definition matrix (e.g., `.vscode/mcp.json` or `.roo/mcp.json`):
```json
{
"mcpServers": {
"repo-mapper": {
"command": "/home/barry/tools/RepoMapper/.venv/bin/python",
"args": ["/home/barry/tools/RepoMapper/repomap_server.py"],
"env": {
"PYTHONUNBUFFERED": "1"
}
}
}
}
```
## Exposed MCP Tools
### `repo_map`
Generates an optimized, topologically sorted layout matching the internal repository architecture.
**Parameters:**
- `project_root` *(string, required)*: The absolute path to the targeted repository root.
- `token_limit` *(integer, optional)*: Maximum scale window for the map text block (defaults to 2000).
- `exclude_unranked` *(boolean, optional)*: Drops low-signal definitions when processing constrained tokens.
- `verbose` *(boolean, optional)*: Promotes deeper diagnostic stdout updates to log levels.
### `search_identifiers`
Performs keyword-based target cross-referencing against structural symbol matrices.
