Large File MCP Server

Instructions

Implementation Reference

• src/fileHandler.ts:440-510 (handler)

  Core implementation of get_file_summary tool. Streams the file to compute detailed statistics: line counts (total, empty, non-empty, max/avg length), character categories (alphabetic, numeric, whitespace, special), and word count for text/markdown files.

  static async getSummary(filePath: string): Promise<FileSummary> {
    await this.verifyFile(filePath);
  
    const metadata = await this.getMetadata(filePath);
  
    let emptyLines = 0;
    let maxLength = 0;
    let totalLength = 0;
    let alphabetic = 0;
    let numeric = 0;
    let whitespace = 0;
    let special = 0;
    let wordCount = 0;
  
    return new Promise((resolve, reject) => {
      const stream = fs.createReadStream(filePath);
      const rl = readline.createInterface({
        input: stream,
        crlfDelay: Infinity,
      });
  
      rl.on('line', (line) => {
        if (line.trim() === '') {
          emptyLines++;
        } else {
          wordCount += line.split(/\s+/).filter(w => w.length > 0).length;
        }
  
        maxLength = Math.max(maxLength, line.length);
        totalLength += line.length;
  
        // Character analysis
        for (const char of line) {
          if (/[a-zA-Z]/.test(char)) alphabetic++;
          else if (/\d/.test(char)) numeric++;
          else if (/\s/.test(char)) whitespace++;
          else special++;
        }
      });
  
      rl.on('close', () => {
        const total = alphabetic + numeric + whitespace + special;
  
        resolve({
          metadata,
          lineStats: {
            total: metadata.totalLines,
            empty: emptyLines,
            nonEmpty: metadata.totalLines - emptyLines,
            maxLength,
            avgLength: metadata.totalLines > 0
              ? Math.round(totalLength / metadata.totalLines)
              : 0,
          },
          charStats: {
            total,
            alphabetic,
            numeric,
            whitespace,
            special,
          },
          wordCount: metadata.fileType === FileType.TEXT ||
                     metadata.fileType === FileType.MARKDOWN
            ? wordCount
            : undefined,
        });
      });
  
      rl.on('error', reject);
    });
  }

• src/server.ts:198-211 (registration)

  Registers the get_file_summary tool in the MCP server by including it in the list of available tools returned by getTools(). Includes tool name, description, and input schema.

  {
    name: 'get_file_summary',
    description: 'Get comprehensive statistical summary of a file including line stats, character stats, and word count.',
    inputSchema: {
      type: 'object',
      properties: {
        filePath: {
          type: 'string',
          description: 'Absolute path to the file',
        },
      },
      required: ['filePath'],
    },
  },

• src/server.ts:368-383 (handler)

  Server-side handler wrapper for get_file_summary. Extracts filePath from arguments, calls FileHandler.getSummary, and formats response as JSON.

  private async handleGetSummary(
    args: Record<string, unknown>
  ): Promise<{ content: Array<{ type: string; text: string }> }> {
    const filePath = args.filePath as string;
  
    const summary: FileSummary = await FileHandler.getSummary(filePath);
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(summary, null, 2),
        },
      ],
    };
  }

• src/types.ts:120-143 (schema)

  TypeScript interface defining the structure of the FileSummary output returned by the get_file_summary tool.

  export interface FileSummary {
    /** File metadata */
    metadata: FileMetadata;
    /** Line statistics */
    lineStats: {
      total: number;
      empty: number;
      nonEmpty: number;
      maxLength: number;
      avgLength: number;
    };
    /** Character statistics */
    charStats: {
      total: number;
      alphabetic: number;
      numeric: number;
      whitespace: number;
      special: number;
    };
    /** Word count (for text files) */
    wordCount?: number;
    /** Top file patterns (e.g., most common lines) */
    patterns?: Array<{ pattern: string; count: number }>;
  }