Large File MCP Server

Instructions

Implementation Reference

• src/fileHandler.ts:171-204 (handler)

  The primary handler function `readChunk` that implements the core tool logic: verifies the file exists, computes metadata and optimal chunk size based on file type, calculates start/end lines with overlap, reads the line range, formats content with optional line numbers, and returns a structured `FileChunk`.

  static async readChunk(
    filePath: string,
    chunkIndex: number,
    options: ChunkOptions = {}
  ): Promise<FileChunk> {
    await this.verifyFile(filePath);
  
    const metadata = await this.getMetadata(filePath);
    const linesPerChunk = options.linesPerChunk ||
      this.getOptimalChunkSize(metadata.fileType, metadata.totalLines);
    const overlapLines = options.overlapLines || 10;
  
    const startLine = Math.max(1, chunkIndex * linesPerChunk - overlapLines + 1);
    const endLine = Math.min(metadata.totalLines, (chunkIndex + 1) * linesPerChunk);
  
    const lines = await this.readLines(filePath, startLine, endLine);
    const content = options.includeLineNumbers
      ? lines.map((line, idx) => `${startLine + idx}: ${line}`).join('\n')
      : lines.join('\n');
  
    const totalChunks = Math.ceil(metadata.totalLines / linesPerChunk);
  
    return {
      content,
      startLine,
      endLine,
      totalLines: metadata.totalLines,
      chunkIndex,
      totalChunks,
      filePath,
      byteOffset: 0, // Calculated if needed
      byteSize: Buffer.byteLength(content, 'utf-8'),
    };
  }

• src/server.ts:267-295 (handler)

  The MCP server-specific handler `handleReadChunk` that parses tool arguments, applies caching via CacheManager, delegates to FileHandler.readChunk, and formats the JSON response for MCP protocol.

  private async handleReadChunk(
    args: Record<string, unknown>
  ): Promise<{ content: Array<{ type: string; text: string }> }> {
    const filePath = args.filePath as string;
    const chunkIndex = (args.chunkIndex as number) || 0;
    const linesPerChunk = args.linesPerChunk as number | undefined;
    const includeLineNumbers = (args.includeLineNumbers as boolean) || false;
  
    const cacheKey = `chunk:${filePath}:${chunkIndex}:${linesPerChunk}:${includeLineNumbers}`;
    let chunk = this.chunkCache.get(cacheKey);
  
    if (!chunk) {
      chunk = await FileHandler.readChunk(filePath, chunkIndex, {
        linesPerChunk,
        includeLineNumbers,
        overlapLines: this.config.defaultOverlap,
      });
      this.chunkCache.set(cacheKey, chunk);
    }
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(chunk, null, 2),
        },
      ],
    };
  }

• src/server.ts:90-115 (registration)

  Registers the 'read_large_file_chunk' tool with the MCP SDK Server by defining its name, description, and inputSchema in the tools list returned by getTools().

  {
    name: 'read_large_file_chunk',
    description: 'Read a specific chunk of a large file with intelligent chunking based on file type. Automatically determines optimal chunk size.',
    inputSchema: {
      type: 'object',
      properties: {
        filePath: {
          type: 'string',
          description: 'Absolute path to the file',
        },
        chunkIndex: {
          type: 'number',
          description: 'Zero-based chunk index to read (default: 0)',
        },
        linesPerChunk: {
          type: 'number',
          description: 'Number of lines per chunk (optional, auto-detected if not provided)',
        },
        includeLineNumbers: {
          type: 'boolean',
          description: 'Include line numbers in output (default: false)',
        },
      },
      required: ['filePath'],
    },
  },

• src/types.ts:5-24 (schema)

  TypeScript interface `FileChunk` defining the structured output returned by the read_large_file_chunk tool handler, including content, line ranges, metadata, and byte info.

  export interface FileChunk {
    /** Chunk content */
    content: string;
    /** Starting line number (1-indexed) */
    startLine: number;
    /** Ending line number (1-indexed) */
    endLine: number;
    /** Total lines in file */
    totalLines: number;
    /** Chunk index */
    chunkIndex: number;
    /** Total number of chunks */
    totalChunks: number;
    /** File path */
    filePath: string;
    /** Byte offset start */
    byteOffset: number;
    /** Chunk size in bytes */
    byteSize: number;
  }

• src/fileHandler.ts:66-87 (helper)

  Helper function `getOptimalChunkSize` that determines the ideal number of lines per chunk based on file type and size, enabling intelligent chunking central to the tool's 'automatic' sizing feature.

  static getOptimalChunkSize(fileType: FileType, totalLines: number): number {
    const baseSizes: Record<FileType, number> = {
      [FileType.LOG]: 500,
      [FileType.CSV]: 1000,
      [FileType.JSON]: 100,
      [FileType.CODE]: 300,
      [FileType.TEXT]: 500,
      [FileType.MARKDOWN]: 200,
      [FileType.XML]: 200,
      [FileType.BINARY]: 1000,
      [FileType.UNKNOWN]: 500,
    };
  
    const baseSize = baseSizes[fileType] || 500;
  
    // Adjust for very large files
    if (totalLines > 100000) {
      return Math.min(baseSize * 2, 2000);
    }
  
    return baseSize;
  }