🛡️ MCPResilience

Un servidor MCP resiliente y conforme a la especificación, construido sobre el SDK oficial v2

Habla MCP como lo hable tu cliente. MCPResilience detecta automáticamente las eras de protocolo heredadas y modernas en la primera petición — y sobrevive a la diferencia.

🔌 Modos de cliente

MCPResilience detecta automáticamente qué era de protocolo habla un cliente que se conecta — sin necesidad de configuración:

1. ⚡ Clientes modernos sin estado — los clientes cuya primera petición lleva el sobre _meta (io.modelcontextprotocol/protocolVersion + clientInfo) se saltan el handshake por completo. tools/call puede ser su primer mensaje.

2. 🤝 Clientes heredados con handshake — los clientes sin ese sobre se enrutan a través del flujo tradicional de initialize, aplicando -32600 Invalid request parameters a cualquier cosa enviada antes de que initialize se complete.

Consulta Soporte de protocolo para el desglose completo de ambas eras.

Related MCP server: mcp-uni

🧠 Qué es esto

MCPResilience existe porque sustituir un servidor MCP hecho a mano por el SDK oficial no es un cambio directo — el formato de red cambia de formas que rompen las migraciones ingenuas. Este proyecto aborda eso en dos etapas:

1. Migración al SDK — sustituir un núcleo de servidor MCP hecho a mano por el SDK oficial de MCP v2, apuntando a la especificación 2026-07-28, para obtener un núcleo sin estado y serialización Pydantic con seguridad de tipos.

2. Endurecimiento de compatibilidad — asegurarse de que la migración no elimina silenciosamente el soporte para clientes que aún usan el handshake heredado, no pierde datos por huecos en el esquema upstream, ni rompe la extensión experimental Tasks a mitad de vuelo.

Ambas etapas están documentadas honestamente a continuación, incluido el único bug del SDK upstream que apareció en el camino.

📊 Resultados clave

Todas las pruebas de compatibilidad de la Fase 5 y los benchmarks de la Fase 6 pasan, de extremo a extremo, en el SDK oficial de MCP v2 — con soporte completo para ambas eras de protocolo y la extensión experimental Tasks, además de un bug del SDK upstream identificado y parcheado (consulta Quirk conocido del SDK).

Extensión Tasks: qué cambió con la migración al SDK

🏗️ Cómo funciona

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

📡 Soporte de protocolo

Era sin estado (2026-07-28)

Bajo la especificación moderna, el handshake tradicional initialize → notifications/initialized es obsoleto. El servidor ejecuta un serve_dual_era_loop:

• Si la primera petición incluye el sobre _meta con io.modelcontextprotocol/protocolVersion y io.modelcontextprotocol/clientInfo, el servidor se fija en la era moderna sin estado.

• Los clientes pueden enviar tools/call como su primera petición — no se necesita ninguna llamada a initialize.

Era heredada

Si la primera petición carece del sobre _meta moderno, el servidor se fija en la era heredada:

• Cualquier petición enviada antes de initialize (p. ej. tools/call) se rechaza con -32600 Invalid request parameters.

• Una vez que initialize ha sido respondido, el servidor no espera a notifications/initialized antes de procesar más peticiones.

Gestión de desajuste de versión

Las peticiones modernas que especifican una versión de protocolo no soportada en el sobre _meta se rechazan limpiamente con -32022 Unsupported protocol version — la conexión en sí se preserva en lugar de descartarse.

🧩 Inmersión profunda en la extensión Tasks

La extensión experimental Tasks sufrió el mayor cambio de formato de red de todo lo que hubo en la migración (consulta la tabla comparativa en Resultados clave). Dos comportamientos merecen una mención específica:

• tasks/get ahora es solo metadatos. El contenido de las tareas se entrega exclusivamente a través del flujo de respuesta de tools/call; hacer polling a tasks/get solo devolverá campos de estado como statusMessage y createdAt — nunca el payload en sí.

• La cancelación es idempotente por diseño. Re-cancelar una tarea que ya está completed o cancelled devuelve un CancelTaskResult exitoso en lugar de un error, a diferencia del -32602 del servidor heredado al cancelar repetidamente.

Quirk conocido del SDK

SDK Issue #2156 — campo execution eliminado de tools/list. El esquema Pydantic actual para v2026_07_28.Tool no define el campo experimental execution, por lo que serialize_server_result lo elimina silenciosamente de las respuestas de tools/list.

Solución alternativa: un monkeypatch específico en mcp_types.methods.serialize_server_result intercepta la salida validada y restaura el diccionario execution a partir de los datos originales del handler. Es un parche temporal — elimínalo cuando el esquema upstream incluya el campo de forma nativa.

🔧 Notas técnicas (las partes que no fueron triviales)

1. La detección de era ocurre exactamente una vez, en la primera petición. No hay ruta de actualización a mitad de conexión — un cliente que se abre sin el sobre _meta permanece en la era heredada durante toda la vida de esa conexión, incluso si empieza a enviar peticiones con forma moderna más tarde.

2. El task handle no solo se movió, su contrato cambió. Reubicar taskHandle del result de nivel superior a result._meta también liberó el objeto result de nivel superior para reservarlo puramente para la salida de contenido inmediato y el indicador isError — una separación más limpia de lo que permitía la forma heredada.

3. El monkeypatch está acotado estrechamente a propósito. Solo intercepta serialize_server_result para restaurar un campo faltante, en lugar de bifurcar o envolver el esquema del SDK por completo — manteniendo el parche fácil de eliminar en el momento en que upstream publique una corrección.

🛠️ Stack tecnológico

• Protocolo: JSON-RPC 2.0 sobre el Model Context Protocol, especificación 2026-07-28

• SDK: SDK oficial de MCP v2 — validación y serialización de esquemas basada en Pydantic

• Núcleo del servidor: Python, gestión de peticiones sin estado primero (serve_dual_era_loop)

• Pruebas: suite de compatibilidad de la Fase 5 + ejecución de benchmarks de la Fase 6

🚀 Primeros pasos

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

Ajusta los comandos anteriores para que coincidan con tu estructura de paquete y punto de entrada reales.

Ejecuta la suite de compatibilidad y los benchmarks con:

pytest

⚠️ Limitaciones honestas

• La extensión Tasks sigue siendo experimental upstream. No está finalizada en la especificación central de MCP, por lo que su formato de red podría cambiar de nuevo en una futura versión del SDK — este servidor sigue la implementación experimental actual del SDK, no un objetivo estable.

• La corrección del campo execution es un monkeypatch, no una solución permanente. Parchea serialize_server_result en tiempo de ejecución en lugar de corregir el esquema subyacente — debe eliminarse cuando SDK Issue #2156 publique una corrección upstream.

• La detección de era es solo en la primera petición. Un cliente fijado en la era heredada al inicio de la conexión no tiene ruta para "actualizarse" a la era sin estado a mitad de conexión, incluso si sus peticiones posteriores parecen modernas.

🙏 Agradecimientos

• SDK oficial de MCP v2 — mantenedores del Model Context Protocol

• Especificación del Model Context Protocol (2026-07-28)

🧑💻 Autor

Hoor Shumail IA | Aprendizaje automático | IA agéntica | Sistemas multiagente | Inteligencia profesional

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

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

📜 Licencia

Este proyecto se desarrolla con fines educativos, de investigación y de portafolio.

Se basa en el SDK oficial del Model Context Protocol — consulta la licencia propia de ese SDK y la especificación del Model Context Protocol para conocer los términos que rigen esos componentes.