Hologres

Deutsch | 中文

Hologres MCP Server

Hologres MCP Server dient als universelle Schnittstelle zwischen KI-Agenten und Hologres-Datenbanken. Er ermöglicht eine nahtlose Kommunikation zwischen KI-Agenten und Hologres und hilft KI-Agenten, Metadaten der Hologres-Datenbank abzurufen und SQL-Operationen auszuführen.

Konfiguration

Modus 1: Lokale Datei verwenden

Herunterladen

Von Github herunterladen

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

MCP-Integration

Fügen Sie die folgende Konfiguration zur MCP-Client-Konfigurationsdatei hinzu:

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

Modus 2: PIP-Modus verwenden

Installation

Installieren Sie den MCP Server mit dem folgenden Paket:

pip install hologres-mcp-server

MCP-Integration

Fügen Sie die folgende Konfiguration zur MCP-Client-Konfigurationsdatei hinzu:

UV-Modus verwenden

{
    "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-Modus verwenden

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

Modus 3: Streamable HTTP Transport verwenden

Der Server unterstützt Streamable HTTP Transport für Remote-Bereitstellungsszenarien, in denen STDIO nicht verfügbar ist.

Server starten

Bevor Sie den Server starten, setzen Sie die Umgebungsvariablen für die Hologres-Verbindung:

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"

Starten Sie dann den 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

Der MCP-Endpunkt ist unter http://<host>:<port>/mcp verfügbar.

CLI-Optionen

Option	Standard	Beschreibung
--transport	stdio	Transporttyp: stdio, streamable-http oder sse
--host	127.0.0.1	Host, an den gebunden wird (nur HTTP-Transporte)
--port	8000	Port, auf dem gelauscht wird (nur HTTP-Transporte)

MCP-Integration

Fügen Sie die folgende Konfiguration zur MCP-Client-Konfigurationsdatei hinzu:

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

Verwendung mit 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

Komponenten

Werkzeuge

• execute_hg_select_sql: Eine SELECT-SQL-Abfrage in der Hologres-Datenbank ausführen
• execute_hg_select_sql_with_serverless: Eine SELECT-SQL-Abfrage in der Hologres-Datenbank mit serverloser Berechnung ausführen
• execute_hg_dml_sql: Eine DML-SQL-Abfrage (INSERT, UPDATE, DELETE) in der Hologres-Datenbank ausführen
• execute_hg_ddl_sql: Eine DDL-SQL-Abfrage (CREATE, ALTER, DROP, COMMENT ON) in der Hologres-Datenbank ausführen
• gather_hg_table_statistics: Tabellenstatistiken in der Hologres-Datenbank sammeln
  • Parameter: schema_name (String), table (String)
• get_hg_query_plan: Abfrageplan in der Hologres-Datenbank abrufen
• get_hg_execution_plan: Ausführungsplan in der Hologres-Datenbank abrufen
• call_hg_procedure: Eine Prozedur in der Hologres-Datenbank aufrufen
• create_hg_maxcompute_foreign_table: MaxCompute-Fremdtabellen in der Hologres-Datenbank erstellen.

Da einige Agenten keine Ressourcen und Ressourcenvorlagen unterstützen, werden die folgenden Werkzeuge bereitgestellt, um die Metadaten von Schemata, Tabellen, Ansichten und externen Tabellen abzurufen.

• list_hg_schemas: Listet alle Schemata in der aktuellen Hologres-Datenbank auf, mit Ausnahme von Systemschemata.
• list_hg_tables_in_a_schema: Listet alle Tabellen in einem bestimmten Schema auf, einschließlich ihrer Typen (Tabelle, Ansicht, externe Tabelle, partitionierte Tabelle).
  • Parameter: schema_name (String)
• show_hg_table_ddl: Zeigt das DDL-Skript einer Tabelle, Ansicht oder externen Tabelle in der Hologres-Datenbank an.
  • Parameter: schema_name (String), table (String)
• query_and_plotly_chart: Führt eine SELECT-SQL-Abfrage aus und generiert ein Diagramm (Balken, Linie, Streuung, Kreis, Histogramm, Fläche). Gibt Abfrageergebnisse und ein base64-kodiertes PNG-Bild zurück.
  • Parameter: query (String), chart_type (String, Standard "bar"), x_column (String), y_column (String), title (String)
• analyze_hg_query_by_id: Analysiert das Leistungsprofil einer bestimmten Abfrage anhand ihrer query_id aus hg_query_log. Gibt detaillierte Metriken zurück, einschließlich Dauer, Speicher, CPU-Zeit, Lese-/Schreibstatistiken.
  • Parameter: query_id (String)
• get_hg_slow_queries: Ruft langsame Abfragen aus hg_query_log ab, sortiert nach Dauer.
  • Parameter: min_duration_ms (int, Standard 1000), limit (int, Standard 20)
• list_hg_dynamic_tables: Listet alle dynamischen Tabellen mit ihrem Status, Aktualitätseinstellungen und Informationen zur letzten Aktualisierung auf.
  • Parameter: schema_name (String, optional)
• get_hg_dynamic_table_refresh_history: Ruft den Aktualisierungsverlauf für eine bestimmte dynamische Tabelle ab, einschließlich Dauer, Status und Latenz.
  • Parameter: schema_name (String), table_name (String), limit (int, Standard 10)
• list_hg_recyclebin: Listet alle Tabellen im Hologres-Papierkorb auf (gelöschte Tabellen, die wiederhergestellt werden können).
• restore_hg_table_from_recyclebin: Stellt eine gelöschte Tabelle aus dem Hologres-Papierkorb wieder her.
  • Parameter: table_name (String), schema_name (String, Standard "public")
• list_hg_warehouses: Listet alle Rechengruppen (Warehouses) mit ihrer CPU, Speicher, Cluster-Anzahl und Status auf.
• switch_hg_warehouse: Wechselt die Rechenressource der aktuellen Sitzung zu einem angegebenen Warehouse.
  • Parameter: warehouse_name (String)
• get_hg_table_storage_size: Ruft Details zur Speichergröße einer Tabelle ab, einschließlich Aufschlüsselung nach Gesamt-, Daten-, Index- und Metadatengröße.
  • Parameter: schema_name (String), table (String)
• cancel_hg_query: Bricht eine laufende Abfrage anhand ihrer Prozess-ID ab oder beendet sie.
  • Parameter: pid (int), terminate (bool, Standard false)
• list_hg_active_queries: Listet aktuell aktive Abfragen und Verbindungen aus pg_stat_activity auf.
  • Parameter: state (String: "active", "idle" oder "all", Standard "active")
• list_hg_query_queues: Listet alle Abfragewarteschlangen und ihre Klassifizierer auf (Parallelitätsgrenzen, Routing-Regeln). Erfordert V3.0+.
• get_hg_table_properties: Ruft Tabelleneigenschaften ab, einschließlich distribution_key, clustering_key, segment_key, bitmap_columns, Binlog-Einstellungen usw.
  • Parameter: schema_name (String), table (String)
• get_hg_table_shard_info: Ruft Informationen zur Tabellengruppe und Shard-Anzahl einer Tabelle ab, um Datenschieflage zu diagnostizieren.
  • Parameter: schema_name (String), table (String)
• list_hg_external_databases: Listet alle externen Datenbanken und Fremdserver für die Lakehouse-Beschleunigung auf. Erfordert V3.0+.
• get_hg_lock_diagnostics: Diagnostiziert Sperrkonflikte, indem blockierende und wartende Abfragen angezeigt werden.
• get_hg_table_info_trend: Ruft den Tabellenspeichertrend aus hg_table_info ab und zeigt tägliche Änderungen der Speichergröße, Dateianzahl und Zeilenanzahl.
  • Parameter: schema_name (String), table (String), days (int, Standard 7)
• manage_hg_query_queue: Erstellt, löscht oder leert eine Abfragewarteschlange. Erfordert V3.0+ und Superuser-Berechtigungen.
  • Parameter: action (String: "create", "drop", "clear"), queue_name (String), max_concurrency (int, für create), max_queue_size (int, für create)
• manage_hg_classifier: Erstellt oder löscht einen Klassifizierer für eine Abfragewarteschlange. Erfordert V3.0+.
  • Parameter: action (String: "create", "drop"), queue_name (String), classifier_name (String), priority (int, für create)
• set_hg_query_queue_property: Setzt oder entfernt Eigenschaften einer Abfragewarteschlange oder eines Klassifizierers. Erfordert V3.0+.
  • Parameter: target (String: "queue", "classifier"), queue_name (String), property_key (String), property_value (String), classifier_name (String, für classifier), action (String: "set", "remove")
• manage_hg_warehouse: Verwaltet eine Rechengruppe: anhalten, fortsetzen, neu starten, umbenennen oder skalieren. Erfordert Superuser.
  • Parameter: action (String: "suspend", "resume", "restart", "rename", "resize"), warehouse_name (String), cu (int, für resize), new_name (String, für rename)
• get_hg_warehouse_status: Ruft den detaillierten Ausführungsstatus und den Skalierungsfortschritt einer Rechengruppe ab.
  • Parameter: warehouse_name (String)
• rebalance_hg_warehouse: Löst eine Shard-Neuverteilung für eine Rechengruppe aus, um Datenschieflage zu beseitigen.
  • Parameter: warehouse_name (String)
• list_hg_data_masking_rules: Listet alle über die hg_anon-Erweiterung konfigurierten Datenmaskierungsregeln auf (spalten- und benutzerspezifisch).
• query_hg_external_files: Fragt Dateien direkt aus OSS mit der EXTERNAL_FILES-Funktion ab, ohne Fremdtabellen zu erstellen. Erfordert V4.1+.
  • Parameter: path (String), format (String: "csv", "parquet", "orc"), columns (String, optional), oss_endpoint (String, optional), role_arn (String, optional)
• get_hg_guc_config: Ruft den aktuellen Wert eines GUC-Parameters (Grand Unified Configuration) ab.
  • Parameter: guc_name (String)

Ressourcen

Integrierte Ressourcen

• hologres:///schemas: Alle Schemata in der Hologres-Datenbank abrufen

Ressourcenvorlagen

• hologres:///{schema}/tables: Alle Tabellen in einem Schema in der Hologres-Datenbank auflisten

• hologres:///{schema}/{table}/partitions: Alle Partitionen einer partitionierten Tabelle in der Hologres-Datenbank auflisten

• hologres:///{schema}/{table}/ddl: Tabellen-DDL in der Hologres-Datenbank abrufen

• hologres:///{schema}/{table}/statistic: Gesammelte Tabellenstatistiken in der Hologres-Datenbank anzeigen

• system:///{+system_path}: Systempfade umfassen:

  • hg_instance_version - Zeigt die Version der Hologres-Instanz an.
  • guc_value/<guc_name> - Zeigt den GUC-Wert (Grand Unified Configuration) an.
  • missing_stats_tables - Zeigt die Tabellen an, für die Statistiken fehlen.
  • stat_activity - Zeigt die Informationen der aktuell laufenden Abfragen an.
  • query_log/latest/<row_limits> - Ruft den aktuellen Abfrageprotokollverlauf mit einer angegebenen Anzahl von Zeilen ab.
  • query_log/user/<user_name>/<row_limits> - Ruft den Abfrageprotokollverlauf für einen bestimmten Benutzer mit Zeilenbegrenzung ab.
  • query_log/application/<application_name>/<row_limits> - Ruft den Abfrageprotokollverlauf für eine bestimmte Anwendung mit Zeilenbegrenzung ab.
  • query_log/failed/<interval>/<row_limits> - Ruft den Verlauf fehlgeschlagener Abfragen mit Intervall und angegebener Zeilenanzahl ab.

Eingabeaufforderungen

• analyze_table_performance: Generiert eine Eingabeaufforderung zur Analyse der Tabellenleistung in Hologres
• optimize_query: Generiert eine Eingabeaufforderung zur Optimierung einer SQL-Abfrage in Hologres
• explore_schema: Generiert eine Eingabeaufforderung zum Erkunden eines Schemas in der Hologres-Datenbank

Testen

Das Projekt umfasst umfassende Unit-Tests und Integrationstests.

Unit-Tests

Unit-Tests erfordern keine Datenbankverbindung und verwenden gemockte Abhängigkeiten. Die Testsuite umfasst 326 Testfälle, die Folgendes abdecken:

• Werkzeugfunktionalität und SQL-Validierung
• Ressourcen und Ressourcenvorlagen
• Generierung von Eingabeaufforderungen
• Hilfsfunktionen und Fehlerbehandlung
• Parallelitätsszenarien
• SQL-Injection-Schutz

# 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

Integrationstests

Integrationstests erfordern eine echte Hologres-Datenbankverbindung. Die Testsuite umfasst 61 Testfälle, die in 12 Testklassen organisiert sind:

Testklasse	Tests	Beschreibung
TestMCPConnection	5	MCP-Serververbindung und grundlegende Funktionalität
TestMCPResources	14	Ressourcenlesefunktionalität (Schemata, Tabellen, DDL, Statistiken, Partitionen, Abfrageprotokolle)
TestMCPTools	10	Werkzeugaufrufe für schreibgeschützte Operationen
TestMCPProcedureTools	3	Aufrufe gespeicherter Prozeduren
TestMCPMaxComputeTools	1	Erstellung von MaxCompute-Fremdtabellen
TestMCPDDLTools	5	DDL-Operationen (CREATE, ALTER, DROP, COMMENT)
TestMCPDMLTools	3	DML-Operationen (INSERT, UPDATE, DELETE)
TestErrorHandling	3	Fehlerbehandlung und Grenzfälle
TestMCPPrompts	4	Funktionalität zur Generierung von Eingabeaufforderungen
TestMCPConcurrency	3	Gleichzeitige MCP-Operationen
TestMCPBoundaryConditions	4	Grenzfälle (Unicode, NULL, leere Ergebnisse)
TestMCPPerformance	3	Leistungsszenarien (große/breite Ergebnismengen)

1. Erstellen Sie eine Konfigurationsdatei aus dem Beispiel:

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

2. Bearbeiten Sie die Konfigurationsdatei mit Ihren Hologres-Anmeldeinformationen:

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

3. Führen Sie die Integrationstests aus:

# 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

Hinweis: Integrationstests werden übersprungen, wenn die Datei .test_mcp_client_env fehlt oder eine unvollständige Konfiguration enthält.

Codequalität

Dieses Projekt verwendet ruff für Code-Linting und -Formatierung.

# 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 & Veröffentlichung

Build

Dieses Projekt verwendet hatchling als Build-Backend. Build-Artefakte werden im Verzeichnis dist/ generiert.

# Using uv (recommended)
uv build

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

Veröffentlichung auf 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/*

Release-Workflow

# 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-Funktion aktualisieren

# 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