Hologres

English | 中文

Hologres MCP Server

Hologres MCP Server berfungsi sebagai antarmuka universal antara AI Agent dan basis data Hologres. Ini memungkinkan komunikasi yang lancar antara AI Agent dan Hologres, membantu AI Agent mengambil metadata basis data Hologres dan menjalankan operasi SQL.

Konfigurasi

Mode 1: Menggunakan File Lokal

Unduh

Unduh dari Github

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

Integrasi MCP

Tambahkan konfigurasi berikut ke file konfigurasi klien 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: Menggunakan Mode PIP

Instalasi

Instal MCP Server menggunakan paket berikut:

pip install hologres-mcp-server

Integrasi MCP

Tambahkan konfigurasi berikut ke file konfigurasi klien MCP:

Gunakan 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"
            }
        }
    }
}

Gunakan 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: Menggunakan Streamable HTTP Transport

Server mendukung Streamable HTTP transport untuk skenario deployment jarak jauh di mana STDIO tidak tersedia.

Mulai server

Sebelum memulai server, atur variabel lingkungan koneksi 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"

Kemudian mulai server:

# 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

Endpoint MCP akan tersedia di http://<host>:<port>/mcp.

Opsi CLI

Opsi	Default	Deskripsi
--transport	stdio	Tipe transport: stdio, streamable-http, atau sse
--host	127.0.0.1	Host yang akan diikat (hanya untuk transport HTTP)
--port	8000	Port yang akan didengarkan (hanya untuk transport HTTP)

Integrasi MCP

Tambahkan konfigurasi berikut ke file konfigurasi klien MCP:

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

Menggunakan dengan 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

Komponen

Tools

• execute_hg_select_sql: Jalankan kueri SQL SELECT di basis data Hologres
• execute_hg_select_sql_with_serverless: Jalankan kueri SQL SELECT di basis data Hologres dengan komputasi serverless
• execute_hg_dml_sql: Jalankan kueri SQL DML (INSERT, UPDATE, DELETE) di basis data Hologres
• execute_hg_ddl_sql: Jalankan kueri SQL DDL (CREATE, ALTER, DROP, COMMENT ON) di basis data Hologres
• gather_hg_table_statistics: Kumpulkan statistik tabel di basis data Hologres
  • Parameter: schema_name (string), table (string)
• get_hg_query_plan: Dapatkan rencana kueri di basis data Hologres
• get_hg_execution_plan: Dapatkan rencana eksekusi di basis data Hologres
• call_hg_procedure: Panggil prosedur di basis data Hologres
• create_hg_maxcompute_foreign_table: Buat tabel asing MaxCompute di basis data Hologres.

Karena beberapa Agent tidak mendukung resource dan template resource, tool berikut disediakan untuk mendapatkan metadata skema, tabel, view, dan tabel eksternal.

• list_hg_schemas: Menampilkan semua skema di basis data Hologres saat ini, tidak termasuk skema sistem.
• list_hg_tables_in_a_schema: Menampilkan semua tabel dalam skema tertentu, termasuk tipenya (tabel, view, tabel eksternal, tabel terpartisi).
  • Parameter: schema_name (string)
• show_hg_table_ddl: Tampilkan skrip DDL dari tabel, view, atau tabel eksternal di basis data Hologres.
  • Parameter: schema_name (string), table (string)
• query_and_plotly_chart: Jalankan kueri SQL SELECT dan hasilkan grafik (batang, garis, sebar, pai, histogram, area). Mengembalikan hasil kueri dan gambar PNG yang dienkode base64.
  • Parameter: query (string), chart_type (string, default "bar"), x_column (string), y_column (string), title (string)
• analyze_hg_query_by_id: Analisis profil performa kueri tertentu berdasarkan query_id dari hg_query_log. Mengembalikan metrik detail termasuk durasi, memori, waktu CPU, statistik baca/tulis.
  • Parameter: query_id (string)
• get_hg_slow_queries: Dapatkan kueri lambat dari hg_query_log yang diurutkan berdasarkan durasi.
  • Parameter: min_duration_ms (int, default 1000), limit (int, default 20)
• list_hg_dynamic_tables: Tampilkan semua Dynamic Table dengan status, pengaturan freshness, dan info refresh terakhir.
  • Parameter: schema_name (string, opsional)
• get_hg_dynamic_table_refresh_history: Dapatkan riwayat refresh untuk Dynamic Table tertentu, termasuk durasi, status, dan latensi.
  • Parameter: schema_name (string), table_name (string), limit (int, default 10)
• list_hg_recyclebin: Tampilkan semua tabel di recycle bin Hologres (tabel yang dihapus yang dapat dipulihkan).
• restore_hg_table_from_recyclebin: Pulihkan tabel yang dihapus dari recycle bin Hologres.
  • Parameter: table_name (string), schema_name (string, default "public")
• list_hg_warehouses: Tampilkan semua computing group (warehouse) dengan CPU, memori, jumlah kluster, dan statusnya.
• switch_hg_warehouse: Alihkan sumber daya komputasi sesi saat ini ke warehouse yang ditentukan.
  • Parameter: warehouse_name (string)
• get_hg_table_storage_size: Dapatkan detail ukuran penyimpanan tabel, termasuk rincian total, data, indeks, dan metadata.
  • Parameter: schema_name (string), table (string)
• cancel_hg_query: Batalkan atau hentikan kueri yang sedang berjalan berdasarkan ID prosesnya.
  • Parameter: pid (int), terminate (bool, default false)
• list_hg_active_queries: Tampilkan kueri dan koneksi yang sedang aktif dari pg_stat_activity.
  • Parameter: state (string: "active", "idle", atau "all", default "active")
• list_hg_query_queues: Tampilkan semua Query Queue dan pengklasifikasinya (batas konkurensi, aturan routing). Memerlukan V3.0+.
• get_hg_table_properties: Dapatkan properti tabel termasuk distribution_key, clustering_key, segment_key, bitmap_columns, pengaturan binlog, dll.
  • Parameter: schema_name (string), table (string)
• get_hg_table_shard_info: Dapatkan info Table Group dan jumlah shard tabel untuk mendiagnosis ketidakseimbangan data.
  • Parameter: schema_name (string), table (string)
• list_hg_external_databases: Tampilkan semua External Database dan Foreign Server untuk akselerasi Lakehouse. Memerlukan V3.0+.
• get_hg_lock_diagnostics: Diagnosis pertentangan kunci dengan menampilkan kueri yang memblokir dan menunggu.
• get_hg_table_info_trend: Dapatkan tren penyimpanan tabel dari hg_table_info, menampilkan ukuran penyimpanan harian, jumlah file, dan perubahan jumlah baris.
  • Parameter: schema_name (string), table (string), days (int, default 7)
• manage_hg_query_queue: Buat, hapus, atau kosongkan Query Queue. Memerlukan V3.0+ dan hak superuser.
  • Parameter: action (string: "create", "drop", "clear"), queue_name (string), max_concurrency (int, untuk create), max_queue_size (int, untuk create)
• manage_hg_classifier: Buat atau hapus pengklasifikasi untuk Query Queue. Memerlukan V3.0+.
  • Parameter: action (string: "create", "drop"), queue_name (string), classifier_name (string), priority (int, untuk create)
• set_hg_query_queue_property: Atur atau hapus properti pada Query Queue atau pengklasifikasi. Memerlukan V3.0+.
  • Parameter: target (string: "queue", "classifier"), queue_name (string), property_key (string), property_value (string), classifier_name (string, untuk classifier), action (string: "set", "remove")
• manage_hg_warehouse: Kelola computing group: suspend, resume, restart, rename, atau resize. Memerlukan superuser.
  • Parameter: action (string: "suspend", "resume", "restart", "rename", "resize"), warehouse_name (string), cu (int, untuk resize), new_name (string, untuk rename)
• get_hg_warehouse_status: Dapatkan status berjalan detail dan progres scaling dari computing group.
  • Parameter: warehouse_name (string)
• rebalance_hg_warehouse: Picu penyeimbangan ulang shard untuk computing group guna menghilangkan ketidakseimbangan data.
  • Parameter: warehouse_name (string)
• list_hg_data_masking_rules: Tampilkan semua aturan penyamaran data yang dikonfigurasi melalui ekstensi hg_anon (tingkat kolom dan tingkat pengguna).
• query_hg_external_files: Kueri file langsung dari OSS menggunakan fungsi EXTERNAL_FILES tanpa membuat tabel asing. Memerlukan V4.1+.
  • Parameter: path (string), format (string: "csv", "parquet", "orc"), columns (string, opsional), oss_endpoint (string, opsional), role_arn (string, opsional)
• get_hg_guc_config: Dapatkan nilai saat ini dari parameter GUC (Grand Unified Configuration).
  • Parameter: guc_name (string)

Resources

Resource Bawaan

• hologres:///schemas: Dapatkan semua skema di basis data Hologres

Template Resource

• hologres:///{schema}/tables: Tampilkan semua tabel dalam skema di basis data Hologres

• hologres:///{schema}/{table}/partitions: Tampilkan semua partisi dari tabel terpartisi di basis data Hologres

• hologres:///{schema}/{table}/ddl: Dapatkan DDL tabel di basis data Hologres

• hologres:///{schema}/{table}/statistic: Tampilkan statistik tabel yang dikumpulkan di basis data Hologres

• system:///{+system_path}: Jalur sistem meliputi:

  • hg_instance_version - Menampilkan versi instans hologres.
  • guc_value/<guc_name> - Menampilkan nilai guc (Grand Unified Configuration).
  • missing_stats_tables - Menampilkan tabel yang tidak memiliki statistik.
  • stat_activity - Menampilkan informasi kueri yang sedang berjalan.
  • query_log/latest/<row_limits> - Dapatkan riwayat log kueri terbaru dengan jumlah baris yang ditentukan.
  • query_log/user/<user_name>/<row_limits> - Dapatkan riwayat log kueri untuk pengguna tertentu dengan batas baris.
  • query_log/application/<application_name>/<row_limits> - Dapatkan riwayat log kueri untuk aplikasi tertentu dengan batas baris.
  • query_log/failed/<interval>/<row_limits> - Dapatkan riwayat log kueri yang gagal dengan interval dan jumlah baris yang ditentukan.

Prompts

• analyze_table_performance: Hasilkan prompt untuk menganalisis performa tabel di Hologres
• optimize_query: Hasilkan prompt untuk mengoptimalkan kueri SQL di Hologres
• explore_schema: Hasilkan prompt untuk menjelajahi skema di basis data Hologres

Pengujian

Proyek ini mencakup pengujian unit dan pengujian integrasi yang komprehensif.

Pengujian Unit

Pengujian unit tidak memerlukan koneksi basis data dan menggunakan dependensi tiruan. Rangkaian pengujian mencakup 326 kasus uji yang meliputi:

• Fungsionalitas tools dan validasi SQL
• Resource dan template resource
• Pembuatan prompt
• Fungsi utilitas dan penanganan kesalahan
• Skenario konkurensi
• Perlindungan injeksi 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

Pengujian Integrasi

Pengujian integrasi memerlukan koneksi basis data Hologres nyata. Rangkaian pengujian mencakup 61 kasus uji yang diatur dalam 12 kelas uji:

Kelas Uji	Pengujian	Deskripsi
TestMCPConnection	5	Koneksi server MCP dan fungsionalitas dasar
TestMCPResources	14	Fungsionalitas pembacaan resource (skema, tabel, DDL, statistik, partisi, log kueri)
TestMCPTools	10	Panggilan tool untuk operasi baca-saja
TestMCPProcedureTools	3	Panggilan tool prosedur tersimpan
TestMCPMaxComputeTools	1	Pembuatan tabel asing MaxCompute
TestMCPDDLTools	5	Operasi DDL (CREATE, ALTER, DROP, COMMENT)
TestMCPDMLTools	3	Operasi DML (INSERT, UPDATE, DELETE)
TestErrorHandling	3	Penanganan kesalahan dan kasus tepi
TestMCPPrompts	4	Fungsionalitas pembuatan prompt
TestMCPConcurrency	3	Operasi MCP konkuren
TestMCPBoundaryConditions	4	Kasus tepi (Unicode, NULL, hasil kosong)
TestMCPPerformance	3	Skenario performa (set hasil besar/lebar)

1. Buat file konfigurasi dari contoh:

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

2. Edit file konfigurasi dengan kredensial Hologres Anda:

HOLOGRES_HOST=your-hologres-instance.hologres.aliyuncs.com
HOLOGRES_PORT=80
HOLOGRES_USER=your_username
HOLOGRES_PASSWORD=your_password
HOLOGRES_DATABASE=your_database

3. Jalankan pengujian integrasi:

# 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

Catatan: Pengujian integrasi akan dilewati jika file .test_mcp_client_env hilang atau berisi konfigurasi yang tidak lengkap.

Kualitas Kode

Proyek ini menggunakan ruff untuk linting dan pemformatan kode.

# 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 & Publish

Build

Proyek ini menggunakan hatchling sebagai backend build. Artefak build akan dihasilkan di direktori dist/.

# Using uv (recommended)
uv build

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

Publish ke 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/*

Alur Kerja Rilis

# 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

Fitur CLI Pembaruan

# 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