search_filesystem

Instructions

Implementation Reference

• src/index.ts:494-501 (handler)

  Executes the search_filesystem tool: parses args with schema, validates path, initiates recursive search, formats and returns matching file paths.

  case "search_filesystem": {
    const parsed = SearchFilesArgsSchema.parse(args);
    const validPath = validateWorkspacePath(parsed.path);
    const results: string[] = [];
    await searchFilesRecursive(validPath, validPath, parsed.pattern, parsed.excludePatterns, results);
    resultText = results.length > 0 ? results.join("\n") : "No matches found";
    break;
  }

• src/index.ts:86-119 (helper)

  Recursive helper function that traverses directories, checks name pattern match (case-insensitive), applies exclude globs, collects relative paths of matches.

  async function searchFilesRecursive(
    rootPath: string,
    currentPath: string,
    pattern: string,
    excludePatterns: string[],
    results: string[]
  ): Promise<void> {
    const entries = await fs.readdir(currentPath, { withFileTypes: true });
  
    for (const entry of entries) {
      const fullPath = path.join(currentPath, entry.name);
      const relativePath = path.relative(rootPath, fullPath);
  
      const shouldExclude = excludePatterns.some(p => minimatch(relativePath, p, { dot: true, matchBase: true }));
      if (shouldExclude) {
        continue;
      }
  
      if (entry.name.toLowerCase().includes(pattern.toLowerCase())) {
        results.push(path.relative(process.cwd(), fullPath));
      }
  
      if (entry.isDirectory()) {
        try {
            const realPath = await fs.realpath(fullPath);
            if (realPath.startsWith(rootPath)) {
               await searchFilesRecursive(rootPath, fullPath, pattern, excludePatterns, results);
            }
        } catch (e) {
            console.error(`Skipping search in ${fullPath}: ${(e as Error).message}`);
        }
      }
    }
  }

• src/tools/search_files.ts:7-11 (schema)

  Zod schema for input validation: path (start dir), pattern (search string), excludePatterns (optional glob excludes).

  export const SearchFilesArgsSchema = z.object({
    path: z.string().describe("The starting directory path for the search (relative to the workspace directory)."),
    pattern: z.string().describe("The case-insensitive text pattern to search for in file/directory names."),
    excludePatterns: z.array(z.string()).optional().default([]).describe("An array of glob patterns (e.g., 'node_modules', '*.log') to exclude from the search.")
  });

• src/tools/search_files.ts:16-39 (registration)

  ToolDefinition export including name 'search_filesystem', description, inputSchema reference, and buildPrompt for arg validation. Imported into tools/index.ts for allTools registration.

  export const searchFilesTool: ToolDefinition = {
      name: "search_filesystem", // Renamed slightly
      description:
        "Recursively search for files and directories within the workspace filesystem matching a pattern in their name. " +
        "Searches through all subdirectories from the starting path. The search " +
        "is case-insensitive and matches partial names. Returns full paths (relative to workspace) to all " +
        "matching items. Supports excluding paths using glob patterns.",
      inputSchema: SearchFilesJsonSchema as any, // Cast as any if needed
  
      // Minimal buildPrompt as execution logic is separate
      buildPrompt: (args: any, modelId: string) => {
          const parsed = SearchFilesArgsSchema.safeParse(args);
          if (!parsed.success) {
              throw new McpError(ErrorCode.InvalidParams, `Invalid arguments for search_filesystem: ${parsed.error}`);
          }
          return {
              systemInstructionText: "",
              userQueryText: "",
              useWebSearch: false,
              enableFunctionCalling: false
          };
      },
      // No 'execute' function here
  };

• src/tools/index.ts:56-56 (registration)

  Includes searchFilesTool in the allTools array, which is exported and used by the MCP server for tool listing and mapping.

  searchFilesTool,