roastify-mcp

roastify-mcp

面向 Roastify Developer API 的 Tollbooth DPYC operator。Roastify 是一家白标咖啡代发货服务商：它负责烘焙、印制品牌包装，并直接发货给客户。

此 operator 可让 AI agent 读取 Roastify 商品目录、生成包装设计图稿，并在 patron 自己拥有的 GitHub repo 中维护私有设计库——费用以 Bitcoin Lightning 聪支付，无需账户、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 schema。
3. Secure Courier — 通过 Nostr DM 提交你的 BTCPay 密钥（btcpay_host、btcpay_api_key、 btcpay_store_id）。这些密钥会被安全保管，绝不会放进环境变量中。
4. 在 Pricing Studio 中设置价格 — 见下文。工具初始没有定价，因此无法调用。
5. 部署到 Prefect Horizon — fastmcp.json 已准备就绪。

获取 Pricing Studio

你的工具发布时尚未定价，没有价格的付费工具无人可调用。 Pricing Studio（iOS）是 operator 控制台：它会实时读取并写入 Neon 中的定价模型，因此价格不会存放在代码中——详见 tollbooth-pricing-studio。

这种间接方式正是设计所在。按工具动态定价——高峰加价、欢乐时段、忠诚度折扣、为首次 patron 提供免费试用——这些都是 DPYC 能提供，而固定付费墙无法实现的功能。

使用你自己的 Roastify 密钥

每位 patron 都通过 Secure Courier 提交自己的 Roastify API 密钥，并按 npub 分别安全保管。operator 不持有密钥，也没有备用路径。

这源于业务领域本身，而非政策选择。Roastify 会根据密钥关联的商家账户，对商品目录、已保存的设计和套餐级别进行限定——使用 Base 的 patron 看到的商品目录与使用 Pro 的 patron 不同。若由 operator 持有单一密钥，就会把某个商家的全部数据交给每位调用者；这不是需要设法绕过的限制，而是错误做法。这也意味着 operator 永远不会持有可能被滥用的凭据；在 Merchant App 中撤销你的密钥，即可切断访问权限，无需 operator 介入。

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 读写权限的细粒度令牌）、github_repo（owner/repo）和 github_branch（默认为 main），供设计库使用。

正式环境密钥以 rty_live_ 开头。沙盒密钥以 rty_test_ 开头，不会创建订单——适合用来测试读取工具，而不触及生产环境。

工具

工具	层级	功能
roastify_browse_catalog	读取	同时浏览产品和咖啡拼配目录，并标注套餐层级
roastify_get_catalog_product	读取	获取一个产品的变体、价格、库存和刀模模板
roastify_get_blend	读取	获取一种拼配：烘焙程度、是否脱因及变体
roastify_list_my_products	读取	列出已保存的 Roastify 产品，使用游标分页
roastify_get_my_product	读取	完整获取一个已保存的产品设计
roastify_check_stock	读取	查询一个 SKU 或整个列表的库存
roastify_generate_artwork	写入	根据已保存的设计生成 artwork
roastify_artwork_status	免费	检查该任务的状态
设计库
roastify_stash_design	写入	将设计保存到你的库中——相当于在你的 GitHub 仓库中提交
roastify_list_designs	读取	列出已保存的设计，仅含元数据，最新的排在最前
roastify_fetch_design	读取	完整获取一个已保存的设计，并重新内嵌图片（供快递员使用）
roastify_list_design_versions	读取	列出某个设计已提交的版本——即其 git 历史
roastify_delete_design	写入	删除一个已保存的设计
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 层只会多一个环节，不会增加判断能力，因此订单自动化有意留给 Shopify 和 Roastify 处理。

Artwork 生成是模板个性化，而非设计。 roastify_generate_artwork 会改写一个由你事先创作的 Roastify Design Studio 设计中指定的文本和图片占位符。它不能从零开始创作设计。

生成的 artwork URL 不会附加到任何内容上。 在 Roastify API 中，artwork URL 唯一的使用方是订单明细，而订单不在此处的范围内。你会收到一个 URL，并自行传递下去。我们有意接受这一衔接点；这并非疏忽，而且此操作工具不会模拟 API 无法完成的设计流程。

目录不包含风味数据。 产地、地区、海拔、处理方式和品种仅存在于 Merchant App UI 中。机器可读的信号只有 roastLevel、isDecaf、尺寸和价格；咖啡风味的其他信息都只是描述中的文字。因此，咖啡豆筛选能力比看起来要弱，而此操作工具也不会把大模型对描述的解读包装成结构化的产地数据。

设计库、传递器和 Design Bench

设计存放在赞助者拥有的 GitHub 仓库中，每个设计对应一个文件夹；运营方使用保管的令牌代表赞助者提交更改。每次保存都会创建一次提交，因此设计拥有真实的版本历史，赞助者也可以直接在 GitHub 中浏览、重命名或删除设计。

在 Roastify 产品中读取或写入设计需要使用商家的浏览器会话，没有任何 API 能提供这种能力。frontend/ 中包含两个相关部分：

• 传递器 — 由书签小工具注入 merchant.roastify.app 的脚本。它会将产品设计存入设计库，并将完成的设计应用回产品。它不包含任何编辑逻辑。
• Design Bench — 位于 roastify.tollbooth-dpyc.com 的 Web 应用，用于编辑设计。其 Cloudflare 函数会代理 /mcp，以便传递器能从商家站点的源访问此运营方。

Agent 使用 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，其自身规范将其标记为 beta，“可能会发生变化”。请做好跟进上游破坏性更改的准备，并在向第三方商家承诺提供此运营方的目录前权衡清楚。

许可证

Apache 2.0 — 参见 LICENSE。