Apache Doris

официальный

MCP-сервер для Apache Doris, реального хранилища данных на основе MPP.

GitHub

320

Что можно делать с Apache Doris MCP?

Run SQL queries against Apache Doris — Ask the AI to execute ad-hoc SQL and return results using doris_query.execute_query.
Explore database schemas and metadata — Discover tables, columns, and data types across internal and external catalogs via the schema extraction tools.
Convert natural language to SQL (NL2SQL) — Describe what data you need and let the AI generate and run the corresponding Doris SQL.
Analyze query performance — Request SQL explain plans and profiling information to understand and optimize query execution.
Monitor cluster health and metrics — Retrieve memory, connection, and node-level metrics from Doris FE and BE instances through the monitoring tools module.

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

Doris MCP Server

English | 简体中文

Doris MCP (Model Context Protocol) Server — это бэкенд-сервис, созданный на Python и FastAPI. Он реализует протокол MCP, позволяя клиентам взаимодействовать с ним через определенные «инструменты». В первую очередь он предназначен для подключения к базам данных Apache Doris, потенциально используя большие языковые модели (LLM) для таких задач, как преобразование запросов на естественном языке в SQL (NL2SQL), выполнение запросов, а также управление и анализ метаданных.

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

Текущие метаданные пакета и последний Git-тег: 0.6.1. Ветка master также содержит изменения, внесенные после этого тега; эти изменения записаны в разделе Unreleased до тех пор, пока не будет выбрана и опубликована следующая версия.

Совместимость с протоколом MCP 2026-07-28 на master является общедоступной (GA) для Streamable HTTP и stdio. Поддерживаемый протокольный контракт прошел полный набор тестов с обработкой предупреждений как ошибок, официальный набор тестов на соответствие без сохранения состояния, чистую установку wheel и реальные тесты Apache Doris по обоим транспортным протоколам.

Это заявление GA относится к совместимости протоколов на поддерживаемых транспортах. Метаданные пакета проекта остаются в статусе Beta, и это не расширяет поддерживаемые варианты развертывания и не снимает задокументированные эксплуатационные ограничения. Перед развертыванием вне контролируемой среды ознакомьтесь с журналом изменений, матрицей поддержки протоколов и ограничениями развертывания.

Основные нововведения версии 0.6.0

🔐 Корпоративная система аутентификации: Революционная конфигурация базы данных с привязкой к токену с комплексной поддержкой аутентификации Token, JWT и OAuth, обеспечивающая безопасный многопользовательский доступ с детальными переключателями управления и корпоративными настройками безопасности по умолчанию.
⚡ Немедленная проверка базы данных: Проверка конфигурации базы данных в реальном времени при подключении, сокращающая время блокировки запросов и обеспечивающая более раннюю обратную связь при неверных конфигурациях.
🔄 Управление конфигурацией с горячей перезагрузкой: Обновление конфигурации во время выполнения с интеллектуальной горячей перезагрузкой tokens.json, автоматической повторной проверкой токенов и комплексной обработкой ошибок с механизмами отката.
🏗️ Продвинутая архитектура подключений: Кэширование сессий и оптимизация пула соединений с интеллектуальным пересозданием пула и автоматическим управлением ресурсами.
🌐 Масштабируемость с несколькими рабочими процессами: Обработка HTTP-запросов без сохранения состояния с поддержкой нескольких рабочих процессов; ограничения на количество рабочих процессов, специфичные для аутентификации, по-прежнему применяются.
🔒 Улучшенная система безопасности: Комплексный контроль доступа и проверка безопасности SQL с немедленной проверкой, ролевыми разрешениями и улучшенными шаблонами обнаружения инъекций.
🛠️ Унифицированная система конфигурации: Оптимизированное управление конфигурацией с правильным приоритетом командной строки, улучшенной совместимостью с Docker и поддержкой кроссплатформенного развертывания.
📊 Панель управления токенами: Полное управление жизненным циклом токенов с созданием, отзывом, статистикой и комплексными аудиторскими следами для корпоративного управления токенами.
🌐 Веб-интерфейс управления: Безопасное администрирование токенов только с localhost с интуитивно понятной панелью, привязкой конфигурации базы данных, операциями в реальном времени и корпоративным контролем доступа.

Примечание к релизу: В версии 0.6.0 представлены функции аутентификации, управления токенами, подключения и поддержки нескольких рабочих процессов, описанные выше. Эти функции не отменяют статус Beta или ограничения развертывания, задокументированные для текущей кодовой базы.

Что также включено из версии 0.5.1

🔥 Критическое исправление подключения at_eof: Полное устранение ошибок пула соединений с помощью интеллектуального мониторинга работоспособности и самовосстановления.
🔧 Корпоративная система логирования: Разделение файлов по уровням с автоматической очисткой и временными метками с миллисекундной точностью.
📊 Расширенный набор инструментов аналитики данных: 7 корпоративных инструментов управления данными, включая анализ качества, отслеживание происхождения и мониторинг производительности.
🏃‍♂️ Высокопроизводительная интеграция ADBC: Поддержка Apache Arrow Flight SQL с повышением производительности в 3-10 раз для больших наборов данных.
⚙️ Улучшенное управление конфигурацией: Полная система конфигурации ADBC с интеллектуальной проверкой параметров.

Основные возможности

Реализация протокола MCP: Предоставляет стандартные интерфейсы MCP, поддерживая вызовы инструментов, управление ресурсами и взаимодействие с подсказками.
Streamable HTTP-коммуникация: Унифицированная конечная точка HTTP, поддерживающая как связь запрос/ответ, так и потоковую передачу для оптимальной производительности и надежности.
Stdio-коммуникация: Режим стандартного ввода/вывода для прямой интеграции с MCP-клиентами, такими как Cursor.
Архитектура корпоративного уровня: Модульная конструкция с комплексной функциональностью:
- Менеджер инструментов: Централизованная регистрация и маршрутизация инструментов с унифицированными интерфейсами (doris_mcp_server/tools/tools_manager.py)
- Модуль расширенных инструментов мониторинга: Расширенное отслеживание памяти, сбор метрик и гибкое обнаружение узлов BE с модульным, расширяемым дизайном
- Инструменты информации о запросах: Улучшенное объяснение и профилирование SQL с настраиваемым усечением содержимого, экспортом файлов для вложений LLM и расширенной аналитикой запросов
- Менеджер ресурсов: Управление ресурсами и предоставление метаданных (doris_mcp_server/tools/resources_manager.py)
- Менеджер подсказок: Интеллектуальные шаблоны подсказок для анализа данных (doris_mcp_server/tools/prompts_manager.py)
Расширенные возможности базы данных:
- Выполнение запросов: Высокопроизводительное выполнение SQL с расширенным кэшированием и оптимизацией, повышенной стабильностью соединения и механизмами автоматических повторов (doris_mcp_server/utils/query_executor.py)
- Управление безопасностью: Комплексная проверка безопасности SQL с настраиваемыми заблокированными ключевыми словами, защитой от SQL-инъекций, маскированием данных и унифицированным управлением конфигурацией безопасности (doris_mcp_server/utils/security.py)
- Извлечение метаданных: Исчерпывающие метаданные базы данных с поддержкой федерации каталогов (doris_mcp_server/utils/schema_extractor.py)
- Анализ производительности: Расширенный анализ столбцов, мониторинг производительности и инструменты анализа данных (doris_mcp_server/utils/analysis_tools.py)
Поддержка федерации каталогов: Полная поддержка сред с несколькими каталогами (внутренние таблицы Doris и внешние источники данных, такие как Hive, MySQL и т. д.)
Корпоративная безопасность: Комплексная система безопасности с аутентификацией, авторизацией, защитой от SQL-инъекций и возможностями маскирования данных с поддержкой настройки через переменные окружения.
Веб-управление токенами: Безопасный интерфейс только для localhost для полного управления жизненным циклом токенов с привязкой к базе данных, статистикой в реальном времени и корпоративным контролем доступа (doris_mcp_server/auth/token_handlers.py)
Унифицированная среда конфигурации: Централизованное управление конфигурацией через config.py с комплексной проверкой, стандартизированными именами параметров и интеллектуальной обработкой базы данных по умолчанию с автоматическим переходом на information_schema

Системные требования

Python: 3.12+
База данных: Данные для подключения к Apache Doris (хост, порт, пользователь, пароль, база данных)

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

Установка из PyPI

# Install the latest version
pip install doris-mcp-server

# Install specific version
pip install doris-mcp-server==0.6.1

💡 Пакетные команды: doris-mcp-server запускает MCP-сервер. doris-mcp-client — это отдельный клиент для подключения к серверу через Streamable HTTP или stdio; эти две команды не взаимозаменяемы.

Запуск в режиме Streamable HTTP (веб-сервис)

Основной режим связи, обеспечивающий оптимальную производительность и надежность:

# Full configuration with database connection
doris-mcp-server \
    --transport http \
    --host 127.0.0.1 \
    --port 3000 \
    --db-host 127.0.0.1 \
    --db-port 9030 \
    --db-user root \
    --db-password your_password

Запуск в режиме Stdio (для Cursor и других MCP-клиентов)

Режим стандартного ввода/вывода для прямой интеграции с MCP-клиентами:

# For direct integration with MCP clients like Cursor
doris-mcp-server --transport stdio

🌐 Интерфейс управления токенами (новое в версии 0.6.0)

Доступ к веб-панели управления токенами для администрирования токенов корпоративного уровня:

Требования безопасного доступа

Доступ только с localhost: Интерфейс ограничен 127.0.0.1 и ::1 для максимальной безопасности.
Аутентификация администратора: Требуется TOKEN_MANAGEMENT_ADMIN_TOKEN для доступа.

Предварительные требования к конфигурации:

# Generate separate high-entropy credentials; do not commit them.
export TOKEN_ADMIN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
export TOKEN_MANAGEMENT_ADMIN_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
export ENABLE_HTTP_TOKEN_MANAGEMENT=true
export ENABLE_TOKEN_AUTH=true
export TOKEN_MANAGEMENT_ALLOWED_IPS=127.0.0.1,::1

Доступ к интерфейсу

Запросы на управление принимают токен администратора только в HTTP-заголовке. Токены в строке запроса отклоняются и не должны размещаться в URL-адресах, истории браузера или журналах доступа.

curl -H "Authorization: Bearer $TOKEN_MANAGEMENT_ADMIN_TOKEN" \
  http://127.0.0.1:3000/token/stats

Необязательная страница /token/management должна открываться через клиент или локальный прокси, который предоставляет тот же заголовок. Ее API-запросы используют поле пароля на странице и не сохраняют и не передают токен в URL-адресах.

Доступные операции

📊 Статистика токенов: Обзор активных, просроченных и общего количества токенов в реальном времени.
➕ Создание токенов:
- Основная информация (ID, описание, срок действия)
- Привязка к базе данных (хост, порт, пользователь, пароль, база данных)
- Пользовательские значения токенов или автоматически сгенерированные безопасные токены
📋 Управление токенами:
- Список всех токенов со статусом привязки к базе данных
- Отзыв токена в один клик
- Автоматическая очистка просроченных токенов
🔒 Корпоративная безопасность:
- Все операции требуют аутентификации администратора
- Проверка IP в реальном времени
- Полное аудиторское логирование
- Сохранение только дайджеста в tokens.json; открытый текст возвращается один раз при создании токена
- Согласованность нескольких рабочих процессов за счет общей для процессов блокировки, атомарных обновлений read-modify-write и записей об отзыве только с дайджестом

🔐 Примечание по безопасности: Интерфейс предназначен только для администрирования с localhost. К нему нельзя получить удаленный доступ, что обеспечивает максимальную безопасность операций по управлению токенами.

Проверка установки

# Check installation
doris-mcp-server --version
doris-mcp-client --version
doris-mcp-server --help
doris-mcp-client --help

# Test HTTP mode (in another terminal)
curl --fail http://localhost:3000/live
curl --fail http://localhost:3000/ready

Переменные окружения (необязательно)

Вместо аргументов командной строки вы можете использовать переменные окружения:

# Basic Database Configuration
export DORIS_HOST="127.0.0.1"
export DORIS_PORT="9030"
export DORIS_USER="root"
export DORIS_PASSWORD="your_password"

# Keep the isolated legacy HTTP migration adapter disabled unless an
# identified 2025-11-25 client still needs /mcp/legacy.
export ENABLE_LEGACY_HTTP_ADAPTER=false

# Bound each resources/list, tools/list, and prompts/list response.
export MCP_LIST_PAGE_SIZE=100
# Expose eight progressive-disclosure domains by default. Set flat to expose
# the same 47 children under exact collision-free formal names.
export MCP_TOOL_EXPOSURE_MODE=hierarchical
# Load only these installed custom tool providers. Empty disables extensions.
export MCP_TOOL_PROVIDERS="orders_api"
# A launch-local key is generated automatically. Configure one shared
# high-entropy value when independently launched replicas share traffic.
export MCP_STATE_HANDLE_SECRET="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
export MCP_STATE_HANDLE_TTL_SECONDS=300

# Token Management Interface (Security-Critical)
export TOKEN_ADMIN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
export TOKEN_MANAGEMENT_ADMIN_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
export ENABLE_HTTP_TOKEN_MANAGEMENT=true
export ENABLE_TOKEN_AUTH=true
export TOKEN_MANAGEMENT_ALLOWED_IPS="127.0.0.1,::1"

# Then start with simplified command
doris-mcp-server --transport http --host 127.0.0.1 --port 3000

Аргументы командной строки

Команда doris-mcp-server поддерживает следующие аргументы:

Аргумент	Описание	По умолчанию	Обязательный
`--transport`	Режим передачи: `http` или `stdio`	`http`	Нет
`--host`	Хост HTTP-сервера (только режим HTTP)	`localhost`	Нет
`--port`	Порт HTTP-сервера (только режим HTTP)	`3000`	Нет
`--db-host`	Хост базы данных Doris	`localhost`	Нет
`--db-port`	Порт базы данных Doris	`9030`	Нет
`--db-user`	Имя пользователя базы данных Doris	`root`	Нет
`--db-password`	Пароль базы данных Doris	-	Да (если не в env)

Настройка для разработки

Для разработчиков, которые хотят собрать из исходного кода:

1. Клонирование репозитория

# Replace with the actual repository URL if different
git clone https://github.com/apache/doris-mcp-server.git
cd doris-mcp-server

2. Установка зависимостей

Группа зависимостей dev содержит инструменты для тестирования и контроля качества, используемые CI:

uv sync --frozen --group dev

Для рабочих процессов на основе pip requirements.txt содержит только производственные зависимости. requirements-dev.txt включает этот манифест времени выполнения и добавляет тот же минимальный набор инструментов для тестирования и контроля качества:

pip install -r requirements-dev.txt

Производственные образы и среды выполнения должны устанавливать только пакет или requirements.txt; pytest, линтеры, средства проверки типов и сборочные бэкенды не являются зависимостями времени выполнения.

3. Настройка переменных окружения

Скопируйте файл .env.example в .env и измените настройки в соответствии с вашей средой:

cp .env.example .env

Ключевые переменные окружения:

Подключение к базе данных:
- DORIS_HOST: Имя хоста базы данных (по умолчанию: localhost)
- DORIS_HOSTS: Упорядоченный список хостов FE MySQL для аварийного переключения в одном кластере Doris (через запятую; если заданы оба параметра, DORIS_HOST добавляется в начало)
- DORIS_PORT: Порт базы данных (по умолчанию: 9030)
- DORIS_USER: Имя пользователя базы данных (по умолчанию: root)
- DORIS_PASSWORD: Пароль базы данных
- DORIS_DATABASE: Имя базы данных по умолчанию (по умолчанию: information_schema)
- DORIS_MIN_CONNECTIONS: Минимальный размер пула соединений (по умолчанию: 5)
- DORIS_MAX_CONNECTIONS: Максимальный размер пула соединений (по умолчанию: 20)
- DORIS_FE_HTTP_HOST: Независимый HTTP-хост FE для инструментов профилирования, оценки размера таблиц и мониторинга (по умолчанию: пусто, используется DORIS_HOST)
- DORIS_FE_HTTP_HOSTS: Упорядоченный список HTTP-хостов FE для аварийного переключения в том же кластере Doris (через запятую)
- DORIS_FE_HTTP_PORT: Независимый порт HTTP API FE (по умолчанию: 8030)
- DORIS_BE_HOSTS: Явный список разрешенных HTTP-хостов BE для мониторинга (через запятую; если пусто, HTTP-метрики BE отключены)
- DORIS_BE_WEBSERVER_PORT: Порт веб-сервера BE для инструментов мониторинга (по умолчанию: 8040)
- DORIS_HTTP_CONNECT_TIMEOUT_SECONDS: Тайм-аут HTTP-соединения FE/BE (по умолчанию: 3)
- DORIS_HTTP_READ_TIMEOUT_SECONDS: Тайм-аут чтения HTTP-сокета FE/BE (по умолчанию: 15)
- DORIS_HTTP_TOTAL_TIMEOUT_SECONDS: Общий тайм-аут HTTP FE/BE (по умолчанию: 30; жесткий максимум: 60)
- DORIS_HTTP_MAX_RESPONSE_BYTES: Лимит HTTP-ответа FE/BE (по умолчанию: 4 МиБ; жесткий максимум: 16 МиБ)
- FE_ARROW_FLIGHT_SQL_PORT: Порт Arrow Flight SQL фронтенда для ADBC (Новое в v0.5.0)
- BE_ARROW_FLIGHT_SQL_PORT: Порт Arrow Flight SQL бэкенда для ADBC (Новое в v0.5.0)
Конфигурация MCP HTTP:
- ENABLE_LEGACY_HTTP_ADAPTER: Предоставить изолированный адаптер миграции 2025-11-25 по адресу /mcp/legacy (по умолчанию: false); современный трафик всегда использует POST /mcp
- MCP_LIST_PAGE_SIZE: Максимальное количество ресурсов, инструментов или подсказок, возвращаемых на страницу протокола (по умолчанию: 100; диапазон: 1-1000)
- MCP_TOOL_EXPOSURE_MODE: Режим предоставления инструментов. hierarchical возвращает восемь доменных инструментов с прогрессивным обнаружением дочерних; flat возвращает те же 47 дочерних инструментов под точными, исключающими коллизии формальными именами (по умолчанию: hierarchical)
- MCP_TOOL_PROVIDERS: Список разрешенных установленных точек входа doris_mcp_server.tool_providers через запятую (по умолчанию: пусто)
- MCP_STATE_HANDLE_SECRET: Необязательный общий высокоэнтропийный ключ (не менее 32 байт), используемый для аутентификации явных дескрипторов состояния при перекрестных вызовах
- MCP_STATE_HANDLE_TTL_SECONDS: Время жизни явного дескриптора состояния (по умолчанию: 300 секунд; диапазон: 1-3600)
Конфигурация аутентификации (Улучшено в v0.6.0):
- ENABLE_TOKEN_AUTH: Включить аутентификацию на основе токенов (по умолчанию: false)
- ENABLE_JWT_AUTH: Включить JWT-аутентификацию (по умолчанию: false)
- ENABLE_OAUTH_AUTH: Включить OAuth-аутентификацию (по умолчанию: false)
- OAUTH_ISSUER: Точный издатель внешнего сервера авторизации
- OAUTH_RESOURCE: Канонический URI защищенного ресурса MCP
- OAUTH_AUDIENCE: Ожидаемая аудитория токена доступа (по умолчанию используется OAUTH_RESOURCE)
- OAUTH_INTROSPECTION_URL: Доверенная конечная точка интроспекции токенов RFC 7662
- OAUTH_SCOPE / OAUTH_REQUIRED_SCOPE: Разрешенные и обязательные области действия внешнего OAuth
- ENABLE_DORIS_OAUTH_AUTH: Включить OAuth-аутентификацию на основе Doris (по умолчанию: false)
- DORIS_OAUTH_BASE_URL: Публичный базовый URL, используемый конечными точками обнаружения и токенов OAuth на основе Doris
- DORIS_OAUTH_CIMD_FETCH_TIMEOUT_SECONDS: Тайм-аут получения документа метаданных идентификатора клиента (по умолчанию: 5)
- DORIS_OAUTH_CIMD_MAX_DOCUMENT_BYTES: Максимальный размер документа метаданных идентификатора клиента (по умолчанию: 5120)
- DORIS_OAUTH_CIMD_DEFAULT_CACHE_SECONDS: Время жизни кэша, если документ его не предоставляет (по умолчанию: 300)
- DORIS_OAUTH_CIMD_MAX_CACHE_SECONDS: Максимальное принимаемое время жизни кэша документа (по умолчанию: 3600)
- DORIS_OAUTH_CIMD_MAX_CLIENTS: Максимальное количество обнаруженных клиентов метаданных идентификатора клиента, хранящихся в памяти (по умолчанию: 1000)
- TOKEN_FILE_PATH: Путь к файлу tokens.json для управления токенами (по умолчанию: tokens.json)
- TOKEN_HOT_RELOAD: Включить горячую перезагрузку конфигурации токенов (по умолчанию: true)
- TOKEN_HASH_ALGORITHM: Алгоритм дайджеста для вновь создаваемых статических токенов (sha256 или sha512; по умолчанию: sha256)
- TOKEN_<ID>: Явный статический токен-носитель; каждый активный токен должен быть безопасно сгенерированным значением длиной не менее 32 символов
Устаревшая конфигурация безопасности:
- AUTH_TYPE: Устаревший тип аутентификации (token/basic/oauth, устарело — используйте отдельные переключатели)
- ENABLE_SECURITY_CHECK: Включить/отключить проверку безопасности SQL (по умолчанию: true)
- BLOCKED_KEYWORDS: Список заблокированных ключевых слов SQL через запятую
- ENABLE_MASKING: Включить маскирование данных (по умолчанию: true)
- MAX_RESULT_ROWS: Предел развертывания для возвращаемых строк запроса (по умолчанию: 10000; абсолютный жесткий лимит: 100000)
- DEFAULT_RESULT_ROWS: Бюджет строк по умолчанию, если doris_query.execute_query.max_rows не указан (по умолчанию: 100; не может превышать MAX_RESULT_ROWS)
Конфигурация ADBC (Новое в v0.5.0):
- ADBC_DEFAULT_MAX_ROWS: Максимальное количество строк по умолчанию для запросов ADBC (по умолчанию: 10000; не может превышать MAX_RESULT_ROWS)
- ADBC_DEFAULT_TIMEOUT: Тайм-аут запроса ADBC по умолчанию в секундах (по умолчанию: 60)
- ADBC_DEFAULT_RETURN_FORMAT: Формат возврата по умолчанию - arrow/pandas/dict (по умолчанию: arrow)
- ADBC_CONNECTION_TIMEOUT: Тайм-аут соединения ADBC в секундах (по умолчанию: 30)
- ADBC_ENABLED: Включить/отключить инструменты ADBC (по умолчанию: true)
Конфигурация производительности:
- ENABLE_QUERY_CACHE: Включить кэширование запросов (по умолчанию: true)
- CACHE_TTL: Время жизни кэша в секундах (по умолчанию: 300)
- MAX_CONCURRENT_QUERIES: Максимальное количество одновременных запросов (по умолчанию: 50)
- QUERY_TIMEOUT: Предел развертывания для времени выполнения запроса (по умолчанию и абсолютный жесткий лимит: 300 секунд)
- MAX_RESULT_BYTES: Предел развертывания для данных строк в формате UTF-8 JSON (по умолчанию: 1048576; допустимый диапазон: 256-16777216 байт)
- MAX_RESPONSE_CONTENT_SIZE: Максимальный размер содержимого ответа для совместимости с LLM (по умолчанию: 4096, Новое в v0.4.0)
Улучшенная конфигурация логирования (Улучшено в v0.5.0):
- LOG_LEVEL: Уровень логирования (DEBUG/INFO/WARNING/ERROR, по умолчанию: INFO)
- LOG_FILE_PATH: Путь к файлу журнала (автоматически упорядочивается по уровням)
- ENABLE_AUDIT: Включить аудит-логирование (по умолчанию: true)
- ENABLE_LOG_CLEANUP: Включить автоматическую очистку журналов (по умолчанию: true, Улучшено в v0.5.0)
- LOG_MAX_AGE_DAYS: Максимальный возраст файлов журнала в днях (по умолчанию: 30, Улучшено в v0.5.0)
- LOG_CLEANUP_INTERVAL_HOURS: Интервал проверки очистки журналов в часах (по умолчанию: 24, Улучшено в v0.5.0)
- Новые возможности в v0.5.0:
  - Разделение файлов по уровням: Автоматическое разделение на debug.log, info.log, warning.log, error.log, critical.log
  - Формат с меткой времени: Улучшенное форматирование с миллисекундной точностью и правильным выравниванием
  - Фоновый планировщик очистки: Автоматическая очистка с настраиваемыми политиками хранения
  - Аудиторский след: Выделенный audit.log с отдельным управлением хранением
  - Оптимизация производительности: Асинхронное логирование с минимальными накладными расходами и поддержкой ротации

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

MCP tools/list предоставляет восемь стабильных доменных инструментов только для чтения. Вызовите домен с пустым объектом, чтобы постепенно обнаружить его точные авторизованные дочерние инструменты, схемы, поддержку версий, доступность, доказательства и аннотации рисков. См. docs/tool-registry.md. Зафиксированный каталог генерируется из тех же проверенных определений доменов, которые используются во время выполнения.

tool:list разрешает обнаружение манифеста домена для сеансов OAuth; это не разрешает выполнение дочерних элементов. Дочерние элементы без разрешения на обнаружение исключаются, в то время как авторизованные, но недоступные дочерние элементы остаются видимыми с callable=false. Ролевая модель управления доступом (RBAC) Doris остается окончательным бэкендом авторизации данных для всех доступов к объектам Doris.

4. Запуск службы

Выполните следующую команду для запуска сервера:

./start_server.sh

Эта команда запускает приложение FastAPI со службой Streamable HTTP MCP.

5. Развертывание в Docker

Если вы хотите запустить только Doris MCP Server в Docker:

cd doris-mcp-server
docker build -t doris-mcp-server .
docker run -d -p <host-port>:3000 -v /*your-host*/doris-mcp-server/.env:/app/.env --name <your-mcp-server-name> doris-mcp-server:latest

Контейнер всегда слушает порт 3000. Встроенное развертывание Compose публикует его на порту хоста 3000 по умолчанию и публикует Grafana на порту хоста 3003, чтобы две службы не боролись за один и тот же порт. Переопределите эти значения по умолчанию с помощью MCP_HTTP_PORT и GRAFANA_HTTP_PORT:

MCP_HTTP_PORT=3100 GRAFANA_HTTP_PORT=3103 docker compose up -d

Перед запуском встроенного стека создайте пять игнорируемых секретных файлов, используемых Compose. Никакие учетные данные базы данных, MCP, Redis или Grafana не хранятся в docker-compose.yml, .env.example или в среде визуализированной службы:

mkdir -p .secrets
chmod 700 .secrets
python -c 'import secrets; print(secrets.token_urlsafe(32))' > .secrets/doris_password
python -c 'import secrets; print(secrets.token_urlsafe(32))' > .secrets/mcp_static_token
python -c 'import secrets; print(secrets.token_urlsafe(32))' > .secrets/redis_password
python -c 'import secrets; print(secrets.token_urlsafe(32))' > .secrets/grafana_admin_password
python -c 'import hashlib, pathlib; p=pathlib.Path(".secrets/doris_password").read_text().rstrip("\n").encode(); print("initial_root_password = *" + hashlib.sha1(hashlib.sha1(p).digest()).hexdigest().upper())' > .secrets/doris_fe_custom.conf
chmod 0444 .secrets/*
docker compose up -d

doris_fe_custom.conf содержит двухэтапный верификатор пароля SHA-1 Doris, а не пароль в открытом виде, и монтируется как конфигурация начального root-пользователя FE. Соответствующий файл с открытым текстом монтируется только в службы, которые должны аутентифицироваться в Doris. Обращайтесь с обоими файлами как с учетными данными. Родительский каталог остается в режиме 0700, в то время как файлы доступны хосту только для чтения и читаемы контейнером для процесса MCP без прав root. Чтобы хранить секретные файлы в другом месте, скопируйте .env.example в .env и измените только пути хоста COMPOSE_*_FILE.

Все сторонние образы в модели Compose используют явную версию upstream и неизменяемый дайджест OCI. Обновляйте их намеренно, изменяя как тег версии, так и дайджест, затем повторно запустите контракт развертывания и транспортные тесты; не заменяйте их на latest или другой плавающий тег.

Проверка работоспособности Docker на уровне образа использует /live, поэтому временный сбой Doris не приводит к тому, что процесс MCP считается мертвым. Compose переопределяет эту проверку с помощью /ready и помечает службу как готовую только после успешного завершения ограниченной проверки Doris. Обе проверки используют фактический внутренний слушатель на порту 3000.

Compose по умолчанию разрешает заголовки Host 127.0.0.1:* и localhost:*. Развертывание, доступное через другое имя хоста, IP-адрес или обратный прокси-сервер, должно установить явный список разрешенных через запятую; значение * для разрешения всего отклоняется:

MCP_ALLOWED_HOSTS='mcp.example.com,mcp.example.com:*' docker compose up -d

Конечные точки службы:

Streamable HTTP: http://<host>:<port>/mcp (сообщения MCP используют POST; не полагайтесь на поведение совместимости GET или DELETE)
Живучесть: http://<host>:<port>/live — процесс и служба протокола работают; не зависит от Doris
Готовность: http://<host>:<port>/ready — возвращает 200 только при успешном завершении ограниченной проверки SELECT 1 Doris; в противном случае возвращает 503
Устаревшая проверка работоспособности: http://<host>:<port>/health — обратно совместимый псевдоним живучести; не используйте его для принятия решения о маршрутизации работы с базой данных

Проверка готовности имеет фиксированный короткий тайм-аут и предоставляет только стабильные поля состояния, а не ошибки соединения или учетные данные. Режим Stdio не имеет поверхности проверки работоспособности HTTP; контролируйте процесс и используйте рукопожатие инициализации/обнаружения MCP для доступности на транспортном уровне.

Примечание: Сервер использует Streamable HTTP для веб-коммуникации, обеспечивая унифицированные возможности запроса/ответа и потоковой передачи.

Поддержка протокола MCP и миграция

Doris MCP Server использует ядро протокола официального Python SDK v2 как для Streamable HTTP, так и для stdio. Версия протокола MCP, используемая при передаче, не зависит от версии пакета Doris MCP Server и версии пакета Python SDK.

Авторитетными ссылками на протокол являются спецификация MCP 2026-07-28, ключевые изменения 2026-07-28, и спецификация транспорта Streamable HTTP.

Матрица протоколов и транспорта

Клиентский протокол	Потоковый HTTP	stdio	Поведение соединения	Статус MCP-сервера Doris
`2026-07-28`	Поддерживается и рекомендуется	Поддерживается и рекомендуется	Запросы без состояния, самодостаточные; без рукопожатия инициализации или сеанса протокола	Покрыто современными тестами HTTP и реальных процессов stdio
`2025-11-25`	Опционально на `/mcp/legacy`	Поддерживается для миграции	Устаревший `initialize` принимается, но сервер остаётся без состояния и не выдаёт `Mcp-Session-Id`	HTTP-адаптер отключён по умолчанию; покрыто устаревшими тестами HTTP и stdio
`2025-06-18` и старше	Не гарантируется	Не гарантируется	Старое поведение согласования и транспорта выходит за рамки поддерживаемого контракта совместимости	Обновите клиент перед подключением
HTTP+SSE (`2024-11-05`)	Не поддерживается	Неприменимо	Выведенная из эксплуатации отдельная конечная точка SSE не предоставляется	Перейдите на Потоковый HTTP на `/mcp`

Путь совместимости HTTP для 2025-11-25 изолирован от современной конечной точки и отключён по умолчанию. Новые интеграции должны ориентироваться на 2026-07-28 на POST /mcp.

Контракт запросов MCP 2026-07-28

Современные клиенты могут вызывать server/discover перед любым другим методом для проверки поддерживаемых версий протокола, возможностей и идентификации сервера. Обнаружение необязательно; каждый обычный запрос по-прежнему самодостаточен.

Каждый современный запрос должен содержать эти значения в params._meta:

io.modelcontextprotocol/protocolVersion: 2026-07-28
io.modelcontextprotocol/clientCapabilities: возможности, доступные для этого запроса, или пустой объект
io.modelcontextprotocol/clientInfo: имя и версия клиента; это рекомендовано спецификацией

Для Потокового HTTP отправляйте один запрос JSON-RPC на POST /mcp и включайте:

Заголовок	Обязателен	Значение
`Content-Type`	Да	`application/json`
`Accept`	Да	Как `application/json`, так и `text/event-stream`
`MCP-Protocol-Version`	Да	Должен совпадать с версией протокола в `_meta`
`Mcp-Method`	Да	Должен совпадать с JSON-RPC `method`
`Mcp-Name`	Для `tools/call`, `resources/read` и `prompts/get`	Должен совпадать с `params.name` или `params.uri`

Имена заголовков нечувствительны к регистру, но значения методов и имён — чувствительны. Обязательный заголовок, который отсутствует или не соответствует телу запроса, отклоняется с HTTP 400 и ошибкой протокола HeaderMismatch (-32020). Неподдерживаемые версии протокола отклоняются с UnsupportedProtocolVersion (-32022). Если имя или URI небезопасны как простое значение заголовка ASCII, закодируйте их байты UTF-8 в Base64 и отправьте Mcp-Name: =?base64?{value}?=, как определено спецификацией транспорта.

Пример запроса обнаружения:

curl --request POST http://127.0.0.1:3000/mcp \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --header 'MCP-Protocol-Version: 2026-07-28' \
  --header 'Mcp-Method: server/discover' \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "server/discover",
    "params": {
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientCapabilities": {},
        "io.modelcontextprotocol/clientInfo": {
          "name": "example-client",
          "version": "1.0.0"
        }
      }
    }
  }'

Stdio передаёт те же метаданные запроса JSON-RPC в теле сообщения, но не использует HTTP-заголовки. Не записывайте журналы или другую диагностику в stdout в режиме stdio; stdout зарезервирован для сообщений протокола MCP.

Контекст трассировки OpenTelemetry

Клиенты могут распространять поля-носители W3C traceparent, tracestate и baggage в params._meta, как определено в MCP SEP-414, W3C Trace Context и W3C Baggage. Один и тот же носитель уровня сообщений работает на Потоковом HTTP и stdio; эти значения не являются отдельными HTTP-заголовками MCP.

Когда настроены провайдер и экспортёр OpenTelemetry, каждый интервал операции MCP привязывается к действительному входящему контексту трассировки. Активный контекст доступен для инструментированной downstream-работы на время жизни этой операции и сбрасывается перед следующим запросом. Поля-носители трассировки никогда не передаются менеджерам инструментов, ресурсов или подсказок Doris и никогда не копируются в содержимое модели или структурированные результаты.

Сервер проверяет значения носителей трассировки до того, как их увидит распространитель SDK. Некорректные, слишком большие, дублирующиеся или осиротевшие поля игнорируются независимо, а предупреждающие журналы идентифицируют только имя поля — никогда не его предоставленное значение. Значения под ключами багажа, похожими на учётные данные, такими как token, secret или authorization, заменяются на [REDACTED] перед распространением. baggage всё ещё может содержать другие чувствительные к развёртыванию корреляционные данные, поэтому клиенты должны отправлять только значения, одобренные их политикой обработки телеметрических данных.

Пагинация списков

resources/list, tools/list и prompts/list возвращают не более MCP_LIST_PAGE_SIZE записей за ответ как на Потоковом HTTP, так и на stdio. Результаты упорядочены по их стабильному URI ресурса, имени инструмента или имени подсказки. Когда присутствует nextCursor, передайте это непрозрачное значение как cursor следующего запроса; не анализируйте и не создавайте курсоры.

Курсор — это аутентифицированный HMAC дескриптор явного состояния, привязанный к своему типу списка, области, ресурсу, текущему снимку видимого списка, контексту авторизации и сроку действия. Он не зависит от сеанса протокола MCP, транспортного соединения или локальной памяти воркера. Повторное использование его для другого списка, после изменений видимости, после истечения срока действия, после модификации или под другим субъектом возвращает Invalid Params. В этом случае перезапустите листинг без курсора. Это предотвращает незаметное дублирование, потерю или пересечение записей с ограниченными разрешениями при многостраничном обходе.

Сервер по умолчанию генерирует локальный для запуска секрет дескриптора и передаёт его всем воркерам, созданным тем же процессом CLI. Установите один общий MCP_STATE_HANDLE_SECRET на независимо запущенных репликах, когда балансировщик нагрузки может направлять последовательные страницы на разные экземпляры. Полезные данные дескриптора содержат ограниченные метаданные продолжения и подписываются, а не шифруются; учётные данные, текст SQL и результаты запросов никогда не должны помещаться в них. См. ADR 0002.

Сбои списков никогда не представляются как успешные пустые коллекции. Сбой метаданных Doris возвращает List backend unavailable; сбой разрешений метаданных Doris возвращает List operation permission denied; а неожиданный сбой реестра инструментов/ресурсов/подсказок возвращает Internal server error. Эти ответы используют код JSON-RPC -32603 и включают только операцию списка и ограниченную категорию/код ошибки, но никогда не текст исключения бэкенда. Успешный ответ с пустым массивом resources, tools или prompts, следовательно, означает, что видимая коллекция вызывающего действительно пуста. Тот же контракт применяется к Потоковому HTTP и stdio, и неудачный запрос не мешает следующему запросу списка быть успешным.

Подписки и уведомления об изменениях

Сервер в настоящее время не рекламирует и не обслуживает subscriptions/listen. Инструменты и подсказки не имеют канала мутации во время выполнения, а метаданные каталога Doris не предоставляют этому процессу надёжного источника событий изменений между воркерами. Истечение срока кэша и периодический опрос каталога не рассматриваются как события изменений.

Следовательно, обнаружение MCP 2026-07-28 сообщает listChanged: false для инструментов, подсказок и ресурсов и subscribe: false для ресурсов. Запрос subscriptions/listen возвращает Method not found; клиентам следует обновлять списки явно. Тесты Потокового HTTP и настоящего подпроцесса stdio обеспечивают эту границу. См. запись решения о подписках для условий, необходимых для включения этой возможности.

Валидация схемы JSON инструментов

inputSchema и outputSchema инструментов используют JSON Schema 2020-12. Сервер проверяет каждое видимое определение инструмента перед его рекламированием или выполнением, затем проверяет аргументы каждого вызова перед обращением к Doris. Недействительные аргументы возвращают Invalid Params без отражения отклонённых значений. Успешные структурированные результаты также проверяются, когда инструмент объявляет outputSchema; несоответствие схемы на стороне сервера скрывается за Internal error.

Схемы самодостаточны. Принимаются только фрагменты $ref и $dynamicRef в пределах одного документа; сервер никогда не извлекает схему по HTTP, из URI файла или из относительного URI. Рекурсивные ссылки отклоняются политикой ограниченной валидации. Жёсткие лимиты по умолчанию на схему: 64 КиБ, 2048 узлов, глубина 32, 64 ветви композиции и 64 ссылки. Каждый ввод или структурированный вывод ограничен 1 МиБ, 10 000 узлов, глубиной 32 и 262 144 символами на строку. Сообщается не более чем о 16 нарушениях валидации, и отчёты содержат только пути экземпляров и неудачные ключевые слова.

Эти проверки выполняются в общем обработчике протокола, поэтому Потоковый HTTP, современный stdio и устаревший stdio используют одно и то же принудительное применение. Клиенты MCP 2026-07-28 могут также получать массив, строку, число или булево значение structuredContent, когда объявлен соответствующий outputSchema.

Миграция с MCP 2025-11-25

Обновите клиент до MCP SDK, совместимого с 2026-07-28.
Продолжайте использовать конечную точку /mcp для Потокового HTTP, но отправляйте каждое сообщение JSON-RPC как отдельный POST-запрос.
Удалите initialize, notifications/initialized, Mcp-Session-Id и любую зависимость от прикреплённых сессий.
Добавьте версию протокола и возможности клиента в _meta каждого запроса. Добавляйте идентификацию клиента в каждый запрос, где это возможно.
Добавьте MCP-Protocol-Version и Mcp-Method в каждый HTTP-запрос, плюс Mcp-Name для именованных запросов инструментов, ресурсов и подсказок.
Прекратите использовать удалённый поток HTTP GET, Last-Event-ID и возобновляемое поведение SSE. Повторно отправьте прерванный запрос с новым ID запроса JSON-RPC.
Примите обязательное поле resultType в современных результатах и обрабатывайте ошибки, определённые протоколом, такие как -32020, -32021 и -32022.
Проверьте мигрировавший клиент как на Потоковом HTTP, так и на stdio, если интеграция поддерживает оба транспорта.

Клиенты, которые не могут мигрировать немедленно, могут сохранить поток 2025-11-25 initialize через stdio. Для Потокового HTTP оператор должен явно установить ENABLE_LEGACY_HTTP_ADAPTER=true и направить этого клиента на /mcp/legacy; /mcp никогда не возвращается к устаревшему транспорту. Адаптер остаётся без состояния и не создаёт сеанс протокола HTTP.

Ограничения развёртывания

Привязывайте локальные развёртывания к 127.0.0.1, localhost или ::1. Транспорт проверяет как Host, так и Origin для защиты от повторной привязки DNS.
Адрес привязки не является идентификатором публичной службы. В частности, 0.0.0.0 не авторизует произвольные значения Host или Origin.
Текущая политика Host/Origin не предоставляет настроенный оператором публичный список разрешённых. Поэтому публичные имена хостов и обратные прокси, переписывающие Host или Origin, пока не являются поддерживаемой формой развёртывания.
Запуск HTTP завершается неудачей, если хост привязки не является loopback и не включён ни один метод аутентификации. ALLOW_UNAUTHENTICATED_NON_LOOPBACK=true — это явное опасное переопределение только для изолированного тестирования; не используйте его как shortcut развёртывания.
Запросы MCP без состояния не требуют прикреплённых HTTP-сессий и могут использовать несколько воркеров. Режимы аутентификации могут иметь более строгие ограничения: OAuth на базе Doris хранит токены и пулы на пользователя в памяти процесса и должен работать с WORKERS=1.
Используйте HTTPS, когда трафик покидает локальную машину, и храните учётные данные в заголовках или переменных окружения процесса, а не в URL.

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

Взаимодействие с MCP-сервером Doris требует наличия MCP-клиента. Клиент подключается к конечной точке Потокового HTTP сервера и отправляет запросы в соответствии со спецификацией MCP для вызова инструментов сервера.

Основной поток взаимодействия:

(Опционально) Обнаружение сервера: Современный клиент может вызвать server/discover для проверки поддерживаемых версий протокола, возможностей и идентификационной информации.
Обнаружение доменов: В режиме по умолчанию hierarchical, tools/list возвращает восемь ограниченных доменов только для чтения. Вызовите домен без аргументов, чтобы узнать его точные дочерние имена, схемы и доступность.
Вызов точного дочернего элемента: Вызовите тот же домен с child_tool, arguments и обнаруженным manifest_version.
- Пример: Получение раздела схемы таблицы
  - name: doris_catalog
  - child_tool: get_table_context
  - arguments: Включите database, table, опциональный catalog и sections: ["schema"].
- В режиме flat вызовите уникальное формальное имя doris_catalog_get_table_context с дочерними аргументами напрямую.
Обработка ответа:
- Без потоковой передачи: Клиент получает ответ, содержащий content или isError.
- Потоковая передача: Клиент получает серию уведомлений о ходе выполнения, за которыми следует окончательный ответ.

Устаревшие клиенты 2025-11-25 stdio инициализируются как и раньше. HTTP-клиентам требуется явно включенный адаптер /mcp/legacy, и на них распространяются ограничения совместимости без сохранения состояния, описанные выше.

Поддержка федерации каталогов

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

Ключевые особенности:

Доступ к метаданным нескольких каталогов: Дочерние элементы doris_catalog принимают опциональный аргумент catalog, где это применимо.
Межкаталожные SQL-запросы: Используйте doris_query.execute_query с трехчастным именованием таблиц.
Обнаружение каталогов: Используйте doris_catalog.list_catalogs.

Требование к трехчастному именованию:

Все SQL-запросы ДОЛЖНЫ использовать трехчастное именование для ссылок на таблицы:

Внутренние таблицы: internal.database_name.table_name
Внешние таблицы: catalog_name.database_name.table_name

Примеры:

Получение доступных каталогов:

{
  "tool_name": "doris_catalog",
  "arguments": {
    "child_tool": "list_catalogs",
    "manifest_version": "<value returned by domain discovery>",
    "arguments": {}
  }
}

Получение баз данных в определенном каталоге:

{
  "tool_name": "doris_catalog",
  "arguments": {
    "child_tool": "list_databases",
    "manifest_version": "<value returned by domain discovery>",
    "arguments": {"catalog": "mysql"}
  }
}

Запрос к внутреннему каталогу:

{
  "tool_name": "doris_query",
  "arguments": {
    "child_tool": "execute_query",
    "manifest_version": "<value returned by domain discovery>",
    "arguments": {
      "sql": "SELECT COUNT(*) FROM internal.ssb.customer"
    }
  }
}

Запрос к внешнему каталогу:

{
  "tool_name": "doris_query",
  "arguments": {
    "child_tool": "execute_query",
    "manifest_version": "<value returned by domain discovery>",
    "arguments": {
      "sql": "SELECT COUNT(*) FROM mysql.ssb.customer"
    }
  }
}

Межкаталожный запрос:

{
  "tool_name": "doris_query",
  "arguments": {
    "child_tool": "execute_query",
    "arguments": {
      "sql": "SELECT i.c_name, m.external_data FROM internal.ssb.customer i JOIN mysql.test.user_info m ON i.c_custkey = m.customer_id"
    }
  }
}

Конфигурация безопасности

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

Функции безопасности (улучшены в версии 0.6.0)

🔐 Мульти-аутентификационная система: Полная аутентификация Token, JWT и OAuth с независимыми переключателями управления
🔗 Конфигурация базы данных с привязкой к токену: Революционный подход, позволяющий токенам нести собственные параметры подключения к базе данных
🔄 Горячая перезагрузка безопасности: Обновление конфигурации безопасности без простоев с интеллектуальной повторной проверкой токенов
⚡ Безопасная проверка маршрутов: Маршруты Doris, привязанные к токену, проверяются через их выделенные пулы с коротким кэшем успешных проверок, чтобы пинги не переподключались при каждом запросе
🛡️ Авторизация на основе ролей: Расширенный RBAC с четырехуровневой классификацией безопасности
🚫 Улучшенная безопасность SQL: Расширенная защита от SQL-инъекций с улучшенным обнаружением шаблонов
🎭 Интеллектуальное маскирование данных: Автоматическое маскирование конфиденциальных данных с разрешениями на основе пользователей
📊 Аналитика безопасности: Комплексные аудиторские следы и мониторинг безопасности

Конфигурация аутентификации (v0.6.0)

Настройте новую систему аутентификации с детальным контролем:

# Generate a deployment-specific token before enabling static authentication.
export TOKEN_ADMIN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"

# Individual Authentication Control (New in v0.6.0)
ENABLE_TOKEN_AUTH=true          # Enable token-based authentication
ENABLE_JWT_AUTH=false           # Enable JWT authentication  
ENABLE_OAUTH_AUTH=false         # Enable OAuth authentication

# Token Management (New in v0.6.0)
TOKEN_FILE_PATH=tokens.json     # Token configuration file
TOKEN_HOT_RELOAD=true          # Enable hot reloading
TOKEN_DB_VALIDATION_TTL_SECONDS=30  # Cache successful Doris route checks

# Legacy Configuration (Deprecated)
# AUTH_TYPE=token               # Use individual switches instead

Репозиторий не поставляет пригодных для использования статических токенов или устаревших секретов. Запуск завершается ошибкой, если включена аутентификация по статическому токену без хотя бы одного активного значения TOKEN_<ID> с высокой энтропией или эквивалентной записи в TOKEN_FILE_PATH.

Проверка токенов доступа внешнего OAuth/OIDC

Внешний OAuth работает по принципу fail-closed. Прежде чем сервер запросит информацию о пользователе, он использует доверенную конечную точку интроспекции RFC 7662 и требует активный, неистекший токен с точно заданным эмитентом, ожидаемой аудиторией, привязкой к ресурсу MCP, требуемыми областями действия и субъектом. Успешный запрос userinfo не принимается как доказательство того, что токен был выпущен для этого MCP-сервера. Субъект userinfo также должен совпадать с субъектом интроспектированного токена.

OAUTH_RESOURCE отправляется при запросах кода авторизации и токена обновления. OAUTH_AUDIENCE по умолчанию соответствует этому URI ресурса. OAUTH_REQUIRED_SCOPE по умолчанию соответствует всем областям действия в OAUTH_SCOPE; области действия, возвращенные сервером авторизации, но отсутствующие в OAUTH_SCOPE, исключаются из контекста аутентификации.

ENABLE_OAUTH_AUTH=true
OAUTH_CLIENT_ID=your_oauth_client_id
OAUTH_CLIENT_SECRET=your_oauth_client_secret
OAUTH_REDIRECT_URI=https://mcp.example.com/auth/callback

OAUTH_ISSUER=https://issuer.example.com
OAUTH_RESOURCE=https://mcp.example.com/mcp
OAUTH_AUDIENCE=https://mcp.example.com/mcp
OAUTH_INTROSPECTION_URL=https://issuer.example.com/introspect
OAUTH_USERINFO_URL=https://issuer.example.com/userinfo

OAUTH_SCOPE="tool:list tool:call:exec_query resource:list resource:read"
OAUTH_REQUIRED_SCOPE="tool:list resource:read"

Документ обнаружения сервера авторизации может предоставлять конечные точки интроспекции и userinfo, но его issuer должен точно совпадать с OAUTH_ISSUER. Могут быть настроены выделенные значения OAUTH_INTROSPECTION_CLIENT_ID и OAUTH_INTROSPECTION_CLIENT_SECRET; в противном случае используются обычные учетные данные клиента OAuth. URL-адреса удаленного эмитента, обнаружения, интроспекции и userinfo должны использовать HTTPS.

Для HTTP-развертываний сервер публикует метаданные RFC 9728 по адресу /.well-known/oauth-protected-resource. Отсутствующие или недействительные учетные данные получают HTTP 401 Bearer challenge, содержащий resource_metadata и минимальные настроенные области действия. Действительный токен, не имеющий области действия для операции, получает HTTP 403 с error="insufficient_scope" и точной областью действия, необходимой для пошаговой авторизации. Токены доступа и внутренние сведения об ошибках провайдера не копируются в эти ответы. Эти HTTP OAuth challenge не применяются к транспорту stdio, где учетные данные предоставляются через локальное окружение процесса.

Области действия внешних операций OAuth точны: для перечисления инструментов требуется tool:list, для вызова инструмента требуется tool:call:<tool-name>, для перечисления и чтения ресурсов требуются resource:list и resource:read, а для операций Prompt требуются prompt:list и prompt:get. Добавьте каждую вызываемую область действия инструмента в OAUTH_SCOPE; * и несвязанные области действия никогда не удовлетворяют проверку операции. Авторизация по статическому токену, JWT, анонимная обратная петля и локальная авторизация stdio сохраняют свое существующее поведение разрешений, не связанное с OAuth.

Аутентификация OAuth на базе Doris

OAuth на базе Doris — это отдельный режим OAuth, в котором сама Doris выступает в качестве серверной части авторизации. MCP-клиент обнаруживает метаданные OAuth этого сервера, пользователь входит в систему с именем пользователя и паролем Doris, сервер проверяет эти учетные данные, создавая пул подключений Doris для каждого пользователя, а выпущенные токены доступа doa_ направляют вызовы инструментов через пул этого пользователя Doris. Области действия MCP контролируют, какие операции MCP могут быть вызваны; RBAC Doris контролирует, какие каталоги, базы данных, таблицы и метаданные пользователь может видеть.

Этот режим не совпадает с внешним OAuth/OIDC. ENABLE_DORIS_OAUTH_AUTH=true конфликтует с ENABLE_OAUTH_AUTH=true, OAUTH_ENABLED=true и устаревшим AUTH_TYPE=oauth; запуск быстро завершается ошибкой, если настроены оба режима. Стандартный MCP-агент вводит один URL-адрес MCP и должен обнаружить ровно одно поведение OAuth для этого URL-адреса, поэтому существующий поток входа в систему внешнего OAuth /auth/* не используется в режиме OAuth на базе Doris.

Каждая запись токена OAuth Doris привязана к ресурсу, выбранному во время авторизации. Защищенная конечная точка MCP принимает только точный канонический ресурс ${DORIS_OAUTH_BASE_URL}/mcp; токен, выпущенный для сервера авторизации или любого другого ресурса, отклоняется с запросом invalid_token до использования пула Doris для каждого пользователя. Клиенты должны отправлять этот канонический resource как в запросе авторизации, так и в запросе токена кода авторизации. Конечная точка токена возвращает RFC 8707 invalid_target, если значение отсутствует или не соответствует точно ресурсу, привязанному к коду авторизации.

Минимальная локальная конфигурация

Следующий пример предназначен для локальной разработки на одном рабочем узле:

TRANSPORT=http
WORKERS=1

DORIS_HOST=localhost
DORIS_PORT=9030
DORIS_USER=root
DORIS_PASSWORD=<service-account-password>
DORIS_DATABASE=information_schema

ENABLE_DORIS_OAUTH_AUTH=true
DORIS_OAUTH_BASE_URL=http://localhost:3000
ENABLE_OAUTH_AUTH=false

DORIS_OAUTH_DB_TOOLS_ENABLED=true
DORIS_OAUTH_DB_TOOL_ALLOWLIST=get_db_list,get_db_table_list,get_table_schema,get_table_comment,get_table_column_comments,get_table_indexes,get_catalog_list
DORIS_OAUTH_QUERY_TOOLS_ENABLED=true
DORIS_OAUTH_EXPLAIN_TOOLS_ENABLED=true

# Optional: let Doris RBAC, not the legacy MCP SQL guard, decide DDL/DML.
ENABLE_SECURITY_CHECK=false

Настроенная сервисная учетная запись Doris по-прежнему требуется для проверки запуска и для путей совместимости, не связанных с Doris OAuth. Запросы OAuth на базе Doris завершаются ошибкой (fail-closed), если пул для каждого пользователя отсутствует, и не должны возвращаться к сервисной/глобальной учетной записи.

Доступ к инструментам Doris OAuth

DORIS_OAUTH_DB_TOOLS_ENABLED=true открывает проверенную корзину метаданных. Проверенными инструментами являются:

get_db_list
get_db_table_list
get_table_schema
get_table_comment
get_table_column_comments
get_table_indexes
get_catalog_list

Для обычных потоков MCP OAuth клиентам не нужно передавать длинный список --scopes. Если запрос OAuth опускает область действия, сервер предоставляет настроенный конверт возможностей Doris OAuth. Для операций по каналу MySQL RBAC Doris решает, может ли вошедший пользователь Doris фактически читать метаданные, выполнять SQL или объяснять SQL.

DORIS_OAUTH_QUERY_TOOLS_ENABLED=true открывает exec_query. DORIS_OAUTH_EXPLAIN_TOOLS_ENABLED=true открывает get_sql_explain. Если ENABLE_SECURITY_CHECK=true, устаревший уровень безопасности SQL MCP все еще может отклонить некоторые SQL до того, как их увидит Doris. Установите ENABLE_SECURITY_CHECK=false, когда предполагаемая политика заключается в том, чтобы позволить RBAC Doris принимать решения по SQL/DDL/DML.

OAuth на базе Doris по-прежнему не открывает подсказки, ADBC, HTTP-профилирование/мониторинг FE, аудит/управление или аналитику производительности на этом этапе, если только эти пути не маршрутизируются отдельно через учетные данные для каждого пользователя или не получают явного назначения сервисной учетной записи/администратора.

Регистрация клиента OAuth

Предпочтительный порядок регистрации клиента:

Использовать клиент, настроенный оператором, если он доступен.
Использовать документ метаданных идентификатора клиента (CIMD), отправив его HTTPS URL как client_id.
Использовать динамическую регистрацию клиента (DCR) только в качестве резервного варианта для совместимости.

Метаданные сервера авторизации объявляют client_id_metadata_document_supported=true. CIMD должен быть объектом JSON, чей client_id точно равен запрошенному URL и чьи client_name и redirect_uris действительны. Этот сервер в настоящее время принимает публичные CIMD-клиенты с token_endpoint_auth_method=none, предоставлением кода авторизации плюс опциональным предоставлением токена обновления, типом ответа code и точным соответствием URI перенаправления. Нативные клиенты могут использовать пользовательскую схему обратного домена или петлевой HTTP URI; веб-клиенты должны использовать не-петлевой HTTPS.

Получение CIMD работает по принципу fail-closed. URL должен использовать HTTPS, содержать путь и не иметь userinfo, фрагмента, обратной косой черты или сегмента пути с точкой. Распознаватель отклоняет адреса назначения специального использования, закрепляет проверенные результаты DNS для запроса, не следует перенаправлениям, требует JSON, ограничивает ответ 5 КиБ по умолчанию, отклоняет встроенные общие секреты или материал закрытого ключа и кэширует только действительные документы в соответствии с элементами управления кэша HTTP. Петлевые хосты метаданных принимаются только тогда, когда эмитент Doris OAuth сам является петлевым эмитентом для разработки. Страница входа отображает имена хостов клиента и перенаправления и предупреждает перед перенаправлением на localhost.

Элементы управления CIMD можно настроить с помощью DORIS_OAUTH_CIMD_FETCH_TIMEOUT_SECONDS, DORIS_OAUTH_CIMD_MAX_DOCUMENT_BYTES, DORIS_OAUTH_CIMD_DEFAULT_CACHE_SECONDS, DORIS_OAUTH_CIMD_MAX_CACHE_SECONDS и DORIS_OAUTH_CIMD_MAX_CLIENTS.

DCR остается доступным для старых клиентов, когда DORIS_OAUTH_DYNAMIC_CLIENT_REGISTRATION_MODE это разрешает. Запросы DCR должны включать application_type как native или web; применяются те же правила для конкретного типа и точного URI перенаправления. Для производственной DCR по-прежнему требуется ENABLE_DORIS_OAUTH_PRODUCTION_DCR=true.

Ответы об успешной авторизации и перенаправляемые ошибки включают точного эмитента сервера авторизации в параметре RFC 9207 iss. Обнаружение объявляет authorization_response_iss_parameter_supported=true; клиенты должны сравнить возвращенное значение с обнаруженным эмитентом без нормализации URI, прежде чем принимать ответ.

Текущие эксплуатационные ограничения

OAuth на базе Doris в настоящее время является однопроцессным и однорабочим:

WORKERS=1 обязателен. WORKERS=0 раскрывает количество ядер CPU и завершается ошибкой, если включена OAuth-аутентификация на базе Doris.
OAuth-клиенты, транзакции авторизации, коды авторизации, токены доступа, токены обновления и DCR-клиенты хранятся только в памяти и в пределах одного процесса.
Пулы соединений Doris для каждого пользователя существуют только в рамках одного процесса.
Перезапуск процесса требует повторного входа пользователей в систему.
Токены и пулы не разделяются между рабочими процессами, процессами или узлами.
Горизонтальное масштабирование без сохранения состояния и развертывание на нескольких узлах пока не поддерживаются для OAuth на базе Doris.

Если токен доступа в остальном действителен, но его пул пользователей Doris отсутствует, запрос завершается ошибкой с требованием входа / DORIS_OAUTH_POOL_MISSING. Сервер не хранит исходные пароли Doris для автоматического восстановления пула.

Подготовка к промышленной эксплуатации

Для промышленных развертываний:

Используйте HTTPS DORIS_OAUTH_BASE_URL для любого адреса, не являющегося loopback.
Сохраняйте DORIS_OAUTH_ALLOW_INSECURE_HTTP=false; не-loopback http:// отклоняется, если это явно не переопределено для разработки.
Включайте DORIS_OAUTH_TRUST_PROXY_HEADERS только за контролируемым обратным прокси-сервером и установите DORIS_OAUTH_TRUSTED_PROXY_CIDRS.
Держите включенными ограничения частоты запросов для входа, авторизации, токенов, обновления, отзыва и DCR.
Используйте RBAC Doris в качестве окончательной границы авторизации данных и предоставляйте пользователям Doris доступ только к тем данным, которые они должны проверять.
Не записывайте в журнал пароли Doris, заголовки авторизации, токены доступа, токены обновления, коды авторизации, верификаторы PKCE или секреты клиентов.
Считайте префикс doa_ зарезервированным для токенов доступа OAuth на базе Doris; статические токены и значения JWT Bearer не должны его использовать.
Отдавайте предпочтение предварительно настроенным клиентам или документам метаданных идентификатора клиента. Оставьте DCR как резервный вариант для совместимости; для промышленного использования DCR требуется ENABLE_DORIS_OAUTH_PRODUCTION_DCR=true.

Конфигурация базы данных с привязкой к токену (Новое в v0.6.0)

Управляемое создание токена возвращает значение bearer один раз и записывает только его дайджест в tokens.json. При ручной настройке сгенерируйте значение bearer и дайджест вне репозитория, сохраните значение bearer в хранилище секретов клиента и поместите только дайджест в файл сервера:

python - <<'PY'
import hashlib
import secrets

token = secrets.token_urlsafe(32)
print(f"Bearer token (store once): {token}")
print(f"token_digest: sha256:{hashlib.sha256(token.encode()).hexdigest()}")
PY

Формат файла v2 использует сгенерированный дайджест:

{
  "version": "2.0",
  "tokens": [
    {
      "token_id": "customer-a-token",
      "token_digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
      "created_at": "2026-07-29T00:00:00Z",
      "expires_at": null,
      "last_used": null,
      "description": "Customer A dedicated database access",
      "is_active": true,
      "database_config": {
        "host": "customer-a-db.example.com",
        "port": 9030,
        "user": "customer_a_user",
        "password": "secure_password",
        "database": "customer_a_data",
        "charset": "UTF8",
        "fe_http_port": 8030
      }
    }
  ]
}

Замените пример из одних нулей на сгенерированный дайджест; он намеренно не является пригодными для использования учетными данными. Управляемые записи атомарны и устанавливают режим файла в 0600. Файлы версии 1, содержащие открытый текст token, принимаются однократно для миграции, а затем немедленно заменяются записями версии 2, содержащими только дайджест. Сервер не может восстановить или отобразить исходное значение bearer из token_digest.

Горячее обновление конфигурации (Новое в v0.6.0)

Система автоматически обнаруживает и применяет изменения конфигурации:

Автоматическое обнаружение: Мониторинг изменений файлов каждые 10 секунд
Мгновенная проверка: Немедленная проверка конфигурации базы данных для новых токенов
Нулевое время простоя: Обновление конфигурации без прерывания обслуживания
Защита от отката: Автоматический откат при ошибках конфигурации
Аудиторский след: Полное протоколирование изменений конфигурации

Пример аутентификации по токену

# Client authentication with token
auth_info = {
    "type": "token",
    "token": "your_jwt_token",
    "session_id": "unique_session_id"
}

Пример базовой аутентификации

# Client authentication with username/password
auth_info = {
    "type": "basic",
    "username": "analyst",
    "password": "secure_password",
    "session_id": "unique_session_id"
}

Авторизация и уровни безопасности

Система поддерживает четыре уровня безопасности с иерархическим контролем доступа:

Уровень безопасности	Область доступа	Типичные сценарии использования
Публичный	Неограниченный доступ	Публичные отчеты, общая статистика
Внутренний	Сотрудники компании	Внутренние панели мониторинга, бизнес-метрики
Конфиденциальный	Авторизованный персонал	Данные клиентов, финансовые отчеты
Секретный	Высшее руководство	Стратегические данные, конфиденциальная аналитика

Конфигурация ролей

Внешнее сопоставление ролей OAuth настраивается через переменные окружения:

# Roles supplied when the provider returns no role claim
OAUTH_DEFAULT_ROLES=oauth_user

# Fallbacks for users whose roles do not occur in the JSON mappings
OAUTH_DEFAULT_SECURITY_LEVEL=internal
OAUTH_DEFAULT_PERMISSIONS=read_data

# Exact domains only. Domain elevation is applied only when the provider
# returns email_verified=true.
OAUTH_TRUSTED_DOMAINS=example.com,internal.example.com
OAUTH_TRUSTED_DOMAIN_SECURITY_LEVEL=confidential

# Each JSON value replaces the complete built-in mapping.
OAUTH_ROLE_SECURITY_LEVELS_JSON={"analyst":"internal","executive":"secret"}
OAUTH_ROLE_PERMISSIONS_JSON={"analyst":["read_data","query_database"],"executive":["read_data","query_database","admin"]}

Имена ролей и доверенные домены сопоставляются без учета регистра. Поддерживаемые уровни безопасности: public, internal, confidential и secret. Явно заданный пустой массив разрешений запрещает разрешения приложения для этой роли; пустое значение OAUTH_DEFAULT_PERMISSIONS приводит к отказу в доступе для неизвестных ролей.

Встроенные значения ролей по умолчанию сохраняют предыдущее поведение для admin, administrator, data_admin, super_admin, data_analyst, developer, manager, viewer, user и oauth_user. По умолчанию ни один домен электронной почты не является доверенным.

Эти параметры управляют разрешениями приложения MCP и классификацией безопасности. Доступ к базам данных, таблицам, столбцам и строкам по-прежнему должен обеспечиваться с помощью пользователей Doris, ролей, грантов, представлений и политик на уровне строк; сопоставление OAuth не обходит авторизацию Doris. См. руководство по детальному контролю доступа Doris для сквозного примера политик столбцов и строк, вариантов маршрутизации идентификации MCP и контрольного списка проверки.

Проверка безопасности SQL

Система автоматически проверяет SQL-запросы на наличие рисков безопасности:

Заблокированные операции

Настройте заблокированные SQL-операции с помощью переменных окружения (Новое в v0.4.2):

# Enable/disable SQL security check (New in v0.4.2)
ENABLE_SECURITY_CHECK=true

# Customize blocked keywords via environment variable (New in v0.4.2)
BLOCKED_KEYWORDS="DROP,DELETE,TRUNCATE,ALTER,CREATE,INSERT,UPDATE,GRANT,REVOKE,EXEC,EXECUTE,SHUTDOWN,KILL"

# Maximum query complexity score
MAX_QUERY_COMPLEXITY=100

Заблокированные ключевые слова по умолчанию (Унифицировано в v0.4.2):

Операции DDL: DROP, CREATE, ALTER, TRUNCATE
Операции DML: DELETE, INSERT, UPDATE
Операции DCL: GRANT, REVOKE
Системные операции: EXEC, EXECUTE, SHUTDOWN, KILL

Защита от SQL-инъекций

Система автоматически обнаруживает и блокирует:

Инъекции на основе UNION: атаки UNION SELECT
Инъекции на основе Boolean: шаблоны OR 1=1
Инъекции на основе времени: функции SLEEP(), WAITFOR
Инъекции через комментарии: шаблоны --, /**/
Составные запросы: Несколько операторов, разделенных ;

Пример проверки безопасности

# This query would be blocked
dangerous_sql = "SELECT * FROM users WHERE id = 1; DROP TABLE users;"

# This query would be allowed
safe_sql = "SELECT name, email FROM users WHERE department = 'sales'"

Конфигурация маскирования данных

Настройте автоматическое маскирование конфиденциальной информации:

Встроенные правила маскирования

# Default masking rules
masking_rules = [
    {
        "column_pattern": r".*phone.*|.*mobile.*",
        "algorithm": "phone_mask",
        "parameters": {
            "mask_char": "*",
            "keep_prefix": 3,
            "keep_suffix": 4
        },
        "security_level": "internal"
    },
    {
        "column_pattern": r".*email.*", 
        "algorithm": "email_mask",
        "parameters": {"mask_char": "*"},
        "security_level": "internal"
    },
    {
        "column_pattern": r".*id_card.*|.*identity.*",
        "algorithm": "id_mask", 
        "parameters": {
            "mask_char": "*",
            "keep_prefix": 6,
            "keep_suffix": 4
        },
        "security_level": "confidential"
    }
]

Алгоритмы маскирования

Алгоритм	Описание	Пример
`phone_mask`	Маскирует номера телефонов	`138****5678`
`email_mask`	Маскирует адреса электронной почты	`j***n@example.com`
`id_mask`	Маскирует номера удостоверений личности	`110101****1234`
`name_mask`	Маскирует личные имена	`张*明`
`partial_mask`	Частичное маскирование с коэффициентом	`abc***xyz`

Пользовательские правила маскирования

Добавьте пользовательские правила маскирования в вашу конфигурацию:

# Custom masking rule
custom_rule = {
    "column_pattern": r".*salary.*|.*income.*",
    "algorithm": "partial_mask",
    "parameters": {
        "mask_char": "*",
        "mask_ratio": 0.6
    },
    "security_level": "confidential"
}

Примеры конфигурации безопасности

Переменные окружения

# Generate this outside source control, then inject it into the process.
export TOKEN_SECURITY_ADMIN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
export ENABLE_TOKEN_AUTH=true
ENABLE_MASKING=true
MAX_RESULT_ROWS=10000
BLOCKED_SQL_OPERATIONS=DROP,DELETE,TRUNCATE,ALTER
MAX_QUERY_COMPLEXITY=100
ENABLE_AUDIT=true

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

# Configure sensitive tables with security levels
sensitive_tables = {
    "user_profiles": "confidential",
    "payment_records": "secret", 
    "employee_salaries": "secret",
    "customer_data": "confidential",
    "public_reports": "public"
}

Лучшие практики безопасности

🔑 Надежная аутентификация: Используйте JWT-токены с надлежащим сроком действия
🎯 Принцип наименьших привилегий: Предоставляйте минимально необходимые разрешения
🔍 Регулярный аудит: Включите аудит для мониторинга безопасности
🛡️ Проверка ввода: Все SQL-запросы автоматически проверяются
🎭 Классификация данных: Правильно классифицируйте данные по уровням безопасности
🔄 Регулярные обновления: Поддерживайте правила и конфигурации безопасности в актуальном состоянии
Усиление безопасности OAuth на базе Doris: Используйте HTTPS, держите внешний OAuth отключенным в этом режиме, сохраняйте WORKERS=1, полагайтесь на RBAC Doris для доступа к данным по каналу MySQL и предоставляйте только те операции, которые настроены и проверены на использование учетных данных вошедшего пользователя Doris.

Мониторинг безопасности

Система обеспечивает комплексный мониторинг безопасности:

# Security audit log example
{
    "timestamp": "2024-01-15T10:30:00Z",
    "user_id": "analyst_user",
    "action": "query_execution", 
    "resource": "customer_data",
    "result": "blocked",
    "reason": "insufficient_permissions",
    "risk_level": "medium"
}

⚠️ Важно: Всегда тестируйте конфигурации безопасности в среде разработки перед развертыванием в промышленной среде. Регулярно пересматривайте и обновляйте политики безопасности в соответствии с требованиями вашей организации.

Подключение с помощью Cursor

Вы можете подключить Cursor к этому MCP-серверу, используя режим Stdio (рекомендуется) или режим Streamable HTTP.

Режим Stdio

Режим Stdio позволяет Cursor управлять процессом сервера напрямую. Настройка выполняется в файле настроек MCP-сервера Cursor (обычно ~/.cursor/mcp.json или аналогичном).

Способ 1: Использование установки из PyPI (Рекомендуется)

Установите пакет из PyPI и настройте Cursor для его использования:

pip install doris-mcp-server

Настройте Cursor: Добавьте запись, подобную следующей, в вашу конфигурацию Cursor MCP:

{
  "mcpServers": {
    "doris-stdio": {
      "command": "doris-mcp-server",
      "args": ["--transport", "stdio"],
      "env": {
        "DORIS_HOST": "127.0.0.1",
        "DORIS_PORT": "9030",
        "DORIS_USER": "root",
        "DORIS_PASSWORD": "your_db_password"
      }
    }
  }
}

Способ 2: Использование uv (Разработка)

Если у вас установлен uv и вы хотите запускать из исходного кода:

uv run --project /path/to/doris-mcp-server doris-mcp-server

Примечание: Замените /path/to/doris-mcp-server на фактический абсолютный путь к каталогу вашего проекта.

Настройте Cursor: Добавьте запись, подобную следующей, в вашу конфигурацию Cursor MCP:

{
  "mcpServers": {
    "doris-stdio": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/your/doris-mcp-server", "doris-mcp-server"],
      "env": {
        "DORIS_HOST": "127.0.0.1",
        "DORIS_PORT": "9030",
        "DORIS_USER": "root",
        "DORIS_PASSWORD": "your_db_password"
      }
    }
  }
}

Режим Streamable HTTP

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

Настройте .env: Убедитесь, что ваши учетные данные базы данных и любые другие необходимые параметры правильно настроены в файле .env в каталоге проекта.
Запустите сервер: Запустите сервер из терминала в корневом каталоге проекта:
```
./start_server.sh
```
Этот скрипт считывает файл .env и запускает сервер Streamable HTTP на 127.0.0.1 по умолчанию. Не-loopback слушатель требует наличия хотя бы одного метода аутентификации.
Настройте Cursor: Добавьте запись, подобную следующей, в вашу конфигурацию Cursor MCP, указав конечную точку Streamable HTTP работающего сервера:
```
{
  "mcpServers": {
    "doris-http": {
       "url": "http://127.0.0.1:3000/mcp"
    }
  }
}
```
Примечание: Измените хост/порт, если ваш сервер работает по другому адресу. Конечная точка /mcp является унифицированным интерфейсом Streamable HTTP.

После настройки любого из режимов в Cursor вы сможете выбрать сервер (например, doris-stdio или doris-http) и использовать его инструменты.

Подключение с помощью Kiro

Или добавьте следующее в ваш файл конфигурации Kiro MCP (~/.kiro/settings/mcp.json для глобальной, или .kiro/settings/mcp.json для области проекта). См. документацию Kiro MCP для получения дополнительной информации.

{
  "mcpServers": {
    "doris-stdio": {
      "command": "doris-mcp-server",
      "args": ["--transport", "stdio"],
      "env": {
        "DORIS_HOST": "127.0.0.1",
        "DORIS_PORT": "9030",
        "DORIS_USER": "root",
        "DORIS_PASSWORD": "your_db_password"
      }
    }
  }
}

Структура каталогов

doris-mcp-server/
├── doris_mcp_server/           # Main server package
│   ├── main.py                 # Main entry point and FastAPI app
│   ├── multiworker_app.py      # Multi-worker application module (New in v0.6.0)
│   ├── auth/                   # Authentication modules (New in v0.6.0)
│   │   ├── token_manager.py    # Enterprise token management with hot reload
│   │   ├── jwt_manager.py      # JWT authentication provider
│   │   ├── oauth_provider.py   # OAuth authentication provider  
│   │   ├── oauth_handlers.py   # OAuth HTTP endpoint handlers
│   │   ├── token_handlers.py   # Token management HTTP endpoints
│   │   ├── auth_middleware.py  # Authentication middleware
│   │   └── __init__.py
│   ├── tools/                  # MCP tools implementation
│   │   ├── tools_manager.py    # Centralized tools management and registration
│   │   ├── resources_manager.py # Resource management and metadata exposure
│   │   ├── prompts_manager.py  # Intelligent prompt templates for data analysis
│   │   └── __init__.py
│   ├── utils/                  # Core utility modules
│   │   ├── config.py           # Configuration management with validation
│   │   ├── db.py               # Enhanced database connection management with token binding (Enhanced in v0.6.0)
│   │   ├── query_executor.py   # High-performance SQL execution with caching
│   │   ├── security.py         # Advanced security management and authentication (Enhanced in v0.6.0)
│   │   ├── schema_extractor.py # Metadata extraction with catalog federation
│   │   ├── analysis_tools.py   # Data analysis and performance monitoring
│   │   ├── data_governance_tools.py  # Data lineage and freshness monitoring (v0.5.0)
│   │   ├── data_quality_tools.py     # Comprehensive data quality analysis (v0.5.0)
│   │   ├── data_exploration_tools.py # Advanced statistical analysis (v0.5.0)
│   │   ├── security_analytics_tools.py # Access pattern analysis (v0.5.0)
│   │   ├── dependency_analysis_tools.py # Impact analysis and dependency mapping (v0.5.0)
│   │   ├── performance_analytics_tools.py # Query optimization and capacity planning (v0.5.0)
│   │   ├── adbc_query_tools.py       # High-performance Arrow Flight SQL operations (v0.5.0)
│   │   ├── logger.py           # Logging configuration
│   │   └── __init__.py
│   └── __init__.py
├── doris_mcp_client/           # MCP client implementation
│   ├── client.py               # Unified MCP client for testing and integration
│   ├── README.md               # Client documentation
│   └── __init__.py
├── logs/                       # Log files directory
├── tokens.json                 # Token configuration file (New in v0.6.0)
├── README.md                   # This documentation
├── CHANGELOG.md                 # Tagged release history and unreleased changes
├── .env.example                # Environment variables template
├── requirements.txt            # Runtime-only Python dependencies
├── requirements-dev.txt        # Runtime plus test and quality dependencies
├── pyproject.toml              # Project configuration and entry points
├── uv.lock                     # UV package manager lock file
├── generate_requirements.py    # Requirements generation script
├── start_server.sh             # Server startup script
└── restart_server.sh           # Server restart script

Разработка новых инструментов

В этом разделе описывается процесс добавления новых инструментов MCP в Doris MCP Server, основанный на унифицированной модульной архитектуре с централизованным управлением инструментами.

Существующие бизнес-API не нужно встраивать в этот репозиторий. Вместо этого упакуйте их как явно установленные, разрешенные пользовательские провайдеры инструментов. Руководство по пользовательским провайдерам инструментов определяет контракт точки входа, жизненный цикл, локальные для процесса ограничения QPS, границу аутентификации, интеграцию с FastGPT и контрольный список безопасности для промышленной эксплуатации.

1. Используйте существующие служебные модули

Сервер предоставляет комплексные служебные модули для общих операций с базами данных:

doris_mcp_server/utils/db.py: Управление подключениями к базе данных с пулом соединений и мониторингом работоспособности.
doris_mcp_server/utils/query_executor.py: Высокопроизводительное выполнение SQL с расширенным кэшированием, оптимизацией и мониторингом производительности.
doris_mcp_server/utils/schema_extractor.py: Извлечение метаданных с полной поддержкой федерации каталогов.
doris_mcp_server/utils/security.py: Комплексное управление безопасностью, проверка SQL и маскирование данных.
doris_mcp_server/utils/analysis_tools.py: Расширенные инструменты анализа данных и статистики.
doris_mcp_server/utils/config.py: Управление конфигурацией с проверкой.
doris_mcp_server/utils/data_governance_tools.py: Отслеживание происхождения данных и мониторинг актуальности (Новое в v0.5.0).
doris_mcp_server/utils/data_quality_tools.py: Комплексная платформа анализа качества данных (Новое в v0.5.0).
doris_mcp_server/utils/adbc_query_tools.py: Высокопроизводительные операции Arrow Flight SQL (Новое в v0.5.0).

2. Реализуйте логику инструмента

Добавьте частный обработчик в DorisToolsManager в doris_mcp_server/tools/tools_manager.py. Имена обработчиков следуют формату _<tool_name>_tool; реестр разрешает это имя и проверяет, что обработчик существует во время создания менеджера.

Пример: Добавление нового инструмента анализа:

# In doris_mcp_server/tools/tools_manager.py

async def _your_new_analysis_tool(
    self,
    arguments: dict[str, Any],
) -> dict[str, Any]:
    """
    Your new analysis tool implementation
    
    Args:
        arguments: Tool arguments from MCP client
        
    Returns:
        JSON-serializable tool result
    """
    try:
        # Use existing utilities
        result = await self.query_executor.execute_sql_for_mcp(
            sql="SELECT COUNT(*) FROM your_table",
            max_rows=arguments.get("max_rows", 100)
        )
        
        return result
        
    except Exception as e:
        logger.error(f"Tool execution failed: {str(e)}", exc_info=True)
        return {"success": False, "error": "Analysis failed"}

3. Добавьте определение в реестр

Добавьте одну схему Tool в doris_mcp_server/tools/tool_catalog.py::build_tool_registry, затем классифицируйте ее политику один раз в doris_mcp_server/tools/tool_registry.py. Не добавляйте обертку-декоратор или ветку диспетчеризации if/elif:

# In doris_mcp_server/tools/tool_catalog.py

Tool(
    name="your_new_analysis_tool",
    description="Description of your new analysis tool",
    input_schema={
        "type": "object",
        "properties": {
            "parameter1": {
                "type": "string",
                "description": "Description of parameter1"
            },
            "parameter2": {
                "type": "integer", 
                "description": "Description of parameter2",
                "default": 100
            }
        },
        "required": ["parameter1"],
    },
)

Пользовательские провайдеры являются внутренними источниками возможностей и не создают дополнительных инструментов MCP верхнего уровня. Интегрируйте каждую возможность провайдера в один формальный дочерний домен с контрактом поддержки, политикой авторизации, схемами ввода/вывода и детерминированной привязкой обработчика. Тестовый набор отклоняет дрейф публичного каталога.

4. Расширенные возможности

Для более сложных инструментов вы можете использовать комплексную платформу:

Продвинутое кеширование: Используйте встроенное кеширование исполнителя запросов для повышения производительности
Корпоративная безопасность: Применяйте комплексную проверку SQL и маскирование данных через менеджер безопасности
Интеллектуальные подсказки: Используйте менеджер подсказок для продвинутой генерации запросов
Управление ресурсами: Предоставляйте метаданные через менеджер ресурсов
Мониторинг производительности: Интегрируйтесь с инструментами анализа для возможностей мониторинга

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

Протестируйте ваш новый инструмент с помощью встроенного MCP-клиента:

# Using doris_mcp_client/client.py
from doris_mcp_client.client import DorisUnifiedMCPClient

async def test_new_tool():
    client = DorisUnifiedMCPClient()
    result = await client.call_tool("your_new_analysis_tool", {
        "parameter1": "test_value",
        "parameter2": 50
    })
    print(result)

Запустите контрольный тест релиза с помощью:

uv run pytest -q -W error
uv run coverage json -o coverage.json
uv run python test/deployment/check_coverage_domains.py coverage.json

Тестовый набор требует покрытия не менее 55% по всему репозиторию. Сгенерированный отчет о покрытии также проверяется на минимальном уровне 80% для доменов протокола, аутентификации и основных менеджеров, чтобы высокорисковый код времени выполнения не мог быть скрыт за счет несвязанного покрытия.

MCP-клиент

Проект включает унифицированный MCP-клиент (doris_mcp_client/) для целей тестирования и интеграции. Клиент поддерживает несколько режимов подключения и предоставляет удобный интерфейс для взаимодействия с MCP-сервером.

Подробную документацию по клиенту см. в doris_mcp_client/README.md.

Участие в разработке

Приветствуется участие через Issues или Pull Requests.

Лицензия

Этот проект лицензирован под Apache 2.0 License. Подробности см. в файле LICENSE.

Часто задаваемые вопросы

В: Почему Qwen3-32b и другие модели с малым количеством параметров всегда терпят неудачу при вызове инструментов?

О: Это распространенная проблема. Основная причина в том, что этим моделям требуется более явное руководство для корректного использования инструментов MCP. Рекомендуется добавить следующую инструкцию-подсказку для модели:

Версия на китайском：

<instruction>
尽可能使用MCP工具完成任务，仔细阅读每个工具的注解、方法名、参数说明等内容。请按照以下步骤操作：

1. 仔细分析用户的问题，从已有的Tools列表中匹配最合适的工具。
2. 确保工具名称、方法名和参数完全按照工具注释中的定义使用，不要自行创造工具名称或参数。
3. 传入参数时，严格遵循工具注释中规定的参数格式和要求。
4. 调用工具时，根据需要直接调用工具，但参数请求参考以下请求格式：{"mcp_sse_call_tool": {"tool_name": "$tools_name", "arguments": "{}"}}
5. 输出结果时，不要包含任何XML标签，仅返回纯文本内容。

<input>
用户问题：user_query
</input>

<output>
返回工具调用结果或最终答案，以及对结果的分析。
</output>
</instruction>

Версия на английском：

<instruction>
Use MCP tools to complete tasks as much as possible. Carefully read the annotations, method names, and parameter descriptions of each tool. Please follow these steps:

1. Carefully analyze the user's question and match the most appropriate tool from the existing Tools list.
2. Ensure tool names, method names, and parameters are used exactly as defined in the tool annotations. Do not create tool names or parameters on your own.
3. When passing parameters, strictly follow the parameter format and requirements specified in the tool annotations.
4. When calling tools, call them directly as needed, but refer to the following request format for parameters: {"mcp_sse_call_tool": {"tool_name": "$tools_name", "arguments": "{}"}}
5. When outputting results, do not include any XML tags, return plain text content only.

<input>
User question: user_query
</input>

<output>
Return tool call results or final answer, along with analysis of the results.
</output>
</instruction>

Если у вас есть дополнительные требования к возвращаемым результатам, вы можете описать конкретные требования в теге <output>.

В: Как настроить различные подключения к базам данных?

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

Переменные окружения (Рекомендуется):

export DORIS_HOST="your_doris_host"
export DORIS_PORT="9030"
export DORIS_USER="root"
export DORIS_PASSWORD="your_password"

Аргументы командной строки:

doris-mcp-server --db-host your_host --db-port 9030 --db-user root --db-password your_password

Конфигурационный файл: Измените соответствующие параметры конфигурации в файле .env.

В: Как настроить узлы BE для инструментов мониторинга?

О: Настраивайте конечные точки SQL, FE HTTP и BE HTTP независимо, когда прокси, туннель или разделенная сеть предоставляют их по разным адресам:

# SQL/MySQL protocol endpoint
DORIS_HOST=sql-gateway.internal
DORIS_HOSTS=sql-gateway.internal,fe-2.internal,fe-3.internal
DORIS_PORT=9030

# FE HTTP endpoint; omit DORIS_FE_HTTP_HOST to reuse DORIS_HOST
DORIS_FE_HTTP_HOST=fe-http-proxy.internal
DORIS_FE_HTTP_HOSTS=fe-http-proxy.internal,fe-2.internal,fe-3.internal
DORIS_FE_HTTP_PORT=8030

# Explicit BE HTTP allowlist
DORIS_BE_HOSTS=10.1.1.100,10.1.1.101,10.1.1.102
DORIS_BE_WEBSERVER_PORT=8040

Конечные точки BE HTTP никогда не выводятся из SHOW BACKENDS: метаданные SQL не являются белым списком исходящего HTTP. Если DORIS_BE_HOSTS пуст, метрики BE HTTP отключены. DORIS_FE_HTTP_HOST возвращается к DORIS_HOST только для обратной совместимости; явное значение используется для каждого HTTP-запроса мониторинга FE, профилирования, трассировки и размера таблицы. Запросы FE и BE используют только настроенные хосты и порты, закрепляют проверенные результаты DNS для каждого запроса, отклоняют адресата метаданных/локальной сети, отключают перенаправления и применяют тайм-ауты соединения/чтения/общие, а также ограничение размера ответа. Частные и петлевые адреса остаются доступными для обычных внутренних развертываний Doris и SSH-туннелей.

DORIS_HOSTS и DORIS_FE_HTTP_HOSTS являются упорядоченными списками аварийного переключения, а не настройками балансировки нагрузки или обнаружения кластера. Каждый хост в одном списке должен принадлежать одному кластеру Doris и использовать настроенный общий порт и учетные данные. Сервер проверяет кандидатов по порядку во время создания и восстановления глобального/статического пула токенов; HTTP-запросы FE переходят к следующей настроенной конечной точке только при транспортной ошибке или 502/503/504. OAuth на базе Doris пробует кандидатов во время входа в систему, но установленный пул для каждого пользователя не может быть восстановлен после сбоя, поскольку сервер намеренно не сохраняет необработанный пароль пользователя; пользователь должен войти снова. Стабильный балансировщик нагрузки или SQL-шлюз по-прежнему рекомендуется для крупных производственных развертываний.

В: Как использовать файлы SQL Explain/Profile с LLM для оптимизации?

О: Инструменты предоставляют как усеченное содержимое, так и полные файлы для анализа LLM:

Получение результатов анализа:

{
  "content": "Truncated plan for immediate review",
  "file_path": "/tmp/explain_12345.txt",
  "is_content_truncated": true
}

Рабочий процесс анализа LLM:
- Просмотрите усеченное содержимое для быстрого понимания
- Загрузите полный файл в вашу LLM как вложение
- Запросите предложения по оптимизации или анализ производительности
- Внедрите рекомендованные улучшения
Настройка размера содержимого:
```
MAX_RESPONSE_CONTENT_SIZE=4096  # Adjust as needed
```

В: Как включить функции безопасности данных и маскирования?

О: Установите следующие конфигурации в вашем файле .env:

# Enable data masking
ENABLE_MASKING=true
# Set maximum result rows
MAX_RESULT_ROWS=10000

В: В чем разница между режимом Stdio и режимом HTTP?

О:

Режим Stdio: Подходит для прямой интеграции с MCP-клиентами (такими как Cursor), где клиент управляет процессом сервера
Режим HTTP: Независимый веб-сервис, поддерживающий несколько клиентских подключений, подходит для производственных сред

Рекомендации:

Разработка и личное использование: режим Stdio
Производственные и многопользовательские среды: режим HTTP

В: Как решить проблемы с тайм-аутом соединения?

О: Попробуйте следующие решения:

Увеличьте настройки тайм-аута:

# Set in .env file
QUERY_TIMEOUT=60
CONNECTION_TIMEOUT=30

Проверьте сетевое подключение:

# /live verifies the process; /ready also verifies Doris
curl --fail http://localhost:3000/live
curl --fail http://localhost:3000/ready

Оптимизируйте конфигурацию пула соединений:
```
DORIS_MAX_CONNECTIONS=20
```

В: Как решить ошибки соединения `at_eof`? (Полностью исправлено в v0.5.0)

О: Версия 0.5.0 полностью устранила критические ошибки соединения at_eof путем комплексной переработки пула соединений:

Проблема:

Ошибки at_eof возникали из-за предварительного создания пула соединений и неправильного управления состоянием соединения
Состояние чтения MySQL aiomysql становилось несогласованным в течение жизненного цикла соединения
Нестабильность пула соединений при параллельной нагрузке

Решение (v0.5.0):

Пересмотр стратегии пула соединений:
- Ноль минимальных соединений: Изменено min_connections со значения по умолчанию на 0 для предотвращения проблем предварительного создания
- Создание соединений по требованию: Соединения создаются только при необходимости, устраняя проблемы устаревших соединений
- Стратегия свежих соединений: Всегда получать свежие соединения из пула, без кеширования на уровне сессии
Улучшенный мониторинг работоспособности:
- Проверки работоспособности на основе тайм-аута: 3-секундный тайм-аут для запросов проверки соединения
- Фоновый монитор работоспособности: Непрерывный мониторинг работоспособности пула каждые 30 секунд
- Проактивное обнаружение устаревших: Автоматическое обнаружение и очистка проблемных соединений
Интеллектуальная система восстановления:
- Автоматическое восстановление пула: Самовосстанавливающийся пул с комплексной обработкой ошибок
- Экспоненциальная отсрочка повторных попыток: Умный механизм повторных попыток с количеством до 3 попыток
- Обнаружение ошибок, специфичных для соединения: Точная идентификация ошибок, связанных с соединением
Оптимизация производительности:
- Прогрев пула: Интеллектуальный прогрев пула соединений для оптимальной производительности
- Фоновая очистка: Периодическая очистка устаревших соединений без влияния на активные операции
- Диагностика соединений: Мониторинг и отчетность о работоспособности соединений в реальном времени

Мониторинг работоспособности соединения:

# Monitor connection pool health in real-time
tail -f logs/doris_mcp_server_info.log | grep -E "(pool|connection|at_eof)"

# Check detailed connection diagnostics
tail -f logs/doris_mcp_server_debug.log | grep "connection health"

# Check process liveness and Doris readiness
curl --fail http://localhost:8000/live
curl --fail http://localhost:8000/ready

Конфигурация для оптимальной производительности соединения:

# Recommended connection pool settings in .env
DORIS_MAX_CONNECTIONS=20          # Adjust based on workload
CONNECTION_TIMEOUT=30             # Connection establishment timeout
QUERY_TIMEOUT=60                  # Query execution timeout

# Health monitoring settings
HEALTH_CHECK_INTERVAL=60          # Pool health check frequency

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

В: Какие версии протокола MCP поддерживаются?

О: Для новых интеграций следует использовать MCP 2026-07-28. Doris MCP Server принимает поток инициализации 2025-11-25 через stdio и, когда ENABLE_LEGACY_HTTP_ADAPTER=true, на изолированной конечной точке HTTP /mcp/legacy. Современная конечная точка /mcp работает только с POST и никогда не возвращается к устаревшему транспорту. Более старые версии и выведенный из эксплуатации транспорт HTTP+SSE не являются частью поддерживаемого контракта совместимости.

Не делайте выводов о поддержке проводного протокола из версии пакета Doris MCP Server или версии зависимости Python mcp. См. Поддержка протокола MCP и миграция для получения информации о метаданных запроса, HTTP-заголовках, шагах миграции и ограничениях развертывания.

В: Как включить высокопроизводительные функции ADBC? (Новое в v0.5.0)

О: ADBC (Arrow Flight SQL) обеспечивает повышение производительности в 3-10 раз для больших наборов данных:

Зависимости ADBC (автоматически включены в v0.5.0+):

# ADBC dependencies are now included by default in doris-mcp-server>=0.5.0
# No separate installation required

Настройка портов Arrow Flight SQL:

# Add to your .env file
FE_ARROW_FLIGHT_SQL_PORT=8096
BE_ARROW_FLIGHT_SQL_PORT=8097

Дополнительная настройка ADBC:

# Customize ADBC behavior (optional)
ADBC_DEFAULT_MAX_ROWS=10000
ADBC_DEFAULT_TIMEOUT=120
ADBC_DEFAULT_RETURN_FORMAT=pandas  # arrow/pandas/dict

Тестирование соединения ADBC:

# Discover doris_query, then call its get_adbc_connection_info child
# Should show "status": "ready" and port connectivity

В: Как использовать инструменты управления данными и пайплайнами?

О: Сначала обнаружьте соответствующий домен, сохраните его manifest_version, а затем вызовите точный дочерний элемент с аргументами, проверенными по схеме:

Анализ столбцов:

{
  "tool_name": "doris_governance",
  "arguments": {
    "child_tool": "analyze_columns",
    "manifest_version": "<value returned by domain discovery>",
    "arguments": {
      "database": "analytics",
      "table": "customer_data",
      "sample_ratio": 0.1
    }
  }
}

Отслеживание происхождения столбцов:

{
  "tool_name": "doris_governance",
  "arguments": {
    "child_tool": "trace_column_lineage",
    "manifest_version": "<value returned by domain discovery>",
    "arguments": {
      "object": "internal.analytics.orders",
      "column": "customer_id",
      "direction": "both",
      "depth": 3
    }
  }
}

Мониторинг актуальности данных:

{
  "tool_name": "doris_pipeline",
  "arguments": {
    "child_tool": "monitor_data_freshness",
    "manifest_version": "<value returned by domain discovery>",
    "arguments": {
      "database": "analytics",
      "table": "orders",
      "threshold_seconds": 86400
    }
  }
}

Аналитика производительности:

{
  "tool_name": "doris_query",
  "arguments": {
    "child_tool": "list_slow_queries",
    "manifest_version": "<value returned by domain discovery>",
    "arguments": {
      "window_minutes": 10080,
      "limit": 20
    }
  }
}

В: Как использовать улучшенную систему логирования? (Улучшено в v0.5.0)

О: Версия 0.5.0 представляет комплексную систему логирования с автоматическим управлением и организацией по уровням:

Структура файлов журналов (Новое в v0.5.0):

logs/
├── doris_mcp_server_debug.log      # DEBUG level messages
├── doris_mcp_server_info.log       # INFO level messages  
├── doris_mcp_server_warning.log    # WARNING level messages
├── doris_mcp_server_error.log      # ERROR level messages
├── doris_mcp_server_critical.log   # CRITICAL level messages
├── doris_mcp_server_all.log        # Combined log (all levels)
└── doris_mcp_server_audit.log      # Audit trail (separate)

Улучшенные функции логирования:

Разделение файлов по уровням: Автоматическая организация по уровню журнала для упрощения устранения неполадок
Форматирование с метками времени: Точность до миллисекунды с правильным выравниванием для профессионального логирования
Автоматическая ротация журналов: Предотвращает проблемы с дисковым пространством с помощью настраиваемых ограничений размера файла
Фоновая очистка: Интеллектуальный планировщик очистки с настраиваемыми политиками хранения
Аудиторский след: Отдельное логирование аудита для соответствия требованиям и мониторинга безопасности

Просмотр журналов:

# View real-time logs by level
tail -f logs/doris_mcp_server_info.log     # General operational info
tail -f logs/doris_mcp_server_error.log    # Error tracking
tail -f logs/doris_mcp_server_debug.log    # Detailed debugging

# View all activity in combined log
tail -f logs/doris_mcp_server_all.log

# Monitor specific operations
tail -f logs/doris_mcp_server_info.log | grep -E "(query|connection|tool)"

# View audit trail
tail -f logs/doris_mcp_server_audit.log

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

# Enhanced logging configuration in .env
LOG_LEVEL=INFO                         # Base log level
ENABLE_AUDIT=true                      # Enable audit logging
ENABLE_LOG_CLEANUP=true                # Enable automatic cleanup
LOG_MAX_AGE_DAYS=30                    # Keep logs for 30 days
LOG_CLEANUP_INTERVAL_HOURS=24          # Check for cleanup daily

# Advanced settings
LOG_FILE_PATH=logs                     # Log directory (auto-organized)

Устранение неполадок с помощью улучшенных журналов:

# Debug connection issues
grep -E "(connection|pool|at_eof)" logs/doris_mcp_server_error.log

# Monitor tool performance
grep "execution_time" logs/doris_mcp_server_info.log

# Check system health
tail -20 logs/doris_mcp_server_warning.log

# View recent critical issues
cat logs/doris_mcp_server_critical.log

Управление очисткой журналов:

Автоматически: Фоновый планировщик удаляет файлы старше LOG_MAX_AGE_DAYS
Вручную: Журналы автоматически ротируются при достижении 10 МБ
Резервное копирование: Хранит 5 резервных файлов для каждого уровня журнала
Производительность: Минимальное влияние на производительность сервера

В: Как использовать новую конфигурацию базы данных, привязанную к токену? (Новое в v0.6.0)

О: Революционная конфигурация базы данных, привязанная к токену, позволяет каждому токену нести собственные параметры подключения к базе данных для безопасного многопользовательского доступа:

Включить аутентификацию по токену:

# In your .env file
ENABLE_TOKEN_AUTH=true
TOKEN_HOT_RELOAD=true
TOKEN_FILE_PATH=tokens.json

Создайте токен-носитель один раз и сохраните только его дайджест в tokens.json:

{
  "version": "2.0",
  "tokens": [
    {
      "token_id": "tenant-alpha",
      "token_digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
      "created_at": "2026-07-29T00:00:00Z",
      "expires_at": null,
      "last_used": null,
      "description": "Tenant Alpha database access",
      "is_active": true,
      "database_config": {
        "host": "tenant-alpha-db.company.com",
        "hosts": [
          "tenant-alpha-fe-1.company.com",
          "tenant-alpha-fe-2.company.com"
        ],
        "port": 9030,
        "user": "alpha_user",
        "password": "secure_password",
        "database": "alpha_analytics",
        "charset": "UTF8",
        "fe_http_hosts": [
          "tenant-alpha-fe-1.company.com",
          "tenant-alpha-fe-2.company.com"
        ],
        "fe_http_port": 8030
      }
    }
  ]
}

Сгенерируйте реальный токен-носитель и дайджест с помощью команды в Конфигурация базы данных, привязанная к токену. Значение из всех нулей выше намеренно непригодно для использования. Передайте значение носителя клиенту один раз; не помещайте его в файл.

Приоритет конфигурации (Новое в v0.6.0):
- Конфигурация БД, привязанная к токену (наивысший приоритет)
- Переменные окружения (.env)
- Ошибка, если ничего не доступно
Преимущества горячей перезагрузки:
- Добавление новых арендаторов без перезапуска службы
- Обновление учетных данных базы данных в реальном времени
- Автоматическая проверка и откат при ошибках
- Полный аудиторский след изменений
Многопользовательское использование:
```
# Different tokens access different databases automatically
curl -H "Authorization: Bearer $TOKEN_TENANT_ALPHA" http://localhost:3000/mcp
curl -H "Authorization: Bearer $TOKEN_TENANT_BETA" http://localhost:3000/mcp
```
Каждая привязка токена может указывать на разный кластер Doris. В рамках одной привязки токена hosts и fe_http_hosts являются упорядоченными кандидатами FE для одного и того же кластера. Аутентифицированный токен фиксирует маршрут; аргументы инструмента MCP не могут выбирать или переопределять другой кластер. Этот режим с несколькими экземплярами требует HTTP- транспорта с аутентификацией по статическому токену. Процесс stdio имеет один глобальный маршрут базы данных, поэтому запускайте отдельные процессы stdio, когда клиентам нужны разные кластеры. exec_adbc_query намеренно закрыт при сбое на маршрутах, привязанных к токену, поскольку текущий клиент Arrow Flight является глобальным для процесса; используйте doris_query.execute_query или отдельный процесс MCP для этого кластера.

В: Чем OAuth на базе Doris отличается от внешнего OAuth/OIDC?

О: Внешний OAuth/OIDC делегирует идентификацию внешнему провайдеру, такому как Google, Azure AD, GitHub, GitLab или Keycloak. OAuth на базе Doris выпускается этим сервером MCP после входа пользователя с учетными данными Doris. Сервер проверяет имя пользователя/пароль Doris, создает пул соединений Doris для каждого пользователя, выпускает doa_ токены доступа и обновления и позволяет ролевой модели управления доступом (RBAC) Doris определять, к каким данным и метаданным пользователь может получить доступ.

Эти режимы являются взаимоисключающими на одном URL MCP. Не включайте ENABLE_DORIS_OAUTH_AUTH=true вместе с ENABLE_OAUTH_AUTH=true, OAUTH_ENABLED=true или AUTH_TYPE=oauth; запуск немедленно завершается ошибкой, если настроены оба режима OAuth.

OAuth на базе Doris в настоящее время предоставляет ресурсы MCP с отключенным кэшем метаданных ресурсов. Он предоставляет проверенные инструменты метаданных, когда DORIS_OAUTH_DB_TOOLS_ENABLED=true, exec_query, когда DORIS_OAUTH_QUERY_TOOLS_ENABLED=true, и объяснение SQL, когда DORIS_OAUTH_EXPLAIN_TOOLS_ENABLED=true. Обычным клиентам не нужно передавать длинный список областей; пропущенная область OAuth предоставляет настроенный конверт возможностей OAuth Doris. RBAC Doris остается окончательным бэкендом авторизации данных для этих операций по каналу MySQL.

В: Может ли OAuth на базе Doris работать с несколькими рабочими процессами или несколькими узлами?

О: Нет, в текущей реализации. OAuth на базе Doris использует хранилище OAuth только в памяти и локальные для процесса пулы Doris для каждого пользователя. Токены доступа, токены обновления, коды авторизации, клиенты DCR и пулы не разделяются между рабочими процессами, процессами или узлами.

Используйте WORKERS=1 с OAuth на базе Doris. WORKERS=0 расширяется до количества ядер ЦП и завершается ошибкой, поскольку это создало бы несколько эффективных рабочих процессов. Горизонтальное масштабирование без сохранения состояния, общее хранилище токенов, общие зашифрованные учетные данные Doris, восстановление прикрепленных сессий и восстановление пулов — это будущие разработки, а не текущие возможности.

В: Как работает горячая перезагрузка и безопасна ли она? (Новое в v0.6.0)

О: Система горячей перезагрузки разработана для корпоративных производственных сред с комплексными мерами безопасности:

Как это работает:

Синхронизация во время запроса: Каждый поиск токена сравнивает общую сигнатуру файла, поэтому создание или отзыв другим локальным рабочим процессом обнаруживается при следующем аутентифицированном запросе, а не при ожидании интервала опроса
Фоновый мониторинг: 10-секундный монитор по-прежнему обновляет неактивные рабочие процессы
Сериализованные обновления: tokens.json.lock защищает каждую управляемую операцию чтения-изменения-записи между локальными рабочими процессами
Атомарные обновления: Временный файл в том же каталоге сбрасывается и заменяется атомарно с разрешениями только для владельца
Защита от отката: Некорректное внешне отредактированное состояние не заменяет частично текущее представление рабочего процесса в памяти
Общий отзыв: revoked_tokens хранит только дайджесты токенов, а также отключает соответствующие TOKEN_<ID> учетные данные среды в каждом рабочем процессе

Функции безопасности:

Отсутствие потерянных обновлений: Параллельные операции создания/отзыва перезагружают последний документ, удерживая общую для процесса блокировку
Отсутствие постоянного хранения токена-носителя в открытом виде: Активные и отозванные значения носителя представлены только самоописывающими дайджестами
Файлы состояния только для владельца: Управляемые файлы состояния и блокировки используют режим 0600
Изоляция ошибок: Некорректное состояние отклоняется до того, как оно сможет заменить полную локальную карту токенов

Лучшие практики:

# Monitor hot reload activity
tail -f logs/doris_mcp_server_info.log | grep "hot reload"

# Test configuration before applying
cp tokens.json tokens.json.backup
# Make changes to tokens.json
# System will automatically validate and apply or rollback

В: Как управлять жизненным циклом и безопасностью токенов? (Новое в v0.6.0)

О: Управление токенами использует безопасный файловый подход с дополнительными административными конечными точками, имеющими комплексные средства контроля безопасности.

Основной метод управления токенами (рекомендуется):

# 1. Keep the management endpoint disabled unless local administration is needed.
# 2. When enabled, create a token through the protected localhost endpoint.
curl -X POST \
  -H "Authorization: Bearer $TOKEN_MANAGEMENT_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"token_id":"service-a","expires_hours":720}' \
  http://127.0.0.1:3000/token/create

# 3. Capture the returned bearer token once and place it in the client secret store.
# 4. The server writes only token_digest to tokens.json.
# 5. Monitor hot reload in logs.
tail -f logs/doris_mcp_server_info.log | grep "hot reload"

Для развертываний без управления токенами по HTTP используйте секрет среды с высокой энтропией TOKEN_<ID> или сгенерируйте пару носитель/дайджест офлайн, как показано выше. Записи с ручным управлением tokens.json должны использовать token_digest; записи token в открытом виде существуют только для односторонней миграции с версии 1.

Файловый бэкенд координирует несколько рабочих процессов на одном хосте. Каждый рабочий процесс должен использовать один и тот же TOKEN_FILE_PATH, а базовая файловая система должна обеспечивать надежную блокировку файлов и семантику атомарного переименования. Несколько хостов или контейнеров без общей файловой системы с блокировками требуют внешнего транзакционного бэкенда состояния; копирование отдельных файлов tokens.json не обеспечивает отзыв в масштабе кластера.

Административные конечные точки (безопасные, только локальный доступ):

🛡️ БЕЗОПАСНОСТЬ: Эти конечные точки защищены комплексными средствами контроля безопасности и отключены по умолчанию.

# Security Requirements (ALL must be met):
# ✓ HTTP token management explicitly enabled in configuration
# ✓ Access only from localhost (127.0.0.1/::1) - IP restrictions enforced
# ✓ Valid admin authentication token required
# ✓ Admin authentication enabled in configuration

# Enable HTTP token management (disabled by default)
export TOKEN_MANAGEMENT_ADMIN_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
export ENABLE_HTTP_TOKEN_MANAGEMENT=true
export REQUIRE_ADMIN_AUTH=true
export TOKEN_MANAGEMENT_ALLOWED_IPS=127.0.0.1,::1

# Access with proper authentication
curl -H "Authorization: Bearer $TOKEN_MANAGEMENT_ADMIN_TOKEN" http://127.0.0.1:3000/token/stats

# Demo page (local access only, with authentication)
# Access: http://127.0.0.1:3000/token/demo

Рекомендуемый рабочий процесс управления токенами:

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

// tokens.json
{
  "version": "2.0",
  "tokens": [
    {
      "token_id": "dev-token",
      "token_digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
      "created_at": "2026-07-29T00:00:00Z",
      "expires_at": "2026-07-30T00:00:00Z",
      "last_used": null,
      "description": "Development environment access",
      "is_active": true
    }
  ]
}

Замените нулевой дайджест на полученный из безопасно сгенерированного токена-носителя и храните этот токен-носитель вне файла сервера.

Производственное развертывание:

# Use secure token generation
openssl rand -hex 32  # Generate secure token

# Store in secure configuration management
# Never commit tokens to version control
# Use environment variables for sensitive tokens

Функции безопасности:

Хранение только дайджестов: Открытый текст носителя возвращается только при создании; файлы версии 2 содержат самоописывающие дайджесты SHA-256/SHA-512
Атомарное управление файлами: Управляемые записи используют замену в том же каталоге и принудительно устанавливают разрешения только для владельца 0600
Горячая перезагрузка: Автоматическое обновление конфигурации без прерывания обслуживания
Миграция устаревших версий: Записи в открытом виде версии 1 заменяются записями только с дайджестом при первой успешной загрузке
Аудиторский след: Полное протоколирование всех операций с токенами и изменений
Управление сроком действия: Автоматическая очистка просроченных токенов
Только локальный администратор: Конечные точки управления ограничены доступом с localhost
Проверка конфигурации: Немедленная проверка конфигураций токенов и баз данных

Лучшие практики безопасности:

Храните значения носителя в клиентском управлении секретами; на сервере храните только дайджесты
Никогда не открывайте конечные точки управления токенами для внешних сетей
Используйте надежные, случайно сгенерированные токены для производства
Храните файлы tokens.json с ручным управлением доступными только для чтения владельцу; управляемые записи принудительно устанавливают 0600
Регулярный аудит активных токенов и шаблонов их использования
Мониторинг журналов горячей перезагрузки на предмет несанкционированных изменений конфигурации

По другим вопросам, пожалуйста, проверьте GitHub Issues или отправьте новый issue.