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），并尽量减少变更。

基于文件的流水线（仅传递路径）

将数据库操作集成到多步骤工作流时，请将所有上下文和产物持久化到磁盘，Agent／子 Agent 之间仅传递路径。

建议目录结构（位于项目内）：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"}	获取安全／性能建议

可选工具（若已启用）：

• Edge Functions：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 为准。