ODPS MCPサーバー

Alibaba Cloud MaxCompute用の読み取り専用MCPサーバー。

ASGIモード

HTTPサーバーには create_app() を使用してください。このアプリは GET /health を公開し、標準のMCP Streamable HTTPアプリを /mcp にマウントします。また、古い呼び出し元との互換性のために / を維持しています。

例:

uvicorn odps_mcp_server.server:create_app --factory

エンドポイント:

• 標準MCPエンドポイント: http://<host>:<port>/mcp

• 互換性MCPエンドポイント: http://<host>:<port>/

• ヘルスチェック: http://<host>:<port>/health

このサービスは streamable-http を介してリモートMCPエンドポイントを公開するため、内部エージェントが許可リストに登録されたMaxComputeテーブルを安全にクエリできます。

環境変数

サーバーを実行する前に、以下の環境変数を設定してください:

• ALIBABA_CLOUD_ACCESS_KEY_ID

• ALIBABA_CLOUD_ACCESS_KEY_SECRET

• ODPS_ENDPOINT

• ODPS_PROJECT

• ODPS_ALLOWLIST_PATH

ODPS_ALLOWLIST_PATH はポリシーファイルを指す必要があります。config/allowlist.example.yaml を基にして、サンプルプロジェクト名とテーブル名を承認済みの許可リストに置き換えてください。

ローカルでのワンクリック起動フローが必要な場合は、.env.local.example を .env.local にコピーし、ODPS認証情報を入力してください。このファイルはgitの管理対象外です。

ローカルセットアップ

仮想環境で依存関係をインストールします:

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

uv を使用する場合の同等のフローは以下の通りです:

uv venv
uv pip install -e .

ポリシーファイル

許可リストファイルは、MCPサーバーがアクセスできるMaxComputeプロジェクトとテーブルを制御します。例:

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

default_limit: 100
max_limit: 200

MCPサーバーの実行

サーバーを起動するには以下を実行します:

python -m odps_mcp_server.server

サーバーは streamable-http モードでMCPトランスポートを開始するように構成されています。

Windowsでのローカル開発の場合は、以下も使用できます:

.\scripts\start-local-mcp.ps1

.env.local を使用したワンクリック起動フローを希望する場合は、以下を使用してください:

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

内部エージェントの統合

内部エージェントは、標準のMCPエンドポイント http://<host>:<port>/mcp に接続する必要があります。ルートパス / は後方互換性のためにのみ利用可能です。このサービスは以下のツールを公開します:

• list_allowed_tables

• describe_table

• preview_table

• run_select_sql

推奨されるエージェントフロー:

1. 許可されたテーブルを一覧表示する。

2. 選択したテーブルのスキーマを読み取る。

3. 必要に応じて行をプレビューする。

4. 許可リストに登録されたテーブルに対して、フィルタリングされた SELECT クエリを実行する。

手動スモークテスト

scripts/manual_smoke_test.py を使用して、非本番環境のMaxComputeプロジェクトに対する接続性とポリシーの動作を検証してください。

例:

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"

許可リストと行制限がレビューされるまで、スモークテストを本番環境専用のプロジェクトに向けないでください。