Large File MCP Server

Instructions

Implementation Reference

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

  Tool registration in MCP server including name, description, and input schema.
  { 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/server.ts:267-295 (handler)

  Server-side handler for the tool call, including caching and delegation to FileHandler.readChunk.
  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/fileHandler.ts:171-204 (handler)

  Core implementation: calculates chunk boundaries with overlap, reads lines using efficient readline stream, applies optimal chunk size based on file type, formats with optional line numbers, returns 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/types.ts:100-107 (schema)

  TypeScript interface defining options for chunk reading, matching tool input parameters.
  export interface ChunkOptions { /** Chunk size in lines */ linesPerChunk?: number; /** Overlap lines between chunks */ overlapLines?: number; /** Include line numbers in output */ includeLineNumbers?: boolean; }
• src/fileHandler.ts:66-87 (helper)

  Helper function to determine optimal linesPerChunk based on detected file type and total file size.
  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; }