Дорис 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 ).

Related MCP server: Superset MCP Server

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

• Питон 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:

Примечание: Все инструменты требуют параметр 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 для вызова инструментов сервера.

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

1. Инициализация клиента : подключитесь к /sse (SSE) или отправьте вызов метода initialize в /mcp (потоковый).

2. (Необязательно) Обнаружение инструментов : клиент может вызвать mcp/listTools или mcp/listOfferings чтобы получить список поддерживаемых инструментов, их описания и схемы параметров.

3. Вызов инструмента : клиент отправляет сообщение/запрос tool_call , указывая tool_name и arguments .

   • Пример: Получить схему таблицы

     • tool_name : mcp_doris_get_table_schema (или имя, специфичное для режима)

     • arguments : включают random_string , table_name , db_name .

4. Ответ на обработку :

   • Непотоковый : клиент получает ответ, содержащий 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

1. Настройте курсор: добавьте в конфигурацию 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 ...
     }
   }

2. Ключевые моменты:

   • Замените /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, как к нему подключиться.

1. Настройте убедитесь, что учетные данные вашей базы данных и любые другие необходимые параметры (например, SERVER_PORT , если не используется порт по умолчанию 3000) правильно настроены в файле .env в каталоге проекта.

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

   ./start_server.sh

   Этот скрипт обычно считывает файл .env и запускает сервер FastAPI в режиме SSE (проверьте скрипт и sse_server.py / main.py для получения подробной информации). Обратите внимание на хост и порт, которые прослушивает сервер (по умолчанию 0.0.0.0:3000 ).

3. Настройте курсор: добавьте в конфигурацию 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 ...
     }
   }

   Примечание: в примере используется порт по умолчанию

После настройки любого из режимов в 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 : предлагает высокоуровневые методы для извлечения метаданных базы данных, такие как перечисление баз данных/таблиц ( 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 : предоставляет оболочку вокруг 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 регистрация (

• Импортируйте новую функцию инструмента из mcp_doris_tools.py .

• Внутри функции register_mcp_tools добавьте новую функцию-оболочку, декорированную @mcp.tool() .

• Функция-оболочка должна вызывать функцию вашего основного инструмента.

• Определите имя инструмента и предоставьте подробное описание (включая параметры, если таковые имеются) в декораторе. Не забудьте включить обязательное описание параметра random_string для совместимости с клиентом, даже если ваша оболочка явно не использует его.

Пример (

# 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 (

• Аналогично SSE добавьте новую функцию-оболочку, декорированную @stdio_mcp.tool() .

• Важно: импортируйте основную функцию инструмента ( mcp_doris_get_server_time ) внутрь функции-оболочки (в этом файле используется шаблон отложенного импорта).

• Обертка вызывает функцию основного инструмента. Сама обертка может потребовать async def в зависимости от того, как FastMCP обрабатывает инструменты в режиме Stdio, даже если базовая функция проста (как видно из текущей структуры файла). Убедитесь, что вызов соответствует (например, используйте await при вызове асинхронной функции).

Пример (

# 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 (если он существует).