# Import text template artwork (`import_customiser_text_template_artwork`)

Imports an SVG staged with create_upload (purpose text_template_svg) as text template artwork: kind production for the Frame Fit metal artwork, which needs its physical size or width_mm, or kind graphic for a graphic area. The SVG is checked and normalised; scripts, styles and external references are refused. It returns the artwork id and sha256 to reference in update_customiser_text_template, and changes no template. It requires the customisers:write scope and an idempotency_key, and supports dry_run.

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

## Purpose

Add the SVG artwork a cut-out metal text template with Frame Fit references.

## Annotations

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

## Prerequisites

- An upload with purpose text_template_svg from create_upload, with its bytes sent.
- A cut-out metal customiser with Frame Fit pricing on a Store with text fields.
- A merchant has connected this store and approved the customisers:write scope.

## Side effects

- Spends the upload and stores the normalised SVG as a Store asset. The same file imported again returns the existing asset.

## Arguments

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `customiser_id` | integer | yes | The customiser id, from list_customisers. |
| `kind` | string | yes | production for the template production artwork, graphic for a graphic area. One of: `production`, `graphic`. |
| `upload_id` | string | yes | The upload id from create_upload. |
| `width_mm` | number | no | Production only: the width of a file without physical units, in millimetres, one decimal. |
| `idempotency_key` | string | unless `dry_run` is true | A client-generated key unique to this logical write, such as a UUID. Required: repeating the call with the same key and the same arguments replays the original result instead of writing twice, and the same key with different arguments is an idempotency_key_conflict. |
| `dry_run` | boolean | no | When true, the import is checked and nothing is written: the result is the same verdict the apply would have reached, and a problem the apply would have raised comes back as the same tool error. Defaults to false. A dry run claims no key. |

## Result

The artwork: id, sha256, width_mm and height_mm. A dry run checks the upload and the customiser without reading the file.

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `request_id` | string | yes |  |
| `store` | object | yes |  |
| `store.id` | integer | yes |  |
| `store.name` | string | yes |  |
| `customiser_id` | integer | yes |  |
| `kind` | string | yes | One of: `production`, `graphic`. |
| `artwork` | object | no | The imported artwork. Absent on a dry run. |
| `artwork.id` | string | yes |  |
| `artwork.sha256` | string | yes |  |
| `artwork.width_mm` | number | yes |  |
| `artwork.height_mm` | number | yes |  |
| `dry_run` | boolean | no | Present and true only when dry_run was requested. |
| `valid` | boolean | no | Present only on a dry run, and always true: a failing dry run returns a tool error instead. |
| `verdict` | object | no | Present only on a dry run: the validation verdict. |
| `idempotent_replay` | boolean | no | True when this call replayed a previously recorded response for the same idempotency_key instead of applying the write again. |

## Error cases

| Code | Recovery |
| --- | --- |
| `insufficient_scope` | The connection was approved without customisers:write. |
| `invalid_svg` | The error code names the rule the file broke. Fix the file and upload it again. |
| `rate_limited` | Wait retry_after seconds; the limit is 30 a minute. |
| `text_template_unsupported_sign` | Only cut-out metal with Frame Fit takes artwork. |
| `upload_purpose_mismatch` | Create a new upload with purpose text_template_svg. |
| `validation_failed` | An error at /width_mm (units_missing, width_mismatch, aspect_mismatch, frame_out_of_range) leaves the upload usable: retry with the right width_mm. |

## Example: Import production artwork without physical units

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "import_customiser_text_template_artwork",
    "arguments": {
      "customiser_id": 42,
      "kind": "production",
      "upload_id": "upl_9f2c4b7ad13e6058ba41cd4201",
      "width_mm": 600,
      "idempotency_key": "d3e4f5a6-7182-4c9d-8e0f-2a3b4c5d6e7f"
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "structuredContent": {
      "request_id": "req_01jz9x2k7c8f3m5n6p7q8r9s0t",
      "store": {
        "id": 12,
        "name": "Demo Signs"
      },
      "customiser_id": 42,
      "kind": "production",
      "artwork": {
        "id": "tas_abcdefghijklmnop",
        "sha256": "ec68d6053154d01f7161b2faba67f38e46584456c7303c6a5d66248b666debea",
        "width_mm": 600,
        "height_mm": 600
      },
      "idempotent_replay": false
    }
  }
}
```

## Example: An SVG with a script is refused (error)

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "import_customiser_text_template_artwork",
    "arguments": {
      "customiser_id": 42,
      "kind": "graphic",
      "upload_id": "upl_9f2c4b7ad13e6058ba41cd4201",
      "idempotency_key": "e4f5a6b7-8293-4dae-8f10-3b4c5d6e7f80"
    }
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "isError": true,
    "structuredContent": {
      "error": {
        "code": "invalid_svg",
        "title": "Invalid SVG",
        "detail": "The file contains a script.",
        "recovery": "The SVG failed the shape constraint named in detail. Correct the file and upload it again.",
        "errors": [
          {
            "pointer": "/upload_id",
            "code": "script_present",
            "detail": "The file contains a script."
          }
        ]
      }
    }
  }
}
```
