agenticSystem/docs/mcp-tools-reference.md

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

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