🛡️ MCPResilience

Ein belastbarer, spezifikationskonformer MCP-Server basierend auf dem offiziellen SDK v2

Sprich MCP, wie dein Client es spricht. MCPResilience erkennt automatisch die Legacy- und modernen Protokoll-Ären bei der allerersten Anfrage – und übersteht den Unterschied.

🔌 Client-Modi

MCPResilience erkennt automatisch, welche Protokoll-Ära ein verbindender Client spricht – keine Konfiguration erforderlich:

1. ⚡ Moderne zustandslose Clients – Clients, deren erste Anfrage die _meta-Hülle (io.modelcontextprotocol/protocolVersion + clientInfo) trägt, überspringen den Handshake vollständig. tools/call kann ihre allererste Nachricht sein.

2. 🤝 Legacy-Handshake-Clients – Clients ohne diese Hülle werden durch den traditionellen initialize-Ablauf geführt, wobei -32600 Invalid request parameters für alles erzwungen wird, was vor Abschluss von initialize gesendet wird.

Siehe Protokollunterstützung für die vollständige Aufschlüsselung beider Ären.

Related MCP server: mcp-uni

🧠 Was das ist

MCPResilience existiert, weil der Austausch eines handgeschriebenen MCP-Servers durch das offizielle SDK kein Drop-in-Wechsel ist – das Drahtformat ändert sich auf eine Weise, die naive Migrationen bricht. Dieses Projekt geht das in zwei Phasen an:

1. SDK-Migration – Ersetzen eines handgeschriebenen MCP-Serverkerns durch das offizielle MCP SDK v2, das auf die 2026-07-28-Spezifikation abzielt, um einen zustandslosen Kern und typsichere Pydantic-Serialisierung zu erhalten.

2. Kompatibilitäts-Härtung – Sicherstellen, dass die Migration nicht stillschweigend die Unterstützung für Clients verliert, die noch den Legacy-Handshake verwenden, keine Daten durch Lücken im Upstream-Schema verliert oder die experimentelle Tasks-Erweiterung mitten im Betrieb bricht.

Beide Phasen sind unten ehrlich dokumentiert, einschließlich des einen Upstream-SDK-Bugs, der dabei aufgetaucht ist.

📊 Wichtige Ergebnisse

Alle Kompatibilitätstests der Phase 5 und Benchmarks der Phase 6 bestehen Ende-zu-Ende auf dem offiziellen MCP SDK v2 – mit vollständiger Unterstützung für beide Protokoll-Ären und die experimentelle Tasks-Erweiterung, plus einem identifizierten und gepatchten Upstream-SDK-Bug (siehe Bekannte SDK-Eigenheit).

Tasks-Erweiterung: Was sich unter der SDK-Migration geändert hat

🏗️ So funktioniert es

Incoming connection
        │
        ▼
  First request received
        │
        ▼
  Does it carry the _meta envelope?
  (protocolVersion + clientInfo)
        │
   ┌────┴────┐
  Yes         No
   │           │
   ▼           ▼
Modern Era   Legacy Era
(stateless)  (handshake required)
   │           │
   ▼           ▼
tools/call   initialize → any request
runs          (initialize enforced,
immediately    notifications/initialized
               not blocked)
   │           │
   └─────┬─────┘
         ▼
  Era locked for the
  life of the connection

📡 Protokollunterstützung

Zustandslose Ära (2026-07-28)

Unter der modernen Spezifikation ist der traditionelle initialize → notifications/initialized-Handshake veraltet. Der Server führt eine serve_dual_era_loop aus:

• Wenn die erste Anfrage die _meta-Hülle mit io.modelcontextprotocol/protocolVersion und io.modelcontextprotocol/clientInfo enthält, verriegelt sich der Server in die moderne zustandslose Ära.

• Clients können tools/call als allererste Anfrage senden – kein initialize-Aufruf erforderlich.

Legacy-Ära

Wenn die erste Anfrage die moderne _meta-Hülle vermissen lässt, verriegelt sich der Server in die Legacy-Ära:

• Jede Anfrage, die vor initialize gesendet wird (z. B. tools/call), wird mit -32600 Invalid request parameters abgelehnt.

• Sobald initialize beantwortet wurde, wartet der Server nicht auf notifications/initialized, bevor er weitere Anfragen verarbeitet.

Behandlung von Versionskonflikten

Moderne Anfragen, die eine nicht unterstützte Protokollversion in der _meta-Hülle angeben, werden sauber mit -32022 Unsupported protocol version abgelehnt – die Verbindung selbst bleibt erhalten, anstatt abgebrochen zu werden.

🧩 Tasks-Erweiterung im Detail

Die experimentelle Tasks-Erweiterung hat bei der Migration die größten Änderungen im Drahtformat durchgemacht (siehe die Vergleichstabelle in Wichtige Ergebnisse). Zwei Verhaltensweisen sind besonders erwähnenswert:

• tasks/get ist jetzt nur noch Metadaten. Der Aufgabeninhalt wird ausschließlich über den tools/call-Antwortstream geliefert; das Pollen von tasks/get gibt nur Statusfelder wie statusMessage und createdAt zurück – niemals die Nutzlast selbst.

• Der Abbruch ist von Natur aus idempotent. Das erneute Abbrechen einer bereits completed- oder cancelled-Aufgabe gibt ein erfolgreiches CancelTaskResult zurück, anstatt einen Fehler zu liefern, anders als der -32602 des Legacy-Servers bei wiederholtem Abbruch.

Bekannte SDK-Eigenheit

SDK-Issue #2156 – execution-Feld wird aus tools/list entfernt. Das aktuelle Pydantic-Schema für v2026_07_28.Tool definiert das experimentelle execution-Feld nicht, daher entfernt serialize_server_result es stillschweigend aus tools/list-Antworten.

Workaround: Ein gezielter Monkeypatch auf mcp_types.methods.serialize_server_result fängt die validierte Ausgabe ab und stellt das execution-Wörterbuch aus den ursprünglichen Handler-Daten wieder her. Dies ist eine Übergangslösung – entfernen Sie sie, sobald das Upstream-Schema das Feld nativ enthält.

🔧 Technische Hinweise (die nicht trivialen Teile)

1. Die Ära-Erkennung erfolgt genau einmal, bei der ersten Anfrage. Es gibt keinen Upgrade-Pfad mitten in der Verbindung – ein Client, der ohne die _meta-Hülle öffnet, bleibt für die Lebensdauer dieser Verbindung in der Legacy-Ära, selbst wenn er später modern geformte Anfragen sendet.

2. Der Aufgaben-Handle hat sich nicht nur verschoben, sein Vertrag hat sich geändert. Die Verlagerung von taskHandle von der obersten Ebene result zu result._meta hat auch das result-Objekt auf oberster Ebene freigegeben, um es ausschließlich für die unmittelbare Inhaltsausgabe und das isError-Flag zu reservieren – eine sauberere Trennung, als es die Legacy-Form erlaubte.

3. Der Monkeypatch ist bewusst eng begrenzt. Er fängt nur serialize_server_result ab, um ein fehlendes Feld wiederherzustellen, anstatt das SDK-Schema komplett zu forken oder zu umhüllen – so bleibt der Patch leicht zu entfernen, sobald Upstream einen Fix liefert.

🛠️ Technologie-Stack

• Protokoll: JSON-RPC 2.0 über das Model Context Protocol, Spezifikation 2026-07-28

• SDK: Offizielles MCP SDK v2 – Pydantic-basierte Schema-Validierung und -Serialisierung

• Serverkern: Python, zustandslose Erst-Anfrage-Verarbeitung (serve_dual_era_loop)

• Tests: Kompatibilitätssuite der Phase 5 + Benchmark-Lauf der Phase 6

🚀 Erste Schritte

git clone https://github.com/HoorShumail/MCPResilience.git
cd MCPResilience
pip install -r requirements.txt

Passen Sie die obigen Befehle an Ihr tatsächliches Paketlayout und Ihren Einstiegspunkt an.

Führen Sie die Kompatibilitätssuite und die Benchmarks aus mit:

pytest

⚠️ Ehrliche Einschränkungen

• Die Tasks-Erweiterung ist upstream noch experimentell. Sie ist in der Kern-MCP-Spezifikation nicht finalisiert, daher könnte sich ihr Drahtformat in einer zukünftigen SDK-Version erneut ändern – dieser Server folgt der aktuellen experimentellen Implementierung des SDK, nicht einem stabilen Ziel.

• Der Fix für das execution-Feld ist ein Monkeypatch, keine dauerhafte Lösung. Er patcht serialize_server_result zur Laufzeit, anstatt das zugrunde liegende Schema zu beheben – er muss entfernt werden, sobald SDK-Issue #2156 einen Upstream-Fix liefert.

• Die Ära-Erkennung erfolgt nur bei der ersten Anfrage. Ein Client, der zu Verbindungsbeginn in die Legacy-Ära gesperrt ist, hat keinen Weg, mitten in der Verbindung auf die zustandslose Ära zu „upgraden", selbst wenn seine späteren Anfragen modern aussehen.

🙏 Danksagungen

• Offizielles MCP SDK v2 – Maintainer des Model Context Protocol

• Model Context Protocol Spezifikation (2026-07-28)

🧑💻 Autor

Hoor Shumail KI | Maschinelles Lernen | Agentische KI | Multi-Agenten-Systeme | Karriere-Intelligenz

• GitHub: https://github.com/HoorShumail

• LinkedIn: https://www.linkedin.com/in/hoor-shumail-a3a076326/

📜 Lizenz

Dieses Projekt wird für Bildungs-, Forschungs- und Portfoliozwecke entwickelt.

Es basiert auf dem offiziellen Model Context Protocol SDK – beachten Sie die eigene Lizenz dieses SDK und die Model Context Protocol Spezifikation für die Bedingungen, die diese Komponenten regeln.