find_files_by_extension
Search directories recursively to locate files by specific extension, including subdirectories. Specify path, extension, depth, and results limit. Ideal for finding XML, JSON, or other file types efficiently.
Instructions
Recursively find all files with a specific extension. Searches through all subdirectories from the starting path. Extension matching is case-insensitive. Returns full paths to all matching files. Requires maxDepth (default 2) and maxResults (default 10) parameters. Perfect for finding all XML, JSON, or other file types in a directory structure. Only searches within allowed directories.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| excludePatterns | No | ||
| extension | Yes | File extension to search for (e.g., "xml", "json", "ts") | |
| maxDepth | Yes | Maximum directory depth to search. Must be a positive integer. Handler default: 2. | |
| maxResults | Yes | Maximum number of results to return. Must be a positive integer. Handler default: 10. | |
| path | Yes |
Implementation Reference
- src/handlers/utility-handlers.ts:68-87 (handler)Main handler function that executes the tool: parses input arguments using the schema, validates the starting path, calls the helper function findFilesByExtension, and returns the list of matching files or a no-match message.export async function handleFindFilesByExtension( args: unknown, allowedDirectories: string[], symlinksMap: Map<string, string>, noFollowSymlinks: boolean ) { const parsed = parseArgs(FindFilesByExtensionArgsSchema, args, 'find_files_by_extension'); const { path: startPath, extension, excludePatterns, maxDepth, maxResults } = parsed; const validPath = await validatePath(startPath, allowedDirectories, symlinksMap, noFollowSymlinks); const results = await findFilesByExtension( validPath, extension, excludePatterns, maxDepth, maxResults ); return { content: [{ type: "text", text: results.length > 0 ? results.join("\n") : "No matching files found" }], }; }
- TypeBox schema definition for the tool's input arguments, including path, extension, optional excludePatterns, maxDepth, and maxResults. Also exports the corresponding TypeScript type.export const FindFilesByExtensionArgsSchema = Type.Object({ path: Type.String(), extension: Type.String({ description: 'File extension to search for (e.g., "xml", "json", "ts")' }), excludePatterns: Type.Optional( Type.Array(Type.String(), { default: [] }) ), maxDepth: Type.Integer({ minimum: 1, description: 'Maximum directory depth to search. Must be a positive integer. Handler default: 2.' }), maxResults: Type.Integer({ minimum: 1, description: 'Maximum number of results to return. Must be a positive integer. Handler default: 10.' }) }); export type FindFilesByExtensionArgs = Static<typeof FindFilesByExtensionArgsSchema>;
- src/utils/file-utils.ts:92-157 (helper)Core utility function that recursively searches for files with the given extension starting from rootPath, respecting maxDepth, maxResults, and excludePatterns using minimatch.export async function findFilesByExtension( rootPath: string, extension: string, excludePatterns: string[] = [], maxDepth: number = 2, // Default depth maxResults: number = 10 // Default results ): Promise<ReadonlyArray<string>> { const results: string[] = []; // Normalize the extension (remove leading dot if present) let normalizedExtension = extension.toLowerCase(); if (normalizedExtension.startsWith('.')) { normalizedExtension = normalizedExtension.substring(1); } async function searchDirectory(currentPath: string, currentDepth: number) { // Stop if max depth is reached if (currentDepth >= maxDepth) { return; } // Stop if max results are reached if (results.length >= maxResults) { return; } const entries = await fsPromises.readdir(currentPath, { withFileTypes: true }); for (const entry of entries) { const fullPath = path.join(currentPath, entry.name); // Check if path matches any exclude pattern const relativePath = path.relative(rootPath, fullPath); const shouldExclude = excludePatterns.some(pattern => { const globPattern = pattern.includes('*') ? pattern : `**/${pattern}/**`; return minimatch(relativePath, globPattern, { dot: true }); }); if (shouldExclude) { continue; } if (entry.isFile()) { // Check if file has the requested extension const fileExtension = path.extname(entry.name).toLowerCase().substring(1); if (fileExtension === normalizedExtension) { if (results.length < maxResults) { results.push(fullPath); } // Check again if max results reached after adding if (results.length >= maxResults) { return; // Stop searching this branch } } } else if (entry.isDirectory()) { // Recursively search subdirectories // Check results length before recursing if (results.length < maxResults) { await searchDirectory(fullPath, currentDepth + 1); } } } } await searchDirectory(rootPath, 0); // Start search at depth 0 return results; }
- index.ts:238-244 (registration)Registration of the tool handler in the toolHandlers object, mapping 'find_files_by_extension' to the handleFindFilesByExtension function with server context parameters.find_files_by_extension: (a: unknown) => handleFindFilesByExtension( a, allowedDirectories, symlinksMap, noFollowSymlinks, ),
- index.ts:310-310 (registration)Tool metadata registration in the allTools array, defining the name and description used when adding the tool to the MCP server.{ name: "find_files_by_extension", description: "Find files by extension" },