juankanh/hilvana repository overview

⁠Hilvana — Visual API Orchestrator (edición Docker)

Hilvana es una herramienta visual + CLI + MCP para componer, ejecutar y verificar flujos de peticiones HTTP y consultas SQL encadenadas: importas comandos curl, conectas nodos, extraes datos de las respuestas (JSONPath / columnas SQL) y los reutilizas en los siguientes pasos con {{variables}}.

Este repositorio es solo documentación: todo lo necesario para usar Hilvana al máximo desde la imagen Docker oficial, sin código fuente.

┌─────────────┐   comandos MCP    ┌──────────────────────────────────────┐
│  IA (Claude) ├──────────────────►  contenedor juankanh/hilvana        │
│  claude mcp  ◄──────────────────┤  · Web (canvas en :3001)             │
└─────────────┘  estado/resultados│  · CLI  (flow runner)                │
                                  │  · MCP  (/mcp, 39 tools)             │
       tú miras el canvas ────────►  · SQL  (postgres/mysql/oracle)      │
                                  └──────────────────────────────────────┘

⁠Arranque rápido

docker run -d \
  --add-host=host.docker.internal:host-gateway \
  -p 9998:3001 \
  -p 1025:1025 \
  --name hilvana \
  juankanh/hilvana:6.4.0

• Web: http://localhost:9998⁠ — el canvas visual.
• CLI: docker exec flow node cli/run-flow.js --dir flows — ejecuta baterías de flows.
• Correo de prueba 🆕 4.36: Config → Correo — SMTP en localhost:1025 que recibe los correos de tus servicios y los muestra (buzones @midominiotest.com, sin cuentas reales); desde la 4.37 la IA lo maneja por MCP (mail_*).
• MCP (agentes IA): claude mcp add --transport http hilvana http://localhost:9998/mcp — la IA construye y ejecuta flows en tu canvas, mientras lo ves.

⁠🗂️ Galería: arranca con 21 flows de verdad

¿Prefieres tocar antes que leer? Monta la galería de ejemplos como tu workspace y la app abre con un tour guiado dentro del propio producto — cada ejemplo se ejecuta con un clic:

git clone https://github.com/jks90/hilvana-public.git
docker run -d \
  --add-host=host.docker.internal:host-gateway \
  -p 9998:3001 --name hilvana \
  -v "$(pwd)/hilvana-public/examples/workspace:/app/flows" \
  juankanh/hilvana:latest
# abre http://localhost:9998 → icono «Proyecto» → «00 EMPIEZA AQUÍ.md»

Dentro: aprende/ (variables, asserts, entornos, scripts, SQL, data-driven — un concepto por flow, 5 minutos cada uno), funciones/ (monitor 24x7, webhook desde CI, correo OTP, puente a local), hilvana-por-dentro/ (nuestra propia plataforma probada con nuestra propia herramienta: alta, login, compra de licencia y salud — el funnel real, documentado como flow) paneles/ (los vistosos para enseñar en una demo) y scripts/ (🆕 5.14: señales de mercado, semáforo del tiempo y verificación de pedidos calculados con scripts JS dentro del flow, gráficos Mermaid incluidos, y dos flows cuyos scripts dibujan botones, páginas y acciones encima de Hilvana). Todos con asserts, verificados con el CLI antes de publicarse. Detalle en examples/README.md⁠. (El tour en .md se abre desde la 5.5.0.)

⁠Versiones de la imagen

Las versiones anteriores (5.12 y antes, desde la 4.x) están en la tabla completa del manual⁠.

docker pull juankanh/hilvana:6.4.0

⁠Documentación

⁠Ficheros listos para usar

⁠Lo esencial en 4 recetas

1. Ver la web y crear un flow a mano → abre http://localhost:9998⁠, pulsa Add Request, pega un curl, conecta nodos y Run Flow.

2. Ejecutar una batería por terminal (CI):

docker exec flow node cli/run-flow.js --dir flows --report-root /tmp/resumen
docker cp flow:/tmp/resumen ./resumen   # informe completo (report.md, debug por flow…)

3. Que una IA construya el flow mientras lo miras:

claude mcp add --transport http hilvana http://localhost:9998/mcp
# abre http://localhost:9998 en el navegador y dile a Claude:
#   «crea un flow que haga login en mi API y liste los usuarios con el token»

4. Guardar lo que la IA construyó y ejecutarlo en CI: la tool flow_save deja el .flow.json en el contenedor; docker exec flow node cli/run-flow.js --flow flows/mi-flow.flow.json lo ejecuta igual que la web.

5. Trabajar sobre tu carpeta de flows como un proyecto (4.25): monta -v /tu/carpeta:/app/flows (o -v /tu/carpeta:/data/flows -e FLOW_FLOWS_DIR=/data/flows), abre el panel Proyecto en la web y edita/guarda con Ctrl+S directamente en tus ficheros — versionables en git y ejecutables por el CLI sin pasos intermedios.

⁠Requisitos

• Docker (la imagen es multi-arquitectura estándar node:20-alpine).
• Para el MCP: Claude Code⁠ u otro cliente MCP con transporte Streamable HTTP.

⁠Licencia y planes

Hilvana es software propietario (LICENSE⁠):

• Gratis — uso personal y no comercial por una persona, con todas las funciones, self-hosted en tu máquina.
• De pago — el uso comercial, en equipo o en la nube requiere una licencia de pago; algunas funciones avanzadas se habilitan con una clave de licencia.

Para una licencia comercial, contacta con el autor a través de este repositorio.

⁠Activar una licencia

Hilvana funciona gratis para uso personal. Para uso comercial, en equipo o en la nube necesitas una licencia (ver LICENSE⁠). Una vez la tengas:

1. En la app: Config ▸ Licencia → pega tu clave → Activar. Se guarda en flows/.license y se verifica al momento.
2. O por entorno: arranca el contenedor con -e FLOW_LICENSE="<tu-clave>".

La verificación es offline (tu clave nunca sale de tu máquina): el servidor comprueba la firma RS256 con una clave pública empaquetada. Para conseguir una licencia comercial, contacta con el autor a través de este repositorio.