MCP Observer Server

🚀 mcp-observer-server

mcp-observer-server 是一個 MCP（模型上下文協議）服務器，它可以監控文件系統事件，並向 MCP 客戶端提供即時通知。它就像一個（更具雙向性的）橋樑，連接著你的本地文件系統和像 Claude Inspector 這樣的 AI 助手，使它們能夠自動響應文件的變化。

注意： 這是我正在開發的一個文件監控 MCP 服務器的演示/概念驗證。我看到很多關於這類東西的問題、評論、議題和討論，所以我想發佈這個最小化的實現，來分享我的方法。

🚀 快速開始

1. 克隆倉庫。
2. 使用 uv 安裝依賴（或者，我想也可以用其他方式）。
3. 使用 make start 運行服務器（使用 uv），或者運行 npx @modelcontextprotocol/inspector uv run src/mcp_observer_server/server.py。
4. 打開 Inspector 客戶端，通過標準輸入輸出進行連接，無需配置。
5. 使用 subscribe 工具監控目錄或文件（或者，你可以運行“列出資源”，點擊一個資源，然後點擊“訂閱”按鈕來訂閱它）。
6. 默認情況下，服務器會暴露一個名為 watched.txt 的文件，路徑為 src/mcp_observer_server/watched.txt（該文件已被添加到 .gitignore 中，所以你需要自己創建它），但你也可以訂閱其他文件。你可以使用 subscribe_default 工具訂閱這個文件。
7. 修改 watched.txt 文件（或者你訂閱的任何文件），你應該會在 Inspector 右下角的面板中看到服務器通知。這樣就完成了概念驗證。

✨ 主要特性

服務器功能概述

MCP 觀察者服務器可以跟蹤系統上的文件和目錄變化，允許 MCP 客戶端訂閱這些事件，並在文件被創建、修改、刪除或移動時採取行動（當前演示僅處理修改事件）。該服務器實現了完整的模型上下文協議規範，具備以下功能：

• 即時文件監控：使用 Watchdog 庫進行高效的文件系統觀察。
• 訂閱管理：為任何路徑創建、列出和取消監控訂閱。
• 更改歷史記錄：為每個訂閱維護最近更改的日誌（演示中省略）。
• 文件和目錄訪問：通過 MCP 資源讀取文件內容和目錄列表。
• 無狀態設計：客戶端控制對文件更改的響應操作。

關鍵特性

• 訂閱特定文件、目錄或整個倉庫的更改。
• 按文件模式或事件類型過濾事件（演示中省略）。
• 查詢最近的更改，瞭解哪些文件受到影響（演示中省略）。
• 通過資源端點訪問文件內容。
• 輕量級且高效的實現，依賴項極少。
• 可與任何兼容 MCP 的客戶端（支持資源訂閱的客戶端）輕鬆集成。

實際應用場景

我試圖解決的主要痛點是，除非像 Claude Code 這樣的工具自己觸及文件並將更改寫入其中，否則它對倉庫/項目中發生的事情一無所知。（你知道那些“自上次讀取以來文件已更改”的通知吧？）擁有一個能夠實際監控你在項目中操作的客戶端或編碼助手，而你不必將每個任務都委託給 Claude 讓它知道發生了什麼，在我看來非常有用。一些實際應用包括：

• 自動化文檔更新：使文檔與代碼更改保持同步——你更新了一些代碼，Claude 會收到更改通知，並主動檢查或更新文檔字符串等。
• 即時代碼審查：在你編寫代碼時獲得即時反饋，捕捉拼寫錯誤、類型錯誤等，提供建議，實現真正的結對編程。
• 測試自動化：當相關文件被修改時運行測試。
• AI 輔助：使 AI 工具能夠自動響應文件更改。
• Git 提交自動化：你是否經常忘記提交代碼？Claude 可以監控你的更改，並更頻繁地建議（或執行）提交操作。

📚 詳細文檔

上下文說明

MCP 協議定義了資源訂閱的概念，客戶端可以請求接收資源更改的通知，服務器可以選擇發送通知。以下是流程圖：

協議規定客戶端應向服務器發送讀取請求以讀取更改（順便說一下，所有這些都是可選的）。但我覺得這有點麻煩，還需要額外的交互，我更希望資源更新通知能同時描述更改內容。幸運的是，SDK 提供了 meta/_meta 字段，你幾乎可以發送任何你想要的內容。所以我可能想發送更改的行數、更改的差異，誰知道呢。在這個演示中我還沒有實現這些，目前我只是發送時間戳。（實際上我從服務器中移除了除最小概念驗證之外的所有內容。）此外，它只是在標準輸入輸出傳輸上運行，沒有什麼花哨的東西。

注意！！！ 我還沒有用任何“真正的”MCP 客戶端測試過這個——據我所知，很少有客戶端真正支持資源訂閱，因為這本來就是可選的。不過，幸運的是 Inspector 是一個非常好的客戶端，你可以用它來測試這個服務器。

演示可視化

1. 啟動服務器並與 Inspector 連接：
2. 列出默認資源：
3. 列出工具：
4. 訂閱默認文件：
5. 修改文件：
6. 查看通知出現：

🔧 技術細節

當前實現設計

服務器實現採用了精簡的架構，優先考慮簡單性、可靠性和可維護性。

架構亮點

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
   • 兩個基本工具：subscribe 和 unsubscribe。
   • 簡單的路徑參數，便於直接的訂閱管理。
   • 清晰的錯誤處理和路徑驗證。
3. 資源處理
   • 通過資源列表直接暴露文件 URI。
   • 路徑解析和驗證。
   • 讀取文件的文本內容。
4. 事件處理
   • Watcher 類繼承自 FileSystemEventHandler。
   • 直接處理修改事件。
   • 線程安全的通知分發。
   • 處理嵌套路徑的相對路徑。
5. 通知傳遞
   • 創建併發送 ServerNotification。
   • 包含時間戳的事件元數據。
   • 清晰的 URI 格式化。

該實現實現了功能和簡單性之間的良好平衡，形成了一個可靠且易於維護的代碼庫。

⚠️ 重要提示

我還沒有用任何“真正的”MCP 客戶端測試過這個——據我所知，很少有客戶端真正支持資源訂閱，因為這本來就是可選的。不過，幸運的是 Inspector 是一個非常好的客戶端，你可以用它來測試這個服務器。

💡 使用建議

按照演示說明的步驟進行操作，可順利完成對服務器的測試。在實際使用中，可根據實際應用場景對服務器進行擴展和優化。