💻 computer science

HarnessAPI: A Skill-First Framework for Unified Streaming APIs and MCP Tools

HarnessAPI ist ein Python-Framework, das Code-Duplizierung eliminiert, indem es typisierte Skill-Ordner als einzige Quelle der Wahrheit behandelt, um automatisch einheitliche Streaming-HTTP-Endpunkte, interaktive OpenAPI-Dokumentation und Konfigurations-freie MCP-Tools aus einem einzigen Handler und Pydantic-Schemas zu generieren.

Ursprüngliche Autoren: Edwin Jose

Veröffentlicht 2026-05-22

📖 4 Min. Lesezeit☕ Kaffeepausen-Lektüre

CC BY 4.0

Ursprüngliche Autoren: Edwin Jose

Originalarbeit lizenziert unter CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ Dies ist eine KI-generierte Erklärung des untenstehenden Papers. Sie wurde nicht von den Autoren verfasst oder gebilligt. Für technische Genauigkeit konsultieren Sie das Originalpaper. Vollständigen Haftungsausschluss lesen

Stellen Sie sich vor, Sie sind ein Koch, der ein köstliches neues Rezept (eine „Fähigkeit") erfunden hat. In der Welt der KI und Software muss dieses Rezept zwei sehr unterschiedlichen Arten von Kunden serviert werden:

Der Web-Kunde: Er kommt auf die Website Ihres Restaurants, füllt ein Formular aus und erwartet einen schnellen, formatierten Kassenbon (ein HTTP-Endpunkt).
Der Roboter-Kellner: Er ist ein KI-Assistent (wie ein digitaler Butler), der Ihr Rezept direkt vom Regal Ihrer Küche holen muss, um es während des Kochens zu verwenden (ein MCP-Tool).

Das Problem: Der „Doppelteingabe"-Albtraum
Momentan müssen Sie Ihr Rezept doppelt schreiben, wenn Sie beide Kunden bedienen wollen.

Zuerst schreiben Sie es in ein elegantes Hauptbuch für die Website (unter Verwendung eines Regelwerks).
Dann müssen Sie die exakt gleichen Anweisungen in einem anderen Notizbuch für den Roboter-Kellner neu schreiben (unter Verwendung eines völlig anderen Regelwerks).

Der Artikel nennt dies das „Dual-Stack"-Problem. Das Schlimmste ist, dass Sie, wenn Sie eine Zutat in Ihrer Küche ändern (Ihren Code aktualisieren), daran denken müssen, beide Hauptbücher zu aktualisieren. Wenn Sie das vergessen, könnte die Website sagen „2 Eier hinzufügen", während der Roboter-Kellner denkt „2 Tassen Mehl hinzufügen". Dies führt zu Verwirrung, Fehlern und einer Menge zusätzlicher Bürokratie.

Die Lösung: HarnessAPI
Der Autor, Edwin Jose, hat ein Framework namens HarnessAPI entwickelt, das dieses Problem löst, indem er die Spielregeln ändert. Anstatt mit der „Website" oder dem „Roboter" zu beginnen, beginnen Sie mit der Fähigkeit (dem Rezeptordner).

Stellen Sie sich HarnessAPI als einen universellen Übersetzer und Drucker vor, der in Ihrer Küche steht.

Sie legen Ihr Rezept in einen einzigen Ordner mit einem Satz Anweisungen.
HarnessAPI betrachtet diesen Ordner und druckt automatisch sowohl den „Web-Kassenbon" als auch das „Roboter-Anweisungsbogen" für Sie aus.
Da beide Bögen aus demselben Hauptordner stammen, können sie niemals widersprüchlich sein. Wenn Sie das Rezept ändern, werden beide Bögen sofort aktualisiert.

Wie es funktioniert (Die Zaubertricks)

Ein Ordner, zwei Türen: Das Framework behandelt einen Ordner, der Ihren Code enthält, als „Quelle der Wahrheit". Es baut automatisch eine Tür für das Web und eine Tür für den Roboter, sodass Sie diese niemals manuell bauen müssen.
Der wandelbare Kellner: Stellen Sie sich einen Kellner vor, der sein Outfit je nach Fragesteller ändern kann. Wenn ein Webbrowser Daten anfordert, serviert der Kellner sie als standardmäßige JSON-Datei. Wenn ein KI-Agent einen Datenstrom anfordert (wie ein Video, das in Abschnitten abgespielt wird), schaltet der Kellner sofort in den Streaming-Modus um. Der Kellner (Ihr Code) weiß nicht einmal, dass er wechselt; das Framework übernimmt den Wechsel automatisch.
Der „Fake"-Roboter: Damit der Roboter-Kellner Ihren Code versteht, erstellt das Framework im laufenden Betrieb einen speziellen „Wrapper" (einen Übersetzer). Es ist so, als würde das Framework schnell eine Notiz schreiben, die besagt: „Hey Roboter, hier ist genau, wie diese Funktion aufgerufen wird", damit der Roboter nicht durch komplexe Code-Strukturen verwirrt wird.

Warum es wichtig ist (Die Ergebnisse)
Der Autor testete dies, indem er sechs verschiedene „Fähigkeiten" (wie das Zusammenfassen von Text oder das Übersetzen von Sprachen) auf zwei Arten entwickelte:

Der alte Weg: Manuelles Schreiben des Codes für die Website und den Roboter separat.
Der HarnessAPI-Weg: Einfach das einmalige Schreiben der Fähigkeit.

Die Erkenntnisse:

74 % weniger Arbeit: Die HarnessAPI-Methode erforderte 74 % weniger „Boilerplate"-Code (die langweilige, repetitive Setup-Arbeit).
Keine Abweichung: Auf die alte Weise konnten die beiden Versionen auseinanderdriften und inkonsistent werden. Auf die neue Weise sind sie mathematisch garantiert identisch, da sie aus derselben Quelle stammen.
Ein Prozess: Anstatt zwei separate Server zu betreiben (einen für das Web, einen für den Roboter), führt HarnessAPI alles in einem einzigen Prozess aus, was es leichter und einfacher zu verwalten macht.

Der Haken (Einschränkungen)
Der Artikel ist ehrlich bezüglich einiger Sicherheitsregeln:

Die „Hot-Swap"-Funktion: Es gibt eine Funktion, die es ermöglicht, den Code zu aktualisieren, während der Server läuft (großartig zum Testen), aber der Autor warnt davor, dass dies wie das Geben einer Fernbedienung für Ihre Küche an jemanden ist. Es ist nur sicher auf Ihrem eigenen Computer (localhost) zu verwenden und sollte niemals für öffentliche Websites aktiviert werden, da Hacker sonst Ihren Server übernehmen könnten.
Komplexität: Es funktioniert hervorragend für Standardrezepte, aber wenn Ihr Rezept extrem komplexe, verschachtelte Strukturen beinhaltet, könnte der automatische Übersetzer ein wenig Hilfe benötigen.

Zusammenfassung
HarnessAPI ist ein Werkzeug, das Entwickler davon abhält, Doppelarbeit zu leisten. Es sagt: „Schreiben Sie Ihren Code einmal, und wir kümmern uns um den Rest." Es stellt sicher, dass Ihre KI-Tools und Ihre Web-Tools immer perfekt synchronisiert sind, spart Zeit und verhindert die Fehler, die auftreten, wenn Sie versuchen, zwei separate Versionen desselben Dings zu pflegen.

Technische Zusammenfassung: HarnessAPI – Ein Skill-First-Framework für vereinheitlichte Streaming-APIs und MCP-Tools

1. Problemstellung

Die Arbeit identifiziert eine kritische architektonische Reibung bei der Bereitstellung von Large Language Model (LLM)-Tools. Derzeit müssen Entwickler für jede als LLM-Tool vorgesehene Python-Funktion zwei parallele Repräsentationen unterhalten:

HTTP-Endpunkt: Für clientseitige Anwendungen, Web-Dashboards und CI-Pipelines, typischerweise implementiert mit Frameworks wie FastAPI.
MCP-Tool: Für Agent-Laufzeitumgebungen (z. B. Claude Desktop, Cursor) unter Verwendung des Model Context Protocol (MCP), typischerweise implementiert mit Frameworks wie FastMCP.

Obwohl diese beiden Schnittstellen dieselbe zugrundeliegende Geschäftslogik teilen, unterscheiden sie sich in ihrer umgebenden Infrastruktur (Routing, Validierung, Serialisierung, Streaming und Schema-Wartung). Dieser „Dual-Stack"-Ansatz zwingt Entwickler dazu, zwei separate Schema-Definitionen zu pflegen (eine für HTTP/Pydantic, eine für MCP). Mit fortschreitender Code-Entwicklung driften diese Definitionen auseinander, was zu veralteten Schemata führt. Die Arbeit zitiert Patil et al. [9], um festzustellen, dass LLMs API-Aufrufe halluzinieren, wenn Typ-Schemata fehlen oder veraltet sind, wodurch diese Drift zu einem Zuverlässigkeitsrisiko wird. Darüber hinaus stellten Mastouri et al. [10] empirisch fest, dass 88,6 % der MCP-Server auf bestehenden REST-Diensten basieren, was bedeutet, dass die überwiegende Mehrheit der Bereitstellungen bereits diese Last der doppelten Wartung trägt.

Bestehende Frameworks betrachten entweder die Route (FastAPI) oder das Tool (FastMCP) als primäre Entität und erfordern einen separaten Registrierungsakt für das andere. Dies zwingt den Entwickler, als Synchronisationsschicht zwischen den beiden zu agieren.

2. Methodik: Die Skill-First-Architektur

HarnessAPI schlägt eine „Skill-First"-Architektur vor, die die Abhängigkeit umkehrt. Anstatt dass der Entwickler eine Route und dann ein Tool (oder umgekehrt) deklariert, wird der Skill-Ordner zur einzigen Quelle der Wahrheit.

Kern-Designprinzipien

Einheitliche Quelle der Wahrheit: Ein Skill wird als Verzeichnis definiert, das eine typisierte handler.py und Pydantic-models.py enthält.
Abgeleitete Repräsentationen: Das Framework leitet sowohl den HTTP-Endpunkt als auch die MCP-Tool-Registrierung automatisch aus dieser einzigen Verzeichnisstruktur ab.
Strukturelle Invariante: Da beide Transports bei Laufzeit auf dasselbe Pydantic-Modell aufgelöst werden, wird die Schema-Konsistenz durch Konstruktion erzwungen und nicht durch Disziplin des Entwicklers.

Wichtige technische Mechanismen

Skill-Erkennung und Isolierung:
- Das Framework scannt ein Skills-Verzeichnis und identifiziert Unterordner, die handler.py und models.py enthalten.
- Um Namensraumkollisionen zu verhindern (z. B. mehrere Skills, die eine Klasse namens Input definieren), erstellt HarnessAPI einen synthetischen Paket-Namensraum für jeden Skill mittels types.ModuleType. Dies ermöglicht es mehreren Skills, nebeneinander zu existieren, ohne sich gegenseitig ihre Klassen zu verdecken.
Dynamische Inhaltsverhandlung im Dual-Modus:
- Das Framework unterstützt sowohl Streaming- als auch Nicht-Streaming-Antworten aus einem einzigen Handler.
- Streaming (SSE): Wenn der Client nicht application/json anfordert, öffnet das Framework einen Server-Sent-Events (SSE)-Stream. Es liefert inkrementell Blöcke aus und sendet chunk, result, done oder error-Ereignisse aus.
- Batch (JSON): Wenn der Client Accept: application/json sendet, puffert das Framework die Ausgabe des Handlers und gibt eine einzelne JSON-Antwort zurück.
- Dies ermöglicht es demselben Handler, interaktive Agent-Sitzungen (Streaming) und Batch-Pipelines (JSON) ohne Codeänderungen zu bedienen.
Dynamische MCP-Wrapper-Generierung:
- Eine bedeutende technische Herausforderung, die adressiert wird, ist die Schema-Introspektion von FastMCP, die darauf angewiesen ist, die __annotations__ einer Funktion zu lesen und Typen gegen __globals__ aufzulösen. Naive Closures scheitern, da das Pydantic-Modell nicht im globalen Gültigkeitsbereich der Funktion liegt.
- Lösung: HarnessAPI kompiliert dynamisch eine Wrapper-Funktion mittels exec innerhalb eines Namensraums, der das Pydantic-Modell explizit einschließt. Dies stellt sicher, dass der Typ von der Introspektionsschicht von FastMCP auflösbar ist, was eine korrekte Tool-Registrierung ohne manuelle Schema-Duplizierung ermöglicht.
Lebenszyklus-Management:
- HarnessAPI unterteilt FastAPI und mountet die FastMCP-Anwendung als ASGI-Subanwendung.
- Es implementiert einen geführten Lebensdauer-Kontextmanager, der die Start-/Stopp-Hooks sowohl der Anwendung des Benutzers (z. B. Datenbankverbindungen) als auch des FastMCP-Servers kombiniert und eine Bereitstellung in einem einzigen Prozess ermöglicht.
Hot-Swap-Fähigkeit (nur Entwicklung):
- Ein optionaler Endpunkt ermöglicht das Einreichen von Code-Strings, um Handler-Logik dynamisch zu ersetzen. Dies ist strikt auf Loopback-Adressen (localhost) beschränkt, um die Ausführung von Remote-Code in der Produktion zu verhindern.

3. Wichtige Beiträge

Die Arbeit definiert folgende Beiträge:

Skill-First-Architekturmuster: Ein formales Muster, bei dem das Skill-Verzeichnis die maßgebliche Definition ist, im Gegensatz zu Route-first (FastAPI) und Tool-first (FastMCP) Mustern.
Implementierungsmethoden:
- Dynamische Routengenerierung und Inhaltsverhandlung im Dual-Modus.
- Eine Code-Generierungstechnik, um Pydantic-Annotationen an die Introspektionsschicht von FastMCP weiterzuleiten.
- Eine Strategie zum Zusammenführen der Lebensdauer für den Betrieb in einem einzigen Prozess.
Reduzierung von Boilerplate: Eine empirische Evaluation, die eine signifikante Reduzierung des Framework-bezogenen Codes zeigt.
Open-Source-Veröffentlichung: Die Veröffentlichung von HarnessAPI v0.1.4, verfügbar auf PyPI und GitHub.

4. Evaluierungsergebnisse

Die Autoren bewerteten HarnessAPI gegen eine manuell gepflegte Dual-Stack-Implementierung (separate FastAPI- und FastMCP-Server) unter Verwendung von sechs repräsentativen Skills: Echo, Greet, Summarize, VectorNorm, Classify und Translate.

Reduzierung von Boilerplate: Unter Verwendung von cloc zur Zählung nicht-leerer, nicht-kommentierter Zeilen von Framework-bezogenem Code (ohne Geschäftslogik) benötigte HarnessAPI insgesamt 44 Zeilen über alle sechs Skills hinweg, verglichen mit 170 Zeilen für die manuelle Implementierung. Dies entspricht einer Reduzierung von 74 % bei Boilerplate.
Skalierungsverhalten: Der manuelle Ansatz zeigt ein $O(n)$ -Skalierungsverhalten, bei dem der Framework-Code linear mit der Anzahl der Skills wächst (jeder erfordert neue Dekoratoren und Registrierungen). HarnessAPI zeigt ein $O(1)$ -Skalierungsverhalten bezüglich des Framework-Codes, da der Einstiegspunkt unabhängig von der Anzahl der Skills fest bleibt.
Funktionsäquivalenz: HarnessAPI bietet alle Funktionen von eigenständigem FastAPI und FastMCP out-of-the-box, einschließlich SSE-Streaming, OpenAPI/Swagger UI und pro-Skill-Timeouts, ohne zusätzliche Bibliotheksintegration zu erfordern.
Kompatibilität: Das Framework importierte und registrierte erfolgreich 12 bestehende Skills aus dem Repository agentskills.io ohne Änderungen am Quellcode und demonstriert damit eine reibungslose Bereitstellung für bestehende Skill-Sets.

5. Bedeutung und Behauptungen

Die Arbeit behauptet, dass HarnessAPI die „unangenehme Antwort" der doppelten Wartung bei der Bereitstellung von LLM-Tools löst. Ihre Bedeutung liegt darin, die Schema-Konsistenz von einer Disziplin des Entwicklers (fehleranfällig und zu Drift neigend) in eine strukturelle Invariante zu verwandeln, die durch das Framework erzwungen wird.

Die Autoren betonen, dass die 74%ige Reduzierung von Boilerplate eine Folge dieser Invariante ist, aber das dauerhaftere Ergebnis die Skalierungseigenschaft ist. Da Agent-Ökosysteme reifen und Entwickler Dutzende oder Hunderte von Skills bereitstellen, wird die sich kumulierende Wartungslast der manuellen Dual-Stack-Registrierung unhaltbar. HarnessAPI schlägt vor, dass die Lösung nicht in besseren Werkzeugen zur Pflege zweier Registrierungen liegt, sondern in der Eliminierung der zweiten Registrierung insgesamt.

Die Arbeit bleibt hinsichtlich ihres Umfangs bescheiden:

Sie beansprucht nicht, End-to-End-Latenz- oder Parallelitäts-Benchmarks zu lösen, und verweist auf die bekannten Leistungsmerkmale des zugrundeliegenden FastAPI/Uvicorn-Stacks.
Sie erkennt Einschränkungen an, wie die Verwendung von exec für die MCP-Wrapper-Generierung (eine vorübergehende Workaround-Lösung für den aktuellen Resolver von FastMCP) und das Fehlen einer pro-Tool-Authentifizierung auf der MCP-Ebene.
Sie warnt ausdrücklich davor, den Hot-Swap-Endpunkt in netzwerkzugänglichen Bereitstellungen zu verwenden, und beschränkt ihn auf lokale Entwicklungsschleifen.

Zusammenfassend bietet HarnessAPI eine vereinheitlichte, skill-first-Bereitstellungsschicht, die Schema-Konsistenz gewährleistet, Wartungsaufwand reduziert und sowohl Streaming- als auch Batch-Interaktionen für moderne LLM-Agenten unterstützt.