search_filesystem
Search for files and directories in the workspace filesystem using a case-insensitive pattern. Recursively scans subdirectories, returns matching paths, and supports excluding specific paths with glob patterns.
Instructions
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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| excludePatterns | No | An array of glob patterns (e.g., 'node_modules', '*.log') to exclude from the search. | |
| path | Yes | The starting directory path for the search (relative to the workspace directory). | |
| pattern | Yes | The case-insensitive text pattern to search for in file/directory names. |
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,