Filesystem MCP Server

Instructions

Implementation Reference

• src/filesystem/index.ts:172-192 (handler)

  Handler function that implements the core logic for the 'read_file' tool. Validates path, optionally tails/heads the file, otherwise reads full content using readFileContent, and returns as text content.

  const readTextFileHandler = async (args: z.infer<typeof ReadTextFileArgsSchema>) => {
    const validPath = await validatePath(args.path);
  
    if (args.head && args.tail) {
      throw new Error("Cannot specify both head and tail parameters simultaneously");
    }
  
    let content: string;
    if (args.tail) {
      content = await tailFile(validPath, args.tail);
    } else if (args.head) {
      content = await headFile(validPath, args.head);
    } else {
      content = await readFileContent(validPath);
    }
  
    return {
      content: [{ type: "text" as const, text: content }],
      structuredContent: { content }
    };
  };

• src/filesystem/index.ts:194-204 (registration)

  Registration of the 'read_file' tool, marking it as deprecated and pointing to read_text_file, using the shared readTextFileHandler.

  server.registerTool(
    "read_file",
    {
      title: "Read File (Deprecated)",
      description: "Read the complete contents of a file as text. DEPRECATED: Use read_text_file instead.",
      inputSchema: ReadTextFileArgsSchema.shape,
      outputSchema: { content: z.string() },
      annotations: { readOnlyHint: true }
    },
    readTextFileHandler
  );

• src/filesystem/index.ts:77-81 (schema)

  Zod input schema defining parameters for read_file (path, optional tail/head line limits).

  const ReadTextFileArgsSchema = z.object({
    path: z.string(),
    tail: z.number().optional().describe('If provided, returns only the last N lines of the file'),
    head: z.number().optional().describe('If provided, returns only the first N lines of the file')
  });

• src/filesystem/lib.ts:134-136 (helper)

  Helper function that performs the actual fs.readFile operation for reading file contents as text, used by the read_file handler.

  export async function readFileContent(filePath: string, encoding: string = 'utf-8'): Promise<string> {
    return await fs.readFile(filePath, encoding as BufferEncoding);
  }

• src/filesystem/lib.ts:262-311 (helper)

  Helper for tailing last N lines, used when 'tail' parameter is provided in read_file.

  export async function tailFile(filePath: string, numLines: number): Promise<string> {
    const CHUNK_SIZE = 1024; // Read 1KB at a time
    const stats = await fs.stat(filePath);
    const fileSize = stats.size;
    
    if (fileSize === 0) return '';
    
    // Open file for reading
    const fileHandle = await fs.open(filePath, 'r');
    try {
      const lines: string[] = [];
      let position = fileSize;
      let chunk = Buffer.alloc(CHUNK_SIZE);
      let linesFound = 0;
      let remainingText = '';
      
      // Read chunks from the end of the file until we have enough lines
      while (position > 0 && linesFound < numLines) {
        const size = Math.min(CHUNK_SIZE, position);
        position -= size;
        
        const { bytesRead } = await fileHandle.read(chunk, 0, size, position);
        if (!bytesRead) break;
        
        // Get the chunk as a string and prepend any remaining text from previous iteration
        const readData = chunk.slice(0, bytesRead).toString('utf-8');
        const chunkText = readData + remainingText;
        
        // Split by newlines and count
        const chunkLines = normalizeLineEndings(chunkText).split('\n');
        
        // If this isn't the end of the file, the first line is likely incomplete
        // Save it to prepend to the next chunk
        if (position > 0) {
          remainingText = chunkLines[0];
          chunkLines.shift(); // Remove the first (incomplete) line
        }
        
        // Add lines to our result (up to the number we need)
        for (let i = chunkLines.length - 1; i >= 0 && linesFound < numLines; i--) {
          lines.unshift(chunkLines[i]);
          linesFound++;
        }
      }
      
      return lines.join('\n');
    } finally {
      await fileHandle.close();
    }
  }