roastify-mcp

roastify-mcp

Roastify Developer API 用の Tollbooth DPYC オペレーターです。Roastify はホワイトラベルのコーヒーのドロップシッピングサービスです。コーヒーを焙煎し、ブランド入りのパッケージを印刷して、お客様に直接配送します。

このオペレーターを使うと、AI エージェントは Roastify のカタログを閲覧し、パッケージ用アートワークを生成して、利用者が所有する GitHub リポジトリにデザインの非公開ライブラリを保管できます。支払いは Bitcoin Lightning の satoshi で行い、アカウントも KYC もサブスクリプションも不要です。

構築するもの

      YOU (operator, human in the loop)
        │                         │
        │ set & tune prices       │ drive credential intake
        ▼                         ▼
  ┌───────────────┐        ┌──────────────────────────────────────────────┐
  │ Pricing Studio│ prices │        Roastify — YOUR OPERATOR MCP           │
  │    (iOS)      ├───────▶│        FastMCP · deployed on Horizon          │
  └───────────────┘  Neon  │  ┌────────────────────────────────────────┐  │
                           │  │ roastify domain module ◀─ Roastify API  │  │
   Patron (Citizen)        │  │ @runtime.paid_tool(FROZEN_UUID) tools   │  │
   + MCP client  ─────────▶│  ├────────────────────────────────────────┤  │
   (Claude, etc.)  npub    │  │ tollbooth-dpyc SDK (the wheel)          │  │
                    +sats  │  │  ledger · vault (AES-256-GCM) · pricing │  │
                           │  │  /ConstraintGate · Secure Courier·audit │  │
                           │  └────────────────────────────────────────┘  │
                           └───┬─────────┬──────────┬───────────┬─────────┘
                               ▼         ▼          ▼           ▼
                         Neon Postgres  BTCPay▶  Sponsor     Nostr relays
                         (your schema)  Lightning Authority   proofs·courier
                         ledger+pricing invoices  certify +    DMs·audit
                                                  provision        │
                     api.roastify.app ◀── domain      │            ▼
                     (each patron's         calls      └──▶ DPYC Oracle +
                      own API key)                          dpyc-community

オンボーディングのロードマップ

1. Nostr キーペア — 生成します（nak key generate）。nsec は唯一の環境変数です： TOLLBOOTH_NOSTR_OPERATOR_NSEC。
2. Sponsor Authority — 登録すると、Neon スキーマが自動的にプロビジョニングされます。
3. Secure Courier — BTCPay のシークレット（btcpay_host、btcpay_api_key、 btcpay_store_id）を Nostr DM で送信します。シークレットは保管され、環境変数には設定しません。
4. Pricing Studio で価格を設定 — 下記をご覧ください。ツールは価格が設定されるまで、価格なしで呼び出せません。
5. Prefect Horizon にデプロイ — fastmcp.json の準備ができています。

Pricing Studio を入手する

ツールは価格が未設定の状態で提供され、価格のない有料ツールは誰も呼び出せません。 Pricing Studio（iOS）はオペレーターコンソールです。Neon の価格モデルをリアルタイムで読み書きするため、価格をコードに含める必要はありません。詳しくは tollbooth-pricing-studioをご覧ください。

この間接化が重要です。ツールごとの動的な価格設定、つまりサージ価格、ハッピーアワー、ロイヤルティ割引、初めての利用者向け無料トライアルは、固定価格のペイウォールでは実現できない DPYC の機能です。

Roastify のキーは各自で用意

各利用者は自分自身の Roastify API キーを Secure Courier 経由で送信し、npub ごとに保管します。オペレーターが保有するキーも、代替手段もありません。

これはポリシー上の選択ではなく、サービスの仕様によるものです。Roastify は、キーに紐づく販売者アカウントに応じてカタログ、保存済みデザイン、プランの階層を設定しています。そのため、Base の利用者が見るカタログは Pro の利用者とは異なります。オペレーターが単一のキーを保有すると、ある販売者の環境をすべての呼び出し元に渡すことになり、対処すべき制約ではなく、誤った設計になります。また、このオペレーターは悪用可能な認証情報を保持しません。Merchant App でキーを取り消せば、オペレーターを介さずにアクセスを遮断できます。

roastify_get_patron_onboarding_status   # what's missing
roastify_request_patron_credentials     # → you get a Nostr DM
   (reply with your Roastify API key)
roastify_receive_patron_credentials     # vaulted, encrypted at rest

同じ返信に、デザインライブラリに必要な任意の github_token（Contents の読み取り／書き込み権限を持つ fine-grained token）、github_repo（owner/repo）、github_branch（デフォルトは main）を含めることもできます。

本番用キーは rty_live_ で始まります。サンドボックス用キーは rty_test_ で始まり、注文の履行には使われません。本番環境に触れずに読み取りツールを試す場合に便利です。

ツール

ツール	ティア	機能
roastify_browse_catalog	読み取り	プランのティアを示しながら、商品とコーヒーブレンドをまとめてカタログ表示します
roastify_get_catalog_product	読み取り	1つの商品について、バリエーション、価格、在庫、型抜きテンプレートを取得します
roastify_get_blend	読み取り	1つのブレンドについて、焙煎度、デカフェかどうか、バリエーションを取得します
roastify_list_my_products	読み取り	保存済みのRoastify商品を、カーソル方式でページネーションして取得します
roastify_get_my_product	読み取り	保存済みの商品デザイン1点の全情報を取得します
roastify_check_stock	読み取り	1つのSKUまたは全商品の在庫を確認します
roastify_generate_artwork	書き込み	保存済みのデザインからアートワークを生成します
roastify_artwork_status	無料	そのジョブのステータスを確認します
デザインライブラリ
roastify_stash_design	書き込み	デザインをライブラリに保存します — GitHubリポジトリへのコミットです
roastify_list_designs	読み取り	保存済みデザインのメタデータのみを、新しい順に取得します
roastify_fetch_design	読み取り	保存済みデザイン1点の全情報を取得します。画像は再びインライン化されます（クーリエ向け）
roastify_list_design_versions	読み取り	デザインのコミット済みバージョンを取得します — Gitの履歴です
roastify_delete_design	書き込み	保存済みデザインを1点削除します
roastify_get_design_text	読み取り	デザインの編集可能なテキストレイヤーと、各レイヤーのサイズを取得します
roastify_update_design_text	書き込み	テキストを編集し、新しいバージョンをコミットします
roastify_add_design_element	書き込み	テキストまたは画像の要素を追加し、新しいバージョンをコミットします
roastify_move_elements	書き込み	要素のグループを移動またはサイズ変更し、新しいバージョンをコミットします
roastify_set_product_description	書き込み	保存済みデザインの商品に、ストアページ用の説明を設定します

標準のDPYCカタログ（残高、購入、クーリエ、価格設定、Oracle、ステータス）も利用できます。

このオペレーターが行わないこと、その理由

商品の作成、更新、削除、同期はできません。 これは機能の欠落ではありません — Roastify APIにそのようなエンドポイントがありません。/v1/productsは読み取り専用であり、OpenAPI仕様のどこにもintegration、sync、shopify、uploadという語は登場しません。保存済み商品とストアフロントの同期は、設計上Merchant Appの機能です。

注文は行いません。 Roastifyはすでに注文を自社の業務に振り分け、追跡情報をストアフロントに返しています。その間にMCPレイヤーを挟んでも、判断力が加わらず、手順が1つ増えるだけなので、注文の自動化は意図的にShopifyとRoastifyに任せています。

アートワークの生成はテンプレートのパーソナライズであり、デザインではありません。 roastify_generate_artworkは、Roastify Design Studioですでに作成したデザインにある、指定されたテキストおよび画像のプレースホルダーを書き換えます。デザインをゼロから作成することはできません。

生成されたアートワークのURLは、何にも添付されません。 Roastify APIでは、アートワークURLを使うのは注文の明細のみであり、注文はこの機能の対象外です。URLを受け取り、その後はご自身で引き継いでください。この境界は意図的に受け入れているものであり、見落としではありません。このオペレーターは、APIが完了できないデザインフローをシミュレートしません。

カタログに味わいのデータはありません。 産地、地域、標高、精製方法、品種はMerchant AppのUIにしかありません。機械可読な情報はroastLevel、isDecaf、サイズ、価格です。コーヒーの特徴に関するそれ以外の情報はすべて、説明文に記載された文章です。そのため、豆の選定能力は見かけより限定的です。このオペレーターは、LLMによる説明文の解釈を、構造化された由来データのように装うことはしません。

デザインライブラリ、クーリエ、Design Bench

デザインは、依頼者が所有する GitHub リポジトリに保存されます。デザインごとにフォルダーがあり、オペレーターは保管されたトークンを使って依頼者に代わりコミットします。保存するたびにコミットが作成されるため、デザインには実際のバージョン履歴が残り、依頼者は GitHub 上でデザインの閲覧、名前の変更、削除を行えます。

Roastify 製品上のデザインの読み取りや書き込みには、販売者自身のブラウザーセッションが必要ですが、それを提供する API はありません。そのため、frontend/ には次の 2 つが含まれています。

• クーリエ — ブックマークレットが merchant.roastify.app に挿入するスクリプトです。製品のデザインをライブラリに保存し、完成したデザインを製品に適用します。編集ロジックは持ちません。
• Design Bench — デザインを編集するウェブアプリ（roastify.tollbooth-dpyc.com）です。その Cloudflare 関数が /mcp をプロキシするため、クーリエは販売者のオリジンからこのオペレーターにアクセスできます。

エージェントは roastify_get_design_text と roastify_update_design_text を使ってデザインのテキストを編集し、人間がクーリエを使って新しいバージョンを適用します。

アートワークの生成は非同期です

Roastify は独自のサーバーでアートワークをレンダリングするため、roastify_generate_artwork はジョブ ID をすぐに返し、roastify_artwork_status でステータスを確認します。ステータスの確認は無料です。作業が完了したことは確認すれば分かります。その確認のたびに課金すると、待つことに課金することになります。

job = roastify_generate_artwork(product_id=..., fields=[...], client_req_id="my-req-1")
roastify_artwork_status(job_id=job["job_id"])   # free, poll until artwork_url appears

client_req_id を渡すと、同じリクエストを繰り返しても安全です。これは Roastify の Idempotency-Key になるため、アートワークが二重に生成されることはありません。

オペレーター自体は待機せず、どちらの呼び出しもすぐに返るため、ここに分離された実行機構はなく、再利用するものもありません。この仕組みが必要になるのは、オペレーターがアートワークを自らレンダリングするようになった場合だけです。

開発

pip install -e ".[dev]"
ruff check .
pytest -v
python -m roastify_mcp.server   # needs TOLLBOOTH_NOSTR_OPERATOR_NSEC to fully run

上流の状況

Roastify の API バージョンは 0.3.1 で、同社の仕様では **ベータ版、「変更される可能性あり」**とされています。上流での破壊的変更への対応が必要になることを想定し、このオペレーターのカタログをサードパーティの販売者に提供する前に、その点を考慮してください。

ライセンス

Apache 2.0 — LICENSE を参照してください。