Skip to main content
Glama
MCP Observer Server

MCP Observer Server

by hesreallyhim

mcp-наблюдатель-сервер

mcp-observer-server — это сервер MCP (Model Context Protocol), который отслеживает события файловой системы и предоставляет уведомления в реальном времени клиентам MCP. Он действует как (более двунаправленный) мост между вашей локальной файловой системой и помощниками ИИ, такими как Клод Inspector, позволяющий автоматически реагировать на изменения файлов.

ПРИМЕЧАНИЕ: Это демонстрация/POC сервера MCP для мониторинга файлов, над которым я работаю. Я вижу много вопросов/комментариев/проблем/обсуждений по этому поводу, поэтому я хотел бы опубликовать эту минимальную реализацию, чтобы поделиться своим подходом.

Контекст

Протокол MCP определяет понятие подписки на ресурс, в котором клиент может запросить уведомление о любых изменениях в ресурсе, а сервер может выбрать отправку уведомлений. Вот схема потока:

Диаграмма потока подписки на ресурсы

Протокол говорит, что клиент должен затем отправить запрос на чтение обратно на сервер, чтобы прочитать изменения. (Все это, кстати, необязательно). Но я нахожу это немного громоздким и подразумевающим дополнительный запрос, и я бы предпочел, чтобы мое уведомление об обновлении ресурсов также описывало изменение. К счастью, SDK предлагает поле meta / _meta , и вы можете отправить практически все, что захотите. Так что я могу захотеть отправить количество измененных строк, разницу изменений, кто знает что. Я не реализовал это в этой демонстрации, сейчас я просто отправляю временную метку. (Я в основном вырвал все с сервера, кроме минимального POC.) Кроме того, он просто работает на транспорте stdio, ничего особенного.

ПРИМЕЧАНИЕ!!! Я пока не тестировал это ни с одним "реальным" клиентом MCP - насколько я понимаю, клиенты view на самом деле поддерживают подписку на ресурсы, поскольку это в любом случае необязательно. Однако, к счастью, 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. По умолчанию сервер выставит файл с именем watched.txt в src/mcp_observer_server/watched.txt (файл .gitignored, поэтому его нужно создать), но вы можете подписаться и на другие файлы. Вы можете подписаться на этот файл с помощью инструмента subscribe_default .

  7. Измените файл watched.txt (или любой другой файл, на который вы подписались), и вы должны увидеть уведомление сервера в нижней правой панели Inspector. Это установленный POC.

Related MCP server: File MCP Server

ДЕМО-ВИЗУАЛИЗАЦИЯ

  1. Запустите сервер и подключитесь с помощью Inspector: Запустить сервер и подключиться

  2. Список ресурсов по умолчанию: Список ресурсов

  3. Перечислите инструменты:Список инструментов

  4. Подписаться на файл по умолчанию: Подписаться на файл по умолчанию

  5. Измените файл:Изменить файл

  6. Появляется уведомление: Смотреть уведомление

🎉

Описание сервера

MCP Observer Server отслеживает изменения файлов и каталогов в вашей системе, позволяя клиентам MCP подписываться на эти события и предпринимать действия при создании, изменении, удалении или перемещении файлов (текущая демонстрация обрабатывает событие изменения). Этот сервер реализует полную спецификацию Model Context Protocol, предоставляя:

  • Мониторинг файлов в реальном времени : использование библиотеки Watchdog для эффективного наблюдения за файловой системой

  • Управление подписками : создание, перечисление и отмена подписок на мониторинг для любого пути.

  • История изменений : ведет журнал последних изменений для каждой подписки (в демоверсии отсутствует)

  • Доступ к файлам и каталогам : чтение содержимого файлов и списков каталогов через ресурсы MCP.

  • Дизайн без сохранения состояния : клиенты контролируют, что происходит в ответ на изменения файлов

Основные характеристики

  • Подпишитесь на изменения в определенных файлах, каталогах или целых репозиториях

  • Фильтрация событий по шаблонам файлов или типам событий (в демоверсии отсутствует)

  • Запросить последние изменения, чтобы узнать, какие файлы были затронуты (в демоверсии пропущено)

  • Доступ к содержимому файла через конечные точки ресурсов

  • Легкая и эффективная реализация с минимальными зависимостями

  • Простая интеграция с любым MCP-совместимым клиентом (...поддерживающий подписку на ресурсы)

Практические применения

Основная проблема, которую я пытаюсь решить, заключается в том, что если Claude Code, например, не коснется файла и не запишет в него изменения, он не будет знать, что происходит в вашем репозитории/проекте. (Вы знаете эти уведомления — «Файл изменен с момента последнего чтения»?) Наличие клиента или помощника по кодированию, который фактически отслеживает то, что вы делаете в своем проекте, и вам не нужно делегировать каждую задачу Claude, просто чтобы он знал, что это происходит, кажется мне чрезвычайно полезным. Некоторые практические приложения включают:

  • Автоматизированные обновления документации : синхронизируйте документацию с изменениями кода — вы обновляете код, Клод уведомляется об изменении, и он заблаговременно проверяет или обновляет строки документации и т. д.

  • Обзоры кода в реальном времени : получайте обратную связь в режиме реального времени об изменениях кода по мере работы, выявляйте орфографические ошибки, ошибки ввода и т. д., давайте советы, настоящее парное программирование.

  • Автоматизация тестирования : запуск тестов при изменении соответствующих файлов.

  • Помощь ИИ : включите инструменты ИИ для автоматического реагирования на изменения файлов.

  • Автоматизация коммитов Git : Вы забываете делать коммиты достаточно часто? Клод может следить за вашими изменениями и предлагать (или выполнять) действия по коммиту чаще.

Текущая реализация проекта

Реализация сервера отличается оптимизированной архитектурой, в которой приоритет отдается простоте, надежности и удобству обслуживания.

Архитектурные особенности

  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

    • Простой параметр пути для простого управления подпиской

    • Чистая обработка ошибок и проверка пути

  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.
      -