Hologres

Français | 中文

Serveur MCP Hologres

Le serveur MCP Hologres sert d'interface universelle entre les agents IA et les bases de données Hologres. Il permet une communication transparente entre les agents IA et Hologres, aidant les agents IA à récupérer les métadonnées de la base de données Hologres et à exécuter des opérations SQL.

Configuration

Mode 1 : Utilisation d'un fichier local

Téléchargement

Télécharger depuis Github

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

Intégration MCP

Ajoutez la configuration suivante au fichier de configuration du client 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"
            }
        }
    }
}

Mode 2 : Utilisation du mode PIP

Installation

Installez le serveur MCP en utilisant le paquet suivant :

pip install hologres-mcp-server

Intégration MCP

Ajoutez la configuration suivante au fichier de configuration du client MCP :

Utiliser le mode 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"
            }
        }
    }
}

Utiliser le mode 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"
            }
        }
    }
}

Mode 3 : Utilisation du transport HTTP Streamable

Le serveur prend en charge le transport HTTP Streamable pour les scénarios de déploiement à distance où STDIO n'est pas disponible.

Démarrer le serveur

Avant de démarrer le serveur, définissez les variables d'environnement de connexion 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"

Puis démarrez le serveur :

# 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

Le point de terminaison MCP sera disponible à l'adresse http://<host>:<port>/mcp.

Options CLI

Option	Valeur par défaut	Description
--transport	stdio	Type de transport : stdio, streamable-http ou sse
--host	127.0.0.1	Hôte auquel se lier (transports HTTP uniquement)
--port	8000	Port d'écoute (transports HTTP uniquement)

Intégration MCP

Ajoutez la configuration suivante au fichier de configuration du client MCP :

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

Utilisation avec 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

Composants

Outils

• execute_hg_select_sql : Exécuter une requête SQL SELECT dans la base de données Hologres
• execute_hg_select_sql_with_serverless : Exécuter une requête SQL SELECT dans la base de données Hologres avec calcul serverless
• execute_hg_dml_sql : Exécuter une requête SQL DML (INSERT, UPDATE, DELETE) dans la base de données Hologres
• execute_hg_ddl_sql : Exécuter une requête SQL DDL (CREATE, ALTER, DROP, COMMENT ON) dans la base de données Hologres
• gather_hg_table_statistics : Collecter les statistiques de table dans la base de données Hologres
  • Paramètres : schema_name (chaîne), table (chaîne)
• get_hg_query_plan : Obtenir le plan de requête dans la base de données Hologres
• get_hg_execution_plan : Obtenir le plan d'exécution dans la base de données Hologres
• call_hg_procedure : Invoquer une procédure dans la base de données Hologres
• create_hg_maxcompute_foreign_table : Créer des tables externes MaxCompute dans la base de données Hologres.

Étant donné que certains agents ne prennent pas en charge les ressources et les modèles de ressources, les outils suivants sont fournis pour obtenir les métadonnées des schémas, tables, vues et tables externes.

• list_hg_schemas : Liste tous les schémas de la base de données Hologres actuelle, à l'exclusion des schémas système.
• list_hg_tables_in_a_schema : Liste toutes les tables d'un schéma spécifique, y compris leurs types (table, vue, table externe, table partitionnée).
  • Paramètres : schema_name (chaîne)
• show_hg_table_ddl : Affiche le script DDL d'une table, vue ou table externe dans la base de données Hologres.
  • Paramètres : schema_name (chaîne), table (chaîne)
• query_and_plotly_chart : Exécute une requête SQL SELECT et génère un graphique (barres, lignes, dispersion, secteurs, histogramme, aires). Renvoie les résultats de la requête et une image PNG encodée en base64.
  • Paramètres : query (chaîne), chart_type (chaîne, défaut "bar"), x_column (chaîne), y_column (chaîne), title (chaîne)
• analyze_hg_query_by_id : Analyse le profil de performance d'une requête spécifique par son query_id depuis hg_query_log. Renvoie des métriques détaillées incluant la durée, la mémoire, le temps CPU, les statistiques de lecture/écriture.
  • Paramètres : query_id (chaîne)
• get_hg_slow_queries : Obtient les requêtes lentes depuis hg_query_log, triées par durée.
  • Paramètres : min_duration_ms (entier, défaut 1000), limit (entier, défaut 20)
• list_hg_dynamic_tables : Liste toutes les tables dynamiques avec leur statut, paramètres de fraîcheur et informations de dernière actualisation.
  • Paramètres : schema_name (chaîne, optionnel)
• get_hg_dynamic_table_refresh_history : Obtient l'historique d'actualisation d'une table dynamique spécifique, incluant la durée, le statut et la latence.
  • Paramètres : schema_name (chaîne), table_name (chaîne), limit (entier, défaut 10)
• list_hg_recyclebin : Liste toutes les tables dans la corbeille Hologres (tables supprimées pouvant être restaurées).
• restore_hg_table_from_recyclebin : Restaure une table supprimée depuis la corbeille Hologres.
  • Paramètres : table_name (chaîne), schema_name (chaîne, défaut "public")
• list_hg_warehouses : Liste tous les groupes de calcul (entrepôts) avec leur CPU, mémoire, nombre de clusters et statut.
• switch_hg_warehouse : Bascule la ressource de calcul de la session actuelle vers un entrepôt spécifié.
  • Paramètres : warehouse_name (chaîne)
• get_hg_table_storage_size : Obtient les détails de la taille de stockage d'une table, y compris la répartition totale, données, index et métadonnées.
  • Paramètres : schema_name (chaîne), table (chaîne)
• cancel_hg_query : Annule ou termine une requête en cours par son ID de processus.
  • Paramètres : pid (entier), terminate (booléen, défaut false)
• list_hg_active_queries : Liste les requêtes et connexions actuellement actives depuis pg_stat_activity.
  • Paramètres : state (chaîne : "active", "idle" ou "all", défaut "active")
• list_hg_query_queues : Liste toutes les files d'attente de requêtes et leurs classificateurs (limites de concurrence, règles de routage). Nécessite V3.0+.
• get_hg_table_properties : Obtient les propriétés de la table, y compris distribution_key, clustering_key, segment_key, bitmap_columns, paramètres binlog, etc.
  • Paramètres : schema_name (chaîne), table (chaîne)
• get_hg_table_shard_info : Obtient les informations du groupe de tables et du nombre de shards pour diagnostiquer le déséquilibre des données.
  • Paramètres : schema_name (chaîne), table (chaîne)
• list_hg_external_databases : Liste toutes les bases de données externes et serveurs étrangers pour l'accélération Lakehouse. Nécessite V3.0+.
• get_hg_lock_diagnostics : Diagnostique les conflits de verrouillage en montrant les requêtes bloquantes et en attente.
• get_hg_table_info_trend : Obtient la tendance de stockage de la table depuis hg_table_info, montrant la taille de stockage quotidienne, le nombre de fichiers et les changements de nombre de lignes.
  • Paramètres : schema_name (chaîne), table (chaîne), days (entier, défaut 7)
• manage_hg_query_queue : Crée, supprime ou vide une file d'attente de requêtes. Nécessite V3.0+ et les privilèges superutilisateur.
  • Paramètres : action (chaîne : "create", "drop", "clear"), queue_name (chaîne), max_concurrency (entier, pour create), max_queue_size (entier, pour create)
• manage_hg_classifier : Crée ou supprime un classificateur pour une file d'attente de requêtes. Nécessite V3.0+.
  • Paramètres : action (chaîne : "create", "drop"), queue_name (chaîne), classifier_name (chaîne), priority (entier, pour create)
• set_hg_query_queue_property : Définit ou supprime des propriétés sur une file d'attente de requêtes ou un classificateur. Nécessite V3.0+.
  • Paramètres : target (chaîne : "queue", "classifier"), queue_name (chaîne), property_key (chaîne), property_value (chaîne), classifier_name (chaîne, pour classifier), action (chaîne : "set", "remove")
• manage_hg_warehouse : Gère un groupe de calcul : suspendre, reprendre, redémarrer, renommer ou redimensionner. Nécessite les privilèges superutilisateur.
  • Paramètres : action (chaîne : "suspend", "resume", "restart", "rename", "resize"), warehouse_name (chaîne), cu (entier, pour resize), new_name (chaîne, pour rename)
• get_hg_warehouse_status : Obtient le statut d'exécution détaillé et la progression de la mise à l'échelle d'un groupe de calcul.
  • Paramètres : warehouse_name (chaîne)
• rebalance_hg_warehouse : Déclenche le rééquilibrage des shards pour un groupe de calcul afin d'éliminer le déséquilibre des données.
  • Paramètres : warehouse_name (chaîne)
• list_hg_data_masking_rules : Liste toutes les règles de masquage de données configurées via l'extension hg_anon (niveau colonne et niveau utilisateur).
• query_hg_external_files : Interroge les fichiers directement depuis OSS en utilisant la fonction EXTERNAL_FILES sans créer de tables externes. Nécessite V4.1+.
  • Paramètres : path (chaîne), format (chaîne : "csv", "parquet", "orc"), columns (chaîne, optionnel), oss_endpoint (chaîne, optionnel), role_arn (chaîne, optionnel)
• get_hg_guc_config : Obtient la valeur actuelle d'un paramètre GUC (Grand Unified Configuration).
  • Paramètres : guc_name (chaîne)

Ressources

Ressources intégrées

• hologres:///schemas : Obtient tous les schémas de la base de données Hologres

Modèles de ressources

• hologres:///{schema}/tables : Liste toutes les tables d'un schéma dans la base de données Hologres

• hologres:///{schema}/{table}/partitions : Liste toutes les partitions d'une table partitionnée dans la base de données Hologres

• hologres:///{schema}/{table}/ddl : Obtient le DDL d'une table dans la base de données Hologres

• hologres:///{schema}/{table}/statistic : Affiche les statistiques de table collectées dans la base de données Hologres

• system:///{+system_path} : Les chemins système incluent :

  • hg_instance_version - Affiche la version de l'instance Hologres.
  • guc_value/<guc_name> - Affiche la valeur GUC (Grand Unified Configuration).
  • missing_stats_tables - Affiche les tables pour lesquelles il manque des statistiques.
  • stat_activity - Affiche les informations des requêtes en cours d'exécution.
  • query_log/latest/<row_limits> - Obtient l'historique récent du journal des requêtes avec un nombre de lignes spécifié.
  • query_log/user/<user_name>/<row_limits> - Obtient l'historique du journal des requêtes pour un utilisateur spécifique avec des limites de lignes.
  • query_log/application/<application_name>/<row_limits> - Obtient l'historique du journal des requêtes pour une application spécifique avec des limites de lignes.
  • query_log/failed/<interval>/<row_limits> - Obtient l'historique du journal des requêtes échouées avec un intervalle et un nombre de lignes spécifié.

Invites

• analyze_table_performance : Génère une invite pour analyser les performances d'une table dans Hologres
• optimize_query : Génère une invite pour optimiser une requête SQL dans Hologres
• explore_schema : Génère une invite pour explorer un schéma dans la base de données Hologres

Tests

Le projet comprend des tests unitaires et des tests d'intégration complets.

Tests unitaires

Les tests unitaires ne nécessitent pas de connexion à la base de données et utilisent des dépendances simulées. La suite de tests comprend 326 cas de test couvrant :

• La fonctionnalité des outils et la validation SQL
• Les ressources et les modèles de ressources
• La génération d'invites
• Les fonctions utilitaires et la gestion des erreurs
• Les scénarios de concurrence
• La protection contre les injections 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

Tests d'intégration

Les tests d'intégration nécessitent une connexion réelle à la base de données Hologres. La suite de tests comprend 61 cas de test organisés en 12 classes de test :

Classe de test	Tests	Description
TestMCPConnection	5	Connexion au serveur MCP et fonctionnalité de base
TestMCPResources	14	Fonctionnalité de lecture des ressources (schémas, tables, DDL, statistiques, partitions, journaux de requêtes)
TestMCPTools	10	Appels d'outils pour les opérations en lecture seule
TestMCPProcedureTools	3	Appels d'outils de procédure stockée
TestMCPMaxComputeTools	1	Création de table externe MaxCompute
TestMCPDDLTools	5	Opérations DDL (CREATE, ALTER, DROP, COMMENT)
TestMCPDMLTools	3	Opérations DML (INSERT, UPDATE, DELETE)
TestErrorHandling	3	Gestion des erreurs et cas limites
TestMCPPrompts	4	Fonctionnalité de génération d'invites
TestMCPConcurrency	3	Opérations MCP concurrentes
TestMCPBoundaryConditions	4	Cas limites (Unicode, NULL, résultats vides)
TestMCPPerformance	3	Scénarios de performance (ensembles de résultats volumineux/larges)

1. Créez un fichier de configuration à partir de l'exemple :

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

2. Modifiez le fichier de configuration avec vos identifiants 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. Exécutez les tests d'intégration :

# 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

Remarque : Les tests d'intégration seront ignorés si le fichier .test_mcp_client_env est manquant ou contient une configuration incomplète.

Qualité du code

Ce projet utilise ruff pour le linting et le formatage du code.

# 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

Construction et publication

Construction

Ce projet utilise hatchling comme backend de construction. Les artefacts de construction seront générés dans le répertoire dist/.

# Using uv (recommended)
uv build

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

Publier sur 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/*

Workflow de publication

# 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

Fonctionnalité CLI de mise à jour

# 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