CLI y MCP para agentes

Guía de las herramientas que un agente usa para entender y operar el framework: el servidor MCP (herramientas expuestas a clientes LLM), los generadores de línea de comandos en tools/, y la introspección del sistema.

---

1. Empieza por la introspección

Antes de tocar nada, obtén un mapa del sistema:

php tools/introspect.php            # snapshot completo (JSON): plugins activos, tablas, relaciones, generadores
php tools/introspect.php --section=plugins
php tools/introspect.php --section=relationships
php tools/introspect.php --compact

Devuelve, en una sola llamada:

• plugins: cada plugin con active (si está registrado en PluginsRegistry), url/type/icon/version (si activo), summary, tables (tablas propias) y relationships.
• relationships: el grafo dirigido (quién dispara/lee a quién y por qué hook).
• generators: los scaffolders disponibles en tools/.

Por MCP es la tool list_plugins (mismo contenido).

Un plugin desactivado (carpeta presente pero no registrada) no aparece como activo aunque sus tablas sigan en la BD. La introspección refleja el estado real.

---

2. Servidor MCP (mcp/)

Servidor Node/TypeScript (transporte stdio) que expone la API REST del framework y utilidades locales como herramientas MCP. Se autentica con API key (header Authorization) en toda petición y, para escrituras, con JWT de sesión (login por env FW_AUTH_EMAIL/FW_AUTH_PASSWORD o interactivo con mcp_login).

Herramientas

Sesión

• whoami — estado de la sesión (email, expiración del JWT, origen).
• mcp_login — login interactivo (abre una URL del CMS que devuelve el JWT).

Datos (API genérica — así se operan los datos de cualquier módulo/plugin)

• list_tables — módulos/tablas del CMS (respeta deny-list).
• describe_table — columnas de un módulo (id_module o suffix).
• search_records — filas de una tabla (linkTo/equalTo/search/orderBy/paginación).
• get_record — una fila por PK.
• create_record — inserta (requiere sesión).
• update_record — actualiza por PK (requiere sesión).
• delete_record — destructivo, dos pasos: la 1ª llamada devuelve un challenge que la 2ª debe repetir.

Páginas

• list_pages — páginas del CMS (filtro por type_page).
• read_page — una página + sus módulos.

Sistema (introspección)

• list_plugins — ejecuta tools/introspect.php: plugins activos, tablas, relaciones, generadores. Úsala primero.
• doctor — ejecuta tools/doctor.php --json: estado del entorno (PHP, config, BD, permisos, plugins, correo). Úsala para distinguir un problema de entorno de uno de código.
• describe_schema — ejecuta tools/schema.php: secciones, columnas (CMS vs SQL), páginas y huérfanos, leyendo la BD directamente (no necesita la API HTTP).

Scaffolding (envuelven los generadores de tools/)

• scaffold_migration — genera una migración CREATE TABLE. Por defecto preview; write:true escribe.
• scaffold_web_page — genera páginas públicas (listado + detalle). Preview por defecto; write:true escribe.
• scaffold_plugin — crea un plugin completo y lo registra. Solo corre con write:true (escribe muchos archivos + toca el registry).

Recursos (documentación legible por el MCP)

• framework://docs/<slug> — docs de docs/ (API, ARQUITECTURA, SEGURIDAD, PLUGINS, CLI-Y-MCP, ROADMAP, …).
• framework://agent-docs/<slug> — docs de .claude/docs/ (MODULOS, INDICE). PLUGINS y CLI-Y-MCP se sirven bajo framework://docs/.

Configuración (mcp/.env)

Variable	Uso
FW_API_BASE_URL	Base de la API REST (requerido)
FW_API_KEY	API key (requerido; coincide con api/config.php)
FW_AUTH_EMAIL / FW_AUTH_PASSWORD	Login automático para escrituras (opcional)
FW_DENY_TABLES	Tablas ocultas (default admins,activity_logs,sessions,tokens)
FW_REPO_ROOT	Raíz del checkout para las tools locales (default: dos niveles sobre dist/)
FW_PHP_BIN	Binario PHP para las tools locales (default php; en local usa el de XAMPP)

Las tools de introspección y scaffolding ejecutan php tools/*.php en la máquina del MCP, así que necesitan PHP + el checkout (FW_REPO_ROOT). Las tools de datos solo usan la API REST.

Build y prueba: cd mcp && npm run build, humo end-to-end con ./smoke.sh.

---

3. Generadores (tools/)

Scripts PHP sin dependencias, ejecutables con php tools/<script>.php (y también expuestos por el MCP). Documentación detallada en tools/README.md.

Script	Qué hace
introspect.php	Snapshot del sistema (plugins activos, relaciones, generadores).
make-plugin.php	Scaffold de un plugin completo + registro.
make-migration.php	Scaffold de una migración CREATE TABLE (convenciones de sufijo + rollback).
make-web-page.php	Páginas públicas de listado + detalle para una tabla.
make-table.php	Tabla + sección CRUD de admin.
make-page.php / page-builder.php	Páginas públicas desde config JSON / plantilla.
make-column.php	Agrega una columna a una sección existente (ALTER TABLE + fila en columns).
seed.php	Inserta registros desde JSON; --key=<col> hace el seeding idempotente.
schema.php	Describe lo existente (secciones, columnas CMS vs SQL, páginas, huérfanos).
doctor.php	Diagnóstico del entorno; --json y exit 1 si algo impide funcionar.
setup.php	Bootstrap idempotente (configs + directorios) tras instalar o restaurar.

Los generadores validan identificadores y no sobreescriben sin --force. Todos tienen tests en tests/ (corren con php tests/run.php).

Contrato para agentes

Los comandos orientados a agentes (make-table, make-column, seed, schema, doctor, introspect) responden siempre igual:

• Éxito: JSON en STDOUT con "success": true y exit 0.
• Error: JSON en STDERR con "success": false, "error": "…" y exit 1.
• --dry-run (en los que mutan) valida y describe el plan sin escribir nada.

Secuencia recomendada para construir un sistema: doctor → schema → make-table --dry-run → make-table → make-column → seed → make-page → schema <tabla> para verificar.

tools/ está bloqueado por HTTP (tools/.htaccess); son comandos de consola.

---

4. Flujo recomendado para un agente

1. Entender: list_plugins (o php tools/introspect.php) → qué plugins hay, sus tablas y relaciones.
2. Leer datos de un plugin: search_records/get_record sobre sus tablas (ej. crm_contacts, stock_movements, report_definitions).
3. Escribir datos: create_record/update_record (respetan validación y auth); las acciones con lógica propia del plugin (venta POS atómica, ejecutar reporte, mover tarjeta) viven en el ajax.php del plugin y requieren sesión CMS, no API — hazlas desde el CMS.
4. Crear estructura nueva: scaffold_migration → scaffold_plugin → scaffold_web_page (preview primero, luego write:true).
5. Respetar las relaciones: no dupliques lógica; engancha por los hooks existentes (ver el grafo en PLUGINS.md). Cada plugin es autocontenido — nunca importes clases de otro plugin.