localnest_search_files

Search file paths and names to quickly locate modules, features, or components by name in your codebase, enabling faster module discovery than content search.

Instructions

Search file paths and names matching a query. Use this first when looking for a module, feature, or component by name (e.g. "sso", "payment", "auth"). Much faster than content search for module discovery, and handles cases where the keyword only appears in file/directory names.

Input Schema

TableJSON Schema

Name	Required	Default
`query`	Yes
`project_path`	No
`all_roots`	No
`max_results`	No
`case_sensitive`	No
`response_format`	No	json

Implementation Reference

src/mcp/tools/retrieval.js:214-261 (handler)

The handler implementation for the 'localnest_search_files' tool, which uses the search.searchFiles service to perform the search and includes handling for "search miss" scenarios.

registerJsonTool(
  'localnest_search_files',
  {
    title: 'Search Files',
    description: 'Search file paths and names matching a query. Use this first when looking for a module, feature, or component by name (e.g. "sso", "payment", "auth"). Much faster than content search for module discovery, and handles cases where the keyword only appears in file/directory names.',
    inputSchema: {
      query: z.string().min(1),
      project_path: z.string().optional(),
      all_roots: z.boolean().default(false),
      max_results: z.number().int().min(1).max(1000).default(defaultMaxResults),
      case_sensitive: z.boolean().default(false)
    },
    annotations: {
      readOnlyHint: true,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: false
    }
  },
  async ({ query, project_path, all_roots, max_results, case_sensitive }) => {
    const results = search.searchFiles({
      query,
      projectPath: project_path,
      allRoots: all_roots,
      maxResults: max_results,
      caseSensitive: case_sensitive
    });
    if (results.length > 0) return results;

    return withSearchMissResponse(
      results,
      buildSearchMeta({
        tool: 'localnest_search_files',
        query,
        project_path,
        all_roots,
        max_results,
        case_sensitive
      }),
      'No file-path matches found.',
      [
        'Verify project_path or broaden the query to a path fragment.',
        'Try synonyms or module names instead of full phrases.'
      ],
      'Retry localnest_search_files with a broader path fragment or switch to localnest_search_code for an exact symbol.'
    );
  }
);

LocalNest MCP