Hyperterse

¿Qué es Hyperterse?

Hyperterse es un framework open source para crear servidores de herramientas MCP (Model Context Protocol) desde configuración declarativa. En lugar de exponer muchos endpoints individuales de herramientas MCP, compila tus definiciones de herramientas en un servidor MCP compatible con estándares que los agentes usan a través de una interfaz consistente.

El propósito principal del framework es permitirte “definir herramientas una sola vez” (incluyendo conexiones a bases de datos y reglas de autenticación) y que Hyperterse maneje las preocupaciones de tiempo de ejecución —como la aplicación de auth, caché de resultados y observabilidad— sin requerir que escribas y mantengas código de pegamento para cada endpoint de herramienta.

Características clave

• Definiciones declarativas de herramientas desde directorios y archivos de declaración: Cada directorio bajo app/tools/ se convierte automáticamente en una herramienta, por lo que no escribes código de registro para cada herramienta.
• Interfaz MCP de dos herramientas (search + execute): Los agentes interactúan con un servidor que expone exactamente dos herramientas MCP —search y execute— mientras Hyperterse descubre y enruta dinámicamente a la implementación subyacente correcta.
• Autenticación integrada vía plugin api_key: Asocia autenticación a herramientas con el plugin api_key integrado (o implementa el tuyo), con auth aplicada automáticamente antes de cada llamada execute.
• Caché con TTL global o por herramienta: Activa caché de resultados para que llamadas execute idénticas devuelvan resultados en caché en lugar de consultar la base de datos; las reglas de caché se pueden configurar globalmente o por herramienta.
• Soporte multi-base de datos con pooling y ciclo de vida gestionados: Conecta PostgreSQL, MySQL, MongoDB y Redis usando adaptadores; Hyperterse gestiona el pooling de conexiones, chequeos de salud y cierre graceful.
• Observabilidad con OpenTelemetry: Hyperterse incluye trazado OpenTelemetry, métricas y logging estructurado para depurar llamadas search y execute de extremo a extremo.
• Scripts TypeScript para handlers y transformaciones: Cuando los archivos de declaración no bastan, agrega handlers/transformaciones como scripts que se ejecutan en un runtime sandboxed con fetch y console.
• Compila y despliega como un solo artefacto: Hyperterse compila archivos de declaración y scripts en un artefacto único que se puede servir en Docker, Kubernetes, bare metal o cualquier entorno cloud.

Cómo usar Hyperterse

1. Instala Hyperterse usando uno de los comandos proporcionados (cURL, NPM, Bun o Homebrew).
2. Crea tus definiciones de herramientas y adaptadores:
   • Coloca adaptadores de base de datos bajo app/adapters/.
   • Coloca declaraciones de herramientas bajo app/tools/, donde cada herramienta se representa por el nombre de su directorio e incluye un archivo de declaración con una sentencia SQL, entradas tipadas y reglas opcionales de auth y caché.
3. (Opcional) Agrega handlers/transformaciones TypeScript cuando necesites lógica más allá de lo que soportan los archivos de declaración.
4. Compila tu artefacto de servidor para que tus herramientas, scripts y configuración queden empaquetados juntos.
5. Sirve el servidor MCP compilado en tu entorno objetivo; los agentes usan entonces search para encontrar herramientas y execute para ejecutar la herramienta seleccionada con entradas estructuradas.

Casos de uso

• Herramientas de investigación o análisis basadas en base de datos: Define muchas herramientas basadas en SQL en app/tools/ y deja que un agente use search para encontrar la herramienta de consulta correcta y execute para ejecutarla con entradas tipadas.
• Ejecución de herramientas multi-tenant o con control de acceso: Asocia reglas de autenticación por clave API a herramientas específicas para que auth se ejecute automáticamente antes de cada llamada execute.
• Flujos de consulta sensibles a costo o latencia: Activa caché global o por herramienta con TTL para que llamadas execute repetidas devuelvan resultados en caché en lugar de reconsultar la base de datos.
• Equipos que estandarizan comportamiento de servidores MCP: Usa la auth, caché y trazado OpenTelemetry integrados de Hyperterse para mantener servidores de herramientas consistentes sin mantener boilerplate separado para cada endpoint de herramienta.
• Despliegues en producción en tipos de infraestructura variados: Compila a un solo artefacto y despliégalo en Docker, Kubernetes, bare metal o entornos cloud sin cambiar el enfoque de definición de herramientas.

Preguntas frecuentes

• ¿Para qué está diseñado Hyperterse? Hyperterse está diseñado para crear servidores de herramientas MCP a partir de archivos de declaración, compilándolos y sirviéndolos con soporte integrado para auth, caché y observabilidad.

• ¿Es Hyperterse gratuito? Sí. Es gratuito y open source bajo la licencia Apache 2.0, y se puede autoalojar.

• ¿Cómo se mapean los archivos de declaración a herramientas? Las herramientas se definen en app/tools/; cada directorio de herramienta corresponde a un nombre de herramienta, y el archivo de declaración del directorio especifica una instrucción SQL, entradas tipadas y reglas opcionales de auth/caché.

• ¿Qué bases de datos son compatibles? Hyperterse soporta PostgreSQL, MySQL, MongoDB y Redis de forma nativa, mediante adaptadores dedicados.

• ¿Qué interfaz MCP expone Hyperterse a los agentes? Hyperterse expone exactamente dos herramientas MCP: search y execute, independientemente del número de definiciones de herramientas que incluyas.

Alternativas

• Servidores de herramientas MCP personalizados con endpoints explícitos: Crea un servidor MCP que exponga un endpoint de herramienta por capacidad. Esto puede ofrecer control detallado, pero suele requerir escribir y mantener más código de registro, validación, auth, caché y observabilidad.
• Frameworks centrados en enrutamiento/descubrimiento en lugar de compilación: Usa un enfoque donde un agente o enrutador mapea solicitudes a funciones/herramientas backend. Comparado con Hyperterse, aún podrías necesitar implementar validación, auth, caché y trazado de forma consistente.
• Bibliotecas de herramientas solo de base de datos con middleware gestionado por la aplicación: Usa bibliotecas de acceso tipado a bases de datos e implementa middleware para auth, caché y trazado en la capa de aplicación. Esto desplaza responsabilidades fuera de un framework MCP y puede aumentar el esfuerzo de integración por herramienta.
• Motores de flujos de trabajo de propósito general para ejecución de herramientas: Orquestadores que ejecutan tareas basadas en configuraciones. Estas alternativas pueden soportar encadenamiento de herramientas, pero Hyperterse está orientado específicamente al comportamiento de servidores MCP y compilación declarativa de herramientas en una interfaz conforme a estándares.