MCP Observer Server

servidor observador mcp

mcp-observer-server es un servidor MCP (Protocolo de Contexto de Modelo) que monitoriza los eventos del sistema de archivos y proporciona notificaciones en tiempo real a los clientes MCP. Actúa como un puente (más bidireccional) entre el sistema de archivos local y los asistentes de IA como Claude Inspector, lo que les permite responder automáticamente a los cambios de archivos.

NOTA: Esta es una demostración/prueba de concepto de un servidor MCP de monitoreo de archivos en el que estoy trabajando. He recibido muchas preguntas, comentarios, problemas y debates sobre este tema, así que quería publicar esta implementación mínima para compartir mi enfoque.

Contexto

El protocolo MCP define el concepto de suscripción de recursos, donde un cliente puede solicitar ser notificado de cualquier cambio en un recurso, y el servidor puede optar por enviar notificaciones. A continuación, se muestra el diagrama de flujo:

El protocolo indica que el cliente debe enviar una solicitud de lectura al servidor para leer los cambios (todo esto es opcional, por cierto). Sin embargo, me parece un poco engorroso e implica un viaje adicional, y preferiría que mi notificación de actualización de recursos también describiera el cambio. Por suerte, el SDK ofrece un campo meta / _meta y se puede enviar prácticamente lo que se quiera. Así que podría querer enviar el número de líneas modificadas, una comparación de los cambios, quién sabe qué más. No lo he implementado en esta demo; ahora mismo solo envío la marca de tiempo. (Básicamente, extraje todo del servidor excepto la prueba de concepto mínima). Además, se ejecuta en el transporte stdio, nada sofisticado.

¡NOTA! Aún no he probado esto con ningún cliente MCP real. Entiendo que muchos clientes de vista admiten suscripciones de recursos, ya que son opcionales. Afortunadamente, Inspector es un cliente muy bueno y puedes usarlo para probar este servidor.

INSTRUCCIONES DE DEMOSTRACIÓN:

1. Clonar el repositorio.
2. Instale las dependencias usando uv (o de alguna otra manera, supongo).
3. Ejecute el servidor usando make start (usa uv ) o ejecute npx @modelcontextprotocol/inspector uv run src/mcp_observer_server/server.py .
4. Abra el cliente Inspector y conéctese usando stdio, no necesita configuración.
5. Utilice la herramienta subscribe para supervisar un directorio o archivo (alternativamente, puede ejecutar "Listar recursos", hacer clic en un recurso y luego hacer clic en el botón "Suscribirse" para suscribirse a él).
6. De forma predeterminada, el servidor expondrá un archivo llamado watched.txt en src/mcp_observer_server/watched.txt (el archivo es .gitignored, por lo que debe crearlo), pero también puede suscribirse a otros archivos. Puede suscribirse a este archivo con la herramienta subscribe_default .
7. Modifique el archivo watched.txt (o el archivo al que se haya suscrito) y debería aparecer una notificación del servidor en el panel inferior derecho del Inspector. Este es el POC establecido.

VISUALIZACIÓN DE DEMOSTRACIÓN

1. Inicie el servidor y conéctese con Inspector:
2. Enumere los recursos predeterminados:
3. Enumere las herramientas:
4. Suscríbete al archivo predeterminado:
5. Modificar el archivo:
6. Ver aparecer la notificación:

🎉

Descripción del servidor

El servidor MCP Observer rastrea los cambios en archivos y directorios de su sistema, lo que permite a los clientes MCP suscribirse a estos eventos y tomar medidas cuando se crean, modifican, eliminan o mueven archivos (la demostración actual gestiona eventos de modificación). Este servidor implementa la especificación completa del Protocolo de Contexto de Modelo, que proporciona:

• Monitoreo de archivos en tiempo real : uso de la biblioteca Watchdog para una observación eficiente del sistema de archivos
• Gestión de suscripciones : cree, enumere y cancele suscripciones de monitoreo para cualquier ruta
• Historial de cambios : mantiene un registro de los cambios recientes para cada suscripción (omitido en la demostración)
• Acceso a archivos y directorios : lea el contenido de los archivos y los listados de directorios a través de los recursos de MCP
• Diseño sin estado : los clientes controlan lo que sucede en respuesta a los cambios de archivos

Características principales

• Suscribirse a cambios en archivos específicos, directorios o repositorios completos
• Filtrar eventos por patrones de archivos o tipos de eventos (omitido en la demostración)
• Consultar cambios recientes para ver qué archivos se vieron afectados (omitido en la demostración)
• Acceda al contenido de los archivos a través de los puntos finales de recursos
• Implementación ligera y eficiente con dependencias mínimas
• Integración sencilla con cualquier cliente compatible con MCP (...que admita suscripciones de recursos)

Aplicaciones prácticas

El principal problema que intento resolver es que, a menos que Claude Code, por ejemplo, toque un archivo y escriba el cambio, no tiene ni idea de lo que ocurre en tu repositorio/proyecto. (¿Conoces esas notificaciones de "Archivo modificado desde la última lectura"?). Tener un cliente o asistente de programación que supervise lo que haces en tu proyecto, sin tener que delegarle todas las tareas a Claude solo para que sepa que suceden, me parece tremendamente útil. Algunas aplicaciones prácticas incluyen:

• Actualizaciones automatizadas de la documentación : mantenga la documentación sincronizada con los cambios de código: usted actualiza algún código, Claude recibe una notificación del cambio y verifica o actualiza de forma proactiva las cadenas de documentación, etc.
• Revisiones de código en vivo : obtenga comentarios en tiempo real sobre los cambios de código mientras trabaja, detectando errores ortográficos, errores tipográficos, etc., brindando asesoramiento, verdadera programación en pares.
• Automatización de pruebas : ejecute pruebas cuando se modifiquen los archivos relevantes.
• Asistencia de IA : habilite las herramientas de IA para responder automáticamente a los cambios de archivos.
• Automatización de commits en Git : ¿Olvidas realizar commits con suficiente frecuencia? Claude puede supervisar tus cambios y sugerir (o realizar) acciones de commit con mayor frecuencia.

Diseño de implementación actual

La implementación del servidor presenta una arquitectura optimizada que prioriza la simplicidad, la confiabilidad y la facilidad de mantenimiento.

Aspectos destacados de la arquitectura

1. Estructura simplificada
   • Implementación enfocada (~170 líneas de código)
   • Funcionalidad consolidada en un pequeño conjunto de componentes principales
   • Diseño limpio basado en funciones que aprovecha directamente el SDK de MCP
   • Alta legibilidad y facilidad de mantenimiento
2. Gestión eficiente del Estado
   • La estructura de diccionario simple asigna rutas a las sesiones del cliente
   • Utiliza un diccionario watched para el mapeo directo de ruta a sesión
   • Seguimiento de estado mínimo con flujo de datos claro
   • Evita estructuras de datos redundantes
3. Integración del protocolo MCP
   • Uso directo de los decoradores de funciones del SDK de MCP
   • Manejo limpio de URI de recursos
   • Inicialización simplificada del servidor con configuración de capacidad adecuada
   • Sistema de entrega de notificaciones directas
4. Procesamiento de eventos
   • Implementación optimizada del controlador de eventos Watchdog
   • Ruta directa de evento a notificación
   • Comunicación segura para subprocesos mediante call_soon_threadsafe
   • Filtrado eficiente de eventos
5. Sistema de notificación
   • Uso directo de primitivas de notificación MCP
   • Entrega confiable con manejo adecuado de errores
   • Manejo preciso de marcas de tiempo UTC
   • Formato de URI limpio

Componentes principales

1. Estructura de datos
   • Un único diccionario global watched asigna objetos de ruta a conjuntos de objetos ServerSession
   • Cada entrada de ruta contiene el conjunto de sesiones suscritas a esa ruta
2. API de herramientas
   • Dos herramientas esenciales: subscribe y unsubscribe
   • Parámetro de ruta simple para una gestión de suscripciones sencilla
   • Manejo limpio de errores y validación de rutas
3. Manejo de recursos
   • URI de archivos expuestos directamente a través del listado de recursos
   • Resolución y validación de rutas
   • Lectura de contenido de texto para archivos
4. Procesamiento de eventos
   • La clase Watcher extiende FileSystemEventHandler
   • Procesa eventos modificados directamente
   • Envío de notificaciones seguro para subprocesos
   • Manejo de la relatividad de trayectorias para trayectorias anidadas
5. Entrega de notificaciones
   • Creación y envío de ServerNotification
   • Metadatos de eventos con marcas de tiempo
   • Formato de URI limpio

La implementación logra un buen equilibrio entre funcionalidad y simplicidad, lo que da como resultado una base de código confiable y fácil de mantener.