Hologres

English | 中文

Hologres MCP Server

Hologres MCP Server funciona como una interfaz universal entre los Agentes de IA y las bases de datos Hologres. Permite una comunicación fluida entre los Agentes de IA y Hologres, ayudando a los Agentes de IA a recuperar metadatos de la base de datos Hologres y ejecutar operaciones SQL.

Configuración

Modo 1: Usar archivo local

Descarga

Descargar desde Github

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

Integración MCP

Agregue la siguiente configuración al archivo de configuración del cliente 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"
            }
        }
    }
}

Modo 2: Usar modo PIP

Instalación

Instale MCP Server usando el siguiente paquete:

pip install hologres-mcp-server

Integración MCP

Agregue la siguiente configuración al archivo de configuración del cliente MCP:

Usar modo 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"
            }
        }
    }
}

Usar modo 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"
            }
        }
    }
}

Modo 3: Usar transporte HTTP transmitible

El servidor admite transporte HTTP transmitible para escenarios de implementación remota donde STDIO no está disponible.

Iniciar el servidor

Antes de iniciar el servidor, configure las variables de entorno de conexión de 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"

Luego inicie el servidor:

# 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

El endpoint MCP estará disponible en http://<host>:<port>/mcp.

Opciones CLI

Opción	Valor predeterminado	Descripción
--transport	stdio	Tipo de transporte: stdio, streamable-http, o sse
--host	127.0.0.1	Host al que enlazar (solo transportes HTTP)
--port	8000	Puerto en el que escuchar (solo transportes HTTP)

Integración MCP

Agregue la siguiente configuración al archivo de configuración del cliente MCP:

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

Uso con 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

Componentes

Herramientas

• execute_hg_select_sql: Ejecutar una consulta SQL SELECT en la base de datos Hologres
• execute_hg_select_sql_with_serverless: Ejecutar una consulta SQL SELECT en la base de datos Hologres con computación sin servidor
• execute_hg_dml_sql: Ejecutar una consulta SQL DML (INSERT, UPDATE, DELETE) en la base de datos Hologres
• execute_hg_ddl_sql: Ejecutar una consulta SQL DDL (CREATE, ALTER, DROP, COMMENT ON) en la base de datos Hologres
• gather_hg_table_statistics: Recopilar estadísticas de tabla en la base de datos Hologres
  • Parámetros: schema_name (string), table (string)
• get_hg_query_plan: Obtener plan de consulta en la base de datos Hologres
• get_hg_execution_plan: Obtener plan de ejecución en la base de datos Hologres
• call_hg_procedure: Invocar un procedimiento en la base de datos Hologres
• create_hg_maxcompute_foreign_table: Crear tablas externas de MaxCompute en la base de datos Hologres.

Dado que algunos Agentes no admiten recursos ni plantillas de recursos, se proporcionan las siguientes herramientas para obtener los metadatos de esquemas, tablas, vistas y tablas externas.

• list_hg_schemas: Lista todos los esquemas en la base de datos Hologres actual, excluyendo los esquemas del sistema.
• list_hg_tables_in_a_schema: Lista todas las tablas en un esquema específico, incluyendo sus tipos (tabla, vista, tabla externa, tabla particionada).
  • Parámetros: schema_name (string)
• show_hg_table_ddl: Mostrar el script DDL de una tabla, vista o tabla externa en la base de datos Hologres.
  • Parámetros: schema_name (string), table (string)
• query_and_plotly_chart: Ejecutar una consulta SQL SELECT y generar un gráfico (barras, línea, dispersión, circular, histograma, área). Devuelve los resultados de la consulta y una imagen PNG codificada en base64.
  • Parámetros: query (string), chart_type (string, predeterminado "bar"), x_column (string), y_column (string), title (string)
• analyze_hg_query_by_id: Analizar el perfil de rendimiento de una consulta específica por su query_id desde hg_query_log. Devuelve métricas detalladas incluyendo duración, memoria, tiempo de CPU, estadísticas de lectura/escritura.
  • Parámetros: query_id (string)
• get_hg_slow_queries: Obtener consultas lentas de hg_query_log ordenadas por duración.
  • Parámetros: min_duration_ms (int, predeterminado 1000), limit (int, predeterminado 20)
• list_hg_dynamic_tables: Listar todas las Tablas Dinámicas con su estado, configuración de frescura e información de la última actualización.
  • Parámetros: schema_name (string, opcional)
• get_hg_dynamic_table_refresh_history: Obtener el historial de actualizaciones de una Tabla Dinámica específica, incluyendo duración, estado y latencia.
  • Parámetros: schema_name (string), table_name (string), limit (int, predeterminado 10)
• list_hg_recyclebin: Listar todas las tablas en la papelera de reciclaje de Hologres (tablas eliminadas que se pueden restaurar).
• restore_hg_table_from_recyclebin: Restaurar una tabla eliminada de la papelera de reciclaje de Hologres.
  • Parámetros: table_name (string), schema_name (string, predeterminado "public")
• list_hg_warehouses: Listar todos los grupos de computación (almacenes) con su CPU, memoria, conteo de clústeres y estado.
• switch_hg_warehouse: Cambiar el recurso de computación de la sesión actual a un almacén especificado.
  • Parámetros: warehouse_name (string)
• get_hg_table_storage_size: Obtener detalles del tamaño de almacenamiento de una tabla, incluyendo desglose total, de datos, índice y metadatos.
  • Parámetros: schema_name (string), table (string)
• cancel_hg_query: Cancelar o terminar una consulta en ejecución por su ID de proceso.
  • Parámetros: pid (int), terminate (bool, predeterminado false)
• list_hg_active_queries: Listar consultas y conexiones actualmente activas desde pg_stat_activity.
  • Parámetros: state (string: "active", "idle", o "all", predeterminado "active")
• list_hg_query_queues: Listar todas las Colas de Consultas y sus clasificadores (límites de concurrencia, reglas de enrutamiento). Requiere V3.0+.
• get_hg_table_properties: Obtener propiedades de la tabla incluyendo distribution_key, clustering_key, segment_key, bitmap_columns, configuración de binlog, etc.
  • Parámetros: schema_name (string), table (string)
• get_hg_table_shard_info: Obtener información del Grupo de Tablas y conteo de fragmentos de una tabla para diagnosticar sesgo de datos.
  • Parámetros: schema_name (string), table (string)
• list_hg_external_databases: Listar todas las Bases de Datos Externas y Servidores Externos para aceleración Lakehouse. Requiere V3.0+.
• get_hg_lock_diagnostics: Diagnosticar contención de bloqueos mostrando consultas bloqueantes y en espera.
• get_hg_table_info_trend: Obtener tendencia de almacenamiento de tabla desde hg_table_info, mostrando tamaño de almacenamiento diario, conteo de archivos y cambios en el conteo de filas.
  • Parámetros: schema_name (string), table (string), days (int, predeterminado 7)
• manage_hg_query_queue: Crear, eliminar o limpiar una Cola de Consultas. Requiere V3.0+ y privilegios de superusuario.
  • Parámetros: action (string: "create", "drop", "clear"), queue_name (string), max_concurrency (int, para create), max_queue_size (int, para create)
• manage_hg_classifier: Crear o eliminar un clasificador para una Cola de Consultas. Requiere V3.0+.
  • Parámetros: action (string: "create", "drop"), queue_name (string), classifier_name (string), priority (int, para create)
• set_hg_query_queue_property: Establecer o eliminar propiedades en una Cola de Consultas o clasificador. Requiere V3.0+.
  • Parámetros: target (string: "queue", "classifier"), queue_name (string), property_key (string), property_value (string), classifier_name (string, para classifier), action (string: "set", "remove")
• manage_hg_warehouse: Administrar un grupo de computación: suspender, reanudar, reiniciar, renombrar o redimensionar. Requiere superusuario.
  • Parámetros: action (string: "suspend", "resume", "restart", "rename", "resize"), warehouse_name (string), cu (int, para resize), new_name (string, para rename)
• get_hg_warehouse_status: Obtener estado de ejecución detallado y progreso de escalado de un grupo de computación.
  • Parámetros: warehouse_name (string)
• rebalance_hg_warehouse: Activar el reequilibrio de fragmentos para un grupo de computación para eliminar el sesgo de datos.
  • Parámetros: warehouse_name (string)
• list_hg_data_masking_rules: Listar todas las reglas de enmascaramiento de datos configuradas mediante la extensión hg_anon (a nivel de columna y de usuario).
• query_hg_external_files: Consultar archivos directamente desde OSS usando la función EXTERNAL_FILES sin crear tablas externas. Requiere V4.1+.
  • Parámetros: path (string), format (string: "csv", "parquet", "orc"), columns (string, opcional), oss_endpoint (string, opcional), role_arn (string, opcional)
• get_hg_guc_config: Obtener el valor actual de un parámetro GUC (Grand Unified Configuration).
  • Parámetros: guc_name (string)

Recursos

Recursos Integrados

• hologres:///schemas: Obtener todos los esquemas en la base de datos Hologres

Plantillas de Recursos

• hologres:///{schema}/tables: Listar todas las tablas en un esquema en la base de datos Hologres

• hologres:///{schema}/{table}/partitions: Listar todas las particiones de una tabla particionada en la base de datos Hologres

• hologres:///{schema}/{table}/ddl: Obtener DDL de tabla en la base de datos Hologres

• hologres:///{schema}/{table}/statistic: Mostrar estadísticas de tabla recopiladas en la base de datos Hologres

• system:///{+system_path}: Las rutas del sistema incluyen:

  • hg_instance_version - Muestra la versión de la instancia de Hologres.
  • guc_value/<guc_name> - Muestra el valor GUC (Grand Unified Configuration).
  • missing_stats_tables - Muestra las tablas que carecen de estadísticas.
  • stat_activity - Muestra la información de las consultas actualmente en ejecución.
  • query_log/latest/<row_limits> - Obtener historial de registro de consultas reciente con un número especificado de filas.
  • query_log/user/<user_name>/<row_limits> - Obtener historial de registro de consultas para un usuario específico con límites de filas.
  • query_log/application/<application_name>/<row_limits> - Obtener historial de registro de consultas para una aplicación específica con límites de filas.
  • query_log/failed/<interval>/<row_limits> - Obtener historial de registro de consultas fallidas con intervalo y número especificado de filas.

Prompts

• analyze_table_performance: Generar un prompt para analizar el rendimiento de una tabla en Hologres
• optimize_query: Generar un prompt para optimizar una consulta SQL en Hologres
• explore_schema: Generar un prompt para explorar un esquema en la base de datos Hologres

Pruebas

El proyecto incluye pruebas unitarias e integrales exhaustivas.

Pruebas Unitarias

Las pruebas unitarias no requieren una conexión a la base de datos y utilizan dependencias simuladas. El conjunto de pruebas incluye 326 casos de prueba que cubren:

• Funcionalidad de herramientas y validación SQL
• Recursos y plantillas de recursos
• Generación de prompts
• Funciones de utilidad y manejo de errores
• Escenarios de concurrencia
• Protección contra inyección 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

Pruebas de Integración

Las pruebas de integración requieren una conexión real a la base de datos Hologres. El conjunto de pruebas incluye 61 casos de prueba organizados en 12 clases de prueba:

Clase de Prueba	Pruebas	Descripción
TestMCPConnection	5	Conexión al servidor MCP y funcionalidad básica
TestMCPResources	14	Funcionalidad de lectura de recursos (esquemas, tablas, DDL, estadísticas, particiones, registros de consultas)
TestMCPTools	10	Llamadas a herramientas para operaciones de solo lectura
TestMCPProcedureTools	3	Llamadas a herramientas de procedimientos almacenados
TestMCPMaxComputeTools	1	Creación de tablas externas de MaxCompute
TestMCPDDLTools	5	Operaciones DDL (CREATE, ALTER, DROP, COMMENT)
TestMCPDMLTools	3	Operaciones DML (INSERT, UPDATE, DELETE)
TestErrorHandling	3	Manejo de errores y casos límite
TestMCPPrompts	4	Funcionalidad de generación de prompts
TestMCPConcurrency	3	Operaciones MCP concurrentes
TestMCPBoundaryConditions	4	Casos límite (Unicode, NULL, resultados vacíos)
TestMCPPerformance	3	Escenarios de rendimiento (conjuntos de resultados grandes/amplios)

1. Cree un archivo de configuración a partir del ejemplo:

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

2. Edite el archivo de configuración con sus credenciales de 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. Ejecute las pruebas de integración:

# 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

Nota: Las pruebas de integración se omitirán si falta el archivo .test_mcp_client_env o contiene una configuración incompleta.

Calidad del Código

Este proyecto utiliza ruff para el linting y formateo de código.

# 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

Construcción y Publicación

Construcción

Este proyecto utiliza hatchling como backend de construcción. Los artefactos de construcción se generarán en el directorio dist/.

# Using uv (recommended)
uv build

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

Publicar en 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/*

Flujo de Trabajo de Lanzamiento

# 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

Funcionalidad CLI de Actualización

# 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