WoWSQL

WoWSQL MCP（Model Context Protocol）

WoWSQL API 上で、OAuth 2.0 認可コード + PKCE を使用する wowsql スタイルの HTTP MCP です。

パッケージ

パッケージ	説明
packages/mcp-server-wowsql	@wowsql/mcp-server-wowsql — HTTP MCP サーバー、AI SDK 用の createToolSchemas()

クイックスタート（セルフホスト可能な MCP プロセス）

リポジトリのルートから実行します。

cd mcp
npm install
npm run build
npm start

認証（OAuth 2.0 + MCP）

MCP プロセスは認可サーバーではなく、OAuth で保護されたリソースです。

1. POST /mcp では、MCP_ALLOW_UNAUTHENTICATED=true（開発時のみ）でない限り、Authorization: Bearer <access_token> が必要です。
2. トークンがない、または無効な場合は、WWW-Authenticate: Bearer ... resource_metadata="<url>" を伴う 401 が返され、MCP クライアント（Cursor など）が OAuth を開始できます。
3. トークンの検証では、同じ Bearer トークンを使用して API に GET {WOWSQL_API_BASE}/api/v1/auth/me を呼び出します（WoWSQL OAuth またはログインによって発行された JWT と一致する必要があります）。
4. ディスカバリー
   • 認可サーバーのメタデータ（WoWSQL API）：GET {WOWSQL_API_BASE}/.well-known/oauth-authorization-server
   • 保護されたリソースのメタデータ（この MCP ホスト）：GET /.well-known/oauth-protected-resource/mcp

Cursor / Electron： OAuth メタデータは書き換えられ、authorization_endpoint、token_endpoint、registration_endpoint がこの MCP ホスト（例：http://localhost:8787/...）を指すようになります。MCP プロセスはこれらのリクエストを WOWSQL_API_BASE にプロキシするため、OAuth のために IDE から localhost:8000 へ直接 fetch できる必要はありません（この問題は fetch failed と表示されることがよくあります）。プロキシが接続できるよう、WOWSQL_API_BASE で FastAPI が実行中である必要があります。

MCP_PUBLIC_URL が未設定の場合、PRM と 401 の resource_metadata は、各リクエストの Host（および X-Forwarded-Proto）から導出されます。そのため、http://localhost:8787/mcp と http://127.0.0.1:8787/mcp には、それぞれ対応するメタデータが返されます。MCP がリバースプロキシの背後にある場合、または本番環境で固定のオリジンが必要な場合は、MCP_PUBLIC_URL を設定してください。

変数	デフォルト	用途
WOWSQL_API_BASE	https://api.wowsql.com	WoWSQL FastAPI のベース URL（末尾のスラッシュなし）。
WOWSQL_OAUTH_ISSUER_URL	WOWSQL_API_BASE と同じ	PRM の authorization_servers で公開される issuer。
MCP_PUBLIC_URL	未設定	設定すると、OAuth PRM と WWW-Authenticate 用の固定パブリックオリジン（/mcp パスなし）になります。Host からの導出より優先されます。
MCP_ALLOW_UNAUTHENTICATED	未設定	true の場合、Bearer のチェックをスキップします（安全ではありません。ローカルテストのみ）。
PORT / MCP_PORT	8787	MCP の HTTP ポート。
MCP_HOST	0.0.0.0	バインドアドレス。

オプション A — .env / .env.local（推奨）
packages/mcp-server-wowsql/.env.example を、そのフォルダー内の .env または .env.local にコピーします。CLI は .env、次に .env.local（上書き）、その後にプロセスの cwd にある .env を読み込みます。コミットせずにマシン固有の値（例：http://localhost:8000）を設定する場合は、.env.local を使用してください。

cd mcp/packages/mcp-server-wowsql
cp .env.example .env
# edit .env — set WOWSQL_API_BASE to your API
npm run build   # from mcp root: npm run build -w @wowsql/mcp-server-wowsql
npm start

オプション B — シェル（ファイルなし）

PowerShell：

cd mcp
$env:WOWSQL_API_BASE="http://localhost:8005"
$env:PORT="8787"
npm start

bash / zsh：

cd mcp
export WOWSQL_API_BASE=http://localhost:8005
export PORT=8787
npm start

エンドポイント

• MCP（ストリーミング可能な HTTP）： POST http://localhost:8787/mcp — JSON-RPC の本文を指定します。スコープを指定するには、クエリパラメーターを追加します。MCP クライアント（Cursor など）はこれを使用します。
• MCP（ブラウザー）： GET http://localhost:8787/mcp は、簡潔な「not authorized」ページ（パブリックメタデータなし）とともに 401 を返します。プロトコルでは、Authorization: Bearer を指定した POST JSON-RPC を使用します。
• ヘルスチェック： GET http://localhost:8787/health

クライアント用のスコープ指定 URL の例：

http://localhost:8787/mcp?project_ref=<uuid-or-slug>&read_only=true&features=database,docs

OAuth（API）

• メタデータ：GET https://api.wowsql.com/.well-known/oauth-authorization-server
• 認可（ダッシュボードへリダイレクト）：GET /api/v1/auth/oauth/mcp/authorize
• 承認（ログイン済みユーザー）：POST /api/v1/auth/oauth/mcp/approve
• トークン：POST /api/v1/auth/oauth/mcp/token（grant_type=authorization_code または refresh_token）

ダッシュボードの同意 UI：アプリの /mcp/oauth（dashboard/app/mcp/oauth/page.tsx を参照）。

mcp.wowsql.com をデプロイする

1. この Node サービスを TLS の背後で実行します（リバースプロキシまたは任意のプラットフォームを使用します）。
2. WOWSQL_API_BASE / WOWSQL_OAUTH_ISSUER_URL を https://api.wowsql.com に設定します（127.0.0.1:8000/8001 ではありません）。ブルー／グリーンの切り替えではバックエンドのホストポートが変わります。公開ホスト名は常に NPM 経由でアクティブなスロットに接続されます。
3. MCP_PUBLIC_URL=https://mcp.wowsql.com を設定します。
4. DNS の mcp.wowsql.com をサービスに向けます。ヘルスチェック：GET /health。
5. CORS と OAuth の redirect_uri に、MCP クライアントのコールバックが含まれていることを確認します（oauth_clients のシードデータと環境変数を参照）。

EC2 のブルー／グリーンデプロイ：./deploy/ec2-blue-green.sh mcp を実行すると、これらの環境変数が自動的に設定されます。

npm に公開する

cd mcp/packages/mcp-server-wowsql
npm version patch
npm publish --access public

npm の組織スコープ @wowsql が必要です（または package.json の name を変更してください）。