mcp-tester

Servidor MCP instrumentado para probar la conformidad del cliente con las notificaciones */list_changed y otras características del protocolo.

Por qué

PR mcaps-microsoft/msx-mcp#321 propuso la aparición dinámica de herramientas mediante notifications/tools/list_changed. El PR se cerró con la afirmación de que "Copilot CLI almacena en caché tools/list al inicio de la sesión e ignora notifications/tools/list_changed", pero nunca se realizó un experimento instrumentado para probar o refutar esto.

Este repositorio proporciona el aparato para probar esa afirmación —y la conformidad de cualquier cliente MCP con list_changed— con evidencia real.

Qué hace

1. Servidor MCP de prueba (src/server.ts) -- Un servidor MCP auto-instrumentado que registra cada mensaje JSON-RPC en su tubería stdio. Expone herramientas, recursos y prompts en estado alfa, además de herramientas de activación que los cambian al estado beta y envían la notificación */list_changed correspondiente.

2. Controlador de cliente automatizado (src/driver.ts) -- Un Client de MCP basado en SDK que guía al servidor a través del ciclo completo de mutación. Este es el control: demuestra que el protocolo funciona cuando ambos puntos finales cumplen con la especificación. Cualquier cliente que se desvíe de este comportamiento es demostrablemente no conforme.

3. Analizador de registros (src/analyze.ts) -- Lee el registro JSONL y emite una tabla de evidencia en markdown que responde a preguntas específicas: ¿Recibió el cliente la notificación? ¿Volvió a realizar la solicitud? ¿Puede llamar al nuevo elemento? ¿Todavía puede llamar al elemento eliminado?

4. Protocolo humano (PROTOCOL.md) -- Instrucciones paso a paso para ejecutar la misma prueba contra Copilot CLI o cualquier otro cliente MCP.

Inicio rápido

git clone https://github.com/ericchansen/mcp-tester.git
cd mcp-tester
npm install
npm run build

Ejecutar el control automatizado (cliente SDK)

npm run driver -- --domain all

Esto inicia el servidor de prueba, ejecuta el protocolo de mutación completo para herramientas, recursos y prompts, e informa los resultados. Debería ver que los tres dominios pasan con total conformidad.

Analizar un registro

npm run analyze -- path/to/log.jsonl --domain tools

Probando su propio cliente MCP

Consulte PROTOCOL.md para obtener instrucciones paso a paso sobre cómo probar Copilot CLI o cualquier otro cliente MCP contra esta sonda.

Diseño del repositorio

mcp-tester/
|-- README.md          # This file
|-- PROTOCOL.md        # Human-driven test procedure
|-- LICENSE            # MIT
|-- package.json
|-- tsconfig.json
|-- src/
|   |-- server.ts      # Probe MCP server (stdio)
|   |-- logger.ts      # JSONL stdio tap + log writer
|   |-- analyze.ts     # CLI: parses log -> markdown evidence table
|   +-- driver.ts      # CLI: spawns server, drives it via SDK Client
+-- results/
    +-- copilot-cli/
        +-- .gitkeep   # Committed experiment results go here

Cómo funciona la sonda

Estado inicial (Alfa)

Además de cinco herramientas permanentes: mcptester_mutate_tools, mcptester_mutate_resources, mcptester_mutate_prompts, mcptester_status.

Después de la mutación (Beta)

Cuando se llama a una herramienta mcptester_mutate_*:

1. Se elimina el elemento alfa (mediante handle.remove() del SDK)

2. Se registra el elemento beta

3. El SDK envía automáticamente la notificación notifications/*/list_changed correspondiente

4. debouncedNotificationMethods combina la eliminación + el registro en una sola notificación

Registro

Cada mensaje JSON-RPC (entrante y saliente) se registra en un archivo JSONL. El registrador accede a process.stdin y process.stdout a través de flujos Transform instalados antes del transporte del SDK, por lo que ve cada byte sin interferir con el protocolo.

Limitaciones

• Solo transporte stdio -- aún no hay pruebas de HTTP/SSE

• Solo tres flujos de list_changed -- futuras pruebas planificadas para muestreo, obtención, raíces, progreso, finalizaciones

• Pruebas de servidor único -- prueba una conexión de servidor MCP a la vez

Licencia

MIT