Dreambooth Studio

dreambooth-mcp

Dreambooth Studio 的 MCP 服务。通过封装仪表板已在使用的 Studio API，让 ChatGPT、Claude 和 Gemini 能回答运营者有关自己摊位的问题——“我在万隆的摊位本周表现如何？”

状态：已上线，地址为 https://mcp.dreamboothstudio.com/mcp（服务版本 0.3.0）。 支持 Streamable HTTP 和 stdio，共有 23 个工具——13 个只读工具、9 个用于创建或编辑内容的工具，以及 connect_account。已在官方 MCP Registry 中登记为 com.dreamboothstudio/dreambooth v0.1.0（Registry 版本不可变，因此该条目会一直保持为 0.1.0）。

十个工具始终会注册，无论在 stdio 还是在每个 HTTP 会话中：

connect_account	启动设备授权流程
只读	connection_status · get_sessions · get_gallery_stats · search_docs
只读	list_projects · get_project · get_revenue_summary · get_credits · get_wallet_transactions

session_info 是第十一个工具，仅在 MCP_DIAGNOSTICS=1 时注册。

每次连接还会列出另外十二个工具（这些工具受什么机制保护，见下文）：

创建	create_booth · start_booth · refine_booth · create_filter · duplicate_project
创建	start_frame · refine_frame · save_frame
编辑	update_booth_draft
只读	get_booth_draft · check_generation · preview_filter

第 3 阶段的安全加固现已上线，应用于 OAuth 路径：Studio 运行完整的 OAuth 2.1 授权服务器——仅支持 PKCE S256、访问令牌有效期为一小时、刷新令牌有效期为 30 天、动态客户端注册、RFC 8707 资源受众、RFC 7009 撤销，以及与 CSRF 绑定且会注明所授予作用域的同意页面。此服务位于其前方，作为受保护资源（RFC 9728）。 两份发现文档均已上线。

设备授权流程是较早的路径，保留了旧有特性——其令牌有效期为一年、没有作用域且无法撤销，因此不得用于写入。它确实无法写入：Studio 会以 403 拒绝该令牌，并在响应中说明修复方法；对仅具备读取作用域的 OAuth 令牌也是如此。

每个连接上的工具列表都相同。 过去，只有请求携带 bearer 时才会注册上述十二个工具，导致 tools/list 在没有 Authorization 标头时返回 10 个工具，而标头中只要有任意字符串就返回 22 个——检查的只是标头是否存在，而非其中的内容。这种做法已被移除。不断变化的工具清单无法使用：ChatGPT 提交门户会在浏览器中扫描且不带凭据，因此它只能看到只读工具，同时提交内容却声明了全部 22 个工具；任何缓存了登录前列表的客户端，也会继续向已连接账户的运营者提供十个工具。现在，这些工具的保护机制与过去实际决定结果的机制相同——AUTH_REQUIRED_TOOLS 会将未提供凭据的调用转换为启动 OAuth 流程的 401，而 Studio 会对没有 booths:write 权限的令牌返回 403。这里没有功能标志——本 README 的早期版本曾描述过一个功能标志，但现已移除；新工具的保护取决于部署顺序。请参阅连接账户。

设计文档：Studio 仓库中的 docs/dreambooth-mcp-design.md。ChatGPT 中的内嵌卡片： docs/apps-sdk-widgets-plan.md。

---

不提供的功能

此服务不包含数据库、业务逻辑或聚合计算。每个工具都会封装 Studio 已经开放的路由，因此“这位运营者的收入是多少”只有一种实现方式，且该实现位于 Studio 中。一旦在这里复制聚合逻辑，就会产生第二个事实来源并悄然出现偏差——最终会出现三个不同的收入数字，却无从判断哪个才正确。

此外，以下功能永久不在范围内：提现、收款账户、多因素身份验证/逐步验证、重新生成订阅令牌，以及 /api/admin 下的任何内容。

运行

npm install
cp .env.example .env

npm run dev               # Streamable HTTP on PORT (default 8080)
npm run dev:stdio         # stdio, for Claude Desktop

npm run build
npm run inspect           # stdio smoke: handshake, tools/list, widgets, every tool
npm run inspect:http      # HTTP smoke: sessions, isolation, unknown-session 404
npm run preview           # writes each widget state to .preview/ to open in a browser

inspect:http 会运行 dist/，因此请先运行 npm run build，否则你测试的将是上一次的构建，而不是你的更改。

两项冒烟测试都无需令牌。search_docs 无需身份验证，而需要身份验证的工具必须返回一条可读消息，指出应使用 connect_account，而不能崩溃——检查验证的内容也包括这条失败路径。

连接账户

两种传输方式都无需配置令牌。 操作员让助手发起连接；connect_account 会启动 Studio 已用于 Electron 展台的设备流程，并返回一个供其打开的 Google 链接（仅限 Google：Studio 会构建一个 accounts.google.com URL）。如果客户端通过自身的连接器设置登录（请求不带会话和凭据），则会收到 use_client_sign_in，且不会获得链接；该登录方式使用 Studio 的登录页面，支持通过电子邮件和密码以及 Google 登录。 工具会立即返回，并在后台轮询——如果工具调用阻塞数分钟，每个 MCP 客户端都会认为服务已挂起；等它们提出下一个问题时，令牌就已经就位。

本地开发也是如此。粘贴的令牌等同于会话凭据（有效期为一年、无作用域、无法撤销），会存放在磁盘上的文件中；在 HTTP 模式下，它还会将每个传入会话都验证为同一个账户。重启后在浏览器中批准只需约十五秒；这就是不保存令牌所付出的全部代价。

设备流程令牌按 MCP 会话保存在内存中。重启意味着所有人都要重新连接；对于这条路径，这是恰当的权衡：无需保护凭据存储。令牌本身仍等同于会话凭据——有效期为一年、无作用域、无法撤销。

变化之处在于，现在不再只有这一种接入方式。携带自身 Authorization: Bearer 的客户端走的是 OAuth 路径，令牌有效期为一小时，包含操作员按名称批准的作用域，并且可以通过 /api/oauth/revoke 撤销。这条路径完全不会在此处存储任何内容：凭据属于携带它的请求，绝不会写入会话，因此后续请求无法通过引用相同的会话 ID 读取它。

这两种凭据在允许执行的操作上有意保持不同。对于启用了连接器写入功能的路由，Studio 会拒绝设备流程令牌发起的非 GET 请求；较弱的凭据不能继承授予较强凭据的访问权限。展台集群使用该令牌发出的所有 POST 请求均不受影响。写入工具仍会在设备流程会话中列出，因为工具列表不能取决于凭据；在该会话中调用写入工具会返回 Studio 的 403 和相应提示，告知操作员应该怎么做。

两种情况下的读取权限均未改变：从未连接账户的会话只能读取 search_docs。

部署

按照 dreambooth-whatsapp 的方案部署到 Railway：使用 railway.json，运行 npm run build / npm start，在 /health 上进行健康检查，并设置为 ON_FAILURE 重启。无需 Dockerfile、CI 或卷——此服务是无状态的。

设置 DREAMBOOTH_API_URL 和 ALLOWED_HOSTS。无需配置令牌。 生产环境中不要设置 MCP_DIAGNOSTICS——请参阅工具部分。 仅在目录提交正在进行时设置 OPENAI_APPS_CHALLENGE——请参阅 docs/chatgpt-listing.md。

ALLOWED_HOSTS 必须列出两个公共主机名：

ALLOWED_HOSTS=mcp.dreamboothstudio.com,dreambooth-mcp-production.up.railway.app

即使附加了自定义域名，Railway 仍会继续提供其生成的主机名；DNS 重绑定保护使用的是允许列表，而非过滤器——只填写一个主机名，会导致另一个主机名访问 /mcp 时返回 400。无论哪种情况，/health 都会继续返回 ok，因为它在传输层之前注册，因此健康检查无法发现此问题。将此变量留空会完全禁用保护，而不是通过某种更安全的方式允许所有主机名。

发布到注册表

server.json 是注册表清单。条目无法取消发布，且每个版本都是不可变的——URL 变更或修正错别字，都意味着要发布一个新 version，绝不能编辑旧版本。

./mcp-publisher validate server.json    # checks against the live registry, publishes nothing
./mcp-publisher login dns --domain dreamboothstudio.com --private-key "$(openssl pkey -in key.pem -noout -text | grep -A3 priv: | tail -n +2 | tr -d ' :\n')"
./mcp-publisher publish

始终先执行 validate；在这一系列步骤中，只有这一步可以撤回。

com.dreamboothstudio 命名空间通过由 key.pem 签名的 TXT 记录进行证明，该记录位于根域名（dreamboothstudio.com，而不是 mcp 子域名）。该文件已加入 gitignore，且只保存在一台机器上。丢失它可以补救——生成新的 Ed25519 密钥对并替换 TXT 记录。泄露则无法补救：此仓库是公开的，任何持有该密钥的人都能永久以 com.dreamboothstudio/* 名义发布内容。

连接客户端

托管服务无需安装。在任何支持远程 MCP 服务的客户端中，将其指向：

https://mcp.dreamboothstudio.com/mcp

Claude Desktop

适用于运行本地检出版本——连接预览版 Studio 或某个分支。要使用已部署的服务，请改为添加上面的 URL；无需克隆任何内容。

将以下内容添加到 claude_desktop_config.json。必须使用 --stdio——入口点默认使用 HTTP；如果不加此参数，Claude Desktop 会启动 Web 服务，并无限期等待通过 stdin 收到回复。

{
  "mcpServers": {
    "dreambooth": {
      "command": "npx",
      "args": ["tsx", "src/index.ts", "--stdio"],
      "cwd": "/absolute/path/to/dreambooth-mcp",
      "env": { "DREAMBOOTH_API_URL": "https://dreamboothstudio.com" }
    }
  }
}

工具

工具	调用接口	身份验证
get_sessions	GET /api/sessions	Bearer
get_gallery_stats	GET /api/gallery	Bearer
search_docs	/docs-search-index-{locale}.json	无
list_projects	GET /api/projects	Bearer
get_project	GET /api/projects?id= + GET /api/device-monitoring	Bearer
get_revenue_summary	GET /api/me/revenue-summary	Bearer
get_credits	GET /api/credits	Bearer
get_wallet_transactions	GET /api/wallet-transactions	Bearer

以上就是完整的读取范围。另有两个工具会调用创建内容的路由：

工具	调用接口	身份验证
create_filter	POST /api/filters	Bearer + booths:write
duplicate_project	POST /api/projects?duplicate	Bearer + booths:write
start_frame	POST /api/ai/frames/start，然后调用 POST /api/ai/threads/{id}/messages	Bearer + booths:write
refine_frame	POST /api/ai/threads/{id}/messages	Bearer + booths:write
check_generation	无——读取此进程	Bearer
save_frame	POST /api/ai/frames/from-generation	Bearer + booths:write
preview_filter	GET /api/filters/preview	Bearer（只读权限即可）
start_booth	POST /api/onboarding/generate	Bearer + booths:write
refine_booth	POST /api/onboarding/generate（重新生成或重建）	Bearer + booths:write
create_booth	GET /api/onboarding/draft → GET by-slug?checkOnly → POST /api/onboarding/draft-frames → GET /api/onboarding/frames + /catalog（以及 /api/ai-effects/catalog）→ POST /api/projects/onboarding → GET by-slug	Bearer + booths:write
get_booth_draft	GET /api/onboarding/draft	Bearer（只读权限即可）
update_booth_draft	PATCH /api/onboarding/draft（命名效果时还会调用 /api/ai-effects/catalog）	Bearer + booths:write

**帧和展台工具的部署顺序很重要。**这些工具始终会列出——没有开关——而且会调用 Studio 中新增或新开放给 OAuth 的路由：/api/ai/frames/start、/api/ai/frames/from-generation、/api/ai/threads/{id}/messages、/api/onboarding/generate、/api/onboarding/draft-frames、/api/projects/onboarding、/api/filters/preview。应先部署 Studio 的相关变更，再部署包含这些工具的服务版本；否则，工具会返回一句说明 Studio 尚未更新的提示。展台生成还需要 Studio 的 digital_mode 功能上线（它是 /new 流程；未启用时，展台工具会说明这一点）。mcp-verify 技能中的 oauth-write-check.mjs 会执行一次真实调用；展台测试需加上 --booth。两者上线后运行一次该脚本。 帧生成是这里唯一既不是单次调用，也不是单次答复的流程。图像模型的一次往返需要 30–90 秒，而此服务的请求超时时间为 15 秒；提高超时时间也无济于事：阻塞这么久的工具调用，在所有 MCP 客户端看来都像是服务挂起了。因此，start_frame 和 refine_frame 会启动任务并返回一个任务 ID，check_generation 则会报告状态——其形式与 connect_account 已采用的设备流程相同。而且，一个提示词很少能一次到位，因此该流程采用了仪表板中的 Frame Studio 对话串：start_frame 会在空白模板上开启一个对话串并生成第一个版本，refine_frame 会在同一对话串中生成下一个版本（“更暗一些”“减少装饰”），只有 save_frame 才会将操作员选定的生成结果保存为其列表中的帧。在此之前，不会保存任何内容；工具描述、结果和预览卡片都会明确说明这一点，而不会让模型自行猜测。每次生成都会消耗账户每日免费额度的一部分，因此描述中会告知模型，绝不要主动反复迭代。

展位采用相同的流程，通过 /new 引导流程进行——Studio 根据一句描述设计整个展位（规格、手机和笔记本电脑的欢迎屏幕、展位内背景）并创建展位。start_booth 会创建一个草稿（draftId，耗时 60–120 秒，属于后台任务）；refine_booth 会根据指令重新绘制欢迎屏幕或展位内背景，或者根据新描述重建整个草稿；update_booth_draft 会修改无法通过重新绘制修改的内容——标题、链接名称、按钮文字、颜色、拍摄模式、语言、包含的帧和滤镜、AI 效果，以及仪表板编辑器提供的页面设置（照片数量、倒计时、超时、GIF/录制、重拍、结账、付款、结果）——这些内容会存储在草稿中，并在创建时由 Studio 应用；get_booth_draft 会在任务存储忘记草稿后读回草稿（草稿保留 7 天）；create_booth 是唯一会创建展位的步骤——它会先检查链接名称，绘制展位自己的三个帧，像 /new 一样选取三个入门帧和 Studio 的默认滤镜，并使用草稿中的设计、主题和拍摄模式创建展位。草稿 ID 是模型保留的普通值，因此对话可以超出此进程的生命周期；草稿会在 Studio 中保留七天。配额由 Studio 管理：每个草稿可完整生成 3 次、重新绘制 5 次，每个账户每小时可创建 10 个草稿。没有规格补丁路径——标题、主标题和颜色只能通过重新绘制或重建来更改；标题和链接名称只能在创建时确定。

滤镜会先预览，再创建：preview_filter 会请求 Studio 使用展位的真实滤镜处理流程来处理其示例照片（或操作员自己的预览照片），并返回一个 URL；create_filter 会保存相同的调整项。预览会显示 31 项调整中的 13 项，并说明哪些调整无法预览——展位会应用全部调整。

任务保存在此进程中，使用启动任务的 bearer 哈希作为键——绝不保存 bearer 本身，以免在任务存续期间持有操作员凭据。进程重启会导致运行中的任务丢失，轮询会据此说明情况，并引导用户前往仪表板，而不是报告一个可能从未发生的失败。运行第二个实例会导致轮询失效；届时需要使用共享存储来解决。

生成结果会使用 Studio 的空白模板（由服务端解析的 layout + shape），绝不会采用模型自行选择的宽度、高度或照片窗口。drawParams 是展位打印所遵循的约定，虚构的几何参数会生成并成功创建一个打印效果错误的帧——而这种失败不会报告任何信息。保存帧中的照片窗口会由与 /new 引导流程相同的服务端代码设置为透明。 **它们会在所有地方显示，但只能通过 OAuth 路径使用。**写入需要凭证，该凭证一小时后过期，带有作用域且可以撤销；设备流的令牌有效期为一年、没有作用域且不可撤销，也不得继承授予另一个令牌的访问权限。这条规则由能够实际评估它的 Studio 强制执行，因为只有 Studio 持有此服务器无法读取作用域的 next-auth JWE 密钥。请参阅其中的 utils/resolveAuthSession.ts，以及 docs/write-tools-plan.md。 在 2026-09-23 之前，这里也曾尝试实现这一规则：仅当请求携带 bearer 时才注册这些工具；这导致工具列表取决于 HTTP 标头，后来已移除。

没有任何工具会删除内容或涉及资金操作。StudioClient 上没有 put 或 delete；Studio 只向其开放了恰好八个 POST 处理程序 — /api/filters、/api/projects、/api/projects/onboarding、 /api/onboarding/generate、/api/onboarding/draft-frames、 /api/ai/frames/start、/api/ai/frames/from-generation 和 /api/ai/threads/{id}/messages。

有一项操作确实会编辑内容：update_booth_draft 会对 /api/onboarding/draft 发起 PATCH，这是 StudioClient 上唯一的 patch。它会修改尚未成为 booth 的草稿——草稿会保留 7 天，create_booth 仍然是创建真实 booth 的唯一步骤——但该功能上线后，“不会编辑任何内容”这句话就不再属实。

有两个工具不封装任何内容： connection_status（检查此会话是否已通过身份验证——由连接卡片轮询） 和 session_info（诊断信息，临时工具，且仅在 MCP_DIAGNOSTICS=1 时注册；待 widgets 计划中的会话连续性问题得到解答后将其删除）。

每个工具都带有 title、outputSchema，以及明确的 readOnlyHint / destructiveHint / openWorldHint 注释。这并非装饰：Anthropic Connectors Directory 和 ChatGPT plugin directory 都会标记缺少其中任一项的工具；而 session_info 默认关闭，因为评估目录条目时会检查其工具列表，且该工具回答的并非运营人员提出的问题。

输出 schema 刻意设置得宽松——Studio 管理的每个字段都是可选的。SDK 会根据 schema 验证 structuredContent，不匹配时会抛出 McpError，这属于协议错误；下方的规则 5 正是为了防止这种情况。Studio 重命名字段时，结果必须是缺少某个键，而不能导致工具失效。

内嵌卡片（ChatGPT）

connect_account 会显示一张真正的卡片——其中有一个 Google 按钮，能检测运营人员是否已完成授权——而不是一个需要他们复制的网址。根据 Apps SDK 的规范，它是一项 MCP 资源（ui://widget/connect-account.html），由工具上的 _meta 指向。

duplicate_project 会显示第二张卡片 ui://widget/write-result.html。它只显示结果，不包含其他内容：副本的名称、复制来源，以及指向其仪表盘页面的链接。没有确认卡片，也没有表单——小组件只有在工具完成写入后才会渲染；若要确认，就需要另一个不执行写入的工具，而真正的关卡是宿主自身的审批对话框。也没有“撤销”按钮：撤销意味着 PUT 或 DELETE，这会让单个按钮的权限范围从“创建”扩大到“更改和删除”。它的 CSP 未指定任何来源，因此它不可能与网络通信。

所有生成内容都会显示在第三张卡片中，即 ui://widget/generation.html——这是唯一一张 CSP 指定了来源的卡片，因为它会显示来自 Studio 存储空间的图像。从提出请求到内容生成完成：

• start_frame / refine_frame / start_booth / refine_booth / create_booth 会在任务运行期间立即返回，其卡片是动态的：显示正在制作内容的骨架（带有照片窗口的条幅、带有欢迎屏幕的手机），并在 iframe 内每隔几秒轮询 check_generation，任务完成后重绘为预览——操作员可以看着它逐渐呈现。check_generation 可供小组件调用，正是为此而设；不支持 callTool 的宿主只会让卡片停留在“处理中”。
• check_generation 会显示预览（边框图片；带有欢迎屏幕和调色板的展位草稿；带有缩略图和链接的已创建展位）。get_booth_draft 和 update_booth_draft 会渲染相同的草稿卡片，并标明已设置的内容和无法应用的内容。
• save_frame 会显示已保存边框的缩略图；create_filter 会在 Studio 的示例照片上显示已创建的滤镜（与 preview_filter 显示的渲染效果相同，保存后获取——尽力而为）；preview_filter 会显示预览，并标明无法呈现的调整项。

离开卡片时会通过宿主处理。卡片中的每个 https 链接都会通过 window.openai.openExternal 路由（宿主没有此 API 时，锚点会保留自己的 target="_blank"）；创建内容后，整张卡片都会变成链接：已创建的展位会打开其公开链接，已保存的边框、已创建的滤镜或已复制的展位会打开控制面板。草稿、预览和动态卡片不会变成链接——因为尚无可打开的内容。

这不会影响其他客户端。每个工具结果都会携带两份负载：供小组件使用的 structuredContent，以及以文本 content 格式化输出的同一对象，供 Claude 和 Gemini 使用；它们不会渲染小组件。文本块和以往完全相同。

小组件是独立的 HTML，两个域列表中的 CSP 均为空。这一点至关重要：无法访问网络的卡片就无法泄露操作员的会话令牌，而且卡片也无需访问网络，因为它的所有数据都通过服务端的 callTool 获取。请保持这种设计——需要的资源都内嵌。

设计令牌从 Studio 的 tailwind.config.js 手动复制到 src/ui/tokens.ts，因为沙盒 iframe 中没有 Tailwind。因此，这相当于设计系统的第二份副本；品牌色变更时，这里也必须同步更新。

get_project 报告的是 livenessTier，而非设备的 isOnline 字段。保留 isOnline 仅为向后兼容；它会把“因主动关机而暂时无响应”归为“离线”——这会让健康的设备群被报告为故障。

前三项无需更改 Studio。其余功能依赖的 Studio 改动现已完成：GET 请求访问 /api/projects、/api/credits 和 /api/wallet-transactions 时，支持通过 resolveAuthSession 使用 Authorization: Bearer（PUT 和 DELETE 则仍明确不支持，POST 也仅在上面提到的两个路由支持，且令牌必须带有 booths:write）；此外，GET /api/me/revenue-summary 是一个新的、限定所有者范围的端点——/api/analytics/revenue 受 superadmin 权限限制，操作员访问会收到 403。

get_wallet_transactions 和 get_revenue_summary 回答的是不同的问题，其描述也明确说明了这一点。钱包流水完全不包含现金和代金券收入，因此对于收取现金的操作员来说，它会低估实际收入——如果模型把它报告为“您的收入”，那就是自信地给出了错误答案。

身份信息绝不能作为参数。 没有任何工具接受 userId 或 email——操作员身份由服务端根据令牌解析，与 Studio 中的 lib/ai-chat 完全相同。需要这类参数的工具设计就是错误的。

添加工具的规则

1. 它封装现有的 Studio 路由。如果没有合适的路由，就在 Studio 中添加一个精简路由——不要在这里重新实现查询。
2. 描述应说明何时调用该工具，而不只是说明它会返回什么。模型仅根据描述来选择工具。
3. 返回最精简且有用的数据结构。get_gallery_stats 返回计数，而不是 12 个媒体 URL，因为模型不需要这些 URL，而且它们会占用上下文。
4. 只读工具应带有 annotations: { readOnlyHint: true }，以便客户端自动批准。写入工具不能带此标记，还必须声明 idempotentHint——create_filter 的值为 false，因为调用两次会创建两个筛选器，而重试超时请求的客户端需要了解这一点。
5. ownerEmail 不是参数。 Studio 的 POST 处理程序接受它，以供仪表板的协作者路径使用。转发它的工具会让调用方得以写入他人的账户，因此，工具请求体是逐字段构建的，而不是从 args 展开构建的。Studio 也会拒绝来自 bearer 的该参数；这两处限制都是有意为之。
6. 失败应作为 isError 内容返回，并附上一句模型可以转述的话——不要返回协议错误，因为那只会让客户端重试。对于写入操作，应转述 Studio 自己的消息：“此连接为只读，请重新连接并批准创建内容的权限”明确指出了要按哪个按钮。

说明

• stdout 是传输通道。 一条 console.log 就会破坏数据流，导致客户端因解析错误而断开连接。诊断信息应写入 stderr。
• 不要照搬 dreambooth-whatsapp 将 .env 提交到仓库的做法。这里面不应包含任何机密，而确保这一点的最佳方法就是永远不要开始这么做。