mcp-observer-server

mcp-observer-server ist ein MCP-Server (Model Context Protocol), der Dateisystemereignisse überwacht und Echtzeitbenachrichtigungen an MCP-Clients sendet. Er fungiert als (bidirektionalere) Brücke zwischen Ihrem lokalen Dateisystem und KI-Assistenten wie Claude Inspector, sodass sie automatisch auf Dateiänderungen reagieren können.

HINWEIS: Dies ist eine Demo/ein POC eines MCP-Servers zur Dateiüberwachung, an dem ich arbeite. Ich sehe viele Fragen/Kommentare/Probleme/Diskussionen zu diesem Thema, daher möchte ich diese minimale Implementierung veröffentlichen, um meinen Ansatz zu teilen.

Kontext

Das MCP-Protokoll definiert das Konzept eines Ressourcenabonnements. Dabei kann ein Client Benachrichtigungen über Änderungen an einer Ressource anfordern und der Server kann Benachrichtigungen senden. Hier ist das Flussdiagramm:

Das Protokoll besagt, dass der Client anschließend eine Lese-Anfrage an den Server zurücksenden soll, um die Änderungen zu lesen. (All dies ist übrigens optional). Ich finde das jedoch etwas umständlich und es erfordert einen zusätzlichen Aufwand. Außerdem möchte ich, dass meine Ressourcenaktualisierungsbenachrichtigung die Änderung auch beschreibt. Glücklicherweise bietet das SDK ein meta / _meta -Feld, sodass man praktisch alles senden kann, was man möchte. So könnte ich beispielsweise die Anzahl der geänderten Zeilen, einen Diff der Änderungen oder sonst etwas senden. Das habe ich in dieser Demo nicht implementiert, ich sende derzeit nur den Zeitstempel. (Ich habe im Grunde alles vom Server entfernt, außer dem minimalen POC.) Außerdem läuft es nur über Standard-Transport, nichts Besonderes.

HINWEIS!!! Ich habe dies noch nicht mit echten MCP-Clients getestet. Meines Wissens unterstützen viele View-Clients Ressourcenabonnements, da diese ohnehin optional sind. Glücklicherweise ist Inspector jedoch ein sehr guter Client, mit dem Sie diesen Server testen können.

DEMO-ANLEITUNG:

1. Klonen Sie das Repository.

2. Installieren Sie die Abhängigkeiten mit uv (oder, ich nehme an, auf eine andere Weise).

3. Führen Sie den Server mit make start (verwendet uv ) aus oder führen Sie npx @modelcontextprotocol/inspector uv run src/mcp_observer_server/server.py .

4. Öffnen Sie den Inspector-Client und stellen Sie eine Verbindung über stdio her. Es ist keine Konfiguration erforderlich.

5. Verwenden Sie das subscribe , um ein Verzeichnis oder eine Datei zu überwachen (alternativ können Sie „Ressourcen auflisten“ ausführen, auf eine Ressource klicken und dann auf die Schaltfläche „Abonnieren“ klicken, um sie zu abonnieren).

6. Standardmäßig stellt der Server eine Datei namens watched.txt in src/mcp_observer_server/watched.txt bereit (die Datei hat die Erweiterung .gitignored, Sie müssen sie also erstellen). Sie können aber auch andere Dateien abonnieren. Sie können diese Datei mit dem Tool subscribe_default abonnieren.

7. Ändern Sie die Datei watched.txt (oder die Datei, die Sie abonniert haben). Daraufhin sollte unten rechts im Inspector eine Serverbenachrichtigung angezeigt werden. Dies ist der etablierte POC.

DEMO-VISUALISIERUNG

1. Starten Sie den Server und stellen Sie eine Verbindung mit Inspector her:

2. Listen Sie die Standardressourcen auf:

3. Listen Sie die Werkzeuge auf:

4. Abonnieren Sie die Standarddatei:

5. Ändern Sie die Datei:

6. Sehen Sie, wie die Benachrichtigung angezeigt wird:

🎉

Serverbeschreibung

Der MCP Observer Server verfolgt Datei- und Verzeichnisänderungen auf Ihrem System. MCP-Clients können diese Ereignisse abonnieren und beim Erstellen, Ändern, Löschen oder Verschieben von Dateien reagieren (die aktuelle Demo behandelt Änderungsereignisse). Dieser Server implementiert die vollständige Model Context Protocol-Spezifikation und bietet:

• Echtzeit-Dateiüberwachung : Verwenden der Watchdog-Bibliothek zur effizienten Überwachung des Dateisystems

• Abonnementverwaltung : Erstellen, Auflisten und Abbrechen von Überwachungsabonnements für jeden Pfad

• Änderungsverlauf : Führt ein Protokoll der letzten Änderungen für jedes Abonnement (in der Demo weggelassen)

• Datei- und Verzeichniszugriff : Lesen Sie Dateiinhalte und Verzeichnislisten über MCP-Ressourcen

• Zustandsloses Design : Clients steuern, was als Reaktion auf Dateiänderungen geschieht

Hauptmerkmale

• Abonnieren Sie Änderungen an bestimmten Dateien, Verzeichnissen oder ganzen Repositories

• Ereignisse nach Dateimustern oder Ereignistypen filtern (in der Demo weggelassen)

• Abfrage der letzten Änderungen, um zu sehen, welche Dateien betroffen waren (in der Demo weggelassen)

• Zugriff auf Dateiinhalte über Ressourcenendpunkte

• Leichtgewichtige und effiziente Implementierung mit minimalen Abhängigkeiten

• Einfache Integration mit jedem MCP-kompatiblen Client (... der Ressourcenabonnements unterstützt)

Praktische Anwendungen

Das Hauptproblem, das ich lösen möchte, ist, dass Claude Code keine Ahnung hat, was in Ihrem Repository/Projekt passiert, es sei denn, er bearbeitet beispielsweise eine Datei und schreibt die Änderung selbst hinein. (Kennen Sie diese Benachrichtigungen – „Datei seit dem letzten Lesen geändert“?) Ein Client oder Programmierassistent, der Ihre Projektaktivitäten tatsächlich überwacht, und Sie müssen nicht jede Aufgabe an Claude delegieren, nur damit er weiß, dass sie ausgeführt wird, erscheint mir äußerst nützlich. Einige praktische Anwendungen sind:

• Automatische Dokumentationsaktualisierungen : Halten Sie die Dokumentation mit Codeänderungen synchron – Sie aktualisieren Code, Claude wird über die Änderung benachrichtigt und prüft oder aktualisiert proaktiv die Dokumentzeichenfolgen usw.

• Live-Codeüberprüfungen : Erhalten Sie während der Arbeit Echtzeit-Feedback zu Codeänderungen, erkennen Sie Rechtschreibfehler, Tippfehler usw. und geben Sie Ratschläge – echte Paarprogrammierung.

• Testautomatisierung : Führen Sie Tests aus, wenn relevante Dateien geändert werden.

• KI-Unterstützung : Aktivieren Sie KI-Tools, um automatisch auf Dateiänderungen zu reagieren.

• Git-Commit-Automatisierung : Vergessen Sie, häufig genug zu committen? Claude kann Ihre Änderungen überwachen und Commit-Aktionen häufiger vorschlagen (oder durchführen).

Aktuelles Implementierungsdesign

Die Serverimplementierung zeichnet sich durch eine optimierte Architektur aus, bei der Einfachheit, Zuverlässigkeit und Wartbarkeit im Vordergrund stehen.

Architektur-Highlights

1. Vereinfachte Struktur

   • Fokussierte Implementierung (~170 Zeilen Code)

   • Konsolidierte Funktionalität in einem kleinen Satz von Kernkomponenten

   • Sauberes, funktionsbasiertes Design, das das MCP SDK direkt nutzt

   • Hohe Lesbarkeit und Wartbarkeit

2. Effizientes Zustandsmanagement

   • Einfache Wörterbuchstruktur ordnet Pfade Clientsitzungen zu

   • Verwendet ein watched Wörterbuch für die direkte Pfad-zu-Sitzungszuordnung

   • Minimale Zustandsverfolgung mit klarem Datenfluss

   • Vermeidet redundante Datenstrukturen

3. MCP-Protokollintegration

   • Direkte Verwendung von MCP SDK-Funktionsdekoratoren

   • Saubere Handhabung von Ressourcen-URIs

   • Vereinfachte Serverinitialisierung mit entsprechender Funktionskonfiguration

   • Direktes Benachrichtigungsübermittlungssystem

4. Ereignisverarbeitung

   • Optimierte Implementierung des Watchdog-Ereignishandlers

   • Direkter Ereignis-zu-Benachrichtigungspfad

   • Threadsichere Kommunikation über call_soon_threadsafe

   • Effiziente Ereignisfilterung

5. Benachrichtigungssystem

   • Direkte Verwendung von MCP-Benachrichtigungsprimitiven

   • Zuverlässige Lieferung mit ordnungsgemäßer Fehlerbehandlung

   • Genaue Handhabung von UTC-Zeitstempeln

   • Saubere URI-Formatierung

Kernkomponenten

1. Datenstruktur

   • Ein einzelnes globales Wörterbuch watched Path-Objekte Sätzen von ServerSession-Objekten zu.

   • Jeder Pfadeintrag enthält die Anzahl der Sitzungen, die für diesen Pfad abonniert sind.

2. Tool-API

   • Zwei wesentliche Tools: subscribe und unsubscribe

   • Einfacher Pfadparameter für unkomplizierte Abonnementverwaltung

   • Saubere Fehlerbehandlung und Pfadvalidierung

3. Ressourcenverwaltung

   • Datei-URIs werden direkt über die Ressourcenliste angezeigt

   • Pfadauflösung und -validierung

   • Lesen von Textinhalten für Dateien

4. Ereignisverarbeitung

   • Die Watcher-Klasse erweitert FileSystemEventHandler

   • Verarbeitet geänderte Ereignisse direkt

   • Threadsicheres Versenden von Benachrichtigungen

   • Pfadrelativitätsbehandlung für verschachtelte Pfade

5. Benachrichtigungsübermittlung

   • Erstellen und Senden von ServerBenachrichtigungen

   • Ereignismetadaten mit Zeitstempeln

   • Saubere URI-Formatierung

Die Implementierung erreicht ein gutes Gleichgewicht zwischen Funktionalität und Einfachheit, was zu einer zuverlässigen und wartbaren Codebasis führt.