agenticSystem/docs/mcp-tools-reference.md

# MCP Tools Reference

## Quick Reference

| Tool | Categoría | Acción |
|------|-----------|--------|
| `create_module` | Módulos | (Legacy) Alternativa para crear módulo — preferir acai_write |
| `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. `acai_write` — Escribe `index-base.tpl` en `template/estandar/modulos/NOMBRE/`. El server crea la carpeta si no existe, compila y genera todos los archivos derivados (index-twig.tpl, index.tpl, builder.json, screenshots)
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

> **Nota:** `create_module` es una alternativa legacy que hace lo mismo pero con menos control sobre el contenido del template.

### 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 `acai_write` o `acai_line_replace` — el server compila automáticamente al guardar
3. 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`