ajustes

docs/09-mcp-tools-reference.md

@@ -0,0 +1,245 @@
+# MCP Tools — Referencia Completa
+
+Este documento es el **inventario canónico** de todas las tools MCP disponibles para el agente Acai. Está agrupado por categoría (archivos, módulos, registros, tablas, layout, librerías, hooks, media, navegación, proyecto, git, autenticación, docs) y describe para cada tool su propósito, parámetros clave, qué devuelve y cuándo usarla. Incluye además los **workflows canónicos** para las operaciones más comunes (crear módulo, editar módulo, crear funcionalidad nueva con tabla + detalle, gestionar imágenes de un módulo, editar header/footer, configurar middleware de hook). Léelo antes de cualquier tarea para elegir la secuencia correcta de tools.
+
+## Inventario por categoría
+
+### Archivos
+
+| Tool | Acción | Notas |
+|------|--------|-------|
+| `acai-view` | Lee un archivo (con rango de líneas opcional) | Ahorra tokens — usa `start_line`/`end_line` |
+| `acai-glob` | Encuentra archivos por patrón glob | `template/estandar/modulos/**/index-base.tpl` |
+| `acai-grep` | Busca texto/regex en archivos | Soporta filtro por glob |
+| `acai-write` | Crea o reescribe un archivo completo | **Editar `index-base.tpl` compila automáticamente** |
+| `acai-line-replace` | Reemplaza un bloque de líneas validado | Preferida sobre `acai-write` para edits puntuales |
+| `acai-delete` | Elimina un archivo | Destructivo — confirma primero |
+
+Reglas:
+- Rutas siempre relativas al proyecto.
+- Editar `index-base.tpl` → compila automáticamente. No necesitas llamar a `compile_module`.
+- **NO toques** `index.tpl`, `index-twig.tpl`, `builder.json` (autogenerados) ni los archivos de layout protegidos (ver `08-layout-and-libraries.md`).
+
+### Módulos
+
+| Tool | Acción | Notas |
+|------|--------|-------|
+| `create_module` | Crea un módulo nuevo (carpeta + archivos + compile) | Alternativa a hacer `acai-write` manual del `index-base.tpl`. Genera `moduleId` único añadiendo sufijo aleatorio. |
+| `compile_module` | Recompila manualmente (rescate) | Solo si los archivos generados están desincronizados. Editar `index-base.tpl` con tools de archivo ya compila. |
+| `check_module` | Preview del render con datos de ejemplo | Devuelve preview (50 líneas) por defecto; `fullRender:true` para todo |
+| `check_module_usage` | Lista páginas que usan el módulo | **OBLIGATORIO antes de `delete_module`** |
+| `delete_module` | Elimina la carpeta del módulo | Destructivo. Si `inUse=true`, deniega — el usuario debe quitarlo de las páginas primero |
+| `set_module_example_data` | Define datos de ejemplo para preview en el editor | Pasar valores para TODAS las variables del schema |
+
+### Registros (records)
+
+| Tool | Acción | Notas |
+|------|--------|-------|
+| `list_table_records` | Lista registros con filtros, paginación | Usa `fields` y `truncateText` para ahorrar tokens |
+| `get_record` | Obtiene un registro completo por `num` | Carga uploads + relations por defecto |
+| `create_or_update_record` | Crea o actualiza registros | Sin `recordId` → crea. Con `recordId` → actualiza. Acepta array para batch |
+| `delete_table_records` | Elimina registros (por IDs o `deleteAll`) | **Destructivo permanente** |
+| `list_page_modules` | Lista módulos colocados en una página Builder | Devuelve sectionIds, posiciones, visibilidad, configVars |
+| `add_module_to_record` | Añade módulo a una página Builder | Devuelve `sectionId` — úsalo en `set_module_config_vars` |
+| `remove_module_from_record` | Quita módulo de la página | Por `sectionId` (preferido) o `modulePosition` |
+| `reorder_module` | Mueve módulo a otra posición | `fromPosition` → `toPosition` |
+| `toggle_module_visibility` | Muestra/oculta sin borrar | Por `sectionId` |
+| `get_module_config_vars` | Lee valores actuales de las variables | Por `tableName` + `recordNum` + `sectionId` |
+| `set_module_config_vars` | Escribe variables del módulo | Devuelve `uploadFields` con `recordNum`+`fieldName` listos para subir imágenes |
+
+### Tablas y campos (schema)
+
+Ver `05-tables-and-fields.md` para detalles. Tools:
+
+| Tool | Acción |
+|------|--------|
+| `list_tables` | Inventario de tablas (sin `cms_`) |
+| `get_table_schema` | Schema completo. Soporta `minimal:true` y `filterFields:"..."` para ahorrar tokens |
+| `create_table` | Crea tabla nueva. PREGUNTA al usuario sobre `enlace`/`seoMetas` antes |
+| `update_table_metadata` | Actualiza el `[meta]`. `newTableName` renombra MySQL (destructivo) |
+| `delete_table` | Borra tabla. Usa `dryRun:true` primero. `dropData:true` borra datos |
+| `reorder_tables` | Reordena sidebar admin |
+| `create_field` | Añade campo a tabla |
+| `update_field` | Actualiza props. `newFieldName` renombra columna (destructivo). Cambios de `type` pueden truncar datos — surfacea `warnings` |
+| `delete_field` | Borra campo. `dropColumn:true` borra datos permanentemente |
+| `reorder_fields` | Reordena los campos del formulario admin |
+| `regenerate_enlaces` | Regenera URLs de la tabla. `generateAlias:true` para preservar redirects |
+
+### Layout global
+
+Ver `08-layout-and-libraries.md`.
+
+| Tool | Acción |
+|------|--------|
+| `get_layout_field` | Lee `style`/`javascript`/`header`/`footer` del `layout.json` |
+| `set_layout_field` | Escribe el campo (atómico: actualiza json + regenera tpl + compila). Destructivo |
+
+### Librerías globales
+
+| Tool | Acción |
+|------|--------|
+| `list_global_libraries` | Lista las URLs `top` (head) y `bottom` (antes de `</body>`) |
+| `add_global_library` | Añade URL idempotente |
+| `remove_global_library` | Quita URL idempotente |
+| `set_global_libraries` | Reemplaza la lista de la sección. Destructivo |
+
+### Hooks (middleware)
+
+| Tool | Acción |
+|------|--------|
+| `get_hook_middleware` | Lee la config `middleWare` de un hook global |
+| `set_hook_middleware` | Configura cuándo se ejecuta automáticamente: `[]`, `["allurls"]`, `["<tableName>-<num>"]` |
+
+Ver `06-hooks-and-cmsapi.md` para uso. Crear/editar el `.php` del hook se hace con `acai-write`.
+
+### Media
+
+| Tool | Acción | Notas |
+|------|--------|-------|
+| `generate_image` | Genera imagen con IA y la guarda en `cms/uploads/generated/` | Devuelve `dockerUrl` y `uploadUrl`/`fullUrl`. **En Forge prefiere `uploadUrl`/`fullUrl`** sobre `dockerUrl` para `upload_record_image` |
+| `upload_record_image` | Sube imagen a un campo de un registro | Necesita `tableName`, `recordId` (num), `fieldName` real (de relations o `uploadFields`) |
+| `upload_image_to_assets` | Sube imagen a `/images/` del template (assets globales) | Acepta base64, data URI, URL. Permite resize/quality/format |
+
+### Navegación
+
+| Tool | Acción |
+|------|--------|
+| `navigate_browser` | Navega el browser preview del usuario a un `enlace` (e.g. `/servicios/`) |
+
+### Proyecto
+
+| Tool | Acción |
+|------|--------|
+| `get_web_url` | URL del sitio en desarrollo. **OBLIGATORIO** antes de fetch/Playwright. Acuérdate de añadir `?pruebas=1` |
+| `save_project_styles` | Guarda resumen de estilos en `docs/project-styles.md` |
+
+### Git
+
+| Tool | Acción |
+|------|--------|
+| `list_git_log` | Lista los últimos commits para que el usuario elija un id de rollback |
+| (rollback) | Tool de rescate; pide confirmación al usuario |
+
+### Autenticación
+
+| Tool | Acción |
+|------|--------|
+| `refresh_acai_token` | Renueva el JWT cuando expira (errores 403) |
+
+### Documentación
+
+| Tool | Acción |
+|------|--------|
+| `read_doc` | Lee un doc del knowledge base completo o por sección. Útil cuando un doc no fue cargado por relevancia o necesitas una sección puntual |
+| `list_docs` | Lista los docs disponibles con sus títulos y summaries |
+
+## Workflows canónicos
+
+### 1. Crear un módulo nuevo
+
+1. **Estilo del proyecto**: si existe `docs/project-styles.md` léelo. Si no, explora 3-4 módulos representativos (no `custom-*`) y guarda con `save_project_styles`.
+2. **Lee la doc relevante** según contenido: `01-builder-fields.md` siempre; `07-css-js-conventions.md` si lleva JS; `06-hooks-and-cmsapi.md` si lleva hook PHP; `02-twig.md` si usa filtros.
+3. **`acai-write`** sobre `template/estandar/modulos/<moduleId>_xxxxxx/index-base.tpl` con el HTML/Twig. Si necesita CSS/JS/PHP, escribe también `style.css`, `script.js`, `hook.php`.
+4. **Compilación automática** al escribir `index-base.tpl`. Si por algún motivo necesitas forzarla sin tocar el archivo: `compile_module`.
+5. **`add_module_to_record`** para colocarlo en una página. Devuelve `sectionId`.
+6. **`set_module_config_vars`** para rellenar variables (textos, listas, etc.). Devuelve `uploadFields` con `recordNum`+`fieldName` por cada upload.
+7. **Imágenes**: `generate_image` o `upload_record_image` usando el `recordNum` y `fieldName` del paso 6.
+8. **`navigate_browser`** al `enlace` de la página para que el usuario vea el resultado.
+
+### 2. Editar un módulo existente
+
+1. `get_module_config_vars` — leer estado actual (vars + recordNums).
+2. `acai-view` — leer el rango concreto de `index-base.tpl` que vas a tocar.
+3. `acai-line-replace` — modificar el bloque (compila automáticamente). Usa `acai-write` solo si el cambio es masivo.
+4. Si cambian variables: `set_module_config_vars` para actualizar valores.
+
+### 3. Gestionar imágenes de un módulo
+
+**Tras `set_module_config_vars`** (recomendado):
+1. La respuesta incluye `uploadFields` con `{ fieldName, recordNum }` por cada variable upload.
+2. Para multi vars con uploads: `uploadFields["records.imagen"]` es array `[{index, fieldName, recordNum}]`.
+3. `upload_record_image` con `tableName: "builder_custom"`, `recordId` y `fieldName` de `uploadFields`.
+
+**Sin `set_module_config_vars` previo**:
+1. `get_module_config_vars` — obtiene `recordNum` de builder_custom.
+2. Lee `builder.json` del módulo para encontrar el `fieldName` real (de `vars.NOMBRE.relations.builder_custom`, ej. `image1` — **NO** uses el nombre de la variable).
+3. `upload_record_image` con `tableName: "builder_custom"`, `recordId` (recordNum del paso 1), `fieldName` (de relations).
+
+Generar imagen primero:
+1. `generate_image` con `prompt` + `style`.
+2. Usa la URL recomendada que devuelve (`uploadUrl` o `fullUrl` en Forge; `dockerUrl` solo en local).
+3. `upload_record_image` con esa URL.
+
+### 4. Crear funcionalidad nueva con tabla + detalle
+
+Ejemplo: implementar "Vacantes".
+
+1. **`create_table`** con `tableName: "vacantes"`, `menuType: "multi"`, `enlace: true`, `seoMetas: true`. Pregunta al usuario antes los flags.
+2. **`create_field`** para cada campo: `titulo`, `descripcion` (wysiwyg), `salario_minimo` (textfield), `categoria_num` (list desde tabla), `fecha_publicacion` (date), `fecha_expiracion` (date), `visible` (checkbox), `imagen_destacada` (upload).
+3. **`acai-write`** sobre `template/estandar/modulos/custom-vacantes/index-base.tpl` con el Twig que usa `thisrecord.*` (sección general que renderiza el detalle de cada registro).
+4. (Opcional) **Módulo de listado** `vacantes_listado_xxxxxx` con `'vacantes' | get('visible=1', 'fecha_publicacion DESC', 20)`.
+5. (Opcional) **Página índice** `/vacantes/` en `apartados` (Builder) con el módulo de listado dentro.
+6. **`navigate_browser`** a un detalle creado para verificar.
+
+### 5. Editar header / footer del sitio
+
+Ver `08-layout-and-libraries.md`.
+
+1. `get_layout_field({ field: "header" })` — lee Twig actual.
+2. Modifica localmente.
+3. `set_layout_field({ field: "header", content: "..." })` — atómico. Sobrescribe `layout.json`, regenera `.tpl` y compila.
+
+**NUNCA** uses `acai-write` sobre `custom-header-twig/index-base.tpl` ni `layout.json`.
+
+### 6. Añadir librería global (jQuery, Vue CDN, Google Fonts)
+
+1. `list_global_libraries` — comprueba si ya existe.
+2. `add_global_library({ section: "bottom", url: "..." })` para JS, o `top` para CSS/fonts.
+
+Para reordenar dependencias: `set_global_libraries` con la lista completa.
+
+### 7. Hook con middleware (auto-ejecutar antes de páginas)
+
+1. **`acai-write`** sobre `hooks/hooks.<id>.php` con la lógica.
+2. **`get_hook_middleware`** sobre `/hooks/<id>/` para ver config actual.
+3. **`set_hook_middleware`** con el nuevo `middleWare`:
+   - `[]` → solo cuando se llama explícitamente
+   - `["allurls"]` → antes de cada página
+   - `["cms_apartados-2"]` → solo antes del registro num=2 de apartados
+
+### 8. Gestionar registros de una tabla
+
+1. `list_table_records` con `where`/`order`/`limit`/`fields` (sin `cms_`).
+2. `get_record` para uno completo (`tableName`+`recordNum`).
+3. `create_or_update_record` para crear/actualizar. Antes consulta el schema con `get_table_schema`.
+4. `delete_table_records` para borrar (destructivo permanente).
+
+### 9. Explorar el sitio
+
+- `list_table_records` sobre `apartados` para ver páginas.
+- `list_page_modules` sobre una página para ver módulos.
+- `get_module_config_vars` para ver datos de un módulo.
+- `check_module` para preview con datos custom.
+
+### 10. Consultar la documentación bajo demanda
+
+Si el knowledge_base no cargó un doc relevante (lo verás en "Other Available Docs") o necesitas una sección puntual con detalle:
+
+```
+list_docs()                                    // todos los docs con summary
+read_doc({ name: "05-tables-and-fields" })     // doc completo
+read_doc({ name: "06-hooks-and-cmsapi", section: "Hook middleware" })   // sección por heading H2
+```
+
+## Reglas globales para todas las tools
+
+1. **`tableName` siempre SIN prefijo `cms_`** (excepto en `queryDB` Twig y en el `middleWare` de `set_hook_middleware`).
+2. **PK siempre `num`**, nunca `id`. Foreign keys con sufijo `_num`.
+3. **Upload fields son arrays** — accede con `[0].urlPath`.
+4. **`fieldName` para imágenes** viene de `builder.json` → `vars.NOMBRE.relations.builder_custom` (ej. `image1`), NO del nombre de la variable.
+5. **`recordId` para imágenes de módulo** es el `num` de `builder_custom`, NO el `sectionId`.
+6. Tras `set_module_config_vars`, **TODAS** las variables (incluidos uploads) reciben `recordNum`+`fieldName` en `uploadFields`.
+7. Si un token JWT expira (error 403): `refresh_acai_token` y reintentar.
+8. Al pedir URLs del sitio: `get_web_url` SIEMPRE primero. Añade `?pruebas=1` para modo desarrollo. Nunca uses dominios de producción ni `localhost:8080`.
+9. Antes de crear archivos, **lee la doc** relevante (`read_doc` si no está en el KB cargado).
+10. Operaciones destructivas (`delete_*`, `dropColumn`, `dropData`, `dropTable`, `newTableName`, `newFieldName`, `regenerate_enlaces` sin alias, `set_global_libraries`, `set_layout_field`): **pide confirmación al usuario** si no es trivial.