mcp-observer-server

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

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

上下文

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

协议规定客户端随后应向服务器发送读取请求以读取更改。（顺便说一下，所有这些都是可选的）。但我发现这有点繁琐，并且涉及额外的往返通信，我宁愿让我的资源更新通知也描述更改内容。幸运的是，SDK 提供了一个 meta/_meta 字段，你可以几乎发送任何你想要的内容。所以我可能想发送更改的行数、更改的差异等。在这个演示中我还没有实现这些功能，目前我只是发送时间戳。（我基本上从服务器中移除了除最小 POC 之外的所有内容。）此外，它只是运行在 stdio 传输上，没有什么特别花哨的东西。

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

演示说明：

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 的文件（该文件被 .gitignore 忽略，所以你需要自己创建），但你也可以订阅其他文件。你可以使用 subscribe_default 工具订阅此文件。
7. 修改 watched.txt 文件（或你订阅的任何文件），你应该会在 Inspector 的右下方面板中看到服务器通知。这就是 POC 的建立。

演示可视化

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

🎉

服务器描述MCP Observer 服务器跟踪系统上的文件和目录更改，允许 MCP 客户端订阅这些事件，并在文件被创建、修改、删除或移动时采取行动（当前演示仅处理修改事件）。该服务器实现了完整的 Model Context Protocol 规范，提供以下功能：

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

主要特性

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

实际应用

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

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

• 简单的路径参数用于直接的订阅管理
• 清晰的错误处理和路径验证

1. 资源处理

   • 通过资源列表直接暴露文件 URI
   • 路径解析和验证
   • 读取文件的文本内容

2. 事件处理

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

3. 通知传递

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

该实现很好地平衡了功能性和简洁性，从而形成了一个可靠且易于维护的代码库。