MCP Observer Server

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

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