VAST DB MCP Server

VAST DB MCP Server

このプロジェクトでは、AI エージェント／LLM と VAST Data データベースの間のインターフェースとして機能する、Model Context Protocol（MCP）サーバーを実装しています。

プロジェクトの目標

MCP 標準を使用して、AI モデルが VAST DB インスタンスに対して情報（スキーマ、データサンプル）を安全かつ構造的に照会し、読み取り専用クエリを実行できるようにします。

中核となる技術

• Python： >=3.9
• MCP SDK： modelcontextprotocol/python-sdk（mcp-sdk）
• VAST DB SDK： vast-data/vastdb_sdk（vastdb）
• ASGI サーバー： uvicorn
• MCP の実装： mcp-sdk の FastMCP
• 設定： python-dotenv
• テスト： pytest、pytest-asyncio、pytest-mock、httpx
• レート制限： slowapi

プロジェクト構成

/
├── sdk/                     # Cloned SDKs (ignored by git)
│   ├── python-sdk/
│   └── vastdb_sdk/
├── src/
│   └── vast_mcp_server/     # Main Python package
│       ├── __init__.py
│       ├── server.py          # FastMCP application setup
│       ├── config.py          # Loads connection details from .env
│       ├── utils.py           # Shared utility functions (e.g., auth header extraction)
│       ├── resources/         # MCP Resource handlers
│       │   ├── __init__.py
│       │   ├── schema.py      # Handler for vast://schemas
│       │   ├── table_data.py  # Handler for vast://tables/{table_name}
│       │   └── metadata.py    # Handler for vast://metadata/tables/{table_name}
│       ├── tools/             # MCP Tool handlers
│       │   ├── __init__.py
│       │   └── query.py       # Handler for vast_sql_query tool
│       └── vast_integration/  # VAST DB interaction logic
│           ├── __init__.py
│           └── db_ops.py      # Connection & query execution (async wrappers)
├── tests/                   # Pytest unit/integration tests
│   ├── __init__.py
│   ├── test_db_ops.py     # Tests for VAST DB interaction logic
│   ├── test_resources.py  # Tests for MCP resource handlers
│   └── test_tools.py      # Tests for MCP tool handlers
├── scripts/
│   └── run_server.py        # Script to start the server via uvicorn
├── .gitignore
├── .env.example             # Example environment file
├── README.md                # This file
└── pyproject.toml           # Project metadata and dependencies

実装済みの MCP 機能

認証： すべてのリソースとツールでは、リクエストに次の HTTP ヘッダーを含める必要があります。

• X-Vast-Access-Key：VAST DB のアクセスキー。
• X-Vast-Secret-Key：VAST DB のシークレットキー。 これらのヘッダーが指定されていない場合、または無効な認証情報が指定された場合は、UNAUTHENTICATED（401）エラーレスポンスが返されます。

レート制限： すべてのリソースおよびツールのハンドラーには、クライアントの IP アドレスに基づくレート制限が適用されます。デフォルトの制限は、MCP_DEFAULT_RATE_LIMIT 環境変数（例：「10/minute」、.env.example を参照）で設定できます。制限を超えると、429 Too Many Requests エラーが返されます。

• リソース：データベーススキーマ
  • URI： vast://schemas
  • 説明： 検出されたすべてのテーブルとその列（名前と型）を説明する、整形済み文字列を返します。認証ヘッダーが必要です。
  • エラー処理： エラーステータスコード（UNAUTHENTICATED、SERVICE_UNAVAILABLE、INTERNAL_SERVER_ERROR）とプレーンテキストのエラーメッセージ本文（ERROR: [ErrorType] Message）を含む McpResponse を返します。
• リソース：テーブル一覧
  • URI： vast://tables?format=FMT
  • 説明： 利用可能なテーブル名の一覧を返します。認証ヘッダーが必要です。
  • パラメーター：
    • format（文字列、省略可、デフォルト：json）：出力形式（json または csv/'list'）。csv または list の場合は、改行区切りの文字列を返します。
  • 形式： 文字列の JSON 配列、または改行区切りのリスト。
  • エラー処理： エラーステータスコード（UNAUTHENTICATED、BAD_REQUEST、SERVICE_UNAVAILABLE、INTERNAL_SERVER_ERROR）と、形式に応じてフォーマットされたエラー本文（JSON またはプレーンテキスト）を含む McpResponse を返します。
• リソース：テーブルメタデータ
  • URI： vast://metadata/tables/{table_name}
  • 説明： 特定のテーブルの詳細なメタデータを返します。認証ヘッダーが必要です。列名、データ型、NULL 許容性（is_nullable：例 'YES'／'NO'）、キー情報（key：例 'PRI'）、デフォルト値（default）を含めるよう試みます。名前／型以外のフィールドは、データベースのイントロスペクションで取得できない場合、null になることがあります。
  • 形式： table_name（文字列）と columns（オブジェクトのリスト。各オブジェクトには name、type、is_nullable、key、default のキーが含まれる場合があります）を含む JSON オブジェクト。
  • 応答例（拡張版）：

    {
      "table_name": "my_table",
      "columns": [
        {
          "name": "id",
          "type": "INTEGER",
          "is_nullable": "NO",
          "key": "PRI",
          "default": null
        },
        {
          "name": "data_column",
          "type": "VARCHAR",
          "is_nullable": "YES",
          "key": "",
          "default": "'Default Text'"
        },
        {
          "name": "timestamp",
          "type": "TIMESTAMP",
          "is_nullable": "YES",
          "key": null,
          "default": null
        }
      ]
    }
    

  • エラー処理： エラーステータスコード（UNAUTHENTICATED、NOT_FOUND、BAD_REQUEST、SERVICE_UNAVAILABLE、INTERNAL_SERVER_ERROR）と JSON エラー本文（{\"error\": ...}）を含む McpResponse を返します。
• リソース：テーブルのサンプルデータ
  • URI： vast://tables/{table_name}?limit=N&format=FMT
  • 説明： 指定された table_name のデータサンプルを返します。認証ヘッダーが必要です。
  • パラメーター：
    • limit（整数、省略可、デフォルト：10）：行数の上限。
    • format（文字列、省略可、デフォルト：csv）：出力形式（csv または json）。
  • 形式： CSV または JSON 文字列（オブジェクトの配列）。CSV の場合はヘッダー行を含みます。
  • エラー処理： エラーステータスコード（UNAUTHENTICATED、BAD_REQUEST、SERVICE_UNAVAILABLE、INTERNAL_SERVER_ERROR）と、形式に応じてフォーマットされたエラー本文（JSON またはプレーンテキスト）を含む McpResponse を返します。
• ツール：SQL クエリー実行ツール
  • 名前： vast_sql_query
  • 引数：
    • sql（文字列、必須）：実行する SQL クエリー。
    • format（文字列、省略可、デフォルト：csv）：出力形式（csv または json）。
    • headers（辞書、必須）：リクエストヘッダーを含む辞書。X-Vast-Access-Key と X-Vast-Secret-Key を含める必要があります。
  • 説明： headers 引数の認証情報を使用して、指定された SQL クエリーを VAST DB に対して実行します。
  • 形式： 結果を CSV または JSON 文字列（オブジェクトの配列）、またはエラーメッセージ文字列（形式に応じて JSON またはプレーンテキスト）として返します。
  • 安全性： 許可するステートメントの種類は MCP_ALLOWED_SQL_TYPES 環境変数で制御されます（デフォルトは SELECT）。
  • エラー処理： 失敗時は、フォーマットされたエラー文字列（JSON またはプレーンテキスト）を返します。エラーには、ヘッダーの欠落／無効（AuthenticationError）、許可されていないクエリーの種類（InvalidInputError）、接続の問題（DatabaseConnectionError）、クエリー実行時の問題（QueryExecutionError）が含まれます。

AI エージェントとの連携に関する注意事項

この MCP サーバーを AI エージェントのフレームワーク（例：LangChain、LlamaIndex、カスタムエージェント）と連携する際は、次の点を考慮してください。

1. エージェントのプロンプト／設定：

   • エージェントのシステムプロンプトまたは設定には、利用可能なリソースとツールの説明（上記の「実装済みの MCP 機能」セクションと同様のもの）を含める必要があります。これにより、ユーザーの要求に応じて LLM が適切なアクションを選択できます。
   • MCP には標準のディスカバリー機能がないため、URI（vast://schemas、vast://tables?...、vast://metadata/tables/{name}、vast://tables/{name}?....）とツール名（vast_sql_query）、およびそれらの機能を明示的に列挙してください。

2. 認証情報の取り扱い（セキュリティ上重要）：

   • VAST DB の認証情報（access_key、secret_key）を、LLM に送信するプロンプトに絶対に含めないでください。
   • 認証情報の管理は、エージェントのオーケストレーター（LLM ではなく、エージェントのロジックを実行するコード）の責任です。
   • クライアント側で、環境変数や Vault／AWS／Azure／GCP Secrets Manager などのシークレットマネージャーを使って認証情報を安全に読み込んでください。
   • リソースの場合： LLM が対象 URI を生成したら、オーケストレーターは次の処理を行う必要があります。
     • 保存済みの認証情報を取得します。
     • headers ディクショナリを構築します：{'X-Vast-Access-Key': '...', 'X-Vast-Secret-Key': '...'}。
     • vast:// URI スキームを、実行中の MCP サーバーの実際の HTTP URL（例：http://localhost:8088/）に対応付けます。
     • 構築した headers を渡し、MCP クライアントまたは標準の HTTP クライアントを使って HTTP GET リクエストを送信します。
   • ツールの場合： LLM が vast_sql_query ツールを使用し、sql と format の引数を指定したら、オーケストレーターは次の処理を行う必要があります。
     • 保存済みの認証情報を取得します。
     • 上記のとおり headers ディクショナリを構築します。
     • この headers ディクショナリを、ツール実行関数に渡す引数に注入します。LLM が headers 引数自体を生成してはなりません。

3. リクエストの構築：

   • リソースの場合、LLM は正しい URI パスパラメーター（{table_name}）とクエリパラメーター（?format=、?limit=）を生成する必要があります。
   • LLM は vast_sql_query ツールの sql と format の引数を生成します。

4. レスポンスの処理：

   • クライアント側のエージェントコードは、さまざまなレスポンスの Content-Type（例：text/plain、application/json、text/csv）を処理する必要があります。
   • エラーを検出できるように、レスポンスのステータスコード（特にリソースの場合）を確認する必要があります（例：401、404、500、503）。
   • レスポンス本文（プレーンテキストまたは JSON）からエラーメッセージを解析し、必要に応じてユーザーに報告したり、再試行や別のアクションに利用したりする必要があります。

今後の候補

• 堅牢なログ記録を実装する。（完了）
• ユニットテストを追加する。（完了）
• 出力形式を改善する（例：CSV に加えて JSON も提供する）。（完了）
• エラー処理と報告を強化する。（完了 — 基本的なカスタム例外とフォーマット処理を追加）
• より細分化されたリソース／ツールを追加する（例：テーブルのみの一覧表示、テーブルメタデータの取得）。（完了 — テーブル一覧、テーブルメタデータ）
• vast_sql_query ツールのクエリ検証／サンドボックス化をより高度にする。（完了 — sqlparse を使用）
• クエリの制限（例：SELECT 以外の許可）を設定可能にする。（完了 — MCP_ALLOWED_SQL_TYPES env var を使用）
• 実行中の VAST DB インスタンスまたはモックサーバーを必要とする統合テストを追加する。（完了 — 現在のすべてのリソース／ツールに ASGI／モックテストを追加）
• 必要に応じて認証／認可レイヤーの追加を検討する。（完了 — ヘッダーベースの認証）
• 共通コード（例：extract_auth_headers、フォーマッター）を utils.py にリファクタリングする。（完了）
• レート制限を実装する。（完了 — ハンドラーで slowapi を使った IP ベースの制限）

実行方法

1. リポジトリをクローンします（まだの場合）。
2. 環境を設定します： .env.example を .env にコピーし、VAST DB のエンドポイント、アクセスキー、シークレットキーを入力します。

   cp .env.example .env
   # .env に詳細を記入します
   

3. 依存関係をインストールします： 仮想環境の使用を推奨します。