image

Instructions

Implementation Reference

• src/core/services/image-service.ts:13-90 (handler)

  Core handler function that implements the image tool logic: constructs image URLs from picsum.photos based on parameters, handles special modes (list, info), applies filters, and returns URL string, ImageContent, or TextContent.

  public static async generateImage(params: {
    width?: number;
    height?: number;
    id?: string;
    seed?: string;
    grayscale?: boolean;
    blur?: number;
    format?: 'jpg' | 'webp';
    output?: 'url' | 'file';
    list?: boolean;
    page?: number;
    limit?: number;
    info?: boolean;
  }): Promise<string | ImageContent | TextContent> {
    const {
      width,
      height,
      id,
      seed,
      grayscale,
      blur,
      format,
      output = 'url',
      list,
      page,
      limit,
      info
    } = params;
  
    // Handle list operation
    if (list) {
      const result = await this.fetchImageList(page, limit);
      return {
        type: "text",
        text: JSON.stringify(result, null, 2)
      } as TextContent;
    }
  
    // Handle info operation
    if (info) {
      let result: object;
      if (id) {
        result = await this.fetchImageInfo(id);
      } else if (seed) {
        result = await this.fetchSeedInfo(seed, width, height);
      } else {
        throw new Error('Info operation requires either --id or --seed parameter');
      }
      return {
        type: "text",
        text: JSON.stringify(result, null, 2)
      } as TextContent;
    }
  
    // Validate blur parameter
    if (blur !== undefined && (blur < 1 || blur > 10)) {
      throw new Error('Blur value must be between 1 and 10');
    }
  
    // Generate image URL
    const url = this.constructImageUrl({
      width,
      height,
      id,
      seed,
      grayscale,
      blur,
      format
    });
  
    // Return URL or fetch file data
    if (output === 'url') {
      return url;
    } else {
      // Use the imageContent helper to return proper ImageContent
      return await imageContent({ url });
    }
  }

• src/core/tools.ts:14-34 (registration)

  Registers the 'image' tool with the FastMCP server, including name, description, Zod input schema, and thin execute handler delegating to ImageService.generateImage.

  server.addTool({
    name: "image",
    description: "Generate or fetch images from picsum.photos with various options",
    parameters: z.object({
      width: z.number().int().positive().optional().describe("The width of the image in pixels"),
      height: z.number().int().positive().optional().describe("The height of the image in pixels"),
      id: z.string().optional().describe("The ID of a specific image to retrieve"),
      seed: z.string().optional().describe("A seed for generating a static random image"),
      grayscale: z.boolean().optional().describe("Apply grayscale filter to the image"),
      blur: z.number().int().min(1).max(10).optional().describe("Apply blur filter (1-10)"),
      format: z.enum(["jpg", "webp"]).optional().describe("Image format"),
      output: z.enum(["url", "file"]).default("url").describe("Output type: url returns string URL, file returns binary data"),
      list: z.boolean().optional().describe("Fetch list of available images"),
      page: z.number().int().positive().optional().describe("Page number for list results"),
      limit: z.number().int().positive().optional().describe("Number of results per page for list"),
      info: z.boolean().optional().describe("Fetch metadata for a specific image")
    }),
    execute: async (params) => {
      return await services.ImageService.generateImage(params);
    }
  });

• src/core/tools.ts:17-30 (schema)

  Zod schema defining all input parameters for the 'image' tool, including dimensions, IDs, seeds, filters, output format, and special operations like list and info.

  parameters: z.object({
    width: z.number().int().positive().optional().describe("The width of the image in pixels"),
    height: z.number().int().positive().optional().describe("The height of the image in pixels"),
    id: z.string().optional().describe("The ID of a specific image to retrieve"),
    seed: z.string().optional().describe("A seed for generating a static random image"),
    grayscale: z.boolean().optional().describe("Apply grayscale filter to the image"),
    blur: z.number().int().min(1).max(10).optional().describe("Apply blur filter (1-10)"),
    format: z.enum(["jpg", "webp"]).optional().describe("Image format"),
    output: z.enum(["url", "file"]).default("url").describe("Output type: url returns string URL, file returns binary data"),
    list: z.boolean().optional().describe("Fetch list of available images"),
    page: z.number().int().positive().optional().describe("Page number for list results"),
    limit: z.number().int().positive().optional().describe("Number of results per page for list"),
    info: z.boolean().optional().describe("Fetch metadata for a specific image")
  }),

• src/core/services/image-service.ts:95-152 (helper)

  Helper method to construct the picsum.photos image URL based on provided parameters, handling path construction and query parameters for filters and format.

  private static constructImageUrl(params: {
    width?: number;
    height?: number;
    id?: string;
    seed?: string;
    grayscale?: boolean;
    blur?: number;
    format?: 'jpg' | 'webp';
  }): string {
    const { width, height, id, seed, grayscale, blur, format } = params;
  
    let url: string;
  
    // Construct base URL path
    if (id) {
      if (width && height) {
        url = `${this.BASE_URL}/id/${id}/${width}/${height}`;
      } else if (width) {
        url = `${this.BASE_URL}/id/${id}/${width}`;
      } else {
        url = `${this.BASE_URL}/id/${id}`;
      }
    } else {
      if (width && height) {
        url = `${this.BASE_URL}/${width}/${height}`;
      } else if (width) {
        url = `${this.BASE_URL}/${width}`;
      } else {
        // Default size if no dimensions specified
        url = `${this.BASE_URL}/200`;
      }
    }
  
    // Add query parameters
    const queryParams: string[] = [];
  
    if (seed) {
      queryParams.push(`seed=${encodeURIComponent(seed)}`);
    }
  
    if (grayscale) {
      queryParams.push('grayscale');
    }
  
    if (blur) {
      queryParams.push(`blur=${blur}`);
    }
  
    if (format) {
      queryParams.push(`fmt=${format}`);
    }
  
    if (queryParams.length > 0) {
      url += '?' + queryParams.join('&');
    }
  
    return url;
  }