Hologres

Português | 中文

Servidor MCP Hologres

O Servidor MCP Hologres atua como uma interface universal entre Agentes de IA e bancos de dados Hologres. Ele permite comunicação contínua entre Agentes de IA e Hologres, ajudando os Agentes de IA a recuperar metadados do banco de dados Hologres e executar operações SQL.

Configuração

Modo 1: Usando Arquivo Local

Download

Baixe do Github

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

Integração MCP

Adicione a seguinte configuração ao arquivo de configuração do 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: Usando Modo PIP

Instalação

Instale o Servidor MCP usando o seguinte pacote:

pip install hologres-mcp-server

Integração MCP

Adicione a seguinte configuração ao arquivo de configuração do cliente MCP:

Use o 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"
            }
        }
    }
}

Use o 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: Usando Transporte HTTP Transmissível

O servidor suporta transporte HTTP transmissível para cenários de implantação remota onde STDIO não está disponível.

Inicie o servidor

Antes de iniciar o servidor, defina as variáveis de ambiente de conexão do 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"

Em seguida, inicie o 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

O endpoint MCP estará disponível em http://<host>:<port>/mcp.

Opções de CLI

Opção	Padrão	Descrição
--transport	stdio	Tipo de transporte: stdio, streamable-http ou sse
--host	127.0.0.1	Host para vincular (apenas transportes HTTP)
--port	8000	Porta para escutar (apenas transportes HTTP)

Integração MCP

Adicione a seguinte configuração ao arquivo de configuração do cliente MCP:

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

Usando com 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

Ferramentas

• execute_hg_select_sql: Executa uma consulta SQL SELECT no banco de dados Hologres
• execute_hg_select_sql_with_serverless: Executa uma consulta SQL SELECT no banco de dados Hologres com computação serverless
• execute_hg_dml_sql: Executa uma consulta SQL DML (INSERT, UPDATE, DELETE) no banco de dados Hologres
• execute_hg_ddl_sql: Executa uma consulta SQL DDL (CREATE, ALTER, DROP, COMMENT ON) no banco de dados Hologres
• gather_hg_table_statistics: Coleta estatísticas de tabela no banco de dados Hologres
  • Parâmetros: schema_name (string), table (string)
• get_hg_query_plan: Obtém o plano de consulta no banco de dados Hologres
• get_hg_execution_plan: Obtém o plano de execução no banco de dados Hologres
• call_hg_procedure: Invoca um procedimento no banco de dados Hologres
• create_hg_maxcompute_foreign_table: Cria tabelas externas do MaxCompute no banco de dados Hologres.

Como alguns Agentes não suportam recursos e modelos de recursos, as seguintes ferramentas são fornecidas para obter os metadados de esquemas, tabelas, visões e tabelas externas.

• list_hg_schemas: Lista todos os esquemas no banco de dados Hologres atual, excluindo esquemas de sistema.
• list_hg_tables_in_a_schema: Lista todas as tabelas em um esquema específico, incluindo seus tipos (tabela, visão, tabela externa, tabela particionada).
  • Parâmetros: schema_name (string)
• show_hg_table_ddl: Mostra o script DDL de uma tabela, visão ou tabela externa no banco de dados Hologres.
  • Parâmetros: schema_name (string), table (string)
• query_and_plotly_chart: Executa uma consulta SQL SELECT e gera um gráfico (barra, linha, dispersão, pizza, histograma, área). Retorna os resultados da consulta e uma imagem PNG codificada em base64.
  • Parâmetros: query (string), chart_type (string, padrão "bar"), x_column (string), y_column (string), title (string)
• analyze_hg_query_by_id: Analisa o perfil de desempenho de uma consulta específica pelo seu query_id do hg_query_log. Retorna métricas detalhadas incluindo duração, memória, tempo de CPU, estatísticas de leitura/gravação.
  • Parâmetros: query_id (string)
• get_hg_slow_queries: Obtém consultas lentas do hg_query_log ordenadas por duração.
  • Parâmetros: min_duration_ms (int, padrão 1000), limit (int, padrão 20)
• list_hg_dynamic_tables: Lista todas as Tabelas Dinâmicas com seu status, configurações de atualização e informações da última atualização.
  • Parâmetros: schema_name (string, opcional)
• get_hg_dynamic_table_refresh_history: Obtém o histórico de atualização de uma Tabela Dinâmica específica, incluindo duração, status e latência.
  • Parâmetros: schema_name (string), table_name (string), limit (int, padrão 10)
• list_hg_recyclebin: Lista todas as tabelas na lixeira do Hologres (tabelas excluídas que podem ser restauradas).
• restore_hg_table_from_recyclebin: Restaura uma tabela excluída da lixeira do Hologres.
  • Parâmetros: table_name (string), schema_name (string, padrão "public")
• list_hg_warehouses: Lista todos os grupos de computação (warehouses) com sua CPU, memória, contagem de clusters e status.
• switch_hg_warehouse: Alterna o recurso de computação da sessão atual para um warehouse especificado.
  • Parâmetros: warehouse_name (string)
• get_hg_table_storage_size: Obtém detalhes do tamanho de armazenamento de uma tabela, incluindo detalhamento total, de dados, índice e metadados.
  • Parâmetros: schema_name (string), table (string)
• cancel_hg_query: Cancela ou termina uma consulta em execução pelo seu ID de processo.
  • Parâmetros: pid (int), terminate (bool, padrão false)
• list_hg_active_queries: Lista consultas e conexões ativas atualmente do pg_stat_activity.
  • Parâmetros: state (string: "active", "idle" ou "all", padrão "active")
• list_hg_query_queues: Lista todas as Filas de Consulta e seus classificadores (limites de concorrência, regras de roteamento). Requer V3.0+.
• get_hg_table_properties: Obtém propriedades da tabela incluindo distribution_key, clustering_key, segment_key, bitmap_columns, configurações de binlog, etc.
  • Parâmetros: schema_name (string), table (string)
• get_hg_table_shard_info: Obtém informações do Grupo de Tabelas e contagem de shards da tabela para diagnosticar distorção de dados.
  • Parâmetros: schema_name (string), table (string)
• list_hg_external_databases: Lista todos os Bancos de Dados Externos e Servidores Estrangeiros para aceleração Lakehouse. Requer V3.0+.
• get_hg_lock_diagnostics: Diagnostica contenção de bloqueios mostrando consultas bloqueantes e em espera.
• get_hg_table_info_trend: Obtém a tendência de armazenamento da tabela do hg_table_info, mostrando tamanho de armazenamento diário, contagem de arquivos e alterações na contagem de linhas.
  • Parâmetros: schema_name (string), table (string), days (int, padrão 7)
• manage_hg_query_queue: Cria, remove ou limpa uma Fila de Consulta. Requer V3.0+ e privilégios de superusuário.
  • Parâmetros: action (string: "create", "drop", "clear"), queue_name (string), max_concurrency (int, para create), max_queue_size (int, para create)
• manage_hg_classifier: Cria ou remove um classificador para uma Fila de Consulta. Requer V3.0+.
  • Parâmetros: action (string: "create", "drop"), queue_name (string), classifier_name (string), priority (int, para create)
• set_hg_query_queue_property: Define ou remove propriedades em uma Fila de Consulta ou classificador. Requer 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: Gerencia um grupo de computação: suspender, retomar, reiniciar, renomear ou redimensionar. Requer superusuário.
  • 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: Obtém o status de execução detalhado e o progresso de escalonamento de um grupo de computação.
  • Parâmetros: warehouse_name (string)
• rebalance_hg_warehouse: Aciona o rebalanceamento de shards para um grupo de computação para eliminar a distorção de dados.
  • Parâmetros: warehouse_name (string)
• list_hg_data_masking_rules: Lista todas as regras de mascaramento de dados configuradas via extensão hg_anon (nível de coluna e nível de usuário).
• query_hg_external_files: Consulta arquivos diretamente do OSS usando a função EXTERNAL_FILES sem criar tabelas externas. Requer 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: Obtém o valor atual de um parâmetro GUC (Grand Unified Configuration).
  • Parâmetros: guc_name (string)

Recursos

Recursos Integrados

• hologres:///schemas: Obtém todos os esquemas no banco de dados Hologres

Modelos de Recursos

• hologres:///{schema}/tables: Lista todas as tabelas em um esquema no banco de dados Hologres

• hologres:///{schema}/{table}/partitions: Lista todas as partições de uma tabela particionada no banco de dados Hologres

• hologres:///{schema}/{table}/ddl: Obtém o DDL da tabela no banco de dados Hologres

• hologres:///{schema}/{table}/statistic: Mostra estatísticas coletadas da tabela no banco de dados Hologres

• system:///{+system_path}: Os caminhos do sistema incluem:

  • hg_instance_version - Mostra a versão da instância do Hologres.
  • guc_value/<guc_name> - Mostra o valor do guc (Grand Unified Configuration).
  • missing_stats_tables - Mostra as tabelas que estão sem estatísticas.
  • stat_activity - Mostra as informações das consultas em execução no momento.
  • query_log/latest/<row_limits> - Obtém o histórico recente de log de consultas com um número especificado de linhas.
  • query_log/user/<user_name>/<row_limits> - Obtém o histórico de log de consultas para um usuário específico com limites de linhas.
  • query_log/application/<application_name>/<row_limits> - Obtém o histórico de log de consultas para uma aplicação específica com limites de linhas.
  • query_log/failed/<interval>/<row_limits> - Obtém o histórico de log de consultas com falha com intervalo e número especificado de linhas.

Prompts

• analyze_table_performance: Gera um prompt para analisar o desempenho da tabela no Hologres
• optimize_query: Gera um prompt para otimizar uma consulta SQL no Hologres
• explore_schema: Gera um prompt para explorar um esquema no banco de dados Hologres

Testes

O projeto inclui testes unitários abrangentes e testes de integração.

Testes Unitários

Os testes unitários não requerem uma conexão com o banco de dados e usam dependências simuladas. A suíte de testes inclui 326 casos de teste cobrindo:

• Funcionalidade das ferramentas e validação SQL
• Recursos e modelos de recursos
• Geração de prompts
• Funções utilitárias e tratamento de erros
• Cenários de concorrência
• Proteção contra injeção 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

Testes de Integração

Os testes de integração requerem uma conexão real com o banco de dados Hologres. A suíte de testes inclui 61 casos de teste organizados em 12 classes de teste:

Classe de Teste	Testes	Descrição
TestMCPConnection	5	Conexão do servidor MCP e funcionalidade básica
TestMCPResources	14	Funcionalidade de leitura de recursos (esquemas, tabelas, DDL, estatísticas, partições, logs de consulta)
TestMCPTools	10	Chamadas de ferramentas para operações somente leitura
TestMCPProcedureTools	3	Chamadas de ferramentas de procedimentos armazenados
TestMCPMaxComputeTools	1	Criação de tabela externa do MaxCompute
TestMCPDDLTools	5	Operações DDL (CREATE, ALTER, DROP, COMMENT)
TestMCPDMLTools	3	Operações DML (INSERT, UPDATE, DELETE)
TestErrorHandling	3	Tratamento de erros e casos limite
TestMCPPrompts	4	Funcionalidade de geração de prompts
TestMCPConcurrency	3	Operações MCP concorrentes
TestMCPBoundaryConditions	4	Casos limite (Unicode, NULL, resultados vazios)
TestMCPPerformance	3	Cenários de desempenho (conjuntos de resultados grandes/amplos)

1. Crie um arquivo de configuração a partir do exemplo:

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

2. Edite o arquivo de configuração com suas credenciais do 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. Execute os testes de integração:

# 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: Os testes de integração serão ignorados se o arquivo .test_mcp_client_env estiver ausente ou contiver configuração incompleta.

Qualidade do Código

Este projeto usa ruff para linting e formatação 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

Build e Publicação

Build

Este projeto usa hatchling como backend de build. Os artefatos de build serão gerados no diretório dist/.

# Using uv (recommended)
uv build

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

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

Fluxo de Trabalho de Release

# 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

Atualizar Funcionalidade 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