mcp-supabase

Supabase MCP スキル

MCP ツールを使って Supabase データベースを操作し、クエリ、書き込み、マイグレーション、診断を実行します。

対象範囲

対象となるケース：

• Supabase で「データベース操作」を行う必要がある場合：クエリ／統計／エクスポート、書き込み（確認後）、マイグレーション（DDL）、型生成、クエリログ／アドバイザー

対象とならないケース：

• Next.js プロジェクトで「統合の実装」（環境変数／クライアントコード／最小限のデータアクセスレイヤー／プロジェクト構成）を完了する必要がある場合
  → プロジェクト側のセットアップには workflow-ship-faster（ステップ 6：Supabase 統合）を使用してください。このスキルが扱うのは、データベース側の操作とゲートのみです。

呼び出し元：

• workflow-ship-faster はこのスキルをデータベース操作の基盤として使用します。プロジェクト側の統合は workflow-ship-faster が、データベース側の操作とセキュリティゲートはこのスキルが担当します。

Postgres のベストプラクティス（同梱）

Ship Faster は、Supabase の Postgres ベストプラクティスを supabase スキルに同梱しています（これらのリファレンスをローカルで利用する場合は、このスキルと一緒に supabase をインストールしてください）。

• ガイド全体：supabase/references/postgres-best-practices/AGENTS.md
• 個別のルール：supabase/references/postgres-best-practices/rules/*.md

次の場合に参照してください：

• SQL クエリの作成／レビュー／最適化
• インデックス、スキーマの変更、RLS ポリシーの設計
• パフォーマンス、ロック、接続の問題の診断

変更を提案する際は、該当するルールファイルのパス（例：supabase/references/postgres-best-practices/rules/query-missing-indexes.md）を明記し、変更は最小限にしてください。

ファイルベースのパイプライン（パスのみを渡す）

複数ステップのワークフローにデータベース操作を組み込む場合は、すべてのコンテキストと成果物をディスクに保存し、エージェント／サブエージェント間ではパスのみを渡してください。

推奨ディレクトリ構成（プロジェクト内）：runs/<workflow>/active/<run_id>/

• 入力：01-input/goal.md（要件）、01-input/context.json（既知のテーブル／フィールド／ID）
• 計画：03-plans/sql.md（実行する SQL。書き込み操作は確認前にここへ記述してください）
• 出力：05-final/result.md（結論＋主要な数値＋SQL＋省略した結果）
• ログ：logs/events.jsonl（各ツール呼び出しの概要。機密性の高いフィールド値は記録しないでください）

ツールリファレンス

ツール	パラメーター	用途
list_tables	{"schemas":["public"]}	指定したスキーマの全テーブルを一覧表示
execute_sql	{"query":"SELECT ..."}	SQL を実行（クエリまたは DML）
apply_migration	{"name":"snake_case_name","query":"-- DDL"}	データベースのマイグレーションを適用
list_migrations	{}	既存のマイグレーションを表示
generate_typescript_types	{}	TypeScript 型定義を生成
get_project_url	{}	プロジェクト URL を取得
get_publishable_keys	{}	公開 API キーを取得
get_logs	{"service":"postgres|api|auth|storage|realtime|edge-function|branch-action"}	サービスログを照会
get_advisors	{"type":"security|performance"}	セキュリティ／パフォーマンスに関する推奨事項を取得

オプションのツール（有効な場合）：

• エッジ関数：list_edge_functions、get_edge_function、deploy_edge_function
• ブランチ：create_branch、list_branches、merge_branch、reset_branch、rebase_branch、delete_branch

セキュリティルール（必ず遵守）

1. 最初に確認：操作の前に、必ずスキーマを確認します
2. デフォルトの LIMIT は 50：すべての SELECT クエリは、ユーザーが明示的にそれ以上を要求しない限り、デフォルトで LIMIT 50 を設定します
3. 書き込み操作の確認：INSERT/UPDATE/DELETE は実行前に、以下を行う必要があります：
   • 実行する SQL を表示する
   • 影響を受けると予想される行数を明示する
   • ユーザーからの明示的な確認を待つ
4. 条件なしの書き込みは禁止：WHERE 条件のない UPDATE/DELETE は、実行を拒否し、実行しません
5. バッチ処理のしきい値：100 行を超える行に影響する場合は、必ず二重確認を行い、先に SELECT count(*) を実行するよう提案します
6. DDL はマイグレーション経由：スキーマの変更には apply_migration を使用する必要があります。execute_sql では DDL を直接実行できません
7. 本番環境：書き込みはデフォルトで無効です。ユーザーが「execute on prod」と明示し、二重確認した場合にのみ許可します
8. 機密フィールド：email/phone/token/password は、ユーザーが明示的に要求しない限り、デフォルトでマスキングするか返しません

操作フロー

1. Parse requirements → restate objective
2. Unsure about tables/fields → first list_tables or execute_sql to query information_schema
3. Plan SQL → present to user
4. Read-only → execute directly
5. Write operation → confirm before execution → verify affected rows → report result

出力形式

• 言語：英語
• 構成：結論 → 主要な数値 → 実行した SQL → 結果テーブル（最大 50 行）
• 上限超過時の処理：切り捨てて、全件数を表示し、必要に応じてエクスポート／ページネーションを提供します

出力例：

✅ Query complete: 142 new users in the last 7 days

Executed SQL:
SELECT DATE(created_at) as date, COUNT(*) as count 
FROM user_profiles 
WHERE created_at > NOW() - INTERVAL '7 days'
GROUP BY DATE(created_at) ORDER BY date DESC;

| date       | count |
|------------|-------|
| 2025-01-09 | 23    |
| 2025-01-08 | 31    |
| ...        | ...   |

エラー処理

状況	対応
SQL 構文エラー	エラーの概要と修正案を返します
権限不足	必要な権限と代替手段を説明します
データが返されない	考えられる理由（条件が厳しすぎるか、データが存在しないかなど）を説明します
RLS によってブロックされた	RLS ポリシーを確認するか、service_role を使用するよう提案します

対話例

読み取り：シンプルなクエリ

User: Get registered user count for the last 7 days, by day
Execution:
1. Confirm table user_profiles, field created_at
2. Execute aggregation SQL
3. Return: conclusion + numbers + SQL + table

読み取り：複雑なクエリ

User: Find projects that have runs but all failed
Execution:
1. Confirm projects, runs tables and status field
2. Present JOIN + aggregation SQL
3. Execute and return results (mask email)

書き込み：挿入

User: Create a new run for project xxx
Execution:
1. First check if project exists
2. Present INSERT SQL + expected impact: 1 row
3. Await confirmation → execute → return new record id

書き込み：更新

User: Change run abc's status to completed
Execution:
1. First SELECT to verify current state
2. Present UPDATE SQL + WHERE id = 'abc'
3. Confirm → execute → SELECT again to verify

危険：削除

User: Delete all runs where status = 'failed'
Execution:
1. First SELECT count(*) WHERE status = 'failed'
2. Present count + DELETE SQL
3. If > 100 rows, force double confirmation
4. After confirmation execute → report deleted row count

危険：WHERE 句なしの DELETE

User: Clear the runs table
Execution:
❌ Refuse to execute
→ Prompt: DELETE without WHERE condition, this will delete all data
→ Suggest: Use TRUNCATE (requires migration) or add explicit condition

スキーマの参照

実行時に最新のスキーマを取得します：

-- List all tables
SELECT table_name FROM information_schema.tables 
WHERE table_schema = 'public';

-- View table structure
SELECT column_name, data_type, is_nullable 
FROM information_schema.columns 
WHERE table_name = '<table_name>';

プロジェクト固有のスキーマ（古くなっている可能性があります）については、schema.md を参照してください。情報の信頼できるソースとして、information_schema／generate_typescript_types を優先してください。