Hologres MCP Server

English | 中文

Hologres MCP サーバー

Hologres MCP サーバーは、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 サーバーをインストールします：

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：Streamable HTTP トランスポートを使用する

サーバーは、STDIO を利用できないリモートデプロイのシナリオ向けに、Streamable HTTP トランスポートをサポートしています。

サーバーを起動する

サーバーを起動する前に、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：Hologres データベースで SELECT SQL クエリを実行します
• execute_hg_select_sql_with_serverless：サーバーレスコンピューティングを使用して、Hologres データベースで SELECT SQL クエリを実行します
• execute_hg_dml_sql：Hologres データベースで DML（INSERT、UPDATE、DELETE）SQL クエリを実行します
• execute_hg_ddl_sql：Hologres データベースで DDL（CREATE、ALTER、DROP、COMMENT ON）SQL クエリを実行します
• 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：Hologres データベースに MaxCompute 外部テーブルを作成します。 一部のエージェントはリソースとリソーステンプレートに対応していないため、スキーマ、テーブル、ビュー、外部テーブルのメタデータを取得するための以下のツールを提供しています。
• list_hg_schemas：システムスキーマを除き、現在の Hologres データベース内のすべてのスキーマを一覧表示します。
• list_hg_tables_in_a_schema：特定のスキーマ内のすべてのテーブルと、その種類（テーブル、ビュー、外部テーブル、パーティションテーブル）を一覧表示します。
  • パラメーター：schema_name (string)
• show_hg_table_ddl：Hologres データベース内のテーブル、ビュー、または外部テーブルの DDL スクリプトを表示します。
  • パラメーター：schema_name (string), table (string)
• query_and_plotly_chart：SELECT SQL クエリを実行し、チャート（棒、折れ線、散布図、円、ヒストグラム、面）を生成します。クエリ結果と Base64 エンコードされた PNG 画像を返します。
  • パラメーター：query (string), chart_type (string, default "bar"), x_column (string), y_column (string), title (string)
• analyze_hg_query_by_id：hg_query_log の query_id を指定して、特定のクエリのパフォーマンスプロファイルを分析します。実行時間、メモリ、CPU 時間、読み書きの統計など、詳細なメトリクスを返します。
  • パラメーター：query_id (string)
• get_hg_slow_queries：hg_query_log から、実行時間の長い順にクエリを取得します。
  • パラメーター：min_duration_ms (int, default 1000), limit (int, default 20)
• list_hg_dynamic_tables：ステータス、鮮度設定、最終更新情報とともに、すべての Dynamic Tables を一覧表示します。
  • パラメーター：schema_name (string, optional)
• get_hg_dynamic_table_refresh_history：特定の Dynamic Table の更新履歴を取得します。実行時間、ステータス、レイテンシが含まれます。
  • パラメーター：schema_name (string), table_name (string), limit (int, default 10)
• list_hg_recyclebin：Hologres のごみ箱にあるすべてのテーブル（削除済みで復元可能なテーブル）を一覧表示します。
• restore_hg_table_from_recyclebin：Hologres のごみ箱から削除済みテーブルを復元します。
  • パラメーター：table_name (string), schema_name (string, default "public")
• list_hg_warehouses：CPU、メモリ、クラスター数、ステータスとともに、すべてのコンピューティンググループ（ウェアハウス）を一覧表示します。
• switch_hg_warehouse：現在のセッションのコンピューティングリソースを、指定したウェアハウスに切り替えます。
  • パラメーター：warehouse_name (string)
• get_hg_table_storage_size：合計、データ、インデックス、メタデータの内訳を含む、テーブルのストレージサイズの詳細を取得します。
  • パラメーター：schema_name (string), table (string)
• cancel_hg_query：プロセス ID を指定して、実行中のクエリをキャンセルまたは終了します。
  • パラメーター：pid (int), terminate (bool, default false)
• list_hg_active_queries：pg_stat_activity から、現在アクティブなクエリと接続を一覧表示します。
  • パラメーター：state (string: "active", "idle", or "all", default "active")
• list_hg_query_queues：すべての Query Queue とその分類器（同時実行数の上限、ルーティングルール）を一覧表示します。V3.0 以降が必要です。
• get_hg_table_properties：distribution_key、clustering_key、segment_key、bitmap_columns、binlog の設定など、テーブルのプロパティを取得します。
  • パラメーター：schema_name (string), table (string)
• get_hg_table_shard_info：データ偏りの診断に役立つ、テーブルの Table Group とシャード数の情報を取得します。
  • パラメーター：schema_name (string), table (string)
• list_hg_external_databases：Lakehouse アクセラレーション用のすべての External Database と Foreign Server を一覧表示します。V3.0 以降が必要です。
• get_hg_lock_diagnostics：ブロック中および待機中のクエリを表示し、ロック競合を診断します。
• get_hg_table_info_trend：hg_table_info からテーブルのストレージ推移を取得し、日ごとのストレージサイズ、ファイル数、行数の変化を表示します。
  • パラメーター：schema_name (string), table (string), days (int, default 7)
• manage_hg_query_queue：Query Queue を作成、削除、またはクリアします。V3.0 以降とスーパーユーザー権限が必要です。
  • パラメーター：action (string: "create", "drop", "clear"), queue_name (string), max_concurrency (int, for create), max_queue_size (int, for create)
• manage_hg_classifier：Query Queue の分類器を作成または削除します。V3.0 以降が必要です。
  • パラメーター：action (string: "create", "drop"), queue_name (string), classifier_name (string), priority (int, for create)
• set_hg_query_queue_property：Query Queue または分類器のプロパティを設定または削除します。V3.0 以降が必要です。
  • パラメーター：target (string: "queue", "classifier"), queue_name (string), property_key (string), property_value (string), classifier_name (string, for classifier), action (string: "set", "remove")
• manage_hg_warehouse：コンピューティンググループを管理します。一時停止、再開、再起動、名前変更、またはサイズ変更ができます。スーパーユーザー権限が必要です。
  • パラメーター：action (string: "suspend", "resume", "restart", "rename", "resize"), warehouse_name (string), cu (int, for resize), new_name (string, for rename)
• get_hg_warehouse_status：コンピューティンググループの詳細な稼働状況とスケーリングの進行状況を取得します。
  • パラメーター：warehouse_name (string)
• rebalance_hg_warehouse：コンピューティンググループのシャード再バランスを実行し、データの偏りを解消します。
  • パラメーター：warehouse_name (string)
• list_hg_data_masking_rules：hg_anon 拡張機能を使用して設定された、すべてのデータマスキングルール（列レベルおよびユーザーレベル）を一覧表示します。
• query_hg_external_files：外部テーブルを作成せずに、EXTERNAL_FILES 関数を使って OSS のファイルを直接クエリします。V4.1 以降が必要です。
  • パラメーター：path (string), format (string: "csv", "parquet", "orc"), columns (string, optional), oss_endpoint (string, optional), role_arn (string, optional)
• get_hg_guc_config：GUC（Grand Unified Configuration）パラメーターの現在値を取得します。
  • パラメーター：guc_name (string)

リソース

組み込みリソース

• hologres:///schemas：Hologres データベース内のすべてのスキーマを取得します

リソーステンプレート

• hologres:///{schema}/tables：Hologres データベース内のスキーマにあるすべてのテーブルを一覧表示します

• hologres:///{schema}/{table}/partitions：Hologres データベース内のパーティションテーブルのすべてのパーティションを一覧表示します

• hologres:///{schema}/{table}/ddl：Hologres データベース内のテーブルの DDL を取得します

• 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：Hologres の SQL クエリを最適化するプロンプトを生成します
• 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 データベース接続が必要です。テストスイートには、12 個のテストクラスに分類された61 件のテストケースが含まれています。

テストクラス	テスト数	説明
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