@iderouter/index-mcp 0.2.0-beta.1

package/README.md

@@ -0,0 +1,93 @@
+# 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:
+
+```text
+~/.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.
+
+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.
+
+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
+
+```bash
+export IDEROUTER_API_KEY="ir-..."
+```
+
+Optional advanced tuning:
+
+```bash
+# Primary probe slower than this will compare the built-in fallback model.
+export IDEROUTER_EMBEDDING_HEALTH_SLOW_MS=8000
+```
+
+## Optional Codex Skill Install
+
+If you want Codex to prefer `iderouter-index` automatically, install the
+companion skill explicitly:
+
+```bash
+npx @iderouter/index-mcp init codex
+```
+
+This writes:
+
+```text
+~/.codex/skills/iderouter-index/SKILL.md
+```
+
+The install step is explicit on purpose; normal MCP startup does not modify the
+client skill catalog automatically.
+
+## Tools
+
+- `index_codebase`: index a local directory.
+- `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.
+
+## Codex Config
+
+```toml
+[mcp_servers.iderouter-index]
+type = "stdio"
+command = "npx"
+args = ["-y", "@iderouter/index-mcp"]
+
+[mcp_servers.iderouter-index.env]
+IDEROUTER_API_KEY = "ir-..."
+```

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@iderouter/index-mcp",
+  "version": "0.2.0-beta.1",
+  "description": "Hybrid local code index MCP powered by IDERouter embeddings.",
+  "type": "module",
+  "bin": {
+    "iderouter-index-mcp": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "scripts",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "check": "node --check src/index.js",
+    "benchmark:noop": "node scripts/benchmark-noop.mjs",
+    "benchmark:small-change": "node scripts/benchmark-small-change.mjs",
+    "benchmark:deferred": "node scripts/benchmark-deferred.mjs",
+    "benchmark:all": "node scripts/benchmark-all.mjs",
+    "benchmark:clean-snapshot": "node scripts/benchmark-clean-snapshot.mjs",
+    "benchmark:stage-summary": "node scripts/benchmark-stage-summary.mjs"
+  }
+}

package/scripts/benchmark-all.mjs

@@ -0,0 +1,177 @@
+#!/usr/bin/env node
+
+import { execFile } from "node:child_process";
+import path from "node:path";
+import process from "node:process";
+import { promisify } from "node:util";
+import { gitWorkspaceStats } from "./lib/mcp-bench.mjs";
+
+const execFileAsync = promisify(execFile);
+const TARGET_PATH = path.resolve(process.argv[2] || process.cwd());
+const SCRIPT_DIR = path.resolve("scripts");
+
+async function runScript(scriptName) {
+  const scriptPath = path.join(SCRIPT_DIR, scriptName);
+  const { stdout } = await execFileAsync(process.execPath, [scriptPath, TARGET_PATH], {
+    cwd: process.cwd(),
+    env: process.env,
+    maxBuffer: 8 * 1024 * 1024,
+  });
+  return JSON.parse(String(stdout || "").trim());
+}
+
+function summarize(result) {
+  if (result?.priority_ready && Array.isArray(result?.searches)) {
+    return {
+      priority_ready_ms: result.priority_ready?.parsed?.priority_ready_ms ?? result.priority_ready?.wallMs ?? 0,
+      priority_ready_anchor_completed: result.priority_ready_anchor_coverage?.completed ?? null,
+      priority_ready_anchor_total: result.priority_ready_anchor_coverage?.total ?? null,
+      query_count: result.searches.length,
+      all_top1_hit: result.searches.every((item) => item?.top1_hit === true),
+      max_search_ms: Math.max(...result.searches.map((item) => Number(item?.wall_ms || 0)), 0),
+      searches: result.searches.map((item) => ({
+        name: item.name,
+        wall_ms: item.wall_ms,
+        top1_hit: item.top1_hit,
+        top1: item.top1,
+      })),
+    };
+  }
+  if (result?.priority_ready && result?.first && result?.second) {
+    return {
+      priority_ready_ms: result.priority_ready?.parsed?.priority_ready_ms ?? result.priority_ready?.wallMs ?? 0,
+      priority_ready_anchor_completed: result.priority_ready_anchor_coverage?.completed ?? null,
+      priority_ready_anchor_total: result.priority_ready_anchor_coverage?.total ?? null,
+      repeat_query: result.repeat_query || "",
+      first_ms: result.first?.wall_ms ?? null,
+      second_ms: result.second?.wall_ms ?? null,
+      speedup_ratio: result.speedup_ratio ?? null,
+    };
+  }
+  return {
+    wall_ms: result.wall_ms ?? 0,
+    scan_ms: result.scan_ms ?? 0,
+    total_ms: result.total_ms ?? 0,
+    strategy_version: result.strategy_version || "",
+    strategy_source: result.strategy_source || "",
+    embedding_model_source: result.embedding_model_source || "",
+    final_status: result.final_status || "",
+  };
+}
+
+async function main() {
+  const workspace = await gitWorkspaceStats(TARGET_PATH);
+  const output = {
+    path: TARGET_PATH,
+    api_key_present: Boolean(process.env.IDEROUTER_API_KEY),
+    generated_at: new Date().toISOString(),
+    workspace,
+    benchmarks: {},
+  };
+
+  const cases = [
+    ["noop", "benchmark-noop.mjs"],
+    ["small_change", "benchmark-small-change.mjs"],
+    ["deferred", "benchmark-deferred.mjs"],
+    ["priority_ready_search", "benchmark-priority-ready-search.mjs"],
+    ["repeat_search", "benchmark-repeat-search.mjs"],
+    ["stage_summary", "benchmark-stage-summary.mjs"],
+  ];
+
+  for (const [name, scriptName] of cases) {
+    try {
+      const result = await runScript(scriptName);
+      output.benchmarks[name] = {
+        ok: true,
+        summary: summarize(result),
+        result,
+      };
+    } catch (error) {
+      output.benchmarks[name] = {
+        ok: false,
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  if (String(process.env.IDEROUTER_BENCH_INCLUDE_CLEAN_SNAPSHOT || "").toLowerCase() === "true") {
+    try {
+      const result = await runScript("benchmark-clean-snapshot.mjs");
+      output.benchmarks.clean_snapshot = {
+        ok: true,
+        summary: summarize(result.measure || result),
+        result,
+      };
+    } catch (error) {
+      output.benchmarks.clean_snapshot = {
+        ok: false,
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  }
+
+  output.comparison = buildComparison(output);
+
+  process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+}
+
+function buildComparison(output) {
+  const noop = output.benchmarks.noop?.result;
+  const smallChange = output.benchmarks.small_change?.result;
+  const deferred = output.benchmarks.deferred?.result;
+  const priorityReadySearch = output.benchmarks.priority_ready_search?.result;
+  const repeatSearch = output.benchmarks.repeat_search?.result;
+  const cleanSnapshot = output.benchmarks.clean_snapshot?.result;
+  const stageSummary = output.benchmarks.stage_summary?.result;
+  const resumeRounds = Array.isArray(stageSummary?.resume_rounds) ? stageSummary.resume_rounds : [];
+  const finalResumeAnchorCoverage = resumeRounds.length > 0 ? resumeRounds[resumeRounds.length - 1]?.priority_ready_anchor_coverage : null;
+  const workspace = output.workspace || {};
+  const noOpComparable = workspace.workspace_dirty === false || Number(workspace.indexable_dirty_entries || 0) === 0;
+  const cleanComparable = Boolean(cleanSnapshot?.comparable_to_auggie);
+  return {
+    no_op_comparable_to_auggie: noOpComparable,
+    clean_snapshot_available: Boolean(cleanSnapshot),
+    clean_snapshot_comparable_to_auggie: cleanComparable,
+    note: noOpComparable
+      ? "No-op benchmark is comparable to Auggie daily ready path."
+      : cleanComparable
+        ? "Workspace is dirty, but clean snapshot benchmark is available for fair Auggie comparison."
+        : "Workspace has indexable dirty files; no-op benchmark is not a true clean-repo comparison against Auggie.",
+    current_signals: {
+      noop_total_ms: noop?.total_ms ?? null,
+      clean_snapshot_noop_total_ms: cleanSnapshot?.measure?.total_ms ?? null,
+      clean_snapshot_strategy_mode: cleanSnapshot?.strategy_mode ?? null,
+      small_change_changed: smallChange?.observed_index_change ?? null,
+      deferred_stable: deferred?.stable_status ?? null,
+      deferred_resumed_unexpectedly: deferred?.resumed_unexpectedly ?? null,
+      priority_ready_ms: priorityReadySearch?.priority_ready?.parsed?.priority_ready_ms ?? null,
+      priority_ready_anchor_completed: priorityReadySearch?.priority_ready_anchor_coverage?.completed ?? null,
+      priority_ready_anchor_total: priorityReadySearch?.priority_ready_anchor_coverage?.total ?? null,
+      priority_ready_all_top1_hit: Array.isArray(priorityReadySearch?.searches)
+        ? priorityReadySearch.searches.every((item) => item?.top1_hit === true)
+        : null,
+      priority_ready_max_search_ms: Array.isArray(priorityReadySearch?.searches)
+        ? Math.max(...priorityReadySearch.searches.map((item) => Number(item?.wall_ms || 0)), 0)
+        : null,
+      repeat_search_first_ms: repeatSearch?.first?.wall_ms ?? null,
+      repeat_search_second_ms: repeatSearch?.second?.wall_ms ?? null,
+      repeat_search_speedup_ratio: repeatSearch?.speedup_ratio ?? null,
+      repeat_search_priority_ready_anchor_completed: repeatSearch?.priority_ready_anchor_coverage?.completed ?? null,
+      repeat_search_priority_ready_anchor_total: repeatSearch?.priority_ready_anchor_coverage?.total ?? null,
+      stage_summary_priority_ready_ms: stageSummary?.priority_ready_ms ?? null,
+      stage_summary_priority_ready_anchor_completed: stageSummary?.priority_ready_anchor_completed ?? null,
+      stage_summary_priority_ready_anchor_total: stageSummary?.priority_ready_anchor_total ?? null,
+      stage_summary_resume_rounds_run: stageSummary?.resume_rounds_run ?? null,
+      stage_summary_resume_final_anchor_completed: finalResumeAnchorCoverage?.completed ?? null,
+      stage_summary_resume_final_anchor_total: finalResumeAnchorCoverage?.total ?? null,
+      stage_summary_resume_cumulative_semantic_files: stageSummary?.resume_cumulative_semantic_files ?? null,
+      stage_summary_composite_score: stageSummary?.composite_score ?? null,
+      stage_summary_composite_band: stageSummary?.composite_band ?? null,
+    },
+  };
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});

package/scripts/benchmark-auto-continuation.mjs

@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+
+import {
+  cleanupBenchmarkRun,
+  installBenchmarkSignalCleanup,
+  readIndexMeta,
+  readJobStatus,
+  sleep,
+  spawnMcpClient,
+} from "./lib/mcp-bench.mjs";
+import {
+  continuationAlreadyMaterialized,
+  hasAdvanced,
+  isCoarseDeferredReady,
+  isFullReadyState,
+} from "./lib/auto-continuation-state.mjs";
+import { createBenchmarkSnapshot } from "./lib/benchmark-snapshot.mjs";
+
+const TARGET_PATH = path.resolve(process.argv[2] || process.cwd());
+const POLL_MS = Number(process.env.IDEROUTER_BENCH_POLL_MS || 1000);
+const FIRST_PHASE_TIMEOUT_MS = Number(process.env.IDEROUTER_BENCH_AUTO_CONTINUE_FIRST_PHASE_TIMEOUT_MS || 180000);
+const CONTINUATION_TIMEOUT_MS = Number(process.env.IDEROUTER_BENCH_AUTO_CONTINUE_TIMEOUT_MS || 180000);
+
+function snapshotState(meta, job, statusText) {
+  return {
+    status_text: statusText.split("\n")[0],
+    job_id: job?.id || "",
+    job_status: job?.status || "",
+    current_step: job?.currentStep || "",
+    continuation_pass_count: Number(job?.continuationPassCount || 0),
+    progress: Number(job?.progress || 0),
+    embedded_count: Number(job?.embeddedCount || 0),
+    total_chunks: Number(job?.totalChunks || 0),
+    background_fine_deferred: Boolean(job?.backgroundFineDeferred),
+    semantic_retry_deferred: Boolean(job?.semanticRetryDeferred),
+    searchable_modes: job?.searchableModes || meta?.searchableModes || "",
+    priority_fine_progress: Number(job?.priorityFineProgress || meta?.priorityFineProgress || 0),
+    fine_semantic_files: Number(meta?.fineSemanticFileCount || 0),
+    fine_semantic_chunks: Number(meta?.fineSemanticChunkCount || 0),
+    background_bucket_cursor: String(meta?.backgroundBucketCursor || ""),
+    background_fine_target_files: Number(meta?.backgroundFineTargetFiles || job?.diagnostics?.backgroundFineTargetFiles || 0),
+    background_fine_target_chunks: Number(meta?.backgroundFineTargetChunks || job?.diagnostics?.backgroundFineTargetChunks || 0),
+    semantic_retry_deferred_at: String(job?.semanticRetryDeferredAt || ""),
+    deferred_resume_worker_pid: Number(job?.deferredResumeWorkerPid || 0),
+    updated_at: job?.updatedAt || meta?.updatedAt || "",
+  };
+}
+
+async function waitForDeferredReady(client, snapshotDir, indexHome) {
+  const startedAt = Date.now();
+  let lastText = "";
+  while (Date.now() - startedAt < FIRST_PHASE_TIMEOUT_MS) {
+    lastText = await client.callTool("get_indexing_status", { path: snapshotDir });
+    const meta = await readIndexMeta(indexHome, snapshotDir);
+    const job = await readJobStatus(indexHome, snapshotDir);
+    const deferredReady =
+      Boolean(job?.backgroundFineDeferred) &&
+      Boolean(job?.priorityFineReady) &&
+      /^Priority semantic search is ready\b/.test(lastText);
+    const coarseDeferredReady =
+      Boolean(job?.backgroundFineDeferred) &&
+      !Boolean(job?.priorityFineReady) &&
+      isCoarseDeferredReady(snapshotState(meta, job, lastText));
+    const fullReady = Boolean(meta?.complete) || isFullReadyState(snapshotState(meta, job, lastText));
+    if (fullReady) {
+      return {
+        settled: true,
+        wall_ms: Date.now() - startedAt,
+        state: snapshotState(meta, job, lastText),
+      };
+    }
+    if (deferredReady) {
+      return {
+        settled: true,
+        wall_ms: Date.now() - startedAt,
+        state: snapshotState(meta, job, lastText),
+      };
+    }
+    if (coarseDeferredReady) {
+      return {
+        settled: true,
+        wall_ms: Date.now() - startedAt,
+        state: snapshotState(meta, job, lastText),
+      };
+    }
+    await sleep(POLL_MS);
+  }
+  const meta = await readIndexMeta(indexHome, snapshotDir);
+  const job = await readJobStatus(indexHome, snapshotDir);
+  return {
+    settled: false,
+    wall_ms: Date.now() - startedAt,
+    state: snapshotState(meta, job, lastText),
+  };
+}
+
+async function waitForAutoContinuation(client, snapshotDir, indexHome, baselineState) {
+  const startedAt = Date.now();
+  let lastText = "";
+  while (Date.now() - startedAt < CONTINUATION_TIMEOUT_MS) {
+    lastText = await client.callTool("get_indexing_status", { path: snapshotDir });
+    const meta = await readIndexMeta(indexHome, snapshotDir);
+    const job = await readJobStatus(indexHome, snapshotDir);
+    const currentState = snapshotState(meta, job, lastText);
+    const continuationOccurred = Number(currentState.continuation_pass_count || 0) >= Number(baselineState.continuation_pass_count || 0);
+    const activeOrNewJob =
+      String(currentState.job_id || "") !== String(baselineState.job_id || "") ||
+      ["queued", "scanning", "indexing"].includes(String(currentState.job_status || ""));
+    if (continuationOccurred && activeOrNewJob && hasAdvanced(baselineState, currentState)) {
+      return {
+        settled: true,
+        wall_ms: Date.now() - startedAt,
+        state: currentState,
+      };
+    }
+    await sleep(POLL_MS);
+  }
+  const meta = await readIndexMeta(indexHome, snapshotDir);
+  const job = await readJobStatus(indexHome, snapshotDir);
+  return {
+    settled: false,
+    wall_ms: Date.now() - startedAt,
+    state: snapshotState(meta, job, lastText),
+  };
+}
+
+async function main() {
+  const snapshot = await createBenchmarkSnapshot(TARGET_PATH, process.env);
+  const snapshotDir = snapshot.snapshotDir;
+  const isolatedIndexHome = await fs.mkdtemp(path.join(os.tmpdir(), "iderouter-bench-auto-continue-"));
+  const env = {
+    ...process.env,
+    IDEROUTER_INDEX_HOME: isolatedIndexHome,
+  };
+  const { child, client } = spawnMcpClient(env);
+  const uninstallSignalCleanup = installBenchmarkSignalCleanup(() => ({
+    child,
+    indexHome: isolatedIndexHome,
+    targetPath: snapshotDir,
+    snapshotDir,
+  }));
+
+  try {
+    await client.initialize();
+    const startText = await client.callTool("index_codebase", { path: snapshotDir, wait: false, cloud: false });
+    const firstPhase = await waitForDeferredReady(client, snapshotDir, isolatedIndexHome);
+    const continuation = !firstPhase.settled
+      ? { settled: false, wall_ms: 0, state: firstPhase.state }
+      : continuationAlreadyMaterialized(firstPhase.state)
+        ? { settled: true, wall_ms: 0, state: firstPhase.state }
+        : await waitForAutoContinuation(client, snapshotDir, isolatedIndexHome, firstPhase.state);
+
+    process.stdout.write(
+      `${JSON.stringify(
+        {
+          path: TARGET_PATH,
+          snapshot_path: snapshotDir,
+          snapshot_mode: snapshot.mode,
+          isolated_index_home: isolatedIndexHome,
+          start_status: startText.split("\n")[0],
+          first_phase: firstPhase,
+          continuation,
+          auto_continuation_confirmed: Boolean(firstPhase.settled && continuation.settled),
+        },
+        null,
+        2,
+      )}\n`,
+    );
+  } finally {
+    uninstallSignalCleanup();
+    await cleanupBenchmarkRun({
+      child,
+      indexHome: isolatedIndexHome,
+      targetPath: snapshotDir,
+      snapshotDir,
+    });
+  }
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});