acai-scaffold/docs/mcp-tools-reference.md

MCP Tools Reference

Quick Reference

Tool	Categoría	Acción
create_module	Módulos	Crea módulo nuevo (directorio + archivos + compila)
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. create_module — Crea el directorio con index-base.tpl, style.css, script.js y compila
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

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 la tool Write o Edit
3. compile_module — OBLIGATORIO tras cada edición de index-base.tpl
4. 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