PlainQuery | MCP DB Agent

PlainQuery

データベースに平易な言葉で質問できます。 PlainQuery は PostgreSQL データベースを Claude、Cursor、または VS Code に接続し、推測ではなく、実際の構造化データで回答します。

---

できること

データベースに一度接続すれば、任意の MCP クライアントから次のような質問ができます。

「3 月に出荷した注文は何件ですか？」 「昨年、最も多く支出した顧客を上位 5 件教えてください。」 「月ごとの平均注文額はいくらですか？」

PlainQuery はスキーマを調査し、LLM で SQL を生成し、安全性を検証して実行し、構造化された JSON を返します。クエリが失敗すると、エラーを読み取り、自動的に再試行します。

PlainQuery を選ぶ理由

• 自然言語で、実際の回答が得られます — SQL は不要です。結果は幻覚ではなく、実際のデータに基づいています。
• 読み取り専用で、設計上安全です — すべてのクエリは実行前にチェックされます。書き込み（INSERT／UPDATE／DELETE／DDL）はブロックされ、危険な関数やパターンは検出・除去され、LIMIT は自動的に追加されます。
• 自己修正します — 生成されたクエリでエラーが発生すると、エージェントはエラーを LLM に返して再試行します（設定可能な上限まで）。
• スキーマを認識します — スキーマを自動的に調査してキャッシュするため、質問を適切なテーブルやカラムに対応付けられます。
• あらゆる MCP クライアントで動作します — Claude Desktop、Cursor、VS Code Copilot など、MCP に対応するあらゆるクライアントで利用できます。
• 安全なマルチテナントホスティング — データベース URL と LLM キーは保存時に Fernet で暗号化されます。ユーザーが指定した接続文字列は SSRF 対策で保護され、すべてのリクエストはテナントごとに分離されます。
• ホスティング版またはセルフホスト版 — マネージドサービスを使うことも、Docker でスタック全体を自分で実行することもできます。
• お好みの LLM を利用できます — Anthropic Claude または Groq に対応しています。

動作の仕組み

Your question
   → Schema introspection      (reads tables/columns, cached)
   → SQL generation            (schema + question → LLM → SQL)
   → Safety validation         (blocks writes, scans dangerous patterns, injects LIMIT)
   → Execution                 (runs read-only, with a timeout)
   → Self-correction retry     (on error: feed it back to the LLM, fix, re-run)
   → Structured JSON result

アーキテクチャ

---

クイックスタート

オプション 1 — ホスティングサービスを利用する（インストール不要）

1. https://plainquery.in で登録し、メールアドレスを確認します。
2. PostgreSQL データベースを接続し、API キーを作成します。
3. MCP クライアントにサーバーを追加します（MCP クライアントの接続を参照）。

これで準備完了です。質問を始めましょう。

オプション 2 — 自分で実行する

以下のセルフホスティングとローカル開発を参照してください。

MCP クライアントの接続

PlainQuery は io.github.Jarvis-27/mcp-db-agent として公式 MCP レジストリに公開されているため、レジストリに対応したクライアントから直接検出できます。

クライアントを手動で設定するには、MCP エンドポイントを指定し、API キーを渡します。

{
  "mcpServers": {
    "plainquery": {
      "url": "https://plainquery.in/mcp",
      "headers": { "X-API-Key": "mdbk_your_key_here" }
    }
  }
}

バックエンドは、VS Code、Cursor、および汎用 HTTP クライアント向けの設定を生成することもできます。POST /api/v1/account/setup-payloads を呼び出してください（セットアップ用ペイロードを参照）。MCP クライアントは、MCP_AUTH_MODE に応じて OAuth 2.1 ベアラートークンまたは API キーで認証できます。

---

セルフホスティングとローカル開発

前提条件

• Python 3.12+
• uv
• フロントエンド用の Node.js 20+ と pnpm
• 少なくとも 1 つの LLM API キー（ANTHROPIC_API_KEY または GROQ_API_KEY）

バックエンド

uv sync
cp .env.example .env

.env を編集し、少なくとも次の値を設定します。

• CREDENTIAL_ENCRYPTION_KEYS
• REGISTRATION_OPEN=true
• LLM プロバイダーキーを 1 つと LLM_PROVIDER

バックエンドを起動します。

uv run uvicorn src.app:app --reload --host 0.0.0.0 --port 8000

バックエンドは次のエンドポイントをマウントします。

• REST API：http://localhost:8000/api
• MCP エンドポイント：http://localhost:8000/mcp

フロントエンド

cd frontend
pnpm install
pnpm dev

http://localhost:3000 を開き、サインアップしてセットアップを完了し、アカウント設定から OAuth ID を連携します。その後、http://localhost:8000/mcp で MCP クライアントを接続します。クライアントは OAuth フローを自動的に完了します。または、api_key_only／hybrid モードで API キーを使用できます。

実行時の構成

• バックエンド API：src.app:app の FastAPI/Starlette
• フロントエンド：frontend/ 内の Next.js アプリ
• 認証：パスワード不要のメール認証とログインリンク
• MCP 認証：OAuth 2.1 ベアラートークン（oauth_only）、API キー（api_key_only）、または両方（hybrid）。MCP_AUTH_MODE で設定します。
• セットアップペイロード：POST /api/v1/account/setup-payloads
• 請求：Stripe Checkout、Customer Portal、および Webhook で確定される Free/Pro の利用権

製品モデルは、単一アカウントでユーザー単位です。 signup → verify email → connect database → link OAuth identity → use /mcp → upgrade with Stripe

セキュリティ

• ユーザーが指定したデータベース URL は、接続を試みる前に SSRF、パストラバーサル、プライベート IP、DNS リバインディングに対して検証されます。
• データベース URL と LLM キーは、キーローテーションに対応した Fernet で保存時に暗号化されます。
• 生成された SQL は実行前に検証されます。単一ステートメントのチェック、禁止関数のスキャン、危険なパターンのスキャン、書き込み／DDL のブロック、テーブルの存在確認、自動的な LIMIT の挿入が行われます。
• リクエスト単位のコンテキストスコープにより、テナント間のデータ漏えいを防ぎます。
• ユーザー単位のレート制限とフォールバック LLM のクォータにより、コストの不正使用を抑制します。

重要な環境変数

変数	説明
AUTH_DATABASE_URL	ホスト型製品で使用する認証／アカウントデータベース
CREDENTIAL_ENCRYPTION_KEYS	保存されたデータベース URL やその他のシークレットを暗号化します
REGISTRATION_OPEN	一般向けサインアップの有効／無効を切り替えます
ANTHROPIC_API_KEY / GROQ_API_KEY	SQL 生成に使用する LLM の認証情報
LLM_PROVIDER	アクティブなプロバイダー名
APP_BASE_URL	セットアップペイロードで使用するベース URL
FRONTEND_BASE_URL	メールリンクで使用するベース URL
STRIPE_SECRET_KEY / STRIPE_WEBHOOK_SECRET	Stripe API と Webhook の認証情報
STRIPE_PRO_PRICE_ID	Pro プランに対応する Stripe Price ID
STRIPE_CHECKOUT_SUCCESS_URL / STRIPE_CHECKOUT_CANCEL_URL	Checkout のリダイレクト先を任意で上書きします
STRIPE_CUSTOMER_PORTAL_RETURN_URL	Customer Portal の戻り先 URL を任意で上書きします

現在の全項目については、.env.example を参照してください。

API の概要

認証

• POST /api/v1/auth/signup
• GET /api/v1/auth/verify-email
• POST /api/v1/auth/request-login-link
• GET /api/v1/auth/exchange-login-link
• POST /api/v1/auth/logout

アカウント（セッション認証）

アカウント関連のすべてのルートでは、セッショントークン認証を使用します（x-session-token: <session-token> または Authorization: Bearer <session-token>）。

• GET /api/v1/account
• GET /api/v1/account/status
• PUT /api/v1/account/database
• GET /api/v1/account/api-keys
• POST /api/v1/account/api-keys
• DELETE /api/v1/account/api-keys/{id}
• POST /api/v1/account/api-keys/{id}/rotate
• POST /api/v1/account/setup-payloads
• GET /api/v1/account/dashboard
• GET /api/v1/account/usage/recent

課金

• GET /api/v1/account/billing
• POST /api/v1/account/billing/checkout-session
• POST /api/v1/account/billing/portal-session
• POST /api/v1/billing/webhook

プランの移行を判断する際は、Stripe の Webhook を正とします。チェックアウトまたはサブスクリプションの有効化によって、ユーザーの plan_code=pro への移行が行われます。キャンセル、未払い、または支払い遅延の状態では、データベースの設定を削除せずに、有料の利用権限が制限されます。

OAuth MCP アカウント連携（セッション認証）

• GET /api/v1/account/mcp-oauth/status
• POST /api/v1/account/mcp-oauth/start
• GET /api/v1/account/mcp-oauth/callback
• DELETE /api/v1/account/mcp-oauth/link

MCP

• POST /mcp
• 認証：OAuth 2.1 ベアラートークン、API キー、またはその両方。MCP_AUTH_MODE で制御します。

セットアップペイロード

POST /api/v1/account/setup-payloads は、VS Code、Cursor、汎用 HTTP MCP クライアント、および現在の ChatGPT プレースホルダー向けのクライアント設定情報を返します。

curl -X POST http://localhost:8000/api/v1/account/setup-payloads \
  -H "Authorization: Bearer <session-token>" \
  -H "Content-Type: application/json" \
  -d '{"raw_api_key":"mdbk_..."}'

バックエンドは、作成後の生の API キーを保存しません。リクエストで明示的に送信した場合に限り、セットアップペイロードに生のキーが含まれます。

テスト

uv run pytest tests/ -m "not integration"
uv run pytest tests/ -m integration
uv run ruff check .
uv run mypy src --ignore-missing-imports

デプロイのスモークテスト

ホスト環境へのデプロイ後は毎回、公開されている MCP OAuth ディスカバリーのエンドポイントを確認してください。

uv run python scripts/smoke_mcp_deployment.py \
  --mcp-url https://mcp.example.com/mcp \
  --issuer-url https://YOUR_DOMAIN.auth0.com/

スモークテストでは、未認証の /mcp チャレンジ、保護されたリソースのメタデータ、ChatGPT／Claude の well-known ディスカバリールート、発行者のメタデータを確認します。認証済み MCP の initialize、tools/list、resources/list も確認するには、連携済みユーザーのアクセストークンを --access-token または MCP_SMOKE_ACCESS_TOKEN で渡します。

Docker

ホスト環境の HTTP スタックを実行します。

docker compose up --build

コンテナーイメージが提供するのは、ホスト環境の HTTP ランタイムのみです。MCP エンドポイントは引き続き http://localhost:8000/mcp です。

ライセンス

MIT © 2026 PlainQuery