Large File MCP Server

Instructions

Implementation Reference

• src/fileHandler.ts:373-435 (handler)

  Core handler function that implements the logic for analyzing file structure: computes metadata, line statistics (empty/non-empty, max/avg length), recommended chunk size, and samples from beginning and end of the file.
  static async getStructure(filePath: string): Promise<FileStructure> { await this.verifyFile(filePath); const metadata = await this.getMetadata(filePath); let emptyLines = 0; let maxLineLength = 0; let totalLineLength = 0; const sampleStart: string[] = []; let lineCount = 0; const endBuffer: string[] = []; return new Promise((resolve, reject) => { const stream = fs.createReadStream(filePath); const rl = readline.createInterface({ input: stream, crlfDelay: Infinity, }); rl.on('line', (line) => { lineCount++; if (line.trim() === '') emptyLines++; maxLineLength = Math.max(maxLineLength, line.length); totalLineLength += line.length; // Sample start if (sampleStart.length < this.SAMPLE_LINES) { sampleStart.push(line); } // Sample end (keep last N lines) endBuffer.push(line); if (endBuffer.length > this.SAMPLE_LINES) { endBuffer.shift(); } }); rl.on('close', () => { const recommendedChunkSize = this.getOptimalChunkSize( metadata.fileType, metadata.totalLines ); resolve({ metadata, lineStats: { total: metadata.totalLines, empty: emptyLines, nonEmpty: metadata.totalLines - emptyLines, maxLineLength, avgLineLength: lineCount > 0 ? Math.round(totalLineLength / lineCount) : 0, }, recommendedChunkSize, estimatedChunks: Math.ceil(metadata.totalLines / recommendedChunkSize), sampleStart, sampleEnd: endBuffer, }); }); rl.on('error', reject); }); }
• src/server.ts:162-175 (registration)

  Registration of the 'get_file_structure' tool in the MCP server's tool list, including name, description, and input schema.
  { name: 'get_file_structure', description: 'Analyze file structure and get comprehensive metadata including line statistics, recommended chunk size, and samples from start and end.', inputSchema: { type: 'object', properties: { filePath: { type: 'string', description: 'Absolute path to the file', }, }, required: ['filePath'], }, },
• src/types.ts:47-66 (schema)

  Output type definition (FileStructure) returned by the get_file_structure tool, defining the structure of the response.
  export interface FileStructure { /** File metadata */ metadata: FileMetadata; /** Line count distribution */ lineStats: { total: number; empty: number; nonEmpty: number; maxLineLength: number; avgLineLength: number; }; /** Recommended chunk size for this file */ recommendedChunkSize: number; /** Total chunks with recommended size */ estimatedChunks: number; /** Sample lines from start */ sampleStart: string[]; /** Sample lines from end */ sampleEnd: string[]; }
• src/server.ts:326-347 (handler)

  MCP server wrapper handler for get_file_structure: handles caching, delegates to FileHandler.getStructure, and formats response as MCP content.
  private async handleGetStructure( args: Record<string, unknown> ): Promise<{ content: Array<{ type: string; text: string }> }> { const filePath = args.filePath as string; const cacheKey = `structure:${filePath}`; let structure = this.metadataCache.get(cacheKey); if (!structure) { structure = await FileHandler.getStructure(filePath); this.metadataCache.set(cacheKey, structure); } return { content: [ { type: 'text', text: JSON.stringify(structure, null, 2), }, ], }; }