code_nav.search

Instructions

Implementation Reference

• src/tools/search.ts:22-81 (handler)

  The main handler function for the 'code_nav.search' tool. Orchestrates the full search workflow: loads repo config, lists candidate files, plans the query, finds files by name (fff), performs exact pattern searches (with fallback), ranks candidates, extracts context, and returns packed results.

  export async function search(input: SearchInput, cwd = process.cwd()) {
    const repo = await getRepoRoot(cwd);
    const loaded = await loadConfig(repo.repoRoot);
    const listed = await listCandidateFiles(repo.repoRoot, repo.isGitRepo, loaded.config);
    const warnings = [...repo.warnings, ...loaded.warnings, ...listed.warnings];
    const limit = clampLimit(input.limit, loaded.config.result_limit, 50);
    const maxTokens = clampLimit(input.max_context_tokens, DEFAULT_CONTEXT_TOKENS, 50_000);
    const plan = planQuery(input.task, input.memory_context, input.scope ?? []);
  
    const fileHits = [];
    for (const fileQuery of plan.file_queries.slice(0, 8)) {
      const found = await fffFindFiles(repo.repoRoot, listed.files, fileQuery, input.scope, limit);
      if (found.warning) warnings.push(`fff: ${found.warning}`);
      fileHits.push(...found.results);
    }
  
    let exactHits: ExactSearchResult[] = [];
    if (plan.exact_patterns.length > 0) {
      try {
        exactHits = await exactSearch(
          {
            patterns: plan.exact_patterns,
            scope: input.scope,
            limit: Math.max(limit * 4, 40),
            context_lines: 1,
            fixed: true,
            case_sensitive: false,
          },
          cwd,
        );
      } catch {
        const fallback = await rgExactSearch(
          repo.repoRoot,
          listed.files,
          plan.exact_patterns,
          input.scope,
          Math.max(limit * 4, 40),
          1,
          true,
          false,
        );
        exactHits = fallback.results;
        if (fallback.warning) warnings.push(fallback.warning);
      }
    }
  
    const candidates = rankCandidates(plan, fileHits, exactHits, input.task, limit);
    const extracted = await extractContext(
      repo.repoRoot,
      targetsFromCandidates(candidates),
      input.task,
      maxTokens,
    );
    warnings.push(...extracted.warnings);
    return {
      query_plan: plan,
      results: packSearchResults(candidates, extracted.blocks, maxTokens),
      warnings,
    };
  }

• src/tools/search.ts:14-20 (schema)

  Input schema type for the search tool: task (string), memory_context (optional string), scope (optional string array), limit (optional positive int), max_context_tokens (optional positive int).

  export interface SearchInput {
    task: string;
    memory_context?: string;
    scope?: string[];
    limit?: number;
    max_context_tokens?: number;
  }

• src/mcp.ts:116-130 (registration)

  Registration of the 'code_nav.search' tool with the MCP server. Registers it with description, inputSchema (Zod validation for task, memory_context, scope, limit, max_context_tokens), readOnlyHint annotation, and a handler that calls the imported 'search' function.

  server.registerTool(
    "code_nav.search",
    {
      description: "Main deterministic code navigation workflow.",
      inputSchema: {
        task: z.string(),
        memory_context: z.string().optional(),
        scope: z.array(z.string()).optional(),
        limit: z.number().int().positive().optional(),
        max_context_tokens: z.number().int().positive().optional(),
      },
      annotations: { readOnlyHint: true, openWorldHint: false },
    },
    async (input) => mcpJson(await search(input)),
  );