Archery MCP 2FA

Parche persistente que añade soporte de autenticación de dos factores (2FA) TOTP de Archery para @seaxlab/archery-mcp.

Este proyecto no se conecta directamente a la base de datos ni elude los mecanismos de permisos, enmascaramiento, limitación de tasa o auditoría de Archery. Solo amplía el flujo de inicio de sesión para que las cuentas de Archery con TOTP habilitado también puedan autenticarse a través del servicio MCP.

El parche actual solo se aplica a @seaxlab/archery-mcp@3.0.2. Antes de actualizar la dependencia ascendente, verifica que el parche siga siendo compatible y regenera el archivo de parche.

Características

• Inicia sesión automáticamente al arrancar con la cuenta y contraseña de Archery de la configuración.

• Cuando se detecte la verificación TOTP, solicita el código de 6 dígitos en la terminal interactiva.

• Cuando no hay terminal interactiva, proporciona herramientas MCP para completar la autenticación.

• Reutiliza la misma sesión de Archery después de una autenticación exitosa.

• El código TOTP se usa únicamente para la solicitud actual; no se escribe en el archivo de configuración ni en la caché de metadatos.

• Usa patch-package para aplicar el parche automáticamente después de instalar las dependencias.

Related MCP server: auth-vault

Requisitos del entorno

• Node.js 24 o superior.

• npm 10 o superior.

• Un servicio Archery accesible; el paquete ascendente indica soporte para Archery v1.8.5.

• Una cuenta de Archery con TOTP habilitado, o una contraseña de cuenta normal.

Inicio rápido

1. Obtener el proyecto e instalar las dependencias

git clone <repository-url>
cd archery-mcp-2fa
npm ci

Cuando npm ci finalice, el script postinstall aplicará automáticamente el parche 2FA en patches/.

2. Preparar el archivo de configuración

Puedes crear la configuración basándote en el ejemplo proporcionado por el paquete ascendente:

mkdir -p ~/.config/archery-mcp
cp node_modules/@seaxlab/archery-mcp/config.example.toml \
  ~/.config/archery-mcp/pro.toml
chmod 600 ~/.config/archery-mcp/pro.toml

Edita ~/.config/archery-mcp/pro.toml y completa al menos lo siguiente:

env = "pro"

[server]
host = "127.0.0.1"
port = 3000

[archery]
base_url = "https://archery.example.com"
username = "mcp_service"
password = "replace-with-a-strong-password"

[query]
default_limit = 100
max_limit = 500

[cache]
enabled = true
ttl_seconds = 604800
exclude_instance_names = []
exclude_instance_ids = []

El archivo de configuración contiene la contraseña en texto plano. Limita siempre los permisos del archivo y no envíes la configuración real al repositorio.

Para la descripción completa de las opciones de configuración, consulta node_modules/@seaxlab/archery-mcp/README.md y config.example.toml del proyecto ascendente después de la instalación.

3. Iniciar el servicio

Especifica el archivo de configuración mediante un argumento de línea de comandos:

npm start -- --config ~/.config/archery-mcp/pro.toml

También puedes usar variables de entorno:

ARCHERY_MCP_CONFIG=~/.config/archery-mcp/pro.toml npm start

La dirección MCP predeterminada es:

http://127.0.0.1:3000/mcp

La dirección de verificación de salud es:

http://127.0.0.1:3000/health

Flujo de autenticación TOTP

Terminal interactiva

Si la cuenta tiene TOTP habilitado, la terminal mostrará el siguiente aviso al arrancar:

archery-mcp [env=pro] Archery requires TOTP authentication
请输入当前 6 位 TOTP 验证码:

Introduce el código que muestra actualmente el autenticador. Tras una autenticación exitosa, el servicio comienza a escuchar en el puerto:

archery-mcp [env=pro] TOTP authentication succeeded
archery-mcp [env=pro] listening on http://127.0.0.1:3000/mcp

Si el código no es válido, puedes reintentarlo directamente. Cuando la sesión de Archery caduque o el proceso se reinicie, será necesario volver a autenticarse.

Sin terminal interactiva

Cuando el servicio se inicia desde un contenedor, una tarea en segundo plano o un administrador de procesos sin terminal interactivo, el servicio sigue arrancando y registra las siguientes herramientas MCP:

Pasos de autenticación:

1. Llama a archery_auth_status.

2. Si devuelve two_factor_required: true, pide al usuario que proporcione el código de 6 dígitos que muestra actualmente el autenticador.

3. Llama a archery_submit_otp con el parámetro { "otp": "123456" }.

4. Después de confirmar que devuelve authenticated: true, llama a las herramientas de consulta o auditoría SQL.

Aparte de las dos herramientas de autenticación mencionadas, el resto de herramientas MCP se mantienen igual que en el paquete ascendente @seaxlab/archery-mcp.

Configuración del cliente MCP

Conéctate con un cliente MCP compatible con Streamable HTTP:

{
  "mcpServers": {
    "archery": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

Codex se puede configurar en ~/.codex/config.toml:

[mcp_servers.archery]
url = "http://127.0.0.1:3000/mcp"

Claude Code se puede agregar mediante la línea de comandos:

claude mcp add --transport http archery http://127.0.0.1:3000/mcp

Estructura del proyecto

.
├── patches/
│   └── @seaxlab+archery-mcp+3.0.2.patch  # TOTP 支持补丁
├── package.json                           # 依赖和启动脚本
├── package-lock.json                      # 锁定依赖版本
└── README.md

Comandos habituales

No uses directamente npx -y @seaxlab/archery-mcp@3.0.2 para iniciar, ya que se ejecutaría el paquete npm oficial sin el parche 2FA de este proyecto.

Notas de seguridad

• Por defecto solo escucha en 127.0.0.1. El endpoint HTTP de MCP no tiene autenticación por sí mismo y no debe exponerse directamente a Internet.

• Si necesitas acceso entre máquinas, añade TLS, autenticación de acceso y control de acceso de red en la capa de proxy inverso.

• La contraseña de Archery se guarda en la configuración TOML. Establece chmod 600 y utiliza una cuenta de servicio dedicada con privilegios mínimos.

• No envíes contraseñas reales, códigos TOTP, cookies de sesión, direcciones internas de Archery ni configuraciones de producción a repositorios, issues o registros.

• El TOTP se transmite a través de solicitudes MCP. Al usar un cliente MCP remoto, asegúrate de que el canal de comunicación sea confiable y esté cifrado.

Compatibilidad y mantenimiento

El parche actúa directamente sobre los artefactos de compilación del paquete ascendente, por lo que los cambios de versión ascendente pueden hacer que el parche no se aplique o que su comportamiento sea incompatible. Al actualizar, se recomienda:

1. Actualiza la versión de @seaxlab/archery-mcp en package.json.

2. Ejecuta npm install y comprueba si hay conflictos con el parche.

3. Reimplementa y verifica las modificaciones 2FA en node_modules/@seaxlab/archery-mcp.

4. Ejecuta npx patch-package @seaxlab/archery-mcp para generar el nuevo parche.

5. Verifica el flujo de autenticación tanto en una terminal interactiva como sin terminal interactiva.

Contribuciones

Te invitamos a enviar Issues o Pull Requests. Antes de enviar código, asegúrate de que no incluya cuentas reales, contraseñas, códigos, cookies, dominios internos u otra información sensible.

Agradecimientos y aviso legal

Este proyecto crea un parche basado en el paquete de distribución pública de @seaxlab/archery-mcp; no es un proyecto oficial de Archery ni de los mantenedores del paquete ascendente. Los derechos sobre Archery y los nombres relacionados pertenecen a sus respectivos propietarios.