Recursos
Además de sus herramientas, arcane-mcp publica recursos MCP: documentos que un cliente puede adjuntar a una conversación como contexto (los menús «añadir contexto» de Claude y VS Code) o que un modelo puede leer con resources/read. Son los mismos en todas las superficies de herramientas. resources/list devuelve las URI fijas y resources/templates/list las plantillas.
Hay tres tipos:
- Estado de Docker en JSON, leído de Arcane en el momento de leer el recurso.
- Guías de trabajo en Markdown: procedimientos paso a paso que nombran las acciones que hay que llamar.
- El catálogo de acciones:
arcane://toolsyarcane://tools/{id}, las acciones que ofrece este servidor con sus parámetros.
Estado de Docker
Sección titulada «Estado de Docker»Cada recurso de datos es una vista de una acción del catálogo. Leerlo ejecuta esa acción, con las partes de la URI como argumentos, y devuelve el valor de la acción (lo que una llamada a herramienta devuelve como structuredContent) con sus secretos ocultos (consulta Ocultación de secretos).
| URI | Acción | Contenido |
|---|---|---|
arcane://environments | environment.list | Todos los entornos (hosts de Docker) que ve quien llama: id (el environmentId de las demás URI; 0 es el host local de Arcane), nombre, apiUrl, estado |
arcane://version | server.app_version | La versión y la compilación de Arcane, y si hay una actualización disponible |
arcane://environment/{environmentId} | environment.get | El registro completo de un entorno |
arcane://environment/{environmentId}/containers | container.list | Todos los contenedores, también los parados, con los recuentos de en marcha, parados y total |
arcane://environment/{environmentId}/container/{containerId} | container.get | Los detalles de inspección de un contenedor (estado y salud, configuración, montajes, redes); containerId es un ID o un nombre |
arcane://environment/{environmentId}/projects | project.list | Todos los proyectos Compose que no están archivados |
arcane://environment/{environmentId}/project/{projectId} | project.get | El resumen de un proyecto: estado, recuentos de servicios, errores de configuración |
arcane://environment/{environmentId}/images | image.list | Todas las imágenes locales, con los resultados guardados de actualizaciones y vulnerabilidades |
Los clientes que admiten autocompletado sugieren las variables de las plantillas (environmentId, containerId, projectId) mientras escribes (consulta Autocompletado). Los resultados de environment.get, container.get y project.get terminan con un resource_link a la plantilla del objeto, ya rellenada (consulta Formato de salida).
Qué hace una lectura:
- Listas completas. Un recurso de lista pide a Arcane todos los elementos (
limit=-1), porque un recurso no se puede paginar. Las acciones de listado siguen con páginas de 20 por defecto; úsalas para filtrar u ordenar. - Tu credencial. La lectura usa el cliente de Arcane del servidor: por stdio, la clave de API o el inicio de sesión configurados; por HTTP, la clave que el cliente envió en
X-Arcane-API-Key(cada clave tiene su propio servidor), así que una lectura nunca ve más de lo que vería la misma clave con una herramienta.arcane://versionno envía credencial, igual queserver.app_version. - Todos los modos. Las lecturas no cambian nada, así que el modo de solo lectura y el modo seguro conservan los recursos. Una acción quitada con
ARCANE_MCP_EXCLUDE_TOOLSse lleva su recurso: excluircontainer.getquita también la plantilla del contenedor (consulta Configuración). - El plazo de la acción (
ARCANE_MCP_ACTION_TIMEOUT) y el tiempo límite de cada petición se aplican igual que en las llamadas a herramientas. - Registro de auditoría. Cada lectura deja un registro de auditoría, con el mensaje
resource read,surface=resource,tool=resources/read, la acción y el resultado (y en modo HTTP la huella de la clave): los campos del registro de una llamada a herramienta. - Sin caché. Los resultados llevan
cacheScope: privateyttlMs: 0: los datos pertenecen a una credencial y el estado de Docker puede cambiar en cualquier momento. - Solo JSON. El contenido es el valor JSON indentado, con tipo MIME
application/json. No hay versión en Markdown; llama a la acción cuando quieras el texto formateado.
Ocultación de secretos
Sección titulada «Ocultación de secretos»Un cliente puede añadir un recurso a la conversación, mostrarlo o guardarlo en caché sin que nadie pida un campo concreto, así que los recursos de datos dejan fuera los secretos que Docker y Compose guardan junto al estado que muestran. Las llamadas a herramientas no ocultan nada: la acción que nombra cada recurso devuelve todo a quien tiene la clave.
| Recurso | Se oculta |
|---|---|
arcane://environments, arcane://environment/{environmentId} | El apiKey y el edgeSessionId de cada entorno |
arcane://environment/{environmentId}/containers | El command de cada contenedor y los valores de sus etiquetas |
arcane://environment/{environmentId}/container/{containerId} | Los valores de config.env (los nombres de las variables se quedan: GH_PAT=[redacted: use container.get]), config.cmd, config.entrypoint, config.healthcheck.test, la salida de la comprobación de salud (state.health.log[].output) y los valores de las etiquetas |
arcane://environment/{environmentId}/projects, arcane://environment/{environmentId}/project/{projectId} | composeContent, envContent, overrideContent y el content de los archivos incluidos; en cada configuración de servicio (services[], runtimeServices[].serviceConfig): los valores de environment y de los args de build (los nombres se quedan), command, entrypoint, healthcheck.test, las órdenes y los valores de entorno de los ganchos pre_start, post_start, pre_stop y develop.watch[].exec, el dockerfile_inline de build, los valores de etiquetas y anotaciones, las opciones de registro que no sean de tamaño, rotación o etiqueta, y las opciones del proveedor |
arcane://environment/{environmentId}/images | Los valores de las etiquetas |
| Todos los recursos | La parte usuario:contraseña@ de cualquier URL en cualquier cadena (gitRepositoryURL, apiUrl, un mensaje de error), esté donde esté, también la forma relativa al esquema //usuario:contraseña@host; una contraseña con /, ?, # o @ sin codificar se quita entera, a costa de cortar a veces algo más que la información de usuario. git@host:repo, las direcciones mailto: y los DSN sin esquema se dejan como están |
- Un valor oculto se sustituye por la cadena
[redacted: use <acción>], que nombra la acción que lo devuelve. Una línea de órdenes se sustituye entera: no se puede recortar con seguridad. Una URL solo pierde la información de usuario y sigue sirviendo. - Se conservan los valores de las etiquetas que escribe el propio Docker Compose (
com.docker.compose.project,.service,.config-hash,.container-number,.project.working_diry el resto de su lista, derivadas de la estructura del proyecto) y deorg.opencontainers.image.*(metadatos públicos de la imagen). Cualquier otra etiqueta puede llevar cualquier cosa, como los usuarios de autenticación básica de Traefik o una etiquetacom.docker.compose.*puesta a mano, así que su valor se oculta. Los nombres de etiquetas y variables siempre se quedan. - Cuando se oculta algo, el valor gana un miembro
_redacted:fullValuees la acción que devuelve todo ypathsenumera las posiciones ocultas como punteros JSON. Los índices de lista y los nombres que cubre una regla (etiquetas, variables) se escriben*; cualquier otra clave de objeto aparece tal cual solo si está hecha de letras, dígitos,_,.y-(64 como mucho), y como*en otro caso. Si el valor de Arcane llegara a tener un miembro_redactedde primer nivel, se retiene y se enumera como/_redacted. - Los identificadores se quedan: ids, nombres, imágenes y etiquetas de imagen, estados, puertos, montajes, redes, el entorno de
failedEnvironments. - Las reglas siguen la posición de los campos en los esquemas de respuesta de Arcane, no los nombres de las claves. Una prueba unitaria rellena cada campo de texto que declaran los esquemas de Arcane incluidos para estas acciones y fija qué pasa con cada uno, así que una versión nueva de Arcane que añada un campo tiene que revisarse.
Errores
Sección titulada «Errores»Una lectura fallida es un error JSON-RPC (el resultado de un recurso no tiene indicador de error). Su mensaje es el que recibiría una llamada a herramienta, con la pista incluida, y su data lleva la uri y, cuando Arcane respondió, su status HTTP.
| Causa | Código |
|---|---|
| Arcane responde 404 (no existe el entorno, el contenedor o el proyecto), o la URI no corresponde a ningún recurso | -32602, recurso no encontrado (como pide la especificación MCP desde SEP-2164) |
| Arcane responde con otro estado de error | el estado × −100: -40100 para 401, -40300 para 403, -50000 para 500 (la convención de los rechazos propios del transporte HTTP) |
| No se puede contactar con Arcane, o el plazo termina la lectura | -32603, error interno |
Arcane también responde 404 para un contenedor (y una imagen, red o volumen) cuando no puede llegar al daemon de Docker del entorno. El código es entonces también -32602, pero la pista del mensaje dice que no se pudo llegar al daemon en lugar de dar el recurso por inexistente.
Guías de trabajo
Sección titulada «Guías de trabajo»Las guías son Markdown estático (text/markdown) escrito a partir de las notas de uso de las acciones, y están en inglés. Nombran las acciones por su ID canónico (project.up); cada una termina con una nota sobre cómo llama a un ID la superficie activa y un recordatorio de que las acciones destructivas necesitan confirmación y de que los modos de solo lectura y seguro retiran o previsualizan las acciones que cambian el estado.
| URI | Trata |
|---|---|
arcane://guides/deploy-compose-project | Crear un proyecto a partir de texto Compose, una plantilla o Git, desplegarlo, comprobarlo y cambiarlo después |
arcane://guides/update-images-safely | Buscar actualizaciones de imágenes sin descargarlas, leer los resultados guardados, aplicarlas a un proyecto, a un contenedor o a todo, y comprobarlo |
arcane://guides/back-up-and-restore-a-volume | Hacer copia de un volumen, revisar la copia, restaurarla entera o en parte, copias programadas |
arcane://guides/diagnose-an-unhealthy-container | Leer el estado de un contenedor, el registro de su comprobación de salud, sus registros, procesos e historial, y después arreglarlo |
Una prueba unitaria falla cuando una guía nombra una acción que el catálogo no tiene.
Tres de las guías también van adjuntas al prompt correspondiente (diagnose_container, update_project_images, backup_volume), que da el orden de los pasos para un contenedor, proyecto o volumen concretos.
El catálogo de acciones
Sección titulada «El catálogo de acciones»arcane://tools lista todas las acciones que ofrece este servidor, con la herramienta y la forma de llamada de la superficie activa; arcane://tools/{id} devuelve la descripción de una acción, su ruta, los parámetros obligatorios y el esquema de entrada completo. En modo de solo lectura, o para una acción excluida, la entrada dice por qué se retira la acción.