Couchbase Guru MCP Server

Сервер MCP, который позволяет LLM искать в документации Couchbase прямо из вашего MCP-клиента. Он предоставляет единственный инструмент ask_couchbase_docs, который передаёт ваш вопрос размещённому документационному агенту с генерацией, дополненной поиском (RAG), и возвращает ответ со ссылками на источники.

Для работы не требуется кластер Couchbase или учётные данные. Сервер общается только с бэкендом документационного агента, а не с вашими данными.

Инструмент

Задавайте полные, самодостаточные вопросы — у бэкенда нет истории диалога, поэтому указывайте продукт, версию и язык, где это уместно (например, «Как создать первичный индекс с помощью Python SDK в Couchbase Server 7.6?»).

Related MCP server: docrag

Предварительные требования

• Python 3.10 или выше.

• Установленный uv для запуска сервера.

• MCP-клиент, например Claude Desktop, Cursor или VS Code.

Конфигурация

Сервер можно запустить из готового пакета на PyPI или из исходного кода с помощью uv. Он работает без какой-либо настройки — по умолчанию используется публичный документационный агент.

Запуск из PyPI

{
  "mcpServers": {
    "couchbase-guru": {
      "command": "uvx",
      "args": ["couchbase-guru"]
    }
  }
}

Если у вас уже настроены другие MCP-серверы, добавьте эту запись в существующий объект mcpServers.

Запуск из исходного кода

Клонируйте репозиторий:

git clone https://github.com/Couchbase-Ecosystem/couchbase-guru.git

Затем подключите ваш MCP-клиент к нему:

{
  "mcpServers": {
    "couchbase-guru": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/cloned/repo/couchbase-guru/",
        "run",
        "src/mcp_server.py"
      ]
    }
  }
}

path/to/cloned/repo/couchbase-guru/ — это путь к клонированному репозиторию на вашем компьютере. Не забудьте завершающий слэш.

Параметры

Все параметры необязательны и могут быть заданы через аргумент CLI или переменную окружения:

Проверьте установленную версию с помощью:

uvx couchbase-guru --version

Самостоятельное размещение документационного агента

По умолчанию сервер использует общий публичный документационный агент, поэтому большинству пользователей не нужна настройка. Если вы запускаете собственный бэкенд агента, укажите серверу его адрес:

uvx couchbase-guru --agent-base-url https://your-agent.example.com

Ограничение частоты запросов и конфиденциальность

Публичный агент применяет разумные ограничения частоты запросов. Для этого сервер отправляет бэкенду псевдонимизированный идентификатор устройства (в заголовке User-Agent):

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

• HTTP: солевой односторонний хеш IP-адреса подключения — сам адрес никогда не отправляется.

Сам MCP-сервер не сохраняет содержимое вопросов и персональные данные. Если вы предпочитаете не передавать сигнал для ограничения частоты запросов, разместите агента самостоятельно (см. выше).

Конфигурация для конкретных клиентов

1. Отредактируйте файл конфигурации (см. краткое руководство по MCP):

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Добавьте конфигурацию в секцию mcpServers.

3. Перезапустите Claude Desktop.

Логи: ~/Library/Logs/Claude (macOS) или %APPDATA%\Claude\Logs (Windows).

1. В Cursor перейдите в Cursor Settings > Tools & Integrations > MCP Tools.

2. Добавьте конфигурацию вручную или воспользуйтесь ссылкой Install in Cursor для установки в один клик.

3. Сохраните, затем обновите, чтобы подтвердить, что сервер включён.

Логи: в нижней панели нажмите Output и выберите Cursor MCP из раскрывающегося списка.

1. Откройте Command Palette > Windsurf MCP Configuration Panel (или Settings > Advanced > Cascade > Model Context Protocol (MCP) Servers).

2. Нажмите Add Server > Add custom server и добавьте конфигурацию.

3. Сохраните, затем обновите, чтобы подтвердить, что сервер включён.

Подробнее см. в документации Windsurf MCP.

1. Создайте .vscode/mcp.json в своей рабочей области (или выполните MCP: Open User Configuration для глобальной конфигурации).

2. VS Code использует servers в качестве ключа верхнего уровня (не mcpServers):

   {
     "servers": {
       "couchbase-guru": {
         "command": "uvx",
         "args": ["couchbase-guru"]
       }
     }
   }

3. После сохранения используйте встроенный список действий для Start/Stop/управления сервером.

Подробнее см. в документации VS Code MCP.

1. Установите плагин AI Assistant или Junie.

2. Перейдите в Settings > Tools > AI Assistant or Junie > MCP Server.

3. Нажмите «+», добавьте конфигурацию и нажмите Save, затем Apply.

Логи: Help > Show Log in Finder (Explorer) > mcp > couchbase-guru.

Режим транспорта Streamable HTTP

Сервер может работать в режиме Streamable HTTP, чтобы несколько клиентов могли подключаться к одному экземпляру. Сначала убедитесь, что ваш MCP-клиент поддерживает этот транспорт.

uvx couchbase-guru --transport=http --port=8000

Сервер будет доступен по адресу http://localhost:8000/mcp:

{
  "mcpServers": {
    "couchbase-guru-http": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Этот режим не включает поддержку авторизации.

Docker

Соберите образ:

docker build -t couchbase-guru .

Запустите его (по умолчанию используется stdio; учётные данные не нужны):

{
  "mcpServers": {
    "couchbase-guru-docker": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "couchbase-guru"]
    }
  }
}

Для HTTP-транспорта опубликуйте порт и задайте транспорт:

docker run --rm -i \
  -e CB_MCP_TRANSPORT=http \
  -e CB_MCP_HOST=0.0.0.0 \
  -e CB_MCP_PORT=8000 \
  -p 8000:8000 \
  couchbase-guru

Риски, связанные с LLM

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

• Couchbase не проверяет и не оценивает качество или точность таких результатов, и такие результаты могут не отражать точку зрения Couchbase.

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

Устранение неполадок

• Убедитесь, что uv/uvx установлены и находятся в PATH. Возможно, потребуется указать абсолютный путь к uv/uvx в поле command.

• Если поиск завершается по тайм-ауту, бэкенд документации может быть занят — повторите попытку через мгновение.

• Чтобы исключить публичный бэкенд, запустите сервер с собственным агентом, указав --agent-base-url.

• Если вы запускаете сервер из исходного кода после обновления репозитория, выполните uv sync, чтобы обновить зависимости.

• Проверьте журналы вашего MCP-клиента (их расположение указано выше) на наличие ошибок.

Тестирование

Модульные тесты выполняются в автономном режиме (бэкенд имитируется):

uv sync --extra dev
uv run pytest tests/

Интеграционные тесты проверяют инструмент сквозным образом на реальном бэкенде агента и запускаются по желанию (opt-in):

CB_MCP_RUN_INTEGRATION=1 uv run pytest tests/test_docs_tools.py

По умолчанию они используют публичный агент; задайте CB_AGENT_BASE_URL, чтобы указать другой бэкенд.

👩💻 Вклад в проект

Вклад приветствуется! Чтобы сообщить об ошибке, запросить новую функцию или внести улучшения, откройте issue на GitHub.

Инструкции для разработчиков см. в CONTRIBUTING.md (окружение с uv, линтинг и форматирование с помощью Ruff, pre-commit хуки и структура проекта).

# Clone and set up
git clone https://github.com/Couchbase-Ecosystem/couchbase-guru.git
cd couchbase-guru

# Install with development dependencies
uv sync --extra dev

# Install pre-commit hooks
uv run pre-commit install

📢 Политика поддержки

Мы ценим ваш интерес к этому проекту! Он поддерживается сообществом Couchbase, а это значит, что официально не поддерживается нашей командой поддержки. Наши инженеры следят за этим репозиторием и поддерживают его, стараясь решать проблемы по мере возможностей. Пожалуйста, оставляйте все запросы на GitHub.