mcp-observer-server

<a href="https://glama.ai/mcp/servers/@hesreallyhim/mcp-observer-server"> <img width="380" height="200" src="https://gips2.baidu.com/it/u=1528596849,317046204&fm=3081&app=3081&f=PNG?w=760&h=400" /> </a>

mcp-observer-server 是一个MCP（模型上下文协议）服务器，用于监控文件系统事件，并向MCP客户端提供实时通知。它充当了本地文件系统与AI助手（如Claude Inspector）之间的桥梁，使它们能够自动响应文件更改。

注意： 这是我正在开发的一个文件监控MCP服务器的演示/概念验证。我看到有很多关于此类问题的问题、评论、问题和讨论，因此我想发布这个最小实现来分享我的方法。

上下文

MCP协议定义了一种资源订阅的概念，其中客户端可以请求在资源发生任何更改时收到通知，而服务器可以选择发送这些通知。以下是流程图：

协议规定客户端应随后向服务器发送读取请求以读取更改。（所有这些都是可选的）。但我发现这有点繁琐，涉及额外的步骤，我更希望我的资源更新通知描述更改内容。幸运的是，SDK提供了meta/_meta字段，你可以几乎发送任何想要的内容。所以我可能想发送更改的行数、更改的差异等。目前在这个演示中我没有实现这一点，我只是发送时间戳。（基本上除了最小的概念验证外，我已经把服务器中的其他东西都移除了。）此外，它只是运行在标准IO传输上，没有什么特别之处。

重要提示！ 我还没有用任何“真实的”MCP客户端测试过——据我所知，很少有客户端实际上支持资源订阅，因为它本来就是可选的。然而，幸运的是，Inspector是一个非常好的客户端，你可以使用它来测试这个服务器。

演示说明：

1. 克隆仓库。
2. 使用uv安装依赖项（或者，用某种其他方式）。
3. 使用make start（使用uv）或运行npx @modelcontextprotocol/inspector uv run src/mcp_observer_server/server.py启动服务器。
4. 打开Inspector客户端并使用标准IO连接，无需配置。
5. 使用subscribe工具监控目录或文件，（或者，你可以运行“列出资源”，点击一个资源，然后点击“订阅”按钮来订阅它）。
6. 默认情况下，服务器会在src/mcp_observer_server/watched.txt暴露一个名为watched.txt的文件（该文件被.gitignore忽略，所以你需要创建它），但你也可以订阅其他文件。你可以使用subscribe_default工具订阅此文件。
7. 修改watched.txt文件（或你订阅的任何文件），你应该在Inspector右下角面板中看到服务器的通知。这就是概念验证的建立。

演示可视化

1. 启动服务器并使用Inspector连接：
2. 列出默认资源：
3. 列出工具：
4. 订阅默认文件：
5. 修改文件：
6. 查看通知出现：

🎉

服务器描述

MCP观察者服务器跟踪系统上的文件和目录更改，允许MCP客户端订阅这些事件并在文件创建、修改、删除或移动时采取行动（当前演示处理修改事件）。此服务器实现了完整的模型上下文协议规范，提供：

• 实时文件监控：使用Watchdog库进行高效的文件系统观察
• 订阅管理：为任何路径创建、列出和取消监控订阅
• 变更历史：维护每个订阅的最近更改日志（演示中省略）
• 文件和目录访问：通过MCP资源读取文件内容和目录列表
• 无状态设计：客户端控制对文件更改的响应

关键特性

• 订阅特定文件、目录或整个存储库的更改
• 根据文件模式或事件类型过滤事件（演示中省略）
• 查询最近的更改以查看哪些文件受到影响（演示中省略）
• 通过资源端点访问文件内容
• 轻量级且高效的实现，具有最少的依赖项
• 简单地与任何支持资源订阅的MCP兼容客户端集成

实际应用

我试图解决的主要痛点是，除非Claude Code等自己接触文件并写入更改，否则它不知道你的仓库/项目中发生了什么。（你知道那些通知——“自上次读取以来文件已更改”？）拥有一个实际监控你在项目中做什么的客户端或编码助手，而你不必将每个任务委托给Claude，以便它知道发生了什么，对我来说非常有用。一些实际应用包括：

• 自动化文档更新：保持文档与代码更改同步——你更新了一些代码，Claude会收到更改通知，并主动检查或更新docstring等。
• 实时代码审查：在工作时获得代码更改的实时反馈，捕捉拼写错误、类型错误等，提供建议，真正的配对编程。
• 测试自动化：当相关文件被修改时运行测试。
• 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

   • 两个基本工具：subscribe和unsubscribe
   • 简单的路径参数用于简单的订阅管理
   • 清晰的错误处理和路径验证

3. 资源处理

   • 文件URIs直接通过资源列表公开
   • 路径解析和验证
   • 文件文本内容读取

4. 事件处理

   • Watcher类扩展FileSystemEventHandler
   • 直接处理修改事件
   • 线程安全的通知分发
   • 处理嵌套路径的路径相对性

5. 通知交付

   • 创建和发送ServerNotification
   • 带有时间戳的事件元数据
   • 清晰的URI格式化

实现达到了功能与简单性的良好平衡，从而产生了一个可靠且易于维护的代码库。