💻 computer science

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

HarnessAPI is een Python-framework dat code-duplicatie elimineert door getypeerde vaardigheidsmappen als enige bron van waarheid te behandelen om automatisch geünificeerde streaming HTTP-eindpunten, interactieve OpenAPI-documentatie en zero-configuratie MCP-tools te genereren vanuit één handler en Pydantic-schema's.

Oorspronkelijke auteurs: Edwin Jose

Gepubliceerd 2026-05-22

📖 4 min leestijd☕ Koffiepauze-leesvoer

CC BY 4.0

Oorspronkelijke auteurs: Edwin Jose

Oorspronkelijk artikel gelicentieerd onder CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ Dit is een AI-gegenereerde uitleg van het onderstaande artikel. Het is niet geschreven of goedgekeurd door de auteurs. Raadpleeg het oorspronkelijke artikel voor technische nauwkeurigheid. Lees de volledige disclaimer

Stel je voor dat je een chef-kok bent die een heerlijk nieuw recept (een "vaardigheid") heeft bedacht. In de wereld van AI en software moet dit recept worden geserveerd aan twee zeer verschillende soorten klanten:

De Webklant: Deze komt naar de website van je restaurant, vult een formulier in en verwacht een snelle, opgemaakte bon (een HTTP-eindpunt).
De Robotbutler: Dit is een AI-assistent (zoals een digitale butler) die je recept direct van je plank in de keuken moet pakken om het tijdens het koken te gebruiken (een MCP-tool).

Het Probleem: De "Dubbele Invoer"-Nachtmerrie
Op dit moment moet je, als je beide klanten wilt bedienen, je recept twee keer opschrijven.

Eerst schrijf je het op in een luxe grootboek voor de website (met behulp van één set regels).
Vervolgens moet je de exacte instructies herschrijven in een ander notitieboek voor de robotbutler (met behulp van een totaal andere set regels).

Het paper noemt dit het "dual-stack"-probleem. Het ergste is dat als je een ingrediënt in je keuken verandert (je code updatet), je moet onthouden om beide grootboeken bij te werken. Als je dat vergeet, kan de website zeggen "Voeg 2 eieren toe" terwijl de robotbutler denkt "Voeg 2 koppen bloem toe". Dit leidt tot verwarring, fouten en veel extra administratie.

De Oplossing: HarnessAPI
De auteur, Edwin Jose, heeft een framework genaamd HarnessAPI ontwikkeld dat dit probleem oplost door de regels van het spel te veranderen. In plaats van te beginnen met de "website" of de "robot", begin je met de Vaardigheid (de receptenmap).

Zie HarnessAPI als een universele vertaler en printer die in je keuken staat.

Je plaatst je recept in één map met één set instructies.
HarnessAPI kijkt naar die map en print automatisch de "Webbon" en het "Instructieblad voor de Robot" voor je.
Omdat beide bladen uit dezelfde hoofdmap komen, kunnen ze nooit met elkaar in strijd zijn. Als je het recept wijzigt, worden beide bladen direct bijgewerkt.

Hoe het Werkt (De Magische Trucs)

Één Map, Twee Deuren: Het framework behandelt een map met je code als de "Bron van Waarheid". Het bouwt automatisch een deur voor het web en een deur voor de robot, zodat je ze nooit handmatig hoeft te bouwen.
De Vormveranderende Kellner: Stel je een kellner voor die zijn uniform kan aanpassen aan wie er vraagt. Als een webbrowser om data vraagt, serveert de kellner het als een standaard JSON-bestand. Als een AI-agent om een datastream vraagt (zoals een video die in stukjes wordt afgespeeld), schakelt de kellner direct over naar een streamingmodus. De kellner (jouw code) weet niet eens dat ze veranderen; het framework regelt de omschakeling automatisch.
De "Valse" Robot: Om de robotbutler je code te laten begrijpen, creëert het framework direct een speciale "wrapper" (een vertaler). Het is alsof het framework snel een briefje schrijft met de tekst: "Hé Robot, dit is precies hoe je deze functie aanroept", zodat de robot niet in de war raakt door complexe codestructuren.

Waarom het Belangrijk Is (De Resultaten)
De auteur heeft dit getest door zes verschillende "vaardigheden" (zoals tekst samenvatten of talen vertalen) op twee manieren te bouwen:

De Oude Manier: Handmatig de code voor de website en de robot apart schrijven.
De HarnessAPI-Manier: Gewoon de vaardigheid één keer schrijven.

De Bevindingen:

74% Minder Werk: De HarnessAPI-methode vereiste 74% minder "boilerplate"-code (het saaie, repetitieve opzetwerk).
Geen Afdwaling: Op de oude manier konden de twee versies uit elkaar groeien en inconsistent worden. Op de nieuwe manier zijn ze wiskundig gegarandeerd identiek, omdat ze uit dezelfde bron komen.
Één Proces: In plaats van twee aparte servers draaien (één voor het web, één voor de robot), draait HarnessAPI alles in één enkel proces, waardoor het lichter en makkelijker te beheren is.

De Haken en Ogen (Beperkingen)
Het paper is eerlijk over een paar veiligheidsregels:

De "Hot-Swap"-Functie: Er is een functie waarmee je de code kunt updaten terwijl de server draait (geweldig voor testen), maar de auteur waarschuwt dat dit is alsof je iemand een afstandsbediening voor je keuken geeft. Het is alleen veilig om te gebruiken op je eigen computer (localhost) en mag nooit worden ingeschakeld voor publieke websites, anders kunnen hackers je server overnemen.
Complexiteit: Het werkt uitstekend voor standaardrecepten, maar als je recept extreem complexe, geneste structuren bevat, kan de automatische vertaler wat hulp nodig hebben.

Samenvattend
HarnessAPI is een tool die ontwikkelaars voorkomt dubbel werk te doen. Het zegt: "Schrijf je code één keer, en wij regelen de rest." Het zorgt ervoor dat je AI-tools en je webtools altijd perfect synchroon lopen, wat tijd bespaart en fouten voorkomt die ontstaan wanneer je probeert twee aparte versies van hetzelfde ding te onderhouden.

Technische Samenvatting: HarnessAPI – Een Vaardigheidsgerichte Architectuur voor Gecombineerde Streaming-API's en MCP-gereedschappen

1. Probleemstelling

Het artikel identificeert een kritieke architecturale wrijving bij het implementeren van tools voor Large Language Models (LLM). Momenteel moeten ontwikkelaars voor elke Python-functie die als LLM-tool bedoeld is, twee parallelle representaties onderhouden:

HTTP-eindpunt: Voor mensgerichte clients, webdashboards en CI-pipelines, doorgaans geïmplementeerd met frameworks zoals FastAPI.
MCP-tool: Voor agent-runtime-omgevingen (bijv. Claude Desktop, Cursor) die het Model Context Protocol (MCP) gebruiken, doorgaans geïmplementeerd met frameworks zoals FastMCP.

Hoewel deze twee interfaces dezelfde onderliggende bedrijfslogica delen, verschillen ze in hun omringende infrastructuur (routing, validatie, serialisatie, streaming en schema-onderhoud). Deze "dubbele-stack"-aanpak dwingt ontwikkelaars om twee aparte schema-definities te onderhouden (één voor HTTP/Pydantic, één voor MCP). Naarmate de code evolueert, raken deze definities uit elkaar, wat leidt tot verouderde schema's. Het artikel citeert Patil et al. [9] om aan te geven dat LLM's API-aanroepen hallucineren wanneer typeschema's ontbreken of verouderd zijn, waardoor deze afwijking een betrouwbaarheidsrisico vormt. Bovendien hebben Mastouri et al. [10] empirisch vastgesteld dat 88,6% van de MCP-servers wordt ondersteund door bestaande REST-services, wat betekent dat de overgrote meerderheid van de implementaties deze dubbele onderhoudslast al draagt.

Bestaande frameworks behandelen ofwel de route (FastAPI) ofwel het gereedschap (FastMCP) als de primaire entiteit, waarbij een aparte registratiehandeling voor het ander vereist is. Dit dwingt de ontwikkelaar om te fungeren als de synchronisatielaag tussen de twee.

2. Methodologie: De Vaardigheidsgerichte Architectuur

HarnessAPI stelt een "Vaardigheidsgerichte" (Skill-First) architectuur voor die de afhankelijkheid omkeert. In plaats dat de ontwikkelaar eerst een route en vervolgens een tool declareert (of andersom), wordt de vaardigheidsmap de enige bron van waarheid.

Kernontwerpprincipes

Enige Bron van Waarheid: Een vaardigheid wordt gedefinieerd als een map die een getypeerde handler.py en Pydantic models.py bevat.
Afgeleide Representaties: Het framework leidt automatisch zowel het HTTP-eindpunt als de MCP-toolregistratie af uit deze enkele mappenstructuur.
Structurele Invariant: Omdat beide transporten tijdens runtime oplossen naar hetzelfde Pydantic-model, wordt schema-consistentie afgedwongen door constructie in plaats van door discipline van de ontwikkelaar.

Belangrijkste Technische Mechanismen

Vaardigheidsontdekking en Isolatie:
- Het framework scant een vaardigheidsmap en identificeert submappen die handler.py en models.py bevatten.
- Om namespace-botsingen te voorkomen (bijv. meerdere vaardigheden die een klasse met de naam Input definiëren), creëert HarnessAPI een synthetische pakket-namespace voor elke vaardigheid met behulp van types.ModuleType. Dit stelt meerdere vaardigheden in staat om naast elkaar te bestaan zonder elkaars klassen te verduisteren.
Dynamische Inhoudsonderhandeling in Twee Modi:
- Het framework ondersteunt zowel streaming- als niet-streaming-antwoorden vanuit één handler.
- Streaming (SSE): Als de client geen application/json aanvraagt, opent het framework een Server-Sent Events (SSE)-stream. Het levert chunks incrementeel op en zendt chunk, result, done of error-evenementen uit.
- Batch (JSON): Als de client Accept: application/json stuurt, bufferd het framework de output van de handler en retourneert het één enkel JSON-antwoord.
- Hiermee kan dezelfde handler interactieve agent-sessies (streaming) en batch-pipelines (JSON) bedienen zonder code-aanpassingen.
Dynamische Generatie van MCP-omhulsels:
- Een aanzienlijke technische uitdaging die wordt aangepakt, is de schema-introspectie van FastMCP, die vertrouwt op het lezen van __annotations__ van een functie en het oplossen van types tegen __globals__. Naïeve closures falen omdat het Pydantic-model niet in de globale scope van de functie staat.
- Oplossing: HarnessAPI compileert dynamisch een wrapper-functie met behulp van exec binnen een namespace die expliciet het Pydantic-model bevat. Dit zorgt ervoor dat het type oplosbaar is door de inspectielaag van FastMCP, waardoor een correcte toolregistratie mogelijk is zonder handmatige schema-duplicatie.
Levenscyclusbeheer:
- HarnessAPI subclassen FastAPI en mount de FastMCP-toepassing als een ASGI-subtoepassing.
- Het implementeert een samengevoegde levensduur-contextmanager die de start/stop-hooks composeert van zowel de toepassing van de gebruiker (bijv. databaseverbindingen) als de FastMCP-server, waardoor implementatie in één proces mogelijk wordt.
Hot-Swap-mogelijkheid (alleen voor Ontwikkeling):
- Een optioneel eindpunt staat toe om code-strings in te dienen om handler-logica dynamisch te vervangen. Dit is strikt beperkt tot loopback-adressen (localhost) om remote code-executie in productie te voorkomen.

3. Belangrijkste Bijdragen

Het artikel definieert de volgende bijdragen:

Vaardigheidsgerichte Architectuurpatroon: Een formeel patroon waarbij de vaardigheidsmap de autoritaire definitie is, in contrast met route-gerichte (FastAPI) en tool-gerichte (FastMCP) patronen.
Implementatiemechanismen:
- Dynamische route-generatie en inhoudsonderhandeling in twee modi.
- Een code-generatietechniek om Pydantic-annotaties door te geven aan de inspectielaag van FastMCP.
- Een strategie voor het samenvoegen van levensduur voor operatie in één proces.
Vermindering van Boilerplate: Een empirische evaluatie die een aanzienlijke vermindering in framework-gerichte code aantoont.
Open-Source Release: De release van HarnessAPI v0.1.4, beschikbaar op PyPI en GitHub.

4. Evaluatieresultaten

De auteurs hebben HarnessAPI geëvalueerd tegenover een handmatig onderhouden dubbele-stack-implementatie (gescheiden FastAPI- en FastMCP-servers) met behulp van zes representatieve vaardigheden: Echo, Greet, Summarize, VectorNorm, Classify en Translate.

Vermindering van Boilerplate: Met behulp van cloc om het aantal niet-lege, niet-commentaarregels van framework-gerichte code te tellen (exclusief bedrijfslogica), vereiste HarnessAPI in totaal 44 regels voor alle zes vaardigheden, tegenover 170 regels voor de handmatige implementatie. Dit vertegenwoordigt een reductie van 74% in boilerplate.
Schalingsgedrag: De handmatige aanpak vertoont $O(n)$ schaling, waarbij framework-code lineair groeit met het aantal vaardigheden (elk vereist nieuwe decorators en registraties). HarnessAPI vertoont $O(1)$ schaling wat betreft framework-code, aangezien het insteekpunt vast blijft ongeacht het aantal vaardigheden.
Functiepariteit: HarnessAPI biedt alle functies van standalone FastAPI en FastMCP out-of-the-box, inclusief SSE-streaming, OpenAPI/Swagger UI en time-outs per vaardigheid, zonder dat extra bibliotheekintegratie vereist is.
Compatibiliteit: Het framework importeerde en registreerde succesvol 12 bestaande vaardigheden uit de agentskills.io-repository zonder aanpassingen aan de broncode, wat een implementatie zonder wrijving voor bestaande vaardigheidssets aantoont.

5. Betekenis en Beweringen

Het artikel beweert dat HarnessAPI het "oncomfortabele antwoord" van dubbel onderhoud bij de implementatie van LLM-tools oplost. De betekenis ligt in het transformeren van schema-consistentie van een discipline van de ontwikkelaar (gevoelig voor fouten en afwijkingen) naar een structurele invariant die door het framework wordt afgedwongen.

De auteurs benadrukken dat de reductie van 74% in boilerplate een gevolg is van deze invariant, maar dat het duurzamere resultaat de schalings eigenschap is. Naarmate agent-ecosystemen rijpen en ontwikkelaars tientallen of honderden vaardigheden implementeren, wordt de cumulatieve onderhoudslast van handmatige dubbele-stack-registratie onhoudbaar. HarnessAPI suggereert dat de oplossing niet ligt in betere hulpmiddelen voor het onderhouden van twee registraties, maar in de eliminatie van de tweede registratie volledig.

Het artikel blijft bescheiden wat betreft zijn reikwijdte:

Het claimt niet om end-to-end latentie- of concurrentie-benchmarks op te lossen, en verwijst naar de bekende prestatie-eigenschappen van de onderliggende FastAPI/Uvicorn-stack.
Het erkent beperkingen, zoals het gebruik van exec voor de generatie van MCP-omhulsels (een tijdelijke oplossing voor de huidige resolver van FastMCP) en het ontbreken van authenticatie per tool in de MCP-laag.
Het waarschuwt expliciet tegen het gebruik van het hot-swap-eindpunt in netwerkbereikbare implementaties, en beperkt dit tot lokale ontwikkelingsloops.

Kortom, HarnessAPI biedt een geünificeerde, vaardigheidsgerichte implementatielaag die schema-consistentie garandeert, onderhoudsoverhead vermindert en zowel streaming- als batch-interacties ondersteunt voor moderne LLM-agents.