Ajustes

docs/09-mcp-tools-reference.md

@@ -1,3 +1,10 @@
+---
+title: "Referencia maestra de tools MCP"
+tags: [tools, reference, workflows]
+load_priority: 50
+load_when: [ranked]
+summary: "Inventario completo de tools por categoría (archivos, módulos, registros, tablas, layout, libs, hooks, media, navegación, proyecto, git, auth, docs) y workflows canónicos."
+---
 # 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.
@@ -110,6 +117,21 @@ Ver `06-hooks-and-cmsapi.md` para uso. Crear/editar el `.php` del hook se hace c
 |------|--------|
 | `navigate_browser` | Navega el browser preview del usuario a un `enlace` (e.g. `/servicios/`) |
 
+### Inspección de páginas (Playwright headless)
+
+Tools del MCP `playwright`. El browser headless es del agente — el usuario NO ve lo que pasa aquí. Para que el USER vea algo, usa `navigate_browser`.
+
+| Tool | Acción | Cuándo usarla |
+|------|--------|---------------|
+| `browser_navigate` | Carga una URL en el headless browser interno | Antes de cualquier otra `browser_*` |
+| `browser_snapshot` | Devuelve el accessibility tree YAML (texto estructurado) | **Tool primaria de inspección**. La usas para leer la página. Ves DOM, roles, valores de inputs, enlaces, jerarquía |
+| `browser_click`, `browser_fill_form`, `browser_press_key`, `browser_select_option` | Interacciones con elementos | Solo cuando necesitas simular interacción del usuario para reproducir un bug o validar un flow |
+| `browser_console_messages` | Logs del console del browser | Para detectar errores JS |
+| `browser_network_requests` | Lista de requests | Para detectar 404, fallos de fetch |
+| `browser_take_screenshot` | Captura PNG | **Evítala**. El modelo NO procesa imágenes; el screenshot se descarta. Solo úsala si el usuario explícitamente pide "haz un screenshot para que lo vea yo" |
+
+**Regla**: para auditar/inspeccionar/depurar UI, `browser_navigate` → `browser_snapshot`. NUNCA `browser_take_screenshot` esperando "ver" la página — el modelo es text-only y la imagen se pierde.
+
 ### Proyecto
 
 | Tool | Acción |