# MCP Server
indxr includes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that gives AI agents access to the codebase knowledge wiki and structural index. Agents can query the wiki for architecture decisions and module context, search for symbols and files, read specific functions, and write knowledge back — all over JSON-RPC.
Two transports are available:
- **stdio** (default) — JSON-RPC 2.0 over stdin/stdout, for single-client use
- **Streamable HTTP** — HTTP server with SSE support, for multi-client scenarios (requires `--features http`)
## Starting the Server
### stdio transport (default)
```bash
indxr serve ./my-project
```
### Streamable HTTP transport
```bash
# Build with HTTP support
cargo install indxr --features http
# Start on a specific address
indxr serve --http 127.0.0.1:8080 # recommended: localhost only
indxr serve --http :8080 # shorthand for 127.0.0.1:8080 (localhost)
indxr serve --http :8080 --watch # with auto-reindex on file changes
```
> **Security note:** The HTTP transport is intended for **local or trusted-network use only**. It does not provide TLS (connections are plaintext), CORS headers, or authentication beyond session IDs. The `:PORT` shorthand binds to `127.0.0.1` (localhost only). To expose on all interfaces, use `0.0.0.0:PORT` explicitly. Do not expose the server to the public internet.
The HTTP transport implements the MCP Streamable HTTP specification (2025-03-26) with a single `/mcp` endpoint:
- **POST /mcp** — send JSON-RPC requests, receive JSON responses
- **GET /mcp** — open an SSE stream for server-initiated notifications (file change events)
- **DELETE /mcp** — terminate a session
Sessions are enforced: the first request must be `initialize`, which returns an `Mcp-Session-Id` header. All subsequent requests must include this header. Sessions use a **sliding-window TTL** (1 hour of inactivity) — each valid POST request refreshes the timer, so active sessions do not expire. Up to 1000 concurrent sessions are supported; expired sessions are evicted lazily.
> **Note:** The GET SSE stream does not refresh the session TTL. Clients that open an SSE stream must continue sending periodic POST requests (e.g., `ping` or tool calls) to keep the session alive. If no POST is made within the TTL window, the session expires and the SSE stream is closed.
### Server Options
```
indxr serve [PATH] [OPTIONS]
Arguments:
[PATH] Root directory to index [default: .]
Options:
--cache-dir <DIR> Cache directory [default: .indxr-cache]
--max-file-size <KB> Skip files larger than N KB [default: 512]
--max-depth <N> Maximum directory depth
-e, --exclude <PATTERNS> Glob patterns to exclude
--no-gitignore Don't respect .gitignore
--member <NAMES> Specific workspace member(s) to index (comma-separated)
--no-workspace Disable workspace detection (treat root as single project)
--watch Watch for file changes and auto-reindex
--debounce-ms <MS> Debounce timeout in milliseconds [default: 300]
--http <ADDR> Start Streamable HTTP server (requires 'http' feature)
--all-tools Expose all 26 tools (default: 3 compound tools)
Wiki options (requires --features wiki):
--wiki-auto-update Auto-update wiki on file changes (requires --watch)
--wiki-debounce-ms <MS> Wiki update debounce in milliseconds [default: 30000]
--wiki-model <MODEL> LLM model override for wiki auto-updates
--wiki-exec <CMD> External LLM command for wiki auto-updates
```
### Auto-Reindexing with `--watch`
When `--watch` is enabled, the MCP server monitors the project directory for source file changes and automatically rebuilds the in-memory index and INDEX.md:
```bash
indxr serve ./my-project --watch
```
This means agents always query up-to-date data without needing to call `regenerate_index` manually. Changes are debounced (default 300ms) to avoid redundant reindexing during rapid saves. Non-source files, hidden directories, cache directories, and the INDEX.md output file are filtered out.
For a standalone watcher that only keeps INDEX.md updated (without running the MCP server), use `indxr watch`.
## Protocol
The MCP server implements JSON-RPC 2.0 over stdin/stdout, following the MCP specification version `2024-11-05`.
### Lifecycle
1. Client sends `initialize` request
2. Server responds with capabilities (tools list)
3. Client sends `initialized` notification
4. Client calls tools via `tools/call` requests
5. Client sends SIGTERM or closes stdin to shut down
## Available Tools
By default, the MCP server lists **3 compound tools** (`find`, `summarize`, `read`) to minimize per-request token overhead. Pass `--all-tools` to the `serve` command to list all 26 tools (3 compound + 23 granular). Granular tools are always **callable** regardless of this flag — `--all-tools` only controls whether they appear in the `tools/list` response.
> **Workspace support:** In monorepo/workspace projects (Cargo, npm, Go), most tools automatically gain an optional `member` parameter (string) to scope the query to a specific workspace member by name. In single-project mode, the `member` parameter is not included to save tokens. If omitted, all members are searched.
**Default compound tools (3):** `find`, `summarize`, `read`
- `find(query, mode?)` — modes: `relevant` (default), `symbol`, `callers`, `signature`. Replaces: `search_relevant`, `lookup_symbol`, `get_callers`, `search_signatures`, `explain_symbol`
- `summarize(path, scope?)` — scope: `all` (default), `public`. Auto-detects: glob -> batch, no "/" -> symbol name, file path -> file summary. Replaces: `get_file_summary`, `get_public_api`, `list_declarations`, `batch_file_summaries`, `get_file_context`, `explain_symbol`
- `read(path, symbol?, symbols?, start_line?, end_line?)` — same as `read_source`. Replaces: `read_source`
**Granular tools (23 — requires `--all-tools`):** `search_relevant`, `lookup_symbol`, `explain_symbol`, `get_file_summary`, `batch_file_summaries`, `get_file_context`, `get_public_api`, `get_callers`, `list_declarations`, `search_signatures`, `read_source`, `get_tree`, `get_stats`, `get_imports`, `get_related_tests`, `get_hotspots`, `get_health`, `get_type_flow`, `get_dependency_graph`, `get_diff_summary`, `get_token_estimate`, `list_workspace_members`, `regenerate_index`
---
### `list_workspace_members`
> *Extended tool — only listed with `--all-tools`, but always callable.*
List workspace members (monorepo packages/crates). Returns member names, paths, and workspace type. In single-project mode, returns one member.
**Parameters:** None.
**Example request:**
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "list_workspace_members",
"arguments": {}
}
}
```
**Example response:**
```json
{
"content": [{
"type": "text",
"text": "{\"workspace_type\":\"cargo\",\"members\":[{\"name\":\"core\",\"path\":\"packages/core\"},{\"name\":\"cli\",\"path\":\"packages/cli\"}]}"
}]
}
```
### `lookup_symbol`
Find declarations matching a name across the entire codebase. Uses case-insensitive substring matching.
**Parameters:**
| `name` | string | yes | Symbol name to search for |
| `limit` | number | no | Max results (default: 50, max: 200) |
| `compact` | boolean | no | Return columnar format (saves ~30% tokens) |
**Example request:**
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "lookup_symbol",
"arguments": { "name": "Cache", "limit": 10 }
}
}
```
**Example response:**
```json
{
"content": [{
"type": "text",
"text": "Found 3 matches:\n\nsrc/cache/mod.rs:\n struct Cache (line 15)\n pub fn Cache::load(...) -> Result<Self> (line 25)\n pub fn Cache::save(&self) -> Result<()> (line 45)"
}]
}
```
### `list_declarations`
List all declarations in a specific file.
**Parameters:**
| `path` | string | yes | Relative file path |
| `kind` | string | no | Filter by kind (function, struct, class, etc.) |
| `shallow` | boolean | no | Omit children and doc comments to reduce output |
| `compact` | boolean | no | Columnar format (implies shallow, saves ~30% tokens) |
**Example:**
```json
{
"params": {
"name": "list_declarations",
"arguments": { "path": "src/main.rs", "kind": "function" }
}
}
```
### `search_signatures`
Search function/method signatures by substring.
**Parameters:**
| `query` | string | yes | Substring to search for in signatures |
| `limit` | number | no | Max results (default: 20, max: 100) |
| `compact` | boolean | no | Return columnar format (saves ~30% tokens) |
**Example:**
```json
{
"params": {
"name": "search_signatures",
"arguments": { "query": "-> Result<" }
}
}
```
### `get_tree`
Get the directory and file tree of the indexed codebase.
**Parameters:**
| `path` | string | no | Filter to a subtree by path prefix |
**Example:**
```json
{
"params": {
"name": "get_tree",
"arguments": { "path": "src/parser" }
}
}
```
### `get_imports`
> *Extended tool — only listed with `--all-tools`, but always callable.*
Get all import statements for a specific file.
**Parameters:**
| `path` | string | yes | Relative file path |
### `get_stats`
> *Extended tool — only listed with `--all-tools`, but always callable.*
Get index statistics. No parameters required.
**Returns:** File count, line count, language breakdown, indexing duration, and generation timestamp.
### `get_file_summary`
Get a complete overview of a file in one call: metadata, imports, declarations (shallow), kind counts, public symbol count, and test presence.
**Parameters:**
| `path` | string | yes | Relative file path |
### `read_source`
Read source code from a file, either by symbol name (uses indexed line info) or by explicit line range. Cap: 200 lines per symbol, 500 lines total for multi-symbol reads.
**Parameters:**
| `path` | string | yes | Relative file path |
| `symbol` | string | no | Symbol name to look up and extract |
| `symbols` | string[] | no | Multiple symbol names to read in one call (alternative to `symbol`) |
| `start_line` | number | no | Start line (1-based) for explicit range |
| `end_line` | number | no | End line (1-based, inclusive) for explicit range |
| `expand` | number | no | Extra context lines above/below (default: 0) |
| `collapse` | boolean | no | If true, collapse nested block bodies to `{ ... }` — shows structure without inner implementation |
### `get_file_context`
Get a file's summary plus its dependency context: which files import it (reverse dependencies) and related files (tests, siblings in the same directory).
**Parameters:**
| `path` | string | yes | Relative file path |
### `get_token_estimate`
> *Extended tool — only listed with `--all-tools`, but always callable.*
Estimate how many tokens a file or symbol would consume if read in full. Helps agents decide whether to use `read_source` (targeted, cheap) or `Read` (full file, expensive). Supports bulk estimation via `directory` or `glob`.
**Parameters:**
| `path` | string | no | Relative file path |
| `symbol` | string | no | Symbol name — if provided, estimates tokens for just that symbol's source |
| `directory` | string | no | Directory path — estimates all files within (alternative to `path`) |
| `glob` | string | no | Glob pattern — estimates all matching files (alternative to `path`) |
**Example (file-level):**
```json
{
"params": {
"name": "get_token_estimate",
"arguments": { "path": "src/mcp/tools.rs" }
}
}
```
**Example response:**
```json
{
"content": [{
"type": "text",
"text": "{\"file\":\"src/mcp/tools.rs\",\"full_file_tokens\":8500,\"full_file_lines\":1400,\"summary_tokens\":300,\"declaration_count\":42,\"recommendation\":\"Use get_file_summary (~300 tokens) instead of Read (~8500 tokens). Use read_source for specific symbols.\"}"
}]
}
```
**Example (symbol-level):**
```json
{
"params": {
"name": "get_token_estimate",
"arguments": { "path": "src/mcp.rs", "symbol": "tool_search_relevant" }
}
}
```
**Example response:**
```json
{
"content": [{
"type": "text",
"text": "{\"file\":\"src/mcp/tools.rs\",\"symbol\":\"tool_search_relevant\",\"symbol_tokens\":250,\"symbol_lines\":45,\"full_file_tokens\":8500,\"full_file_lines\":1400,\"savings\":\"read_source saves ~8250 tokens (97% reduction)\"}"
}]
}
```
### `search_relevant`
Multi-signal relevance search across file paths, symbol names, signatures, and doc comments. Returns ranked results scored by weighted matching (3x name, 2x signature, 1x doc comment, public symbol boost). Use as a starting point to find where to look without reading any files.
**Parameters:**
| `query` | string | yes | Search query — a concept (e.g. `authentication`), partial name (e.g. `parse`), or type pattern (e.g. `Result<Cache>`) |
| `limit` | number | no | Max results (default: 20, max: 50) |
| `kind` | string | no | Filter by declaration kind (e.g. `fn`, `struct`, `class`, `trait`) |
| `compact` | boolean | no | Return columnar format (saves ~30% tokens) |
**Example:**
```json
{
"params": {
"name": "search_relevant",
"arguments": { "query": "token budget", "limit": 10 }
}
}
```
**Example response:**
```json
{
"content": [{
"type": "text",
"text": "Found 5 relevant matches:\n\nsrc/budget.rs (path, score: 4)\n pub fn apply_token_budget(...) -> CodebaseIndex (name+signature, score: 12)\n pub fn estimate_tokens(text: &str) -> usize (name, score: 9)\n\nsrc/mcp.rs:\n fn tool_get_token_estimate(...) -> Value (name, score: 6)"
}]
}
```
### `regenerate_index`
> *Extended tool — only listed with `--all-tools`, but always callable.*
Re-scan the codebase, rebuild the index, and write an updated INDEX.md to the project root. Also refreshes the in-memory index used by all other tools. No parameters required.
**Example request:**
```json
{
"jsonrpc": "2.0",
"id": 4,
"method": "tools/call",
"params": {
"name": "regenerate_index",
"arguments": {}
}
}
```
**Example response:**
```json
{
"content": [{
"type": "text",
"text": "{\"status\":\"ok\",\"message\":\"INDEX.md regenerated (44 files, 16132 lines)\",\"path\":\"/path/to/project/INDEX.md\",\"files_indexed\":44,\"total_lines\":16132}"
}]
}
```
### `explain_symbol`
Get everything needed to USE a symbol without reading its body: signature, doc comment, relationships (children, parent), and metadata. Ideal for understanding an API without the implementation cost.
**Parameters:**
| `name` | string | yes | Symbol name (exact match, case-insensitive) |
**Example:**
```json
{
"params": {
"name": "explain_symbol",
"arguments": { "name": "apply_token_budget" }
}
}
```
### `batch_file_summaries`
Get summaries for multiple files in one call. Provide an array of paths or a glob pattern. Cap: 30 files.
**Parameters:**
| `paths` | string[] | no | Array of file paths (relative to project root) |
| `glob` | string | no | Glob pattern to match files (e.g. `*.rs`, `src/parser/*`) |
**Example:**
```json
{
"params": {
"name": "batch_file_summaries",
"arguments": { "glob": "src/mcp/*.rs" }
}
}
```
### `get_public_api`
Get only public declarations with signatures for a file, directory, or the entire codebase. Minimal output for "how do I use this module?" questions.
**Parameters:**
| `path` | string | no | File path or directory prefix. Omit for entire codebase |
**Example:**
```json
{
"params": {
"name": "get_public_api",
"arguments": { "path": "src/cache" }
}
}
```
### `get_callers`
Find declarations that reference a symbol. Searches signatures and import statements across all files. Approximate — based on name matching, not full call graph.
**Parameters:**
| `symbol` | string | yes | Symbol name to search for references to |
| `limit` | number | no | Max results (default: 20, max: 50) |
**Example:**
```json
{
"params": {
"name": "get_callers",
"arguments": { "symbol": "estimate_tokens" }
}
}
```
### `get_related_tests`
> *Extended tool — only listed with `--all-tools`, but always callable.*
Find test functions for a symbol by naming convention and file association.
**Parameters:**
| `symbol` | string | yes | Symbol name to find tests for |
| `path` | string | no | Optional file path to scope search |
**Example:**
```json
{
"params": {
"name": "get_related_tests",
"arguments": { "symbol": "apply_token_budget" }
}
}
```
### `get_dependency_graph`
> *Extended tool — only listed with `--all-tools`, but always callable.*
Get file-level or symbol-level dependency graph. Shows import relationships between files or extends/implements relationships between symbols. Output in DOT (Graphviz), Mermaid, or JSON format.
**Parameters:**
| `path` | string | no | Scope to a subtree (file or directory prefix). Omit for entire codebase |
| `level` | string | no | Graph granularity: `file` (default) or `symbol` |
| `format` | string | no | Output format: `dot`, `mermaid` (default), or `json` |
| `depth` | number | no | Max edge hops from scoped files/symbols (default: unlimited) |
**Example:**
```json
{
"params": {
"name": "get_dependency_graph",
"arguments": { "path": "src/parser", "format": "mermaid", "depth": 2 }
}
}
```
### `get_diff_summary`
> *Extended tool — only listed with `--all-tools`, but always callable.*
Get structural changes (added/removed/modified declarations) since a git ref or for a GitHub PR. Requires either `since_ref` or `pr` (not both). Much cheaper than reading raw diffs.
**Parameters:**
| `since_ref` | string | no | Git ref to diff against (branch name, tag, or commit like `HEAD~3`) |
| `pr` | integer | no | GitHub PR number — resolves the PR's base branch automatically (alternative to `since_ref`) |
One of `since_ref` or `pr` must be provided.
**Authentication (for `pr`):** Requires a GitHub token via `GITHUB_TOKEN` env var, `GH_TOKEN` env var, or `gh auth token` (GitHub CLI). The PR's base branch must be available locally.
**Example (git ref):**
```json
{
"params": {
"name": "get_diff_summary",
"arguments": { "since_ref": "main" }
}
}
```
**Example (PR):**
```json
{
"params": {
"name": "get_diff_summary",
"arguments": { "pr": 42 }
}
}
```
When using `pr`, the response includes a `pr` field with metadata:
```json
{
"since_ref": "origin/main",
"pr": { "number": 42, "title": "Add caching layer", "base": "main", "head": "feat/cache" },
"changes": 3,
"files_added": [...],
"files_removed": [...],
"files_modified": [...]
}
```
### `get_hotspots`
> *Extended tool — only listed with `--all-tools`, but always callable.*
Get the most complex functions/methods in the codebase, ranked by a composite complexity score. Useful for identifying refactoring targets and understanding where technical debt concentrates. Only includes tree-sitter parsed languages (Rust, Python, TS, JS, Go, Java, C, C++).
**Parameters:**
| `limit` | number | no | Maximum number of results (default: 20, max: 100) |
| `path` | string | no | Optional file or directory path filter |
| `min_complexity` | number | no | Minimum cyclomatic complexity to include (default: 1) |
| `sort_by` | string | no | Sort criterion: `score` (default), `complexity`, `nesting`, `params`, `body_lines` |
| `compact` | boolean | no | Return columnar format (saves ~30% tokens) |
**Example:**
```json
{
"params": {
"name": "get_hotspots",
"arguments": { "limit": 10, "min_complexity": 5 }
}
}
```
**Example response:**
```json
{
"content": [{
"type": "text",
"text": "{\"total\":42,\"hotspots\":[{\"file\":\"src/parser.rs\",\"name\":\"parse_file\",\"kind\":\"function\",\"line\":10,\"cyclomatic\":12,\"max_nesting\":4,\"param_count\":1,\"body_lines\":20,\"score\":18.5}]}"
}]
}
```
**Score formula:** `cyclomatic + nesting*2 + params*0.5 + body_lines/20`
### `get_health`
> *Extended tool — only listed with `--all-tools`, but always callable.*
Get a codebase health summary with aggregate complexity metrics, documentation coverage, test ratio, and quality indicators. Only complexity data from tree-sitter parsed languages is included.
**Parameters:**
| `path` | string | no | Optional path filter to scope to a directory or file |
**Example:**
```json
{
"params": {
"name": "get_health",
"arguments": { "path": "src/parser" }
}
}
```
**Example response:**
```json
{
"content": [{
"type": "text",
"text": "{\"total_functions\":150,\"analyzed\":120,\"complexity\":{\"avg\":4.2,\"median\":3,\"max\":25,\"p90\":10},\"nesting\":{\"avg\":1.8},\"params\":{\"avg\":2.1},\"body_lines\":{\"avg\":15.3},\"high_complexity_count\":8,\"high_complexity_pct\":6.7,\"documented_pct\":45.0,\"test_count\":35,\"deprecated_count\":2,\"public_api_count\":60,\"hottest_files\":[{\"file\":\"src/parser.rs\",\"functions\":12,\"avg_complexity\":8.5,\"max_complexity\":25}]}"
}]
}
```
**Fields:**
- `total_functions` — total function/method count (all languages)
- `analyzed` — functions with complexity data (tree-sitter languages only)
- `complexity` — avg, median, max, p90 cyclomatic complexity
- `high_complexity_count/pct` — functions with cyclomatic complexity >= 10
- `documented_pct` — percentage of functions with doc comments
- `test_count` — number of test functions
- `hottest_files` — top 5 files by average complexity (min 2 functions)
### `get_type_flow`
> *Extended tool — only listed with `--all-tools`, but always callable.*
Track where a type flows across function boundaries. Shows which functions produce (return) and consume (accept as parameters) a given type. Useful for understanding data flow, finding related code, and tracing how data moves through the system. Supports 10+ languages: Rust, Go, TypeScript, JavaScript, Python, Java, Kotlin, Swift, C, C++, and C#.
**Parameters:**
| `type_name` | string | yes | Type name to track (e.g., `FileIndex`, `Declaration`, `Cache`) |
| `path` | string | no | File or directory path filter to scope the search |
| `include_fields` | boolean | no | If true, also include struct/class fields that hold this type (default: false) |
| `limit` | number | no | Maximum results per role (default: 50, max: 200) |
| `compact` | boolean | no | Return columnar format (saves ~30% tokens) |
**Example:**
```json
{
"params": {
"name": "get_type_flow",
"arguments": { "type_name": "FileIndex", "path": "src/parser" }
}
}
```
**Example response:**
```json
{
"content": [{
"type": "text",
"text": "{\"type_name\":\"FileIndex\",\"producers_count\":3,\"consumers_count\":5,\"producers\":[{\"file\":\"src/parser/mod.rs\",\"name\":\"parse_file\",\"kind\":\"function\",\"signature\":\"pub fn parse_file(path: &Path) -> Result<FileIndex>\",\"line\":42,\"role\":\"producer\"}],\"consumers\":[{\"file\":\"src/indexer.rs\",\"name\":\"merge_index\",\"kind\":\"function\",\"signature\":\"pub fn merge_index(files: Vec<FileIndex>) -> CodebaseIndex\",\"line\":15,\"role\":\"consumer\"}]}"
}]
}
```
**Fields:**
- `type_name` — the type that was searched for
- `producers_count` / `consumers_count` — total matches (before `limit` truncation)
- `producers` — functions that return this type
- `consumers` — functions that accept this type as a parameter (and fields, if `include_fields` is true)
## Wiki Tools
> *Requires `--features wiki`. `wiki_generate` is always listed; the remaining 8 tools appear once a wiki exists in `.indxr/wiki/`.*
Wiki tools let agents generate, query, and grow a persistent knowledge wiki about the codebase. See [Wiki docs](wiki.md) for the full feature overview.
### `wiki_generate`
Initialize a new wiki and return the codebase structural context for planning pages. After calling this, plan which pages to create (architecture, module, entity, topic) based on the returned context, then call `wiki_contribute` for each page. Fails if a wiki already exists unless `force=true`.
**Parameters:**
| `force` | boolean | no | Overwrite existing wiki if one exists (default: false) |
### `wiki_search`
Search the codebase knowledge wiki by keyword or concept. Returns matching pages with excerpts.
**Parameters:**
| `query` | string | yes | Search term or concept |
| `limit` | integer | no | Max results (default: 5) |
| `include_failures` | boolean | no | Include failure pattern details in results (default: false) |
### `wiki_read`
Read a wiki page by ID (e.g. `"architecture"`, `"mod-mcp"`). Returns full page content with metadata.
**Parameters:**
| `page` | string | yes | Page ID or partial title to search |
### `wiki_status`
Check wiki health: page count, how stale it is (commits behind HEAD), source file coverage.
**Parameters:** None.
### `wiki_contribute`
Write knowledge back to the wiki. Create a new page or update an existing one. Supports contradiction tracking and failure pattern recording.
**Parameters:**
| `page` | string | yes | Page ID (slug). If it exists, the page is updated; if not, a new page is created |
| `content` | string | yes | Markdown content for the page. Use `[[page-id]]` for cross-references |
| `title` | string | no | Human-readable title (required for new pages, optional for updates) |
| `page_type` | string | no | Page type: `architecture`, `module`, `entity`, `topic` (default: `topic`). Only used for new pages |
| `source_files` | string[] | no | Source files this page relates to |
| `contradictions` | object[] | no | Contradictions to add (each: `description` required, `source` optional) |
| `resolve_contradictions` | boolean | no | Mark all existing unresolved contradictions on this page as resolved |
| `failures` | object[] | no | Failure patterns to add (each: `symptom`, `attempted_fix`, `diagnosis` required; `actual_fix`, `source_files` optional) |
| `resolve_failures` | boolean | no | Mark all unresolved failures on this page as resolved |
### `wiki_update`
Analyze code changes since last wiki generation and return affected pages with diff context. For each affected page, rewrite its content based on the diff and current content, then call `wiki_contribute` to save. No API keys needed — the agent drives the updates.
**Parameters:**
| `since` | string | no | Git ref to diff against (default: wiki's stored ref) |
### `wiki_suggest_contribution`
Given a synthesis or analysis, suggest which wiki page to update or whether to create a new one. Lightweight — uses keyword matching against existing pages, no LLM call needed.
**Parameters:**
| `synthesis` | string | yes | The synthesized knowledge or analysis text |
| `source_pages` | string[] | no | Wiki page IDs that were consulted during synthesis |
### `wiki_compound`
Compound new knowledge into the wiki. Takes a synthesis and automatically routes it to the best matching page, or creates a new topic page if no good match exists. Use this after answering questions that required cross-page synthesis.
**Parameters:**
| `synthesis` | string | yes | The knowledge to compound into the wiki |
| `source_pages` | string[] | no | Wiki page IDs that contributed to this synthesis |
| `title` | string | no | Title for new page if one needs to be created |
### `wiki_record_failure`
Record a failed fix attempt so future agents can learn from it. Auto-routes to the best matching wiki page, or specify a target page explicitly.
**Parameters:**
| `symptom` | string | yes | What was observed (error message, test failure, unexpected behavior) |
| `attempted_fix` | string | yes | What fix was attempted |
| `diagnosis` | string | yes | Why the fix didn't work / root cause analysis |
| `actual_fix` | string | no | What actually worked (if known at recording time) |
| `source_files` | string[] | no | Source files involved in this failure |
| `page` | string | no | Target wiki page ID. If omitted, auto-routes to best matching page |
## Configuration for AI Tools
> **Tip:** `indxr init` can create all these configuration files automatically. See `indxr init --help` or the [Agent Integration Guide](agent-integration.md#quick-setup).
### Claude Code
Add to `.mcp.json` in your project root (or run `indxr init --claude`):
```json
{
"mcpServers": {
"indxr": {
"command": "indxr",
"args": ["serve", "."]
}
}
}
```
Or via CLI:
```bash
claude mcp add indxr -- indxr serve .
```
### Claude Desktop
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"indxr": {
"command": "indxr",
"args": ["serve", "/absolute/path/to/project"]
}
}
}
```
### Cursor
Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global), or run `indxr init --cursor` (`indxr init --global --cursor` for global):
```json
{
"mcpServers": {
"indxr": {
"command": "indxr",
"args": ["serve", "."]
}
}
}
```
### Windsurf
Add to `.windsurf/mcp.json` (project) or `~/.codeium/windsurf/mcp_config.json` (global), or run `indxr init --windsurf` (`indxr init --global --windsurf` for global):
```json
{
"mcpServers": {
"indxr": {
"command": "indxr",
"args": ["serve", "."]
}
}
}
```
### Codex CLI
Add to `.codex/config.toml` (project) or `~/.codex/config.toml` (global), or run `indxr init --codex` (`indxr init --global --codex` for global):
```toml
[mcp_servers.indxr]
command = "indxr"
args = ["serve", "."]
```
### Custom Integration
#### stdio
The MCP server communicates via JSON-RPC 2.0 over stdin/stdout. Any client that speaks MCP can connect. Spawn the process and send/receive newline-delimited JSON messages.
```python
import subprocess, json
proc = subprocess.Popen(
["indxr", "serve", "./my-project"],
stdin=subprocess.PIPE,
stdout=subprocess.PIPE,
text=True
)
# Send initialize
request = {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {
"protocolVersion": "2024-11-05",
"capabilities": {},
"clientInfo": {"name": "my-agent", "version": "1.0"}
}}
proc.stdin.write(json.dumps(request) + "\n")
proc.stdin.flush()
response = json.loads(proc.stdout.readline())
# Send initialized notification
proc.stdin.write(json.dumps({
"jsonrpc": "2.0", "method": "notifications/initialized"
}) + "\n")
proc.stdin.flush()
# Call a compound tool
request = {"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {
"name": "find",
"arguments": {"query": "main", "mode": "symbol"}
}}
proc.stdin.write(json.dumps(request) + "\n")
proc.stdin.flush()
result = json.loads(proc.stdout.readline())
print(result)
```
#### Streamable HTTP
With the HTTP transport, send JSON-RPC requests as HTTP POST to `/mcp`:
```bash
# Initialize (creates a session)
curl -X POST http://localhost:8080/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}'
# Response includes Mcp-Session-Id header
# Call a tool (include session ID)
curl -X POST http://localhost:8080/mcp \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Mcp-Session-Id: <session-id>' \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_stats","arguments":{}}}'
# Listen for server notifications (SSE)
curl -N http://localhost:8080/mcp \
-H 'Accept: text/event-stream' \
-H 'Mcp-Session-Id: <session-id>'
# End session
curl -X DELETE http://localhost:8080/mcp \
-H 'Mcp-Session-Id: <session-id>'
```