Referencia de evoMCP

Endpoint y protocolo

Códigos HTTP que puedes ver:

Una herramienta que la conexión no puede usar no aparece en tools/list, y llamarla devuelve «Herramienta desconocida», igual que si no existiera.

Respuestas de las herramientas

El resultado va en structuredContent y en el texto, con la forma {"data": ...}. Si la herramienta puede devolver texto procedente de terceros (artículos, menús, registros, datos de visitantes), el resultado incluye "untrusted_content": true y un aviso: ese texto no debe tratarse como instrucciones. Los errores de validación y de permisos llegan con isError: true.

Cuando una escritura exige aprobación, no se ejecuta. La respuesta es:

{"data": {"status": "pending_approval", "approval_id": 12, "message": "..."}}

Antes de dejarla pendiente, si la herramienta admite dry_run, se valida con una simulación: un error de validación llega al agente en el momento y no cuando un humano ya ha aprobado.

dry_run

Las herramientas con dry_run aceptan un argumento booleano dry_run. Con true, simulan la acción y devuelven lo que harían, sin cambiar nada y sin pedir aprobación.

Herramientas propias del servidor

Están siempre disponibles para cualquier conexión.

Permisos y aprobación en las tablas

Cada herramienta pertenece a un componente y a un recurso de la matriz de permisos, que se escriben componente/recurso. El permiso es lo que la conexión necesita sobre ese par: lectura, escritura o full (las dos cosas).

La columna Aprobación puede valer:

La columna dry_run indica si admite el argumento. Las herramientas que cambian datos personales o los devuelven llevan la indicación en su descripción.

Contenido (content)

Los artículos que no están publicados solo los ve quien puede editarlos (o, con core.edit.own, los suyos).

Menús, módulos, medios, plantillas, usuarios, extensiones y configuración (plg_evomcp_joomla)

Entidades, opciones y copias (entities)

Esta capa trabaja sobre los modelos y los formularios de Joomla, de modo que valida igual que el administrador. El permiso real se comprueba por entidad con el componente y el recurso de cada una (artículos con content/articles, módulos con modules/modules, y así). El componente entities es la pasarela y exige Super User para concederse.

Entidades de serie: artículos, categorías de artículos, etiquetas, campos personalizados de artículos, menús, elementos de menú, módulos del sitio, estilos de plantilla, banners y sus clientes y categorías, contactos y sus categorías, canales de noticias y sus categorías, redirecciones, grupos de usuarios y niveles de acceso. Las extensiones pueden declarar las suyas con el evento onEvomcpCollectEntities.

Las opciones de com_evomcp, las de registro de usuarios y las de subida de ficheros de medios no se pueden cambiar con options_set; los permisos (rules), la licencia y los secretos tampoco.

YOOtheme Pro (yootheme)

Estas herramientas solo existen si la plantilla YOOtheme está instalada. Las que cambian una página del constructor exigen que el grupo del usuario de la conexión tenga el filtro de texto de Joomla en «Sin filtro».

La jerarquía válida es layout, sección, fila, columna y elementos. La biblioteca del constructor y las plantillas de página del constructor no tienen herramientas propias.

Sistema (system, config, scheduler)

Solo superusuarios. El núcleo de Joomla y evoMCP no se actualizan desde estas herramientas.

Límites de system_install_from_url: solo https y sin puerto; solo servidores de los sitios de actualización instalados más la lista de las opciones de evoMCP; solo IP públicas, y cada redirección se vuelve a comprobar; máximo 40 MB. system_set_config nunca toca credenciales, rutas ni sesiones. system_read_log solo lee la carpeta de registros, por nombre y solo el final del fichero.

Capa avanzada: SQL y ficheros (advanced)

Viene deshabilitada de fábrica y solo la usa un superusuario. Hay tres cerrojos y hacen falta los tres:

1. El plugin «evoMCP - Capa avanzada» se instala deshabilitado y hay que habilitarlo a mano.
2. El interruptor «Capa avanzada (SQL y ficheros)» de las opciones de evoMCP está apagado y hay que encenderlo.
3. La conexión necesita permiso full sobre el componente advanced, y solo un Super User puede concedérselo.

El instalador no habilita este plugin, ni al instalar ni al actualizar. Si la capa está encendida, la pestaña Conectar lo avisa.

Reglas de SQL: se usa #__ como prefijo de tablas. No se pueden leer las tablas de credenciales, sesiones ni las internas de evoMCP, y las columnas que parecen secretos salen ocultas. No se escribe en tablas de evoMCP ni de credenciales. La copia previa de una tabla se llama <tabla>_bak_evomcp_<fecha> y el mantenimiento diario la borra a los 30 días.

Reglas de ficheros:

No se admiten .., enlaces simbólicos ni ficheros ocultos. Solo tipos no ejecutables y nunca código PHP. El HTML solo se escribe en plantillas y los SVG no pueden llevar scripts.

Herramientas que añaden otras extensiones evo

Cuando están instaladas, evoLeadGate, evoOrigin y evoYTAccess registran sus herramientas en evoMCP. Se documentan aquí porque cuelgan de su propio componente en la matriz de permisos.

Para desarrolladores: registrar herramientas desde una extensión

Un plugin del grupo evomcp, o un plugin de sistema que escuche onEvomcpCollect, registra un proveedor de herramientas:

public function onEvomcpCollect(Event $event): void
{
    $event->getArgument('registry')->register(new MiProveedor($this->getApplication()));
}

MiProveedor implementa ToolProvider, contrato versión 1:

El núcleo oculta las herramientas que la conexión no puede usar, valida los argumentos contra el esquema, aplica la aprobación y audita. Las anotaciones destructiveHint, consequentialHint y approvalRequired determinan cuándo se pide aprobación. Para declarar entidades gestionables con las herramientas genéricas, escucha onEvomcpCollectEntities y registra una definición en el EntityRegistry.

OAuth 2.1

El consentimiento guarda solo lo que el usuario desmarca. Por eso, los componentes que lleguen después a una conexión ya autorizada se ven sin repetir el consentimiento; si el cliente ya tiene la lista de herramientas en memoria, hay que reconectar el conector para refrescarla. Una conexión por OAuth tiene como techo la matriz de la conexión elegida.