mcp-resource-subscribe-test

Servidor HTTP Streamable MCP mínimo para probar si los clientes MCP manejan correctamente resources/subscribe y notifications/resources/updated.

Este repositorio pretende ser un laboratorio de problemas reproducibles / compatibilidad para agentes de IA de CLI como Codex CLI, Gemini CLI, OpenCode, GitHub Copilot CLI, Claude Code, Goose y Crush.

Propósito

El servidor expone un recurso MCP fijo:

test://review/status

Contenido inicial:

status: pending
version: 1
message: Waiting for simulated review result.

Después de que un cliente se suscribe al recurso, el servidor espera MCP_TEST_UPDATE_DELAY_SECONDS, cambia el recurso y envía:

{
  "method": "notifications/resources/updated",
  "params": {
    "uri": "test://review/status"
  }
}

Contenido actualizado:

status: reviewed
version: 2
message: Simulated review result is now available.

Related MCP server: mcp-hello-world

¿Por qué Resources/Subscribe en lugar de Tools/Call?

tools/call es útil para acciones explícitas, pero muchos flujos de trabajo de agentes dependen de un contexto que cambia después de la solicitud original. Sondear cada fuente es ruidoso y específico del cliente. Las suscripciones a recursos MCP brindan a los clientes una forma a nivel de protocolo de saber que un objeto de contexto conocido cambió y debe volver a leerse.

Ejemplos donde el comportamiento de suscripción importa:

• Resultado de revisión de Copilot

• Hilo de revisión de PR

• Estado de CI

• Comentario de Codecov

• Discusión de issue de GitHub

• Resultado de compilación/prueba local

Este servidor de prueba se centra en si el cliente nota una actualización de recurso, vuelve a ejecutar resources/read y refleja el nuevo contenido en el bucle del agente / contexto del modelo.

Inicio

docker compose up --build

URL de MCP:

http://127.0.0.1:8089/mcp

Para desarrollo local:

npm install
npm run dev

Configuración

Si MCP_TEST_SEND_LIST_CHANGED=true, el servidor también envía notifications/resources/list_changed después de la actualización simulada.

Comportamiento esperado del cliente

Un cliente MCP ideal debería seguir este flujo:

initialize
  ↓
resources/list
  ↓
resources/read test://review/status
  ↓
resources/subscribe test://review/status
  ↓
receive notifications/resources/updated
  ↓
resources/read test://review/status again
  ↓
reflect updated status: reviewed in agent context

Capacidades del servidor

La respuesta de inicialización anuncia:

{
  "resources": {
    "subscribe": true,
    "listChanged": true
  }
}

Mensajes MCP implementados

• initialize

• resources/list

• resources/read

• resources/subscribe

• resources/unsubscribe

• notifications/resources/updated

• notifications/resources/list_changed cuando MCP_TEST_SEND_LIST_CHANGED=true

No se implementan herramientas.

Registros

El servidor registra cada mensaje importante para que el comportamiento del cliente pueda verificarse objetivamente:

[initialize] client connected
[resources/list] requested
[resources/read] uri=test://review/status version=1
[resources/subscribe] uri=test://review/status
[resource/update] uri=test://review/status version=2
[notification/send] notifications/resources/updated uri=test://review/status
[resources/read] uri=test://review/status version=2
[resources/unsubscribe] uri=test://review/status

La evidencia clave para el soporte de suscripción de recursos es:

resources/subscribe was received
notification was sent
resources/read was received again after the notification

Pruebas

npm test

El conjunto de pruebas verifica:

• resources/list devuelve test://review/status

• resources/read inicial devuelve la versión 1

• resources/subscribe activa una actualización interna a la versión 2

• Se recibe notifications/resources/updated

• resources/read actualizado devuelve la versión 2

Notas de compatibilidad del cliente

Codex CLI

• Conexión MCP:

• ¿Llama a resources/list?

• ¿Llama a resources/read?

• ¿Llama a resources/subscribe?

• ¿Recibe notifications/resources/updated?

• ¿Vuelve a leer el recurso después de la actualización?

• Notas:

Gemini CLI

• Conexión MCP:

• ¿Llama a resources/list?

• ¿Llama a resources/read?

• ¿Llama a resources/subscribe?

• ¿Recibe notifications/resources/updated?

• ¿Vuelve a leer el recurso después de la actualización?

• Notas:

OpenCode

• Conexión MCP:

• ¿Llama a resources/list?

• ¿Llama a resources/read?

• ¿Llama a resources/subscribe?

• ¿Recibe notifications/resources/updated?

• ¿Vuelve a leer el recurso después de la actualización?

• Notas:

GitHub Copilot CLI

• Conexión MCP:

• ¿Llama a resources/list?

• ¿Llama a resources/read?

• ¿Llama a resources/subscribe?

• ¿Recibe notifications/resources/updated?

• ¿Vuelve a leer el recurso después de la actualización?

• Notas:

Claude Code

• Conexión MCP:

• ¿Llama a resources/list?

• ¿Llama a resources/read?

• ¿Llama a resources/subscribe?

• ¿Recibe notifications/resources/updated?

• ¿Vuelve a leer el recurso después de la actualización?

• Notas:

Goose

• Conexión MCP:

• ¿Llama a resources/list?

• ¿Llama a resources/read?

• ¿Llama a resources/subscribe?

• ¿Recibe notifications/resources/updated?

• ¿Vuelve a leer el recurso después de la actualización?

• Notas:

Crush

• Conexión MCP:

• ¿Llama a resources/list?

• ¿Llama a resources/read?

• ¿Llama a resources/subscribe?

• ¿Recibe notifications/resources/updated?

• ¿Vuelve a leer el recurso después de la actualización?

• Notas: