search_files
Search for specific regex patterns within files in a specified directory using a read-only glob filter. Ideal for locating text matches in file systems.
Instructions
Search for a regex pattern within files in a specified directory (read-only).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file_pattern | No | Glob pattern to filter files (e.g., '*.ts'). Defaults to all files ('*'). | * |
| path | No | Relative path of the directory to search in. | . |
| regex | Yes | The regex pattern to search for. |
Implementation Reference
- src/handlers/search-files.ts:221-270 (handler)Main handler function that validates args, compiles regex, finds files with glob, searches content in parallel, collects matches with context lines and errors, returns JSON-structured response.export const handleSearchFilesFunc = async ( deps: SearchFilesDependencies, args: unknown, ): Promise<LocalMcpResponse> => { // Updated response type const { path: relativePath, regex: regexString, file_pattern: filePattern, } = parseAndValidateArgs(args); const searchRegex = compileSearchRegex(regexString); const allResults: SearchResultItem[] = []; try { const filesToSearch = await findFilesToSearch(deps, relativePath, filePattern); const searchPromises = filesToSearch.map((absoluteFilePath) => searchFileContent({ deps, absoluteFilePath, searchRegex }), ); const resultsPerFile = await Promise.all(searchPromises); // Flatten results (which now include potential errors) for (const fileResults of resultsPerFile) allResults.push(...fileResults); } catch (error: unknown) { // Errors from findFilesToSearch or Promise.all rejections (should be less likely now) if (error instanceof McpError) throw error; const errorMessage = error instanceof Error ? error.message : 'An unknown error occurred during file search.'; // Error logged via McpError // Include a general error if the whole process fails unexpectedly allResults.push({ type: 'error', file: 'general', error: errorMessage }); // Don't throw, return the collected results including the general error // throw new McpError(ErrorCode.InternalError, errorMessage); } // Return the structured data including matches and errors return { content: [ { type: 'text', text: JSON.stringify({ results: allResults }, undefined, 2), }, ], data: { results: allResults, }, }; };
- src/handlers/search-files.ts:30-47 (schema)Zod input schema defining parameters: path (directory), regex (pattern), file_pattern (glob filter).export const SearchFilesArgsSchema = z .object({ path: z .string() .optional() .default('.') .describe('Relative path of the directory to search in.'), regex: z .string() .min(1, { message: 'Regex pattern cannot be empty' }) .describe('The regex pattern to search for.'), file_pattern: z .string() .optional() .default('*') .describe("Glob pattern to filter files (e.g., '*.ts'). Defaults to all files ('*')."), }) .strict();
- src/handlers/search-files.ts:273-306 (registration)Tool definition object registering 'search_files' with name, description, input/output schemas, and handler wrapper that provides dependencies.export const searchFilesToolDefinition = { name: 'search_files', description: 'Search for a regex pattern within files in a specified directory (read-only). Returns matches and any errors encountered.', inputSchema: SearchFilesArgsSchema, // Define output schema outputSchema: z.object({ results: z.array( z.object({ type: z.enum(['match', 'error']), file: z.string(), line: z.number().int().optional(), match: z.string().optional(), context: z.array(z.string()).optional(), error: z.string().optional(), }), ), }), // Use the imported local McpResponse type handler: (args: unknown): Promise<LocalMcpResponse> => { const deps: SearchFilesDependencies = { readFile: async (_path, _options) => { const encoding = typeof _options === 'string' ? _options : (_options?.encoding ?? 'utf8'); return fsPromises.readFile(_path, { encoding }); }, glob: globFn, resolvePath: resolvePathUtil, PROJECT_ROOT: projectRootUtil, pathRelative: path.relative.bind(path), pathJoin: path.join.bind(path), }; return handleSearchFilesFunc(deps, args); }, };
- src/handlers/index.ts:48-91 (registration)Central registry aggregating all tool definitions, including searchFilesToolDefinition (line 59 in original file).export const allToolDefinitions: HandlerToolDefinition[] = [ listFilesToolDefinition, statItemsToolDefinition, readContentToolDefinition, writeContentToolDefinition, deleteItemsToolDefinition, createDirectoriesToolDefinition, chmodItemsToolDefinition, chownItemsToolDefinition, moveItemsToolDefinition, copyItemsToolDefinition, searchFilesToolDefinition, replaceContentToolDefinition, { name: 'apply_diff', description: 'Apply diffs to files', inputSchema: applyDiffInputSchema, handler: async (args: unknown): Promise<McpToolResponse> => { const validatedArgs = applyDiffInputSchema.parse(args); const result: ApplyDiffOutput = await handleApplyDiff(validatedArgs.changes, { readFile: async (path: string) => fs.promises.readFile(path, 'utf8'), writeFile: async (path: string, content: string) => fs.promises.writeFile(path, content, 'utf8'), path, projectRoot: process.cwd(), }); return { content: [ { type: 'text', text: JSON.stringify( { success: result.success, results: result.results, }, undefined, 2, ), }, ], }; }, }, ];
- src/handlers/index.ts:11-11 (registration)Import of the search_files tool definition for inclusion in the central registry.import { searchFilesToolDefinition } from './search-files.js';