opencode-codebase-index 0.15.0 → 0.16.0

package/dist/cli.js

@@ -8995,10 +8995,19 @@ var Indexer = class {
     });
     const embeddingStartTime = performance2.now();
     const embeddingQuery = stripFilePathHint(query);
-    const embedding = await this.getQueryEmbedding(embeddingQuery, provider);
+    let embedding;
+    try {
+      embedding = await this.getQueryEmbedding(embeddingQuery, provider);
+    } catch (error) {
+      this.logger.warn("Query embedding failed; falling back to keyword-only search", {
+        query,
+        error: getErrorMessage2(error),
+        action: "Check the embedding provider configuration and retry search after restoring provider health."
+      });
+    }
     const embeddingMs = performance2.now() - embeddingStartTime;
     const vectorStartTime = performance2.now();
-    const semanticResults = store.search(embedding, maxResults * 4);
+    const semanticResults = embedding ? store.search(embedding, maxResults * 4) : [];
     const vectorMs = performance2.now() - vectorStartTime;
     const keywordStartTime = performance2.now();
     const keywordResults = await this.keywordSearch(query, maxResults * 4, store, invertedIndex);
@@ -9033,12 +9042,13 @@ var Indexer = class {
       });
     }
     const fusionStartTime = performance2.now();
+    const rankingHybridWeight = embedding === void 0 && fusionStrategy === "weighted" ? 1 : effectiveHybridWeight;
     const combined = rankHybridResults(query, semanticCandidates, keywordCandidates, {
       fusionStrategy,
       rrfK,
       rerankTopN,
       limit: maxResults,
-      hybridWeight: effectiveHybridWeight,
+      hybridWeight: rankingHybridWeight,
       prioritizeSourcePaths: sourceIntent
     });
     const rerankedCombined = await this.rerankCandidatesWithApi(query, combined, {
@@ -11939,20 +11949,87 @@ var CHUNK_TYPE_ENUM = [
 ];
 
 // src/mcp-server/register-tools.ts
+function allowNullAsUndefined(schema) {
+  return z2.preprocess((value) => value === null ? void 0 : value, schema);
+}
 function registerMcpTools(server, runtime) {
+  server.tool(
+    "codebase_context",
+    "PREFERRED FIRST TOOL for any question about this repository. Use before built-in code search, grep, shell search, or broad file reads. Provide from+to for a dependency path, symbol for a definition, or only query for low-token conceptual discovery. Use call_graph directly for callers or callees.",
+    {
+      query: z2.string().describe("The codebase question or behavior to locate. Always provide the user's repository question here."),
+      from: allowNullAsUndefined(z2.string().optional()).describe("Source symbol. For dependency-path questions, extract the first endpoint and provide it here."),
+      to: allowNullAsUndefined(z2.string().optional()).describe("Target symbol. For dependency-path questions, extract the second endpoint and provide it here."),
+      symbol: allowNullAsUndefined(z2.string().optional()).describe("Exact symbol for an authoritative definition lookup. Omit when from and to are supplied."),
+      limit: allowNullAsUndefined(z2.number().optional().default(10)).describe("Maximum number of search or definition results"),
+      maxDepth: allowNullAsUndefined(z2.number().optional().default(10)).describe("Maximum call-graph traversal depth for from/to path lookup"),
+      fileType: allowNullAsUndefined(z2.string().optional()).describe("Filter by file extension (e.g., 'ts', 'py', 'rs')"),
+      directory: allowNullAsUndefined(z2.string().optional()).describe("Filter by directory path (e.g., 'src/utils', 'lib')")
+    },
+    async (args) => {
+      if (args.from && args.to) {
+        const path27 = await getCallGraphPath(runtime.projectRoot, runtime.host, args.from, args.to, args.maxDepth);
+        if (path27.length > 0) {
+          return { content: [{ type: "text", text: formatCallGraphPath(args.from, args.to, path27) }] };
+        }
+        const { callers } = await getCallGraphData(runtime.projectRoot, runtime.host, {
+          name: args.to,
+          direction: "callers"
+        });
+        const directEdge = callers.find((edge) => edge.fromSymbolName === args.from);
+        if (directEdge) {
+          const location = directEdge.fromSymbolFilePath ? ` at ${directEdge.fromSymbolFilePath}:${directEdge.line}` : "";
+          return {
+            content: [{
+              type: "text",
+              text: `Direct path: ${args.from} --${directEdge.callType}--> ${args.to}${location} (edge is ${directEdge.isResolved ? "resolved" : "unresolved"}).`
+            }]
+          };
+        }
+        return { content: [{ type: "text", text: formatCallGraphPath(args.from, args.to, path27) }] };
+      }
+      if (args.symbol) {
+        const results2 = await implementationLookup(runtime.projectRoot, runtime.host, args.symbol, {
+          limit: args.limit ?? 10,
+          fileType: args.fileType,
+          directory: args.directory
+        });
+        return { content: [{ type: "text", text: formatDefinitionLookup(results2, args.symbol) }] };
+      }
+      const results = await searchCodebase(runtime.projectRoot, runtime.host, args.query, {
+        limit: args.limit ?? 10,
+        fileType: args.fileType,
+        directory: args.directory,
+        metadataOnly: true
+      });
+      if (results.length === 0) {
+        return { content: [{ type: "text", text: "No matching code found. Try a different query or run index_codebase first." }] };
+      }
+      return {
+        content: [{
+          type: "text",
+          text: `Found ${results.length} locations for "${args.query}":
+
+${formatCodebasePeek(results)}
+
+Use implementation_lookup for an authoritative definition, or call call_graph/call_graph_path once you have a symbol.`
+        }]
+      };
+    }
+  );
   server.tool(
     "codebase_search",
-    "Search codebase by MEANING, not keywords. Returns full code content. For just finding WHERE code is (saves ~90% tokens), use codebase_peek instead.",
+    "FULL-CONTENT semantic retrieval. Use after codebase_peek when you need implementation text, not as the default first step. For exact identifiers or exhaustive matches use grep instead.",
     {
       query: z2.string().describe("Natural language description of what code you're looking for. Describe behavior, not syntax."),
-      limit: z2.number().optional().default(5).describe("Maximum number of results to return"),
-      fileType: z2.string().optional().describe("Filter by file extension (e.g., 'ts', 'py', 'rs')"),
-      directory: z2.string().optional().describe("Filter by directory path (e.g., 'src/utils', 'lib')"),
-      chunkType: z2.enum(CHUNK_TYPE_ENUM).optional().describe("Filter by code chunk type"),
-      contextLines: z2.number().optional().describe("Number of extra lines to include before/after each match (default: 0)"),
-      blameAuthor: z2.string().optional().describe("Filter by git blame author name or email"),
-      blameSha: z2.string().optional().describe("Filter by git blame commit SHA or prefix"),
-      blameSince: z2.string().optional().describe("Filter to chunks last changed on or after this date")
+      limit: allowNullAsUndefined(z2.number().optional().default(5)).describe("Maximum number of results to return"),
+      fileType: allowNullAsUndefined(z2.string().optional()).describe("Filter by file extension (e.g., 'ts', 'py', 'rs')"),
+      directory: allowNullAsUndefined(z2.string().optional()).describe("Filter by directory path (e.g., 'src/utils', 'lib')"),
+      chunkType: allowNullAsUndefined(z2.enum(CHUNK_TYPE_ENUM).optional()).describe("Filter by code chunk type"),
+      contextLines: allowNullAsUndefined(z2.number().optional()).describe("Number of extra lines to include before/after each match (default: 0)"),
+      blameAuthor: allowNullAsUndefined(z2.string().optional()).describe("Filter by git blame author name or email"),
+      blameSha: allowNullAsUndefined(z2.string().optional()).describe("Filter by git blame commit SHA or prefix"),
+      blameSince: allowNullAsUndefined(z2.string().optional()).describe("Filter to chunks last changed on or after this date")
     },
     async (args) => {
       const results = await searchCodebase(runtime.projectRoot, runtime.host, args.query, {
@@ -11975,16 +12052,16 @@ ${formatSearchResults(results, "score")}` }] };
   );
   server.tool(
     "codebase_peek",
-    "Quick lookup of code locations by meaning. Returns only metadata (file, line, name, type) WITHOUT code content. Saves ~90% tokens vs codebase_search.",
+    "DIRECT LOW-TOKEN semantic location lookup for unfamiliar-code discovery. Prefer codebase_context when the request may involve definitions or graph navigation; use this specialized tool when you only need conceptual locations.",
     {
       query: z2.string().describe("Natural language description of what code you're looking for."),
-      limit: z2.number().optional().default(10).describe("Maximum number of results to return"),
-      fileType: z2.string().optional().describe("Filter by file extension (e.g., 'ts', 'py', 'rs')"),
-      directory: z2.string().optional().describe("Filter by directory path (e.g., 'src/utils', 'lib')"),
-      chunkType: z2.enum(CHUNK_TYPE_ENUM).optional().describe("Filter by code chunk type"),
-      blameAuthor: z2.string().optional().describe("Filter by git blame author name or email"),
-      blameSha: z2.string().optional().describe("Filter by git blame commit SHA or prefix"),
-      blameSince: z2.string().optional().describe("Filter to chunks last changed on or after this date")
+      limit: allowNullAsUndefined(z2.number().optional().default(10)).describe("Maximum number of results to return"),
+      fileType: allowNullAsUndefined(z2.string().optional()).describe("Filter by file extension (e.g., 'ts', 'py', 'rs')"),
+      directory: allowNullAsUndefined(z2.string().optional()).describe("Filter by directory path (e.g., 'src/utils', 'lib')"),
+      chunkType: allowNullAsUndefined(z2.enum(CHUNK_TYPE_ENUM).optional()).describe("Filter by code chunk type"),
+      blameAuthor: allowNullAsUndefined(z2.string().optional()).describe("Filter by git blame author name or email"),
+      blameSha: allowNullAsUndefined(z2.string().optional()).describe("Filter by git blame commit SHA or prefix"),
+      blameSince: allowNullAsUndefined(z2.string().optional()).describe("Filter to chunks last changed on or after this date")
     },
     async (args) => {
       const results = await searchCodebase(runtime.projectRoot, runtime.host, args.query, {
@@ -12009,11 +12086,11 @@ Use Read tool to examine specific files.` }] };
   );
   server.tool(
     "index_codebase",
-    "Index the codebase for semantic search. Creates vector embeddings of code chunks. Incremental - only re-indexes changed files. Run before first codebase_search.",
+    "Create or refresh the semantic index. Call index_status first when readiness is unknown, then use this tool only if the index is missing, stale, or incompatible. Incremental by default; force=true rebuilds everything.",
     {
-      force: z2.boolean().optional().default(false).describe("Force reindex even if already indexed"),
-      estimateOnly: z2.boolean().optional().default(false).describe("Only show cost estimate without indexing"),
-      verbose: z2.boolean().optional().default(false).describe("Show detailed info about skipped files and parsing failures")
+      force: allowNullAsUndefined(z2.boolean().optional().default(false)).describe("Force reindex even if already indexed"),
+      estimateOnly: allowNullAsUndefined(z2.boolean().optional().default(false)).describe("Only show cost estimate without indexing"),
+      verbose: allowNullAsUndefined(z2.boolean().optional().default(false)).describe("Show detailed info about skipped files and parsing failures")
     },
     async (args) => {
       const result = await runIndexCodebase(runtime.projectRoot, runtime.host, args);
@@ -12028,7 +12105,7 @@ Use Read tool to examine specific files.` }] };
   );
   server.tool(
     "index_status",
-    "Check the status of the codebase index. Shows whether the codebase is indexed, how many chunks are stored, and the embedding provider being used.",
+    "START HERE once per repository task when index readiness or freshness is unknown. Reports whether semantic retrieval is ready, chunk counts, compatibility, and the embedding provider. If ready, continue with codebase_peek or implementation_lookup; otherwise run index_codebase.",
     {},
     async () => {
       const status = await getIndexStatus(runtime.projectRoot, runtime.host);
@@ -12060,9 +12137,13 @@ Use Read tool to examine specific files.` }] };
     "index_logs",
     "Get recent debug logs from the codebase indexer. Requires debug.enabled=true in config.",
     {
-      limit: z2.number().optional().default(20).describe("Maximum number of log entries to return"),
-      category: z2.enum(["search", "embedding", "cache", "gc", "branch", "general"]).optional().describe("Filter by log category"),
-      level: z2.enum(["error", "warn", "info", "debug"]).optional().describe("Filter by minimum log level")
+      limit: allowNullAsUndefined(z2.number().optional().default(20)).describe("Maximum number of log entries to return"),
+      category: allowNullAsUndefined(
+        z2.enum(["search", "embedding", "cache", "gc", "branch", "general"]).optional()
+      ).describe("Filter by log category"),
+      level: allowNullAsUndefined(
+        z2.enum(["error", "warn", "info", "debug"]).optional()
+      ).describe("Filter by minimum log level")
     },
     async (args) => {
       const result = await getIndexLogs(runtime.projectRoot, runtime.host, args);
@@ -12071,14 +12152,14 @@ Use Read tool to examine specific files.` }] };
   );
   server.tool(
     "find_similar",
-    "Find code similar to a given snippet. Use for duplicate detection, pattern discovery, or refactoring prep.",
+    "Use when you already have a code snippet and need analogous implementations, duplicates, patterns, or refactoring candidates. For a natural-language concept without example code, start with codebase_peek instead.",
     {
       code: z2.string().describe("The code snippet to find similar code for"),
-      limit: z2.number().optional().default(10).describe("Maximum number of results to return"),
-      fileType: z2.string().optional().describe("Filter by file extension (e.g., 'ts', 'py', 'rs')"),
-      directory: z2.string().optional().describe("Filter by directory path (e.g., 'src/utils', 'lib')"),
-      chunkType: z2.enum(CHUNK_TYPE_ENUM).optional().describe("Filter by code chunk type"),
-      excludeFile: z2.string().optional().describe("Exclude results from this file path")
+      limit: allowNullAsUndefined(z2.number().optional().default(10)).describe("Maximum number of results to return"),
+      fileType: allowNullAsUndefined(z2.string().optional()).describe("Filter by file extension (e.g., 'ts', 'py', 'rs')"),
+      directory: allowNullAsUndefined(z2.string().optional()).describe("Filter by directory path (e.g., 'src/utils', 'lib')"),
+      chunkType: allowNullAsUndefined(z2.enum(CHUNK_TYPE_ENUM).optional()).describe("Filter by code chunk type"),
+      excludeFile: allowNullAsUndefined(z2.string().optional()).describe("Exclude results from this file path")
     },
     async (args) => {
       const results = await findSimilarCode(runtime.projectRoot, runtime.host, args.code, {
@@ -12098,12 +12179,12 @@ ${formatSearchResults(results)}` }] };
   );
   server.tool(
     "implementation_lookup",
-    "Jump to symbol definition. Find WHERE something is defined. Returns the authoritative source location(s). Prefers real implementation files over tests, docs, examples, and fixtures.",
+    "FIRST TOOL only for known-symbol definition questions. Returns authoritative source locations and prefers implementations over tests, docs, examples, and fixtures. Do not use for callers, callees, dependency paths, or code flow; use codebase_context with direction or from/to for those questions.",
     {
       query: z2.string().describe("Symbol name or natural language description (e.g., 'validateToken', 'where is the payment handler defined')"),
-      limit: z2.number().optional().default(5).describe("Maximum number of results"),
-      fileType: z2.string().optional().describe("Filter by file extension (e.g., 'ts', 'py')"),
-      directory: z2.string().optional().describe("Filter by directory path (e.g., 'src/utils')")
+      limit: allowNullAsUndefined(z2.number().optional().default(5)).describe("Maximum number of results"),
+      fileType: allowNullAsUndefined(z2.string().optional()).describe("Filter by file extension (e.g., 'ts', 'py')"),
+      directory: allowNullAsUndefined(z2.string().optional()).describe("Filter by directory path (e.g., 'src/utils')")
     },
     async (args) => {
       const results = await implementationLookup(runtime.projectRoot, runtime.host, args.query, {
@@ -12116,12 +12197,16 @@ ${formatSearchResults(results)}` }] };
   );
   server.tool(
     "call_graph",
-    "Query the call graph to find callers or callees of a function/method. Use to understand code flow and dependencies. Supports relationship types: Call, MethodCall, Constructor, Import, Inherits, Implements.",
+    "Use after identifying a symbol to find its direct callers or callees and understand code flow. Use implementation_lookup first if the symbol or definition is still ambiguous. Supports relationship types: Call, MethodCall, Constructor, Import, Inherits, Implements.",
     {
       name: z2.string().describe("Function or method name to query"),
-      direction: z2.enum(["callers", "callees"]).default("callers").describe("Direction: 'callers' finds who calls this function, 'callees' finds what this function calls"),
-      symbolId: z2.string().optional().describe("Symbol ID (required for 'callees' direction)"),
-      relationshipType: z2.enum(["Call", "MethodCall", "Constructor", "Import", "Inherits", "Implements"]).optional().describe("Filter by relationship type. Omit to show all.")
+      direction: allowNullAsUndefined(
+        z2.enum(["callers", "callees"]).default("callers")
+      ).describe("Direction: 'callers' finds who calls this function, 'callees' finds what this function calls"),
+      symbolId: allowNullAsUndefined(z2.string().optional()).describe("Symbol ID (required for 'callees' direction)"),
+      relationshipType: allowNullAsUndefined(
+        z2.enum(["Call", "MethodCall", "Constructor", "Import", "Inherits", "Implements"]).optional()
+      ).describe("Filter by relationship type. Omit to show all.")
     },
     async (args) => {
       if (args.direction === "callees") {
@@ -12137,11 +12222,11 @@ ${formatSearchResults(results)}` }] };
   );
   server.tool(
     "call_graph_path",
-    "Find the shortest connection path between two symbols in the call graph. Returns the chain of calls connecting them.",
+    "Use after identifying both endpoint symbols to find the shortest known call path between them. Use codebase_peek or implementation_lookup first when either endpoint is unknown.",
     {
       from: z2.string().describe("Source function/method name (starting point)"),
       to: z2.string().describe("Target function/method name (destination)"),
-      maxDepth: z2.number().optional().default(10).describe("Maximum traversal depth (default: 10)")
+      maxDepth: allowNullAsUndefined(z2.number().optional().default(10)).describe("Maximum traversal depth (default: 10)")
     },
     async (args) => {
       const path27 = await getCallGraphPath(runtime.projectRoot, runtime.host, args.from, args.to, args.maxDepth);
@@ -12150,14 +12235,16 @@ ${formatSearchResults(results)}` }] };
   );
   server.tool(
     "pr_impact",
-    "Analyze the impact of a pull request or branch by examining changed files, affected symbols, transitive callers, communities touched, hub nodes, and risk level. Use to understand blast radius before merging.",
+    "FIRST TOOL for pull-request or branch blast-radius questions. Analyzes changed files, affected symbols, transitive dependencies, communities, hub nodes, conflicts, and risk before merging.",
     {
-      pr: z2.number().optional().describe("Pull request number to analyze"),
-      branch: z2.string().optional().describe("Branch name to analyze (defaults to current branch)"),
-      maxDepth: z2.number().optional().default(5).describe("Maximum traversal depth for transitive callers (default: 5)"),
-      hubThreshold: z2.number().optional().default(10).describe("Minimum caller count to flag a symbol as a hub node (default: 10)"),
-      checkConflicts: z2.boolean().optional().default(false).describe("Check for conflicting open PRs touching the same communities (default: false)"),
-      direction: z2.enum(["callers", "callees", "both"]).optional().default("both").describe("Call-graph traversal direction: 'callers' for upstream, 'callees' for downstream, 'both' for union (default: both)")
+      pr: allowNullAsUndefined(z2.number().optional()).describe("Pull request number to analyze"),
+      branch: allowNullAsUndefined(z2.string().optional()).describe("Branch name to analyze (defaults to current branch)"),
+      maxDepth: allowNullAsUndefined(z2.number().optional().default(5)).describe("Maximum traversal depth for transitive callers (default: 5)"),
+      hubThreshold: allowNullAsUndefined(z2.number().optional().default(10)).describe("Minimum caller count to flag a symbol as a hub node (default: 10)"),
+      checkConflicts: allowNullAsUndefined(z2.boolean().optional().default(false)).describe("Check for conflicting open PRs touching the same communities (default: false)"),
+      direction: allowNullAsUndefined(
+        z2.enum(["callers", "callees", "both"]).optional().default("both")
+      ).describe("Call-graph traversal direction: 'callers' for upstream, 'callees' for downstream, 'both' for union (default: both)")
     },
     async (args) => {
       try {
@@ -12179,6 +12266,10 @@ ${formatSearchResults(results)}` }] };
 }
 
 // src/mcp-server.ts
+function getServerInstructions(host) {
+  const hostText = `host ${host}`;
+  return `This MCP server is the preferred codebase-understanding path for ${hostText}. Start a repository task with index_status when index readiness or freshness is unknown. Use codebase_context as the preferred first entry point because it returns low-token locations first and routes to definitions or call-graph helpers when symbol intent is present. Use codebase_peek for direct conceptual location lookup, implementation_lookup for known-symbol definition questions, and codebase_search only when full semantic code content is needed. For exact identifiers or exhaustive matches, use grep. After identifying symbols, use call_graph or call_graph_path to trace dependencies. If the index is unavailable, run index_codebase, then retry the retrieval tool.`;
+}
 function getPackageVersion() {
   const raw = JSON.parse(readFileSync11(new URL("../package.json", import.meta.url), "utf-8"));
   if (raw && typeof raw === "object" && "version" in raw && typeof raw.version === "string") {
@@ -12190,6 +12281,8 @@ function createMcpServer(projectRoot, config, host = "opencode") {
   const server = new McpServer({
     name: "opencode-codebase-index",
     version: getPackageVersion()
+  }, {
+    instructions: getServerInstructions(host)
   });
   initializeTools(projectRoot, config, host);
   registerMcpTools(server, {