160 lines
9.0 KiB
Markdown
160 lines
9.0 KiB
Markdown
# MCP Tools Reference
|
|
|
|
## Quick Reference
|
|
|
|
| Tool | Categoría | Acción |
|
|
|------|-----------|--------|
|
|
| `compile_module` | Módulos | Recompilación manual de rescate cuando necesitas forzar la compilación sin editar el archivo |
|
|
| `check_module` | Módulos | Preview de cómo renderiza un módulo |
|
|
| `check_module_usage` | Módulos | Qué páginas usan un módulo |
|
|
| `acai-view` | Archivos | Lee un archivo del proyecto por tramos |
|
|
| `acai-glob` | Archivos | Busca rutas de archivos por patrón |
|
|
| `acai-grep` | Archivos | Busca texto en archivos del proyecto |
|
|
| `acai-line-replace` | Archivos | Reemplaza un bloque concreto en un archivo existente |
|
|
| `acai-write` | Archivos | Crea o reescribe un archivo completo. Antes de usarlo, lee la doc correspondiente según el tipo de archivo (`module-creation-guide`, `builder-fields`, `css-js-conventions`, `hooks-and-api`) |
|
|
| `acai-delete` | Archivos | Borra un archivo del proyecto |
|
|
| `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 |
|
|
| `rollback_git` | Git | Recuperar cambios de git remoto |
|
|
| `get_layout_field` | Layout | Lee el source de los campos globales del layout.json: style, javascript, header, footer |
|
|
| `set_layout_field` | Layout | Reemplaza un campo global del layout.json. **USA ESTA TOOL** para editar header/footer — NO toques los .tpl directos |
|
|
|
|
## Flujos de trabajo
|
|
|
|
### Crear un módulo nuevo desde cero
|
|
|
|
1. `acai-write` — Crea `index-base.tpl`, `style.css`, `script.js` y cualquier hook necesario con rutas relativas al proyecto
|
|
2. `acai-write` o `acai-line-replace` compilan automáticamente al tocar `index-base.tpl`
|
|
3. `add_module_to_record` — Añade el módulo a una página (tabla padre, ej: `apartados`)
|
|
4. `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 }]`
|
|
5. Para imágenes: `generate_image` o `upload_record_image` usando el `recordNum` y `fieldName` del `uploadFields` devuelto en el paso 4
|
|
6. 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. `acai-view` — Leer solo el tramo de `index-base.tpl` que se va a modificar
|
|
3. `acai-line-replace` — Editar el bloque concreto. Usa `acai-write` solo si el archivo es nuevo o el cambio es masivo
|
|
4. La compilación es automática tras cada edición de `index-base.tpl`
|
|
5. Si cambias variables: `set_module_config_vars` para actualizar valores
|
|
|
|
### Editar archivos del proyecto con bajo consumo de tokens
|
|
|
|
1. `acai-view` — Leer el archivo o un rango de líneas
|
|
2. `acai-glob` — Encontrar archivos relevantes por ruta cuando no conoces el path exacto
|
|
3. `acai-grep` — Buscar texto o atributos concretos dentro de archivos del proyecto
|
|
4. `acai-line-replace` — Reemplazar el bloque exacto en archivos existentes
|
|
5. `acai-write` — Crear archivos nuevos o reescribirlos por completo si es necesario
|
|
6. `acai-delete` — Borrar archivos solo cuando sea explícitamente necesario
|
|
|
|
Reglas:
|
|
- Usa siempre rutas relativas al proyecto
|
|
- No edites `index.tpl`, `index-twig.tpl` ni `builder.json` — son auto-generados
|
|
- Tras editar cualquier `index-base.tpl` con las file tools, la compilación se ejecuta automáticamente
|
|
|
|
### 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`: usa la URL recomendada por la tool que generó/subió la imagen. En Forge, si `generate_image` devuelve `uploadUrl` o `fullUrl`, priorízala frente a `dockerUrl`
|
|
|
|
### 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 una URL local de preview (`dockerUrl`) y, cuando aplica, una URL recomendada para subida (`uploadUrl` / `fullUrl`)
|
|
3. Para `upload_record_image`, usa la URL recomendada por la tool. En Forge, prioriza `uploadUrl` o `fullUrl` si están presentes
|
|
|
|
### 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. `list_page_modules` — Ver qué módulos tiene cada página
|
|
2. `get_module_config_vars` — Ver los datos de cada módulo
|
|
3. `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`
|
|
|
|
## Layout global (header, footer, style, javascript)
|
|
|
|
Los 4 campos globales del proyecto (`style.css`, `script.js`, `header`, `footer`) viven en `cms/lib/plugins/builder_saas/layout.json`.
|
|
|
|
### REGLA CRÍTICA
|
|
|
|
**NUNCA uses `acai-view`, `acai-line-replace`, `acai-write` ni `acai-delete` sobre**:
|
|
- `cms/lib/plugins/builder_saas/layout.json`
|
|
- `template/estandar/modulos/custom-header-twig/*`
|
|
- `template/estandar/modulos/custom-footer-twig/*`
|
|
- `template/estandar/modulos/custom-header/*`
|
|
- `template/estandar/modulos/custom-footer/*`
|
|
|
|
Esos ficheros son **artefactos generados** a partir del `layout.json`. Editarlos directamente provoca:
|
|
- Desincronización con `layout.json.{header,footer}ModuleCustom.htmlParsed`.
|
|
- Sobrescritura de tus cambios cuando el usuario abre el builder visual y guarda.
|
|
- Comportamiento inconsistente entre el render público y el builder.
|
|
|
|
### Workflow correcto
|
|
|
|
Para leer:
|
|
```
|
|
get_layout_field({ field: "header" }) // devuelve el source Twig del header
|
|
get_layout_field({ field: "footer" })
|
|
get_layout_field({ field: "style" }) // CSS global
|
|
get_layout_field({ field: "javascript" }) // JS global
|
|
```
|
|
|
|
Para editar:
|
|
```
|
|
set_layout_field({ field: "footer", content: "<footer>...nuevo HTML/Twig...</footer>" })
|
|
```
|
|
|
|
El backend:
|
|
1. Escribe el source en `layout.json.{field}`.
|
|
2. Sincroniza `layout.json.{field}ModuleCustom.htmlParsed`.
|
|
3. Regenera los `.tpl` del módulo `custom-{field}-twig/`.
|
|
4. Compila el Twig a PHP.
|