Esquemas de salida

Una herramienta MCP puede declarar un esquema de salida: el JSON Schema del structuredContent que devuelve, para que un cliente conozca la forma de un resultado antes de llamar. arcane-mcp puede declarar uno para cada acción, derivado del documento OpenAPI de Arcane. Es experimental y está desactivado por defecto: actívalo con ARCANE_MCP_OUTPUT_SCHEMAS=on (consulta Configuración).

Dónde se declaran

• Solo en la superficie de herramientas individual, un esquema por herramienta. Una herramienta meta o dynamic ejecuta muchas acciones, así que su esquema sería la unión de todos los suyos, y eso no le dice a un cliente nada en lo que pueda confiar.
• Solo para las acciones que el ejecutor genérico ejecuta a partir de una operación OpenAPI con respuesta JSON: 420 de las 461 acciones. Las acciones con un manejador escrito a mano construyen su propio valor; las descargas y los flujos no tienen esquema JSON.
• En modo seguro, una acción que cambia estado responde con una vista previa en lugar de su resultado, así que no declara ninguno.

Qué describe un esquema

El esquema describe structuredContent, que no es el cuerpo de la respuesta de Arcane: el servidor saca el contenido del sobre {success, data, pagination} de Arcane (consulta Formato de salida). Los campos de un objeto suben al nivel superior, una lista va bajo items, un valor suelto bajo value, y pagination y los demás miembros del sobre (como failedEnvironments) quedan a su lado.

Relajados a propósito

Arcane no siempre envía lo que declara su documento, y un cliente puede rechazar un resultado que no encaje con un esquema de salida declarado, lo que convertiría una llamada correcta en un error. Por eso cada esquema está relajado: indica el tipo de cada campo que Arcane declara y nada que una divergencia inofensiva pueda romper.

• Todo campo admite también null, y ningún campo es obligatorio.
• Los objetos aceptan campos que el documento no enumera.
• Se quitan las restricciones de valor: enum, format, pattern, límites y longitudes. oneOf se lee como anyOf.
• La raíz es siempre un objeto, como exige MCP.

Donde se sabe que Arcane envía otro tipo, el esquema amplía ese campo. Arcane (v2.16.1 a v2.17.2, cuya biblioteca compose-go no cambia en esto) envía los tamaños en bytes de compose (mem_limit, mem_reservation, mem_swappiness, memswap_limit, shm_size, el shm_size de un build, el memory de los recursos de deploy, el size de un tmpfs) como cadenas, por ejemplo "0", mientras que su documento dice entero, así que esos campos aceptan un entero o una cadena.

Cuando un resultado sigue sin encajar

El servidor comprueba cada resultado contra el esquema declarado antes de enviarlo. Si alguna parte sigue sin encajar, la llamada sigue siendo correcta:

• structuredContent lleva null en esa parte, así que encaja con el esquema;
• el texto gana una nota breve Output schema con el JSON Pointer de cada parte ajustada y el valor original de Arcane en ella, para que no se pierda nada de lo que devolvió Arcane (hasta 20 partes, con el JSON cortado en 4000 bytes);
• el servidor registra un aviso con la acción y los punteros ajustados.

Cómo se validaron los esquemas

La batería de pruebas extremo a extremo en vivo tiene un modo validador (E2E_VALIDATE_OUTPUT=1) que comprueba el structuredContent de cada llamada correcta contra el esquema de la acción y escribe en un informe lo que no encaja. Con Arcane v2.16.1, 2714 resultados comprobados en las tres superficies mostraron una sola divergencia, los tamaños en bytes de compose de arriba, en cuatro acciones (project.compose, project.runtime, project.update, project.updates); los campos ampliados la cubren. Con Arcane v2.17.0, 2843 resultados de 414 acciones comprobados en las tres superficies, con esos campos ampliados, no mostraron ninguna. Con Arcane v2.17.1, 2892 resultados comprobados en las tres superficies tampoco mostraron ninguna, incluidos los campos de compose que añade (umask, use_service_name_alias). Con Arcane v2.17.2, 2908 resultados de 455 acciones no mostraron ninguna.

Qué cuestan

Los esquemas llevan descripciones y los esquemas de los componentes a los que se refieren, así que son grandes: el resultado de tools/list de la superficie individual pasa de 988 KB a 1,85 MB. Los clientes los usan para comprobar y tipar resultados; no suelen pasárselos al modelo.