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),
        },
      ],
    };
  }