YDB MCP

Сервер Model Context Protocol для YDB. Он позволяет работать с базами данных YDB из любого LLM, поддерживающего MCP. Эта интеграция обеспечивает выполнение операций с базой данных с помощью ИИ и взаимодействие с вашими экземплярами YDB на естественном языке.

Использование

Через uvx

uvx, который является псевдонимом для uv run tool, позволяет запускать различные приложения Python без их явной установки. Ниже приведены примеры того, как настроить YDB MCP с помощью uvx.

Пример: Использование анонимной аутентификации

{
  "mcpServers": {
    "ydb": {
      "command": "uvx",
      "args": [
        "ydb-mcp",
        "--ydb-endpoint", "grpc://localhost:2136",
        "--ydb-database", "/local"
      ]
    }
  }
}

Через pipx

pipx позволяет запускать различные приложения из PyPI без явной установки каждого из них. Однако сначала его необходимо установить. Ниже приведены примеры того, как настроить YDB MCP с помощью pipx.

Пример: Использование анонимной аутентификации

{
  "mcpServers": {
    "ydb": {
      "command": "pipx",
      "args": [
        "run", "ydb-mcp",
        "--ydb-endpoint", "grpc://localhost:2136",
        "--ydb-database", "/local"
      ]
    }
  }
}

Через pip

YDB MCP можно установить с помощью pip, установщика пакетов Python. Пакет доступен на PyPI и включает все необходимые зависимости.

pip install ydb-mcp

Чтобы начать работу с YDB MCP, вам нужно настроить ваш MCP-клиент для связи с экземпляром YDB. Ниже приведены примеры файлов конфигурации, которые вы можете настроить в соответствии с вашей установкой, а затем поместить в настройки MCP-клиента. Путь к интерпретатору Python, возможно, также потребуется скорректировать, указав правильное виртуальное окружение, в котором установлен пакет ydb-mcp.

Пример: Использование анонимной аутентификации

{
  "mcpServers": {
    "ydb": {
      "command": "python3",
      "args": [
        "-m", "ydb_mcp",
        "--ydb-endpoint", "grpc://localhost:2136",
        "--ydb-database", "/local"
      ]
    }
  }
}

Аутентификация

Независимо от метода использования (uvx, pipx или pip), вы можете настроить аутентификацию для вашей установки YDB. Для этого передайте специальные аргументы командной строки.

Использование аутентификации по логину/паролю

Чтобы использовать аутентификацию по логину/паролю, укажите аргументы --ydb-auth-mode, --ydb-login и --ydb-password:

{
  "mcpServers": {
    "ydb": {
      "command": "uvx",
      "args": [
        "ydb-mcp",
        "--ydb-endpoint", "grpc://localhost:2136",
        "--ydb-database", "/local",
        "--ydb-auth-mode", "login-password",
        "--ydb-login", "<your-username>",
        "--ydb-password", "<your-password>"
      ]
    }
  }
}

Использование аутентификации по токену доступа

Чтобы использовать аутентификацию по токену доступа, укажите аргументы --ydb-auth-mode и --ydb-access-token:

{
  "mcpServers": {
    "ydb": {
      "command": "uvx",
      "args": [
        "ydb-mcp",
        "--ydb-endpoint", "grpc://localhost:2136",
        "--ydb-database", "/local",
        "--ydb-auth-mode", "access-token",
        "--ydb-access-token", "qwerty123"
      ]
    }
  }
}

Использование аутентификации через сервисный аккаунт

Чтобы использовать аутентификацию через сервисный аккаунт, укажите аргументы --ydb-auth-mode и --ydb-sa-key-file:

{
  "mcpServers": {
    "ydb": {
      "command": "uvx",
      "args": [
        "ydb-mcp",
        "--ydb-endpoint", "grpc://localhost:2136",
        "--ydb-database", "/local",
        "--ydb-auth-mode", "service-account",
        "--ydb-sa-key-file", "~/sa_key.json"
      ]
    }
  }
}

Related MCP server: GreptimeDB MCP Server

Доступные инструменты

YDB MCP предоставляет следующие инструменты для взаимодействия с базами данных YDB:

• ydb_query: Выполнение SQL-запроса к базе данных YDB

  • Параметры:

    • sql: Строка SQL-запроса для выполнения

• ydb_query_with_params: Выполнение параметризованного SQL-запроса с параметрами в формате JSON

  • Параметры:

    • sql: Строка SQL-запроса с плейсхолдерами параметров

    • params: JSON-строка, содержащая значения параметров

• ydb_explain_query: Объяснение SQL-запроса (возвращает план выполнения)

  • Параметры:

    • sql: Строка SQL-запроса для объяснения

• ydb_explain_query_with_params: Объяснение параметризованного SQL-запроса

  • Параметры:

    • sql: Строка SQL-запроса с плейсхолдерами параметров

    • params: JSON-строка, содержащая значения параметров

• ydb_list_directory: Список содержимого директории в YDB

  • Параметры:

    • path: Путь к директории YDB для вывода списка

• ydb_describe_path: Получение подробной информации о пути в YDB (таблица, директория и т.д.)

  • Параметры:

    • path: Путь в YDB для описания

• ydb_status: Получение текущего статуса соединения с YDB

Создание пользовательских MCP-серверов

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

Зачем создавать пользовательский сервер?

• Безопасность — ограничьте LLM фиксированным набором запросов только для чтения вместо предоставления возможности выполнения произвольного SQL.

• Специфика предметной области — предоставьте модели инструменты, соответствующие вашей бизнес-логике, а не примитивы базы данных.

• Простота — меньше инструментов означает меньше двусмысленности для модели.

Доступные методы

Переопределите или вызовите их в своем подклассе:

Аргумент params — это обычный dict. Ключи без префикса $ получат его автоматически. Чтобы указать явный тип YDB, используйте кортеж (value, "TypeName") — например, {"id": (42, "Int64")}.

Управление общими инструментами

Используйте атрибут класса generic_tools, чтобы управлять тем, какие встроенные инструменты регистрируются:

YDBGenericTool — это строковое перечисление (enum) — доступные значения: QUERY, QUERY_WITH_PARAMS, EXPLAIN, EXPLAIN_WITH_PARAMS, STATUS, LIST_DIRECTORY, DESCRIBE_PATH.

Пример

# my_server.py
from ydb_mcp import YDBMCPServer, YDBGenericTool, serialize_ydb_response


class OrdersServer(YDBMCPServer):
    """Minimal read-only MCP server for the orders service."""

    generic_tools = {YDBGenericTool.STATUS}  # keep status check for diagnostics

    def __init__(self, **kwargs):
        super().__init__(**kwargs)

        @self.tool()
        async def get_order(order_id: str) -> str:
            """Fetch a single order by ID."""
            rows = await self.execute(
                "SELECT * FROM orders WHERE id = $id",
                {"id": order_id},
            )
            return serialize_ydb_response(rows)

        @self.tool()
        async def list_recent_orders(limit: int = 10) -> str:
            """Return the most recent orders."""
            rows = await self.execute(
                "SELECT * FROM orders ORDER BY created_at DESC LIMIT $limit",
                {"limit": limit},
            )
            return serialize_ydb_response(rows)


if __name__ == "__main__":
    OrdersServer(
        endpoint="grpc://localhost:2136",
        database="/local",
    ).run()

Запустите его напрямую:

python my_server.py

Или подключите его как MCP-сервер в конфигурации вашего клиента:

{
  "mcpServers": {
    "orders": {
      "command": "python",
      "args": ["my_server.py"]
    }
  }
}

Разработка

Проект использует Make в качестве основного инструмента разработки, обеспечивая согласованный интерфейс для общих задач разработки.

Доступные команды Make

Проект включает в себя комплексный Makefile с различными командами для задач разработки. Каждая команда разработана для оптимизации рабочего процесса разработки и обеспечения качества кода:

• make all: Последовательный запуск clean, lint и test (цель по умолчанию)

• make clean: Удаление всех артефактов сборки и временных файлов

• make test: Запуск всех тестов с использованием pytest

  • Можно настроить с помощью переменных окружения:

    • LOG_LEVEL (по умолчанию: WARNING) - Управление детализацией вывода тестов (DEBUG, INFO, WARNING, ERROR)

• make unit-tests: Запуск только модульных тестов с подробным выводом

  • Можно настроить с помощью переменных окружения:

    • LOG_LEVEL (по умолчанию: WARNING) - Управление детализацией вывода тестов (DEBUG, INFO, WARNING, ERROR)

• make integration-tests: Запуск только интеграционных тестов с подробным выводом

  • Можно настроить с помощью переменных окружения:

    • YDB_ENDPOINT (по умолчанию: grpc://localhost:2136)

    • YDB_DATABASE (по умолчанию: /local)

    • MCP_HOST (по умолчанию: 127.0.0.1)

    • MCP_PORT (по умолчанию: 8989)

    • LOG_LEVEL (по умолчанию: WARNING) - Управление детализацией вывода тестов (DEBUG, INFO, WARNING, ERROR)

• make run-server: Запуск сервера YDB MCP

  • Можно настроить с помощью переменных окружения:

    • YDB_ENDPOINT (по умолчанию: grpc://localhost:2136)

    • YDB_DATABASE (по умолчанию: /local)

  • Дополнительные аргументы можно передать с помощью ARGS="your args"

• make lint: Запуск всех проверок линтинга (flake8, mypy, black, isort)

• make format: Форматирование кода с помощью black и isort

• make install: Установка пакета в режиме разработки

• make dev: Установка пакета в режиме разработки со всеми зависимостями для разработки

Управление детализацией тестов

По умолчанию тесты запускаются с минимальным выводом (уровень WARNING), чтобы сохранить чистоту вывода. Вы можете управлять детализацией вывода тестов с помощью переменной окружения LOG_LEVEL:

# Run all tests with debug output
make test LOG_LEVEL=DEBUG

# Run integration tests with info output
make integration-tests LOG_LEVEL=INFO

# Run unit tests with warning output (default)
make unit-tests LOG_LEVEL=WARNING

Доступные уровни логирования:

• DEBUG: Показать все отладочные сообщения, полезно для детального отслеживания выполнения тестов

• INFO: Показать информационные сообщения и выше

• WARNING: Показать только предупреждения и ошибки (по умолчанию)

• ERROR: Показать только сообщения об ошибках