mcp-ikaos-story

用于通过 Codex 或 Claude Code 创建和修改 iKAOS Story 原型内容的 Stdio MCP 服务器。

该 MCP 与经过身份验证的 iKAOS Story API 通信。用户无需克隆 ikaos-content-studio-v2026 或配置本地仓库路径。Story 内容/布局 JSON 存储在 Supabase 中，而固定的工作流文档和源元数据在 API 后端保持只读。

边界

• get_story_context 返回当前内容修订版和权威的 docsLink。

• save_story_content 仅写入 content_data；源数据、文档、Story 身份和生产元数据无法更改。

• 每次内容写入都需要精确的当前修订版。过期的编辑会返回冲突，而不是覆盖较新的内容。

• 图像生成不在范围内。设计人员可以通过 df-sheet 存储上传、替换、整理和删除提供的图像文件。

• 不会向 MCP 用户分发 Supabase 服务密钥。

安装

npm install
npm run build

配置 Story API：

export IKAOS_STORY_API_URL=https://your-ikaos-preview.vercel.app
export IKAOS_STORY_API_TOKEN=your-project-scoped-api-token
export IKAOS_STORY_PREVIEW_URL=https://your-ikaos-preview.vercel.app

图像工具还需要：

export DF_SHEET_URL=https://your-df-sheet.vercel.app
export DF_SHEET_PROJECT_ID=your-project-uuid
export DF_SHEET_ACCESS_TOKEN=your-df-login-review-access-token

IKAOS_STORY_PREVIEW_URL 是可选的，默认为 http://localhost:3000。DF_SHEET_ACCESS_TOKEN 目前是一个短期的 df-login 审查访问令牌。切勿提交任何令牌。

Codex

codex mcp add ikaos-story \
  --env IKAOS_STORY_API_URL=https://your-ikaos-preview.vercel.app \
  --env IKAOS_STORY_API_TOKEN=your-project-scoped-api-token \
  --env IKAOS_STORY_PREVIEW_URL=https://your-ikaos-preview.vercel.app \
  -- node /absolute/path/to/mcp-ikaos-story/dist/src/index.js

当需要图像工具时，将三个 DF_SHEET_* 环境变量值添加到同一命令中。使用 codex mcp list 或 /mcp 进行验证。

Claude Code

claude mcp add --transport stdio \
  --env IKAOS_STORY_API_URL=https://your-ikaos-preview.vercel.app \
  --env IKAOS_STORY_API_TOKEN=your-project-scoped-api-token \
  --env IKAOS_STORY_PREVIEW_URL=https://your-ikaos-preview.vercel.app \
  ikaos-story -- node /absolute/path/to/mcp-ikaos-story/dist/src/index.js

当需要图像工具时，添加三个 DF_SHEET_* 环境变量值。使用 claude mcp list 或 /mcp 进行验证。

工具

内容工作流

1. 调用 get_story_context。

2. 打开 docsLink，并使用 get_story_rules 阅读所需的固定规则。

3. 仅修改返回的 currentData.data 内容/布局对象。

4. 使用未更改的 Story ID 和 currentData.revision 调用 save_story_content。仅当 Story 尚无内容时才使用 null。

5. 调用 validate_story，然后在 390px 和 1280px 下检查返回的预览 URL。

如果另一个客户端先保存了，请获取最新的上下文并有意合并。未经审查较新的内容，不要使用替换后的修订版重试。

图像工作流

1. 从 Story 内容中选择一个有效的 imagePromptPackages[].inputBrief.slotId。

2. 使用本地图像的绝对路径调用 upload_story_image。

3. 在 Story 内容中使用返回的 imageUrl，并使用 save_story_content 保存。

4. 调用 update_story_image 更改元数据或替换文件。替换会先上传，并且仅在上传成功后才删除旧文件。

5. 仅在确认图像 ID 后调用 delete_story_image。删除会移除 R2 对象，并且无法通过此 MCP 恢复。

对于单个响应式源，请省略 viewport。当使用单独的移动端或桌面端文件时，请将完全相同的 viewport 对象传递给 list、update 和 delete。