内容
ultramock-mcp
允许 AI 代理（Claude Code、Claude Desktop 等）使用**您自己的登录订阅**创建和配置 [ultramock.io](https://www.ultramock.io) 产品模拟图。
Ultramock 目前在浏览器中使用 WebGL、canvas 和视频编码器 API 渲染最终图像/视频。公共应用程序不提供服务器端的“渲染和下载”端点。此 MCP 涵盖了可以通过 Ultramock 的 HTTP API 无头执行的操作：项目、模板、完整项目有效载荷/配置编辑、源资产上传和身份验证的源资产下载。
使用代理的 `get_capabilities` 查看当前机器可读形式。最终渲染的图像/视频导出仍然需要 Ultramock 添加服务器渲染 API 或无头浏览器自动化层。
## 工具列表
| 工具 | 功能描述 |
|------|--------------|
| `get_capabilities` | 报告哪些操作在无需浏览器情况下有效，以及为什么无法导出最终渲染结果。 |
| `get_status` | 获取 Ultramock 暴露的身份验证编辑器状态/帐户有效载荷。 |
| `list_projects` | 列出您的项目（id、名称、版本、编辑器 URL）。 |
get_project` | 获取一个项目的完整配置：拨号值、完整有效载荷、资产键/URL、编辑器 URL。 |
| `create_project` | 新建项目，可选地从模板中创建。 |
| `duplicate_project` | 复制项目，包括其配置和屏幕图像。 |
| `rename_project` | 重命名项目。 |
delete_project` | 删除项目）。 |
| `list_templates` | 系统 + 您的模板（与创建/应用结合使用）。 |
| `apply_template` | 将模板的设备/角度/照明应用于项目。 |
| `update_config` | 将拨号值（相机、场景、效果、设备、边框）合并到项目中。 |
| `update_payload` | 将任意 JSON 深度合并到完整项目有效载荷中，包括视口/时间线/编辑器设置。 |
| `set_screenshot` | 上传本地 PNG/JPG/WebP 作为设备上的屏幕内容。 |
| `set_scene_screenshot` | 上传本地 PNG/JPG/WebP 并将其分配给特定时间线场景。 |
| `set_background_image` | 上传本地 PNG/JPG/WebP 作为项目背景图像。 |
| `download_asset` | 下载源资产（屏幕图像、背景、场景截图）到本地文件。 |
| `get_editor_url` | 仅在需要视觉预览或最终渲染导出时打开的 URL。 |
### `update_config` 使用的拨号键
传递一个 `dials` 对象，其中包含 `key -> value`。只有您传递的键会更改。
- **camera**: `Viewport.camera.tiltX`, `.tiltY`, `.roll`, `.fov`, `.zoom`, `.panX`, `.panY`, `.flap`, `.flapX`
- **scene**: `Viewport.scene.bgMode`, `.darkMode`, `.bgColor` （十六进制），`.bgImage`, `.bgBlur`, `.transparentBg`, `.envId`, `.lightHeight`, `.lightPos`, `.lift`, `Viewport.devices.mockupModel`
- **device**: `Viewport.devices.mockupBgMode`, `.mockupBg`, `.mockupBgImage`, `.mockupPadding`, `.iphoneFinish`, `.statusBar`, `.hdrYaw`, `.contactShadow`, `.iblIntensity`, `.keyLight`, `.keyLightHeight`, `.keyLightRotation`
- **border**: `Viewport.border.borderRadius`, `.borderStyle`, `.glassWidth`
- **effects**: `Viewport.effects.depth`, `.sharpen`, `.vignette`, `.grain`, `.pixelGrid`, `.caStrength`, `.bloom`, `.bloomStrength`, `.bloomThreshold`, `.bloomRadius`, `.lighting`, `.lightingAngle`, `.lightingIntensity`, `.lightingSoftness`, `.reflection`, `.strength`
- **blur**: `Viewport.blur.mode`, `.strength`, `.falloff`, `.bokeh`, `.focusX`, `.focusY`, `.focusSize`, `.angle`, `.position`
使用 `update_payload` 来设置存储在 `payload.dialValues` 之外的设置，例如 `editorSettings`、`viewport`、`timeline.scenes`、文本/徽标场景数据和导出元数据。对象补丁会递归合并；数组和标量值会被替换。
## 安装
```bash
npm install
npm run build
```
### 获取会话令牌
身份验证使用您的 ultramock 登录 cookie（无单独的 API 密钥）。
1. 打开 <https://www.ultramock.io> 并登录。
2. DevTools → Application → Cookies → `https://www.ultramock.io`。
3. 复制 **`__Secure-authjs.session-token`** 的值（一个 UUID）。
该值是 `ULTRAMOCK_SESSION_TOKEN`。当您注销/会话过期（约 30 天）时，它会旋转；如果调用开始返回身份验证错误，请刷新它。
### 在 Claude Code 中注册
```bash
claude mcp add ultramock \
--env ULTRAMOCK_SESSION_TOKEN=<您的令牌> \
-- node /path/to/ultramock-mcp/dist/index.js
```
或将其添加到您的 MCP 配置（`~/.claude.json` / Claude Desktop `claude_desktop_config.json`）：
```json
{
"mcpServers": {
"ultramock": {
"command": "node",
"args": ["/path/to/ultramock-mcp/dist/index.js"],
"env": { "ULTRAMOCK_SESSION_TOKEN": "您的令牌" }
}
}
}
```
可选环境变量：`ULTRAMOCK_BASE_URL`（默认为 `https://www.ultramock.io`）。
## 典型代理流程
1. `get_capabilities` -> 确认无需浏览器即可执行的操作。
2list_templates` -> 选择外观（例如“逼真 iPhone”）。
3. `create_project` with `fromTemplateId` -> 获取项目 ID。
4. `set_screenshot`、`set_scene_screenshot` 或 `set_background_image` -> 上传源资产。
5. `update_config` 或 `update_payload` -> 调整相机、背景、效果、视口或时间线数据。
6. `download_asset` -> 如有需要，重新检索源资产。
7. `get_editor_url` -> 仅用于视觉预览或最终渲染图像/视频导出。
## 注意事项
- 写入操作amock 的租约 + 乐观版本模型；此服务器为您获取和释放编辑租约。如果另一个会话持有租约（例如，项目在浏览器选项卡中打开），服务器会接管它，并且该选项卡变为。
- `download_asset` 下载存储在项目上的源图像。它不会渲染合成的模拟图。
- 图像上传工具接受 PNG、JPG/JPEG 和 WebP 文件，最高可达 Ultramock 的 1 MB 上传限制。
- 我针对 Ultramock 的公共客户端捆绑包验证了当前应用程序行为：`/api/capture` 和 `/api/video-authorize` 授权导出，而最终图像/视频字节在浏览器中生成，并从本地 blob URL 下载。
