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 是一个非常好的客户端，你可以用它来测试这个服务器。

💡 使用建议

按照演示说明的步骤进行操作，可顺利完成对服务器的测试。在实际使用中，可根据实际应用场景对服务器进行扩展和优化。