search_files
Search for files matching specific patterns within a directory path to locate documents, code, or project resources.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| pattern | Yes | ||
| excludePatterns | No |
Implementation Reference
- src/tools/file-tools.ts:151-170 (handler)The handler function for the 'search_files' tool. It validates the input path, calls the searchFilesOptimized helper to find matching files, and returns the list of matches with metadata.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:146-150 (schema)Zod input schema defining parameters: path (required string), pattern (required string), excludePatterns (optional array of strings, defaults to empty).{ 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([]) },
- src/tools/file-tools.ts:144-172 (registration)The registerSearchFiles function registers the 'search_files' tool on the MCP server using server.tool(), providing schema and handler. Called from registerFileTools.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)Optimized recursive search function using minimatch for glob patterns. Collects relative paths of matching files, excluding those matching excludePatterns.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/index.ts:65-65 (registration)Calls registerFileTools(server) which includes registration of search_files among file tools.registerFileTools(server);