Content Helpers

Helper functions for creating MCP content types

FastMCP provides helper functions to create image and audio content from various sources.

imageContent()

Create image content from a buffer, file path, or URL.

import { imageContent } from "fastmcp";

// From URL
const image1 = await imageContent({ 
  url: "https://example.com/image.png" 
});

// From file path
const image2 = await imageContent({ 
  path: "/path/to/image.jpg" 
});

// From buffer
const buffer = Buffer.from("...");
const image3 = await imageContent({ 
  buffer 
});

// Use in tool response
server.addTool({
  name: "get_chart",
  execute: async () => {
    const chart = await generateChart();
    return await imageContent({ buffer: chart });
  },
});

Parameters

input · object · required

Image source (must provide exactly one)

Show options

url · string

HTTP(S) URL to fetch image from

{ url: "https://example.com/image.png" }

path · string

Local file system path

{ path: "/path/to/image.jpg" }

buffer · Buffer

Raw image data buffer

{ buffer: Buffer.from(...) }

Returns

result · Promise<ImageContent>

Image content object

{
  type: "image",
  data: string,      // Base64-encoded image data
  mimeType: string,  // Auto-detected (e.g., "image/png", "image/jpeg")
}

Features

• Auto-detection: Automatically detects MIME type using file-type package
• Base64 encoding: Converts image data to base64 for MCP protocol
• Format validation: Warns if content doesn’t appear to be a valid image
• Error handling: Clear error messages for fetch failures, file read errors

Supported Formats

Any image format supported by the file-type package:

• PNG (.png)
• JPEG (.jpg, .jpeg)
• GIF (.gif)
• WebP (.webp)
• SVG (.svg)
• BMP (.bmp)
• ICO (.ico)
• And many more…

Error Handling

try {
  const image = await imageContent({ url: "https://example.com/image.png" });
} catch (error) {
  if (error instanceof Error) {
    console.error(error.message);
    // Possible errors:
    // - "Failed to fetch image from URL (...): ..."
    // - "Failed to read image from path (...): ..."
    // - "Invalid input: Provide a valid 'url', 'path', or 'buffer'"
  }
}

audioContent()

Create audio content from a buffer, file path, or URL.

import { audioContent } from "fastmcp";

// From URL
const audio1 = await audioContent({ 
  url: "https://example.com/audio.mp3" 
});

// From file path
const audio2 = await audioContent({ 
  path: "/path/to/audio.wav" 
});

// From buffer
const buffer = Buffer.from("...");
const audio3 = await audioContent({ 
  buffer 
});

// Use in tool response
server.addTool({
  name: "text_to_speech",
  execute: async ({ text }) => {
    const audioBuffer = await synthesizeSpeech(text);
    return await audioContent({ buffer: audioBuffer });
  },
});

Parameters

input · object · required

Audio source (must provide exactly one)

Show options

url · string

HTTP(S) URL to fetch audio from

{ url: "https://example.com/audio.mp3" }

path · string

Local file system path

{ path: "/path/to/audio.wav" }

buffer · Buffer

Raw audio data buffer

{ buffer: Buffer.from(...) }

Returns

result · Promise<AudioContent>

Audio content object

{
  type: "audio",
  data: string,      // Base64-encoded audio data
  mimeType: string,  // Auto-detected (e.g., "audio/mpeg", "audio/wav")
}

Features

• Auto-detection: Automatically detects MIME type using file-type package
• Base64 encoding: Converts audio data to base64 for MCP protocol
• Format validation: Warns if content doesn’t appear to be valid audio
• Error handling: Clear error messages for fetch failures, file read errors

Supported Formats

Any audio format supported by the file-type package:

• MP3 (.mp3)
• WAV (.wav)
• OGG (.ogg)
• FLAC (.flac)
• AAC (.aac)
• M4A (.m4a)
• OPUS (.opus)
• And more…

Error Handling

try {
  const audio = await audioContent({ url: "https://example.com/audio.mp3" });
} catch (error) {
  if (error instanceof Error) {
    console.error(error.message);
    // Possible errors:
    // - "Failed to fetch audio from URL (...): ..."
    // - "Failed to read audio from path (...): ..."
    // - "Invalid input: Provide a valid 'url', 'path', or 'buffer'"
  }
}

Usage Examples

Return multiple content types

import { imageContent, audioContent } from "fastmcp";

server.addTool({
  name: "media_analysis",
  description: "Analyze media and return visualization",
  execute: async ({ videoUrl }) => {
    const thumbnail = await extractThumbnail(videoUrl);
    const audioTrack = await extractAudio(videoUrl);
    
    return {
      content: [
        { type: "text", text: "Analysis results:" },
        await imageContent({ buffer: thumbnail }),
        await audioContent({ buffer: audioTrack }),
      ],
    };
  },
});

Download and return image

import { imageContent } from "fastmcp";

server.addTool({
  name: "get_screenshot",
  description: "Screenshot a website",
  parameters: z.object({
    url: z.string().url(),
  }),
  execute: async ({ url }) => {
    const screenshot = await takeScreenshot(url);
    return await imageContent({ buffer: screenshot });
  },
});

Generate and return audio

import { audioContent } from "fastmcp";

server.addTool({
  name: "generate_tone",
  description: "Generate audio tone",
  parameters: z.object({
    frequency: z.number(),
    duration: z.number(),
  }),
  execute: async ({ frequency, duration }) => {
    const audioBuffer = generateTone(frequency, duration);
    return await audioContent({ buffer: audioBuffer });
  },
});

Resource with image content

import { imageContent } from "fastmcp";

server.addResource({
  uri: "app://logo",
  name: "App Logo",
  mimeType: "image/png",
  load: async () => {
    const logo = await imageContent({ path: "./assets/logo.png" });
    return {
      blob: logo.data,
      mimeType: logo.mimeType,
    };
  },
});