PromptQL MCP Server

PromptQL MCP サーバー

ステータス：不安定で、PromptQL v1 専用です。PromptQL v2 向けのアルファ版は近日公開予定です。

概要

このプロジェクトは、Model Context Protocol を通じて、Hasura の PromptQL データエージェントと AI アシスタントをつなぐブリッジを提供します。この連携により、AI アシスタントは PromptQL の強力なデータアクセス、分析、可視化機能を活用し、自然言語でエンタープライズデータに直接クエリを実行できます。

機能

• 🔍 自然言語によるデータクエリ - エンタープライズデータについて、平易な英語で質問できます
• 📊 テーブルアーティファクトのサポート - データクエリの結果を整形されたテーブルで取得できます
• 🔐 安全な設定 - PromptQL API 認証情報を安全に保存、管理できます
• 🔑 2 種類の認証モード - パブリックおよびプライベートの両方の DDN デプロイメントをサポートします
• 📈 データ分析 - データからインサイトや可視化を得られます
• 🛠️ シンプルな連携 - Claude Desktop やその他の MCP 対応クライアントで動作します

認証モード

PromptQL MCP サーバーは、異なる種類の DDN デプロイメントに対応するため、2 種類の認証モードをサポートしています。

パブリックモード（デフォルト）

• 認証に Auth-Token ヘッダーを使用します
• パブリック DDN エンドポイントに対応しています
• 既存の設定との後方互換性があります
• 使用する場合：DDN デプロイメントがパブリックにアクセス可能な場合

プライベートモード

• 認証に x-hasura-ddn-token ヘッダーを使用します
• プライベート DDN エンドポイントに対応しています
• プライベートなデプロイメントのセキュリティを強化します
• 使用する場合：DDN デプロイメントがプライベートまたは内部向けの場合

設定時に --auth-mode フラグまたは auth_mode パラメーターを使用して、認証モードを指定できます。

インストール

前提条件

• Python 3.10 以降
• API キー、プレイグラウンド URL、DDN Auth Token を備えた Hasura PromptQL プロジェクト
• Claude Desktop（対話形式で使用する場合）、または MCP 対応クライアント

ソースからインストール

1. リポジトリをクローンします。

git clone https://github.com/hasura/promptql-mcp.git
cd promptql-mcp

2. 仮想環境をセットアップします（推奨）。

# Create a virtual environment
python -m venv venv

# Activate the virtual environment
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. パッケージをインストールします。

pip install -e .

クイックスタート

1. PromptQL の認証情報を設定します。

# For public DDN deployments (default)
python -m promptql_mcp_server setup --api-key YOUR_PROMPTQL_API_KEY --playground-url YOUR_PLAYGROUND_URL --auth-token YOUR_AUTH_TOKEN --auth-mode public

# For private DDN deployments
python -m promptql_mcp_server setup --api-key YOUR_PROMPTQL_API_KEY --playground-url YOUR_PLAYGROUND_URL --auth-token YOUR_AUTH_TOKEN --auth-mode private

別の方法：環境変数

export PROMPTQL_API_KEY="your-api-key"
export PROMPTQL_PLAYGROUND_URL="your-playground-url"
export PROMPTQL_AUTH_TOKEN="your-auth-token"
export PROMPTQL_AUTH_MODE="public"  # or "private"

2. サーバーをテストします。

python -m promptql_mcp_server

3. 新しいターミナルを開き、サンプルクライアントを試します。

python examples/simple_client.py

Claude Desktop での使用

1. Claude Desktop をインストールします
2. Claude Desktop を開き、「Settings」>「Developer」に移動します
3. 「Edit Config」をクリックし、以下を追加します。

{
  "mcpServers": {
    "promptql": {
      "command": "/full/path/to/python",
      "args": ["-m", "promptql_mcp_server"]
    }
  }
}

/full/path/to/python を、Python 実行ファイルの実際のパスに置き換えてください。

仮想環境を使用している場合（推奨）：

{
  "mcpServers": {
    "promptql": {
      "command": "/path/to/your/project/venv/bin/python",
      "args": ["-m", "promptql_mcp_server"]
    }
  }
}

別の方法：Claude Desktop で環境変数を使用する

{
  "mcpServers": {
    "promptql": {
      "command": "/full/path/to/python",
      "args": ["-m", "promptql_mcp_server"],
      "env": {
        "PROMPTQL_API_KEY": "your-api-key",
        "PROMPTQL_PLAYGROUND_URL": "your-playground-url",
        "PROMPTQL_AUTH_TOKEN": "your-auth-token",
        "PROMPTQL_AUTH_MODE": "public"
      }
    }
  }
}

Python のパスを確認するには、次のコマンドを実行します。

which python  # On macOS/Linux
where python  # On Windows

4. Claude Desktop を再起動します
5. Claude とチャットし、自然言語でデータにクエリを実行します

Claude 向けのプロンプト例

• 「前四半期の売上合計はいくらでしたか？」
• 「売上高上位 5 社の顧客は誰ですか？」
• 「過去 6 か月間の新規ユーザー登録数の推移を見せてください」
• 「利益率が最も高い製品はどれですか？」

利用可能なツールとプロンプト

ツール

サーバーは以下の MCP ツールを公開します。

スレッド管理モード

• start_thread - 初回メッセージを添えて新しい会話スレッドを開始し、完了まで待機します（thread_id、interaction_id、応答を返します）
• start_thread_without_polling - 完了を待たずに新しい会話スレッドを開始します（thread_id と interaction_id をすぐに返します）
• continue_thread - 新しいメッセージを送信して既存のスレッドを続行します（会話のコンテキストを維持します）
• get_thread_status - GET /threads/v2/{thread_id} を使用してスレッドのステータス（処理中／完了）を確認します
• cancel_thread - スレッド内の最新のやり取りの処理をキャンセルします

設定

• setup_config - PromptQL API キー、プレイグラウンド URL、DDN Auth Token、認証モード（パブリック／プライベート）を設定します
• check_config - 認証モードを含む現在の設定状態を確認します

使用例

マルチターン会話モード

オプション 1：ポーリングを開始する（即時応答を取得）

# Start a new conversation thread (waits for completion and returns full response)
thread_result = await client.call_tool("start_thread", {
    "message": "What tables are available in my database?"
})

# Extract thread_id from result (format: "Thread ID: abc-123\nInteraction ID: def-456\n\n[response content]")
thread_id = thread_result.split("Thread ID: ")[1].split("\n")[0].strip()

# Continue the conversation with context
result = await client.call_tool("continue_thread", {
    "thread_id": thread_id,
    "message": "Show me the schema of the users table"
})

オプション 2：ポーリングを開始しない（別途ステータスを確認）

# Start a new conversation thread (returns immediately with thread_id)
thread_result = await client.call_tool("start_thread_without_polling", {
    "message": "What tables are available in my database?"
})

# Extract thread_id from result (format: "Thread ID: abc-123\nInteraction ID: def-456\n\n...")
thread_id = thread_result.split("Thread ID: ")[1].split("\n")[0].strip()

# Check status manually
status_result = await client.call_tool("get_thread_status", {
    "thread_id": thread_id
})

# Continue when ready
result = await client.call_tool("continue_thread", {
    "thread_id": thread_id,
    "message": "Show me the schema of the users table"
})

# Continue further
result = await client.call_tool("continue_thread", {
    "thread_id": thread_id,
    "message": "How many records are in that table?"
})

# Check thread status
status = await client.call_tool("get_thread_status", {
    "thread_id": thread_id
})

# Cancel thread processing (if currently processing)
cancel_result = await client.call_tool("cancel_thread", {
    "thread_id": thread_id
})

システム指示を使用する場合

# Start thread with system instructions
result = await client.call_tool("start_thread", {
    "message": "Show me the top 10 products by revenue",
    "system_instructions": "Format all results as markdown tables"
})

設定例

認証モードの設定

パブリックモードの設定（デフォルト）

# Using MCP tool
result = await client.call_tool("setup_config", {
    "api_key": "your-api-key",
    "playground_url": "https://promptql.your-domain.public-ddn.hasura.app/playground",
    "auth_token": "your-auth-token",
    "auth_mode": "public"
})

プライベートモードの設定

# Using MCP tool
result = await client.call_tool("setup_config", {
    "api_key": "your-api-key",
    "playground_url": "https://promptql.your-domain.private-ddn.hasura.app/playground",
    "auth_token": "your-auth-token",
    "auth_mode": "private"
})

現在の設定の確認

# Check what authentication mode is currently configured
config_result = await client.call_tool("check_config", {})
# Returns configuration details including auth_mode

プロンプト

• data_analysis - 特定のトピックについてデータ分析を行うための専用プロンプトを作成します

アーキテクチャ

この統合はクライアント・サーバーアーキテクチャに従っています。

1. PromptQL MCP Server - MCP プロトコルを通じて PromptQL の機能を公開する Python サーバーです
2. MCP Client - MCP プロトコルを実装する任意のクライアントです（例：Claude Desktop）
3. PromptQL API - データアクセスと分析のための Hasura の自然言語 API です

サーバーは MCP プロトコルと PromptQL の API の間を変換し、AI アシスタントとエンタープライズデータのシームレスな統合を可能にします。

トラブルシューティング

コマンドが見つかりません：pip または python

多くのシステム、特に macOS では、python と pip の代わりに python3 と pip3 を使用する必要がある場合があります。

externally-managed-environment エラー

最新の Python インストール環境では、グローバルなパッケージのインストールが禁止されていることがよくあります。インストールのセクションで説明されているように、仮想環境を使用してください。

No module named promptql_mcp_server

以下を確認してください。

1. pip install -e . でパッケージをインストールしている
2. 正しい Python 環境を使用している（仮想環境を使用している場合は、有効化されていることを確認してください）
3. Claude Desktop が正しい Python 実行ファイルのパスを使用するように設定されている

Python のバージョンに関する問題

複数の Python バージョンがインストールされている場合は、Python 3.10 以降を使用していることを確認してください。

python3.10 -m venv venv  # Specify the exact version

認証に関する問題

認証モードが正しくありません

認証エラーが発生する場合は、正しい認証モードを使用していることを確認してください。

• パブリック DDN デプロイメント：--auth-mode public を使用します（デフォルト）
• プライベート DDN デプロイメント：--auth-mode private を使用します

現在の設定を確認してください。

python -m promptql_mcp_server
# Then use check_config tool to see current auth_mode

認証モードの切り替え

認証モードを切り替えるには、再設定してください。

# Switch to private mode
python -m promptql_mcp_server setup --api-key YOUR_API_KEY --playground-url YOUR_URL --auth-token YOUR_TOKEN --auth-mode private

# Switch back to public mode
python -m promptql_mcp_server setup --api-key YOUR_API_KEY --playground-url YOUR_URL --auth-token YOUR_TOKEN --auth-mode public

開発

プロジェクト構成

promptql-mcp/
├── promptql_mcp_server/     # Main package
│   ├── __init__.py
│   ├── __main__.py          # Entry point
│   ├── server.py            # MCP server implementation
│   ├── config.py            # Configuration management
│   └── api/                 # API clients
│       ├── __init__.py
│       └── promptql_client.py # PromptQL API client
├── examples/                # Example clients
│   └── simple_client.py     # Simple MCP client
├── setup.py                 # Package configuration
└── README.md                # Documentation

コントリビューション

コントリビューションを歓迎します。お気軽にプルリクエストを送信してください。

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add some amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. プルリクエストを作成します

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細は LICENSE ファイルをご覧ください。

謝辞

• PromptQL を作成した Hasura に感謝します
• Model Context Protocol を開発した Anthropic に感謝します

TODO

• 現時点では最新の interaction_id のみを参照しているため、mcp_server の continue_thread と start_thread の一部として返される interaction_id に基づいて、スレッドの応答を適切に処理する
• interaction_response を適切に処理し、コード、プラン、code_output を特定する
• simple_client.py で cancellation_thread のデモが適切に表示されるようにする。現在のステータス呼び出しはブロッキングしているように見える
• アーティファクトが適切に処理されるか検証する