Дорис MCP Сервер

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

Основные характеристики

Реализация протокола MCP : предоставляет стандартные интерфейсы MCP, поддерживающие вызовы инструментов, управление ресурсами и оперативное взаимодействие.
Несколько режимов связи :
- SSE (события, отправленные сервером) : обслуживаются через конечные точки /sse (инициализация) и /mcp/messages (связь) ( src/sse_server.py ).
- Потоковый HTTP : обслуживается через унифицированную конечную точку /mcp , поддерживая запрос/ответ и потоковую передачу ( src/streamable_server.py ).
- (Необязательно) Stdio : взаимодействие возможно через стандартный ввод/вывод ( src/stdio_server.py ), требуется определенная конфигурация запуска.
Интерфейс на основе инструментов : основные функции инкапсулированы в виде инструментов MCP, которые клиенты могут вызывать по мере необходимости. Доступные в настоящее время ключевые инструменты фокусируются на прямом взаимодействии с базой данных:
- Выполнение SQL ( mcp_doris_exec_query )
- Список баз данных и таблиц ( mcp_doris_get_db_list , mcp_doris_get_db_table_list )
- Извлечение метаданных ( mcp_doris_get_table_schema , mcp_doris_get_table_comment , mcp_doris_get_table_column_comments , mcp_doris_get_table_indexes )
- Извлечение журнала аудита ( mcp_doris_get_recent_audit_logs ) Примечание: текущие инструменты в основном ориентированы на прямые операции с базами данных.
Взаимодействие с базой данных : предоставляет функциональные возможности для подключения к Apache Doris (или другим совместимым базам данных) и выполнения запросов ( src/utils/db.py ).
Гибкая конфигурация : настраивается с помощью файла .env , поддерживает настройки для подключений к базе данных, поставщиков/моделей LLM, ключей API, уровней ведения журнала и т. д.
Извлечение метаданных : возможность извлечения метаданных базы данных ( src/utils/schema_extractor.py ).

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

Питон 3.12+
Детали подключения к базе данных (например, Doris Host, Port, User, Password, Database)

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

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

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

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

pip install -r requirements.txt

3. Настройте переменные среды

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

cp env.example .env

Ключевые переменные среды:

Подключение к базе данных :
- DB_HOST : Имя хоста базы данных
- DB_PORT : порт базы данных (по умолчанию 9030)
- DB_USER : Имя пользователя базы данных
- DB_PASSWORD : Пароль базы данных
- DB_DATABASE : Имя базы данных по умолчанию
Конфигурация сервера :
- SERVER_HOST : Адрес хоста, который прослушивает сервер (по умолчанию 0.0.0.0 )
- SERVER_PORT : Порт, который прослушивает сервер (по умолчанию 3000 )
- ALLOWED_ORIGINS : разрешенные CORS источники (через запятую, * разрешает все)
- MCP_ALLOW_CREDENTIALS : разрешать ли учетные данные CORS (по умолчанию false )
Конфигурация ведения журнала :
- LOG_DIR : Каталог для файлов журнала (по умолчанию ./logs )
- LOG_LEVEL : Уровень журнала (например, INFO , DEBUG , WARNING , ERROR , INFO по умолчанию)
- CONSOLE_LOGGING : Выводить ли журналы на консоль (по умолчанию false )

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

В следующей таблице перечислены основные инструменты, доступные в настоящее время для вызова через клиент MCP:

Название инструмента	Описание	Параметры	Статус
`mcp_doris_get_db_list`	Получить список всех имен баз данных на сервере.	`random_string` (строка, обязательно)	✅ Активный
`mcp_doris_get_db_table_list`	Получить список всех имен таблиц в указанной базе данных.	`random_string` (string, Обязательно), `db_name` (string, Необязательно, по умолчанию текущая база данных)	✅ Активный
`mcp_doris_get_table_schema`	Получить подробную структуру указанной таблицы.	`random_string` (строка, Обязательно), `table_name` (строка, Обязательно), `db_name` (строка, Необязательно)	✅ Активный
`mcp_doris_get_table_comment`	Получить комментарий к указанной таблице.	`random_string` (строка, Обязательно), `table_name` (строка, Обязательно), `db_name` (строка, Необязательно)	✅ Активный
`mcp_doris_get_table_column_comments`	Получить комментарии для всех столбцов указанной таблицы.	`random_string` (строка, Обязательно), `table_name` (строка, Обязательно), `db_name` (строка, Необязательно)	✅ Активный
`mcp_doris_get_table_indexes`	Получить информацию об индексе для указанной таблицы.	`random_string` (строка, Обязательно), `table_name` (строка, Обязательно), `db_name` (строка, Необязательно)	✅ Активный
`mcp_doris_exec_query`	Выполнить SQL-запрос и вернуть команду результата.	`random_string` (строка, Обязательно), `sql` (строка, Обязательно), `db_name` (строка, Необязательно), `max_rows` (целое число, Необязательно, по умолчанию 100), `timeout` (целое число, Необязательно, по умолчанию 30)	✅ Активный
`mcp_doris_get_recent_audit_logs`	Получите записи журнала аудита за последний период.	`random_string` (строка, обязательно), `days` (целое число, необязательно, по умолчанию 7), `limit` (целое число, необязательно, по умолчанию 100)	✅ Активный

Примечание: Все инструменты требуют параметр random_string в качестве идентификатора вызова, который обычно автоматически обрабатывается клиентом MCP. «Необязательный» и «Обязательный» относятся к внутренней логике инструмента; клиенту может потребоваться предоставить значения для всех параметров в зависимости от его реализации. Перечисленные здесь имена инструментов являются базовыми именами; клиенты могут видеть их с префиксом (например, mcp_doris_stdio3_get_db_list ) в зависимости от режима подключения.

4. Запустите службу

Если вы используете режим SSE, выполните следующую команду:

./start_server.sh

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

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

Инициализация SSE : http://<host>:<port>/sse
SSE-коммуникация : http://<host>:<port>/mcp/messages (POST)
Потоковое HTTP : http://<host>:<port>/mcp (поддерживает GET, POST, DELETE, OPTIONS)
Проверка работоспособности : http://<host>:<port>/health
(Потенциальная) проверка статуса : http://<host>:<port>/status (подтвердите, если реализовано в main.py )

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

Для взаимодействия с Doris MCP Server требуется MCP Client . Клиент подключается к конечным точкам SSE или Streamable HTTP сервера и отправляет запросы (например, tool_call ) в соответствии со спецификацией MCP для вызова инструментов сервера.

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

Инициализация клиента : подключитесь к /sse (SSE) или отправьте вызов метода initialize в /mcp (потоковый).
(Необязательно) Обнаружение инструментов : клиент может вызвать mcp/listTools или mcp/listOfferings чтобы получить список поддерживаемых инструментов, их описания и схемы параметров.
Вызов инструмента : клиент отправляет сообщение/запрос tool_call , указывая tool_name и arguments .
- Пример: Получить схему таблицы
  - tool_name : mcp_doris_get_table_schema (или имя, специфичное для режима)
  - arguments : включают random_string , table_name , db_name .
Ответ на обработку :
- Непотоковый : клиент получает ответ, содержащий result или error .
- Потоковая передача : клиент получает ряд уведомлений об tools/progress , за которыми следует окончательный ответ, содержащий result или error .

Конкретные названия инструментов и параметры должны быть указаны в коде src/tools/ или получены через механизмы обнаружения MCP.

Подключение с помощью курсора

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

Режим Stdio

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

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

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

Настройте курсор: добавьте в конфигурацию Cursor MCP запись следующего вида:
{ "mcpServers": { "doris-stdio": { "command": "uv", "args": ["--project", "/path/to/your/doris-mcp-server", "run", "doris-mcp"], "env": { "DB_HOST": "127.0.0.1", "DB_PORT": "9030", "DB_USER": "root", "DB_PASSWORD": "your_db_password", "DB_DATABASE": "your_default_db" } }, // ... other server configurations ... } }
Ключевые моменты:
- Замените /path/to/your/doris-mcp на фактический абсолютный путь к корневому каталогу проекта в вашей системе. Аргумент --project имеет решающее значение для uv , чтобы найти pyproject.toml и запустить правильную команду.
- command установлена на uv (предполагая, что вы используете uv для управления пакетами, как указано в uv.lock ). args включают --project , путь, run и mcp-doris (который должен соответствовать скрипту, определенному в вашем pyproject.toml ).
- Подробности подключения к базе данных ( DB_HOST , DB_PORT , DB_USER , DB_PASSWORD , DB_DATABASE ) задаются непосредственно в блоке env в файле конфигурации. Курсор передаст их серверному процессу. Для этого режима не требуется файл .env при настройке через Курсор.

Режим SSE

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

Настройте .env : убедитесь, что учетные данные вашей базы данных и любые другие необходимые параметры (например, SERVER_PORT , если не используется порт по умолчанию 3000) правильно настроены в файле .env в каталоге проекта.
Запустите сервер: Запустите сервер из терминала в корневом каталоге проекта:
./start_server.sh
Этот скрипт обычно считывает файл .env и запускает сервер FastAPI в режиме SSE (проверьте скрипт и sse_server.py / main.py для получения подробной информации). Обратите внимание на хост и порт, которые прослушивает сервер (по умолчанию 0.0.0.0:3000 ).
Настройте курсор: добавьте в конфигурацию Cursor MCP запись следующего вида, указывающую на конечную точку SSE работающего сервера:
{ "mcpServers": { "doris-sse": { "url": "http://127.0.0.1:3000/sse" // Adjust host/port if your server runs elsewhere }, // ... other server configurations ... } }
Примечание: в примере используется порт по умолчанию 3000 Если ваш сервер настроен для работы на другом порту (например, 3010 в примере пользователя), измените URL-адрес соответствующим образом.

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

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

doris-mcp-server/
├── doris_mcp_server/    # Source code for the MCP server
│   ├── main.py          # Main entry point, FastAPI app definition
│   ├── mcp_core.py      # Core MCP tool registration and Stdio handling
│   ├── sse_server.py    # SSE server implementation
│   ├── streamable_server.py # Streamable HTTP server implementation
│   ├── config.py        # Configuration loading
│   ├── tools/           # MCP tool definitions
│   │   ├── mcp_doris_tools.py # Main Doris-related MCP tools
│   │   ├── tool_initializer.py # Tool registration helper (used by mcp_core.py)
│   │   └── __init__.py
│   ├── utils/           # Utility classes and helper functions
│   │   ├── db.py              # Database connection and operations
│   │   ├── logger.py          # Logging configuration
│   │   ├── schema_extractor.py # Doris metadata/schema extraction logic
│   │   ├── sql_executor_tools.py # SQL execution helper (might be legacy)
│   │   └── __init__.py
│   └── __init__.py
├── logs/                # Log file directory (if file logging enabled)
├── README.md            # This file
├── .env.example         # Example environment variable file
├── requirements.txt     # Python dependencies for pip
├── pyproject.toml       # Project metadata and build system configuration (PEP 518)
├── uv.lock              # Lock file for 'uv' package manager (alternative to pip)
├── start_server.sh      # Script to start the server
└── restart_server.sh    # Script to restart the server

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

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

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

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

doris_mcp_server/utils/db.py : предоставляет базовые функции для получения подключений к базе данных ( get_db_connection ) и выполнения необработанных запросов ( execute_query , execute_query_df ).
doris_mcp_server/utils/schema_extractor.py (класс MetadataExtractor ) : предлагает высокоуровневые методы для извлечения метаданных базы данных, такие как перечисление баз данных/таблиц ( get_all_databases , get_database_tables ), получение схем таблиц/комментариев/индексов ( get_table_schema , get_table_comment , get_column_comments , get_table_indexes ) и доступ к журналам аудита ( get_recent_audit_logs ). Включает механизмы кэширования.
doris_mcp_server/utils/sql_executor_tools.py (функция execute_sql_query ) : предоставляет оболочку вокруг db.execute_query , которая включает проверки безопасности (необязательно, контролируется переменной окружения ENABLE_SQL_SECURITY_CHECK ), добавляет автоматический LIMIT к запросам SELECT, обрабатывает сериализацию результатов (даты, десятичные числа) и форматирует вывод в стандартную структуру MCP success/error. Рекомендуется использовать это для выполнения предоставленного пользователем или сгенерированного SQL.

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

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

Реализуйте основную логику для вашего нового инструмента как async функцию в doris_mcp_server/tools/mcp_doris_tools.py . Это сохранит централизованность основных реализаций инструмента. Убедитесь, что ваша функция возвращает данные в формате, который можно легко обернуть в стандартную структуру ответа MCP (см. _format_response в том же файле для справки).

Пример: Давайте создадим простой инструмент get_server_time .

# In doris_mcp_server/tools/mcp_doris_tools.py
import datetime
# ... other imports ...
from doris_mcp_server.tools.mcp_doris_tools import _format_response # Reuse formatter

# ... existing tools ...

async def mcp_doris_get_server_time() -> Dict[str, Any]:
    """Gets the current server time."""
    logger.info(f"MCP Tool Call: mcp_doris_get_server_time")
    try:
        current_time = datetime.datetime.now().isoformat()
        # Use the existing formatter for consistency
        return _format_response(success=True, result={"server_time": current_time})
    except Exception as e:
        logger.error(f"MCP tool execution failed mcp_doris_get_server_time: {str(e)}", exc_info=True)
        return _format_response(success=False, error=str(e), message="Error getting server time")

3. Зарегистрируйте инструмент (двойная регистрация)

Из-за раздельной обработки режимов SSE/Streamable и Stdio вам необходимо зарегистрировать инструмент в двух местах:

A. SSE/Streamable регистрация ( tool_initializer.py )

Импортируйте новую функцию инструмента из mcp_doris_tools.py .
Внутри функции register_mcp_tools добавьте новую функцию-оболочку, декорированную @mcp.tool() .
Функция-оболочка должна вызывать функцию вашего основного инструмента.
Определите имя инструмента и предоставьте подробное описание (включая параметры, если таковые имеются) в декораторе. Не забудьте включить обязательное описание параметра random_string для совместимости с клиентом, даже если ваша оболочка явно не использует его.

Пример ( tool_initializer.py ):

# In doris_mcp_server/tools/tool_initializer.py
# ... other imports ...
from doris_mcp_server.tools.mcp_doris_tools import (
    # ... existing tool imports ...
    mcp_doris_get_server_time # <-- Import the new tool
)

async def register_mcp_tools(mcp):
    # ... existing tool registrations ...

    # Register Tool: Get Server Time
    @mcp.tool("get_server_time", description="""[Function Description]: Get the current time of the MCP server.\n
[Parameter Content]:\n
- random_string (string) [Required] - Unique identifier for the tool call\n""")
    async def get_server_time_tool() -> Dict[str, Any]:
        """Wrapper: Get server time"""
        # Note: No parameters needed for the core function call here
        return await mcp_doris_get_server_time()

    # ... logging registration count ...

B. Регистрация Stdio ( mcp_core.py )

Аналогично SSE добавьте новую функцию-оболочку, декорированную @stdio_mcp.tool() .
Важно: импортируйте основную функцию инструмента ( mcp_doris_get_server_time ) внутрь функции-оболочки (в этом файле используется шаблон отложенного импорта).
Обертка вызывает функцию основного инструмента. Сама обертка может потребовать async def в зависимости от того, как FastMCP обрабатывает инструменты в режиме Stdio, даже если базовая функция проста (как видно из текущей структуры файла). Убедитесь, что вызов соответствует (например, используйте await при вызове асинхронной функции).

Пример ( mcp_core.py ):

# In doris_mcp_server/mcp_core.py
# ... other imports and setup ...

# ... existing Stdio tool registrations ...

# Register Tool: Get Server Time (for Stdio)
@stdio_mcp.tool("get_server_time", description="""[Function Description]: Get the current time of the MCP server.\n
[Parameter Content]:\n
- random_string (string) [Required] - Unique identifier for the tool call\n""")
async def get_server_time_tool_stdio() -> Dict[str, Any]: # Using a slightly different wrapper name for clarity if needed
    """Wrapper: Get server time (Stdio)"""
    from doris_mcp_server.tools.mcp_doris_tools import mcp_doris_get_server_time # <-- Delayed import
    # Assuming the Stdio runner handles async wrappers correctly
    return await mcp_doris_get_server_time()

# --- Register Tools --- (Or wherever the registrations are finalized)

4. Перезапуск и тестирование

После внедрения и регистрации инструмента в обоих файлах перезапустите сервер MCP (в режиме SSE через ./start_server.sh и убедитесь, что команда Stdio, используемая Cursor, обновлена при необходимости) и протестируйте новый инструмент с помощью клиента MCP (например, Cursor) в обоих режимах подключения.

Внося вклад

Приветствуются ваши вклады через Issues или Pull Requests.

Лицензия

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

Doris MCP Server

Integrations