ridvay-mcp

ridvay-mcp

MCP（Model Context Protocol）服务，让 AI 助手——Claude Code、Claude Desktop、 GitHub Copilot（VS Code Agent 模式）、Cursor，以及任何其他 MCP 客户端——能够直接通过聊天 创建和编辑 Ridvay Studio 海报、传单和社交媒体设计。

每个设计完成后，都会返回一个可用的分享链接（ridvay.com/d/…），以及在 Studio 编辑器中打开和 编辑该设计的链接。

托管端点（无需安装）

同一服务也运行在 **https://mcp.ridvay.com**（可流式传输的 HTTP）上。有两种身份验证方式：

• 在 URL 中使用密钥 — 适用于通过 URL 添加连接器且无法设置标头的客户端（claude.ai 自定义连接器、ChatGPT 连接器）：https://mcp.ridvay.com/mcp/sk-ridvay-…。请像保护密钥本身一样保护该 URL；你可以随时在 ridvay.com/user/api-keys 撤销它。
• Bearer 标头 — 适用于支持标头的客户端：https://mcp.ridvay.com/mcp，并使用 Authorization: Bearer sk-ridvay-…。Claude Code：claude mcp add --transport http ridvay https://mcp.ridvay.com/mcp --header "Authorization: Bearer sk-ridvay-…"。
• 无需账户即可试用 — https://mcp.ridvay.com/mcp/demo 是一个沙盒：无需密钥，无需注册，仅提供免费工具（设计指南、组合设计、渲染、导出 PNG、分享）。在此创建的设计是公开的，也可能会被删除；使用频率受网络限制。Claude Code：claude mcp add --transport http ridvay-demo https://mcp.ridvay.com/mcp/demo。
• 登录（OAuth 2.1） — 适用于支持 MCP OAuth 的客户端（claude.ai 自定义连接器、ChatGPT 连接器/插件、Claude Code、Cursor、MCP Inspector）：添加 https://mcp.ridvay.com/mcp，无需密钥。客户端会发现 api.ridvay.com 是授权服务器，注册自身（动态客户端注册）或提供客户端 ID 元数据文档，并将你带到 ridvay.com/oauth/consent 以供批准。收到的令牌是一个普通的 Ridvay API 密钥，名称为“ (OAuth)”，因此你可以随时从账户页面撤销它（客户端也可以调用撤销端点）。

实时设计工具（0.6.0）

list_designs、share_design（查看 / 编辑 / 实时图片 / 屏幕链接）、get_values 和 set_values （更新设计中声明的 {{variables}} ——例如菜单板或价目板；它会在 /screen/<id> 页面和 /img/<id>.png 实时图片上自动刷新），以及 list_brands（将 brand_id 传递给 generate_poster）。

工作原理

该 GIF 的每一帧都由此 MCP 服务设计并渲染——一个由设计 IR 组合而成的四页设计，使用 create_poster 保存，然后逐页使用 export_poster 导出。无需录屏，也无需图像编辑器。

工具

工具	功能
get_design_guide	从这里开始 — 设计 IR 编写规范（元素类型、背景、字体、完整示例），指导你的助手自行构建设计。
create_poster	首选方式： 由你的助手将设计构建为 Ridvay 设计 IR，Ridvay 只负责存储、渲染和分享。快速、免费，创作自由度高。
generate_poster	备用方式：Ridvay 根据文本简介设计海报（速度较慢，会消耗账户的生成额度）。
recreate_poster	将现有设计图片（海报照片、屏幕截图、导出文件——文件路径或 URL）转换为可编辑设计：文本变为可编辑内容，形状变为矢量图，图像将重新渲染。速度较慢（1–4 分钟），会消耗生成额度。
refine_poster	使用自然语言编辑现有设计（design_id、instruction）。
check_poster	报告设计的 AI 图像是否已完成渲染，并返回其链接和浏览次数（Views: N）。
export_poster	将设计渲染为可下载的原始像素尺寸 PNG/JPEG（scale 为 1–4，默认为 2）。
animate_poster	添加动态效果（入场/退场、页面过渡、变形）——留空可使用雅致的默认效果，也可以自行描述。
export_video	将动态设计渲染为可下载的 H.264 MP4（可选循环播放的配乐）。
check_export	轮询异步 export_poster / export_video 任务，获取其下载 URL。

你的 AI 客户端负责设计；Ridvay 是保存、渲染和分享的后端。客户端编写的 设计仍可包含 prompt 图像占位符——创建后，Ridvay 会在服务端渲染这些占位符。 当助手无法自行构建设计时，仍可使用 generate_poster。

导出与动态效果： export_poster 会生成实际尺寸的海报图片 （例如，1080×1350 的 PNG），而不是分享页面。若要添加动画，可以在构建设计时加入动态效果字段 （参见指南），也可以调用 animate_poster，然后使用 export_video 导出 MP4。

size 支持 1080x1080（默认）、1080x1920 / story、1080x1350、1920x1080、 a4、slide 或任意 WxH。

实时图像

每个已分享设计都会获得一个始终更新的图像 URL——每次获取时都会重新解析设计的实时数据绑定（{{time.now}}、倒计时、JSON 源、声明的 {{vars}}）， 因此嵌入的图像不会过时（最多每 60 秒重新渲染一次）：

https://ridvay.com/img/{designId}.png

声明的变量会从查询参数中填充，因此只需一个 URL，就能通过 ESP 的合并标签生成个性化电子邮件图片：

https://ridvay.com/img/abc123.png?name=*|FNAME|*

支持 .jpg 变体以及 page、scale、w 和 quality 参数——绑定格式请参阅 get_design_guide（“实时数据绑定 + 实时图像 URL”），其中也列出了不能同时用作绑定/变量键的保留参数名称。

每次加载实时图像以及每次查看 /d/ 分享页面，都会计入设计的浏览次数——check_poster 会以 Views: N 的形式报告。

获取 API 密钥

登录并在 ridvay.com/user/api-keys 创建密钥。 通过 MCP 生成的设计会显示在你自己的 My designs 中。

快速开始

Claude Code

claude mcp add --scope user ridvay --env RIDVAY_API_KEY=sk-ridvay-… -- npx -y ridvay-mcp

Claude Desktop — 添加到 claude_desktop_config.json （macOS：~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "ridvay": {
      "command": "npx",
      "args": ["-y", "ridvay-mcp"],
      "env": { "RIDVAY_API_KEY": "sk-ridvay-…" }
    }
  }
}

VS Code / GitHub Copilot Agent 模式 — 添加到用户的 mcp.json （命令面板 → “MCP: Open User Configuration”），然后在 Copilot Chat 工具选择器中启用 ridvay：

{
  "servers": {
    "ridvay": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "ridvay-mcp"],
      "env": { "RIDVAY_API_KEY": "sk-ridvay-…" }
    }
  }
}

然后可以向你的助手提出以下请求：

为我们的周末限时促销生成一张故事尺寸的海报——所有商品优惠 30%，仅限周六。

示例

直接根据简报制作海报

为我们的周末限时促销制作一张适合 Story 尺寸的海报——全场商品 7 折，仅限周六。

端到端制作促销视频——设计、动画和 MP4，一次完成：

使用 ridvay MCP，围绕 [主题] 创建一个 3 页、1080x1920 的促销视频设计。第 1 页：醒目的开场。第 2 页：配有强调色条的三到四个要点。第 3 页：一个完整示例加上行动号召。深海军蓝背景、蓝色点缀、Poppins 标题。然后为其添加节奏明快的交错入场动画和变形转场，并渲染为 MP4。

让现有设计重新变得可编辑

将 ~/Desktop/last-years-flyer.png 重新制作为可编辑设计，然后把日期改为 10 月 3 日，并将标题设为我们的品牌蓝。

永不过时的图片——每次获取时都会解析实时绑定：

制作一张 1080x1080 的状态卡片，包含今天的日期以及距离我们 9 月 1 日发布还有多少天，然后给我实时图片 URL。

视频示例的详细演示（包含 Agent 实际调用的工具顺序）见博客：Ridvay MCP：通过 Claude Code 免费生成 AI 设计。

环境变量

变量	必填	含义
RIDVAY_API_KEY	是	你的 Ridvay API 密钥（sk-ridvay-…）。
RIDVAY_API_URL	否	默认值为 https://api.ridvay.com。
RIDVAY_WEB_URL	否	返回链接的基址，默认值为 https://ridvay.com。
RIDVAY_SUB_USER_ID	否	仅限管理员/平台密钥：代表特定用户执行操作。

行为说明

• 分享： 默认情况下，generate_poster / create_poster 会创建未公开列出的公开分享链接，因此聊天回复中会包含可用的 /d/{id} URL。传入 share: false 可将设计设为仅对你的账户私有（只返回 Studio 编辑链接）。
• 延迟生成图片： 布局就绪后即会返回生成结果；AI/图库图片会在服务器端后台渲染（约 1 分钟）。check_poster 会报告进度，并在需要时重新触发渲染。

遥测

MCP 中的内容和使用数据（例如提示词和生成的设计）可能会用于改进 Ridvay 的产品、服务和 AI 功能。请求包含基本归属信息：连接的 MCP 客户端名称/版本，以及在助手提供可选的 agent_model 参数时，创作设计所用的模型 ID。

开发

npm install
npm run build     # emits dist/
npm test          # vitest unit suite
node dist/index.js  # run the stdio server directly (needs RIDVAY_API_KEY)

MIT © Ridvay