Riepilogo Tecnico: HarnessAPI – Un Framework "Skill-First" per API di Streaming Unificate e Strumenti MCP

1. Enunciato del Problema

Il documento identifica un attrito architetturale critico nella distribuzione degli strumenti per i Modelli Linguistici su Grande Scala (LLM). Attualmente, gli sviluppatori devono mantenere due rappresentazioni parallele per ogni funzione Python destinata a diventare uno strumento LLM:

1. Endpoint HTTP: Per client rivolti all'utente, dashboard web e pipeline CI, tipicamente implementati utilizzando framework come FastAPI.
2. Strumento MCP: Per i runtime degli agenti (ad esempio, Claude Desktop, Cursor) che utilizzano il Protocollo di Contesto del Modello (MCP), tipicamente implementati utilizzando framework come FastMCP.

Sebbene queste due interfacce condividano la stessa logica di business sottostante, divergono nella loro infrastruttura circostante (instradamento, validazione, serializzazione, streaming e manutenzione degli schemi). Questo approccio "dual-stack" costringe gli sviluppatori a mantenere due definizioni di schema separate (una per HTTP/Pydantic, una per MCP). Man mano che il codice evolve, queste definizioni si allontanano l'una dall'altra, portando a un invecchiamento degli schemi. Il documento cita Patil et al. [9] per notare che gli LLM generano allucinazioni nelle chiamate API quando gli schemi di tipo sono assenti o obsoleti, rendendo questa divergenza un rischio per l'affidabilità. Inoltre, Mastouri et al. [10] hanno riscontrato empiricamente che l'88,6% dei server MCP è supportato da servizi REST esistenti, il che significa che la stragrande maggioranza delle distribuzioni già sostiene questo onere di manutenzione duale.

I framework esistenti trattano o l'endpoint (FastAPI) o lo strumento (FastMCP) come l'entità primaria, richiedendo un atto di registrazione separato per l'altro. Questo costringe lo sviluppatore ad agire come strato di sincronizzazione tra i due.

2. Metodologia: L'Architettura Skill-First

HarnessAPI propone un'architettura "Skill-First" che inverte la dipendenza. Invece che lo sviluppatore dichiari un endpoint e poi uno strumento (o viceversa), la cartella skill diventa l'unica fonte di verità.

Principi di Progettazione Fondamentali

• Unica Fonte di Verità: Una skill è definita come una directory contenente un handler.py tipizzato e un models.py Pydantic.
• Rappresentazioni Derivate: Il framework deriva automaticamente sia l'endpoint HTTP che la registrazione dello strumento MCP da questa singola struttura di directory.
• Invariante Strutturale: Poiché entrambi i trasporti risolvono allo stesso modello Pydantic a runtime, la coerenza dello schema è imposta per costruzione piuttosto che dalla disciplina dello sviluppatore.

Meccanismi Tecnici Chiave

1. Scoperta e Isolamento delle Skill:

   • Il framework scansiona una directory delle skill, identificando le sottocartelle contenenti handler.py e models.py.
   • Per prevenire collisioni di namespace (ad esempio, più skill che definiscono una classe chiamata Input), HarnessAPI crea un namespace di pacchetto sintetico per ogni skill utilizzando types.ModuleType. Ciò consente a più skill di coesistere senza oscurare le classi delle altre.

2. Negoziazione del Contenuto in Modalità Duale:

   • Il framework supporta sia risposte in streaming che non in streaming da un singolo handler.
   • Streaming (SSE): Se il client non richiede application/json, il framework apre un flusso di Server-Sent Events (SSE). Restituisce i frammenti in modo incrementale, emettendo eventi chunk, result, done o error.
   • Batch (JSON): Se il client invia Accept: application/json, il framework memorizza nel buffer l'output dell'handler e restituisce una singola risposta JSON.
   • Ciò consente allo stesso handler di servire sessioni interattive di agenti (streaming) e pipeline batch (JSON) senza modifiche al codice.

3. Generazione Dinamica del Wrapper MCP:

   • Una sfida tecnica significativa affrontata è l'introspezione degli schemi di FastMCP, che si basa sulla lettura delle __annotations__ di una funzione e sulla risoluzione dei tipi rispetto a __globals__. Le chiusure naive falliscono perché il modello Pydantic non è nello scope globale della funzione.
   • Soluzione: HarnessAPI compila dinamicamente una funzione wrapper utilizzando exec all'interno di un namespace che include esplicitamente il modello Pydantic. Ciò garantisce che il tipo sia risolvibile dal livello di ispezione di FastMCP, consentendo una corretta registrazione degli strumenti senza duplicazione manuale degli schemi.

4. Gestione del Ciclo di Vita:

   • HarnessAPI sottoclasse FastAPI e monta l'applicazione FastMCP come un'applicazione ASGI secondaria.
   • Implementa un gestore del contesto di vita unito che compone i hook di avvio/arresto sia dell'applicazione dell'utente (ad esempio, connessioni al database) che del server FastMCP, abilitando la distribuzione in un singolo processo.

5. Capacità di Hot-Swap (Solo Sviluppo):

   • Un endpoint opzionale consente di inviare stringhe di codice per sostituire dinamicamente la logica dell'handler. Questo è rigorosamente limitato agli indirizzi loopback (localhost) per prevenire l'esecuzione di codice remoto in produzione.

3. Contributi Chiave

Il documento definisce i seguenti contributi:

1. Pattern Architetturale Skill-First: Un pattern formale in cui la directory della skill è la definizione autorevole, in contrasto con i pattern route-first (FastAPI) e tool-first (FastMCP).
2. Meccanismi di Implementazione:
   • Generazione dinamica degli endpoint e negoziazione del contenuto in modalità duale.
   • Una tecnica di generazione del codice per propagare le annotazioni Pydantic al livello di ispezione di FastMCP.
   • Una strategia di fusione del ciclo di vita per l'operazione in singolo processo.
3. Riduzione del Codice Boilerplate: Una valutazione empirica che mostra una significativa riduzione del codice rivolto al framework.
4. Rilascio Open Source: Il rilascio di HarnessAPI v0.1.4, disponibile su PyPI e GitHub.

4. Risultati della Valutazione

Gli autori hanno valutato HarnessAPI contro un'implementazione dual-stack mantenuta manualmente (server FastAPI e FastMCP separati) utilizzando sei skill rappresentative: Echo, Greet, Summarize, VectorNorm, Classify e Translate.

• Riduzione del Codice Boilerplate: Utilizzando cloc per contare le righe non vuote e non commentate di codice rivolto al framework (esclusa la logica di business), HarnessAPI ha richiesto 44 righe totali per tutte e sei le skill, rispetto alle 170 righe per l'implementazione manuale. Ciò rappresenta una riduzione del 74% del codice boilerplate.
• Comportamento di Scalabilità: L'approccio manuale mostra una scalabilità $O(n)$, dove il codice del framework cresce linearmente con il numero di skill (ognuna richiede nuovi decoratori e registrazioni). HarnessAPI mostra una scalabilità $O(1)$ per quanto riguarda il codice del framework, poiché il punto di ingresso rimane fisso indipendentemente dal numero di skill.
• Parità di Funzionalità: HarnessAPI fornisce tutte le funzionalità di FastAPI e FastMCP standalone fuori dalla scatola, inclusi lo streaming SSE, l'interfaccia OpenAPI/Swagger UI e i timeout per skill, senza richiedere integrazioni di librerie aggiuntive.
• Compatibilità: Il framework ha importato e registrato con successo 12 skill esistenti dal repository agentskills.io senza modifiche al codice sorgente, dimostrando una distribuzione senza attriti per set di skill esistenti.

5. Significato e Affermazioni

Il documento afferma che HarnessAPI risolve la "risposta scomoda" della manutenzione duale nella distribuzione degli strumenti LLM. Il suo significato risiede nel trasformare la coerenza degli schemi da una disciplina dello sviluppatore (soggetta a errori e divergenze) a un invariante strutturale imposto dal framework.

Gli autori sottolineano che la riduzione del 74% del codice boilerplate è una conseguenza di questo invariante, ma il risultato più duraturo è la proprietà di scalabilità. Man mano che gli ecosistemi di agenti maturano e gli sviluppatori distribuiscono dozzine o centinaia di skill, l'onere di manutenzione cumulativo della registrazione dual-stack manuale diventa insostenibile. HarnessAPI suggerisce che la soluzione non è un migliore tooling per mantenere due registrazioni, ma l'eliminazione della seconda registrazione interamente.

Il documento rimane modesto riguardo al suo ambito:

• Non afferma di risolvere i benchmark di latenza o concorrenza end-to-end, rimandando alle caratteristiche di prestazioni note dello stack sottostante FastAPI/Uvicorn.
• Riconosce le limitazioni, come l'uso di exec per la generazione del wrapper MCP (una soluzione temporanea per il risolutore attuale di FastMCP) e la mancanza di autenticazione per strumento nel livello MCP.
• Avverte esplicitamente contro l'uso dell'endpoint hot-swap in distribuzioni accessibili dalla rete, limitandolo ai cicli di sviluppo locali.

In conclusione, HarnessAPI fornisce un livello di distribuzione unificato e skill-first che garantisce la coerenza degli schemi, riduce l'overhead di manutenzione e supporta sia le interazioni in streaming che quelle batch per gli agenti LLM moderni.