Large File MCP Server

Instructions

Implementation Reference

• src/fileHandler.ts:283-368 (handler)

  Core handler implementation for searching large files. Streams lines using readline, supports regex/literal patterns, case sensitivity, context lines, line range limits, and max results. Returns structured SearchResult array.

  static async search(
    filePath: string,
    pattern: string,
    options: SearchOptions = {}
  ): Promise<SearchResult[]> {
    await this.verifyFile(filePath);
  
    const results: SearchResult[] = [];
    const maxResults = options.maxResults || 100;
    const contextBefore = options.contextBefore || 2;
    const contextAfter = options.contextAfter || 2;
  
    const regex = options.regex
      ? new RegExp(pattern, options.caseSensitive ? 'g' : 'gi')
      : new RegExp(
          pattern.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'),
          options.caseSensitive ? 'g' : 'gi'
        );
  
    return new Promise((resolve, reject) => {
      let lineNumber = 0;
      const lineBuffer: string[] = [];
      const stream = fs.createReadStream(filePath);
      const rl = readline.createInterface({
        input: stream,
        crlfDelay: Infinity,
      });
  
      rl.on('line', (line) => {
        lineNumber++;
        lineBuffer.push(line);
  
        // Keep buffer for context
        if (lineBuffer.length > contextBefore + contextAfter + 1) {
          lineBuffer.shift();
        }
  
        // Check if within search range
        if (options.startLine && lineNumber < options.startLine) return;
        if (options.endLine && lineNumber > options.endLine) {
          rl.close();
          return;
        }
  
        // Search for pattern
        const matches = Array.from(line.matchAll(regex));
        if (matches.length > 0) {
          const matchPositions = matches.map(m => ({
            start: m.index!,
            end: m.index! + m[0].length,
          }));
  
          const bufferIndex = lineBuffer.length - 1;
          const before = lineBuffer.slice(
            Math.max(0, bufferIndex - contextBefore),
            bufferIndex
          );
  
          results.push({
            lineNumber,
            lineContent: line,
            matchPositions,
            contextBefore: before,
            contextAfter: [], // Will be filled after
            chunkIndex: Math.floor((lineNumber - 1) / 500),
          });
  
          if (results.length >= maxResults) {
            rl.close();
          }
        }
  
        // Fill context after for previous results
        if (results.length > 0) {
          const lastResult = results[results.length - 1];
          const linesSince = lineNumber - lastResult.lineNumber;
          if (linesSince > 0 && linesSince <= contextAfter) {
            lastResult.contextAfter.push(line);
          }
        }
      });
  
      rl.on('close', () => resolve(results));
      rl.on('error', reject);
    });
  }

• src/server.ts:116-162 (registration)

  Tool registration in getTools() method, defining name, description, and input schema for listTools MCP protocol.

  {
    name: 'search_in_large_file',
    description: 'Search for a pattern in a large file with context lines. Supports regex and case-sensitive search.',
    inputSchema: {
      type: 'object',
      properties: {
        filePath: {
          type: 'string',
          description: 'Absolute path to the file',
        },
        pattern: {
          type: 'string',
          description: 'Search pattern (supports regex if regex=true)',
        },
        caseSensitive: {
          type: 'boolean',
          description: 'Case sensitive search (default: false)',
        },
        regex: {
          type: 'boolean',
          description: 'Use regex pattern (default: false)',
        },
        maxResults: {
          type: 'number',
          description: 'Maximum number of results (default: 100)',
        },
        contextBefore: {
          type: 'number',
          description: 'Number of context lines before match (default: 2)',
        },
        contextAfter: {
          type: 'number',
          description: 'Number of context lines after match (default: 2)',
        },
        startLine: {
          type: 'number',
          description: 'Start searching from line number (optional)',
        },
        endLine: {
          type: 'number',
          description: 'End searching at line number (optional)',
        },
      },
      required: ['filePath', 'pattern'],
    },
  },
  {

• src/server.ts:119-160 (schema)

  JSON Schema defining input parameters and validation for the search_in_large_file tool.

  inputSchema: {
    type: 'object',
    properties: {
      filePath: {
        type: 'string',
        description: 'Absolute path to the file',
      },
      pattern: {
        type: 'string',
        description: 'Search pattern (supports regex if regex=true)',
      },
      caseSensitive: {
        type: 'boolean',
        description: 'Case sensitive search (default: false)',
      },
      regex: {
        type: 'boolean',
        description: 'Use regex pattern (default: false)',
      },
      maxResults: {
        type: 'number',
        description: 'Maximum number of results (default: 100)',
      },
      contextBefore: {
        type: 'number',
        description: 'Number of context lines before match (default: 2)',
      },
      contextAfter: {
        type: 'number',
        description: 'Number of context lines after match (default: 2)',
      },
      startLine: {
        type: 'number',
        description: 'Start searching from line number (optional)',
      },
      endLine: {
        type: 'number',
        description: 'End searching at line number (optional)',
      },
    },
    required: ['filePath', 'pattern'],
  },

• src/server.ts:297-324 (handler)

  MCP server tool handler wrapper that extracts arguments, calls FileHandler.search, and formats JSON response for MCP protocol.

  private async handleSearch(
    args: Record<string, unknown>
  ): Promise<{ content: Array<{ type: string; text: string }> }> {
    const filePath = args.filePath as string;
    const pattern = args.pattern as string;
  
    const results: SearchResult[] = await FileHandler.search(filePath, pattern, {
      caseSensitive: args.caseSensitive as boolean,
      regex: args.regex as boolean,
      maxResults: (args.maxResults as number) || 100,
      contextBefore: (args.contextBefore as number) || 2,
      contextAfter: (args.contextAfter as number) || 2,
      startLine: args.startLine as number | undefined,
      endLine: args.endLine as number | undefined,
    });
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            totalResults: results.length,
            results,
          }, null, 2),
        },
      ],
    };
  }

• src/types.ts:68-98 (schema)

  TypeScript interfaces defining SearchResult (output structure) and SearchOptions (input options) used by the search handler.

  export interface SearchResult {
    /** Line number (1-indexed) */
    lineNumber: number;
    /** Line content */
    lineContent: string;
    /** Match positions in line */
    matchPositions: Array<{ start: number; end: number }>;
    /** Context lines before */
    contextBefore: string[];
    /** Context lines after */
    contextAfter: string[];
    /** Chunk index containing this result */
    chunkIndex: number;
  }
  
  export interface SearchOptions {
    /** Case sensitive search */
    caseSensitive?: boolean;
    /** Regular expression search */
    regex?: boolean;
    /** Maximum results to return */
    maxResults?: number;
    /** Number of context lines before match */
    contextBefore?: number;
    /** Number of context lines after match */
    contextAfter?: number;
    /** Start searching from line */
    startLine?: number;
    /** End searching at line */
    endLine?: number;
  }