mcp-观察者-服务器
mcp-observer-server
是一个 MCP(模型上下文协议)服务器,用于监控文件系统事件并向 MCP 客户端提供实时通知。它充当本地文件系统和 AI 助手(例如克劳德检查器,使他们能够自动响应文件更改。
**注意:**这是我正在开发的文件监控 MCP 服务器的演示/POC。我看到很多关于这类问题的问题/评论/问题/讨论,所以我想发布这个最小实现来分享我的方法。
语境
MCP 协议定义了资源订阅的概念,客户端可以请求接收资源任何变更的通知,服务器可以选择发送通知。流程图如下:
协议规定客户端应该向服务器发送读取请求以读取更改。(顺便说一下,所有这些都是可选的)。但是,我觉得这有点麻烦,而且需要额外的一次传输,我更希望我的资源更新通知也能描述更改。幸运的是,SDK 提供了一个meta
/ _meta
字段,你几乎可以发送任何你想要的内容。所以我可能想发送更改的行数、更改的差异,或者其他什么,谁知道呢。我在这个演示中没有实现这些,现在我只发送时间戳。(我基本上把服务器里除了最小 POC 之外的所有内容都删掉了。)而且,它只是在 stdio 传输上运行,没什么特别的。
**注意!!!**我还没有用任何“真正的” MCP 客户端测试过这一点——我的理解是,每个视图客户端实际上都支持资源订阅,因为它本来就是可选的。不过幸运的是, Inspector是一款非常优秀的客户端,你可以用它来测试这个服务器。
演示说明:
- 克隆存储库。
- 使用
uv
安装依赖项(或者,我想是其他方式)。 - 使用
make start
(使用uv
)运行服务器或运行npx @modelcontextprotocol/inspector uv run src/mcp_observer_server/server.py
。 - 打开 Inspector 客户端并使用 stdio 连接,无需配置。
- 使用
subscribe
工具来监控一个目录或文件,(或者,您可以运行“列出资源”,单击一个资源,然后单击“订阅”按钮来订阅它)。 - 默认情况下,服务器会在
src/mcp_observer_server/watched.txt
中公开一个名为watched.txt
的文件(该文件是 .gitignored 文件,因此您必须创建它),但您也可以订阅其他文件。您可以使用subscribe_default
工具订阅此文件。 - 修改
watched.txt
文件(或你订阅的任何文件),你应该会看到在 Inspector 的右下角面板中出现一条服务器通知。这就是 POC 的雏形。
演示可视化
- 启动服务器并连接 Inspector:
- 列出默认资源:
- 列出工具:
- 订阅默认文件:
- 修改文件:
- 查看出现的通知:
🎉
服务器描述
MCP 观察服务器 (MCP Observer Server) 跟踪系统中文件和目录的变更,允许 MCP 客户端订阅这些事件,并在文件创建、修改、删除或移动时采取行动(当前演示版本处理修改事件)。该服务器实现了完整的模型上下文协议 (MCP) 规范,提供:
- 实时文件监控:使用 Watchdog 库进行高效的文件系统观察
- 订阅管理:创建、列出和取消任何路径的监控订阅
- 变更历史记录:维护每个订阅的最近变更日志(演示中省略)
- 文件和目录访问:通过 MCP 资源读取文件内容和目录列表
- 无状态设计:客户端控制文件更改时发生的响应
主要特点
- 订阅特定文件、目录或整个存储库的更改
- 按文件模式或事件类型过滤事件(演示中省略)
- 查询最近的更改,查看哪些文件受到影响(演示中省略)
- 通过资源端点访问文件内容
- 轻量级、高效的实现,依赖性最小
- 与任何 MCP 兼容客户端简单集成(...支持资源订阅)
实际应用
我试图解决的主要痛点是,除非 Claude Code 接触到文件并自行写入更改,否则它根本不知道你的代码库/项目中发生了什么。(你知道那些通知吗?“文件自上次读取后已更改”?)拥有一个客户端或编码助手来实际监控你在项目中的操作,你不必把所有任务都委托给 Claude 让它知道发生了什么,这对我来说非常有用。一些实际应用包括:
- 自动文档更新:使文档与代码更改保持同步 - 您更新一些代码,Claude 会收到更改通知,并且它会主动检查或更新文档字符串等。
- 实时代码审查:在工作时获得代码更改的实时反馈,捕捉拼写错误、类型错误等,提供建议,真正的结对编程。
- 测试自动化:当相关文件被修改时运行测试。
- AI辅助:启用AI工具自动响应文件更改。
- Git 提交自动化:你是否经常忘记提交?Claude 可以监控你的更改,并建议(或执行)更频繁的提交操作。
当前实施设计
服务器实现具有简化的架构,优先考虑简单性、可靠性和可维护性。
架构亮点
- 简化结构
- 重点实施(约 170 行代码)
- 将功能整合到一小组核心组件中
- 简洁的基于函数的设计,直接利用 MCP SDK
- 较高的可读性和可维护性
- 高效的状态管理
- 简单的字典结构将路径映射到客户端会话
- 使用
watched
字典进行直接路径到会话的映射 - 具有清晰数据流的最小状态跟踪
- 避免冗余数据结构
- MCP 协议集成
- 直接使用 MCP SDK 函数装饰器
- 清理资源 URI 处理
- 通过适当的功能配置简化服务器初始化
- 直接通知传递系统
- 事件处理
- 简化的看门狗事件处理程序实现
- 直接事件到通知路径
- 通过
call_soon_threadsafe
实现线程安全通信 - 高效的事件过滤
- 通知系统
- 直接使用 MCP 通知原语
- 通过适当的错误处理实现可靠的交付
- 准确的 UTC 时间戳处理
- 清理 URI 格式
核心组件
- 数据结构
watched
单个全局字典将 Path 对象映射到 ServerSession 对象集- 每个路径条目包含订阅该路径的会话集
- 工具 API
- 两个必备工具:
subscribe
和unsubscribe
- 简单的路径参数,用于直接的订阅管理
- 清理错误处理和路径验证
- 两个必备工具:
- 资源处理
- 通过资源列表直接公开的文件 URI
- 路径解析和验证
- 文件的文本内容读取
- 事件处理
- Watcher 类扩展了 FileSystemEventHandler
- 直接处理修改的事件
- 线程安全通知调度
- 嵌套路径的路径相关性处理
- 通知传递
- ServerNotification 创建和发送
- 带有时间戳的事件元数据
- 清理 URI 格式
该实现在功能性和简单性之间取得了良好的平衡,从而形成了可靠且可维护的代码库。
This server cannot be installed
local-only server
The server can only run on the client's local machine because it depends on local resources.
文件监控服务器可跟踪文件系统事件并向 AI 助手提供实时通知,使其能够自动响应文件更改而无需手动更新。
Related MCP Servers
- -securityAlicense-qualityProvides code manipulation, execution, and version control capabilities. It allows AI assistants to read, write, and execute code while maintaining a history of changes.Last updated -8PythonMIT License
- -securityFlicense-qualityThis server provides an interface for performing basic file system operations such as navigation, reading, writing, and file analysis, allowing users to manage directories and files efficiently.Last updated -3Python
- AsecurityAlicenseAqualityAn unofficial server that allows AI assistants to access Fathom Analytics data, enabling users to retrieve account information, site statistics, events, aggregated reports, and real-time visitor tracking.Last updated -5202TypeScriptMIT License
- AsecurityFlicenseAqualityEnables AI models to perform file system operations (reading, creating, and listing files) on a local file system through a standardized Model Context Protocol interface.Last updated -3JavaScript