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
`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,
      });
    });
  });
}

Grep MCP Server