ODPS MCP-Server

Schreibgeschützter MCP-Server für Alibaba Cloud MaxCompute.

ASGI-Modus

Verwenden Sie create_app() für den HTTP-Server. Die App stellt GET /health bereit, bindet die standardmäßige MCP Streamable HTTP-App unter /mcp ein und behält / als Kompatibilitätspfad für ältere Aufrufer bei.

Beispiel:

uvicorn odps_mcp_server.server:create_app --factory

Endpunkte:

• Standard-MCP-Endpunkt: http://<host>:<port>/mcp

• Kompatibilitäts-MCP-Endpunkt: http://<host>:<port>/

• Gesundheitsprüfung: http://<host>:<port>/health

Dieser Dienst stellt einen Remote-MCP-Endpunkt über streamable-http bereit, sodass ein interner Agent sicher MaxCompute-Tabellen auf der Zulassungsliste abfragen kann.

Umgebung

Setzen Sie diese Umgebungsvariablen, bevor Sie den Server starten:

• ALIBABA_CLOUD_ACCESS_KEY_ID

• ALIBABA_CLOUD_ACCESS_KEY_SECRET

• ODPS_ENDPOINT

• ODPS_PROJECT

• ODPS_ALLOWLIST_PATH

ODPS_ALLOWLIST_PATH sollte auf Ihre Richtliniendatei verweisen. Beginnen Sie mit config/allowlist.example.yaml und ersetzen Sie die Beispielprojekt- und Tabellennamen durch Ihre genehmigte Zulassungsliste.

Wenn Sie einen lokalen One-Click-Startablauf wünschen, kopieren Sie .env.local.example nach .env.local und geben Sie Ihre ODPS-Anmeldedaten ein. Die Datei wird von git ignoriert.

Lokale Einrichtung

Installieren Sie die Abhängigkeiten in einer virtuellen Umgebung:

python -m venv .venv
.venv\Scripts\activate
pip install -e .

Wenn Sie uv bevorzugen, ist der entsprechende Ablauf:

uv venv
uv pip install -e .

Richtliniendatei

Die Zulassungslistendatei steuert, auf welche MaxCompute-Projekte und -Tabellen der MCP-Server zugreifen kann. Beispiel:

projects:
  analytics:
    tables:
      sales_orders:
        allowed_columns:
          - order_id
          - order_date

default_limit: 100
max_limit: 200

Den MCP-Server ausführen

Starten Sie den Server mit:

python -m odps_mcp_server.server

Der Server ist so konfiguriert, dass der MCP-Transport im streamable-http-Modus gestartet wird.

Für die lokale Entwicklung unter Windows können Sie auch Folgendes verwenden:

.\scripts\start-local-mcp.ps1

Wenn Sie einen One-Click-Startablauf bevorzugen, der auf .env.local basiert, verwenden Sie:

.\scripts\start-local-mcp-oneclick.ps1

Integration interner Agenten

Ihr interner Agent sollte eine Verbindung zum Standard-MCP-Endpunkt http://<host>:<port>/mcp herstellen. Der Stammpfad / bleibt nur aus Gründen der Abwärtskompatibilität verfügbar. Der Dienst stellt diese Tools bereit:

• list_allowed_tables

• describe_table

• preview_table

• run_select_sql

Empfohlener Agent-Ablauf:

1. Zulässige Tabellen auflisten.

2. Das Schema für eine ausgewählte Tabelle lesen.

3. Zeilen bei Bedarf in der Vorschau anzeigen.

4. Eine gefilterte SELECT-Abfrage gegen die Tabelle auf der Zulassungsliste ausführen.

Manueller Rauchtest

Verwenden Sie scripts/manual_smoke_test.py, um die Konnektivität und das Richtlinienverhalten gegenüber einem Nicht-Produktions-MaxCompute-Projekt zu validieren.

Beispiele:

python scripts/manual_smoke_test.py list-tables --project analytics
python scripts/manual_smoke_test.py describe-table --project analytics --table sales_orders
python scripts/manual_smoke_test.py run-sql --project analytics --sql "SELECT order_id FROM analytics.sales_orders LIMIT 10"

Verweisen Sie den Rauchtest nicht auf ein reines Produktionsprojekt, bevor die Zulassungsliste und die Zeilenbeschränkungen überprüft wurden.