Initial commit

docs/mcp-tools-reference.md

@@ -0,0 +1,100 @@
+# MCP Tools Reference
+
+## Quick Reference
+
+| Tool | Categoría | Acción |
+|------|-----------|--------|
+| `create_module` | Módulos | Crea módulo nuevo (directorio + archivos + compila) |
+| `compile_module` | Módulos | Compila módulo tras editar index-base.tpl |
+| `check_module` | Módulos | Preview de cómo renderiza un módulo |
+| `check_module_usage` | Módulos | Qué páginas usan un módulo |
+| `set_module_example_data` | Módulos | Datos de ejemplo para editor visual |
+| `list_page_modules` | Registros | Lista módulos de una página |
+| `add_module_to_record` | Registros | Añade módulo a una página |
+| `remove_module_from_record` | Registros | Elimina módulo de una página |
+| `reorder_module` | Registros | Cambia posición de un módulo |
+| `toggle_module_visibility` | Registros | Muestra/oculta módulo |
+| `get_module_config_vars` | Registros | Lee variables de un módulo |
+| `set_module_config_vars` | Registros | Escribe variables de un módulo |
+| `list_table_records` | Registros | Buscar/listar registros con filtros |
+| `get_record` | Registros | Obtener un registro por num |
+| `create_or_update_record` | Registros | Crear o actualizar registros |
+| `delete_table_records` | Registros | Eliminar registros (destructivo) |
+| `upload_record_image` | Media | Subir imagen a campo de registro (desde URL) |
+| `generate_image` | Media | Generar imagen con IA y guardar en uploads |
+| `upload_image_to_assets` | Media | Subir imagen a /images/ del template |
+| `list_record_uploads` | Media | Listar uploads de un campo |
+| `replace_record_image` | Media | Reemplazar imagen existente |
+| `delete_record_upload` | Media | Borrar upload |
+| `reorder_record_uploads` | Media | Reordenar imágenes de un campo |
+| `refresh_acai_token` | Auth | Renovar token JWT expirado |
+| `navigate_browser` | Navegación | Navegar el browser del frontend a una URL |
+| `save_project_styles` | Proyecto | Guardar resumen de estilos en docs/project-styles.md |
+| `orchestrate_task` | Orquestador | Guía paso a paso para tareas complejas |
+| `rollback_git` | Git | Recuperar cambios de git remoto |
+
+## Flujos de trabajo
+
+### Crear un módulo nuevo desde cero
+
+1. `create_module` — Crea el directorio con index-base.tpl, style.css, script.js y compila
+2. `add_module_to_record` — Añade el módulo a una página (tabla padre, ej: `apartados`)
+3. `set_module_config_vars` — Rellena las variables con contenido (textos, colores, opciones). **OBLIGATORIO** — sin esto el módulo no muestra nada. Devuelve:
+   - `configVars`: mapa de variables → recordNums
+   - `uploadFields`: mapa de variables upload → `{ fieldName, recordNum }` — **usa estos directamente** para subir imágenes sin necesidad de leer builder.json
+   - Para vars multi con uploads: `uploadFields["varName.subVarName"]` es un array con `[{ index, fieldName, recordNum }]`
+4. Para imágenes: `generate_image` o `upload_record_image` usando el `recordNum` y `fieldName` del `uploadFields` devuelto en el paso 3
+5. Verificar con `check_module` o recargando la página
+
+### Editar un módulo existente
+
+1. `get_module_config_vars` — Leer el estado actual del módulo (variables, recordNums)
+2. Editar `index-base.tpl` con la tool `Write` o `Edit`
+3. `compile_module` — **OBLIGATORIO** tras cada edición de index-base.tpl
+4. Si cambias variables: `set_module_config_vars` para actualizar valores
+
+### Añadir/modificar imágenes de un módulo
+
+**Tras `set_module_config_vars`** (método recomendado — sin pasos extra):
+1. El response de `set_module_config_vars` incluye `uploadFields` con los `recordNum` y `fieldName` de cada variable upload
+2. `upload_record_image` con `tableName: "builder_custom"`, `recordId` y `fieldName` del `uploadFields`
+3. Para uploads dentro de vars multi: `uploadFields["records.imagen"]` devuelve array con `{ index, fieldName, recordNum }` por cada record
+
+**Sin haber llamado a `set_module_config_vars`**:
+1. `get_module_config_vars` — Obtener el `recordNum` de builder_custom
+2. Leer `builder.json` del módulo para encontrar el `fieldName` real (ej: `image1`, NO el nombre de la variable)
+3. `upload_record_image` con:
+   - `tableName`: `"builder_custom"` (siempre sin cms_)
+   - `recordId`: el recordNum del paso 1
+   - `fieldName`: el campo de relations del builder.json (ej: `image1`)
+   - `imageUrl`: URL accesible desde Docker (ej: `http://localhost/cms/uploads/...`)
+
+### Generar imagen con IA
+
+1. `generate_image` con prompt descriptivo + style (photographic, digital-art, minimalist...)
+2. La imagen se guarda en `cms/uploads/generated/` y devuelve `dockerUrl`
+3. Usar esa `dockerUrl` con `upload_record_image` para asignarla a un módulo
+
+### Gestionar registros de una tabla
+
+1. `list_table_records` — Buscar registros con filtros (`where`, `order`, `limit`)
+2. `get_record` — Obtener un registro completo por num
+3. `create_or_update_record` — Crear o actualizar (la tabla sin prefijo `cms_`, PK es `num`)
+4. `delete_table_records` — Eliminar por IDs
+
+### Explorar el sitio
+
+1. `orchestrate_task` con workflow `explore_site` — Guía para entender la estructura
+2. `list_page_modules` — Ver qué módulos tiene cada página
+3. `get_module_config_vars` — Ver los datos de cada módulo
+4. `check_module` — Preview de cómo renderiza
+
+## Reglas importantes para todas las tools
+
+1. **tableName** siempre SIN prefijo `cms_` (ej: `apartados`, no `cms_apartados`)
+2. **Primary key** es siempre `num`, nunca `id`
+3. **Uploads** son arrays — acceder con `[0].urlPath`
+4. **fieldName de imágenes** viene de `builder.json` → `vars.NOMBRE.relations.builder_custom` (ej: `image1`), NO del nombre de la variable
+5. **recordId para imágenes** es el `num` de `builder_custom`, NO el sectionId del módulo
+6. Tras `set_module_config_vars`, TODAS las variables del módulo (incluyendo upload) reciben config-vars automáticamente
+7. Si el token expira (error 403), usar `refresh_acai_token`