Vast Db MCP

🚀 VAST データベース MCP サーバー実装説明

VAST データベースの MCP サーバーは、データベースのリソース管理や SQL クエリの実行などの機能を提供します。この README では、実装された MCP 機能特性、AI 代理フレームワークとのインタラクションにおける注意事項、次の計画、実行方法、注意事項について説明します。

✨ 主な機能

1. リソース

a. すべてのスキーマを一覧表示

• 機能: データベース内のすべてのスキーマ名を表示します。
• リクエスト方式: GET /schemas
• レスポンス形式: 文字列型のスキーマ名を含む JSON 配列

b. 指定されたスキーマ内のテーブルを一覧表示

• 機能: 提供されたスキーマ名に基づいて、そのスキーマ内のすべてのテーブル情報を一覧表示します。
• リクエスト方式: GET /schemas/{schema_name}/tables
• レスポンス形式: JSON 配列で、各要素は以下のフィールドを含みます。
  • name: テーブル名
  • type: テーブルのタイプ（例: BASE TABLE）
  • schema: テーブルが属するスキーマ名

c. テーブルのメタデータを取得

• 機能: 提供されたスキーマ名とテーブル名に基づいて、そのテーブルの詳細なメタデータを返します。
• リクエスト方式: GET /schemas/{schema_name}/tables/{table_name}
• レスポンス形式: 以下のフィールドを含む JSON オブジェクト。
  • name: テーブル名
  • type: テーブルのタイプ
  • schema: スキーマ名
  • columns: 列情報の配列で、各列オブジェクトは以下を含みます。
    • name: 列名
    • type: データ型
    • nullable: 空を許可するかどうか
    • default_value: デフォルト値（存在する場合）

d. テーブルデータを取得

• 機能: 提供されたスキーマ名とテーブル名に基づいて、そのテーブルの具体的なデータを返します。
• リクエスト方式: GET /schemas/{schema_name}/tables/{table_name}/data
• レスポンス形式: JSON 配列で、各要素は 1 行のデータに対応し、フィールドはメタデータの列情報と一致します。

2. ツール

a. クエリベースの対話型 SQL 実行ツール

• 機能: SQL クエリ文を提供することで、任意のデータベース操作を実行でき、出力形式を指定できます。
• 名称: vast_sql_query
• パラメータ:
  • sql: 実行する SQL クエリ文字列
  • format: 出力形式。json または csv が選択可能

🔧 AI 代理フレームワークとのインタラクションにおける注意事項

1. プロンプト/設定

• システムプロンプトまたは設定には、利用可能なリソースとツールの説明（「実装された MCP 特性」の部分のようなもの）を含める必要があります。
• MCP には標準的な検出メカニズムがないため、すべての URI とツール名およびその機能を明示的に列挙する必要があります。

2. 認証処理

⚠️ 重要提示

絶対に LLM に送信するプロンプトに VAST データベースの認証情報を含めないでください。

• リソースリクエスト:

  • LLM がターゲット URI を生成した後、orchestrator（LLM ではなく、エージェントロジックを実行するコード）が以下のことを行います。
    • 保存された認証情報を安全に読み込む。
    • headers 辞書を構築する: {'X-Vast-Access-Key': '...', 'X-Vast-Secret-Key': '...'}。
    • vast:// URI を実際に動作している MCP サーバーの HTTP URL（例: http://localhost:8088/）にマッピングする。
    • MCP クライアントまたは標準の HTTP クライアントを使用して、構築した headers を渡しながら GET リクエストを送信する。

• ツール使用:

  • LLM が vast_sql_query ツールを使用することを決定し、sql と format パラメータを提供した場合、orchestrator が以下のことを行います。
    • 保存された認証情報を安全に読み込む。
    • 上記の headers 辞書を構築し、ツール実行関数のパラメータに注入する。LLM は自動的に headers を生成しないでください。

3. リクエスト構築

• LLM は正しい URI パスパラメータとクエリパラメータを生成する必要があります。
• LLM はツール呼び出しに sql と format パラメータを生成する必要があります。

4. レスポンス処理

• クライアントエージェントコードは、異なるレスポンス MIME タイプ（例: text/plain, application/json, text/csv）を処理する必要があります。
• HTTP ステータスコードを必ずチェックし（特にリソースリクエストで）、エラー（例: 401, 404, 500, 503）を検出する必要があります。
• レスポンス本文からエラー情報（純テキストまたは JSON）を解析し、ユーザーに報告するか、再試行/代替操作に使用する必要があります。

📈 次の計画

• 堅牢なログ記録の実装。(完了)
• 単体テストの追加。(完了)
• 出力形式の微調整。(完了 - JSON と CSV オプションを提供)
• エラー処理メカニズムの強化。(完了)
• ドキュメントの作成とサンプルの充実。(進行中)

🚀 クイックスタート

MCP サービスの起動

uvicorn fastapi_mcp.main:app --reload

サンプルリクエスト

すべてのスキーマを取得

curl http://localhost:8000/schemas

指定されたスキーマ内のテーブルを取得

curl http://localhost:8000/schemas/my_schema/tables

テーブルのメタデータを取得

curl http://localhost:8000/schemas/my_schema/tables/my_table

テーブルデータを取得

curl http://localhost:8000/schemas/my_schema/tables/my_table/data

サンプル SQL クエリ

curl -X POST "http://localhost:8000/_api" \
     -H "Content-Type: application/json" \
     -d '{"name": "vast_sql_query", "params": {"sql": "SELECT * FROM my_table LIMIT 5", "format": "json"}}'

📄 注意事項

• すべての API リクエストには認証ヘッダーを含める必要があります。
• 機密性の高い操作には適切な権限管理とログ記録を行う必要があります。