Grep MCP Server

Instructions

Implementation Reference

• src/index.ts:165-233 (handler)

  The execution logic for the 'grep_search_intent' tool. Validates the target path, converts natural language 'intent' to regex using interpretSearchIntent helper, constructs safe grep arguments (recursive if dir, case-insens if specified, line nums, context, max results), spawns grep process, captures output, and returns formatted markdown content with results or errors.
  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 input schema for the tool parameters: intent (required string), target (required string), optional case_sensitive (bool, default false), max_results (number), show_context (bool, default false), context_lines (number, default 2). Defines validation and descriptions.
  { 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:154-234 (registration)

  Registration of the tool on the MCP server using server.tool(name, description, schema, handler), where name is 'grep_search_intent' and handler is inline.
  server.tool( "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 unique to this tool that maps plain English intents (e.g., 'emails', 'phone numbers', 'functions', 'TODO') to regex patterns via a lookup table, with partial matching and fallback to escaped literal search.
  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, '\\$&'); }