MCP Observer Server

🚀 mcp-observer-server

mcp-observer-server は、ファイルシステムイベントを監視し、MCPクライアントにリアルタイム通知を提供するMCP（Model Context Protocol）サーバーです。これは、ローカルファイルシステムとClaude InspectorのようなAIアシスタントとの間の（より双方向的な）橋渡し役として機能し、ファイルの変更に自動的に対応できるようにします。

⚠️ 重要提示

これは私が開発中のファイル監視MCPサーバーのデモ/POCです。このようなものに関する多くの質問やコメント、Issue、Discussionがあるので、この最小限の実装を公開して自分のアプローチを共有したいと思いました。

🚀 クイックスタート

デモの手順

1. リポジトリをクローンします。
2. uv を使用して依存関係をインストールします（または、他の方法でも可能です）。
3. make start を使用してサーバーを起動します（uv を使用）、または npx @modelcontextprotocol/inspector uv run src/mcp_observer_server/server.py を実行します。
4. Inspectorクライアントを開き、stdioを使用して接続します。設定は必要ありません。
5. subscribe ツールを使用してディレクトリまたはファイルを監視します（または、「List Resources」を実行し、リソースをクリックしてから「Subscribe」ボタンをクリックしてサブスクライブすることもできます）。
6. デフォルトでは、サーバーは src/mcp_observer_server/watched.txt にある watched.txt というファイルを公開します（このファイルは.gitignoredされているので、自分で作成する必要があります）が、他のファイルにもサブスクライブできます。 subscribe_default ツールを使用してこのファイルにサブスクライブできます。
7. watched.txt ファイル（またはサブスクライブした任意のファイル）を変更すると、Inspectorの右下のパネルにサーバー通知が表示されます。これでPOCが確立されました。

✨ 主な機能

サーバーの概要

MCP Observer Serverは、システム上のファイルとディレクトリの変更を追跡し、MCPクライアントがこれらのイベントをサブスクライブし、ファイルが作成、変更、削除、または移動されたときにアクションを実行できるようにします（現在のデモでは変更イベントのみを処理しています）。このサーバーは、完全なModel Context Protocol仕様を実装しており、以下の機能を提供します。

• リアルタイムファイル監視：Watchdogライブラリを使用して効率的なファイルシステム監視を行います。
• サブスクリプション管理：任意のパスに対する監視サブスクリプションの作成、一覧表示、およびキャンセルができます。
• 変更履歴：各サブスクリプションの最近の変更履歴を保持します（デモでは省略されています）。
• ファイルおよびディレクトリアクセス：MCPリソースを介してファイルの内容とディレクトリの一覧を読み取ることができます。
• ステートレス設計：クライアントがファイルの変更に応じて何をするかを制御します。

主要機能

• 特定のファイル、ディレクトリ、またはリポジトリ全体の変更をサブスクライブできます。
• ファイルパターンまたはイベントタイプでイベントをフィルタリングできます（デモでは省略されています）。
• 最近の変更をクエリして、どのファイルが影響を受けたかを確認できます（デモでは省略されています）。
• リソースエンドポイントを介してファイルの内容にアクセスできます。
• 軽量で効率的な実装で、最小限の依存関係です。
• 任意のMCP互換クライアント（リソースサブスクリプションをサポートするもの）と簡単に統合できます。

実用的なアプリケーション

私が解決しようとしている主な問題は、例えばClaude Codeがファイルに触れて変更を書き込まない限り、リポジトリ/プロジェクトで何が起こっているかを知らないことです。（「前回の読み取り以来ファイルが変更されました」という通知がありますよね？）実際にプロジェクトで自分が何をしているかを監視し、Claudeにすべてのタスクを委任しなくても何が起こっているかを知ることができるクライアントまたはコーディングアシスタントは、私にとって非常に有用です。いくつかの実用的なアプリケーションは以下の通りです。

• 自動ドキュメント更新：コードの変更にドキュメントを同期させます。コードを更新すると、Claudeに変更が通知され、自動的にdoc-stringなどをチェックまたは更新します。
• ライブコードレビュー：作業中にコードの変更に対するリアルタイムのフィードバックを得ることができます。スペルミス、型エラーなどを検出し、アドバイスを与え、本当のペアプログラミングを実現します。
• テスト自動化：関連するファイルが変更されたときにテストを実行します。
• AIアシスタンス：AIツールがファイルの変更に自動的に応答できるようにします。
• Gitコミット自動化：頻繁にコミットするのを忘れませんか？Claudeが変更を監視し、より頻繁にコミットアクションを提案（または実行）することができます。

🔧 技術詳細

現在の実装設計

サーバーの実装は、シンプルさ、信頼性、および保守性を重視した合理化されたアーキテクチャを持っています。

アーキテクチャのハイライト

1. 簡素化された構造

   • 焦点を絞った実装（約170行のコード）
   • 機能を少数のコアコンポーネントに集約
   • MCP SDKを直接利用したクリーンな関数ベースの設計
   • 高い可読性と保守性

2. 効率的な状態管理

   • シンプルな辞書構造でパスをクライアントセッションにマッピング
   • watched 辞書を使用して直接パスからセッションへのマッピングを行う
   • 明確なデータフローで最小限の状態追跡
   • 冗長なデータ構造を避ける

3. MCPプロトコルの統合

   • MCP SDKの関数デコレータを直接使用
   • クリーンなリソースURIの処理
   • 適切な機能構成で簡素化されたサーバー初期化
   • 直接的な通知配信システム

4. イベント処理

   • 合理化されたWatchdogイベントハンドラの実装
   • 直接的なイベントから通知へのパス
   • call_soon_threadsafe を介したスレッドセーフな通信
   • 効率的なイベントフィルタリング

5. 通知システム

   • MCP通知プリミティブを直接使用
   • 適切なエラーハンドリングで信頼性の高い配信
   • 正確なUTCタイムスタンプの処理
   • クリーンなURIの書式設定

コアコンポーネント

1. データ構造

   • 単一のグローバル辞書 watched がPathオブジェクトをServerSessionオブジェクトのセットにマッピングします。
   • 各パスエントリには、そのパスにサブスクライブしているセッションのセットが含まれています。

2. ツールAPI

   • 2つの必須ツール：subscribe と unsubscribe
   • シンプルなパスパラメータで直感的なサブスクリプション管理
   • クリーンなエラーハンドリングとパスの検証

3. リソース処理

   • ファイルURIがリソースリストを通じて直接公開されます。
   • パスの解決と検証
   • ファイルのテキスト内容の読み取り

4. イベント処理

   • WatcherクラスがFileSystemEventHandlerを拡張します。
   • 変更されたイベントを直接処理します。
   • スレッドセーフな通知のディスパッチ
   • ネストされたパスの相対パス処理

5. 通知配信

   • サーバー通知の作成と送信
   • タイムスタンプ付きのイベントメタデータ
   • クリーンなURIの書式設定
   • 適切なエラーハンドリングで信頼性の高い配信

📚 ドキュメント

デモの可視化

1. サーバーを起動してInspectorと接続します：
2. デフォルトのリソースを一覧表示します：
3. ツールを一覧表示します：
4. デフォルトのファイルにサブスクライブします：
5. ファイルを変更します：
6. 通知が表示されるのを確認します：

🎉

⚠️ 重要注意

これを「本物の」MCPクライアントでテストしたことはありません - 私の理解では、リソースサブスクリプションはオプションなので、実際にサポートしているクライアントはほとんどありません。しかし、幸いなことに Inspector は非常に優れたクライアントであり、このサーバーをテストするために使用できます。