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.

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

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

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