# Response Illustrator MCP

[中文说明](./README.zh-CN.md)

An MCP server that adds illustrative images to responses. It exposes an image generation and editing service over MCP stdio for clients such as Cherry Studio, and returns Markdown images together with locally hosted HTTP URLs so clients can render them directly.

## Configure image generation

Copy [config.example.json](./config.example.json) to create your configuration file, then set the API URL, model, API key environment variable, and timeout as needed.

The example uses OpenAI's Images API and the `gpt-image-1` model. Other OpenAI-compatible image APIs can be used by changing the endpoint and model.

```json
{
  "apiUrl": "https://api.openai.com/v1/images/generations",
  "editApiUrl": "https://api.openai.com/v1/images/edits",
  "model": "gpt-image-1",
  "apiKeyEnv": "OPENAI_API_KEY",
  "timeoutMs": 120000
}
```

The default configuration file locations are:

- Windows: `%APPDATA%\\seedream-image-mcp\\config.json`
- macOS / Linux: `$XDG_CONFIG_HOME/seedream-image-mcp/config.json`, or `~/.config/seedream-image-mcp/config.json` when `XDG_CONFIG_HOME` is not set

Use `--config PATH` to select another file. Required fields are `apiUrl`, `model`, `apiKeyEnv`, and `timeoutMs`. `editApiUrl` is optional; when omitted, reference-image requests use `apiUrl`.

## Configure the API key

Create a `.env` file in the project directory. The variable name must match `apiKeyEnv`:

```dotenv
OPENAI_API_KEY=replace-with-your-api-key
```

Keep `.env` out of version control and never put a real key in JSON configuration.

## Cherry Studio configuration

Install dependencies first:

```bash
bun install
```

In Cherry Studio, add an MCP server and replace the example paths with the paths on your machine:

```json
{
  "mcpServers": {
    "response-illustrator": {
      "command": "bun",
      "args": [
        "run",
        "/path/to/your/project/src/index.ts",
        "--env-file",
        "/path/to/your/project/.env",
        "--config",
        "/path/to/your/project/config.local.json"
      ]
    }
  }
}
```

Cherry Studio and the MCP server must run on the same computer so the client can access returned `http://127.0.0.1:<port>/images/...` URLs. Generated images are stored in a temporary directory and cleaned up automatically after 24 hours.

## Recommended system prompt

Add the following system prompt in Cherry Studio to let the assistant decide when an answer benefits from an illustration:

```text
You are a helpful assistant. Answer the user in {{language}}.

For every response, decide whether an illustration would make the explanation clearer.
- Use the MCP generate-image tool when an image can explain a complex concept, show a relationship, or illustrate a process.
- Do not use the tool for simple facts, calculations, code, definitions, or content that is already clear without an image.
- When an image is useful, call the tool while generating the answer and place the returned Markdown image near the relevant explanation. Do not replace the image URL with another URL.
```

## Tool reference

The MCP tool is named `generate-image` and accepts:

- `prompt`: image description, up to 5000 characters
- `size`: optional image size, default `auto`
- `images`: optional array of reference-image URLs, up to 16 images

The server accepts image URLs and base64 image data. Generated images are cached locally and returned as Markdown image URLs. Each image is limited to 20 MB.

## Local development

```bash
bun install
bun test
bun run build
```

To select environment and configuration files explicitly:

```bash
bun run src/index.ts --env-file .env --config config.local.json
```

## Troubleshooting

- Confirm that the environment variable in `.env` matches `apiKeyEnv`.
- If Cherry Studio cannot display an image, check that both processes run on the same computer and that the client can reach the local URL.
- Verify the API URL, model name, and timeout against the provider's documentation.