mcp-ikaos-story

Servidor MCP Stdio para crear y modificar contenido de prototipos de iKAOS Story con Codex o Claude Code.

El MCP se comunica con la API autenticada de iKAOS Story. Los usuarios no necesitan clonar ikaos-content-studio-v2026 ni configurar una ruta de repositorio local. El JSON de contenido/diseño de Story reside en Supabase, mientras que los documentos de flujo de trabajo fijos y los metadatos de origen permanecen de solo lectura detrás de la API.

Límites

• get_story_context devuelve la revisión de contenido actual y el docsLink autoritativo.

• save_story_content escribe solo content_data; el origen, los documentos, la identidad de Story y los metadatos de producción no se pueden cambiar.

• Cada escritura de contenido requiere la revisión actual exacta. Una edición obsoleta devuelve un conflicto en lugar de sobrescribir contenido más reciente.

• La generación de imágenes queda fuera del alcance. Los diseñadores pueden subir, reemplazar, organizar y eliminar los archivos de imagen proporcionados a través del almacenamiento df-sheet.

• No se distribuye ninguna clave de servicio de Supabase a los usuarios de MCP.

Instalación

npm install
npm run build

Configura la API de Story:

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

Las herramientas de imagen requieren además:

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 es opcional y su valor predeterminado es http://localhost:3000. DF_SHEET_ACCESS_TOKEN es actualmente un token de acceso de revisión df-login de corta duración. Nunca hagas commit de ningún token.

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

Añade los tres valores de entorno DF_SHEET_* al mismo comando cuando se necesiten las herramientas de imagen. Verifícalo con codex mcp list o /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

Añade los tres valores de entorno DF_SHEET_* cuando se necesiten las herramientas de imagen. Verifícalo con claude mcp list o /mcp.

Herramientas

Flujo de trabajo de contenido

1. Llama a get_story_context.

2. Abre docsLink y lee las reglas fijas requeridas con get_story_rules.

3. Modifica solo el objeto de contenido/diseño currentData.data devuelto.

4. Llama a save_story_content con el ID de Story sin cambios y currentData.revision. Usa null solo cuando la Story aún no tenga contenido.

5. Llama a validate_story y luego comprueba la URL de vista previa devuelta a 390px y 1280px.

Si otro cliente guardó primero, obtén el contexto más reciente y combina intencionadamente. No reintentes con una revisión reemplazada sin revisar el contenido más reciente.

Flujo de trabajo de imágenes

1. Elige un imagePromptPackages[].inputBrief.slotId válido del contenido de la Story.

2. Llama a upload_story_image con una ruta de imagen local absoluta.

3. Usa el imageUrl devuelto en el contenido de la Story y guárdalo con save_story_content.

4. Llama a update_story_image para cambiar los metadatos o reemplazar el archivo. El reemplazo sube primero y elimina el archivo antiguo solo después de que la subida tenga éxito.

5. Llama a delete_story_image solo después de confirmar el ID de la imagen. La eliminación borra el objeto R2 y este MCP no puede recuperarlo.

Omite viewport para una única fuente responsive. Pasa exactamente el mismo objeto viewport a list, update y delete cuando uses archivos separados para móvil o escritorio.