MCP ツールでファイルを生成する

Bannerify の MCP サーバーには、6 つのツールがあります。アシスタントがリクエストに合わせてツールを選ぶので、ツール名を指定して呼び出すことはほとんどありません。どのツールも、接続したワークスペースに対してだけ動作します。まだの場合は、先にMCP クライアントを接続してください。

ツール

ツール	内容	生成として数えられるか	引数
list_templates	ワークスペースのテンプレートを一覧表示します。includeLayers を付けると、変更できるレイヤーも一覧表示します	数えられない	includeLayers（boolean、省略可）
get_template	1 つのテンプレートと、そのレイヤーを取得します	数えられない	templateId（string）
get_project	ワークスペースの ID、名前、プラン、作成日を取得します	数えられない	なし
create_image	テンプレートを描画し、画像を返します	数えられる	templateId（string）、modifications（object、省略可）、format（png、jpeg、webp、初期値は png）
create_pdf	テンプレートを PDF として描画し、そのリンクを返します	数えられる	templateId（string）、modifications（object、省略可）
create_image_from_shapes	テンプレートを使わず、図形から画像を組み立てます	数えられる	canvas（object、省略可）、shapes（array）、format（png、jpeg、webp、初期値は png）

テンプレート ID は、list_templates が返したとおりに使ってください。

テンプレートを探す

テンプレートと、そのレイヤーを頼みます。

Bannerify のテンプレートを、各テンプレートのレイヤーつきで一覧表示してください。

ツールは、テンプレートごとに 1 件ずつ返します。includeLayers がない場合、各件には ID と名前だけが入ります。付けた場合は、各レイヤーに、modifications で使う名前が付いてきます。

[
  {
    "id": "tpl_xxx",
    "name": "Lifecycle email",
    "layers": [
      { "name": "headline", "id": "shape:abc123", "type": "text", "suggestInput": "text" },
      { "name": "photo", "id": "shape:def456", "type": "image", "suggestInput": "src" },
      { "name": "qr", "id": "shape:ghi789", "type": "qrcode", "suggestInput": null }
    ]
  }
]

suggestInput は、設定するフィールドを示します。テキストレイヤーなら text、画像レイヤーなら src、それ以外の種類なら null です。名前のないレイヤーは Untitled と表示されます。

レイヤー名は、テンプレートエディターで付けます。レイヤーをダブルクリックして名前を変更します。名前とレイヤーがどう対応するかは、Modificationsで説明しています。

レイヤーの値を渡す

modifications は、レイヤー名をキーにしたオブジェクトです。文字列を渡すとレイヤーのテキストを設定し、オブジェクトを渡すとそのレイヤーのフィールドを設定します。REST API の配列形式は、ここでは使えません。

レイヤー	値の例
テキスト	{ "headline": "Summer sale" }
画像	{ "photo": { "src": "https://example.com/photo.png" } }
QR コード	{ "qr": { "qrcode": "https://example.com/restart" } }
表	{ "prices": { "columns": ["Plan", "Price"], "rows": [{ "Plan": "Automate", "Price": "$29" }] } }
すべてのレイヤー	{ "tag": { "visible": false } }

create_image の完全な例です。

{
  "templateId": "tpl_xxx",
  "format": "png",
  "modifications": {
    "headline": "Welcome back, An",
    "photo": { "src": "https://example.com/hero.png" },
    "qr": { "qrcode": "https://example.com/restart" }
  }
}

指定しなかったレイヤーは、テンプレートの値のままです。どのレイヤーにも一致しない名前は無視されます。レイヤーの種類ごとのフィールドは、Modificationsにまとめています。

結果を読む

create_image は、画像をインラインで返し、形式とバイト単位のサイズを示す 1 行を添えます。画像の表示や保存の方法は、クライアントが決めます。

create_pdf は、ファイルを保存してリンクを返します。

Generated a PDF from template tpl_xxx. Download: https://images.bannerify.co/files/mcp/0b3c1c1e-5d6f-4c52-9e0a-8f6a4c0f2a11.pdf

PDF はキャンバスと同じサイズの 1 ページで、テキストを選択して検索できます。詳しくはPDF の生成を参照してください。

テンプレートなしで画像を組み立てる

合うテンプレートがないときは、create_image_from_shapes を使います。キャンバスと図形のリストを渡すと、ツールが図形を順番に描画して画像を返すため、アシスタントは 1 回限りのバナーや請求書をデザインできます。

canvas オブジェクトは省略できます。次のフィールドを設定しない限り、1200 × 630 ピクセルの白い背景になります。

フィールド	説明
width, height	ピクセル単位のサイズ。各辺 16〜4096
background	単色。初期値は白です
backgroundImage	HTTPS URL、データ URL、または linear-gradient(to right, #4f46e5, #9333ea) のような CSS グラデーション。background より優先されます
objectFit	背景画像がキャンバスを埋める方法: cover（初期値）、contain、none

すべての図形には、type、x、y、width、height があり、キャンバスの左上からのピクセルで指定します。最初の図形が最背面で、最後の図形が最前面です。どの種類でも、さらに 3 つのフィールドが使えます。opacity（0〜1）、rotation（度、時計回り）、style です。

種類	必須	省略可
text	text	fontSize（初期値 24）、align（left、center、right）、lineClamp、color、fontFamily、fontWeight
frame	なし	backgroundColor、borderColor、borderWidth、borderRadius
image	src	objectFit（fill、contain、cover、none、scale-down、初期値は cover）、borderRadius
qrcode	qrcode	backgroundColor
barcode	barcode	なし
icon	icon	color
star	なし	star（1〜5、初期値 1）、color
table	columns、rows	footer、variant、stripe、compact、fontFamily、align（left、center、right）

いくつかのルールがあります。

• icon には、Iconoir の名前（例: check-circle、arrow-right）を指定します。Iconoir にない名前を指定すると、呼び出しは失敗します。
• src には、HTTPS URL またはデータ URL を指定します。リモート画像は、テンプレートと同じルールで読み込まれます。形式は PNG、JPEG、WebP、SVG で、ダウンロードに失敗すると FETCH_IMAGE_ERROR が返ります。
• 表は、すべての行に列ごとに 1 つの値を持ちます。行がオブジェクトになる modifications とは異なります。variant は、line、grid（初期値）、minimal、striped、compact、bordered、primary-header のいずれかです。
• style には、キャメルケースの CSS プロパティ名（例: padding、boxShadow、lineHeight、letterSpacing）を指定します。レンダラーが対応していないキーを指定すると、呼び出しは Unrecognized key メッセージで失敗します。サイズは、style ではなく width と height で指定します。
• color や borderRadius など、図形のフィールドは、style の同じキーより優先されます。
• 色には、16 進数の値、rgb()、hsl()、CSS の色名が使えます。

制限	値
図形	1〜100
キャンバス	各辺 16〜4096 ピクセル、合計 12,000,000 ピクセルまで
テキスト	4,000 文字
表	12 列、200 行
src と backgroundImage	8,192 文字
qrcode の値	2,000 文字
barcode の値	200 文字

請求書の完全な例です。

{
  "canvas": { "width": 800, "height": 560, "background": "#f8fafc" },
  "shapes": [
    { "type": "frame", "x": 0, "y": 0, "width": 800, "height": 120, "backgroundColor": "#0f172a" },
    { "type": "text", "x": 48, "y": 44, "width": 400, "height": 40, "text": "INVOICE", "fontSize": 30, "color": "#ffffff" },
    { "type": "text", "x": 500, "y": 52, "width": 252, "height": 24, "text": "INV-1042", "fontSize": 18, "align": "right", "color": "#94a3b8" },
    {
      "type": "table",
      "x": 48,
      "y": 176,
      "width": 704,
      "height": 180,
      "columns": ["Item", "Qty", "Total"],
      "rows": [["Logo pack", 1, "$29.00"], ["Banner credits", 500, "$19.00"]],
      "footer": ["", "Due", "$48.00"],
      "variant": "striped",
      "compact": true
    },
    { "type": "text", "x": 48, "y": 392, "width": 300, "height": 28, "text": "Thank you for your business.", "fontSize": 16, "color": "#475569" },
    { "type": "qrcode", "x": 632, "y": 384, "width": 120, "height": 120, "qrcode": "https://bannerify.co/invoices/1042" }
  ]
}

Bannerify は、描画の前にリクエスト全体を検証するため、無効なリクエストは生成を消費しません。有効なリクエストは、テンプレートからの生成と同じように数えられます。詳しくはクォータと制限を参照してください。

エラーを処理する

失敗した呼び出しは、isError: true と、次のいずれかの形式のテキストメッセージを返します。

形式	意味
CODE: message（例: NOT_FOUND: template tpl_xxx not found）	Bannerify からのエラーです。コードは次の表にまとめています
Invalid arguments. <field>: <message>	引数がツールと一致していません。メッセージにフィールド名が示されます。この形式にはコードがありません

コード	意味	対処
NOT_FOUND	このワークスペースにテンプレートが存在しません。別のワークスペースのテンプレートも見つかりません	list_templates を実行し、結果の ID を使います
USAGE_EXCEEDED	ワークスペースが、月間または日次の生成回数の上限に達しました	次の期間まで待つか、クォータと制限を参照します
BAD_REQUEST	create_image_from_shapes の色またはスタイルの値が無効か、modifications の値がレイヤーのフィールドに合っていません	メッセージに示された値を修正します。modifications の場合、メッセージには、オブジェクト内のレイヤーの位置が 0 から数えて示されます（例: modifications[0].src）
FETCH_IMAGE_ERROR	画像をダウンロードできなかったか、サイズが大きすぎてデコードできません	画像を返す公開 URL を使います
INTERNAL_SERVER_ERROR	描画に失敗したか、icon の名前が Iconoir に存在しません	もう一度試し、アイコン名を確認します

トークンがない、または期限切れの場合は、ツールが実行される前に、エラー invalid_token を伴う HTTP 401 が返ります。そのため、ツールが UNAUTHORIZED を返すことはありません。その後、クライアントがもう一度サインインします。MCP サーバーにはリクエストのレート制限がないため、RATE_LIMITED と TOO_MANY_REQUESTS は発生しません。REST API のコードは、エラーの処理にまとめています。

関連情報

• MCP クライアントを接続する
• Modifications
• レイヤーの種類