grep_regex
Search files or directories using regex patterns with options for case sensitivity, whole words, context display, file extensions, and result limits. Invert matches to exclude patterns.
Instructions
Search using a direct regex pattern
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| case_sensitive | No | Whether the search should be case sensitive | |
| context_lines | No | Number of context lines to show before/after matches | |
| file_extensions | No | Only search files with these extensions (e.g., ['js', 'ts']) | |
| invert_match | No | Show lines that don't match the pattern | |
| max_results | No | Maximum number of results to return | |
| pattern | Yes | Regular expression pattern to search for | |
| show_context | No | Show surrounding lines for context | |
| target | Yes | File or directory path to search in | |
| whole_words | No | Match whole words only |
Implementation Reference
- src/index.ts:251-335 (handler)The asynchronous handler function for the 'grep_regex' tool. It validates the target path using validatePath, constructs grep command arguments based on parameters like pattern, case sensitivity, whole words, invert match, etc., executes via executeGrep, and formats the results.async ({ pattern, target, case_sensitive, whole_words, invert_match, max_results, show_context, context_lines, file_extensions }) => { // Validate target path const pathValidation = validatePath(target); if (!pathValidation.isValid) { return { content: [ { type: "text", text: `Error: ${pathValidation.error}`, }, ], }; } const args = ['grep']; // Use extended regex args.push('-E'); args.push(pattern); // Add case sensitivity option if (!case_sensitive) { args.push('-i'); } // Add whole words option if (whole_words) { args.push('-w'); } // Add invert match option if (invert_match) { args.push('-v'); } // Add recursive search if target is directory if (pathValidation.isDirectory) { args.push('-r'); } // Add line numbers args.push('-n'); // Add context if requested if (show_context && context_lines > 0) { args.push(`-C${context_lines}`); } // Add max results limit if (max_results) { args.push('-m', max_results.toString()); } // Add file extension filters if (file_extensions && file_extensions.length > 0 && pathValidation.isDirectory) { file_extensions.forEach(ext => { args.push('--include', `*.${ext}`); }); } // Add target path args.push(target); try { const result = await executeGrep(args); return { content: [ { type: "text", text: `Pattern: ${pattern}\nExit Code: ${result.exitCode}\n\nResults:\n${result.stdout}${result.stderr ? `\n\nErrors:\n${result.stderr}` : ''}`, }, ], }; } catch (error) { return { content: [ { type: "text", text: `Error executing grep: ${error instanceof Error ? error.message : String(error)}`, }, ], }; } }
- src/index.ts:240-250 (schema)Zod input schema for the 'grep_regex' tool, defining parameters such as pattern (required regex), target path, case_sensitive, whole_words, invert_match, max_results, show_context, context_lines, and file_extensions.{ pattern: z.string().describe("Regular expression pattern to search for"), target: z.string().describe("File or directory path to search in"), case_sensitive: z.boolean().optional().default(false).describe("Whether the search should be case sensitive"), whole_words: z.boolean().optional().default(false).describe("Match whole words only"), invert_match: z.boolean().optional().default(false).describe("Show lines that don't match the pattern"), max_results: z.number().optional().describe("Maximum number of results to return"), show_context: z.boolean().optional().default(false).describe("Show surrounding lines for context"), context_lines: z.number().optional().default(2).describe("Number of context lines to show before/after matches"), file_extensions: z.array(z.string()).optional().describe("Only search files with these extensions (e.g., ['js', 'ts'])"), },
- src/index.ts:237-336 (registration)The server.tool() registration call for 'grep_regex', including name, description, input schema, and handler function.server.tool( "grep_regex", "Search using a direct regex pattern", { pattern: z.string().describe("Regular expression pattern to search for"), target: z.string().describe("File or directory path to search in"), case_sensitive: z.boolean().optional().default(false).describe("Whether the search should be case sensitive"), whole_words: z.boolean().optional().default(false).describe("Match whole words only"), invert_match: z.boolean().optional().default(false).describe("Show lines that don't match the pattern"), max_results: z.number().optional().describe("Maximum number of results to return"), show_context: z.boolean().optional().default(false).describe("Show surrounding lines for context"), context_lines: z.number().optional().default(2).describe("Number of context lines to show before/after matches"), file_extensions: z.array(z.string()).optional().describe("Only search files with these extensions (e.g., ['js', 'ts'])"), }, async ({ pattern, target, case_sensitive, whole_words, invert_match, max_results, show_context, context_lines, file_extensions }) => { // Validate target path const pathValidation = validatePath(target); if (!pathValidation.isValid) { return { content: [ { type: "text", text: `Error: ${pathValidation.error}`, }, ], }; } const args = ['grep']; // Use extended regex args.push('-E'); args.push(pattern); // Add case sensitivity option if (!case_sensitive) { args.push('-i'); } // Add whole words option if (whole_words) { args.push('-w'); } // Add invert match option if (invert_match) { args.push('-v'); } // Add recursive search if target is directory if (pathValidation.isDirectory) { args.push('-r'); } // Add line numbers args.push('-n'); // Add context if requested if (show_context && context_lines > 0) { args.push(`-C${context_lines}`); } // Add max results limit if (max_results) { args.push('-m', max_results.toString()); } // Add file extension filters if (file_extensions && file_extensions.length > 0 && pathValidation.isDirectory) { file_extensions.forEach(ext => { args.push('--include', `*.${ext}`); }); } // Add target path args.push(target); try { const result = await executeGrep(args); return { content: [ { type: "text", text: `Pattern: ${pattern}\nExit Code: ${result.exitCode}\n\nResults:\n${result.stdout}${result.stderr ? `\n\nErrors:\n${result.stderr}` : ''}`, }, ], }; } catch (error) { return { content: [ { type: "text", text: `Error executing grep: ${error instanceof Error ? error.message : String(error)}`, }, ], }; } } );
- src/index.ts:21-60 (helper)executeGrep helper: Safely spawns grep process with given arguments, captures stdout/stderr/exit code, handles errors.async function executeGrep(args: string[]): Promise<{ stdout: string; stderr: string; exitCode: number }> { return new Promise((resolve) => { // Ensure we're only calling grep with safe arguments if (!args.includes('grep')) { args.unshift('grep'); } const child = spawn('grep', args.slice(1), { stdio: ['pipe', 'pipe', 'pipe'], shell: false, }); let stdout = ''; let stderr = ''; child.stdout.on('data', (data) => { stdout += data.toString(); }); child.stderr.on('data', (data) => { stderr += data.toString(); }); child.on('close', (code) => { resolve({ stdout, stderr, exitCode: code || 0, }); }); child.on('error', (error) => { resolve({ stdout: '', stderr: error.message, exitCode: 1, }); }); }); }
- src/index.ts:63-74 (helper)validatePath helper: Checks if path exists, resolves it, determines if directory or file, used for target validation.function validatePath(path: string): { isValid: boolean; isDirectory: boolean; error?: string } { try { const resolvedPath = resolve(path); if (!existsSync(resolvedPath)) { return { isValid: false, isDirectory: false, error: `Path does not exist: ${path}` }; } const stats = statSync(resolvedPath); return { isValid: true, isDirectory: stats.isDirectory() }; } catch (error) { return { isValid: false, isDirectory: false, error: `Invalid path: ${path}` }; } }