Перейти к содержимому
Последнее обновление

Сервер MCP

Кратко Apache Doris MCP Server (doris-mcp-server 1.0) — это сервис на Python, который поддерживает Model Context Protocol через stdio или Streamable HTTP. Он предоставляет ИИ-ассистентам доступ к Apache Doris через восемь доменов инструментов только для чтения (catalog, query, cluster, pipeline, search, governance, lakehouse и semantic) с 55 функциями, которые ассистент обнаруживает по мере необходимости. Установите его с помощью pip, настройте подключение к нему в Claude Desktop, Cursor или любом клиенте MCP, и модель сможет изучать схемы и выполнять SQL-запросы только для чтения с заданными ограничениями на реальном кластере без разработки собственной интеграции.

Apache Doris MCP Server: Doris MCP Server 1.0 предоставляет Claude Desktop, Cursor и другим клиентам MCP доступ к кластеру Apache Doris только для чтения через восемь доменов инструментов с 55 функциями.

Зачем использовать Apache Doris MCP Server?​

Apache Doris MCP Server избавляет компании от необходимости с нуля разрабатывать одну и ту же интеграцию между чат-ассистентом и базой данных. Без него пришлось бы разворачивать небольшой сервис на Python, создавать обёртки для вспомогательных SQL-функций, управлять учётными данными, тайм-аутами и усечением результатов, принудительно ограничивать доступ чтением, а затем писать отдельный связующий код для Claude Desktop, Cursor и очередного клиента, который появится в следующем месяце. Большая часть этой работы шаблонная, но возможностей допустить ошибку много: необдуманный DELETE от LLM может привести к реальному сбою. Средства ИИ внутри базы данных, SQL-функции LLM и эмбеддинги, дополняют описанные здесь возможности со стороны SQL.

Anthropic представила MCP в ноябре 2024 года, чтобы стандартизировать эту работу. Серверы предоставляют инструменты с типизированными входными и выходными данными; клиенты (Claude Desktop, Cursor, Cline, Continue, Zed и другие) используют один и тот же протокол; модель решает, когда вызывать инструменты. Разработчики баз данных последовали этому примеру: ClickHouse, Snowflake, MotherDuck, BigQuery и Supabase уже выпускают официальные серверы.

Apache Doris MCP Server — аналогичное решение для Apache Doris. Он разрабатывается в отдельном репозитории (apache/doris-mcp-server), распространяется через PyPI под лицензией Apache 2.0, а для его запуска достаточно нескольких строк в конфигурации любого клиента MCP.

Что такое Apache Doris MCP Server?​

Apache Doris MCP Server — это сервис на Python 3.12+, который подключается к Apache Doris 2.0 или более поздней версии по протоколу MySQL. В версии 1.0 прежний плоский список инструментов заменён восемью стабильными доменами: каждый домен представляет собой один инструмент MCP, а доступные в нём операции обнаруживаются по запросу, поэтому модель начинает работу с восьми элементов вместо 55. Сервер проверяет, какие операции действительно поддерживает подключённый кластер, выполняет только операции чтения и возвращает JSON, прошедший проверку по схеме.

Основные термины

  • MCP (Model Context Protocol): открытый протокол JSON-RPC 2.0 для подключения клиентов LLM к внешним инструментам и данным. Инструменты — это типизированные функции; ресурсы — данные только для чтения; промпты — шаблоны для повторного использования.
  • Домен: один из восьми инструментов, которые регистрирует сервер: doris_catalog, doris_query, doris_cluster, doris_pipeline, doris_search, doris_governance, doris_lakehouse и doris_semantic.
  • Дочерняя функция: операция внутри домена, например list_tables в doris_catalog, execute_query и explain_query в doris_query или search_data в doris_search. Всего их 55; полный список приведён в реестре инструментов.
  • Постепенное раскрытие возможностей: режим hierarchical, используемый по умолчанию. Ассистент вызывает домен с пустым объектом, чтобы получить список его дочерних функций, схемы их входных данных и сведения о доступности каждой функции в этом кластере, а затем снова вызывает тот же домен с child_tool и arguments. Для клиентов, которые не поддерживают такой двухэтапный вызов, можно установить MCP_TOOL_EXPOSURE_MODE=flat: тогда все 55 дочерних функций будут доступны как отдельные инструменты.
  • Транспорт: stdio запускает сервер как дочерний процесс локального клиента. Streamable HTTP запускает его как постоянно работающий сервис с конечной точкой /mcp и проверками работоспособности /live и /ready; для прослушивания HTTP за пределами loopback требуется аутентификация (статические токены, JWT или OAuth/OIDC).
  • Среда выполнения только для чтения: встроенные функции никогда не выполняют запись. Инструкции, которые могут изменить данные, отклоняются, а для каждого результата до его отправки с сервера ограничиваются число строк, объём в байтах и время выполнения. Доступ подключённой учётной записи к данным по-прежнему определяется привилегиями Doris.

Как работает Apache Doris MCP Server?​

Apache Doris MCP Server работает по циклу из пяти шагов: клиент подключается к серверу, сервер подключается к кластеру, модель обнаруживает домен, вызывает дочернюю функцию и получает результаты в формате JSON с учётом заданных ограничений.

  1. Клиент подключается к серверу. В режиме stdio клиент MCP запускает doris-mcp-server --transport stdio как дочерний процесс и обменивается с ним данными через stdin/stdout. В режиме HTTP вы запускаете doris-mcp-server --transport http --host 127.0.0.1 --port 3000, а клиент отправляет запросы на http://127.0.0.1:3000/mcp.
  2. Сервер подключается к Apache Doris. Он считывает DORIS_HOST, DORIS_PORT, DORIS_USER, DORIS_PASSWORD и DORIS_DATABASE из переменных окружения (или соответствующих флагов --doris-*), открывает соединение по протоколу MySQL с FE на порту 9030 и проверяет, какие функции поддерживаются версией и конфигурацией кластера.
  3. Модель обнаруживает нужные возможности. Клиент получает список из восьми инструментов-доменов. Для вопроса «в каких таблицах хранятся данные о заказах?» модель вызывает doris_catalog с {} и получает пять дочерних функций, включая list_tables и get_table_context, со статусом каждой функции в этом кластере. Функции, зависящие от дополнительных интеграций, например MetricFlow в doris_semantic, возвращают статус misconfigured, пока вы их не настроите; они остаются видимыми, но при вызове отказывают в выполнении.
  4. Модель вызывает дочернюю функцию. Она снова вызывает doris_catalog с child_tool: "list_tables", затем doris_query с child_tool: "execute_query" и написанным ею SQL-запросом. Сервер проверяет аргументы по схеме дочерней функции и отклоняет всё, что не ограничивается чтением: для DELETE возвращается SQL operation DELETE is not read-only.
  5. Результаты возвращаются в формате JSON с учётом ограничений. По умолчанию запрос возвращает не более 100 строк и 1 MB данных и выполняется не дольше 30 секунд. При вызове можно запросить больше в пределах ограничений сервера (max_rows до 100,000, timeout_ms до 300,000), поэтому неосторожный SELECT * не переполнит контекстное окно модели.

Быстрый старт​

Установите сервер (требуется Python 3.12 или более поздняя версия), затем создайте данные и учётную запись с доступом к ним только для чтения:

pip install doris-mcp-server==1.0.0
which doris-mcp-server        # note the absolute path
CREATE DATABASE demo;
CREATE TABLE demo.orders (
  order_id   INT NOT NULL,
  region     VARCHAR(16) NOT NULL,
  amount     DECIMAL(10, 2) NOT NULL,
  created_at DATETIME NOT NULL
) DUPLICATE KEY(order_id) DISTRIBUTED BY HASH(order_id) BUCKETS 1;

INSERT INTO demo.orders VALUES
  (1, 'emea', 120.00, '2026-10-01 09:00:00'),
  (2, 'apac',  80.50, '2026-10-01 10:30:00'),
  (3, 'emea',  42.25, '2026-10-02 14:10:00'),
  (4, 'amer', 310.00, '2026-10-03 08:45:00');

-- Never hand an LLM a write-capable account
CREATE USER 'mcp_reader'@'%' IDENTIFIED BY 'replace-me';
GRANT SELECT_PRIV ON internal.demo.* TO 'mcp_reader'@'%';

Зарегистрируйте сервер в конфигурации вашего клиента MCP (файл и его расположение зависят от клиента). Используйте абсолютный путь из вывода which doris-mcp-server: клиенты с графическим интерфейсом не наследуют PATH или виртуальное окружение вашей оболочки.

{
  "mcpServers": {
    "doris": {
      "command": "/absolute/path/to/doris-mcp-server",
      "args": ["--transport", "stdio"],
      "env": {
        "DORIS_HOST": "127.0.0.1",
        "DORIS_PORT": "9030",
        "DORIS_USER": "mcp_reader",
        "DORIS_PASSWORD": "replace-me",
        "DORIS_DATABASE": "demo"
      }
    }
  }
}

Ожидаемый результат

После перезапуска клиент показывает один сервер doris с восемью инструментами: doris_catalog, doris_cluster, doris_governance, doris_lakehouse, doris_pipeline, doris_query, doris_search и doris_semantic. Спросите «какова выручка по каждому региону в demo.orders?», и ассистент вызовет doris_query с {}, чтобы обнаружить execute_query, а затем выполнит вызов:

{
  "child_tool": "execute_query",
  "arguments": {
    "database": "demo",
    "sql": "SELECT region, SUM(amount) AS revenue FROM orders GROUP BY region ORDER BY revenue DESC"
  }
}

Строки возвращаются вместе с применёнными ограничениями:

"rows": [
  {"region": "amer", "revenue": "310.00"},
  {"region": "emea", "revenue": "162.25"},
  {"region": "apac", "revenue": "80.50"}
],
"limits": {"max_bytes": 1048576, "max_rows": 100, "timeout_seconds": 30}

Попросите «удали заказы для apac», и тот же вызов вернёт ошибку SQL operation DELETE is not read-only.; у mcp_reader также нет привилегии записи.

Когда стоит использовать Apache Doris MCP Server?​

Apache Doris MCP Server подходит для сценариев с ИИ-ассистентами, в которых преобладает чтение данных, особенно для изучения схем, анализа по запросу, поиска и расследования инцидентов дежурными инженерами на реальном кластере.

Подходящие сценарии

  • Написание SQL с помощью ИИ в Cursor или Claude Code: ассистент читает реальную схему (doris_catalog → get_table_context) и составляет запрос, не гадая о названиях столбцов.
  • Разовые сеансы «задайте вопрос своим данным» в Claude Desktop, особенно для инженеров, которым иначе пришлось бы вручную вставлять схемы в чат.
  • Ассистенты для дежурных инженеров: doris_query выводит медленные запросы, объясняет планы и читает профили выполнения, а doris_cluster предоставляет сведения об узлах, compaction и группах рабочей нагрузки, что помогает ассистенту установить причину сбоя дашборда.
  • Ассистенты с возможностями поиска: doris_search выполняет текстовый, векторный и гибридный поиск через search_data, а также проверяет анализаторы и индексы, поэтому модели не приходится вручную писать SQL с MATCH_* или ANN.

Неподходящие сценарии

  • Запись данных в производственной среде. Сервер версии 1.0 изначально предназначен только для чтения, а выполнять INSERT или UPDATE через LLM не следует. Для записи используйте полноценное приложение.
  • Недоверенные данные. Злоумышленник, способный поместить текст в строку, которую позже прочитает ассистент, может попытаться внедрить инструкции в промпт. Сообщество уже задокументировало реальные инциденты с серверами MCP для Postgres; воспринимайте всё, что получает модель, как данные, а не инструкции, и проверяйте вызовы инструментов перед выполнением. См. рекомендации по безопасности MCP.
  • Просмотр таблиц с миллионами строк. Результаты инструментов попадают в контекстное окно модели, а стоимость растёт пропорционально числу токенов. Сохраняйте ограничение числа строк по умолчанию, просите модель писать агрегирующие запросы, а для работы с данными за пределами небольшой выборки используйте блокнот.
  • Многопользовательские кластеры без разграничения доступа на уровне строк. Сервер подключается с настроенной вами учётной записью Doris; модель видит всё, что доступно этой учётной записи. Создайте отдельного пользователя с доступом только для чтения, ограничьте его права на базы данных и никогда не используйте учётную запись с расширенными привилегиями.
  • Рабочие процессы, выходящие за рамки чтения. Эти 55 функций охватывают работу со схемами и запросами, эксплуатационные задачи и поиск, но собственные рабочие процессы, пакетные задания или NL2SQL с вашими промптами следует реализовывать в интеграции, которая обращается к Apache Doris напрямую, или в собственном поставщике инструментов.

Дополнительные материалы​

Report issue