# Preview customiser icon (`preview_customiser_icon`)

Shows what the icon converter makes of one SVG drawing for a customiser before an icon is created from it: the drawing is sanitised, converted by the icon service and sanitised again, and the answer is the SVG an icon create would store as rendered_svg. Nothing is saved. It requires the customisers:read scope and has its own per-connection rate limit, separate from the option-write budget.

- Source URL: https://www.signcustomiser.com/help/mcp/tools/preview_customiser_icon/
- Markdown URL: https://www.signcustomiser.com/help/mcp/tools/preview_customiser_icon.md
- MCP endpoint: https://mcp.signcustomiser.com
- Required scope: `customisers:read`
- Behaviour: read

## Purpose

Check how a drawing will look as a customiser icon before creating the icon with create_customiser_option and option_type icon.

## Annotations

| Hint | Value |
| --- | --- |
| readOnlyHint | true |
| destructiveHint | false |
| idempotentHint | true |
| openWorldHint | false |

## Prerequisites

- A customiser id from list_customisers.
- A single SVG document of at most 512 KiB.
- A merchant has connected this store and approved the customisers:read scope.

## Arguments

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `customiser_id` | integer | yes | The customiser id, from list_customisers. |
| `svg` | string | yes | The drawing to preview, as one SVG document of at most 512 KiB. Scripts, event handlers and external references are removed before conversion. |

## Result

The customiser id and the converted SVG. The SVG is at most the size of the drawing the converter returns for one icon.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `request_id` | string | yes |  |
| `store` | object | yes |  |
| `store.id` | integer | yes |  |
| `store.name` | string | yes |  |
| `customiser_id` | integer | yes |  |
| `svg` | string | yes | The sanitised, converted drawing: what an icon create would store as rendered_svg. |

## Error cases

| Code | Recovery |
| --- | --- |
| `icon_conversion_failed` | The icon service could not be reached or could not convert the drawing. Nothing was saved; call the tool again. |
| `insufficient_scope` | The connection was approved without customisers:read. |
| `rate_limited` | The icon preview limit for this connection is spent. Wait retry_after seconds. |
| `resource_not_found` | No customiser with that id exists in this store. |
| `validation_failed` | The svg argument is not one SVG document, or nothing is left of it once scripts, event handlers and external references are removed (error code invalid_svg on /svg). Send a plain vector drawing. |

## Example: Preview a square icon

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "preview_customiser_icon",
    "arguments": {
      "customiser_id": 42,
      "svg": "<svg viewBox=\"0 0 24 24\"><path d=\"M4 4h16v16H4z\"/></svg>"
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "customiser_id": 42,
      "svg": "<svg viewBox=\"0 0 24 24\"><path d=\"M4 4h16v16H4z\"/></svg>"
    }
  }
}
```

## Example: A drawing with nothing safe left in it (error)

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "preview_customiser_icon",
    "arguments": {
      "customiser_id": 42,
      "svg": "<script>alert(1)</script>"
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "validation_failed",
        "title": "Validation failed",
        "detail": "The icon SVG could not be sanitised safely: nothing was left of it once scripts, event handlers, and external references were removed. Send a plain vector drawing.",
        "recovery": "Correct every field listed in errors, using its pointer to locate the value and allowed_values where one is given, then call the tool again.",
        "pointer": "/svg"
      }
    }
  }
}
```