Hologres

English | 中文

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: 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 (string), table (string)
• 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, デフォルト "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, デフォルト 1000), limit (int, デフォルト 20)
• list_hg_dynamic_tables: すべての動的テーブルを、そのステータス、鮮度設定、最終更新情報とともに一覧表示します。
  • パラメータ: schema_name (string, オプション)
• get_hg_dynamic_table_refresh_history: 特定の動的テーブルの更新履歴を、所要時間、ステータス、レイテンシを含めて取得します。
  • パラメータ: schema_name (string), table_name (string), limit (int, デフォルト 10)
• list_hg_recyclebin: Hologresのごみ箱内のすべてのテーブル (復元可能な削除済みテーブル) を一覧表示します。
• restore_hg_table_from_recyclebin: Hologresのごみ箱から削除されたテーブルを復元します。
  • パラメータ: table_name (string), schema_name (string, デフォルト "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, デフォルト false)
• list_hg_active_queries: pg_stat_activityから現在アクティブなクエリと接続を一覧表示します。
  • パラメータ: state (string: "active"、"idle"、または "all"、デフォルト "active")
• list_hg_query_queues: すべてのクエリキューとその分類子 (同時実行制限、ルーティングルール) を一覧表示します。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: データスキューを診断するためのテーブルのテーブルグループとシャード数情報を取得します。
  • パラメータ: schema_name (string), table (string)
• list_hg_external_databases: レイクハウスアクセラレーション用のすべての外部データベースと外部サーバーを一覧表示します。V3.0以降が必要です。
• get_hg_lock_diagnostics: ブロッキングクエリと待機中クエリを表示してロック競合を診断します。
• get_hg_table_info_trend: hg_table_infoからテーブルストレージの傾向を取得し、日次ストレージサイズ、ファイル数、行数の変化を表示します。
  • パラメータ: schema_name (string), table (string), days (int, デフォルト 7)
• manage_hg_query_queue: クエリキューを作成、削除、またはクリアします。V3.0以降とスーパーユーザー権限が必要です。
  • パラメータ: action (string: "create"、"drop"、"clear"), queue_name (string), max_concurrency (int, create用), max_queue_size (int, create用)
• manage_hg_classifier: クエリキューの分類子を作成または削除します。V3.0以降が必要です。
  • パラメータ: action (string: "create"、"drop"), queue_name (string), classifier_name (string), priority (int, create用)
• set_hg_query_queue_property: クエリキューまたは分類子のプロパティを設定または削除します。V3.0以降が必要です。
  • パラメータ: target (string: "queue"、"classifier"), queue_name (string), property_key (string), property_value (string), classifier_name (string, classifier用), action (string: "set"、"remove")
• manage_hg_warehouse: コンピューティンググループを管理します: 一時停止、再開、再起動、名前変更、またはサイズ変更。スーパーユーザーが必要です。
  • パラメータ: action (string: "suspend"、"resume"、"restart"、"rename"、"resize"), warehouse_name (string), cu (int, resize用), new_name (string, 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, オプション), oss_endpoint (string, オプション), role_arn (string, オプション)
• 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