file_read

Instructions

Implementation Reference

• src/tools/file-operations.ts:34-95 (handler)

  The handler function for file_read tool. Reads file contents from disk using fs.readFile, validates it's not a directory, checks size limit (10 MB), and returns file content with metadata (path, size, lastModified, encoding).

    async ({ filePath, encoding }) => {
      try {
        const resolvedPath = path.resolve(filePath);
        const stats = await fs.stat(resolvedPath);
  
        if (stats.isDirectory()) {
          return {
            content: [
              {
                type: "text" as const,
                text: `Error: '${resolvedPath}' is a directory, not a file.`,
              },
            ],
            isError: true,
          };
        }
  
        if (stats.size > 10_000_000) {
          return {
            content: [
              {
                type: "text" as const,
                text: `Error: File is too large (${(stats.size / 1_000_000).toFixed(1)} MB). Maximum size is 10 MB.`,
              },
            ],
            isError: true,
          };
        }
  
        const content = await fs.readFile(resolvedPath, { encoding: encoding as BufferEncoding });
  
        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify(
                {
                  path: resolvedPath,
                  size: stats.size,
                  lastModified: stats.mtime.toISOString(),
                  encoding,
                  content,
                },
                null,
                2
              ),
            },
          ],
        };
      } catch (err: any) {
        return {
          content: [
            {
              type: "text" as const,
              text: `File Read Error: ${err.message}`,
            },
          ],
          isError: true,
        };
      }
    }
  );

• src/tools/file-operations.ts:27-32 (schema)

  Input schema for file_read tool. Defines 'filePath' (string) and 'encoding' (enum with defaults to utf-8) parameters.

  {
    filePath: z.string().describe("Absolute or relative path to the file."),
    encoding: z
      .enum(["utf-8", "ascii", "utf-16le", "ucs2", "latin1", "binary"])
      .default("utf-8")
      .describe("Character encoding (default: utf-8)."),

• src/tools/file-operations.ts:13-96 (registration)

  Registration function for file_read tool. Calls server.tool('file_read', ...) with description, schema, and handler.

  export function registerFileReadTool(server: McpServer): void {
    server.tool(
      "file_read",
      `Read the contents of a file from the local filesystem.
  
  Features:
    - Read entire file or a specific byte range
    - Automatic encoding detection (UTF-8 default)
    - Returns file metadata (size, last modified)
    - Supports any text file type
  
  Security:
    - Rejects paths outside the allowed root directories
    - Refuses to read binary files or directories`,
      {
        filePath: z.string().describe("Absolute or relative path to the file."),
        encoding: z
          .enum(["utf-8", "ascii", "utf-16le", "ucs2", "latin1", "binary"])
          .default("utf-8")
          .describe("Character encoding (default: utf-8)."),
      },
      async ({ filePath, encoding }) => {
        try {
          const resolvedPath = path.resolve(filePath);
          const stats = await fs.stat(resolvedPath);
  
          if (stats.isDirectory()) {
            return {
              content: [
                {
                  type: "text" as const,
                  text: `Error: '${resolvedPath}' is a directory, not a file.`,
                },
              ],
              isError: true,
            };
          }
  
          if (stats.size > 10_000_000) {
            return {
              content: [
                {
                  type: "text" as const,
                  text: `Error: File is too large (${(stats.size / 1_000_000).toFixed(1)} MB). Maximum size is 10 MB.`,
                },
              ],
              isError: true,
            };
          }
  
          const content = await fs.readFile(resolvedPath, { encoding: encoding as BufferEncoding });
  
          return {
            content: [
              {
                type: "text" as const,
                text: JSON.stringify(
                  {
                    path: resolvedPath,
                    size: stats.size,
                    lastModified: stats.mtime.toISOString(),
                    encoding,
                    content,
                  },
                  null,
                  2
                ),
              },
            ],
          };
        } catch (err: any) {
          return {
            content: [
              {
                type: "text" as const,
                text: `File Read Error: ${err.message}`,
              },
            ],
            isError: true,
          };
        }
      }
    );
  }

• src/index.ts:47-49 (registration)

  Registration call in the McpToolkitServer class where registerFileReadTool is invoked with the server instance.

  registerFileReadTool(this.server);
  registerFileWriteTool(this.server);
  registerFileListTool(this.server);

• src/utils/helpers.ts:1-34 (helper)

  Shared utility helpers (ToolResult, textResult, errorResult, jsonResult) used by the file_read handler for constructing responses.

  /**
   * Shared utility types and helpers for MCP Toolkit Server tools.
   */
  
  /** Standard success response shape returned by tool handlers. */
  export interface ToolResult {
    content: Array<{ type: "text"; text: string }>;
    isError?: boolean;
  }
  
  /** Helper to build a success text response. */
  export function textResult(text: string): ToolResult {
    return { content: [{ type: "text" as const, text }] };
  }
  
  /** Helper to build an error text response. */
  export function errorResult(message: string): ToolResult {
    return {
      content: [{ type: "text" as const, text: message }],
      isError: true,
    };
  }
  
  /** Helper to JSON-stringify and wrap in a text result. */
  export function jsonResult(data: unknown, pretty = true): ToolResult {
    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify(data, null, pretty ? 2 : 0),
        },
      ],
    };
  }