Resumen Técnico: HarnessAPI – Un Marco de Trabajo Primero-Habilidad para APIs de Streaming Unificadas y Herramientas MCP

1. Declaración del Problema

El documento identifica una fricción arquitectónica crítica en el despliegue de herramientas de Modelos de Lenguaje Grande (LLM). Actualmente, los desarrolladores deben mantener dos representaciones paralelas para cada función de Python destinada a ser una herramienta LLM:

1. Punto Final HTTP: Para clientes orientados al humano, paneles web y pipelines de CI, típicamente implementados usando marcos de trabajo como FastAPI.
2. Herramienta MCP: Para entornos de ejecución de agentes (por ejemplo, Claude Desktop, Cursor) que utilizan el Protocolo de Contexto de Modelo (MCP), típicamente implementados usando marcos de trabajo como FastMCP.

Aunque estas dos interfaces comparten la misma lógica de negocio subyacente, divergen en su maquinaria circundante (enrutamiento, validación, serialización, streaming y mantenimiento de esquemas). Este enfoque de "doble pila" obliga a los desarrolladores a mantener dos definiciones de esquema separadas (una para HTTP/Pydantic y otra para MCP). A medida que el código evoluciona, estas definiciones se separan, lo que conduce a la obsolescencia del esquema. El documento cita a Patil et al. [9] para señalar que los LLM alucinan llamadas a la API cuando los esquemas de tipos están ausentes o son obsoletos, convirtiendo esta divergencia en un riesgo de fiabilidad. Además, Mastouri et al. [10] encontraron empíricamente que el 88.6% de los servidores MCP están respaldados por servicios REST existentes, lo que significa que la gran mayoría de los despliegues ya soportan esta carga de mantenimiento dual.

Los marcos de trabajo existentes tratan ya sea la ruta (FastAPI) o la herramienta (FastMCP) como la entidad principal, requiriendo un acto de registro separado para la otra. Esto obliga al desarrollador a actuar como la capa de sincronización entre ambas.

2. Metodología: La Arquitectura Primero-Habilidad

HarnessAPI propone una arquitectura "Primero-Habilidad" que invierte la dependencia. En lugar de que el desarrollador declare una ruta y luego una herramienta (o viceversa), la carpeta de habilidad se convierte en la única fuente de verdad.

Principios de Diseño Central

• Única Fuente de Verdad: Una habilidad se define como un directorio que contiene un handler.py tipado y un models.py de Pydantic.
• Representaciones Derivadas: El marco de trabajo deriva automáticamente tanto el punto final HTTP como el registro de la herramienta MCP a partir de esta única estructura de directorio.
• Invariante Estructural: Dado que ambos transportes se resuelven al mismo modelo Pydantic en tiempo de ejecución, la consistencia del esquema se hace cumplir por construcción en lugar de por la disciplina del desarrollador.

Mecanismos Técnicos Clave

1. Descubrimiento y Aislamiento de Habilidades:

   • El marco de trabajo escanea un directorio de habilidades, identificando subcarpetas que contienen handler.py y models.py.
   • Para evitar colisiones de espacios de nombres (por ejemplo, múltiples habilidades definiendo una clase llamada Input), HarnessAPI crea un espacio de nombres de paquete sintético para cada habilidad utilizando types.ModuleType. Esto permite que múltiples habilidades coexistan sin ocultar las clases de las demás.

2. Negociación de Contenido en Modo Dual:

   • El marco de trabajo admite respuestas de streaming y no streaming desde un único manejador.
   • Streaming (SSE): Si el cliente no solicita application/json, el marco de trabajo abre un flujo de Eventos Enviados por el Servidor (SSE). Genera fragmentos incrementalmente, emitiendo eventos chunk, result, done o error.
   • Lote (JSON): Si el cliente envía Accept: application/json, el marco de trabajo almacena en búfer la salida del manejador y devuelve una única respuesta JSON.
   • Esto permite que el mismo manejador sirva sesiones interactivas de agentes (streaming) y pipelines por lotes (JSON) sin cambios en el código.

3. Generación Dinámica de Envoltorios MCP:

   • Un desafío técnico significativo abordado es la introspección de esquemas de FastMCP, que depende de leer las __annotations__ de una función y resolver tipos contra __globals__. Los cierres ingenuos fallan porque el modelo Pydantic no está en el ámbito global de la función.
   • Solución: HarnessAPI compila dinámicamente una función de envoltorio utilizando exec dentro de un espacio de nombres que incluye explícitamente el modelo Pydantic. Esto asegura que el tipo sea resoluble por la capa de inspección de FastMCP, permitiendo el registro correcto de la herramienta sin duplicación manual del esquema.

4. Gestión del Ciclo de Vida:

   • HarnessAPI subclase FastAPI y monta la aplicación FastMCP como una subaplicación ASGI.
   • Implementa un gestor de contexto de ciclo de vida fusionado que compone los ganchos de inicio/apagado tanto de la aplicación del usuario (por ejemplo, conexiones a bases de datos) como del servidor FastMCP, habilitando el despliegue en un solo proceso.

5. Capacidad de Intercambio en Caliente (Solo Desarrollo):

   • Un punto final opcional permite enviar cadenas de código para reemplazar dinámicamente la lógica del manejador. Esto está estrictamente restringido a direcciones de bucle local (localhost) para prevenir la ejecución remota de código en producción.

3. Contribuciones Clave

El documento define las siguientes contribuciones:

1. Patrón de Arquitectura Primero-Habilidad: Un patrón formal donde el directorio de la habilidad es la definición autorizada, en contraste con los patrones primero-ruta (FastAPI) y primero-herramienta (FastMCP).
2. Mecanismos de Implementación:
   • Generación dinámica de rutas y negociación de contenido en modo dual.
   • Una técnica de generación de código para propagar las anotaciones de Pydantic a la capa de inspección de FastMCP.
   • Una estrategia de fusión de ciclo de vida para operación en un solo proceso.
3. Reducción de Código Boilerplate: Una evaluación empírica que muestra una reducción significativa en el código orientado al marco de trabajo.
4. Lanzamiento de Código Abierto: El lanzamiento de HarnessAPI v0.1.4, disponible en PyPI y GitHub.

4. Resultados de la Evaluación

Los autores evaluaron HarnessAPI frente a una implementación de doble pila mantenida manualmente (servidores FastAPI y FastMCP separados) utilizando seis habilidades representativas: Eco, Saludar, Resumir, NormaVectorial, Clasificar y Traducir.

• Reducción de Código Boilerplate: Utilizando cloc para contar líneas de código orientado al marco de trabajo no vacías y sin comentarios (excluyendo la lógica de negocio), HarnessAPI requirió un total de 44 líneas para las seis habilidades, en comparación con 170 líneas para la implementación manual. Esto representa una reducción del 74% en el código boilerplate.
• Comportamiento de Escalado: El enfoque manual exhibe un escalado $O(n)$, donde el código del marco de trabajo crece linealmente con el número de habilidades (cada una requiere nuevos decoradores y registros). HarnessAPI exhibe un escalado $O(1)$ en cuanto al código del marco de trabajo, ya que el punto de entrada permanece fijo independientemente del número de habilidades.
• Paridad de Funcionalidades: HarnessAPI proporciona todas las características de FastAPI y FastMCP independientes desde el principio, incluido el streaming SSE, OpenAPI/Swagger UI y tiempos de espera por habilidad, sin requerir integración adicional de bibliotecas.
• Compatibilidad: El marco de trabajo importó y registró con éxito 12 habilidades existentes del repositorio agentskills.io sin modificaciones en el código fuente, demostrando un despliegue sin fricción para conjuntos de habilidades existentes.

5. Significado y Afirmaciones

El documento afirma que HarnessAPI resuelve la "respuesta incómoda" del mantenimiento dual en el despliegue de herramientas LLM. Su importancia radica en transformar la consistencia del esquema de una disciplina del desarrollador (propensa a errores y divergencias) a un invariante estructural hecho cumplir por el marco de trabajo.

Los autores enfatizan que la reducción del 74% en el código boilerplate es una consecuencia de este invariante, pero el resultado más duradero es la propiedad de escalado. A medida que los ecosistemas de agentes maduran y los desarrolladores despliegan docenas o cientos de habilidades, la carga de mantenimiento acumulativa del registro manual de doble pila se vuelve insostenible. HarnessAPI sugiere que la solución no es mejores herramientas para mantener dos registros, sino la eliminación del segundo registro por completo.

El documento se mantiene modesto respecto a su alcance:

• No afirma resolver métricas de latencia o concurrencia de extremo a extremo, remitiendo a las características de rendimiento conocidas de la pila subyacente FastAPI/Uvicorn.
• Reconoce limitaciones, como el uso de exec para la generación de envoltorios MCP (una solución temporal para el resolvedor actual de FastMCP) y la falta de autenticación por herramienta en la capa MCP.
• Advierte explícitamente contra el uso del punto final de intercambio en caliente en despliegues accesibles por red, restringiéndolo a bucles de desarrollo local.

En conclusión, HarnessAPI proporciona una capa de despliegue unificada y primero-habilidad que garantiza la consistencia del esquema, reduce la sobrecarga de mantenimiento y admite tanto interacciones de streaming como por lotes para agentes LLM modernos.