Superficies de herramientas

Cada capacidad de Arcane se declara una sola vez, como una acción del catálogo con un ID canónico dominio.acción (container.restart, swarm_service.scale). La superficie de herramientas decide cómo aparece ese catálogo en la lista de herramientas del cliente. Las tres superficies son proyecciones del mismo catálogo, nunca registros paralelos: elijas la que elijas, todas las acciones son alcanzables, aceptan los mismos parámetros, siguen las mismas reglas de seguridad y devuelven el mismo resultado.

Se elige con ARCANE_MCP_TOOL_SURFACE o --tool-surface.

Superficie	Herramientas	Forma de llamada
`dynamic` (predeterminada)	2: `arcane_find_action`, `arcane_execute_action`	`{"action": "container.restart", "params": {...}, "confirm": false}`
`meta`	52: una por dominio, `arcane_<dominio>`	`{"action": "restart", "params": {...}, "confirm": false}`
`individual`	461: una por acción, `arcane_<dominio>_<acción>`	`{...parámetros, "confirm": false}`

Lo que cuestan las definiciones de herramientas de cada superficie en el contexto del modelo: dynamic 1,8 KB (~400 tokens), meta 71 KB (~16 k tokens), individual 531 KB (~111 k tokens). Son el nombre, la descripción y el esquema de entrada de cada herramienta, que es lo que un cliente pasa al modelo (los títulos, las anotaciones, los iconos y los esquemas de salida no), tal como los mide cmd/audit_tokens sobre el catálogo completo; los tokens son su estimación, a pocos puntos porcentuales de los tokenizadores de GPT. make check falla cuando estas cifras se alejan más de un 15% de la medida.

dynamic (predeterminada)

Dos herramientas, sea cual sea el tamaño del catálogo.

arcane_find_action busca en el catálogo de forma local —no hace ninguna llamada a Arcane— y devuelve las mejores coincidencias con su ID, título, descripción, nota de uso, parámetros obligatorios, si modifican o destruyen algo, acciones relacionadas y un schemaUri. Las cinco primeras incluyen su esquema de entrada completo; el resto, un resumen de una línea por parámetro.

{ "query": "restart container", "limit": 10 }

query son palabras sencillas, un recurso y un verbo (list containers, pull image, swarm service scale), de 256 caracteres como máximo; limit vale 10 por defecto y como mucho 50. El índice de búsqueda está en inglés, como el catálogo.

arcane_execute_action ejecuta una acción por su ID canónico. Los parámetros de la acción van dentro de params; confirm se queda en el nivel superior.

{
  "action": "container.restart",
  "params": { "containerId": "web-1", "environmentId": "0" },
  "confirm": false
}

action también acepta el nombre que la acción tiene en otra superficie (arcane_container_restart, arcane_container.restart) o el operationId de Arcane. A un nombre desconocido se responde con los IDs más parecidos; a una acción retirada por el modo de solo lectura o por una exclusión, con el motivo.

individual

Una herramienta por acción: arcane_container_restart, arcane_image_pull, arcane_project_up… Cada herramienta lleva el esquema de entrada completo de su acción y las anotaciones MCP readOnlyHint, destructiveHint e idempotentHint. Los parámetros van en el nivel superior; las herramientas destructivas añaden un booleano confirm a su esquema. Una acción retirada por el modo de solo lectura o por una exclusión no tiene herramienta, así que una llamada a su nombre recibe el error de herramienta desconocida del cliente.

{ "containerId": "web-1" }

Cómo elegir

Si…	Usa
Quieres la lista de herramientas más corta, o el cliente limita su número	`dynamic`
El modelo trabaja mejor con una lista fija que puede leer de antemano	`meta`
Quieres listas de permitidos o aprobaciones por herramienta en el cliente, o las anotaciones más claras en cada llamada	`individual`

dynamic cuesta un viaje de ida y vuelta adicional la primera vez que se usa una acción (buscar y luego ejecutar), pero mantiene el contexto pequeño: dos definiciones de herramienta en lugar de cientos.
meta pone unas 52 descripciones en el contexto. El modelo ve de antemano el nombre de cada acción; para el esquema completo lee arcane://tools/<id>, y una llamada con parámetros erróneos recibe los aceptados y los obligatorios antes de que nada llegue a Arcane.
individual registra 461 herramientas. Algunos clientes limitan cuántas envían al modelo; compruébalo en el tuyo antes de elegirla. Combínala con exclusiones para recortar la lista.

Sea cual sea la superficie, las instrucciones del servidor indican al cliente que las acciones destructivas necesitan confirm: true y que environmentId toma por defecto el entorno configurado.

Los recursos `arcane://tools`

El servidor publica el catálogo que sirve como dos recursos MCP, adaptados a la superficie activa:

arcane://tools enumera todas las acciones con su ID, su título, la herramienta que la ejecuta en esta superficie, una línea de llamada lista para adaptar y sus indicadores de modificación y destrucción:

{
  "surface": "meta",
  "count": 461,
  "actions": [
    {
      "id": "container.kill",
      "title": "Kill container",
      "tool": "arcane_container",
      "call": "arcane_container {\"action\":\"kill\",\"params\":{...},\"confirm\":true}",
      "mutating": true,
      "destructive": true
    }
  ]
}

arcane://tools/{id} devuelve una acción completa: descripción, nota de uso, ruta de Arcane, operationId, parámetros obligatorios, el esquema de entrada completo y las acciones relacionadas. Para una acción retirada por el modo de solo lectura o por una exclusión, devuelve el motivo.

Los recursos reflejan el catálogo filtrado: con --read-only el recuento baja y las acciones que modifican desaparecen de la lista.

El servidor publica también como recursos el estado de Docker (entornos, contenedores, proyectos, imágenes) y guías de trabajo, iguales en todas las superficies: consulta Recursos.

Resultados

Una llamada correcta devuelve el valor completo como structuredContent y una representación en Markdown como texto, igual en todas las superficies. Un listado es una tabla con los campos que identifican y describen cada elemento, bajo el recuento y la paginación (3 item(s) — 12 total, page 1 of 4); un objeto es una lista de campos con los valores anidados en un bloque JSON; un texto descargado es el propio texto. Cuando una tabla omite algo, el texto lo dice: nombra los campos que no muestra y la acción que devuelve un elemento completo (por ejemplo container.get), y una página de más de 50 elementos indica cuántas filas se han recortado y cómo recorrer el resto con start y limit. Los clientes que leen structuredContent tienen siempre todos los campos.

Errores

Los fallos vuelven como resultados de herramienta con isError activado, nunca como errores de protocolo, y proponen un siguiente paso: los parámetros aceptados y obligatorios cuando los argumentos no superan la validación (que se hace localmente, antes de llamar a Arcane), la acción de listado que encuentra un ID válido tras un 404, la credencial que revisar tras un 401 o la asignación de roles implicada tras un 403. Cuando Arcane no ha podido llegar al daemon de Docker o al agente del entorno (entonces responde 404, 500, 502 o 503 con sus propias palabras para ello), la pista lo dice en lugar de dar el recurso por inexistente, y remite a environment.test y environment.get cuando el servidor las ofrece.