IDERouter Index MCP

Hybrid local code indexing MCP for Cursor, Codex, and Claude Code.

The MCP process runs locally so it can read your repository files. It uses your IDERouter API key for embedding requests and stores the generated index under:

~/.iderouter/index-mcp/indexes

Re-running index_codebase is incremental: unchanged files are reused from the local manifest without being read again, and unchanged chunks reuse their existing vectors. Only new or modified chunks call the embedding API.

The MCP uses a fixed two-model embedding policy. New fine indexes prefer qwen/qwen3-embedding-8b and automatically fall back to openai/text-embedding-3-small when the primary model is unavailable or slow. Users only configure an IDERouter API key; the endpoint and model policy are built in. Existing completed indexes keep using the model stored with that index so vector spaces are not mixed.

search_code also checks the workspace manifest before searching. If files were added, removed, or changed, it performs the same incremental refresh first so agents do not search stale code.

Indexing starts as a background job by default, so AI agents can keep working while the local index is being built. To use async indexing:

1. Call index_codebase with the target path and omit wait (or set wait=false).
2. Continue with other work while the job runs in the background.
3. Call get_indexing_status with the same path whenever progress is needed.

For faster agent adoption, summarize_codebase returns a compact overview with stack hints, key entrypoints, and detected repo context files such as AGENTS.md, CLAUDE.md, or Codex config. Use it first when you want a quick orientation before deeper questions.

The product is local-first: repository files stay on the machine running the MCP. Remote usage is limited to embedding requests and aggregate billing metadata.

The MCP also emits lightweight product telemetry so maintainers can understand tool adoption, indexing latency, coarse/priority readiness, fallback usage, and common query categories. These telemetry events do not upload repository file contents or raw search queries. Telemetry is best-effort: authentication failures and timeouts are automatically silenced so MCP responses stay usable even when telemetry is unavailable.

MCP installation itself cannot reliably auto-install client-side skills or rules across Cursor, Codex, and Claude Code. The supported path is to pair the MCP config with a companion prompt or rules block in the client so the agent prefers iderouter-index before broad file reads.

Environment

export IDEROUTER_API_KEY="ir-..."

Optional advanced tuning:

# Primary probe slower than this will compare the built-in fallback model.
export IDEROUTER_EMBEDDING_HEALTH_SLOW_MS=8000

# Disable product telemetry entirely for local testing or CI.
export IDEROUTER_DISABLE_TELEMETRY=1

# Override telemetry HTTP timing budgets when debugging or writing tests.
export IDEROUTER_TELEMETRY_REQUEST_TIMEOUT_MS=4000
export IDEROUTER_TELEMETRY_TIMEOUT_COOLDOWN_MS=60000

# Override interactive query embedding budget for experiments/tests.
export IDEROUTER_INTERACTIVE_QUERY_EMBEDDING_REQUEST_TIMEOUT_MS=5000
export IDEROUTER_INTERACTIVE_QUERY_EMBEDDING_MAX_RETRIES=0

Optional Codex Skill Install

If you want Codex to prefer iderouter-index automatically, install the companion skill explicitly:

npx @iderouter/index-mcp init codex

This writes:

~/.codex/skills/iderouter-index/SKILL.md

The install step is explicit on purpose; normal MCP startup does not modify the client skill catalog automatically.

Release

The recommended release path is a dedicated GitHub release mirror repository that contains only the MCP runtime package and release workflow. The private new-api repository remains the source of truth; the mirror is a generated, minimal publishing surface.

Main repository responsibilities:

# Build the release-repo mirror locally
./scripts/release/build_index_mcp_release_repo.sh

# Push the mirror to the release repo
INDEX_MCP_RELEASE_REMOTE=https://github.com/iderouter/index-mcp-release.git \
  ./scripts/release/push_index_mcp_release_repo.sh

# One-click sync + publish via GitHub Actions
./scripts/release/release_index_mcp.sh

The generated release repository contains only:

• src/
• package.json
• README.md
• .github/workflows/publish-index-mcp.yml
• publish_index_mcp.sh

This keeps the public release surface aligned with the files that actually ship in the npm package. Private backend, dashboard, billing, and other main-repo code stay outside the mirror.

Tools

• index_codebase: index a local directory.
• edit_file: apply a minimal-context file edit. Exact matching blocks are handled locally; placeholder-style edits using // ... existing code ... prefer local anchor application and only fall back to a model-backed full-file rewrite when needed.
• summarize_codebase: produce a fast project overview from the local index while background fine indexing continues.
• search_code: semantic search against the local index.
• ask_codebase: answer a repository question from indexed code and cite matching snippets.
• clear_index: delete an index.
• get_indexing_status: show indexed file/chunk counts and reuse diagnostics.

edit_file examples

Exact-match block edit:

{
  "path": "src/example.js",
  "instruction": "Keep the block aligned with the desired content.",
  "code_edit": "const alpha = 1;\nconst beta = 2;\nconst gamma = 3;"
}

Placeholder edit with local anchors or model fallback:

{
  "path": "src/example.js",
  "instruction": "Drop the middle section while preserving the surrounding anchors.",
  "code_edit": "const alpha = 1;\n// ... existing code ...\nconst gamma = 3;"
}

Preview without writing:

{
  "path": "src/example.js",
  "instruction": "Preview the candidate edit only.",
  "code_edit": "const alpha = 1;\n// ... existing code ...\nconst gamma = 3;",
  "dryRun": true
}

edit_file result summaries include execution details such as whether the edit was applied locally, whether a model fallback would be required, line-level change counts, and a compact preview of the changed region. In dryRun mode, unresolved edits do not invoke the model fallback path; they return a preview summary instead.

Codex Config

[mcp_servers.iderouter-index]
type = "stdio"
command = "npx"
args = ["-y", "@iderouter/index-mcp"]

[mcp_servers.iderouter-index.env]
IDEROUTER_API_KEY = "ir-..."