@iderouter/index-mcp 0.2.0-beta.1 → 0.2.0-beta.3

package/README.md

@@ -75,6 +75,7 @@ client skill catalog automatically.
 ## Tools
 
 - `index_codebase`: index a local directory.
+- `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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iderouter/index-mcp",
-  "version": "0.2.0-beta.1",
+  "version": "0.2.0-beta.3",
   "description": "Hybrid local code index MCP powered by IDERouter embeddings.",
   "type": "module",
   "bin": {

package/src/index.js

@@ -314,6 +314,7 @@ const searchResultCache = new Map();
 const SEARCH_RESULT_CACHE_TTL_MS = Number(process.env.IDEROUTER_SEARCH_RESULT_CACHE_TTL_MS || 120000);
 const queryAnalysisCache = new Map();
 const QUERY_ANALYSIS_CACHE_TTL_MS = Number(process.env.IDEROUTER_QUERY_ANALYSIS_CACHE_TTL_MS || 300000);
+const contextProbeCache = new Map();
 
 function log(message) {
   process.stderr.write(`[${SERVER_NAME}] ${message}\n`);
@@ -341,8 +342,9 @@ Use this skill when a repository has the \`iderouter-index\` MCP configured.
 
 1. Run \`index_codebase(path=...)\` when the repository is new or stale.
 2. Use \`get_indexing_status(path=...)\` to wait for coarse or priority-semantic readiness.
-3. Use \`ask_codebase(path=..., question=...)\` for repository questions.
-4. Use \`search_code(path=..., query=...)\` when you need ranked snippets or exact evidence.
+3. Use \`summarize_codebase(path=...)\` for a fast project overview while background fine indexing continues.
+4. Use \`ask_codebase(path=..., question=...)\` for repository questions.
+5. Use \`search_code(path=..., query=...)\` when you need ranked snippets or exact evidence.
 
 ## Notes
 
@@ -352,6 +354,88 @@ Use this skill when a repository has the \`iderouter-index\` MCP configured.
 `;
 }
 
+function userCodexConfigPath() {
+  const codexHome = String(process.env.CODEX_HOME || "").trim();
+  if (codexHome) {
+    return path.join(codexHome, "config.toml");
+  }
+  return path.join(os.homedir(), ".codex", "config.toml");
+}
+
+function contextProbeCacheKey(codebasePath) {
+  return `context:${codebasePath}`;
+}
+
+function summarizeContextText(text, maxLines = 8) {
+  return String(text || "")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .filter((line) => !/^#/.test(line))
+    .slice(0, maxLines)
+    .join(" ");
+}
+
+async function readOptionalFileProbe(filePath, kind) {
+  try {
+    const stat = await fs.stat(filePath);
+    if (!stat.isFile()) return null;
+    const content = await fs.readFile(filePath, "utf8");
+    return {
+      kind,
+      filePath,
+      mtimeMs: Math.trunc(stat.mtimeMs),
+      size: stat.size,
+      excerpt: summarizeContextText(content),
+    };
+  } catch {
+    return null;
+  }
+}
+
+async function probeAgentContext(codebasePath) {
+  const cacheKey = contextProbeCacheKey(codebasePath);
+  const repoAgentsPath = path.join(codebasePath, "AGENTS.md");
+  const repoClaudePath = path.join(codebasePath, "CLAUDE.md");
+  const codexConfigPath = userCodexConfigPath();
+  const [agentsProbe, claudeProbe, codexProbe] = await Promise.all([
+    readOptionalFileProbe(repoAgentsPath, "repo_agents"),
+    readOptionalFileProbe(repoClaudePath, "repo_claude"),
+    readOptionalFileProbe(codexConfigPath, "codex_config"),
+  ]);
+  const fingerprint = [
+    agentsProbe ? `${agentsProbe.filePath}:${agentsProbe.mtimeMs}:${agentsProbe.size}` : "",
+    claudeProbe ? `${claudeProbe.filePath}:${claudeProbe.mtimeMs}:${claudeProbe.size}` : "",
+    codexProbe ? `${codexProbe.filePath}:${codexProbe.mtimeMs}:${codexProbe.size}` : "",
+  ].join("|");
+  const cached = contextProbeCache.get(cacheKey);
+  if (cached && cached.fingerprint === fingerprint) {
+    return cached.value;
+  }
+  const value = {
+    found: [agentsProbe, claudeProbe, codexProbe].filter(Boolean),
+    hasRepoAgents: Boolean(agentsProbe),
+    hasRepoClaude: Boolean(claudeProbe),
+    hasCodexConfig: Boolean(codexProbe),
+    summary: [agentsProbe, claudeProbe, codexProbe]
+      .filter(Boolean)
+      .map((item) => `${item.kind}:${item.excerpt}`)
+      .join(" | "),
+  };
+  contextProbeCache.set(cacheKey, { fingerprint, value });
+  return value;
+}
+
+function contextProbeNotice(contextProbe) {
+  if (!contextProbe) return "";
+  const found = [];
+  if (contextProbe.hasRepoAgents) found.push("AGENTS.md");
+  if (contextProbe.hasRepoClaude) found.push("CLAUDE.md");
+  if (contextProbe.hasCodexConfig) found.push("Codex config");
+  if (found.length === 0) return "";
+  return ` Agent context detected: ${found.join(", ")}.`;
+}
+
 async function initCodexSkill() {
   const skillDir = codexSkillDir();
   await fs.mkdir(skillDir, { recursive: true });
@@ -1063,6 +1147,7 @@ function buildIndexMetaPayload(fullIndex) {
     updatedAt: fullIndex.updatedAt,
     embeddingModel: fullIndex.embeddingModel,
     embeddingModelsUsed: fullIndex.embeddingModelsUsed,
+    strategySource: fullIndex.strategySource || "",
     complete: fullIndex.complete,
     indexStage: fullIndex.indexStage,
     coarseReady: fullIndex.coarseReady,
@@ -3262,6 +3347,7 @@ async function saveIndex(codebasePath, files, chunks, options = {}) {
         .filter((chunk) => chunk.granularity !== "coarse" && Array.isArray(chunk.vector) && chunk.vector.length > 0)
         .map((chunk) => chunkVectorModel(chunk, options.embeddingModel || DEFAULT_EMBEDDING_MODEL)),
     ),
+    strategySource: options.strategySource || lastStrategySource || "local_fallback",
     complete: options.complete !== false,
     indexStage: options.indexStage || (options.complete === false ? "fine_partial" : "fine"),
     coarseReady: Boolean(options.coarseReady),
@@ -3638,6 +3724,16 @@ function formatIndexDiagnostics(diagnostics) {
   ].join(", ");
 }
 
+function effectiveStrategySource(...sources) {
+  for (const source of sources) {
+    const value = String(source || "").trim();
+    if (!value) continue;
+    if (value === "local_fallback") continue;
+    return value;
+  }
+  return "local_fallback";
+}
+
 async function indexCodebase(args, precomputedFiles) {
   const codebasePath = normalizePath(args.path);
   const job = args.__jobId ? indexJobs.get(args.__jobId) : null;
@@ -6324,7 +6420,11 @@ async function exactAnchorSearch(codebasePath, args, indexedKeys) {
       ? args.extensionFilter.map((ext) => (ext.startsWith(".") ? ext : `.${ext}`))
       : [],
   );
-  const files = await collectFiles(codebasePath, args.customExtensions, args.ignorePatterns);
+  const existingIndex = args.__searchIndex || null;
+  const prepared = existingIndex
+    ? await prepareFilesFast(codebasePath, existingIndex, args.customExtensions, args.ignorePatterns)
+    : null;
+  const files = prepared?.files || await collectFiles(codebasePath, args.customExtensions, args.ignorePatterns);
   const prioritizedFiles = files
     .map((file) => ({
       file,
@@ -6697,14 +6797,15 @@ async function searchCode(args) {
 async function collectSearchState(codebasePath, args, query, limit) {
   const loadedIndex = await loadExistingIndex(codebasePath);
   let job = await loadLatestJobForPath(codebasePath);
+  const contextProbe = await probeAgentContext(codebasePath);
   if (!loadedIndex) {
     if (isActiveJobStatus(job?.status)) {
-      return `No local index file is ready yet for ${codebasePath}. Index job ${job.id} is ${job.status}: ${job.progress}% (${job.embeddedCount}/${job.totalChunks} changed chunks), step=${job.currentStep}. ${AGENT_INDEX_NOTICE}`;
+      return `No local index file is ready yet for ${codebasePath}. Index job ${job.id} is ${job.status}: ${job.progress}% (${job.embeddedCount}/${job.totalChunks} changed chunks), step=${job.currentStep}.${contextProbeNotice(contextProbe)} ${AGENT_INDEX_NOTICE}`;
     }
     if (job?.status === "failed") {
-      return `No local index file is available for ${codebasePath}. Last index job ${job.id} failed at ${job.progress}%: ${cleanDiagnosticMessage(job.error)}. ${AGENT_INDEX_NOTICE}`;
+      return `No local index file is available for ${codebasePath}. Last index job ${job.id} failed at ${job.progress}%: ${cleanDiagnosticMessage(job.error)}.${contextProbeNotice(contextProbe)} ${AGENT_INDEX_NOTICE}`;
     }
-    return `No local index found for ${codebasePath}. Run index_codebase first. ${COMPANION_PROMPT_NOTICE} ${AGENT_INDEX_NOTICE}`;
+    return `No local index found for ${codebasePath}. Run index_codebase first, then use summarize_codebase(path=...) for a fast project overview.${contextProbeNotice(contextProbe)} ${COMPANION_PROMPT_NOTICE} ${AGENT_INDEX_NOTICE}`;
   }
   const usingPartialIndex = loadedIndex.complete === false;
   let resumed = null;
@@ -6718,7 +6819,10 @@ async function collectSearchState(codebasePath, args, query, limit) {
   const index = refresh.index;
   const indexEmbeddingModel = index.embeddingModel || DEFAULT_EMBEDDING_MODEL;
   const anchorVariants = anchorIdentifierVariants(query);
-  const skipQueryEmbedding = usingPartialIndex && anchorVariants.length > 0;
+  const activeJobRunning = isActiveJobStatus(job?.status);
+  const skipQueryEmbedding =
+    (usingPartialIndex && anchorVariants.length > 0) ||
+    ((usingPartialIndex || activeJobRunning) && !isImplementationLocatorQuery(query) && !isRemoveDisabledFieldsQuery(query));
   const queryVectors = new Map();
   const indexedVectorModels = mergeStringSets(
     index.chunks
@@ -6772,7 +6876,7 @@ async function collectSearchState(codebasePath, args, query, limit) {
     .filter((chunk) => chunk.score > 0 && querySpecificChunkAllowed(query, chunk));
 
   const indexedKeys = new Set(indexedResults.map((chunk) => `${chunk.relativePath}:${chunk.startLine}:${chunk.endLine}`));
-  const anchorResults = (await exactAnchorSearch(codebasePath, args, indexedKeys))
+  const anchorResults = (await exactAnchorSearch(codebasePath, { ...args, __searchIndex: index }, indexedKeys))
     .filter((chunk) => querySpecificChunkAllowed(query, chunk));
   let results = await expandResultSnippetsToBoundaries(codebasePath, query, diversifyResults(
     query,
@@ -6844,6 +6948,71 @@ function summarizeAnswerFromResults(question, results, limit) {
   ].join("\n");
 }
 
+function summarizeRepoDomains(results) {
+  const domains = new Set();
+  for (const result of results || []) {
+    const relativePath = String(result.relativePath || "").toLowerCase();
+    if (relativePath.startsWith("controller/")) domains.add("controller");
+    else if (relativePath.startsWith("service/")) domains.add("service");
+    else if (relativePath.startsWith("model/")) domains.add("model");
+    else if (relativePath.startsWith("router/")) domains.add("router");
+    else if (relativePath.startsWith("relay/")) domains.add("relay");
+    else if (relativePath.startsWith("pkg/")) domains.add("pkg");
+    else if (relativePath.startsWith("setting/")) domains.add("setting");
+    else if (relativePath.startsWith("dto/")) domains.add("dto");
+    else if (relativePath.startsWith("web/") || relativePath.startsWith("iderouter_frontend/")) domains.add("frontend");
+    else if (relativePath.startsWith("common/")) domains.add("common");
+  }
+  return [...domains];
+}
+
+function summarizeRepoTechStack(results) {
+  const files = (results || []).map((result) => String(result.relativePath || "").toLowerCase());
+  const stack = [];
+  if (files.some((file) => file.endsWith(".go"))) stack.push("Go backend");
+  if (files.some((file) => file.includes("web/") || file.includes("iderouter_frontend/") || file.endsWith(".tsx") || file.endsWith(".ts"))) {
+    stack.push("TypeScript/React frontend");
+  }
+  if (files.some((file) => file.endsWith(".sql"))) stack.push("SQL schema or migrations");
+  if (files.some((file) => file.endsWith(".yml") || file.endsWith(".yaml"))) stack.push("YAML workflow/config");
+  return stack;
+}
+
+function repoSummaryLines(codebasePath, state, contextProbe) {
+  const results = Array.isArray(state?.results) ? state.results : [];
+  const topResults = results.slice(0, 8);
+  const domains = summarizeRepoDomains(topResults);
+  const stack = summarizeRepoTechStack(topResults);
+  const lines = [
+    `Fast repository summary for ${codebasePath}:`,
+    "",
+    `Status: ${state?.usingPartialIndex ? "searchable partial index" : "ready index"}${state?.refresh?.skippedDueToActiveJob ? " while background indexing continues" : ""}.`,
+  ];
+  if (stack.length > 0) {
+    lines.push(`Likely stack: ${stack.join(", ")}.`);
+  }
+  if (domains.length > 0) {
+    lines.push(`Indexed layers present: ${domains.join(", ")}.`);
+  }
+  if (contextProbe?.found?.length) {
+    lines.push("");
+    lines.push("Agent Context:");
+    for (const item of contextProbe.found.slice(0, 3)) {
+      lines.push(`- ${path.basename(item.filePath)}: ${item.excerpt || "context file detected"}`);
+    }
+  }
+  if (topResults.length > 0) {
+    lines.push("");
+    lines.push("Key entrypoints:");
+    for (const result of topResults.slice(0, 5)) {
+      lines.push(`- ${result.relativePath}:${result.startLine}-${result.endLine}`);
+    }
+  }
+  lines.push("");
+  lines.push("Use get_indexing_status(path=...) to check background fine indexing progress.");
+  return lines.join("\n");
+}
+
 async function askCodebase(args) {
   const codebasePath = normalizePath(args.path);
   const question = String(args.question || "").trim();
@@ -6885,6 +7054,25 @@ async function askCodebase(args) {
   return summarizeAnswerFromResults(question, state.results, limit);
 }
 
+async function summarizeCodebase(args) {
+  const codebasePath = normalizePath(args.path);
+  const summaryQuery = "repository overview architecture core modules backend frontend key entrypoints";
+  const contextProbe = await probeAgentContext(codebasePath);
+  const state = await collectSearchState(
+    codebasePath,
+    { ...args, query: summaryQuery, __skipSearchCache: true },
+    summaryQuery,
+    Math.min(Number(args.limit || 8), 12),
+  );
+  if (typeof state === "string") {
+    return `${state}${contextProbeNotice(contextProbe)}`;
+  }
+  if (!Array.isArray(state.results) || state.results.length === 0) {
+    return `I could not build a repository summary for ${codebasePath} from the current index.${contextProbeNotice(contextProbe)}`;
+  }
+  return `${repoSummaryLines(codebasePath, state, contextProbe)}${contextProbeNotice(contextProbe)}`;
+}
+
 function latestJobForPath(codebasePath) {
   let latest = null;
   for (const job of indexJobs.values()) {
@@ -7601,6 +7789,19 @@ async function getIndexingStatus(args) {
   job = await ensureDeferredCloudState(codebasePath, currentIndex, job, args);
   const resumed = await maybeResumeOrphanedIndexJob(codebasePath, args, currentIndex, job);
   if (resumed?.job) job = resumed.job;
+  const resolvedStrategySource = effectiveStrategySource(
+    lastStrategySource,
+    currentIndex?.strategySource,
+    job?.strategySource,
+    currentIndex?.diagnostics?.strategySource,
+    job?.diagnostics?.strategySource,
+  );
+  if (job?.diagnostics) {
+    job.diagnostics = {
+      ...job.diagnostics,
+      strategySource: effectiveStrategySource(job.diagnostics.strategySource, resolvedStrategySource),
+    };
+  }
   const cloudSuffix = cloudStatusSuffix(job);
   const diagnosticsSuffix = job?.diagnostics ? ` Diagnostics: ${formatIndexDiagnostics(job.diagnostics)}.` : "";
   const readinessSuffix = job ? ` Readiness: ${summarizeReadiness(job)}.` : "";
@@ -7734,6 +7935,18 @@ const tools = [
       required: ["path", "query"],
     },
   },
+  {
+    name: "summarize_codebase",
+    description: "Produce a fast repository overview from the local index while background fine indexing may still be running.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string" },
+        limit: { type: "number" },
+      },
+      required: ["path"],
+    },
+  },
   {
     name: "ask_codebase",
     description: "Answer a repository question using the indexed local code context and cite the strongest matching snippets.",
@@ -7774,6 +7987,8 @@ async function callTool(name, args) {
       return args?.wait ? indexCodebase(args || {}) : startIndexJob(args || {});
     case "search_code":
       return searchCode(args || {});
+    case "summarize_codebase":
+      return summarizeCodebase(args || {});
     case "ask_codebase":
       return askCodebase(args || {});
     case "clear_index":