# Story Studio MCP Server

Servidor **MCP** (Model Context Protocol) para controlar [Story Studio](https://story-studio.carlosnarro.com) desde agentes: crear proyectos y conducir todo el pipeline de producción de series animadas IA (idea motriz → personajes → capítulos → guión → escaleta → prompts → fondos → imágenes → vídeos → render).

Envuelve la **API HTTP** de la app; no accede a la BD directamente.

## Requisitos

- Node.js ≥ 18
- Una instancia de Story Studio accesible (local en `npm run dev`, o la desplegada).

## Instalar y compilar

```bash
cd mcp-server
npm install
npm run build      # genera dist/
```

## Configuración

| Variable | Default | Descripción |
|----------|---------|-------------|
| `STORY_STUDIO_URL` | `http://localhost:3000` | Base URL de la app. Local: `http://localhost:3000`. Prod: `https://story-studio.carlosnarro.com`. |

> La app **no tiene autenticación**; el server hereda ese modelo. Apunta `STORY_STUDIO_URL` al entorno que quieras controlar.

## Uso con Claude Code / clientes MCP

Transporte **stdio**. Ejemplo de registro (`.mcp.json` o config del cliente):

```json
{
  "mcpServers": {
    "story-studio": {
      "command": "node",
      "args": ["C:/Users/carlo/Proyectos/story-studio/mcp-server/dist/index.js"],
      "env": { "STORY_STUDIO_URL": "http://localhost:3000" }
    }
  }
}
```

O en desarrollo con recarga: `command: "npx"`, `args: ["tsx", ".../src/index.ts"]`.

## Herramientas

Prefijo `story_`. Lectura (`readOnlyHint`) vs generación (efectos, LLM/imagen/vídeo).

**Proyecto e idea**: `story_list_projects`, `story_get_project`, `story_create_project`,
`story_get_idea_motriz`, `story_generate_idea_motriz`, `story_refine_idea_motriz`.

**Personajes**: `story_get_personajes`, `story_generate_personajes`, `story_add_personaje`,
`story_improve_personajes`, y assets de imagen: `story_get_character_assets`,
`story_generate_asset_prompts`, `story_generate_base_image`, `story_lock_base_image`,
`story_generate_all_variations`.

**Capítulo y pipeline**: `story_list_capitulos`, `story_create_capitulo`,
`story_get_guion` / `story_generate_guion`,
`story_get_pre_escaleta` / `story_generate_pre_escaleta`,
`story_get_escaleta` / `story_generate_escaleta`,
`story_get_prompts` / `story_generate_prompts`,
`story_get_fondos` / `story_refresh_fondos` / `story_generate_fondo` / `story_generate_all_fondos`,
`story_get_imagenes` / `story_generate_plano_image` / `story_generate_all_images`,
`story_get_videos` / `story_generate_plano_video`,
`story_render_chapter` / `story_get_render_status`.

## Orden típico del pipeline

1. `story_create_project` → `story_generate_idea_motriz` → `story_generate_personajes`
2. (opcional) assets de personaje: `story_generate_asset_prompts` → `story_generate_base_image` → `story_lock_base_image` → `story_generate_all_variations`
3. `story_create_capitulo` → `story_generate_guion` → `story_generate_pre_escaleta` → `story_generate_escaleta` → `story_generate_prompts`
4. `story_refresh_fondos` → `story_generate_all_fondos` → `story_generate_all_images` → `story_generate_plano_video` → `story_render_chapter`

Las tools de generación pueden tardar (LLM/imagen); el server usa timeouts amplios.