grep_search_intent
Search files using plain English descriptions like 'email addresses' or 'TODO comments' to find patterns without writing complex regex.
Instructions
Search for patterns using plain English descriptions (e.g., 'email addresses', 'phone numbers', 'TODO comments')
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| intent | Yes | Plain English description of what to search for | |
| target | Yes | File or directory path to search in | |
| case_sensitive | No | Whether the search should be case sensitive | |
| max_results | No | Maximum number of results to return | |
| show_context | No | Show surrounding lines for context | |
| context_lines | No | Number of context lines to show before/after matches |
Implementation Reference
- src/index.ts:165-233 (handler)The main execution logic for the 'grep_search_intent' tool. Validates the input path, converts the plain English intent to a regex pattern using interpretSearchIntent, constructs the appropriate grep command arguments (including flags for regex, case-insensitivity, recursion, line numbers, context, etc.), executes the command via executeGrep, and returns the formatted results or error.
async ({ intent, target, case_sensitive, max_results, show_context, context_lines }) => { // Validate target path const pathValidation = validatePath(target); if (!pathValidation.isValid) { return { content: [ { type: "text", text: `Error: ${pathValidation.error}`, }, ], }; } const args = ['grep']; // Convert intent to regex pattern const pattern = interpretSearchIntent(intent); args.push('-E'); // Use extended regex args.push(pattern); // Add case sensitivity option if (!case_sensitive) { args.push('-i'); } // 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 target path args.push(target); try { const result = await executeGrep(args); return { content: [ { type: "text", text: `Search Intent: "${intent}"\nPattern Used: ${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:157-164 (schema)Zod-based input schema defining parameters for the tool: intent (string), target (path), case_sensitive (bool), max_results (number), show_context (bool), context_lines (number).
{ intent: z.string().describe("Plain English description of what 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"), 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"), }, - src/index.ts:155-234 (registration)Registration of the 'grep_search_intent' tool on the MCP server, including name, description, input schema, and inline handler function.
"grep_search_intent", "Search for patterns using plain English descriptions (e.g., 'email addresses', 'phone numbers', 'TODO comments')", { intent: z.string().describe("Plain English description of what 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"), 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"), }, async ({ intent, target, case_sensitive, max_results, show_context, context_lines }) => { // Validate target path const pathValidation = validatePath(target); if (!pathValidation.isValid) { return { content: [ { type: "text", text: `Error: ${pathValidation.error}`, }, ], }; } const args = ['grep']; // Convert intent to regex pattern const pattern = interpretSearchIntent(intent); args.push('-E'); // Use extended regex args.push(pattern); // Add case sensitivity option if (!case_sensitive) { args.push('-i'); } // 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 target path args.push(target); try { const result = await executeGrep(args); return { content: [ { type: "text", text: `Search Intent: "${intent}"\nPattern Used: ${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:77-151 (helper)Core helper function specific to this tool that interprets natural language search intents (e.g., 'email addresses', 'phone numbers', 'TODOs') into corresponding regex patterns for grep.
function interpretSearchIntent(intent: string): string { const lowerIntent = intent.toLowerCase().trim(); // Common search patterns const patterns: Record<string, string> = { // Email patterns 'email': '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}', 'email address': '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}', 'emails': '[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}', // URL patterns 'url': 'https?://[^\\s]+', 'urls': 'https?://[^\\s]+', 'website': 'https?://[^\\s]+', 'link': 'https?://[^\\s]+', 'links': 'https?://[^\\s]+', // IP addresses 'ip address': '\\b(?:[0-9]{1,3}\\.){3}[0-9]{1,3}\\b', 'ip addresses': '\\b(?:[0-9]{1,3}\\.){3}[0-9]{1,3}\\b', 'ip': '\\b(?:[0-9]{1,3}\\.){3}[0-9]{1,3}\\b', // Phone numbers 'phone number': '\\b\\d{3}[-.]?\\d{3}[-.]?\\d{4}\\b', 'phone numbers': '\\b\\d{3}[-.]?\\d{3}[-.]?\\d{4}\\b', 'phone': '\\b\\d{3}[-.]?\\d{3}[-.]?\\d{4}\\b', // Dates 'date': '\\b\\d{1,2}[/-]\\d{1,2}[/-]\\d{2,4}\\b', 'dates': '\\b\\d{1,2}[/-]\\d{1,2}[/-]\\d{2,4}\\b', // Numbers 'number': '\\b\\d+\\b', 'numbers': '\\b\\d+\\b', 'integer': '\\b\\d+\\b', 'integers': '\\b\\d+\\b', // Common code patterns 'function': '\\bfunction\\s+\\w+\\s*\\(', 'functions': '\\bfunction\\s+\\w+\\s*\\(', 'class': '\\bclass\\s+\\w+', 'classes': '\\bclass\\s+\\w+', 'import': '^\\s*import\\b', 'imports': '^\\s*import\\b', 'export': '^\\s*export\\b', 'exports': '^\\s*export\\b', // Common file types 'todo': '\\b(TODO|FIXME|HACK|XXX)\\b', 'todos': '\\b(TODO|FIXME|HACK|XXX)\\b', 'comment': '^\\s*(/\\*|//|#)', 'comments': '^\\s*(/\\*|//|#)', // Error patterns 'error': '\\b(error|Error|ERROR)\\b', 'errors': '\\b(error|Error|ERROR)\\b', 'warning': '\\b(warning|Warning|WARNING)\\b', 'warnings': '\\b(warning|Warning|WARNING)\\b', }; // Check for exact matches first if (patterns[lowerIntent]) { return patterns[lowerIntent]; } // Check for partial matches for (const [key, pattern] of Object.entries(patterns)) { if (lowerIntent.includes(key)) { return pattern; } } // If no pattern matches, treat as literal string search (escaped for regex) return intent.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); } - src/index.ts:21-60 (helper)Shared utility function to safely execute grep commands via child_process.spawn, capturing stdout, stderr, and exit code.
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, }); }); }); }