Skip to main content
Glama
MCP Observer Server

MCP Observer Server

by hesreallyhim

mcp-观察者-服务器

mcp-observer-server是一个 MCP(模型上下文协议)服务器,用于监控文件系统事件并向 MCP 客户端提供实时通知。它充当本地文件系统和 AI 助手(例如克劳德检查器,使他们能够自动响应文件更改。

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

语境

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的文件(该文件是 .gitignored 文件,因此您必须创建它),但您也可以订阅其他文件。您可以使用subscribe_default工具订阅此文件。

  7. 修改watched.txt文件(或你订阅的任何文件),你应该会看到在 Inspector 的右下角面板中出现一条服务器通知。这就是 POC 的雏形。

Related MCP server: File MCP Server

演示可视化

  1. 启动服务器并连接 Inspector:启动服务器并连接

  2. 列出默认资源:列出资源

  3. 列出工具:列表工具

  4. 订阅默认文件:订阅默认文件

  5. 修改文件:修改文件

  6. 查看出现的通知:查看通知

🎉

服务器描述

MCP 观察服务器 (MCP Observer Server) 跟踪系统中文件和目录的变更,允许 MCP 客户端订阅这些事件,并在文件创建、修改、删除或移动时采取行动(当前演示版本处理修改事件)。该服务器实现了完整的模型上下文协议 (MCP) 规范,提供:

  • 实时文件监控:使用 Watchdog 库进行高效的文件系统观察

  • 订阅管理:创建、列出和取消任何路径的监控订阅

  • 变更历史记录:维护每个订阅的最近变更日志(演示中省略)

  • 文件和目录访问:通过 MCP 资源读取文件内容和目录列表

  • 无状态设计:客户端控制文件更改时发生的响应

主要特点

  • 订阅特定文件、目录或整个存储库的更改

  • 按文件模式或事件类型过滤事件(演示中省略)

  • 查询最近的更改,查看哪些文件受到影响(演示中省略)

  • 通过资源端点访问文件内容

  • 轻量级、高效的实现,依赖性最小

  • 与任何 MCP 兼容客户端简单集成(...支持资源订阅)

实际应用

我试图解决的主要痛点是,除非 Claude Code 接触到文件并自行写入更改,否则它根本不知道你的代码库/项目中发生了什么。(你知道那些通知吗?“文件自上次读取后已更改”?)拥有一个客户端或编码助手来实际监控你在项目中的操作,你不必把所有任务都委托给 Claude 让它知道发生了什么,这对我来说非常有用。一些实际应用包括:

  • 自动文档更新:使文档与代码更改保持同步 - 您更新一些代码,Claude 会收到更改通知,并且它会主动检查或更新文档字符串等。

  • 实时代码审查:在工作时获得代码更改的实时反馈,捕捉拼写错误、类型错误等,提供建议,真正的结对编程。

  • 测试自动化:当相关文件被修改时运行测试。

  • AI辅助:启用AI工具自动响应文件更改。

  • Git 提交自动化:你是否经常忘记提交?Claude 可以监控你的更改,并建议(或执行)更频繁的提交操作。

当前实施设计

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

架构亮点

  1. 简化结构

    • 重点实施(约 170 行代码)

    • 将功能整合到一小组核心组件中

    • 简洁的基于函数的设计,直接利用 MCP SDK

    • 较高的可读性和可维护性

  2. 高效的状态管理

    • 简单的字典结构将路径映射到客户端会话

    • 使用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. 通知传递

    • ServerNotification 创建和发送

    • 带有时间戳的事件元数据

    • 清理 URI 格式

该实现在功能性和简单性之间取得了良好的平衡,从而形成了可靠且可维护的代码库。

Available Tools

4 tools
list_watchedA

List all currently monitored paths and their subscriber counts

Inputs: no named parameters.

subscribeC

Subscribe to changes on a file or directory

Inputs: path (required).

subscribe_defaultB

Subscribe to the default watched.txt file for development

Inputs: no named parameters.

unsubscribeC

Unsubscribe from changes on a file or directory

Inputs: path (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no overlap: list_watched for viewing current subscriptions, subscribe for adding new ones, subscribe_default for a specific default case, and unsubscribe for removal. The descriptions reinforce these distinct roles, making misselection unlikely.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern (list_watched, subscribe, subscribe_default, unsubscribe) with clear, action-oriented names. The naming is uniform and predictable, enhancing usability.

    Tool Count5/5

    With 4 tools, this server is well-scoped for its purpose of monitoring file/directory changes. Each tool serves a necessary function in the subscription lifecycle, and the count is neither too sparse nor bloated.

    Completeness5/5

    The tool set provides complete coverage for the domain of file/directory monitoring: list (read), subscribe (create), unsubscribe (delete), and a specialized subscribe_default for convenience. There are no obvious gaps, supporting full agent workflows.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A Model Context Protocol (MCP) server that enables AI assistants to perform comprehensive file operations including finding, reading, writing, editing, searching, moving, and copying files with security validations.
      7
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A secure file server for AI assistants that provides comprehensive file operations and text manipulation with configurable access levels and multiple connection modes.
      6
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A secure, sandboxed file system server that enables reading, writing, searching, and managing files through MCP-compatible AI clients with path traversal protection and size limits.
      -