supabase-automation

通过 Rube MCP 实现 Supabase 自动化

通过 Composio 的 Supabase 工具包，自动执行 Supabase 操作，包括数据库查询、表结构检查、SQL 执行、项目和组织管理、存储桶、边缘函数以及服务健康监控。

工具包文档：composio.dev/toolkits/supabase

前置条件

• 必须已连接 Rube MCP（可用 RUBE_SEARCH_TOOLS）
• 通过 RUBE_MANAGE_CONNECTIONS 建立有效的 Supabase 连接，工具包为 supabase
• 始终先调用 RUBE_SEARCH_TOOLS，以获取当前工具架构

设置

获取 Rube MCP：在客户端配置中添加 https://rube.app/mcp 作为 MCP 服务。无需 API 密钥——只需添加端点即可使用。

1. 确认 RUBE_SEARCH_TOOLS 有响应，以验证 Rube MCP 可用
2. 调用 RUBE_MANAGE_CONNECTIONS，工具包为 supabase
3. 如果连接状态不是 ACTIVE，请使用返回的身份验证链接完成 Supabase 身份验证
4. 在运行任何工作流之前，确认连接状态显示为 ACTIVE

核心工作流

1. 查询和管理数据库表

适用场景：用户希望读取表中的数据、检查架构或执行 CRUD 操作

工具调用顺序：

1. SUPABASE_LIST_ALL_PROJECTS - 列出项目以查找目标 project_ref［前置条件］
2. SUPABASE_LIST_TABLES - 列出数据库中的所有表和视图［前置条件］
3. SUPABASE_GET_TABLE_SCHEMAS - 获取详细的列类型、约束和关系［写入操作的前置条件］
4. SUPABASE_SELECT_FROM_TABLE - 使用筛选、排序和分页查询行［读取操作必需］
5. SUPABASE_BETA_RUN_SQL_QUERY - 执行任意 SQL，以进行复杂查询、插入、更新或删除［写入操作必需］

SELECT_FROM_TABLE 的关键参数：

• project_ref：20 个字符的小写项目引用
• table：要查询的表或视图名称
• select：以逗号分隔的列名列表（支持嵌套选择和类似 profile->avatar_url 的 JSON 路径）
• filters：筛选对象数组，包含 column、operator、value
• order：排序表达式，例如 created_at.desc
• limit：返回的最大行数（最小值为 1）
• offset：分页时跳过的行数

PostgREST 筛选运算符：

• eq、neq：等于／不等于
• gt、gte、lt、lte：比较运算符
• like、ilike：模式匹配（区分大小写／不区分大小写）
• is：IS 检查（用于 null、true、false）
• in：属于值列表
• cs、cd：包含／被包含（数组）
• fts、plfts、phfts、wfts：全文搜索变体

RUN_SQL_QUERY 的关键参数：

• ref：项目引用（20 个小写字母，模式为 ^[a-z]{20}$）
• query：有效的 PostgreSQL SQL 语句
• read_only：布尔值，用于强制事务只读（SELECT 操作更安全）

注意事项：

• project_ref 必须恰好包含 20 个小写字母（仅限 a-z，不含数字或连字符）
• SELECT_FROM_TABLE 为只读；INSERT、UPDATE、DELETE 操作请使用 RUN_SQL_QUERY
• 对于 PostgreSQL 数组列（text[]、integer[]），请使用 ARRAY['item1', 'item2'] 或 '{"item1", "item2"}' 语法，不要使用 JSON 数组语法 '["item1", "item2"]'
• 查询中区分大小写的 SQL 标识符必须用双引号括起来
• 复杂的 DDL 操作可能会超时（限制约为 60 秒）；请拆分成较小的查询
• ERROR 42P01“relation does not exist”通常表示未用引号括起区分大小写的标识符
• ERROR 42883“function does not exist”表示调用了非标准辅助函数；优先使用 information_schema 查询

2. 管理项目和组织

使用时机：用户想要列出项目、检查配置或管理组织

工具调用顺序：

1. SUPABASE_LIST_ALL_ORGANIZATIONS - 列出所有组织（ID 和名称）[必需]
2. SUPABASE_GETS_INFORMATION_ABOUT_THE_ORGANIZATION - 根据 slug 获取组织详细信息 [可选]
3. SUPABASE_LIST_MEMBERS_OF_AN_ORGANIZATION - 列出组织成员及其角色和 MFA 状态 [可选]
4. SUPABASE_LIST_ALL_PROJECTS - 列出所有项目及其元数据 [必需]
5. SUPABASE_GETS_PROJECT_S_POSTGRES_CONFIG - 获取数据库配置 [可选]
6. SUPABASE_GETS_PROJECT_S_AUTH_CONFIG - 获取身份验证配置 [可选]
7. SUPABASE_GET_PROJECT_API_KEYS - 获取 API 密钥（敏感信息——谨慎处理）[可选]
8. SUPABASE_GETS_PROJECT_S_SERVICE_HEALTH_STATUS - 检查服务健康状态 [可选]

关键参数：

• ref：项目专用工具所需的项目引用
• slug：组织工具所需的组织 slug（适用于 URL 的标识符）
• services：用于健康检查的服务数组：auth、db、db_postgres_user、pg_bouncer、pooler、realtime、rest、storage

注意事项：

• LIST_ALL_ORGANIZATIONS 返回 id 和 slug；LIST_MEMBERS_OF_AN_ORGANIZATION 需要 slug，而不是 id
• GET_PROJECT_API_KEYS 会返回正在使用的密钥——绝不要记录、显示或持久化完整的密钥值
• GETS_PROJECT_S_SERVICE_HEALTH_STATUS 需要非空的 services 数组；空数组会导致 invalid_request 错误
• 如果令牌缺少必需的作用域，配置工具可能会返回 401/403；应妥善处理，而不是导致整个工作流失败

3. 检查数据库架构

使用时机：用户想要了解表结构、列、约束或生成类型

工具调用顺序：

1. SUPABASE_LIST_ALL_PROJECTS - 查找目标项目 [前置条件]
2. SUPABASE_LIST_TABLES - 列出所有表和视图及其元数据 [必需]
3. SUPABASE_GET_TABLE_SCHEMAS - 获取指定表的详细架构 [必需]
4. SUPABASE_GENERATE_TYPE_SCRIPT_TYPES - 根据架构生成 TypeScript 类型 [可选]

LIST_TABLES 的关键参数：

• project_ref：项目引用
• schemas：要搜索的架构名称数组（例如 ["public"]）；省略则搜索所有非系统架构
• include_views：是否在表之外包含视图（默认值为 true）
• include_metadata：是否包含行数估算和大小（默认值为 true）
• include_system_schemas：是否包含 pg_catalog、information_schema 等（默认值为 false）

GET_TABLE_SCHEMAS 的关键参数：

• project_ref：项目引用
• table_names：表名数组（每次请求最多 20 个）；支持 public.users、auth.users 这样的架构前缀
• include_relationships：是否包含外键信息（默认值为 true）
• include_indexes：是否包含索引信息（默认值为 true）
• exclude_null_values：隐藏 null 字段以简化输出（默认值为 true）

GENERATE_TYPE_SCRIPT_TYPES 的关键参数：

• ref：项目引用
• included_schemas：以逗号分隔的架构名称（默认值为 "public"）

注意事项：

• 不带架构前缀的表名默认使用 public 架构
• LIST_TABLES 返回的 row_count 和 size_bytes 对于视图或最近创建的表可能为 null；应视为未知，而非零
• GET_TABLE_SCHEMAS 每次请求最多处理 20 个表；必要时分批请求
• TypeScript 类型包含指定架构中的所有表；无法筛选单个表

4. 管理 Edge Functions

适用场景：用户想要列出、检查或使用 Supabase Edge Functions

工具调用顺序：

1. SUPABASE_LIST_ALL_PROJECTS - 查找项目引用 [前置条件]
2. SUPABASE_LIST_ALL_FUNCTIONS - 列出所有 Edge Functions 及其元数据 [必需]
3. SUPABASE_RETRIEVE_A_FUNCTION - 获取特定函数的详细信息 [可选]

关键参数：

• ref：项目引用
• RETRIEVE_A_FUNCTION 使用的函数 slug

注意事项：

• LIST_ALL_FUNCTIONS 仅返回元数据，不包含函数代码或日志
• created_at 和 updated_at 可能是 epoch 毫秒时间戳；请转换为人类可读的时间戳
• 这些工具无法创建或部署 Edge Functions；它们只是只读检查工具
• 没有组织或项目管理员权限时，可能会出现权限错误

5. 管理存储桶

适用场景：用户想要列出存储桶或管理文件存储

工具调用顺序：

1. SUPABASE_LIST_ALL_PROJECTS - 查找项目引用 [前置条件]
2. SUPABASE_LISTS_ALL_BUCKETS - 列出所有存储桶 [必需]

关键参数：

• ref：项目引用

注意事项：

• LISTS_ALL_BUCKETS 仅返回存储桶列表，不包含桶内内容或访问策略
• 对于文件上传，SUPABASE_RESUMABLE_UPLOAD_SIGN_OPTIONS_WITH_ID 仅处理 TUS 可续传上传的 CORS 预检请求
• 直接进行文件操作可能需要通过 Supabase 存储 API 使用 proxy_execute

常见模式

ID 解析

• 项目引用：SUPABASE_LIST_ALL_PROJECTS -- 提取 ref 字段（20 个小写字母）
• 组织 slug：SUPABASE_LIST_ALL_ORGANIZATIONS -- 下游组织工具使用 slug（而非 id）
• 表名：SUPABASE_LIST_TABLES -- 查询前先列出可用的表
• 架构发现：SUPABASE_GET_TABLE_SCHEMAS -- 写入前检查列和约束

分页

• SUPABASE_SELECT_FROM_TABLE：使用 offset + limit 分页。每次将 offset 增加 limit，直到返回的行数少于 limit。
• SUPABASE_LIST_ALL_PROJECTS：大型账户可能会分页；请逐页跟进游标，直到没有更多内容。
• SUPABASE_LIST_TABLES：大型数据库可能会分页。

SQL 最佳实践

• 编写 SQL 前，务必使用 SUPABASE_GET_TABLE_SCHEMAS 或 SUPABASE_LIST_TABLES
• 对 SELECT 查询使用 read_only: true，以避免意外修改数据
• 对大小写敏感的标识符加引号：使用 SELECT * FROM "MyTable"，而非 SELECT * FROM MyTable
• 数组列使用 PostgreSQL 数组语法：ARRAY['a', 'b']，而非 ['a', 'b']
• 将复杂的 DDL 拆分为较小的语句，以避免超时

已知注意事项

ID 格式

• 项目引用恰好由 20 个小写字母（a-z）组成：模式为 ^[a-z]{20}$
• 组织标识符有 id（UUID）和 slug（URL 友好字符串）两种形式；不同工具接受的格式可能不同
• LIST_MEMBERS_OF_AN_ORGANIZATION 要求使用 slug，而非 id

SQL 执行

• BETA_RUN_SQL_QUERY 执行复杂操作时超时时间约为 60 秒
• 必须使用 PostgreSQL 数组语法：ARRAY['item'] 或 '{"item"}'，不能使用 JSON 语法 '["item"]'
• SQL 中大小写敏感的标识符必须用双引号括起来
• ERROR 42P01：关系不存在（检查引用方式和架构前缀）
• ERROR 42883：函数不存在（使用 information_schema，而非自定义辅助函数）

敏感数据

• GET_PROJECT_API_KEYS 会返回 service-role 密钥——绝不要暴露完整值
• Auth 配置工具会排除密钥，但仍可能包含敏感配置
• 输出 API 密钥时，务必进行遮盖或截断

架构元数据

• LIST_TABLES 返回的 row_count 和 size_bytes 可能为 null；不要将其视为零
• 默认排除系统架构；设置 include_system_schemas: true 可查看这些架构
• 除非设置 include_views: false，否则视图会与表一同显示

速率限制和权限

• 增强工具（API 密钥、配置）在缺少适当作用域时可能返回 401/403；请跳过并继续处理
• 列出大量表时可能需要分页
• GETS_PROJECT_S_SERVICE_HEALTH_STATUS 在 services 数组为空时会失败——请始终至少指定一项

快速参考

任务	工具标识	关键参数
列出组织	SUPABASE_LIST_ALL_ORGANIZATIONS	（无）
获取组织信息	SUPABASE_GETS_INFORMATION_ABOUT_THE_ORGANIZATION	slug
列出组织成员	SUPABASE_LIST_MEMBERS_OF_AN_ORGANIZATION	slug
列出项目	SUPABASE_LIST_ALL_PROJECTS	（无）
列出表	SUPABASE_LIST_TABLES	project_ref、schemas
获取表结构	SUPABASE_GET_TABLE_SCHEMAS	project_ref、table_names
查询表	SUPABASE_SELECT_FROM_TABLE	project_ref、table、select、filters
运行 SQL	SUPABASE_BETA_RUN_SQL_QUERY	ref、query、read_only
生成 TS 类型	SUPABASE_GENERATE_TYPE_SCRIPT_TYPES	ref、included_schemas
Postgres 配置	SUPABASE_GETS_PROJECT_S_POSTGRES_CONFIG	ref
身份验证配置	SUPABASE_GETS_PROJECT_S_AUTH_CONFIG	ref
获取 API 密钥	SUPABASE_GET_PROJECT_API_KEYS	ref
服务健康状态	SUPABASE_GETS_PROJECT_S_SERVICE_HEALTH_STATUS	ref、services
列出边缘函数	SUPABASE_LIST_ALL_FUNCTIONS	ref
获取边缘函数	SUPABASE_RETRIEVE_A_FUNCTION	ref、函数标识
列出存储桶	SUPABASE_LISTS_ALL_BUCKETS	ref
列出数据库分支	SUPABASE_LIST_ALL_DATABASE_BRANCHES	ref

---

由 Composio 提供支持