MCP Observer Server

mcp观察服务器

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

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

上下文

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

Resource Subscription Flow Diagram

协议规定，客户端应向服务器发送读取请求以读取更改。（顺便说一句，所有这些都是可选的）。但是，我觉得这有点麻烦，而且需要额外的行程，我宁愿让我的资源更新通知也描述一下这一变化。幸运的是，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：

Start Server and Connect

1. 列出默认资源：

List Resources

1. 列出工具：

List Tools

1. 订阅默认文件：

Subscribe to Default File

1. 修改文件：

Modify the File

1. 查看出现的通知：

See Notification

🎉

服务器描述

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

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

主要特点

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

实际应用

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

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

当前实施设计

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

建筑亮点

1. 简化结构

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

1. 高效的状态管理

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

1. MCP协议集成

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

1. 事件处理

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

1. 通知系统

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

核心组件

1. 数据结构

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

1. 工具API

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

1. 资源处理

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

1. 事件处理

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

1. 通知递送

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

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