Large File MCP Server

Instructions

Implementation Reference

• src/fileHandler.ts:242-278 (handler)

  Core implementation of the navigate_to_line tool: verifies file, calculates context lines, reads lines, formats with markers and numbers, returns FileChunk.

  static async navigateToLine(
    filePath: string,
    lineNumber: number,
    contextLines: number = 5
  ): Promise<FileChunk> {
    await this.verifyFile(filePath);
  
    const metadata = await this.getMetadata(filePath);
  
    if (lineNumber < 1 || lineNumber > metadata.totalLines) {
      throw new Error(`Line number ${lineNumber} out of range (1-${metadata.totalLines})`);
    }
  
    const startLine = Math.max(1, lineNumber - contextLines);
    const endLine = Math.min(metadata.totalLines, lineNumber + contextLines);
  
    const lines = await this.readLines(filePath, startLine, endLine);
    const content = lines
      .map((line, idx) => {
        const num = startLine + idx;
        const marker = num === lineNumber ? '→ ' : '  ';
        return `${marker}${num}: ${line}`;
      })
      .join('\n');
  
    return {
      content,
      startLine,
      endLine,
      totalLines: metadata.totalLines,
      chunkIndex: Math.floor((lineNumber - 1) / 500),
      totalChunks: Math.ceil(metadata.totalLines / 500),
      filePath,
      byteOffset: 0,
      byteSize: Buffer.byteLength(content, 'utf-8'),
    };
  }

• src/server.ts:176-197 (registration)

  Registration of the 'navigate_to_line' tool in the MCP server's tool list, including name, description, and input schema definition.

  {
    name: 'navigate_to_line',
    description: 'Jump to a specific line in a large file with surrounding context lines. Highlights the target line.',
    inputSchema: {
      type: 'object',
      properties: {
        filePath: {
          type: 'string',
          description: 'Absolute path to the file',
        },
        lineNumber: {
          type: 'number',
          description: 'Line number to navigate to (1-indexed)',
        },
        contextLines: {
          type: 'number',
          description: 'Number of context lines before and after (default: 5)',
        },
      },
      required: ['filePath', 'lineNumber'],
    },
  },

• src/server.ts:179-195 (schema)

  Input schema definition for the navigate_to_line tool, specifying parameters and types for MCP validation.

  inputSchema: {
    type: 'object',
    properties: {
      filePath: {
        type: 'string',
        description: 'Absolute path to the file',
      },
      lineNumber: {
        type: 'number',
        description: 'Line number to navigate to (1-indexed)',
      },
      contextLines: {
        type: 'number',
        description: 'Number of context lines before and after (default: 5)',
      },
    },
    required: ['filePath', 'lineNumber'],

• src/server.ts:349-366 (helper)

  MCP server wrapper handler that extracts arguments, calls FileHandler.navigateToLine, and formats response as MCP content.

  private async handleNavigateToLine(
    args: Record<string, unknown>
  ): Promise<{ content: Array<{ type: string; text: string }> }> {
    const filePath = args.filePath as string;
    const lineNumber = args.lineNumber as number;
    const contextLines = (args.contextLines as number) || this.config.defaultContextLines;
  
    const chunk = await FileHandler.navigateToLine(filePath, lineNumber, contextLines);
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(chunk, null, 2),
        },
      ],
    };
  }