MCP Contract Harness
Servidor MCP de solo lectura y clientes independientes para comprobar negociación, paginación, errores y cancelación por stdio, con mensajes reales e informes reproducibles.
Problema y utilidad para agentes
Un initialize exitoso no demuestra que una integración maneje la segunda página, una cancelación o un error. El proyecto comprueba esos contratos contra una versión concreta de MCP y conserva los mensajes intercambiados.
Un agente necesita saber qué herramientas existen, recuperar recursos completos y distinguir errores de protocolo de errores de ejecución. Esta implementación hace observables esos límites mediante clientes y trazas de transporte.
Arquitectura
- Servidor acotado. Un servidor escrito con la biblioteca estándar de Python implementa un subconjunto de MCP 2025-06-18 sobre JSON-RPC por stdio. Expone tres notas ficticias y dos herramientas de lectura, sin acceso a archivos ni a la red.
- Tres clientes. Un cliente Python propio, el SDK oficial Python 2.3.0 y el SDK oficial TypeScript 1.32.1 se conectan al mismo servidor. Los clientes SDK negocian desde 2025-11-25 a la versión soportada.
- Registro de mensajes. Un proxy registra las líneas reales de los clientes SDK antes de reenviarlas. El cliente propio registra su transporte por separado. Las trazas conservan dirección y mensajes JSON-RPC.
- Validación del contrato. Un verificador adicional comprueba correlación, cadenas de cursores, cancelaciones sin respuesta y un ping posterior contestado. Los errores de herramienta usan isError; los de protocolo usan errores JSON-RPC.
Qué demuestra
- Implementación de un contrato MCP versionado sin depender de un SDK en el servidor.
- Interoperabilidad medida con tres clientes, con cobertura declarada por cliente y mensajes inspeccionables.
- Validación de casos negativos, paginación y cancelación más allá de una inicialización exitosa.
Resultados publicados
El informe publicado registra un servidor local ejercitado por tres clientes. El cliente propio completó 13 escenarios y cada cliente SDK completó ocho. Los tres negociaron MCP 2025-06-18.
La ejecución registrada usa Python 3.11.9 y Node 24.8.0 en un Intel Xeon W-3223. Todos los clientes recorren páginas de recursos y herramientas, leen una nota, obtienen resultados y errores, prueban un cursor inválido y cancelan una operación antes de enviar otro ping.
Ejecución registrada por cliente
| Cliente | Versión | Controles | Mensajes | Protocolo |
|---|---|---|---|---|
| Referencia propia | 0.1.0 | 13 | 34 | 2025-06-18 |
| SDK oficial Python | 2.3.0 | 8 | 23 | 2025-06-18 |
| SDK oficial TypeScript | 1.32.1 | 8 | 23 | 2025-06-18 |
Son escenarios fijos de corrección sobre un subconjunto stdio. Los 13, 8 y 8 controles no son la misma cobertura ni un ranking de clientes. El resultado no certifica conformidad completa con MCP ni compatibilidad con hosts gráficos.
La matriz detalla controles que solo ejecuta el cliente propio: errores antes de inicializar, método y recurso desconocidos, JSON inválido y cancelaciones desconocidas. Matriz de interoperabilidad y alcance.
Las pruebas negativas documentadas alteran una página, la versión negociada, una respuesta duplicada y una respuesta a una petición cancelada. El informe de clientes no es una medición estadística de detección de defectos. Matriz de interoperabilidad y alcance.
Reproducir
El servidor y el cliente propio usan la biblioteca estándar de Python. La reproducción con los SDK requiere Python 3.11.9, Node 24.8.0, npm 11.6.0 y los archivos lock del repositorio. No necesita modelos, cuentas ni APIs pagas.
El primer comando ejecuta el cliente propio contra un subproceso real. La reproducción completa instala dependencias fijadas, verifica las trazas guardadas y genera nuevas en un directorio libre. No uses Python con -O: los clientes usan assertions de contrato.
Ejecutar el cliente propio
git clone https://github.com/lucioduran/mcp-contract-harness.git
cd mcp-contract-harness
git checkout 44e77c071525127cd7e9ef5008b1b9f41e02ad07
python -m clients.rawReproducir los tres clientes
python -m venv .venv
. .venv/bin/activate
python -m pip install --require-hashes -r requirements-dev.lock
npm ci --ignore-scripts
python -m clients.reproduce verify --output results/reference
python -m clients.reproduce run --output build/reproduced
python -m clients.reproduce verify --output build/reproducedAlcance y límites
- No implementa HTTP, OAuth, subscriptions, prompts, sampling, elicitation, progress ni plantillas de recursos. No es una certificación MCP.
- No se probaron ChatGPT, Claude Desktop, IDEs ni otros hosts gráficos. La compatibilidad con SDKs no demuestra compatibilidad con esos hosts.
- La cancelación usa una demora deliberada de 400 ms y una ventana de silencio de al menos 600 ms. No prueba todas las carreras de planificación ni ausencia de fugas bajo carga.
- Hay límites de 64 KiB por mensaje, 32 solicitudes activas y 10.000 identificadores por sesión. No se evaluaron rendimiento, backpressure, fuzzing exhaustivo ni agotamiento adversarial de recursos.
- Las anotaciones de herramientas son descriptivas. La restricción real viene de leer un catálogo compilado; no hay una auditoría de seguridad ni un sandbox para herramientas arbitrarias.
- Las trazas y hashes permiten inspeccionar consistencia. No autentican quién realizó la medición ni constituyen revisión independiente.
Fuentes y revisión
Los valores de esta ficha provienen del informe enlazado. No son una medición en vivo. El informe conserva la revisión ejecutada; la revisión consultada incluye la publicación posterior de ese informe.
- Revisión consultada:
44e77c071525127cd7e9ef5008b1b9f41e02ad07 - Revisión registrada por el experimento:
781f24d4188cae00d231460ccce04638f877f33c - Fecha del informe (UTC):
- Catálogo de notas ficticias SHA-256:
163b61136fba3454add6694d38492f6ee6b899c34864f4c10b971faaab720fdc