Apache Doris

Apache Doris MCP Server

English | 简体中文

Apache Doris MCP Server предоставляет доступ только для чтения к возможностям Apache Doris для MCP-хостов и ИИ-агентов через MCP 2026-07-28. Версия 1.0 заменяет большую плоскую поверхность инструментов восемью стабильными доменами и пятьюдесятью пятью дочерними возможностями с прогрессивным раскрытием, сохраняя при этом явными доступность во время выполнения, авторизацию, входные схемы, выходные схемы и поведение при сбоях.

Статус релиза

Версия пакета — 1.0.0. Совместимость с протоколом MCP 2026-07-28 на master общедоступна (GA) для Streamable HTTP и stdio. Это заявление GA ограничено совместимостью протокола; классификатор Python-пакета остаётся Beta, и задокументированные ограничения развёртывания по-прежнему действуют.

Перед обновлением прочтите примечания к релизу 1.0, руководство по миграции на 1.0 и сгенерированный реестр 8 доменов/55 дочерних возможностей. Подробная запись о релизе — Issue #189.

Архитектура вкратце

MCP Host
  -> stdio or Streamable HTTP
  -> transport security and authentication
  -> MCP protocol validation and authorization
  -> stable domain discovery
  -> route-aware Doris capability detection
  -> exact child dispatch and read-only runtime
  -> request-specific Doris route and RBAC
  -> bounded, schema-validated result

Режим по умолчанию hierarchical предоставляет следующие домены:

Домен	Дочерние возможности	Ответственность
doris_catalog	5	каталоги, базы данных, таблицы, контекст таблицы, размер
doris_query	7	запрос, explain, profile, диагностика, медленные запросы, явный ADBC
doris_cluster	11	узлы, задачи, метрики, память, кэш, компакция, рабочие нагрузки
doris_pipeline	5	приём данных, материализованные представления, свежесть, зависимости
doris_search	4	текстовый/векторный/гибридный поиск, анализаторы, индексы, диагностика
doris_governance	8	качество, хранение, происхождение данных, аудит, UDF, сопоставление авторизации
doris_lakehouse	3	внешние каталоги, lakehouse-таблицы, Variant
doris_semantic	12	опциональная привязка Apache Ossie и потребление MetricFlow

Вызовите домен с {}, чтобы обнаружить его авторизованные дочерние возможности и точные схемы. Вызовите тот же домен снова с child_tool, arguments и возвращённым manifest_version. Хосты, которые не могут использовать прогрессивное раскрытие, могут установить MCP_TOOL_EXPOSURE_MODE=flat до запуска; это раскрывает те же 55 дочерних возможностей под формальными именами без коллизий и не восстанавливает псевдонимы до версии 1.0.

См. Архитектура, Жизненный цикл запроса и Домены инструментов.

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

Требования:

• Python 3.12 или новее;
• Apache Doris 2.0.0 или новее;
• сетевой доступ к MySQL-эндпоинту Doris FE, обычно порт 9030.

Установите закреплённый релиз:

pip install doris-mcp-server==1.0.0

doris-mcp-server запускает Server. doris-mcp-client — это отдельный клиент; эти две команды не взаимозаменяемы.

Настройте маршрут Doris:

export DORIS_HOST=127.0.0.1
export DORIS_PORT=9030
export DORIS_USER=mcp_reader
export DORIS_PASSWORD='replace-me'
export DORIS_DATABASE=information_schema

Запустите Streamable HTTP на loopback:

doris-mcp-server \
  --transport http \
  --host 127.0.0.1 \
  --port 3000

Эндпоинты:

• MCP: POST http://127.0.0.1:3000/mcp
• устаревший MCP (по желанию): POST http://127.0.0.1:3000/mcp/legacy
• проверка живости: GET http://127.0.0.1:3000/live
• готовность на основе Doris: GET http://127.0.0.1:3000/ready

Хосты, ограниченные Streamable HTTP эпохи рукопожатия, включая Dify 1.16.1 с MCP 2025-06-18, должны установить ENABLE_LEGACY_HTTP_ADAPTER=true и подключаться к /mcp/legacy. Адаптер изменяет только границу протокола; он сохраняет те же инструменты 1.0, авторизацию, шлюзы возможностей и выполнение только для чтения.

Или запустите stdio для локального хоста:

doris-mcp-server --transport stdio

См. полный Быстрый старт и Руководство по интеграции хостов.

Граница безопасности

• Встроенный каталог 1.0 доступен только для чтения; doris_admin зарезервирован и не регистрируется.
• Поддерживаются статические токены, JWT, внешние OAuth/OIDC и OAuth на основе Doris в рамках взаимно проверенных границ конфигурации.
• Обнаружение доменов и выполнение дочерних возможностей используют точные идентификаторы авторизации.
• Doris RBAC остаётся конечным органом для видимых объектов и данных.
• Форма SQL, идентификаторы, параметры, таймаут, строки, байты и схемы результатов ограничены до того, как данные покинут Server.
• Секреты и ошибки серверной части скрываются из публичных результатов и журналов.
• HTTP на не-loopback адресах требует аутентификации, если не включён явный опасный override для разработки.

Прочтите Модель безопасности и разрешений и Руководство по детальному доступу Doris.

Граница надёжности

Server использует детерминированные манифесты и ошибки, подписанные истекающие курсоры, снимки возможностей с учётом маршрута, ограниченный fallback на устаревшие данные, маршрутизацию соединений с учётом запроса, отказоустойчивость при нескольких FE, разделение проверки живости/готовности, валидацию выходных схем и очищенное распространение трассировок. Неподдерживаемые или неправильно настроенные возможности остаются обнаруживаемыми с помощью callable=false и завершаются отказом при вызове.

Текущие ограничения включают локальный для процесса OAuth на основе Doris, только явный ADBC, отключённый по умолчанию и завершающийся отказом на маршрутах с привязкой к токену, опциональную привязку Ossie только для чтения, опциональный sidecar-компилятор MetricFlow, чей SQL должен выполняться через ограниченную среду выполнения запросов MCP, и доставку нативного происхождения данных по принципу best-effort. См. Надёжность и ограничения.

Документация

Корневой README — это намеренно точка входа. Двуязычная система документации индексируется по адресу:

• Английская документация
• 简体中文文档

Основные руководства:

• Архитектура
• Поток запросов и данных
• Домены инструментов
• Доступность возможностей
• Матрица возможностей версий Doris
• Интеграция MetricFlow
• Контракт MCP 2026-07-28
• Модель безопасности
• Развёртывание
• Надёжность и ограничения
• Устранение неполадок
• Справочник по конфигурации
• Интеграции хостов
• Пользовательские поставщики инструментов
• Участие в разработке

Разработка

git clone https://github.com/apache/doris-mcp-server.git
cd doris-mcp-server
uv sync --group dev
uv run pytest

Сгенерированные артефакты должны оставаться синхронизированными:

uv run python generate_tool_catalog.py --check
uv lock --check

См. Участие в разработке и проверка.

Лицензия

Apache License 2.0. См. LICENSE.txt и NOTICE.