Filesystem MCP Server

Instructions

Implementation Reference

• src/filesystem/index.ts:248-278 (handler)

  The handler function for the 'read_media_file' tool. Validates the path, determines the MIME type based on file extension, reads the file as base64 using a helper, categorizes as image/audio/blob, and returns structured content with base64 data.

  async (args: z.infer<typeof ReadMediaFileArgsSchema>) => {
    const validPath = await validatePath(args.path);
    const extension = path.extname(validPath).toLowerCase();
    const mimeTypes: Record<string, string> = {
      ".png": "image/png",
      ".jpg": "image/jpeg",
      ".jpeg": "image/jpeg",
      ".gif": "image/gif",
      ".webp": "image/webp",
      ".bmp": "image/bmp",
      ".svg": "image/svg+xml",
      ".mp3": "audio/mpeg",
      ".wav": "audio/wav",
      ".ogg": "audio/ogg",
      ".flac": "audio/flac",
    };
    const mimeType = mimeTypes[extension] || "application/octet-stream";
    const data = await readFileAsBase64Stream(validPath);
  
    const type = mimeType.startsWith("image/")
      ? "image"
      : mimeType.startsWith("audio/")
        ? "audio"
        // Fallback for other binary types, not officially supported by the spec but has been used for some time
        : "blob";
    const contentItem = { type: type as 'image' | 'audio' | 'blob', data, mimeType };
    return {
      content: [contentItem],
      structuredContent: { content: [contentItem] }
    } as unknown as CallToolResult;
  }

• src/filesystem/index.ts:83-85 (schema)

  Zod schema defining the input arguments for the read_media_file tool: a single 'path' string.

  const ReadMediaFileArgsSchema = z.object({
    path: z.string()
  });

• src/filesystem/index.ts:229-279 (registration)

  Registration of the 'read_media_file' tool with the MCP server, including title, description, input/output schemas, annotations, and the inline handler function.

  server.registerTool(
    "read_media_file",
    {
      title: "Read Media File",
      description:
        "Read an image or audio file. Returns the base64 encoded data and MIME type. " +
        "Only works within allowed directories.",
      inputSchema: {
        path: z.string()
      },
      outputSchema: {
        content: z.array(z.object({
          type: z.enum(["image", "audio", "blob"]),
          data: z.string(),
          mimeType: z.string()
        }))
      },
      annotations: { readOnlyHint: true }
    },
    async (args: z.infer<typeof ReadMediaFileArgsSchema>) => {
      const validPath = await validatePath(args.path);
      const extension = path.extname(validPath).toLowerCase();
      const mimeTypes: Record<string, string> = {
        ".png": "image/png",
        ".jpg": "image/jpeg",
        ".jpeg": "image/jpeg",
        ".gif": "image/gif",
        ".webp": "image/webp",
        ".bmp": "image/bmp",
        ".svg": "image/svg+xml",
        ".mp3": "audio/mpeg",
        ".wav": "audio/wav",
        ".ogg": "audio/ogg",
        ".flac": "audio/flac",
      };
      const mimeType = mimeTypes[extension] || "application/octet-stream";
      const data = await readFileAsBase64Stream(validPath);
  
      const type = mimeType.startsWith("image/")
        ? "image"
        : mimeType.startsWith("audio/")
          ? "audio"
          // Fallback for other binary types, not officially supported by the spec but has been used for some time
          : "blob";
      const contentItem = { type: type as 'image' | 'audio' | 'blob', data, mimeType };
      return {
        content: [contentItem],
        structuredContent: { content: [contentItem] }
      } as unknown as CallToolResult;
    }
  );

• src/filesystem/index.ts:154-167 (helper)

  Helper function that reads a binary file using a stream, concatenates chunks into a buffer, and returns the base64-encoded string. Used by the read_media_file handler.

  async function readFileAsBase64Stream(filePath: string): Promise<string> {
    return new Promise((resolve, reject) => {
      const stream = createReadStream(filePath);
      const chunks: Buffer[] = [];
      stream.on('data', (chunk) => {
        chunks.push(chunk as Buffer);
      });
      stream.on('end', () => {
        const finalBuffer = Buffer.concat(chunks);
        resolve(finalBuffer.toString('base64'));
      });
      stream.on('error', (err) => reject(err));
    });
  }