find
Search for files and directories using pattern matching, filtering by depth, and excluding ignored files to locate specific items in a directory.
Instructions
Find files and directories with pattern matching and filtering
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Directory path to search (required) | |
| pattern | No | File pattern to match (*.js,**/*.test.ts,!**/node_modules/**). Use ! to exclude, comma-separated | |
| depth | No | Maximum depth to recurse (default: 0 = unlimited) | |
| includeIgnored | No | Include files ignored by .gitignore (default: false) |
Implementation Reference
- servers/file-mcp/tools/find.ts:44-77 (handler)The execute method of the FindTool class that handles tool invocation: validates input with Zod schema, uses DirectoryUtils.findFiles for the core logic, formats results as newline-separated relative paths, and handles errors.
async execute(args: any): Promise<any> { try { // Validate and parse input using Zod schema const validatedArgs = FindToolInputSchema.parse(args); const { path: targetPath, depth, includeIgnored, pattern: filterPath } = validatedArgs; const basePath = targetPath || "."; // Use DirectoryUtils for file finding with all the same features const options: any = { includeIgnored, includeFiles: true, includeDirectories: true, }; if (depth > 0) { options.maxDepth = depth; } const results = await DirectoryUtils.findFiles(basePath, filterPath, options); // Format results as relative paths (maintaining original behavior) const relativePaths = results.map((result) => { const path = result.relativePath; return result.isDirectory ? `${path}/` : path; }); return ResultFormatter.createResponse(relativePaths.join("\n")); } catch (error) { // Handle Zod validation errors if (error instanceof Error && error.name === "ZodError") { throw ToolError.createValidationError("input", args, `Invalid input: ${error.message}`); } throw ToolError.wrapError("Find operation", error); } } - Zod input schema (FindToolInputSchema) defining parameters for the find tool: path (required), optional pattern, depth, and includeIgnored flag.
// Find tool input schema export const FindToolInputSchema = z.object({ path: FilePathSchema, pattern: z.string().optional(), depth: z.number().int().min(0).default(0), includeIgnored: BooleanFlagSchema, }); - servers/file-mcp/index.ts:90-99 (registration)Tool registration in getTools() method: includes FindTool.getDefinition() in the list of available tools returned by the MCP server.
protected getTools(): Tool[] { return [ this.readTool.getDefinition(), this.findTool.getDefinition(), this.grepTool.getDefinition(), this.writeTool.getDefinition(), this.editTool.getDefinition(), this.moveTool.getDefinition(), this.copyTool.getDefinition(), ]; - servers/file-mcp/index.ts:112-113 (registration)Tool dispatch registration in handleToolCall switch statement: routes 'find' calls to this.findTool.execute().
case "find": return await this.findTool.execute(args); - Supporting utility DirectoryUtils.findFiles: parses patterns, traverses directory with filtering, gitignore respect, and depth limits, returns matching file/directory results used by the find handler.
static async findFiles( basePath: string, filterPatterns?: string, options: Omit<TraversalOptions, "includePatterns" | "excludePatterns"> = {} ): Promise<TraversalResult[]> { const { include, exclude } = DirectoryUtils.parseFilterPatterns(filterPatterns); const results: TraversalResult[] = []; for await (const entry of DirectoryUtils.traverseDirectory(basePath, { ...options, includePatterns: include, excludePatterns: exclude, includeFiles: true, includeDirectories: options.includeDirectories !== false, })) { results.push(entry); } return results; }