MCP Observer Server
mcp-オブザーバーサーバー
mcp-observer-serverファイルシステムのイベントを監視し、MCPクライアントにリアルタイム通知を提供するMCP(Model Context Protocol)サーバーです。これは、ローカルファイルシステムとAIアシスタント(例えば、クロードインスペクターにより、ファイルの変更に自動的に対応できるようになります。
**注:**これは私が現在開発中のファイル監視MCPサーバーのデモ/POCです。この件に関して多くの質問、コメント、問題、議論をいただいているため、私のアプローチを共有するために、この最小限の実装を投稿することにしました。
コンテクスト
MCPプロトコルはリソースサブスクリプションの概念を定義します。クライアントはリソースへの変更があった場合に通知を要求でき、サーバーは通知を送信するかどうかを選択できます。フロー図を以下に示します。

プロトコルでは、クライアントは変更内容を読み取るためにサーバーに読み取りリクエストを返すように指定されています(ちなみに、これらはすべてオプションです)。しかし、これは少し面倒で、余分なやり取りが必要になるため、リソース更新通知にも変更内容を記述してもらいたいと考えています。幸い、SDKにはmeta / _metaフィールドが用意されているので、ほぼ何でも送信できます。変更された行数や変更点の差分など、送信したい情報も送信できます。このデモではそれを実装しておらず、今はタイムスタンプのみを送信しています(最小限のPOCを除いて、サーバーからすべて削除しました)。また、stdioトランスポートで実行されているだけで、特別な処理は施していません。
注意!まだ「本物の」MCPクライアントでテストしていません。私の理解では、リソースサブスクリプションはオプションなので、ほとんどのビュークライアントが実際にサポートしているはずです。しかし、幸いなことにInspectorは非常に優れたクライアントなので、このサーバーをテストするのに使用できます。
デモの手順:
リポジトリをクローンします。
uv(または、他の方法) を使用して依存関係をインストールします。make start(uvを使用) を使用してサーバーを実行するか、npx @modelcontextprotocol/inspector uv run src/mcp_observer_server/server.py実行します。Inspector クライアントを開き、stdio を使用して接続します。構成は必要ありません。
subscribeツールを使用して、ディレクトリまたはファイルを監視します (または、「リソースの一覧表示」を実行し、リソースをクリックして、「サブスクライブ」ボタンをクリックしてサブスクライブすることもできます)。デフォルトでは、サーバーは
src/mcp_observer_server/watched.txtにwatched.txtというファイルを公開します(このファイルは .gitignored なので、作成する必要があります)。ただし、他のファイルも購読できます。このファイルはsubscribe_defaultツールを使って購読できます。watched.txtファイル(またはサブスクライブしたファイル)を変更すると、インスペクターの右下パネルにサーバー通知が表示されます。これで POC が確立されました。
Related MCP server: File MCP Server
デモの視覚化
サーバーを起動し、Inspector で接続します。

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

ツールをリストします:

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

ファイルを変更します:

通知が表示されます:

🎉
サーバーの説明
MCP Observer Serverはシステム上のファイルとディレクトリの変更を追跡し、MCPクライアントがこれらのイベントをサブスクライブして、ファイルの作成、変更、削除、または移動時にアクションを実行できるようにします(現在のデモでは変更イベントを処理します)。このサーバーは、モデルコンテキストプロトコル仕様を完全に実装しており、以下を提供します。
リアルタイムファイル監視: Watchdogライブラリを使用した効率的なファイルシステム監視
サブスクリプション管理: 任意のパスの監視サブスクリプションを作成、一覧表示、キャンセルします
変更履歴: 各サブスクリプションの最近の変更のログを保持します (デモでは省略)
ファイルとディレクトリのアクセス: MCP リソースを通じてファイルの内容とディレクトリの一覧を読み取ります
ステートレス設計: クライアントはファイルの変更に応じて何が起こるかを制御します
主な特徴
特定のファイル、ディレクトリ、またはリポジトリ全体の変更を購読する
ファイルパターンまたはイベントタイプでイベントをフィルタリングする(デモでは省略)
最近の変更を照会して、影響を受けたファイルを確認します(デモでは省略)
リソースエンドポイント経由でファイルの内容にアクセスする
最小限の依存関係で軽量かつ効率的な実装
MCP 互換クライアント(リソース サブスクリプションをサポートするもの)とのシンプルな統合
実用的な応用
私が解決しようとしている主な問題点は、例えばClaude Codeがファイルにアクセスして変更内容をそのファイルに書き込まない限り、リポジトリ/プロジェクトで何が起こっているのか全く把握できないことです。(「前回の読み取り以降にファイルが変更されました」という通知をご存知ですか?)プロジェクトで実際に何をしているかを監視してくれるクライアントやコーディングアシスタントがあれば、Claudeにタスクの発生を知らせるためだけにすべてのタスクを委任する必要がなくなり、非常に便利に思えます。具体的な応用例を以下に示します。
自動化されたドキュメント更新: コードの変更とドキュメントの同期を維持します。コードを更新すると、Claude に変更が通知され、ドキュメント文字列などが積極的にチェックまたは更新されます。
ライブ コード レビュー: 作業中にコードの変更に関するフィードバックをリアルタイムで取得し、スペル エラーや入力エラーなどを検出してアドバイスを提供し、真のペア プログラミングを実現します。
テストの自動化: 関連するファイルが変更されたときにテストを実行します。
AI アシスタンス: AI ツールを有効にして、ファイルの変更に自動的に応答します。
Git コミット自動化: コミットを頻繁に忘れていませんか? Claude は変更を監視し、より頻繁にコミットアクションを提案 (または実行) します。
現在の実装設計
サーバーの実装は、シンプルさ、信頼性、保守性を重視した合理化されたアーキテクチャを特徴としています。
建築のハイライト
簡素化された構造
集中的な実装(コード約170行)
機能を少数のコアコンポーネントに統合
MCP SDKを直接活用するクリーンな関数ベースの設計
高い可読性と保守性
効率的な状態管理
シンプルな辞書構造がパスをクライアントセッションにマッピングします
watched辞書を使用して、パスからセッションへの直接マッピングを行う明確なデータフローによる最小限の状態追跡
冗長なデータ構造を回避する
MCPプロトコル統合
MCP SDK 関数デコレータの直接使用
クリーンなリソースURI処理
適切な機能構成による簡素化されたサーバー初期化
直接通知配信システム
イベント処理
合理化されたウォッチドッグイベントハンドラーの実装
イベントから通知への直接パス
call_soon_threadsafeによるスレッドセーフな通信効率的なイベントフィルタリング
通知システム
MCP通知プリミティブの直接使用
適切なエラー処理による信頼性の高い配信
正確なUTCタイムスタンプ処理
クリーンなURIフォーマット
コアコンポーネント
データ構造
watched対象の単一のグローバル辞書は、Path オブジェクトを ServerSession オブジェクトのセットにマッピングします。各パスエントリには、そのパスにサブスクライブされているセッションのセットが含まれます。
ツールAPI
2つの必須ツール:
subscribeとunsubscribe簡単なサブスクリプション管理のためのシンプルなパスパラメータ
クリーンなエラー処理とパス検証
リソースハンドリング
リソースリストを通じて直接公開されるファイル URI
パス解決と検証
ファイルのテキストコンテンツの読み取り
イベント処理
WatcherクラスはFileSystemEventHandlerを拡張します
変更されたイベントを直接処理します
スレッドセーフな通知ディスパッチ
ネストされたパスのパス相対処理
通知配信
ServerNotificationの作成と送信
タイムスタンプ付きイベントメタデータ
クリーンなURIフォーマット
この実装により、機能性とシンプルさのバランスが適切に保たれ、信頼性が高く保守しやすいコードベースが実現します。
Available Tools
4 toolslist_watchedA
List all currently monitored paths and their subscriber counts
Inputs: no named parameters.
subscribeC
Subscribe to changes on a file or directory
Inputs: path (required).
subscribe_defaultB
Subscribe to the default watched.txt file for development
Inputs: no named parameters.
unsubscribeC
Unsubscribe from changes on a file or directory
Inputs: path (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose with no overlap: list_watched for viewing current subscriptions, subscribe for adding new ones, subscribe_default for a specific default case, and unsubscribe for removal. The descriptions reinforce these distinct roles, making misselection unlikely.
All tools follow a consistent verb_noun pattern (list_watched, subscribe, subscribe_default, unsubscribe) with clear, action-oriented names. The naming is uniform and predictable, enhancing usability.
With 4 tools, this server is well-scoped for its purpose of monitoring file/directory changes. Each tool serves a necessary function in the subscription lifecycle, and the count is neither too sparse nor bloated.
The tool set provides complete coverage for the domain of file/directory monitoring: list (read), subscribe (create), unsubscribe (delete), and a specialized subscribe_default for convenience. There are no obvious gaps, supporting full agent workflows.
Maintenance
Related MCP Connectors
A real-time, multiplayer filesystem for agents and humans: shared files, live edits, history.
Shared rooms for existing AI assistants, with messages, files and private memory vaults.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
AI-native website, RSS, and API monitoring with MCP change events and alerts.
Related MCP Servers
- AlicenseAqualityDmaintenanceA Model Context Protocol server that provides AI agents with secure access to local filesystem operations, enabling reading, writing, and managing files through a standardized interface.1082 npm55Apache 2.0
- AlicenseAqualityDmaintenanceA Model Context Protocol (MCP) server that enables AI assistants to perform comprehensive file operations including finding, reading, writing, editing, searching, moving, and copying files with security validations.71MIT
- AlicenseNot gradedqualityDmaintenanceA secure file server for AI assistants that provides comprehensive file operations and text manipulation with configurable access levels and multiple connection modes.6MIT
- FlicenseNot gradedqualityDmaintenanceA secure, sandboxed file system server that enables reading, writing, searching, and managing files through MCP-compatible AI clients with path traversal protection and size limits.-