Dokumentation

MCP Fusion/Protocol and runtime/Introspektion

Introspektion

Frag die KI über Vinkius

Lassen Sie einen Konnektor sich selbst beschreiben: die Serverkarte am bekannten Pfad, das nach RBAC gefilterte mcpfusion-Manifest, Metadaten pro Aktion und die Verträge hinter der Lockdatei.

Ein Konnektor, der sich selbst beschreiben kann, ist leichter zu betreiben, zu prüfen und zu integrieren. MCP Fusion stellt drei Introspektionsflächen bereit: eine statische Serverkarte, ein dynamisches Live-Manifest und eine Metadaten-API im Prozess.

Die Serverkarte

Sie wird unter /.well-known/mcp/server-card.json für http und stateless bereitgestellt und beim Start einmal kompiliert:

json
{
  "$schema": "https://modelcontextprotocol.io/schemas/server-card/v1",
  "version": "1.0",
  "protocolVersion": "2026-07-28",
  "serverInfo": { "name": "billing", "version": "1.4.0", "title": "Billing connector" },
  "transport": { "type": "streamable-http", "endpoint": "/mcp" },
  "capabilities": { "tools": {}, "prompts": {}, "resources": {} },
  "tools": [{ "name": "billing", "description": "...", "tags": ["finance"] }]
}

Die Fähigkeiten werden aus dem tatsächlich registrierten Serverbestand befüllt, sodass die Karte keine nicht vorhandene Oberfläche ankündigen kann. Sie wird schreibgeschützt, ohne Sitzung und mit einem öffentlichen Cache-Header von fünf Minuten ausgeliefert. Discovery-Clients und Überwachungssysteme lesen sie, ohne jemals eine MCP-Verbindung zu öffnen.

Das dynamische Manifest

Aktivieren Sie es, damit der Konnektor eine Ressource veröffentlicht, die sich selbst beschreibt:

typescript
attachToServer(server, {
  introspection: {
    enabled: true,
    uri: 'mcpfusion://manifest.json',
    filter: (manifest, ctx) => stripInternal(manifest, ctx.userRole),
  },
});

Das Manifest enthält die Serveridentität, den MVA-Architekturmarker und pro Tool Aktionen, destruktive und schreibgeschützte Kennzeichen, Pflichtfelder sowie pro Presenter Schema-Schlüssel, unterstützte UI-Blocktypen und die Information, ob Regeln kontextabhängig sind. Anders als die statische Karte wird das Manifest über die MCP-Verbindung gelesen und daher pro Sitzung gefiltert: Der Filter erhält Manifest und Request-Kontext und gibt zurück, was diese Sitzung sehen darf. Rollenbasierte Discovery ist somit eine Funktion und kein separater Endpunkt.

Verwenden Sie das Manifest, wenn sich Agents selbst orientieren sollen: Ein Agent kann zuerst mcpfusion://manifest.json lesen und gegen genau die Oberfläche planen, für die er berechtigt ist.

Metadaten im Prozess

Die Registry beantwortet Fragen zu ihrer eigenen Oberfläche ohne Roundtrip über das Wire:

typescript
for (const builder of registry.getBuilders()) {
  console.log(builder.getName(), builder.getActionNames());
  for (const action of builder.getActionMetadata()) {
    console.log(action.actionName, action.destructive, action.requiredFields);
    console.log(action.hasMiddleware, action.presenterName);
    console.log(action.presenterSchemaKeys, action.presenterUiBlockTypes);
  }
}

Dies ist dasselbe Material, das der Vertragscompiler verwendet. Deshalb kann die CLI Ihre Oberfläche ausgeben, das Lockfile sie hashen und ein Admin-Dashboard sie darstellen: eine Quelle, drei Verbraucher.

Verträge und Digests

Jedes Tool wird als ToolContract mit den jeweils gehashten Bereichen Oberfläche, Verhalten, Token-Ökonomie und Berechtigungen materialisiert. computeServerDigest() setzt sie zu einem Server-Digest zusammen; compareServerDigests() zeigt, ob zwei Deployments verhaltensgleich sind. Das Lockfile schreibt genau dieses Material auf die Festplatte. Siehe Contracts für Schema und CI-Gate.

Warum das im Betrieb wichtig ist

  • Onboarding: Ein neuer Client liest die Karte und kennt Transport und Endpunkt vor der Verbindung
  • Geringste Berechtigungen: Der Manifestfilter macht die Sichtbarkeit von Fähigkeiten zu einer Laufzeitentscheidung pro Rolle
  • Auditierung: Der Vertrags-Digest ist das von einem Prüfer signierte Artefakt, kein Dashboard-Screenshot
  • Regressionserkennung: Der Vergleich von Digests über Releases beantwortet "Hat sich das Verhalten geändert?", ohne einen Diff des gesamten Repositorys zu lesen

Nächste Schritte