Hologres

Türkçe | 中文

Hologres MCP Sunucusu

Hologres MCP Sunucusu, Yapay Zeka Ajanları ile Hologres veritabanları arasında evrensel bir arayüz görevi görür. Yapay Zeka Ajanları ile Hologres arasında kesintisiz iletişim sağlayarak, Yapay Zeka Ajanlarının Hologres veritabanı meta verilerini almasına ve SQL işlemleri gerçekleştirmesine yardımcı olur.

Yapılandırma

Mod 1: Yerel Dosya Kullanımı

İndirme

Github'dan indirin

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

MCP Entegrasyonu

MCP istemci yapılandırma dosyasına aşağıdaki yapılandırmayı ekleyin:

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

Mod 2: PIP Modu Kullanımı

Kurulum

MCP Sunucusunu aşağıdaki paketi kullanarak kurun:

pip install hologres-mcp-server

MCP Entegrasyonu

MCP istemci yapılandırma dosyasına aşağıdaki yapılandırmayı ekleyin:

uv modunu kullanın

{
    "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 modunu kullanın

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

Mod 3: Akışkan HTTP Aktarımı Kullanımı

Sunucu, STDIO'nun mevcut olmadığı uzaktan dağıtım senaryoları için Akışkan HTTP aktarımını destekler.

Sunucuyu başlatma

Sunucuyu başlatmadan önce, Hologres bağlantı ortam değişkenlerini ayarlayın:

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"

Ardından sunucuyu başlatın:

# 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 uç noktası http://<host>:<port>/mcp adresinde kullanılabilir olacaktır.

CLI Seçenekleri

Seçenek	Varsayılan	Açıklama
--transport	stdio	Aktarım türü: stdio, streamable-http veya sse
--host	127.0.0.1	Bağlanılacak ana bilgisayar (yalnızca HTTP aktarımları)
--port	8000	Dinlenecek bağlantı noktası (yalnızca HTTP aktarımları)

MCP Entegrasyonu

MCP istemci yapılandırma dosyasına aşağıdaki yapılandırmayı ekleyin:

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

Claude Code ile Kullanım

# 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

Bileşenler

Araçlar

• execute_hg_select_sql: Hologres veritabanında bir SELECT SQL sorgusu çalıştırır
• execute_hg_select_sql_with_serverless: Hologres veritabanında sunucusuz hesaplama ile bir SELECT SQL sorgusu çalıştırır
• execute_hg_dml_sql: Hologres veritabanında bir DML (INSERT, UPDATE, DELETE) SQL sorgusu çalıştırır
• execute_hg_ddl_sql: Hologres veritabanında bir DDL (CREATE, ALTER, DROP, COMMENT ON) SQL sorgusu çalıştırır
• gather_hg_table_statistics: Hologres veritabanında tablo istatistiklerini toplar
  • Parametreler: schema_name (dize), table (dize)
• get_hg_query_plan: Hologres veritabanında sorgu planını alır
• get_hg_execution_plan: Hologres veritabanında yürütme planını alır
• call_hg_procedure: Hologres veritabanında bir prosedür çağırır
• create_hg_maxcompute_foreign_table: Hologres veritabanında MaxCompute yabancı tabloları oluşturur.

Bazı Ajanlar kaynakları ve kaynak şablonlarını desteklemediğinden, şemaların, tabloların, görünümlerin ve harici tabloların meta verilerini almak için aşağıdaki araçlar sağlanmıştır.

• list_hg_schemas: Sistem şemaları hariç, mevcut Hologres veritabanındaki tüm şemaları listeler.
• list_hg_tables_in_a_schema: Belirli bir şemadaki tüm tabloları, türleri (tablo, görünüm, harici tablo, bölümlenmiş tablo) dahil olmak üzere listeler.
  • Parametreler: schema_name (dize)
• show_hg_table_ddl: Hologres veritabanındaki bir tablonun, görünümün veya harici tablonun DDL betiğini gösterir.
  • Parametreler: schema_name (dize), table (dize)
• query_and_plotly_chart: Bir SELECT SQL sorgusu çalıştırır ve bir grafik (çubuk, çizgi, dağılım, pasta, histogram, alan) oluşturur. Sorgu sonuçlarını ve base64 kodlu bir PNG görüntüsü döndürür.
  • Parametreler: query (dize), chart_type (dize, varsayılan "bar"), x_column (dize), y_column (dize), title (dize)
• analyze_hg_query_by_id: hg_query_log'dan query_id'ye göre belirli bir sorgunun performans profilini analiz eder. Süre, bellek, CPU zamanı, okuma/yazma istatistikleri gibi ayrıntılı metrikleri döndürür.
  • Parametreler: query_id (dize)
• get_hg_slow_queries: hg_query_log'dan süreye göre sıralanmış yavaş sorguları alır.
  • Parametreler: min_duration_ms (tamsayı, varsayılan 1000), limit (tamsayı, varsayılan 20)
• list_hg_dynamic_tables: Tüm Dinamik Tabloları durumları, güncellik ayarları ve son yenileme bilgileriyle listeler.
  • Parametreler: schema_name (dize, isteğe bağlı)
• get_hg_dynamic_table_refresh_history: Belirli bir Dinamik Tablo için süre, durum ve gecikme dahil yenileme geçmişini alır.
  • Parametreler: schema_name (dize), table_name (dize), limit (tamsayı, varsayılan 10)
• list_hg_recyclebin: Hologres geri dönüşüm kutusundaki tüm tabloları (geri yüklenebilecek silinmiş tablolar) listeler.
• restore_hg_table_from_recyclebin: Hologres geri dönüşüm kutusundan silinmiş bir tabloyu geri yükler.
  • Parametreler: table_name (dize), schema_name (dize, varsayılan "public")
• list_hg_warehouses: Tüm hesaplama gruplarını (ambarlar) CPU, bellek, küme sayısı ve durumlarıyla listeler.
• switch_hg_warehouse: Mevcut oturumun hesaplama kaynağını belirtilen bir ambara geçirir.
  • Parametreler: warehouse_name (dize)
• get_hg_table_storage_size: Toplam, veri, dizin ve meta veri dökümü dahil olmak üzere bir tablonun depolama boyutu ayrıntılarını alır.
  • Parametreler: schema_name (dize), table (dize)
• cancel_hg_query: Süreç kimliğine göre çalışan bir sorguyu iptal eder veya sonlandırır.
  • Parametreler: pid (tamsayı), terminate (bool, varsayılan false)
• list_hg_active_queries: pg_stat_activity'den şu anda aktif olan sorguları ve bağlantıları listeler.
  • Parametreler: state (dize: "active", "idle" veya "all", varsayılan "active")
• list_hg_query_queues: Tüm Sorgu Kuyruklarını ve sınıflandırıcılarını (eşzamanlılık limitleri, yönlendirme kuralları) listeler. V3.0+ gerektirir.
• get_hg_table_properties: distribution_key, clustering_key, segment_key, bitmap_columns, binlog ayarları vb. dahil tablo özelliklerini alır.
  • Parametreler: schema_name (dize), table (dize)
• get_hg_table_shard_info: Veri dengesizliğini teşhis etmek için tablonun Tablo Grubu ve parça sayısı bilgisini alır.
  • Parametreler: schema_name (dize), table (dize)
• list_hg_external_databases: Lakehouse hızlandırması için tüm Harici Veritabanlarını ve Yabancı Sunucuları listeler. V3.0+ gerektirir.
• get_hg_lock_diagnostics: Engelleyen ve bekleyen sorguları göstererek kilit çekişmesini teşhis eder.
• get_hg_table_info_trend: hg_table_info'dan günlük depolama boyutu, dosya sayısı ve satır sayısı değişikliklerini gösteren tablo depolama eğilimini alır.
  • Parametreler: schema_name (dize), table (dize), days (tamsayı, varsayılan 7)
• manage_hg_query_queue: Bir Sorgu Kuyruğu oluşturur, siler veya temizler. V3.0+ ve süper kullanıcı ayrıcalıkları gerektirir.
  • Parametreler: action (dize: "create", "drop", "clear"), queue_name (dize), max_concurrency (tamsayı, oluşturma için), max_queue_size (tamsayı, oluşturma için)
• manage_hg_classifier: Bir Sorgu Kuyruğu için sınıflandırıcı oluşturur veya siler. V3.0+ gerektirir.
  • Parametreler: action (dize: "create", "drop"), queue_name (dize), classifier_name (dize), priority (tamsayı, oluşturma için)
• set_hg_query_queue_property: Bir Sorgu Kuyruğu veya sınıflandırıcı üzerinde özellikleri ayarlar veya kaldırır. V3.0+ gerektirir.
  • Parametreler: target (dize: "queue", "classifier"), queue_name (dize), property_key (dize), property_value (dize), classifier_name (dize, sınıflandırıcı için), action (dize: "set", "remove")
• manage_hg_warehouse: Bir hesaplama grubunu yönetir: askıya al, devam ettir, yeniden başlat, yeniden adlandır veya yeniden boyutlandır. Süper kullanıcı gerektirir.
  • Parametreler: action (dize: "suspend", "resume", "restart", "rename", "resize"), warehouse_name (dize), cu (tamsayı, yeniden boyutlandırma için), new_name (dize, yeniden adlandırma için)
• get_hg_warehouse_status: Bir hesaplama grubunun ayrıntılı çalışma durumunu ve ölçeklendirme ilerlemesini alır.
  • Parametreler: warehouse_name (dize)
• rebalance_hg_warehouse: Veri dengesizliğini gidermek için bir hesaplama grubu için parça yeniden dengelemesini tetikler.
  • Parametreler: warehouse_name (dize)
• list_hg_data_masking_rules: hg_anon uzantısı aracılığıyla yapılandırılmış tüm veri maskeleme kurallarını listeler (sütun düzeyinde ve kullanıcı düzeyinde).
• query_hg_external_files: Yabancı tablolar oluşturmadan EXTERNAL_FILES işlevini kullanarak doğrudan OSS'den dosya sorgular. V4.1+ gerektirir.
  • Parametreler: path (dize), format (dize: "csv", "parquet", "orc"), columns (dize, isteğe bağlı), oss_endpoint (dize, isteğe bağlı), role_arn (dize, isteğe bağlı)
• get_hg_guc_config: Bir GUC (Grand Unified Configuration) parametresinin mevcut değerini alır.
  • Parametreler: guc_name (dize)

Kaynaklar

Yerleşik Kaynaklar

• hologres:///schemas: Hologres veritabanındaki tüm şemaları alır

Kaynak Şablonları

• hologres:///{schema}/tables: Hologres veritabanındaki bir şemadaki tüm tabloları listeler

• hologres:///{schema}/{table}/partitions: Hologres veritabanındaki bölümlenmiş bir tablonun tüm bölümlerini listeler

• hologres:///{schema}/{table}/ddl: Hologres veritabanında tablo DDL'sini alır

• hologres:///{schema}/{table}/statistic: Hologres veritabanında toplanan tablo istatistiklerini gösterir

• system:///{+system_path}: Sistem yolları şunları içerir:

  • hg_instance_version - Hologres örnek sürümünü gösterir.
  • guc_value/<guc_name> - GUC (Grand Unified Configuration) değerini gösterir.
  • missing_stats_tables - İstatistikleri eksik olan tabloları gösterir.
  • stat_activity - Şu anda çalışan sorguların bilgilerini gösterir.
  • query_log/latest/<row_limits> - Belirtilen satır sayısıyla son sorgu günlüğü geçmişini alır.
  • query_log/user/<user_name>/<row_limits> - Satır limitleriyle belirli bir kullanıcı için sorgu günlüğü geçmişini alır.
  • query_log/application/<application_name>/<row_limits> - Satır limitleriyle belirli bir uygulama için sorgu günlüğü geçmişini alır.
  • query_log/failed/<interval>/<row_limits> - Aralık ve belirtilen satır sayısıyla başarısız sorgu günlüğü geçmişini alır.

İstemler

• analyze_table_performance: Hologres'te tablo performansını analiz etmek için bir istem oluşturur
• optimize_query: Hologres'te bir SQL sorgusunu optimize etmek için bir istem oluşturur
• explore_schema: Hologres veritabanında bir şemayı keşfetmek için bir istem oluşturur

Test

Proje kapsamlı birim testleri ve entegrasyon testleri içerir.

Birim Testleri

Birim testleri bir veritabanı bağlantısı gerektirmez ve taklit bağımlılıklar kullanır. Test paketi, aşağıdakileri kapsayan 326 test senaryosu içerir:

• Araç işlevselliği ve SQL doğrulaması
• Kaynaklar ve kaynak şablonları
• İstem oluşturma
• Yardımcı işlevler ve hata yönetimi
• Eşzamanlılık senaryoları
• SQL enjeksiyon koruması

# 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

Entegrasyon Testleri

Entegrasyon testleri gerçek bir Hologres veritabanı bağlantısı gerektirir. Test paketi, 12 test sınıfında düzenlenmiş 61 test senaryosu içerir:

Test Sınıfı	Testler	Açıklama
TestMCPConnection	5	MCP sunucu bağlantısı ve temel işlevsellik
TestMCPResources	14	Kaynak okuma işlevselliği (şemalar, tablolar, DDL, istatistikler, bölümler, sorgu günlükleri)
TestMCPTools	10	Salt okunur işlemler için araç çağrıları
TestMCPProcedureTools	3	Saklı prosedür araç çağrıları
TestMCPMaxComputeTools	1	MaxCompute yabancı tablo oluşturma
TestMCPDDLTools	5	DDL işlemleri (CREATE, ALTER, DROP, COMMENT)
TestMCPDMLTools	3	DML işlemleri (INSERT, UPDATE, DELETE)
TestErrorHandling	3	Hata yönetimi ve uç durumlar
TestMCPPrompts	4	İstem oluşturma işlevselliği
TestMCPConcurrency	3	Eşzamanlı MCP işlemleri
TestMCPBoundaryConditions	4	Uç durumlar (Unicode, NULL, boş sonuçlar)
TestMCPPerformance	3	Performans senaryoları (büyük/geniş sonuç kümeleri)

1. Örnekten bir yapılandırma dosyası oluşturun:

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

2. Yapılandırma dosyasını Hologres kimlik bilgilerinizle düzenleyin:

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

3. Entegrasyon testlerini çalıştırın:

# 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

Not: .test_mcp_client_env dosyası eksikse veya eksik yapılandırma içeriyorsa entegrasyon testleri atlanacaktır.

Kod Kalitesi

Bu proje, kod denetimi ve biçimlendirme için ruff kullanır.

# 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

Derleme ve Yayınlama

Derleme

Bu proje, derleme arka ucu olarak hatchling kullanır. Derleme yapıtları dist/ dizininde oluşturulacaktır.

# Using uv (recommended)
uv build

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

PyPI'ye Yayınlama

# Install twine
pip install twine

# Upload to PyPI
twine upload dist/*

# Or upload to Test PyPI first for verification
twine upload --repository testpypi dist/*

Sürüm İş Akışı

# 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 Özelliğini Güncelleme

# 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