search_files
Search for files matching specific patterns within a directory path to locate documents, code, or data files efficiently.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| pattern | Yes | ||
| excludePatterns | No |
Implementation Reference
- src/tools/file-tools.ts:144-172 (registration)Registration function for the 'search_files' tool. Defines the Zod input schema (path, pattern, excludePatterns) and the handler function that validates the search path, calls the optimized search helper, and returns matched files as text content with metadata.function registerSearchFiles(server: McpServer): void { server.tool("search_files", { path: z.string().min(1, "Search root path is required"), pattern: z.string().min(1, "Glob pattern is required"), excludePatterns: z.array(z.string()).optional().default([]) }, async ({ path: searchPath, pattern, excludePatterns }) => { return wrapToolExecution(async () => { const validatedPath = await validatePathExists(searchPath); const matches = await searchFilesOptimized(validatedPath, pattern, excludePatterns); return { content: [{ type: "text" as const, text: matches.length > 0 ? matches.join("\n") : "No files found matching pattern" }], metadata: { count: matches.length, pattern } }; }, { errorCode: ERROR_CODES.FILE_OPERATION, context: "Failed to search files" }); } ); }
- src/tools/file-tools.ts:177-209 (helper)Helper function implementing the core file search logic using recursive directory traversal and minimatch for glob pattern matching, with support for exclude patterns.async function searchFilesOptimized( searchPath: string, pattern: string, excludePatterns: string[] ): Promise<string[]> { const matches: string[] = []; async function searchDir(currentPath: string, baseRelative: string = ""): Promise<void> { const entries = await readdir(currentPath, { withFileTypes: true }); for (const entry of entries) { const relativePath = path.join(baseRelative, entry.name); const fullPath = path.join(currentPath, entry.name); // Check if matches pattern if (minimatch(relativePath, pattern, { dot: true })) { const isExcluded = excludePatterns.some(excl => minimatch(relativePath, excl, { dot: true }) ); if (!isExcluded) { matches.push(relativePath); } } if (entry.isDirectory()) { await searchDir(fullPath, relativePath); } } } await searchDir(searchPath); return matches; }
- src/tools/file-tools.ts:19-24 (registration)Top-level registration function for all file-related tools, including a call to registerSearchFiles.export function registerFileTools(server: McpServer): void { registerReadFile(server); registerWriteFile(server); registerListDirectory(server); registerSearchFiles(server); }
- src/index.ts:65-65 (registration)Invocation of registerFileTools in the main server initialization, which indirectly registers the search_files tool.registerFileTools(server);
- src/tools/file-tools.ts:151-170 (handler)The inline async handler function passed to server.tool for executing the search_files logic, including error wrapping, path validation, search execution, and result formatting.async ({ path: searchPath, pattern, excludePatterns }) => { return wrapToolExecution(async () => { const validatedPath = await validatePathExists(searchPath); const matches = await searchFilesOptimized(validatedPath, pattern, excludePatterns); return { content: [{ type: "text" as const, text: matches.length > 0 ? matches.join("\n") : "No files found matching pattern" }], metadata: { count: matches.length, pattern } }; }, { errorCode: ERROR_CODES.FILE_OPERATION, context: "Failed to search files" }); }