Repo Interrogator

Repo Interrogator is a local-first, deterministic MCP server that helps AI tools inspect one code repository safely.

It is for repository interrogation, not code modification.

What it does:

• indexes files inside one repo_root
• runs deterministic BM25 search
• outlines code structure via pluggable language adapters
• builds context bundles with citations
• writes sanitized audit logs

What it does not do:

• no LLM calls in v1
• no code writes or patching
• no multi-repo routing
• no HTTP/SSE transport in v1

Supported Environments

• Python: >=3.11
• Tested in this project: Linux and WSL paths, with explicit Windows path normalization tests
• Expected to run on: Linux, macOS, Windows (with Python 3.11+)

Quick Start

1. Clone this repository and enter it:

git clone https://github.com/taggedzi/Repo-Interrogator
cd repomap

2. Install (end-user style):

python -m pip install .

This installs the console command repo-mcp.

3. Run against a local repository:

repo-mcp --repo-root /absolute/path/to/target/repo

The server uses STDIO. It waits for newline-delimited JSON requests and writes newline-delimited JSON responses.

4. Verify it responds:

printf '%s\n' \
  '{"id":1,"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}' \
  '{"id":2,"jsonrpc":"2.0","method":"tools/call","params":{"name":"repo.status","arguments":{}}}' \
  | repo-mcp --repo-root /absolute/path/to/target/repo

You should get two JSON-RPC 2.0 response lines (the notification produces no output):

• Line 1: initialize result — {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05",...}}
• Line 2: tool result — {"jsonrpc":"2.0","id":2,"result":{"content":[{"type":"text","text":"{\"index_status\":...}"}]}}

Developer Quick Start

python -m venv .venv
source .venv/bin/activate
python -m pip install -e .
python -m pip install ruff mypy pytest build

Run checks:

python -m ruff format .
python -m ruff check .
python -m mypy src
python -m pytest -q

Tool Surface (Current)

• repo.status
• repo.list_files
• repo.open_file
• repo.outline
• repo.search
• repo.references
• repo.find_definition
• repo.build_context_bundle
• repo.refresh_index
• repo.audit_log

Optional Semantic Search

Install the semantic extra (pip install repo-interrogator[semantic]) to enable mode="semantic"/"hybrid" on repo.search and retrieval_mode on repo.build_context_bundle. The core package has zero runtime dependencies and is unaffected when this extra isn't installed. See ADR-0018 and docs/USAGE.md for details.

Language Adapter Support

repo.outline currently supports these adapters:

• Python: python (AST-based)
• TypeScript/JavaScript: ts_js_lexical (lexical)
• Java: java_lexical (lexical)
• Go: go_lexical (lexical)
• Rust: rust_lexical (lexical)
• C++: cpp_lexical (lexical)
• C#: csharp_lexical (lexical)
• Fallback: lexical (empty structural outline for unsupported files)

Important limits:

• Non-Python adapters are lexical. They are deterministic and fast, but conservative.
• Macro/generated code and advanced language features can be partially represented.
• Search, references, and context bundle coverage depend on indexed extensions/excludes.
• Start from examples/repo_mcp.toml for stack-aware include/exclude defaults and override guidance.

Documentation

• Installation: docs/INSTALL.md
• Usage and request/response examples: docs/USAGE.md
• Configuration and limits: docs/CONFIG.md
• AI client integration (MCP over STDIO): docs/AI_INTEGRATION.md
• Troubleshooting: docs/TROUBLESHOOTING.md
• Issue labels and triage workflow: docs/TRIAGE.md
• Security policy and vulnerability reporting: SECURITY.md
• Security model and blocked behavior: docs/SECURITY.md
• Release process: docs/release.md

Docs Verification Checklist

Run these commands to validate docs examples against the current codebase:

python -m ruff format .
python -m ruff check .
python -m mypy src
python -m pytest -q

# quick server smoke
printf '%s\n' \
  '{"id":1,"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0"}}}' \
  '{"id":2,"jsonrpc":"2.0","method":"tools/call","params":{"name":"repo.status","arguments":{}}}' \
  | python -m repo_mcp.server --repo-root .