agenticSystem/docs/09-mcp-tools-reference.md

# 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.