mcp-オブザーバーサーバー

mcp-observer-serverファイルシステムのイベントを監視し、MCPクライアントにリアルタイム通知を提供するMCP（Model Context Protocol）サーバーです。これは、ローカルファイルシステムとAIアシスタント（例えば、クロードインスペクターにより、ファイルの変更に自動的に対応できるようになります。

**注：**これは私が現在開発中のファイル監視MCPサーバーのデモ/POCです。この件に関して多くの質問、コメント、問題、議論をいただいているため、私のアプローチを共有するために、この最小限の実装を投稿することにしました。

コンテクスト

MCPプロトコルはリソースサブスクリプションの概念を定義します。クライアントはリソースへの変更があった場合に通知を要求でき、サーバーは通知を送信するかどうかを選択できます。フロー図を以下に示します。

プロトコルでは、クライアントは変更内容を読み取るためにサーバーに読み取りリクエストを返すように指定されています（ちなみに、これらはすべてオプションです）。しかし、これは少し面倒で、余分なやり取りが必要になるため、リソース更新通知にも変更内容を記述してもらいたいと考えています。幸い、SDKにはmeta / _metaフィールドが用意されているので、ほぼ何でも送信できます。変更された行数や変更点の差分など、送信したい情報も送信できます。このデモではそれを実装しておらず、今はタイムスタンプのみを送信しています（最小限のPOCを除いて、サーバーからすべて削除しました）。また、stdioトランスポートで実行されているだけで、特別な処理は施していません。

注意！非常に優れたクライアントなので、このサーバーをテストするのに使用できます。

デモの手順:

1. リポジトリをクローンします。

2. uv (または、他の方法) を使用して依存関係をインストールします。

3. make start ( uvを使用) を使用してサーバーを実行するか、 npx @modelcontextprotocol/inspector uv run src/mcp_observer_server/server.py実行します。

4. Inspector クライアントを開き、stdio を使用して接続します。構成は必要ありません。

5. subscribeツールを使用して、ディレクトリまたはファイルを監視します (または、「リソースの一覧表示」を実行し、リソースをクリックして、「サブスクライブ」ボタンをクリックしてサブスクライブすることもできます)。

6. デフォルトでは、サーバーはsrc/mcp_observer_server/watched.txtにwatched.txtというファイルを公開します（このファイルは .gitignored なので、作成する必要があります）。ただし、他のファイルも購読できます。このファイルはsubscribe_defaultツールを使って購読できます。

7. watched.txtファイル（またはサブスクライブしたファイル）を変更すると、インスペクターの右下パネルにサーバー通知が表示されます。これで POC が確立されました。

デモの視覚化

1. サーバーを起動し、Inspector で接続します。

2. デフォルトのリソースを一覧表示します。

3. ツールをリストします:

4. デフォルトのファイルをサブスクライブします:

5. ファイルを変更します:

6. 通知が表示されます:

🎉

サーバーの説明

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

• リアルタイムファイル監視: Watchdogライブラリを使用した効率的なファイルシステム監視

• サブスクリプション管理: 任意のパスの監視サブスクリプションを作成、一覧表示、キャンセルします

• 変更履歴: 各サブスクリプションの最近の変更のログを保持します (デモでは省略)

• ファイルとディレクトリのアクセス: MCP リソースを通じてファイルの内容とディレクトリの一覧を読み取ります

• ステートレス設計: クライアントはファイルの変更に応じて何が起こるかを制御します

主な特徴

• 特定のファイル、ディレクトリ、またはリポジトリ全体の変更を購読する

• ファイルパターンまたはイベントタイプでイベントをフィルタリングする（デモでは省略）

• 最近の変更を照会して、影響を受けたファイルを確認します（デモでは省略）

• リソースエンドポイント経由でファイルの内容にアクセスする

• 最小限の依存関係で軽量かつ効率的な実装

• MCP 互換クライアント（リソース サブスクリプションをサポートするもの）とのシンプルな統合

実用的な応用

私が解決しようとしている主な問題点は、例えばClaude Codeがファイルにアクセスして変更内容をそのファイルに書き込まない限り、リポジトリ/プロジェクトで何が起こっているのか全く把握できないことです。（「前回の読み取り以降にファイルが変更されました」という通知をご存知ですか？）プロジェクトで実際に何をしているかを監視してくれるクライアントやコーディングアシスタントがあれば、Claudeにタスクの発生を知らせるためだけにすべてのタスクを委任する必要がなくなり、非常に便利に思えます。具体的な応用例を以下に示します。

• 自動化されたドキュメント更新: コードの変更とドキュメントの同期を維持します。コードを更新すると、Claude に変更が通知され、ドキュメント文字列などが積極的にチェックまたは更新されます。

• ライブ コード レビュー: 作業中にコードの変更に関するフィードバックをリアルタイムで取得し、スペル エラーや入力エラーなどを検出してアドバイスを提供し、真のペア プログラミングを実現します。

• テストの自動化: 関連するファイルが変更されたときにテストを実行します。

• AI アシスタンス: AI ツールを有効にして、ファイルの変更に自動的に応答します。

• Git コミット自動化: コミットを頻繁に忘れていませんか? Claude は変更を監視し、より頻繁にコミットアクションを提案 (または実行) します。

現在の実装設計

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

建築のハイライト

1. 簡素化された構造

   • 集中的な実装（コード約170行）

   • 機能を少数のコアコンポーネントに統合

   • MCP SDKを直接活用するクリーンな関数ベースの設計

   • 高い可読性と保守性

2. 効率的な状態管理

   • シンプルな辞書構造がパスをクライアントセッションにマッピングします

   • watched辞書を使用して、パスからセッションへの直接マッピングを行う

   • 明確なデータフローによる最小限の状態追跡

   • 冗長なデータ構造を回避する

3. MCPプロトコル統合

   • MCP SDK 関数デコレータの直接使用

   • クリーンなリソースURI処理

   • 適切な機能構成による簡素化されたサーバー初期化

   • 直接通知配信システム

4. イベント処理

   • 合理化されたウォッチドッグイベントハンドラーの実装

   • イベントから通知への直接パス

   • call_soon_threadsafeによるスレッドセーフな通信

   • 効率的なイベントフィルタリング

5. 通知システム

   • MCP通知プリミティブの直接使用

   • 適切なエラー処理による信頼性の高い配信

   • 正確なUTCタイムスタンプ処理

   • クリーンなURIフォーマット

コアコンポーネント

1. データ構造

   • watched対象の単一のグローバル辞書は、Path オブジェクトを ServerSession オブジェクトのセットにマッピングします。

   • 各パスエントリには、そのパスにサブスクライブされているセッションのセットが含まれます。

2. ツールAPI

   • 2つの必須ツール： subscribeとunsubscribe

   • 簡単なサブスクリプション管理のためのシンプルなパスパラメータ

   • クリーンなエラー処理とパス検証

3. リソースハンドリング

   • リソースリストを通じて直接公開されるファイル URI

   • パス解決と検証

   • ファイルのテキストコンテンツの読み取り

4. イベント処理

   • WatcherクラスはFileSystemEventHandlerを拡張します

   • 変更されたイベントを直接処理します

   • スレッドセーフな通知ディスパッチ

   • ネストされたパスのパス相対処理

5. 通知配信

   • ServerNotificationの作成と送信

   • タイムスタンプ付きイベントメタデータ

   • クリーンなURIフォーマット

この実装により、機能性とシンプルさのバランスが適切に保たれ、信頼性が高く保守しやすいコードベースが実現します。