Volcengine Image Generation MCP Server

Instructions

Implementation Reference

• src/tools.ts:28-59 (handler)

  The primary handler function for the 'generate_image' tool. Validates input arguments using Zod schema, prepares the request, calls the Volcengine API, and returns formatted success/error response.

  async generateImage(args: VolcengineImageGenerationToolArgs) {
    try {
      const validatedArgs = generateImageSchema.parse(args);
      
      const request = {
        model: validatedArgs.model,
        prompt: validatedArgs.prompt,
        response_format: validatedArgs.response_format,
        size: validatedArgs.size,
        seed: validatedArgs.seed,
        guidance_scale: validatedArgs.guidance_scale,
        watermark: validatedArgs.watermark,
      };
  
      const response = await this.api.generateImage(request);
  
      return {
        success: true,
        data: {
          model: response.model,
          created: response.created,
          images: response.data,
          usage: response.usage,
        },
      };
    } catch (error) {
      return {
        success: false,
        error: error instanceof Error ? error.message : 'Unknown error occurred',
      };
    }
  }

• src/tools.ts:11-19 (schema)

  Zod schema used for input validation of the 'generate_image' tool arguments.

  export const generateImageSchema = z.object({
    prompt: z.string().min(1, 'Prompt is required').max(1000, 'Prompt too long'),
    model: z.string().default(DEFAULT_MODEL),
    size: z.enum(SUPPORTED_SIZES).default(DEFAULT_SIZE),
    seed: z.number().int().min(-1).max(2147483647).optional(),
    guidance_scale: z.number().min(1).max(10).optional(),
    watermark: z.boolean().default(true),
    response_format: z.enum(['url', 'b64_json']).default(DEFAULT_RESPONSE_FORMAT),
  });

• src/tools.ts:61-110 (registration)

  Tool definition method returning the MCP tool specification for 'generate_image', including name, description, and input schema. Used in listTools response.

  getToolDefinition() {
    return {
      name: 'generate_image',
      description: 'Generate images using Volcengine\'s text-to-image API',
      inputSchema: {
        type: 'object',
        properties: {
          prompt: {
            type: 'string',
            description: 'Text prompt for image generation (max 1000 characters)',
          },
          model: {
            type: 'string',
            description: 'Model to use for image generation',
            default: DEFAULT_MODEL,
          },
          size: {
            type: 'string',
            description: 'Image size dimensions',
            enum: SUPPORTED_SIZES,
            default: DEFAULT_SIZE,
          },
          seed: {
            type: 'number',
            description: 'Random seed for reproducible results (-1 for random)',
            minimum: -1,
            maximum: 2147483647,
          },
          guidance_scale: {
            type: 'number',
            description: 'How closely to follow the prompt (1-10)',
            minimum: 1,
            maximum: 10,
          },
          watermark: {
            type: 'boolean',
            description: 'Whether to add watermark to generated images',
            default: true,
          },
          response_format: {
            type: 'string',
            description: 'Format for returned image data',
            enum: ['url', 'b64_json'],
            default: DEFAULT_RESPONSE_FORMAT,
          },
        },
        required: ['prompt'],
      },
    };
  }

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

  Dispatch logic in MCP callTool request handler: checks for 'generate_image' tool name and invokes the handler, formats MCP response.

  if (name === 'generate_image') {
    try {
      const result = await this.imageTools.generateImage(args);
      
      if (result.success) {
        return {
          content: [
            {
              type: 'text',
              text: JSON.stringify(result.data, null, 2),
            },
          ],
        };
      } else {
        return {
          content: [
            {
              type: 'text',
              text: `Error: ${result.error}`,
            },
          ],
          isError: true,
        };
      }
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/volcengine-api.ts:25-51 (helper)

  Low-level helper that makes the HTTP POST request to Volcengine's image generation API endpoint.

  async generateImage(request: VolcengineImageGenerationRequest): Promise<VolcengineImageGenerationResponse> {
    try {
      const response = await this.client.post<VolcengineImageGenerationResponse>(
        '/images/generations',
        request
      );
      
      return response.data;
    } catch (error) {
      if (axios.isAxiosError(error)) {
        const status = error.response?.status;
        const message = error.response?.data?.error?.message || error.message;
        
        if (status === 401) {
          throw new Error('Invalid API key or unauthorized access');
        } else if (status === 429) {
          throw new Error('Rate limit exceeded. Please try again later.');
        } else if (status === 400) {
          throw new Error(`Invalid request: ${message}`);
        } else {
          throw new Error(`API request failed: ${message}`);
        }
      }
      
      throw new Error(`Unknown error: ${error instanceof Error ? error.message : 'Unknown error'}`);
    }
  }