Dokumentation

MCP Fusion/Protocol and runtime/State-Sync

State-Sync

Frag die KI über Vinkius

Teilen Sie dem Agenten mit, was wiederverwendet werden darf und was gerade stale geworden ist: Cache-Control-Hinweise in Beschreibungen, glob-gescopete Invalidierung bei Mutationen, Ressourcen-Benachrichtigungen und MCP-2.0-List-Caching.

Der klassische Fehler eines Agenten nach einer Mutation: Er liest veraltete Daten erneut, "behebt" das falsche Problem oder wendet seine Änderung erneut an, weil die Lesung aus seinem eigenen Kontext stammt, nicht von Ihrem Server. Die State-Sync-Ebene von MCP Fusion beantwortet genau eine Frage: Wann darf der Agent gecachten Daten vertrauen, und was signalisiert ihm, dass eine Domäne gerade stale geworden ist?

Dies ist kein Response-Cache. MCP Fusion speichert niemals Tool-Ergebnisse. Es ist ein temporales Signalisierungssystem, das HTTP-Cache-Vokabular nutzt, das das Modell bereits versteht.

Die Richtlinie deklarieren

Drei Methoden auf jedem Tool:

typescript
f.query('billing.get_invoice')
  .cached()                          // "[Cache-Control: immutable]" on the description
  .handle(...)

f.mutation('billing.refund')
  .invalidates('billing.get_*', 'dashboard.invoices')
  .handle(...)
  • .cached() stempelt immutable; .stale() stempelt no-store; es gibt kein max-age, weil Sprachmodelle keine Uhr haben
  • .invalidates(patterns) deklariert, welche Domänen ein erfolgreicher Aufruf stale macht, mit Dot-Glob-Mustern (* ein Segment, ** beliebige Tiefe)
  • Hints werden in einer first-match-wins PolicyEngine mit memoisierter Auflösung zu Richtlinien kompiliert

Was auf dem Draht landet

Zwei Abfänge auf Protokollebene, keine Middleware:

Bei tools/list tragen die dekorierten Beschreibungen die Direktive: Retrieve an invoice by ID [Cache-Control: immutable]. Der Agent sieht die Wiederverwendungsregel zum Planungszeitpunkt.

Bei tools/call lösen nur erfolgreiche Aufrufe eine Invalidierung aus (eine fehlgeschlagene isError-Mutation sendet nichts). Die Antwort erhält einen maschinenlesbaren Tag als erstes Inhaltselement, positioniert an Index 0, damit eine Kürzung ihn nicht abschneiden kann:

xml
<cache_invalidation cause="billing.refund" domains="billing.get_*" />

und jede stale URI feuert notifications/resources/updated mit einem synthetischen mcpfusion://stale/{pattern}, damit Clients mit Subscriptionen genau wissen, was sie verwerfen müssen.

Ressourcen und Subscriptionen

Echte Ressourcen laufen über f.resource() (oder defineResource): ein URI-Template wie invoices://{id}, ein Handler, der { text } oder { blob } zurückgibt, ein subscribable-Flag und Audience-Annotationen. Template-URIs werden mit Matching im Stil von RFC-6570 aufgelöst.

Bei MCP 2.0 ist der subscriptions/listen-Stream erstklassig: Ein Client registriert einen Filter (toolsListChanged, promptsListChanged, resourcesListChanged, konkrete resourceSubscriptions-URIs), der Server bestätigt mit dem erfüllten Filter und streamt die passenden Events. Die Zustellung ist best-effort und blockiert die Pipeline nie: Eine Benachrichtigung wird verworfen, nicht gedrosselt.

List-Caching (SEP-2549)

Getrennt vom Tool-Staleness kann ein Server bei MCP 2.0 List-Ergebnissen Cache-Metadaten anhängen: ttlMs und scope (private pro Client, public geteilt) auf tools/list, prompts/list und den Ressourcen-Listen, konfiguriert mit attachToServer({ listCacheTtlMs, listCacheScope }). Standard: 5 Minuten, private. Ein Proxy vor Ihrem Connector kann wiederholte List-Aufrufe dann aus seinem Cache bedienen, das ist die Antwort des Protokolls auf gesprächige Clients beim Cold Start. Setzen Sie listCacheTtlMs: 0, und die Metadaten verschwinden mit null Overhead.

Das dynamische Manifest und Introspection

attachToServer({ introspection: { enabled: true } }) registriert die Ressource mcpfusion://manifest.json: jedes Tool, jede Action, jeder Presenter, jeder Schema-Schlüssel, jedes destructive-Flag und jedes contextual-rule-Flag, pro Lesung RBAC-gefiltert mit einem frischen contextFactory-Kontext, damit zwei Sitzungen das Manifest lesen, das sie sehen dürfen. Dieselbe Materialize-and-Digest-Maschinerie ist es, die Governance festhält.

Warum nicht max-age

Weil es im Modell keinen Timer gibt: Es kann keinen Freshness-Header prüfen, man kann ihm nur Bescheid sagen. immutable bedeutet "wiederverwenden in dieser Unterhaltung, außer ich sage anders"; Invalidierungs-Events sind das "anders". Das HTTP-Vokabular wird gerade deshalb geliehen, weil Modelle darauf trainiert sind, und das [Cache-Control]-Suffix reitet in der Tool-Beschreibung mit, dem einzigen Text, den der Agent vor dem Planen zuverlässig liest.

Nächste Schritte