Huly

Huly MCP

Huly MCP es un servidor MCP completo para la integración con Huly. Publicado en npm como @firfi/huly-mcp.

Se conecta a implementaciones de la Plataforma Huly y también debería funcionar con las bifurcaciones Platform Collective y TraceX. Intabia 0.8.33 / modelo 0.8.4 ha sido probado para compatibilidad; las brechas conocidas se rastrean en el problema #279. El soporte para bifurcaciones sigue siendo no oficial.

Alternativa a Huly CLI

¿Buscas una CLI de Huly, integración de Huly nativa de terminal, o una alternativa de scripting y automatización a ejecutar un servidor MCP? Huly CLI es una interfaz de línea de comandos completa para Huly, publicada como @firfi/huly-cli, con paridad total de operaciones de Huly con Huly MCP. Expone las mismas operaciones de Huly como comandos nativos y conscientes del esquema con salida legible por humanos o JSON, entradas respaldadas por archivos, cargas y descargas.

Huly MCP y Huly CLI se mantienen juntos en este monorepo y derivan del mismo registro de operaciones compartido, manteniendo alineadas las entradas, salidas, advertencias y fallos tipados de las operaciones. Consulta la documentación de Huly CLI para la referencia completa de comandos generada, o explora ejemplos de CLI, patrones de automatización de Huly y la comparación entre Huly MCP y CLI.

Instalación

Requisito de Node.js

Huly MCP requiere Node.js 22.19.0 o posterior. Los clientes MCP no proporcionan un entorno de ejecución de Node.js: node, npx, y el ejecutable del paquete #!/usr/bin/env node resuelven Node.js desde el entorno en el que se ejecuta el cliente MCP. Verifica ese entorno antes de la instalación:

node --version

Si un cliente MCP inicia Huly MCP con un entorno de ejecución más antiguo, Huly MCP inicializa una superficie MCP solo de diagnóstico en lugar de cargar la aplicación incompatible. Sus instrucciones de servidor y la herramienta get_huly_startup_diagnostic informan el ejecutable detectado y la versión requerida, y el mismo diagnóstico unsupported Node.js runtime se escribe en stderr. Actualiza Node.js o configura el comando del servidor MCP para usar la ruta absoluta de un ejecutable de Node.js compatible, luego reinicia el servidor MCP. Las operaciones de Huly permanecen no disponibles hasta que se actualice el entorno de ejecución.

La configuración estándar usa un token de API de Huly y funciona con la mayoría de los clientes MCP:

{
  "mcpServers": {
    "huly": {
      "command": "npx",
      "args": ["-y", "@firfi/huly-mcp@latest"],
      "env": {
        "HULY_URL": "https://your-huly-instance.example.com",
        "HULY_TOKEN": "your-huly-api-token",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }
  }
}

Prefiere un token de API administrado creado en la configuración de la cuenta de Huly cuando la implementación de destino lo admita. Los tokens administrados están vinculados a un espacio de trabajo, tienen una caducidad asignada y pueden revocarse sin cambiar la contraseña de la cuenta. Aún heredan los derechos completos de la cuenta en ese espacio de trabajo, así que usa una cuenta de integración dedicada solo con el rol de espacio de trabajo, las membresías de espacio y el acceso a datos que la automatización necesite. Las implementaciones más antiguas de Huly pueden no exponer la configuración de tokens administrados; la autenticación por correo electrónico/contraseña sigue disponible como respaldo de compatibilidad.

Valores Predeterminados de Exposición de Herramientas

De forma predeterminada (HULY_TOOL_MODE=auto), Huly MCP optimiza para los clientes MCP actuales evitando una lista eager de 470 herramientas. Las sesiones exactas de claude-code reciben herramientas nativas de Huly. Codex, Cursor, Windsurf, Copilot, OpenCode, clientes estilo Claude AI/Desktop y clientes desconocidos reciben una pequeña superficie proxy: list_tool_categories, search_tools, get_tool_schema y invoke_tool.

Los nombres exactos de herramientas nativas aún se despachan cuando un cliente las llama directamente, pero muchos clientes solo llaman a las herramientas devueltas por tools/list. Establece HULY_TOOL_MODE=native para que cada herramienta de Huly aparezca de primera clase, o usa TOOLSETS / TOOLS para fijar herramientas nativas de uso frecuente mientras mantienes disponible el descubrimiento proxy.

codex mcp add huly \
  --env HULY_URL=https://your-huly-instance.example.com \
  --env HULY_TOKEN=your-huly-api-token \
  --env HULY_WORKSPACE=yourworkspace \
  -- npx -y @firfi/huly-mcp@latest

[mcp_servers.huly]
command = "npx"
args = ["-y", "@firfi/huly-mcp@latest"]

[mcp_servers.huly.env]
HULY_URL = "https://your-huly-instance.example.com"
HULY_TOKEN = "your-huly-api-token"
HULY_WORKSPACE = "yourworkspace"

claude mcp add huly \
  -e HULY_URL=https://your-huly-instance.example.com \
  -e HULY_TOKEN=your-huly-api-token \
  -e HULY_WORKSPACE=yourworkspace \
  -- npx -y @firfi/huly-mcp@latest

{
  "servers": {
    "huly": {
      "command": "npx",
      "args": ["-y", "@firfi/huly-mcp@latest"],
      "env": {
        "HULY_URL": "https://your-huly-instance.example.com",
        "HULY_TOKEN": "your-huly-api-token",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }
  }
}

{
  "mcp": {
    "huly": {
      "type": "local",
      "command": ["npx", "-y", "@firfi/huly-mcp@latest"],
      "environment": {
        "HULY_URL": "https://your-huly-instance.example.com",
        "HULY_TOKEN": "your-huly-api-token",
        "HULY_WORKSPACE": "yourworkspace"
      }
    }
  }
}

pi install npm:pi-mcp-adapter

Actualización

La etiqueta @latest le pide al ejecutor de paquetes la versión más reciente. Algunos clientes MCP mantienen procesos de servidor o instalaciones resueltas activos, así que reinicia o vuelve a agregar el servidor al actualizar:

Publicación de Mantenimiento en Producción

Publica desde un checkout limpio y actual de master con el entorno de ejecución de Node.js certificado preferido:

mise exec node@24.15.0 -- pnpm local-release

Usa este comando exacto incluso si una versión más nueva de Node.js está activa en el host. La compilación de publicación acepta solo las versiones exactas de Node.js certificadas por CI; esto es intencionalmente más estricto que el requisito de entorno de ejecución del paquete. Consulta la guía de publicación en producción para verificaciones previas, comportamiento de reejecución y verificación.

Transporte HTTP

De forma predeterminada, el servidor usa transporte stdio. Para transporte HTTP:

HULY_URL=https://your-huly-instance.example.com \
HULY_TOKEN=your-huly-api-token \
HULY_WORKSPACE=yourworkspace \
MCP_TRANSPORT=http \
npx -y @firfi/huly-mcp@latest

El servidor escucha en http://127.0.0.1:3000/mcp de forma predeterminada.

Configura con MCP_HTTP_PORT y MCP_HTTP_HOST:

MCP_TRANSPORT=http MCP_HTTP_PORT=8080 MCP_HTTP_HOST=0.0.0.0 npx -y @firfi/huly-mcp@latest

Soporte de Protocolo MCP HTTP

Ambos transportes se implementan con el servidor MCP y los adaptadores de protocolo de Effect AI. El servidor configura el protocolo sin estado MCP 2026-07-28 publicado y el protocolo de compatibilidad MCP 2025-06-18. HTTP moderno requiere un mensaje JSON-RPC por POST, Accept: application/json, text/event-stream, MCP-Protocol-Version: 2026-07-28, Mcp-Method, metadatos de cliente Mcp-Name específicos del método y _meta.io.modelcontextprotocol/* por solicitud. HTTP heredado admite sesiones inicializadas usando el Mcp-Session-Id devuelto y llamadas sin estado con enlaces locales a la solicitud. Las credenciales de Huly se configuran por separado a través de variables de entorno o encabezados x-huly-* admitidos.

Consulta arquitectura y certificación de transporte MCP para el límite de implementación y el registro de verificación actual.

Para implementaciones HTTP alojadas o tunelizadas, puedes requerir un token de portador de endpoint MCP:

MCP_TRANSPORT=http \
MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
npx -y @firfi/huly-mcp@latest

Los clientes HTTP deben entonces enviar:

Authorization: Bearer <MCP_AUTH_TOKEN>

MCP_AUTH_TOKEN protege solo el endpoint MCP HTTP /mcp. No está relacionado con HULY_TOKEN, no autentica ante Huly y no reemplaza HULY_EMAIL / HULY_PASSWORD / HULY_TOKEN. Las credenciales de Huly aún se requieren a través de variables de entorno del proceso o, para implementaciones de URL alojadas, los encabezados x-huly-* admitidos. Las implementaciones stdio no usan MCP_AUTH_TOKEN.

Perfiles CLI y stdio compartidos

Guarda un perfil con huly auth login --profile work, luego establece HULY_PROFILE=work en el entorno del servidor MCP stdio. Ambos procesos deben ejecutarse bajo el mismo usuario de SO y directorio de configuración. Stdio nunca sigue el perfil CLI activo implícitamente. Los tokens guardados están vinculados a su URL de instancia y espacio de trabajo; los cambios requieren iniciar sesión nuevamente o una inyección completa de credenciales de entorno. Consulta las instrucciones de perfil CLI. La configuración HTTP permanece sin cambios.

Configuración de Encabezados HTTP Alojados

Para implementaciones de URL alojadas, mantén el proceso del servidor configurado con MCP_TRANSPORT=http. Una capa de alojamiento puede reenviar credenciales de Huly por sesión como encabezados de solicitud, de modo que un servidor alojado pueda atender diferentes espacios de trabajo de Huly sin variables de entorno HULY_* a nivel de proceso.

Encabezados v1 admitidos:

Si está presente cualquier encabezado x-huly-* admitido, todos los encabezados requeridos deben estar presentes y los encabezados x-huly-* no admitidos se rechazan. Las solicitudes con solo encabezados x-huly-* no admitidos (por ejemplo, un ID de seguimiento de proxy) usan la configuración de entorno del proceso. Los valores faltantes no se completan desde variables de entorno. La autenticación por correo electrónico/contraseña no se admite en la configuración de encabezados alojados v1.

Para un ejemplo de esquema de publicación de Smithery, consulta docs/SMITHERY_URL_PUBLISH.md.

Variables de Entorno

*Auth: Prefiera HULY_TOKEN. Use HULY_EMAIL + HULY_PASSWORD solo cuando la implementación de Huly no admita un token de API administrado u otra restricción de compatibilidad requiera autenticación por contraseña.

Herramientas de Diagnóstico Integradas

get_version devuelve la versión actual del servidor y la última versión de npm.

get_huly_context devuelve contexto de configuración/tiempo de ejecución saneado para la sesión MCP actual sin conectarse a Huly. Informa la versión del paquete, transporte, modo de autenticación, origen/host/protocolo de URL de Huly saneado, espacio de trabajo, tiempo de espera, fuentes de configuración, filtrado de alcance de herramientas nativas y exposición resuelta de herramientas nativas/proxy. Los tokens, contraseñas, valores de correo electrónico, encabezados de credenciales, rutas de URL, cadenas de consulta de URL y credenciales de URL nunca se devuelven.

Recursos MCP

El servidor expone Recursos MCP de solo lectura como contexto JSON para clientes que admiten resources/read.

resources/list devuelve recursos de proyecto activos concretos. Los recursos de problemas se basan en plantillas: use resources/templates/list para descubrir plantillas de URI de problemas compatibles y luego lea una URI de problema conocida.

Trabajo Pendiente

Las notas de trabajo pendiente de funciones y paridad de SDK están en docs/BACKLOG.md.

Herramientas Disponibles

Cuando la exposición de herramientas resuelta es proxy, los clientes ven las herramientas integradas más estas meta-herramientas de proxy. Las herramientas nativas de Huly se descubren e invocan a través del catálogo de candidatos proxy. Los nombres exactos de herramientas nativas también se despachan cuando un cliente las llama directamente, sujeto a las reglas de alcance de PROXY_OUTPUT_STRICT, pero las herramientas nativas ocultas no se anuncian a través de tools/list.

Meta-Herramientas de Proxy

Categorías de TOOLSETS: projects, issues, comments, milestones, documents, storage, attachments, contacts, channels, calendar, time tracking, search, associations, activity, notifications, workspace, approvals, boards, cards, collaborators, custom-fields, drive, hr, inventory, labels, leads, mail, templates, model-administration, planner, preferences, processes, recruiting, sdk-discovery, security-administration, sequence-administration, spaces, support, tag-categories, tags, task-management, test-management, user-statuses, views, virtual-office, workbench, workflow-statuses

Proyectos

Problemas

Comentarios

Hitos

Documentos

Almacenamiento

Adjuntos

Contactos

Canales

Calendario

Seguimiento de tiempo

Búsqueda

Asociaciones

Actividad

Notificaciones

Espacio de trabajo

Aprobaciones

Tableros

Tarjetas

Colaboradores

Campos-Personalizados

Drive

Hr

Inventario

Etiquetas

Leads

Correo

Plantillas

Administración de modelos

Planificador

Preferencias

Procesos

Reclutamiento

Sdk-Discovery

Security-Administration

Sequence-Administration

Spaces

Support

Tag-Categories

Etiquetas

Gestión de tareas

Gestión de pruebas

Estados de usuario

Vistas

Oficina virtual

Workbench

Workflow-Statuses

Solución de problemas

Respaldo de contraseña con caracteres especiales

Si tu contraseña de Huly contiene caracteres como *, %, ! o #, pasarla a través de banderas de entorno de CLI como -e o --env puede fallar porque el shell interpreta estos caracteres antes de que lleguen al proceso.

Solución: Edita tu archivo de configuración de MCP directamente en lugar de pasar la contraseña a través del shell:

• Codex: ~/.codex/config.toml
• Claude Code: ~/.claude.json (ámbito de usuario) o .mcp.json (ámbito de proyecto)
• Claude Desktop: claude_desktop_config.json en la ubicación indicada en la sección de instalación
• VS Code y Cursor: usa la ubicación de configuración del cliente de la sección de instalación; evita confirmar archivos de espacio de trabajo que contengan credenciales reales
• Windsurf: edita tu archivo de configuración de MCP de Windsurf directamente
• OpenCode: ~/.config/opencode/opencode.json

Para la configuración JSON de Claude, los caracteres sensibles al shell anteriores pueden escribirse directamente. Los caracteres reservados de JSON como " y \ aún necesitan escape JSON normal:

{
  "mcpServers": {
    "huly": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@firfi/huly-mcp@latest"],
      "env": {
        "HULY_URL": "https://your-huly-instance.com",
        "HULY_EMAIL": "you@example.com",
        "HULY_PASSWORD": "p@ss*w0rd!#%",
        "HULY_WORKSPACE": "your-workspace"
      }
    }
  }
}

Prefiere HULY_TOKEN en lugar de este respaldo de contraseña cuando el despliegue admita tokens de API gestionados (consulta Variables de entorno).

El cliente MCP muestra "Failed to reconnect"

Después de cambiar la configuración de MCP, algunos clientes (incluido Claude Code) requieren un reinicio completo, no solo una reconexión. Sal de la aplicación por completo y vuelve a abrirla.

Puedes verificar que la conexión funciona de forma independiente con:

claude mcp list  # Should show "Connected"

Huly autohospedado: cuenta bloqueada después de intentos de inicio de sesión fallidos

Huly bloquea el inicio de sesión con contraseña después de 5 intentos fallidos de autenticación de API. Esto ocurre comúnmente durante la configuración inicial cuando la contraseña está mal configurada. El bloqueo persiste en la base de datos a través de reinicios del servicio.

Síntomas: error PasswordLoginLocked del servidor MCP, y la interfaz web de Huly muestra "Password login is locked due to too many failed attempts. Please use an OTP login method to unlock your account." (OTP no funcionará sin SMTP configurado).

Solución — restablece el contador de bloqueo en CockroachDB:

# Find your account UUID and check lock status
docker exec -e PGPASSWORD=<your_cockroach_password> <cockroach_container> \
  cockroach sql --host=localhost --user=<db_user> --database=defaultdb --insecure \
  -e "SELECT uuid, failed_login_attempts FROM global_account.account;"

# Reset the counter
docker exec -e PGPASSWORD=<your_cockroach_password> <cockroach_container> \
  cockroach sql --host=localhost --user=<db_user> --database=defaultdb --insecure \
  -e "UPDATE global_account.account SET failed_login_attempts = 0 WHERE uuid = '<your_account_uuid>';"

Las credenciales de CockroachDB se pueden encontrar en tu compose.yml de Huly o mediante docker exec <cockroach_container> env | grep COCKROACH.

Notas específicas de Windows

• Scripts de envoltura Bash (que obtienen archivos .env) pueden no funcionar de manera confiable cuando los lanzan clientes MCP en Windows. Prefiere establecer variables de entorno directamente en el JSON de configuración de MCP.
• Extracciones de Docker sobre SSH pueden fallar en Windows debido a problemas del administrador de credenciales. Extrae imágenes desde el escritorio del servidor si es necesario.