huly-mcp
Servidor MCP para Huly que permite leer y escribir documentos e incidencias desde Claude Desktop o Code, actuando como capa fina sobre el SDK oficial sin pasos de compilación.
Ficha actualizada 27 sept 2026, 15:08 · upstream 27 sept 2026, 14:37 · release sin release detectada
Qué es huly-mcp
Descripción editorial construida a partir del repositorio, su documentación y sus señales de mantenimiento.
Este proyecto implementa un servidor Model Context Protocol (MCP) diseñado específicamente para integrarse con la plataforma Huly. Funciona como una capa delgada que utiliza el SDK oficial @hcengineering/api-client disponible en npm, permitiendo a los usuarios interactuar con documentos y tickets desde entornos de desarrollo como Claude Desktop o Claude Code. Es compatible tanto con instancias auto-alojadas como con Huly Cloud, aunque la verificación exhaustiva se ha realizado principalmente sobre versiones self-hosted.
La arquitectura evita pasos de compilación complejos, utilizando CommonJS puro sin TypeScript ni bundlers, lo que facilita su instalación directa mediante npm. El servidor expone herramientas para gestión completa de documentos (CRUD) y seguimiento de incidencias (issues), incluyendo la capacidad crítica de escribir contenido real en lugar de solo metadatos. Esto se logra mediante una implementación personalizada del cliente colaborativo para manejar blobs de contenido.
La configuración es estrictamente basada en variables de entorno, sin necesidad de archivos de configuración externos complejos. Soporta autenticación mediante tokens o credenciales (email/password), aunque recomienda tokens para evitar bloqueos por fallos repetidos. Es importante notar que el servidor actúa con los permisos completos de la cuenta de Huly asociada y no añade capas de autorización propias.
- Gestión colaborativa de documentación técnica dentro del flujo de trabajo de Claude.
- Búsqueda y recuperación de contenido en documentos almacenados en Huly mediante consultas MCP.
- Creación y edición de tickets de incidencias (issues) directamente desde el entorno de desarrollo.
- Integración de datos de Huly en flujos de automatización impulsados por IA.
- Lectura de comentarios y descripción de issues para análisis contextual.
- Escritura real de contenido colaborativo mediante implementación personalizada del cliente, evitando errores comunes de APIs genéricas.
- Cero pasos de compilación: código plano en CommonJS sin TypeScript ni bundlers.
- Compatibilidad directa con el SDK oficial @hcengineering/api-client sin necesidad de tokens de GitHub para instalación.
- Soporte explícito para WebSocket y gestión de actualizaciones de contenido existentes (blobs YDoc).
- Pruebas end-to-end completas contra instancias auto-alojadas verificando integridad de JSON-RPC.
- Herramienta de diagnóstico integrada (`npm run doctor`) para validar conexión antes del uso.
- Requiere Node.js 20 o superior; no soporta versiones anteriores ni entornos sin Node.
- No incluye soporte nativo para Docker, Compose ni contenedores predefinidos.
- La actualización de dependencias (especialmente api-client) debe hacerse manualmente tras cambios en Huly.
- Los tokens de autenticación caducan y requieren renovación manual del servidor.
- El contenido actualizado reemplaza el cuerpo completo, requiriendo lectura previa para operaciones de concatenación.
Perfil de infraestructura
Estimación inicial derivada del repositorio y de los servicios detectados.
Despliegue detectado
Qué señales reales de instalación hemos encontrado.
Instalar globalmente con `npm install -g @lazco-studio/huly-mcp` o usar localmente. Configurar variables de entorno: HULY_URL (base URL), HULY_WORKSPACE (slug de la URL, no el nombre), y autenticación (HULY_TOKEN recomendado). Usar paths absolutos para Node si nvm/fnm está en uso. Ejecutar `npm run doctor` antes de conectar para validar credenciales y conexión WebSocket. Si usas reverse proxy, asegurar que se reenvían headers Upgrade/Connection.
Stack y dependencias
Componentes inferidos a partir de manifests, configuración y documentación.
Puede sustituir a
Relaciones detectadas por el análisis del repositorio y su categoría.
Experiencia real de la comunidad
Ayuda a contrastar la estimación automática con instalaciones reales.
Todavía no hay datos comunitarios para este proyecto.