文件监控服务

mcp观察服务器

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

注： 这是我正在开发的一个文件监控MCP服务器的演示/POC。我看到了很多关于这类事情的问题/评论/问题/讨论，所以我想发布这个最小的实现来分享我的方法。

上下文

MCP协议定义了资源订阅的概念，其中客户端可以请求通知资源的任何更改，服务器可以选择发送通知。流程图如下：

协议规定，客户端应向服务器发送读取请求以读取更改。（顺便说一句，所有这些都是可选的）。但是，我觉得这有点麻烦，而且需要额外的行程，我宁愿让我的资源更新通知也描述一下这一变化。幸运的是，SDK提供了 meta/_meta 字段，你几乎可以发送任何你想要的东西。所以我可能想发送更改的行数，更改的差异，谁知道呢。我在这个演示中还没有实现，现在我只是发送时间戳。（我基本上从服务器上删除了所有内容，除了最小的POC。）此外，它只是在stdio传输上运行，没什么了不起的。

注意！！！ 我还没有在任何“真正的”MCP客户端上测试过这一点——我的理解是，视图客户端实际上支持资源订阅，因为它无论如何都是可选的。然而，幸运的是 检查员 是一个非常好的客户端，您可以使用它来测试此服务器。

演示说明：

1. 克隆存储库。
2. 使用安装依赖项 uv （或者，我想是另一种方式）。
3. 使用以下命令运行服务器 make start （使用 uv)或奔跑 npx @modelcontextprotocol/inspector uv run src/mcp_observer_server/server.py.
4. 打开Inspector客户端并使用stdio连接，无需配置。
5. 使用 subscribe 监视目录或文件的工具（或者，您可以运行“列出资源”，单击资源，然后单击“订阅”按钮订阅它）。
6. 默认情况下，服务器将公开一个名为 watched.txt 在……里面 src/mcp_observer_server/watched.txt （该文件是.gitignored，因此您必须创建它），但您也可以订阅其他文件。您可以使用订阅此文件 subscribe_default 工具。
7. 修改 watched.txt 文件（或您订阅的任何文件），您应该会在检查器的右下角面板中看到服务器通知。这就是POC。

演示可视化

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

🎉

服务器描述

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

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

主要特点

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

实际应用

我试图解决的主要痛点是，除非Claude Code（例如）触摸文件并将更改写入文件本身，否则它不知道你的仓库/项目中发生了什么。（你知道这些通知吗？“自上次阅读以来文件已更改”？）有一个客户端或编码助理实际监控你在项目中所做的事情，你不必把每项任务都委托给Claude，这样它就知道它发生了，这对我来说似乎非常有用。一些实际应用包括：

• 自动更新文档：保持文档与代码更改同步——您更新了一些代码，Claude会收到更改通知，它会主动检查或更新文档字符串等。
• 实时代码评论：在工作时获得代码更改的实时反馈，发现拼写错误、类型错误等，提供建议，真正的结对编程。
• 测试自动化：修改相关文件时运行测试。
• 人工智能辅助：启用AI工具自动响应文件更改。
• Git提交自动化你是否经常忘记承诺？Claude可以观察您的更改，并更频繁地建议（或执行）提交操作。

当前实施设计

服务器实现具有精简的架构，优先考虑简单性、可靠性和可维护性。

建筑亮点

1. 简化结构

   • 集中实现（约170行代码）
   • 将功能整合到一小部分核心组件中
   • 基于功能的简洁设计，直接利用MCP SDK
   • 可读性和可维护性高

2. 高效的状态管理

   • 简单的字典结构将路径映射到客户端会话
   • 使用a watched 会话映射直接路径字典
   • 具有清晰数据流的最小状态跟踪
   • 避免冗余数据结构

3. MCP协议集成

   • 直接使用MCP SDK函数装饰器
   • 清理资源URI处理
   • 通过适当的功能配置简化了服务器初始化
   • 直接通知传递系统

4. 事件处理

   • 简化的监视器事件处理程序实现
   • 将事件直接发送到通知路径
   • 通过线程安全通信 call_soon_threadsafe
   • 高效的事件过滤

5. 通知系统

   • 直接使用MCP通知原语
   • 可靠的交付，正确的错误处理
   • 精确的UTC时间戳处理
   • 干净的URI格式

核心组件

1. 数据结构

   • 单一全球词典 watched 将Path对象映射到ServerSession对象集
   • 每个路径条目都包含订阅该路径的会话集

2. 工具API

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

3. 资源处理

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

4. 事件处理

   • Watcher类扩展FileSystemEventHandler
   • 直接处理修改后的事件
   • 线程安全通知调度
   • 嵌套路径的路径相关性处理

5. 通知递送

   • 服务器通知创建和发送
   • 带有时间戳的事件元数据
   • 干净的URI格式

该实现在功能性和简单性之间实现了良好的平衡，从而产生了可靠和可维护的代码库。