MCP Firebase Server

MCP Firebase Server (протокол контекста модели)

Этот сервер реализует протокол контекста модели (MCP), чтобы действовать как мост между большой языковой моделью (LLM), такой как Claude, и Firebase (Firestore). Он позволяет LLM читать и писать в коллекции Firestore, предоставляя эти операции как «инструменты» MCP.

Этот сервер создан с использованием официального mcp Python SDK.

Предпосылки

• Python 3.7+ (предпочтительно 3.8+ для asynccontextmanager и функций полного указания типов, используемых MCP)
• Pip (установщик пакетов Python) или uv (рекомендуется документацией MCP для управления проектами)
• Проект Firebase с включенным Firestore.
• Файл JSON ключа учетной записи службы Firebase.

Настраивать

1. Клонирование/Загрузка: Убедитесь, что у вас есть файл сервера ( mcp_firebase_server.py ), requirements.txt и т. д. в локальном каталоге.
2. Ключ учетной записи сервиса:
   • Для аутентификации серверу необходим ключ учетной записи службы Firebase.
   • Вариант 1 (рекомендуется для конфигурации клиента MCP): Установите переменную среды SERVICE_ACCOUNT_KEY_PATH на абсолютный путь к файлу JSON вашей учетной записи службы. Это наиболее гибкий метод, когда сервер запускается клиентом MCP.
   • Вариант 2 (резервный): Если переменная среды SERVICE_ACCOUNT_KEY_PATH не установлена, сервер будет искать файл с именем serviceAccountKey.json в своем собственном каталоге (том же каталоге, что и mcp_firebase_server.py ). При использовании этого метода переименуйте свой файл ключа соответствующим образом.
   • Важно: убедитесь, что ваш файл ключа учетной записи службы (как бы он ни назывался и к которому осуществлялся доступ) хранится в безопасности и, в идеале, указан в вашем .gitignore , если в проекте существует локальная копия.
3. Хранилище Firebase (необязательно):
   • Если вы собираетесь использовать функциональные возможности Firebase Storage с этим сервером (в настоящее время ни один инструмент не использует его, но его можно добавить), установите переменную среды FIREBASE_STORAGE_BUCKET на имя контейнера хранилища вашего проекта Firebase (например, your-project-id.appspot.com ). Сервер прочитает и выведет это значение, если оно установлено.
4. Создание виртуальной среды (рекомендуется): с помощью venv :
   python3 -m venv venv source venv/bin/activate # On macOS/Linux # venv\\Scripts\\activate # On Windows
   Или, если используется uv (как предлагается в документации MCP для новых проектов):
   uv venv source .venv/bin/activate # Or similar, depending on your uv setup
5. Установка зависимостей: с помощью pip :
   pip install -r requirements.txt
   Или, если использовать uv :
   uv pip install -r requirements.txt
   Это установит mcp[cli] и firebase-admin .

Запуск сервера

Есть несколько способов запустить этот MCP-сервер:

1. Прямое выполнение (для транспорта stdio через run_server.sh ): скрипт run_server.sh предоставляется для упрощения запуска сервера. Этот скрипт обрабатывает активацию виртуальной среды (если она называется venv и присутствует в корне проекта) перед запуском скрипта Python.Сначала сделайте скрипт исполняемым:
   chmod +x run_server.sh
   Затем запустите сервер с помощью скрипта:
   ./run_server.sh
   Именно так обычно настраивается клиент MCP для запуска сервера (см. раздел «Использование с Клодом» ниже).
2. **Использование MCP CLI для разработки и проверки ( mcp dev ): mcp CLI (устанавливается как часть mcp[cli] ) предоставляет сервер разработки и инструмент инспектора. Это настоятельно рекомендуется во время разработки.
   mcp dev mcp_firebase_server.py
   Это запустит сервер и часто предоставит веб-интерфейс для проверки его возможностей (инструментов, ресурсов) и выполнения тестовых вызовов.

Инструменты MCP раскрыты

Этот сервер, называемый MCPFirebaseServer , предоставляет следующие инструменты:

1. query_firestore_collection

• Описание (из строки документации): Извлекает документы из указанной коллекции Firestore.
• Аргументы:
  • collection_name (строка, обязательно): Имя коллекции Firestore для запроса.
  • limit (целое число, необязательное, по умолчанию: 50): максимальное количество возвращаемых документов.
• Возвращает: (List[Dict[str, Any]]) Список документов из коллекции. Каждый документ представляет собой словарь, включающий поле id . Возвращает список, содержащий один словарь ошибок, если происходит ошибка (например, [{"error": "Firestore not initialized..."}] или [{"error": "Failed to query..."}] ).

2. add_document_to_firestore

• Описание (из docstring): Добавляет новый документ с автоматически сгенерированным идентификатором в указанную коллекцию Firestore.
• Аргументы:
  • collection_name (строка, обязательно): Имя коллекции Firestore, в которую будет добавлен документ.
  • document_data (объект/словарь, обязательно): словарь, представляющий документ для добавления.
• Возвращает: (Dict[str, Any]) Словарь, содержащий success (логическое значение) и либо id (строка) и message (строка) в случае успеха, либо error (строка) в случае неудачи. Пример успеха: {"success": True, "id": "newDocId", "message": "Document added to 'logs'"} Пример неудачи: {"success": False, "error": "Firestore not initialized..."}

Использование с Клодом (или другими клиентами MCP)

Этот MCP Firebase Server разработан для запуска в качестве отдельного процесса, обычно запускаемого клиентским приложением MCP (таким как Claude Desktop или пользовательским приложением, созданным с помощью платформы, такой как Windsurf, которая может управлять серверами MCP). Затем клиент взаимодействует с этим сервером, обычно через stdio (стандартный ввод/вывод) для локально запущенных серверов.

Общие этапы интеграции:

1. Доступность сервера: убедитесь, что mcp_firebase_server.py и его зависимости (включая serviceAccountKey.json ) доступны в системе, где клиент MCP будет работать или может запускать процессы.
2. Конфигурация клиента: Клиентское приложение MCP должно быть настроено так, чтобы знать, как запустить ваш MCPFirebaseServer . Эта конфигурация обычно включает указание:
   • Команда для выполнения (например, python или uv run python ).
   • Аргументы для этой команды (например, путь к mcp_firebase_server.py ).
   • При желании, любые переменные среды, которые могут понадобиться серверу (хотя наш текущий сервер ожидает serviceAccountKey.json в том же каталоге, альтернативой может быть переменная среды для пути к ключу).
3. Запуск и коммуникация:
   • Когда клиенту MCP потребуется использовать инструмент, предоставляемый этим сервером, он запустит mcp_firebase_server.py с помощью настроенной команды.
   • Затем клиент и сервер взаимодействуют по протоколу MCP (например, через stdio ). Клиент может обнаружить доступные инструменты ( query_firestore_collection , add_document_to_firestore ) и вызвать их.

Пример концептуальной конфигурации (для клиента MCP, такого как Claude Desktop):

Многие клиентские приложения, совместимые с MCP (например, Claude Desktop, как указано в документации MCP), используют файл конфигурации (часто JSON) для определения того, как запускать и управлять серверами MCP. Хотя точный формат может различаться в зависимости от клиента, принцип схож.

Ниже приведен концептуальный пример, основанный на шаблонах, представленных в документации MCP. Вам нужно будет адаптировать его к конкретному механизму конфигурации выбранного вами клиента MCP (Claude Desktop, Windsurf и т. д.).

Ключевые моменты конфигурации:

• "command" : исполняемый файл для запуска (например, python ). Убедитесь, что он находится в системной переменной PATH или укажите полный путь к интерпретатору Python.
• "args" : список аргументов. Первый аргумент — это обычно скрипт для выполнения. Крайне важно использовать полный, абсолютный путь к mcp_firebase_server.py , чтобы клиент мог его найти, независимо от того, откуда запускается сам клиент.
• "cwd" (текущий рабочий каталог) : иногда может потребоваться указать рабочий каталог для серверного процесса, особенно если он использует относительные пути для других файлов (хотя наш путь serviceAccountKey.json указан относительно самого скрипта, что обычно надежно, если путь к скрипту абсолютный).
• "env" : Для передачи переменных среды. В то время как наш текущий сервер находит serviceAccountKey.json относительно своего собственного пути, распространенным шаблоном для более настраиваемых серверов является передача путей учетных данных или других параметров через переменные среды.

Поток взаимодействия (краткий обзор):

1. Клиент запускает сервер: Клиент MCP (использующий конфигурацию выше) запускает mcp_firebase_server.py .
2. Инициализация сервера: наш сервер пытается подключиться к Firebase.
3. Обнаружение и вызовы инструментов: клиент обнаруживает и вызывает такие инструменты, как query_firestore_collection или add_document_to_firestore по мере необходимости.
4. Ответ сервера: результаты отправляются обратно клиенту через stdio .

Конкретные инструкции для Claude Desktop или Windsurf:

• Claude Desktop: Если вы используете Claude Desktop, обратитесь к его документации о том, как добавлять и настраивать пользовательские серверы MCP. Структура JSON выше — это общий шаблон, который вы можете адаптировать.
• Windsurf: Если Windsurf — ваш оркестратор и он поддерживает управление серверами MCP, у него будет свой собственный метод определения и запуска этих внешних серверов инструментов. Вам нужно будет обратиться к документации Windsurf для получения подробностей, но основная информация (команда, аргументы для запуска mcp_firebase_server.py ) будет той же.

Если у вашего клиента нет выделенного пользовательского интерфейса/файла конфигурации управления сервером MCP, но он может выполнять команды оболочки и взаимодействовать через stdio, вам следует программно запустить скрипт mcp_firebase_server.py , а затем использовать клиентскую библиотеку MCP (например, ту, что находится в mcp.client.stdio ) для взаимодействия с ним.

Разработка и тестирование

• Используйте mcp dev mcp_firebase_server.py для запуска сервера с MCP Inspector. Это позволяет вам видеть обнаруженные инструменты и тестировать их в интерактивном режиме.
• Убедитесь, что serviceAccountKey.json правильно размещен ИЛИ установлена переменная среды SERVICE_ACCOUNT_KEY_PATH при запуске сервера клиентом MCP.
• Проверьте вывод консоли сервера на наличие сообщений инициализации Firebase и ошибок выполнения.

Скрипт run_server.sh :

Скрипт run_server.sh в корне проекта предназначен для:

1. Определить свое местоположение и изменить текущий каталог на него.
2. Найдите и активируйте виртуальную среду Python с именем venv , если она существует в корне проекта.
3. Выполните скрипт mcp_firebase_server.py с помощью интерпретатора python (в идеале из активированного venv).

Этот скрипт гарантирует, что сервер MCP запустится в своей предполагаемой среде. Не забудьте сделать его исполняемым ( chmod +x run_server.sh ).