Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Repo Interrogator search for 'BM25' in the codebase"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
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+)
Related MCP server: mcplens
Clone this repository and enter it:
git clone https://github.com/taggedzi/Repo-Interrogator
cd repomapInstall (end-user style):
python -m pip install .This installs the console command repo-mcp.
Run against a local repository:
repo-mcp --repo-root /absolute/path/to/target/repoThe server uses STDIO. It waits for newline-delimited JSON requests and writes newline-delimited JSON responses.
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/repoYou 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\":...}"}]}}
python -m venv .venv
source .venv/bin/activate
python -m pip install -e .
python -m pip install ruff mypy pytest buildRun checks:
python -m ruff format .
python -m ruff check .
python -m mypy src
python -m pytest -qrepo.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
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.
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.
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
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 .Read sanitized audit log entries for all tool calls made in this session. Useful for diagnostics and verifying what was called and whether it succeeded.
Inputs: limit, since.
Build a compact, ranked, cited context bundle for a coding task. Combines search, outline, and cross-file references into a budget-bounded excerpt set. Each selection includes why_selected explaining which signals drove it. Requires the index to be built first (repo.refresh_index).
Inputs: budget (required), prompt (required), strategy, include_tests.
List readable source files under the repository root. Supports glob filtering. Use to discover what files exist before searching or opening.
Inputs: glob, max_results, include_hidden.
Read a line range from a source file. Returns numbered lines. Specify start_line and end_line to read a focused range rather than the entire file.
Inputs: path (required), end_line, start_line.
Return the declaration structure of a file using AST (Python) or lexical analysis. Shows classes, functions, and other symbols with line ranges and parent context.
Inputs: path (required).
Find all cross-file references to a named symbol using AST (Python) or lexical analysis. Returns file paths, line numbers, strategy, and confidence level per reference.
Inputs: symbol (required), path, top_k.
Build or incrementally refresh the BM25 search index. Run this before searching or bundling if the index is stale or not yet built. Use force=true to rebuild from scratch.
Inputs: force.
Run BM25 full-text search over indexed repository chunks. Returns ranked hits with file path, line range, snippet, and matched terms. Run repo.refresh_index first if the index is not yet built.
Inputs: query (required), mode, top_k, file_glob, +1 more.
Return index state, active limits, enabled adapters, and effective config. Call this first to verify the server is connected and the index is ready.
Inputs: no named parameters.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 9 tools
Each tool has a clearly distinct purpose: from indexing and search to file operations, references, outline, and audit. No overlap exists between tools.
All tools follow the 'repo.verb_noun' pattern using snake_case, providing a predictable and consistent naming scheme throughout.
With 9 tools, the set is well-scoped for repository interrogation. Each tool serves a specific function without redundancy or excess.
The tool surface covers the full workflow: indexing, searching, listing, opening, outlining, referencing, and building context bundles. No obvious gaps for the stated purpose.
An MCP server that gives your AI access to the source code and docs of all public github repos
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
Capability registry for the agentic economy. Semantic search over verified MCP server listings.
