Recraft AI MCP Server

Instructions

Implementation Reference

• src/tools/ReplaceBackground.ts:44-80 (handler)

  The main handler function that parses input arguments, downloads the input image, calls the Recraft API's replaceBackground method, transforms the response, and handles errors.

  export const replaceBackgroundHandler = async (server: RecraftServer, args: Record<string, unknown>): Promise<CallToolResult> => {
    try {
      const { imageURI, prompt, style, substyle, styleID, numberOfImages } = z.object({
        imageURI: z.string(),
        prompt: z.string(),
        style: z.nativeEnum(ImageStyle).optional(),
        substyle: z.nativeEnum(ImageSubStyle).optional(),
        styleID: z.string().optional(),
        numberOfImages: z.number().optional()
      }).parse(args)
  
      const imageData = await downloadImage(imageURI)
  
      const result = await server.api.imageApi.replaceBackground({
        image: await imageDataToBlob(imageData),
        prompt: prompt,
        style: styleID ? undefined : style,
        substyle: styleID ? undefined : substyle,
        styleId: styleID,
        responseFormat: 'url',
        n: numberOfImages,
        expire: server.isLocalResultsStorage,
      })
  
      return await server.transformGenerateImageResponseToCallToolResult(result)
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `Error generating image: ${error}`
          }
        ],
        isError: true
      }
    }
  }

• src/tools/ReplaceBackground.ts:9-42 (schema)

  The tool definition object including the name, description, and detailed inputSchema for parameter validation.

  export const replaceBackgroundTool = {
    name: "replace_background",
    description: "Generate an image using Recraft from an input image with its detected background replaced based on the prompt.\n" +
      "You can specify the input image, style, model, and number of images to generate.\n" +
      "You should provide the same style/substyle/styleID settings as were used for input image generation (if exists) if there are no specific requirements to change the style.\n" +
      "Other parameters are recommended to keep default if you don't have any specific requirements on them.\n" +
      "You can use styles to refine the image background generation, and also to generate raster or vector images.\n" +
      "Local paths or URLs to generated images and their previews will be returned in the response.",
    inputSchema: {
      type: "object",
      properties: {
        imageURI: PARAMETERS.imageURI,
        prompt: {
          type: "string",
          description: "Text prompt of the background areas that will be changed.\n" +
            "Its length should be from 1 to 1024 characters."
        },
        style: {
          ...PARAMETERS.imageStyle,
          description: PARAMETERS.imageStyle.description + "\n" + STYLE_PRESERVATION_WARNING,
        },
        substyle: {
          ...PARAMETERS.imageSubStyle,
          description: PARAMETERS.imageSubStyle.description + "\n" + STYLE_PRESERVATION_WARNING,
        },
        styleID: {
          ...PARAMETERS.imageStyleID,
          description: PARAMETERS.imageStyleID.description + "\n" + STYLE_PRESERVATION_WARNING,
        },
        numberOfImages: PARAMETERS.numberOfImages,
      },
      required: ["imageURI", "prompt"]
    }
  }

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

  Registration of the replace_background tool in the listTools handler, where replaceBackgroundTool is included in the tools array.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: [
        generateImageTool,
        createStyleTool,
        vectorizeImageTool,
        imageToImageTool,
        removeBackgroundTool,
        replaceBackgroundTool,
        crispUpscaleTool,
        creativeUpscaleTool,
        getUserTool,
      ],
    }
  })

• src/index.ts:112-113 (registration)

  Dispatch registration in the callTool handler switch statement, routing calls to replaceBackgroundTool.name to the replaceBackgroundHandler.

  case replaceBackgroundTool.name:
    return await replaceBackgroundHandler(recraftServer, args ?? {})