search_code

Instructions

Implementation Reference

• src/features/search-code/index.ts:172-320 (handler)

  The main handler/execute function for the search_code tool. It takes SearchCodeInput, initializes Ollama client and vector store, performs hybrid search (vector + BM25 + RRF), optionally adds call context, and returns formatted results.

  export async function execute(input: SearchCodeInput): Promise<FeatureResult> {
    const { query, directory, limit, threshold, mode, includeCallContext } =
      input;
  
    // Validate directory exists
    if (!fs.existsSync(directory)) {
      return {
        success: false,
        error: `Directory not found: ${directory}`,
      };
    }
  
    const absoluteDir = path.resolve(directory);
  
    // Initialize components
    const ollamaClient = createOllamaClient(EMBEDDING_CONFIG);
    const vectorStore = createVectorStore(absoluteDir, EMBEDDING_CONFIG);
  
    // Check if index exists
    if (!vectorStore.exists()) {
      return {
        success: false,
        error: `No index found for directory. Run index_codebase first: ${absoluteDir}`,
      };
    }
  
    try {
      // Check Ollama health
      const health = await ollamaClient.healthCheck();
      if (!health.ok) {
        return {
          success: false,
          error: health.error ?? "Ollama is not available",
        };
      }
  
      // Connect to vector store
      await vectorStore.connect();
  
      // Generate query embedding
      const queryVector = await ollamaClient.embed(query);
  
      // Search for similar chunks using hybrid search (vector + BM25 + RRF)
      let results = await vectorStore.searchHybrid(queryVector, query, limit, {
        mode: mode as SearchMode,
      });
  
      // Apply threshold filter if specified (only for vector mode where lower = better)
      // For hybrid/fts modes, RRF scores are higher = better, so threshold is ignored
      if (threshold !== undefined && mode === "vector") {
        results = results.filter((r) => r.score <= threshold);
      }
  
      vectorStore.close();
  
      let formattedResults = formatResults(results, absoluteDir);
  
      // Add call context if requested
      if (includeCallContext && formattedResults.length > 0) {
        // Build call graph for the directory
        const ig = createIgnoreFilter(absoluteDir);
        const files = collectFiles(absoluteDir, ig, absoluteDir);
        const fileContents = files.map((f) => ({
          path: f,
          content: fs.readFileSync(f, "utf-8"),
        }));
  
        const callGraph = await buildCallGraph(fileContents);
  
        // Add call context to each result that has a symbol name
        formattedResults = formattedResults.map((result) => {
          if (!result.symbolName) {
            return result;
          }
  
          const fullPath = path.join(absoluteDir, result.filePath);
          const context = getCallContext(callGraph, fullPath, result.symbolName);
  
          if (context) {
            return {
              ...result,
              callContext: {
                callers: context.callers.map((c) => c.name),
                callees: context.callees.map((c) => c.name),
              },
            };
          }
  
          return result;
        });
      }
  
      const output: SearchOutput = {
        query,
        directory: absoluteDir,
        resultsCount: formattedResults.length,
        results: formattedResults,
      };
  
      if (formattedResults.length === 0) {
        return {
          success: true,
          message: "No matching code found",
          data: output,
        };
      }
  
      // Build text message with results
      const resultLines = formattedResults.map((r, i) => {
        const location = `${r.filePath}:${String(r.startLine)}-${String(r.endLine)}`;
        const symbol = r.symbolName
          ? ` (${r.symbolType ?? "symbol"}: ${r.symbolName})`
          : "";
        const preview = r.content.slice(0, 100).replace(/\n/g, " ");
  
        let callInfo = "";
        if (r.callContext) {
          const callers =
            r.callContext.callers.length > 0
              ? `Called by: ${r.callContext.callers.slice(0, 3).join(", ")}${r.callContext.callers.length > 3 ? "..." : ""}`
              : "";
          const callees =
            r.callContext.callees.length > 0
              ? `Calls: ${r.callContext.callees.slice(0, 3).join(", ")}${r.callContext.callees.length > 3 ? "..." : ""}`
              : "";
          if (callers || callees) {
            callInfo = `\n   ${[callers, callees].filter(Boolean).join(" | ")}`;
          }
        }
  
        return `${String(i + 1)}. [${r.language}] ${location}${symbol}\n   ${preview}...${callInfo}`;
      });
  
      const message = `Found ${String(formattedResults.length)} results for "${query}":\n\n${resultLines.join("\n\n")}`;
  
      return {
        success: true,
        message,
        data: output,
      };
    } catch (err) {
      vectorStore.close();
      const errorMsg = err instanceof Error ? err.message : String(err);
      return {
        success: false,
        error: `Search failed: ${errorMsg}`,
      };
    }
  }

• src/features/search-code/index.ts:35-69 (schema)

  Zod schema defining input validation for search_code: query (string, required), directory, limit (default 10), threshold, mode (hybrid/vector/fts, default hybrid), includeCallContext (default true).

  export const searchCodeSchema = z.object({
    query: z.string().min(1).describe("Natural language search query"),
    directory: z
      .string()
      .optional()
      .default(".")
      .describe("Path to the indexed directory (defaults to current directory)"),
    limit: z
      .number()
      .int()
      .positive()
      .optional()
      .default(10)
      .describe("Maximum number of results to return"),
    threshold: z
      .number()
      .min(0)
      .max(2)
      .optional()
      .describe("Maximum distance threshold for results (lower = more similar)"),
    mode: z
      .enum(["vector", "fts", "hybrid"])
      .optional()
      .default("hybrid")
      .describe(
        "Search mode: 'vector' (semantic only), 'fts' (keyword only), 'hybrid' (combined with RRF fusion)",
      ),
    includeCallContext: z
      .boolean()
      .optional()
      .default(true)
      .describe(
        "Include caller/callee information for each result (uses cached call graph)",
      ),
  });

• src/features/search-code/index.ts:322-328 (registration)

  The Feature object for search_code: registers the tool under name 'search_code' with its schema, description, and execute function.

  export const searchCodeFeature: Feature<typeof searchCodeSchema> = {
    name: "search_code",
    description:
      "Search code semantically using natural language queries. USE THIS to find code by concept/meaning (e.g., 'authentication logic', 'error handling'). Requires index_codebase first. Returns relevant code chunks with file locations, function names, and call relationships (who calls what).",
    schema: searchCodeSchema,
    execute,
  };

• src/features/index.ts:22-29 (registration)

  The features registry array that includes searchCodeFeature and exports it via the getFeature lookup function.

  // Registry of features exposed via CLI and MCP
  export const features: Feature[] = [
    infoFeature,
    indexCodebaseFeature,
    searchCodeFeature,
    getIndexStatusFeature,
    updateIndexFeature,
  ];

• src/tools/adapter.ts:12-42 (registration)

  Generic adapter that registers any feature as an MCP tool on the server by calling server.tool() with feature name, description, schema, and execute wrapper.

  export function registerFeatureAsTool(
    server: McpServer,
    feature: Feature,
  ): void {
    const mcpSchema = zodToMcpSchema(feature.schema);
  
    // eslint-disable-next-line @typescript-eslint/no-deprecated
    server.tool(feature.name, feature.description, mcpSchema, async (params) => {
      const result = feature.execute(params);
  
      const formatResult = (
        res: Awaited<ReturnType<typeof feature.execute>>,
      ): {
        content: { type: "text"; text: string }[];
        isError: boolean;
      } => ({
        content: [
          {
            type: "text" as const,
            text: res.message ?? JSON.stringify(res.data, null, 2),
          },
        ],
        isError: !res.success,
      });
  
      if (result instanceof Promise) {
        return await result.then(formatResult);
      }
      return formatResult(result);
    });
  }