Registro de cambios

Esta página es para quien instala y ejecuta arcane-mcp. Describe cada versión por lo que te permite hacer y por lo que quizá tengas que cambiar, no commit a commit. Las notas detalladas, commit a commit, están en cada versión de GitHub.

Sin publicar

La primera versión pública todavía no tiene etiqueta y su número aún está por decidir. Todo lo que sigue es lo que incluirá. No hay ninguna versión anterior, así que no hay nada desde lo que actualizar ni notas de migración.

Está hecha para Arcane v2.17.2 (publicada el 2026-10-31); Arcane v2.16.x no se admite, y la v2.17.0 y la v2.17.1 ya no se prueban: a través de un agente directo pueden cortar descargas de imágenes y despliegues de proyectos en conexiones reutilizadas, algo que arcane-mcp ya no esquiva, así que actualiza Arcane a la v2.17.2, que lo corrige (getarcaneapp/arcane#4592). Desde la v2.17.1, updater.run, con o sin resourceIds, también actualiza los contenedores que renunciaron a las actualizaciones (con una etiqueta o con el ajuste de contenedores excluidos) y tienen una actualización pendiente, como Arcane hace ahora en toda ejecución manual; pasa automatic: true para respetar esas renuncias como lo hace la actualización automática programada. La confirmación de esa ejecución lo indica. Con la v2.17.2, project.up y project.redeploy aceptan build: true para reconstruir antes del despliegue las imágenes de los servicios que tienen una sección build (el redespliegue de una sincronización GitOps ya lo hace por sí solo), y Arcane responde con un 4xx en lugar de un 500 a los registros desconocidos y las peticiones no válidas, algo que ahora describen las notas de uso.

Todas las capacidades de Arcane, en tres superficies de herramientas

• 461 acciones en 52 dominios cubren todas las operaciones de la API de Arcane (442 en la v2.17.2) y las rutas que Arcane sirve fuera de la descripción de su API y que una persona puede usar, como los flujos de logs y estadísticas o el terminal de los contenedores: contenedores, imágenes, proyectos Compose, volúmenes, redes, Swarm, Podman (pods, YAML de Kubernetes, quadlets, secretos, actualización automática), entornos y agentes, registros, GitOps, plantillas, copias de seguridad, análisis de vulnerabilidades, usuarios, roles, ajustes y diagnóstico. Las pocas rutas que quedan fuera (el túnel propio de los agentes edge, las compilaciones solo para pruebas, el reenvío de telemetría de la interfaz web) están listadas con su motivo, y una comprobación en la CI falla cuando una operación de Arcane no es una acción ni está en esa lista. La referencia de herramientas recoge todas las acciones.
• Tres formas de presentarlas a tu cliente: dynamic (la predeterminada: dos herramientas que buscan en el catálogo y ejecutan una acción), meta (una herramienta por dominio) e individual (una herramienta por acción). Desde cualquier superficie se llega a todas las acciones, con los mismos parámetros y las mismas reglas de seguridad. Consulta Superficies de herramientas.
• Cada acción tiene una nota de uso y acciones relacionadas, contrastadas con el código fuente de Arcane, para que el asistente sepa de dónde sale cada ID y qué hacer a continuación.
• Los flujos en directo se convierten en acciones acotadas: los logs de contenedores, proyectos y servicios de Swarm, las estadísticas, el canal de eventos en directo y la ejecución de un comando en un contenedor escuchan unos segundos y devuelven lo que ha llegado. Las descargas y compilaciones de imágenes y los despliegues de proyectos se siguen hasta el final y se resumen. Se pueden descargar y subir ficheros. Consulta Flujos y ficheros.
• Resultados legibles: el texto de un resultado es Markdown a la medida del modelo (una tabla para una lista, líneas de campos para un objeto) y dice lo que deja fuera (una lista vacía de contenedores, imágenes, proyectos, volúmenes, redes o entornos dice qué filtros pueden dejarla vacía), mientras que el contenido estructurado lleva siempre el valor completo. Cada resultado termina con unos pocos pasos siguientes sugeridos. Al texto que viene de Arcane se le quitan las secuencias de escape de terminal y los caracteres de control. Consulta Formato de salida.
• Errores que indican por dónde seguir: los argumentos se comprueban antes de llamar a Arcane, y un fallo dice qué parámetros se aceptan (y, cuando Arcane rechaza campos, cada uno por el argumento que pasaste, con el motivo de Arcane), qué acción de listado encuentra un ID válido o qué credencial o rol hay que revisar.
• Catálogo apto para pasarelas: todos los nombres, títulos y descripciones de herramientas, prompts y recursos que lista el servidor (esquemas y esquemas de salida incluidos) son ASCII puro, para las pasarelas MCP que validan el catálogo de un servidor antes de admitirlo; los caracteres tipográficos de las descripciones del propio Arcane se escriben en ASCII.

Seguridad

• Las acciones destructivas necesitan aprobación. Los borrados, purgas, kills, restauraciones, redespliegues y cambios en la definición de un stack no hacen nada sin confirm: true. En los clientes que admiten la elicitación MCP, el servidor te lo pregunta directamente, mostrando la acción y sus argumentos (con las credenciales ocultas); si rechazas, la respuesta es un limpio «no se ha hecho nada». Consulta Confirmación de las acciones destructivas.
• El modo de solo lectura (ARCANE_MCP_READ_ONLY) quita todas las acciones que cambian algo; el modo seguro (ARCANE_MCP_SAFE_MODE o --safe-mode) las mantiene, pero responde con una vista previa de la petición (método, ruta, consulta, cuerpo y si es destructiva, bajo una línea en negrita NOT EXECUTED), que nombra las dos formas, para que quien la lea sepa desactivar la que se usó al arrancar el servidor; las exclusiones (ARCANE_MCP_EXCLUDE_TOOLS) ocultan las acciones o los dominios enteros que elijas. Una exclusión que no coincide con nada se avisa al arrancar.
• Un interruptor de seguridad mal escrito detiene el servidor en lugar de dejarlo escribiendo sin avisar, y lo mismo ocurre con cualquier número, duración o nivel de log ilegible.
• Un registro de auditoría por llamada (ARCANE_MCP_AUDIT_LOG): qué acción se ejecutó, con qué resultado y cómo se aprobó si era destructiva, nunca los valores de los argumentos.
• Un plazo por acción (ARCANE_MCP_ACTION_TIMEOUT, 30 minutos por defecto) acota también las descargas de imágenes, las compilaciones y las descargas de ficheros largas.
• Credenciales solo donde Arcane las necesita: las rutas públicas (inicio de sesión, versión, estado…) se llaman sin tu clave.
• Ningún segmento de punto llega a la ruta de una petición: un argumento de ruta que sea . o .., o que tenga una parte así (a/../b, %2e%2e), se rechaza antes de enviar nada, así que un proxy inverso que resuelva los segmentos de punto no puede convertir volume.delete en el borrado del entorno. Consulta Seguridad.
• Todo ello se explica en Seguridad.

Uso remoto por HTTP

• Streamable HTTP con --http, además de stdio. Cada usuario puede traer su propia clave de API de Arcane, y cada clave tiene su propio servidor, así que cada cual actúa con sus propios permisos en Arcane.
• Dos formas de autenticarse: un token bearer compartido (ARCANE_MCP_HTTP_TOKEN), o ARCANE_MCP_HTTP_AUTH=apikey, en el que el token bearer es la propia clave de API de Arcane del usuario, verificada contra Arcane. Esta segunda encaja con los conectores remotos que solo pueden poner una cabecera Authorization.
• Endurecido de serie: límites de claves, sesiones, peticiones simultáneas, tamaño del cuerpo y anidamiento JSON (100 niveles por mensaje, como en stdio); una sesión queda ligada a la clave que la abrió; protección frente a peticiones de otro origen y frente a DNS rebinding (ARCANE_MCP_HTTP_ALLOWED_HOSTS, ARCANE_MCP_HTTP_TRUSTED_ORIGINS); un cupo de autenticaciones fallidas por dirección de cliente (y por /48 de IPv6, para que un bloque IPv6 grande no pueda esquivarlo rotando; ARCANE_MCP_HTTP_AUTH_NETWORK_FACTOR dimensiona o desactiva ese límite); unos ajustes de proxies de confianza que no pueden funcionar con la escucha detienen el servidor al arrancar; un límite de peticiones opcional por clave; sondas /healthz y /readyz.
• El HTTP sin cifrar en la red se anuncia, o se rechaza: un puerto TCP al que llegan otras máquinas sin TLS avisa al arrancar, en cualquier modo de autenticación. ARCANE_MCP_HTTP_ALLOW_PLAINTEXT=true (--http-allow-plaintext) declara que un proxy delante cifra ese tramo y convierte el aviso en una línea INFO, y false es un modo endurecido que se niega a arrancar un puerto así (TLS, loopback y los sockets unix arrancan siempre). Consulta HTTP sin cifrar y el modo endurecido.
• Varias instancias de Arcane desde un único servidor: se enumeran en ARCANE_URL como pares nombre=url y cada petición HTTP elige una con X-Arcane-URL. El servidor nunca contacta con una URL que no hayas listado ni sigue una redirección de Arcane hacia otro host.
• Un aviso cuando la versión de Arcane difiere de la del catálogo: al arrancar, por stdio y por HTTP, el servidor lee en segundo plano la versión de cada instancia (una ruta pública, sin tu clave, sin retrasar el arranque) y registra un aviso cuando su major.minor no es el del catálogo, para que un 404 o un 422 de una ruta que cambió no se confunda con un fallo. /readyz?format=json muestra catalogVersion y si cada instancia coincide con ella (versionMatch), nunca la versión exacta; una diferencia nunca hace fallar /readyz. Consulta Solución de problemas.
• Las acciones que un Arcane más antiguo no tiene se rechazan con el motivo: cada acción posterior a Arcane v2.10.0 registra la versión que la añadió (find y arcane://tools/{id} la muestran como since). En una instancia que se sabe que ejecuta una versión anterior, la llamada se rechaza antes de que nada llegue a Arcane, nombrando ambas versiones; en una instancia cuya versión es desconocida o de desarrollo, la llamada sigue adelante y un 404 lleva la misma frase como pista. Consulta Solución de problemas.
• HTTP sin estado (ARCANE_MCP_HTTP_STATELESS), el transporte de la revisión 2026-07-28 del protocolo, como opción.
• Una tarjeta del servidor (SEP-2127) en /mcp/server-card y /server-card: la identidad del servidor, su punto final, las revisiones del protocolo y las cabeceras que necesita una conexión, para los clientes y registros que descubren servidores antes de conectarse; nunca una credencial ni nada sobre el Arcane que hay detrás. Con ETag para la caché, limitada por dirección (ARCANE_MCP_HTTP_DISCOVERY_RATE_LIMIT_RPS, _BURST), activada por defecto; ARCANE_MCP_HTTP_SERVER_CARD=off la quita. Consulta Tarjeta del servidor.
• Un stdio más robusto: una línea mal formada, una que pasa de ARCANE_MCP_STDIO_MAX_LINE_BYTES (16 MiB por defecto) o una que anida JSON a más de 100 niveles recibe un error y la sesión continúa, un servidor arrancado a mano en un terminal dice en una línea que es un servidor MCP y dónde se explica cómo configurar el cliente, y los ajustes solo HTTP que recibe un servidor stdio se nombran en un aviso al arrancar en lugar de ignorarse sin decir nada; un valor ilegible de uno de ellos ya no detiene un servidor stdio, solo uno HTTP.
• Consulta Configuración.

Recursos, prompts y autocompletado

• Recursos: entornos, contenedores, proyectos e imágenes en JSON que tu cliente puede adjuntar a la conversación, cuatro guías de trabajo (desplegar un proyecto Compose, actualizar imágenes con seguridad, hacer y restaurar la copia de seguridad de un volumen, diagnosticar un contenedor que no está sano) y el propio catálogo de acciones. Los resultados de environment.get, container.get y project.get terminan con un resource_link al recurso correspondiente.
• Prompts: siete flujos de trabajo paso a paso que tu cliente ofrece como comandos de barra, como diagnosticar un contenedor, actualizar las imágenes de un proyecto, un informe de seguridad o liberar espacio en disco. Nunca se saltan la confirmación de un paso destructivo.
• Autocompletado: los clientes que lo admiten sugieren entornos, contenedores, proyectos, imágenes, volúmenes y servicios de Swarm, sacados de tu Arcane, mientras rellenas un argumento de un prompt o la dirección de un recurso.
• Notificaciones de progreso mientras se ejecutan las operaciones largas, para los clientes que las piden.

Iconos

• El servidor y todas las herramientas, prompts y recursos llevan el icono de arcane-mcp, para los clientes que muestran uno. ARCANE_MCP_ICONS=off los quita, para un cliente que los rechace. Consulta Iconos.

Esquemas de salida

• Experimentales y desactivados por defecto: con ARCANE_MCP_OUTPUT_SCHEMAS=on, la superficie individual declara la forma del resultado de cada acción (420 de las 461), derivada de la propia descripción de la API de Arcane y contrastada con resultados reales. Un resultado que no encaja nunca se convierte en un error. Consulta Esquemas de salida.

Distribución

• Cada versión publicará binarios para Linux, macOS y Windows en amd64 y arm64 (más un único binario de macOS para ambas arquitecturas), archivos comprimidos, un SBOM por binario y un fichero de sumas de comprobación firmado, con procedencia de la compilación, para que puedas verificar lo que descargas.
• Una imagen de contenedor firmada y atestada para linux/amd64 y linux/arm64, ghcr.io/jmrplens/arcane-mcp, también en Docker Hub cuando esté configurado allí.
• Una extensión de Claude Desktop (.mcpb), una por sistema operativo y otra para los tres, cuyos ajustes piden la URL de tu Arcane y tu clave de API (un campo marcado como sensible, que Claude Desktop trata como secreto) y ofrecen la superficie, el modo de solo lectura y el modo seguro.
• Paquetes que llevan el mismo binario de la versión: npx -y @jmrp.io/arcane-mcp (npm), uvx arcane-mcp (PyPI), dnx arcane-mcp (NuGet, .NET 10), brew install jmrplens/tap/arcane-mcp (Homebrew) y winget install jmrplens.arcane-mcp (winget, en cuanto se fusione su primera versión).
• Una entrada en el MCP Registry, io.github.jmrplens/arcane-mcp, que apunta a las extensiones, a la imagen de contenedor y a los paquetes de npm, PyPI y NuGet.
• Instalación tiene una página por canal. Hasta la primera versión, compílalo desde el código fuente como explica Puesta en marcha. Publicación de versiones describe cómo se construyen las versiones y cómo verificarlas.

Probado contra un Arcane real

• Una batería de extremo a extremo ejecuta cada acción en las tres superficies contra instancias reales de Arcane v2.17.2, un host Podman incluido: 455 de las 461 acciones funcionan; las 6 restantes no se pueden ejercitar allí, por los motivos que recoge Cobertura e2e.
• Está listo un corpus de evaluación con modelos con 94 peticiones realistas; todavía no se ha medido ningún modelo real con él. La página de casos de uso recorre algunas.

Cómo se registran las versiones

Esta página se escribe a mano, en inglés y en español, y las notas de las versiones de GitHub se generan.

• Aquí, cada cambio que notarías (una capacidad nueva, un ajuste nuevo, un valor por defecto distinto, algo que ahora detiene el servidor al arrancar, la corrección de un comportamiento visible) se añade en Sin publicar en el mismo cambio que lo introduce. Cuando se etiqueta una versión, esa sección recibe el número de versión y la fecha como encabezado (## v0.2.0 (2026-11-20)), y encima empieza una nueva sección Sin publicar vacía; el flujo de publicación rechaza una etiqueta cuya versión no tenga esa sección en alguno de los dos idiomas. Los cambios que te piden algo (un ajuste renombrado, un valor que ahora se rechaza) van bajo un apartado Cambios de comportamiento al principio de la sección de la versión.
• En GitHub, las notas de cada versión se generan a partir de los mensajes de commit, agrupadas en novedades, correcciones, seguridad y documentación, junto con los artefactos y cómo verificarlos.

Por qué las dos: las notas generadas son completas, pero siguen a los commits, que también cubren pruebas, CI y trabajo interno, y solo están en inglés. Este sitio es bilingüe, y quien decide si actualizar necesita un resumen breve por capacidades y una lista clara de lo que tiene que cambiar, algo que solo una persona escribe bien. Se mantienen por separado para que ninguna de las dos tenga que renunciar a nada.