Hologres

Русский | 中文

Hologres MCP Server

Hologres MCP Server служит универсальным интерфейсом между AI-агентами и базами данных Hologres. Он обеспечивает бесперебойную связь между AI-агентами и Hologres, помогая AI-агентам получать метаданные базы данных Hologres и выполнять SQL-операции.

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

Режим 1: Использование локального файла

Загрузка

Загрузите с Github

git clone https://github.com/aliyun/alibabacloud-hologres-mcp-server.git

Интеграция с MCP

Добавьте следующую конфигурацию в файл конфигурации MCP-клиента:

{
    "mcpServers": {
        "hologres-mcp-server": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/alibabacloud-hologres-mcp-server",
                "run",
                "hologres-mcp-server"
            ],
            "env": {
                "HOLOGRES_HOST": "host",
                "HOLOGRES_PORT": "port",
                "HOLOGRES_USER": "access_id",
                "HOLOGRES_PASSWORD": "access_key",
                "HOLOGRES_DATABASE": "database"
            }
        }
    }
}

Режим 2: Использование режима PIP

Установка

Установите MCP Server, используя следующий пакет:

pip install hologres-mcp-server

Интеграция с MCP

Добавьте следующую конфигурацию в файл конфигурации MCP-клиента:

Используйте режим uv

{
    "mcpServers": {
        "hologres-mcp-server": {
            "command": "uv",
            "args": [
                "run",
                "--with",
                "hologres-mcp-server",
                "hologres-mcp-server"
            ],
            "env": {
                "HOLOGRES_HOST": "host",
                "HOLOGRES_PORT": "port",
                "HOLOGRES_USER": "access_id",
                "HOLOGRES_PASSWORD": "access_key",
                "HOLOGRES_DATABASE": "database"
            }
        }
    }
}

Используйте режим uvx

{
    "mcpServers": {
        "hologres-mcp-server": {
            "command": "uvx",
            "args": [
                "hologres-mcp-server"
            ],
            "env": {
                "HOLOGRES_HOST": "host",
                "HOLOGRES_PORT": "port",
                "HOLOGRES_USER": "access_id",
                "HOLOGRES_PASSWORD": "access_key",
                "HOLOGRES_DATABASE": "database"
            }
        }
    }
}

Режим 3: Использование потоковой передачи HTTP

Сервер поддерживает потоковую передачу HTTP для сценариев удаленного развертывания, где STDIO недоступен.

Запуск сервера

Перед запуском сервера задайте переменные окружения подключения к Hologres:

export HOLOGRES_HOST="your-hologres-instance.hologres.aliyuncs.com"
export HOLOGRES_PORT="80"
export HOLOGRES_USER="your_access_id"
export HOLOGRES_PASSWORD="your_access_key"
export HOLOGRES_DATABASE="your_database"

Затем запустите сервер:

# Using pip-installed package
hologres-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000

# Or using uvx
uvx hologres-mcp-server --transport streamable-http --host 0.0.0.0 --port 8000

Конечная точка MCP будет доступна по адресу http://<host>:<port>/mcp.

Параметры CLI

Параметр	По умолчанию	Описание
--transport	stdio	Тип транспорта: stdio, streamable-http или sse
--host	127.0.0.1	Хост для привязки (только для HTTP-транспорта)
--port	8000	Порт для прослушивания (только для HTTP-транспорта)

Интеграция с MCP

Добавьте следующую конфигурацию в файл конфигурации MCP-клиента:

{
    "mcpServers": {
        "hologres-mcp-server": {
            "url": "http://<host>:<port>/mcp"
        }
    }
}

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

# Add to Claude Code
claude mcp add hologres-mcp-server \
  -e HOLOGRES_HOST=<your_host> \
  -e HOLOGRES_PORT=<your_port> \
  -e HOLOGRES_USER=<your_access_id> \
  -e HOLOGRES_PASSWORD=<your_access_key> \
  -e HOLOGRES_DATABASE=<your_database> \
  -- uvx hologres-mcp-server

Компоненты

Инструменты

• execute_hg_select_sql: Выполнить SQL-запрос SELECT в базе данных Hologres
• execute_hg_select_sql_with_serverless: Выполнить SQL-запрос SELECT в базе данных Hologres с бессерверными вычислениями
• execute_hg_dml_sql: Выполнить SQL-запрос DML (INSERT, UPDATE, DELETE) в базе данных Hologres
• execute_hg_ddl_sql: Выполнить SQL-запрос DDL (CREATE, ALTER, DROP, COMMENT ON) в базе данных Hologres
• gather_hg_table_statistics: Собрать статистику таблицы в базе данных Hologres
  • Параметры: schema_name (строка), table (строка)
• get_hg_query_plan: Получить план запроса в базе данных Hologres
• get_hg_execution_plan: Получить план выполнения в базе данных Hologres
• call_hg_procedure: Вызвать процедуру в базе данных Hologres
• create_hg_maxcompute_foreign_table: Создать внешние таблицы MaxCompute в базе данных Hologres.

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

• list_hg_schemas: Выводит список всех схем в текущей базе данных Hologres, исключая системные схемы.
• list_hg_tables_in_a_schema: Выводит список всех таблиц в определенной схеме, включая их типы (таблица, представление, внешняя таблица, секционированная таблица).
  • Параметры: schema_name (строка)
• show_hg_table_ddl: Показать DDL-скрипт таблицы, представления или внешней таблицы в базе данных Hologres.
  • Параметры: schema_name (строка), table (строка)
• query_and_plotly_chart: Выполнить SQL-запрос SELECT и сгенерировать диаграмму (столбчатую, линейную, точечную, круговую, гистограмму, с областями). Возвращает результаты запроса и PNG-изображение в кодировке base64.
  • Параметры: query (строка), chart_type (строка, по умолчанию "bar"), x_column (строка), y_column (строка), title (строка)
• analyze_hg_query_by_id: Проанализировать профиль производительности конкретного запроса по его query_id из hg_query_log. Возвращает подробные метрики, включая длительность, память, процессорное время, статистику чтения/записи.
  • Параметры: query_id (строка)
• get_hg_slow_queries: Получить медленные запросы из hg_query_log, упорядоченные по длительности.
  • Параметры: min_duration_ms (целое число, по умолчанию 1000), limit (целое число, по умолчанию 20)
• list_hg_dynamic_tables: Вывести список всех динамических таблиц с их статусом, настройками актуальности и информацией о последнем обновлении.
  • Параметры: schema_name (строка, необязательный)
• get_hg_dynamic_table_refresh_history: Получить историю обновлений для конкретной динамической таблицы, включая длительность, статус и задержку.
  • Параметры: schema_name (строка), table_name (строка), limit (целое число, по умолчанию 10)
• list_hg_recyclebin: Вывести список всех таблиц в корзине Hologres (удаленных таблиц, которые можно восстановить).
• restore_hg_table_from_recyclebin: Восстановить удаленную таблицу из корзины Hologres.
  • Параметры: table_name (строка), schema_name (строка, по умолчанию "public")
• list_hg_warehouses: Вывести список всех вычислительных групп (хранилищ) с их CPU, памятью, количеством кластеров и статусом.
• switch_hg_warehouse: Переключить вычислительный ресурс текущей сессии на указанное хранилище.
  • Параметры: warehouse_name (строка)
• get_hg_table_storage_size: Получить сведения о размере хранилища таблицы, включая разбивку по общему объему, данным, индексу и метаданным.
  • Параметры: schema_name (строка), table (строка)
• cancel_hg_query: Отменить или завершить выполняющийся запрос по его идентификатору процесса.
  • Параметры: pid (целое число), terminate (логическое значение, по умолчанию false)
• list_hg_active_queries: Вывести список активных в данный момент запросов и подключений из pg_stat_activity.
  • Параметры: state (строка: "active", "idle" или "all", по умолчанию "active")
• list_hg_query_queues: Вывести список всех очередей запросов и их классификаторов (ограничения параллелизма, правила маршрутизации). Требуется версия 3.0+.
• get_hg_table_properties: Получить свойства таблицы, включая distribution_key, clustering_key, segment_key, bitmap_columns, настройки binlog и т.д.
  • Параметры: schema_name (строка), table (строка)
• get_hg_table_shard_info: Получить информацию о группе таблиц и количестве шардов таблицы для диагностики перекоса данных.
  • Параметры: schema_name (строка), table (строка)
• list_hg_external_databases: Вывести список всех внешних баз данных и внешних серверов для ускорения Lakehouse. Требуется версия 3.0+.
• get_hg_lock_diagnostics: Диагностировать конфликт блокировок, показывая блокирующие и ожидающие запросы.
• get_hg_table_info_trend: Получить тренд использования хранилища таблицей из hg_table_info, показывающий ежедневные изменения размера хранилища, количества файлов и количества строк.
  • Параметры: schema_name (строка), table (строка), days (целое число, по умолчанию 7)
• manage_hg_query_queue: Создать, удалить или очистить очередь запросов. Требуется версия 3.0+ и привилегии суперпользователя.
  • Параметры: action (строка: "create", "drop", "clear"), queue_name (строка), max_concurrency (целое число, для create), max_queue_size (целое число, для create)
• manage_hg_classifier: Создать или удалить классификатор для очереди запросов. Требуется версия 3.0+.
  • Параметры: action (строка: "create", "drop"), queue_name (строка), classifier_name (строка), priority (целое число, для create)
• set_hg_query_queue_property: Установить или удалить свойства очереди запросов или классификатора. Требуется версия 3.0+.
  • Параметры: target (строка: "queue", "classifier"), queue_name (строка), property_key (строка), property_value (строка), classifier_name (строка, для classifier), action (строка: "set", "remove")
• manage_hg_warehouse: Управлять вычислительной группой: приостановить, возобновить, перезапустить, переименовать или изменить размер. Требуются права суперпользователя.
  • Параметры: action (строка: "suspend", "resume", "restart", "rename", "resize"), warehouse_name (строка), cu (целое число, для resize), new_name (строка, для rename)
• get_hg_warehouse_status: Получить подробный статус работы и прогресс масштабирования вычислительной группы.
  • Параметры: warehouse_name (строка)
• rebalance_hg_warehouse: Запустить ребалансировку шардов для вычислительной группы, чтобы устранить перекос данных.
  • Параметры: warehouse_name (строка)
• list_hg_data_masking_rules: Вывести список всех правил маскирования данных, настроенных через расширение hg_anon (на уровне столбцов и пользователей).
• query_hg_external_files: Запрашивать файлы напрямую из OSS с помощью функции EXTERNAL_FILES без создания внешних таблиц. Требуется версия 4.1+.
  • Параметры: path (строка), format (строка: "csv", "parquet", "orc"), columns (строка, необязательный), oss_endpoint (строка, необязательный), role_arn (строка, необязательный)
• get_hg_guc_config: Получить текущее значение параметра GUC (Grand Unified Configuration).
  • Параметры: guc_name (строка)

Ресурсы

Встроенные ресурсы

• hologres:///schemas: Получить все схемы в базе данных Hologres

Шаблоны ресурсов

• hologres:///{schema}/tables: Вывести список всех таблиц в схеме базы данных Hologres

• hologres:///{schema}/{table}/partitions: Вывести список всех секций секционированной таблицы в базе данных Hologres

• hologres:///{schema}/{table}/ddl: Получить DDL таблицы в базе данных Hologres

• hologres:///{schema}/{table}/statistic: Показать собранную статистику таблицы в базе данных Hologres

• system:///{+system_path}: Системные пути включают:

  • hg_instance_version - Показывает версию экземпляра Hologres.
  • guc_value/<guc_name> - Показывает значение GUC (Grand Unified Configuration).
  • missing_stats_tables - Показывает таблицы, для которых отсутствует статистика.
  • stat_activity - Показывает информацию о текущих выполняемых запросах.
  • query_log/latest/<row_limits> - Получить историю журнала запросов с указанным количеством строк.
  • query_log/user/<user_name>/<row_limits> - Получить историю журнала запросов для конкретного пользователя с ограничением по строкам.
  • query_log/application/<application_name>/<row_limits> - Получить историю журнала запросов для конкретного приложения с ограничением по строкам.
  • query_log/failed/<interval>/<row_limits> - Получить историю неудачных запросов с интервалом и указанным количеством строк.

Подсказки

• analyze_table_performance: Сгенерировать подсказку для анализа производительности таблицы в Hologres
• optimize_query: Сгенерировать подсказку для оптимизации SQL-запроса в Hologres
• explore_schema: Сгенерировать подсказку для исследования схемы в базе данных Hologres

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

Проект включает комплексные модульные и интеграционные тесты.

Модульные тесты

Модульные тесты не требуют подключения к базе данных и используют имитированные зависимости. Набор тестов включает 326 тестовых случаев, охватывающих:

• Функциональность инструментов и проверку SQL
• Ресурсы и шаблоны ресурсов
• Генерацию подсказок
• Вспомогательные функции и обработку ошибок
• Сценарии параллельной работы
• Защиту от SQL-инъекций

# Run all unit tests
uv run pytest tests/unit/ -v

# Run specific test file
uv run pytest tests/unit/test_tools.py -v

# Run with coverage
uv run pytest tests/unit/ --cov=src/hologres_mcp_server --cov-report=html

Интеграционные тесты

Интеграционные тесты требуют реального подключения к базе данных Hologres. Набор тестов включает 61 тестовый случай, организованный в 12 тестовых классов:

Тестовый класс	Тесты	Описание
TestMCPConnection	5	Подключение к MCP-серверу и базовая функциональность
TestMCPResources	14	Функциональность чтения ресурсов (схемы, таблицы, DDL, статистика, секции, журналы запросов)
TestMCPTools	10	Вызовы инструментов для операций только для чтения
TestMCPProcedureTools	3	Вызовы инструментов хранимых процедур
TestMCPMaxComputeTools	1	Создание внешней таблицы MaxCompute
TestMCPDDLTools	5	Операции DDL (CREATE, ALTER, DROP, COMMENT)
TestMCPDMLTools	3	Операции DML (INSERT, UPDATE, DELETE)
TestErrorHandling	3	Обработка ошибок и граничные случаи
TestMCPPrompts	4	Функциональность генерации подсказок
TestMCPConcurrency	3	Параллельные операции MCP
TestMCPBoundaryConditions	4	Граничные случаи (Unicode, NULL, пустые результаты)
TestMCPPerformance	3	Сценарии производительности (большие/широкие наборы результатов)

1. Создайте файл конфигурации из примера:

cp tests/integration/.test_mcp_client_env_example tests/integration/.test_mcp_client_env

2. Отредактируйте файл конфигурации, указав свои учетные данные Hologres:

HOLOGRES_HOST=your-hologres-instance.hologres.aliyuncs.com
HOLOGRES_PORT=80
HOLOGRES_USER=your_username
HOLOGRES_PASSWORD=your_password
HOLOGRES_DATABASE=your_database

3. Запустите интеграционные тесты:

# Run all integration tests
uv run pytest tests/integration/ -v -m integration

# Run specific test class
uv run pytest tests/integration/test_mcp_integration.py::TestMCPTools -v

# Run all tests (unit + integration)
uv run pytest tests/ -v

Примечание: Интеграционные тесты будут пропущены, если файл .test_mcp_client_env отсутствует или содержит неполную конфигурацию.

Качество кода

В этом проекте используется ruff для линтинга и форматирования кода.

# Install dev dependencies
uv sync --dev
uv pip install ruff

# Check code style
uv run ruff check .

# Check and auto-fix
uv run ruff check . --fix

# Format code
uv run ruff format .

# Format check only (no changes)
uv run ruff format . --check

Сборка и публикация

Сборка

В этом проекте используется hatchling в качестве бэкенда сборки. Артефакты сборки будут созданы в каталоге dist/.

# Using uv (recommended)
uv build

# Or using python build module
pip install build
python -m build

Публикация в PyPI

# Install twine
pip install twine

# Upload to PyPI
twine upload dist/*

# Or upload to Test PyPI first for verification
twine upload --repository testpypi dist/*

Процесс выпуска

# 1. Update version in pyproject.toml
# 2. Clean old build artifacts
rm -rf dist/

# 3. Build
uv build

# 4. Publish
twine upload dist/*

# 5. Tag the release
git tag -a v1.0.3 -m "Release v1.0.3"
git push origin v1.0.3

Функция обновления CLI

# Use FastMCP framework to generate CLI code and Skill
uv run fastmcp generate-cli hologres-mcp-server hologres_mcp_cli/hologres_mcp_cli.py -f