@iderouter/index-mcp 0.2.0-beta.2 → 0.2.0-beta.4

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.2",
+  "version": "0.2.0-beta.4",
   "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,89 @@ 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 = 4) {
+  return String(text || "")
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .filter((line) => !/^#/.test(line))
+    .map((line) => line.replace(/\*\*/g, "").replace(/`/g, ""))
+    .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 });
@@ -6713,14 +6798,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;
@@ -6863,6 +6949,117 @@ 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 summarizeRepoTechStackFromContext(contextProbe, fallbackStack) {
+  const summary = String(contextProbe?.summary || "").toLowerCase();
+  const merged = new Set(Array.isArray(fallbackStack) ? fallbackStack : []);
+  if (summary.includes("go ")) merged.add("Go backend");
+  if (summary.includes("react") || summary.includes("typescript")) merged.add("TypeScript/React frontend");
+  if (summary.includes("tailwind")) merged.add("Tailwind CSS");
+  if (summary.includes("gin")) merged.add("Gin web framework");
+  if (summary.includes("gorm")) merged.add("GORM");
+  if (summary.includes("redis")) merged.add("Redis");
+  if (summary.includes("sqlite") || summary.includes("mysql") || summary.includes("postgresql")) {
+    merged.add("Multi-database support");
+  }
+  return [...merged];
+}
+
+function summarizeEntrypoints(results, limit = 5) {
+  const preferredRoleOrder = ["controller", "router", "service", "relay", "model", "pkg", "frontend", "core"];
+  const bestByRole = new Map();
+  for (const result of results || []) {
+    const role = pathRole(result.relativePath);
+    if (!preferredRoleOrder.includes(role)) continue;
+    const existing = bestByRole.get(role);
+    if (!existing || Number(result.score || 0) > Number(existing.score || 0)) {
+      bestByRole.set(role, result);
+    }
+  }
+  const ordered = [];
+  for (const role of preferredRoleOrder) {
+    const item = bestByRole.get(role);
+    if (item) ordered.push(item);
+    if (ordered.length >= limit) break;
+  }
+  if (ordered.length >= limit) return ordered.slice(0, limit);
+  const seen = new Set(ordered.map((item) => `${item.relativePath}:${item.startLine}:${item.endLine}`));
+  for (const result of results || []) {
+    const key = `${result.relativePath}:${result.startLine}:${result.endLine}`;
+    if (seen.has(key)) continue;
+    if (["docs", "tests", "mcp", "other"].includes(pathRole(result.relativePath))) continue;
+    ordered.push(result);
+    seen.add(key);
+    if (ordered.length >= limit) break;
+  }
+  return ordered;
+}
+
+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 = summarizeRepoTechStackFromContext(contextProbe, summarizeRepoTechStack(topResults));
+  const entrypoints = summarizeEntrypoints(topResults, 5);
+  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 (entrypoints.length > 0) {
+    lines.push("");
+    lines.push("Key entrypoints:");
+    for (const result of entrypoints) {
+      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();
@@ -6904,6 +7101,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()) {
@@ -7766,6 +7982,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.",
@@ -7806,6 +8034,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":