search_code

Instructions

Implementation Reference

• index.ts:340-362 (handler)

  MCP CallTool handler for search_code: validates input parameters using Zod schema and delegates to ripgrepSearch helper function.

  case 'search_code': {
    const schema = z.object({
      pattern: z.string(),
      path: z.string().optional(),
      filePattern: z.string().optional(),
      caseInsensitive: z.boolean().optional().default(true),
      contextLines: z.number().optional().default(2),
      maxResults: z.number().optional().default(DEFAULT_MAX_RESULTS),
      page: z.number().optional().default(1),
      literalString: z.boolean().optional().default(false),
      wordBoundary: z.boolean().optional().default(false)
    });
    const options = schema.parse(args);
    
    const result = await ripgrepSearch(options, getAllowedDirectories());
    
    return {
      content: [{
        type: 'text',
        text: JSON.stringify(result, null, 2)
      }]
    };
  }

• index.ts:97-168 (schema)

  Tool definition for 'search_code' including comprehensive input schema with descriptions, defaults, and examples for ripgrep-powered code search.

    {
      name: 'search_code',
      description: `Search for code patterns using ripgrep (very fast). Supports regex patterns and advanced filtering.
  
  PATTERN EXAMPLES:
    - Exact text: "functionName"
    - Multiple options: "\\\\b(class|struct|record|interface|enum)\\\\s+TypeName\\\\b"
      (finds: class TypeName, record TypeName, interface TypeName, etc.)
    - Regex: "async.*Promise<.*>" (finds async functions returning Promise)
    - Any declaration: "\\\\b(public|private|protected)\\\\s+\\\\w+\\\\s+methodName"
    
  COMMON USE CASES:
    - Find type declaration: "\\\\b(class|struct|interface|record|enum)\\\\s+TypeName\\\\b"
    - Find method: "\\\\b(public|private|protected|internal).*\\\\s+methodName\\\\s*\\\\("
    - Find property: "\\\\bpublic\\\\s+\\\\w+\\\\s+propertyName\\\\s*\\\\{"
    - Find async methods: "async.*Task<"
    - Find implementations: ":\\\\s*IInterfaceName\\\\b"
  
  TIPS:
    - Use \\\\b for word boundaries
    - Use \\\\s+ for whitespace
    - Combine alternatives with (opt1|opt2|opt3)
    - Escape special chars: \\\\( \\\\) \\\\{ \\\\}`,
      inputSchema: {
        type: 'object',
        properties: {
          pattern: {
            type: 'string',
            description: 'Regex pattern to search. For multiple alternatives use: (class|struct|interface) to match any'
          },
          path: {
            type: 'string',
            description: "Limit search to specific directory (e.g., 'src/components'). Omit to search entire workspace."
          },
          filePattern: {
            type: 'string',
            description: "File glob pattern (ripgrep -g flag). Examples: '*.js', '*.{ts,tsx}', '!*test*' (exclude). Can specify multiple patterns separated by comma."
          },
          caseInsensitive: {
            type: 'boolean',
            description: 'Ignore case in search (ripgrep -i). Default: true for LLM-friendly searching',
            default: true
          },
          contextLines: {
            type: 'number',
            description: 'Lines of context before/after match (ripgrep -C)',
            default: 2
          },
          maxResults: {
            type: 'number',
            description: `Maximum number of results to return (per page). Default: ${DEFAULT_MAX_RESULTS}. Configure via MCP_MAX_SEARCH_RESULTS env var.`,
            default: DEFAULT_MAX_RESULTS
          },
          page: {
            type: 'number',
            description: 'Page number for paginated results (1-based). Use to get more results beyond maxResults.',
            default: 1
          },
          literalString: {
            type: 'boolean',
            description: 'Treat pattern as literal string, not regex (ripgrep -F)',
            default: false
          },
          wordBoundary: {
            type: 'boolean',
            description: 'Match whole words only (ripgrep -w)',
            default: false
          }
        },
        required: ['pattern']
      }
    },

• ripgrep.ts:58-166 (helper)

  Core helper function implementing the search_code logic: constructs and executes ripgrep command, parses output, handles pagination and suggestions.

  export async function ripgrepSearch(
    options: RipgrepSearchOptions,
    allowedDirs: string[]
  ): Promise<RipgrepResult> {
    const startTime = Date.now();
    
    const args: string[] = ['--json', '--no-config'];
    
    // Context lines
    if (options.contextLines !== undefined && options.contextLines > 0) {
      args.push('-C', options.contextLines.toString());
    }
    
    // Case sensitivity
    if (options.caseInsensitive) {
      args.push('-i');
    }
    
    // Literal string (not regex)
    if (options.literalString) {
      args.push('-F');
    }
    
    // Word boundary
    if (options.wordBoundary) {
      args.push('-w');
    }
    
    // File pattern (glob)
    if (options.filePattern) {
      // Support multiple patterns separated by comma
      const patterns = options.filePattern.split(',').map(p => p.trim());
      patterns.forEach(pattern => {
        args.push('-g', pattern);
      });
    }
    
    // Note: We don't use ripgrep's -m flag for pagination
    // Instead, we collect ALL matches and paginate in memory
    // This allows proper pagination across all results
    
    // Pattern
    args.push(options.pattern);
    
    // Search paths (validated)
    let searchPaths: string[];
    if (options.path) {
      try {
        const validated = await validatePath(path.join(allowedDirs[0], options.path));
        searchPaths = [validated];
      } catch (error) {
        throw new Error(`Invalid search path: ${error instanceof Error ? error.message : String(error)}`);
      }
    } else {
      searchPaths = allowedDirs;
    }
    
    args.push(...searchPaths);
    
    const result = await executeRipgrep(args, options.pattern, searchPaths);
    result.summary.searchTimeMs = Date.now() - startTime;
    
    // Apply pagination
    const page = options.page || 1;
    const pageSize = options.maxResults || 100;
    const totalMatches = result.matches.length;
    const startIdx = (page - 1) * pageSize;
    const endIdx = startIdx + pageSize;
    
    // Paginate matches
    const paginatedMatches = result.matches.slice(startIdx, endIdx);
    const totalPages = Math.ceil(totalMatches / pageSize);
    
    result.matches = paginatedMatches;
    result.pagination = {
      page,
      pageSize,
      totalPages,
      hasMore: endIdx < totalMatches
    };
    
    // Update summary to reflect total (not paginated)
    result.summary.totalMatches = totalMatches;
    
    // Add helpful suggestions
    if (totalMatches === 0) {
      result.suggestions = [
        'No matches found. Try:',
        '- Using case-insensitive search (caseInsensitive: true)',
        '- Simplifying the pattern',
        '- Checking if the file pattern is correct'
      ];
    } else if (result.pagination.hasMore) {
      result.suggestions = [
        `Showing page ${page} of ${totalPages} (${paginatedMatches.length} of ${totalMatches} total matches)`,
        `To see more results, request page ${page + 1}`,
        'Or narrow your search with:',
        '- More specific pattern',
        '- File pattern filter (filePattern)',
        '- Path restriction (path parameter)'
      ];
    } else if (page > 1) {
      result.suggestions = [
        `Showing final page ${page} of ${totalPages} (${paginatedMatches.length} matches on this page, ${totalMatches} total)`
      ];
    }
    
    return result;
  }

• ripgrep.ts:9-19 (schema)

  TypeScript interface defining RipgrepSearchOptions, mirroring the input schema for type safety in the helper functions.

  export interface RipgrepSearchOptions {
    pattern: string;
    path?: string;
    filePattern?: string;        // -g flag
    caseInsensitive?: boolean;   // -i flag
    contextLines?: number;       // -C flag
    maxResults?: number;         // Results per page
    page?: number;               // Page number (1-based)
    literalString?: boolean;     // -F flag
    wordBoundary?: boolean;      // -w flag
  }

• index.ts:259-262 (registration)

  Registration of all tools including search_code via the ListToolsRequestSchema handler that returns the static tools array.

  // Tool handlers
  server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools
  }));