)\n- `query`: Valid PostgreSQL SQL statement\n- `read_only`: Boolean to force read-only transaction (safer for SELECTs)\n\n**Pitfalls**:\n- `project_ref` must be exactly 20 lowercase letters (a-z only, no numbers or hyphens)\n- `SELECT_FROM_TABLE` is read-only; use `RUN_SQL_QUERY` for INSERT, UPDATE, DELETE operations\n- For PostgreSQL array columns (text[], integer[]), use `ARRAY['item1', 'item2']` or `'{\"item1\", \"item2\"}'` syntax, NOT JSON array syntax `'[\"item1\", \"item2\"]'`\n- SQL identifiers that are case-sensitive must be double-quoted in queries\n- Complex DDL operations may timeout (~60 second limit); break into smaller queries\n- ERROR 42P01 \"relation does not exist\" usually means unquoted case-sensitive identifiers\n- ERROR 42883 \"function does not exist\" means you are calling non-standard helpers; prefer information_schema queries\n\n### 2. Manage Projects and Organizations\n\n**When to use**: User wants to list projects, inspect configurations, or manage organizations\n\n**Tool sequence**:\n1. `SUPABASE_LIST_ALL_ORGANIZATIONS` - List all organizations (IDs and names) [Required]\n2. `SUPABASE_GETS_INFORMATION_ABOUT_THE_ORGANIZATION` - Get detailed org info by slug [Optional]\n3. `SUPABASE_LIST_MEMBERS_OF_AN_ORGANIZATION` - List org members with roles and MFA status [Optional]\n4. `SUPABASE_LIST_ALL_PROJECTS` - List all projects with metadata [Required]\n5. `SUPABASE_GETS_PROJECT_S_POSTGRES_CONFIG` - Get database configuration [Optional]\n6. `SUPABASE_GETS_PROJECT_S_AUTH_CONFIG` - Get authentication configuration [Optional]\n7. `SUPABASE_GET_PROJECT_API_KEYS` - Get API keys (sensitive -- handle carefully) [Optional]\n8. `SUPABASE_GETS_PROJECT_S_SERVICE_HEALTH_STATUS` - Check service health [Optional]\n\n**Key parameters**:\n- `ref`: Project reference for project-specific tools\n- `slug`: Organization slug (URL-friendly identifier) for org tools\n- `services`: Array of services for health check: `auth`, `db`, `db_postgres_user`, `pg_bouncer`, `pooler`, `realtime`, `rest`, `storage`\n\n**Pitfalls**:\n- `LIST_ALL_ORGANIZATIONS` returns both `id` and `slug`; `LIST_MEMBERS_OF_AN_ORGANIZATION` expects `slug`, not `id`\n- `GET_PROJECT_API_KEYS` returns live secrets -- NEVER log, display, or persist full key values\n- `GETS_PROJECT_S_SERVICE_HEALTH_STATUS` requires a non-empty `services` array; empty array causes invalid_request error\n- Config tools may return 401/403 if token lacks required scope; handle gracefully rather than failing the whole workflow\n\n### 3. Inspect Database Schema\n\n**When to use**: User wants to understand table structure, columns, constraints, or generate types\n\n**Tool sequence**:\n1. `SUPABASE_LIST_ALL_PROJECTS` - Find the target project [Prerequisite]\n2. `SUPABASE_LIST_TABLES` - Enumerate all tables and views with metadata [Required]\n3. `SUPABASE_GET_TABLE_SCHEMAS` - Get detailed schema for specific tables [Required]\n4. `SUPABASE_GENERATE_TYPE_SCRIPT_TYPES` - Generate TypeScript types from schema [Optional]\n\n**Key parameters for LIST_TABLES**:\n- `project_ref`: Project reference\n- `schemas`: Array of schema names to search (e.g., `[\"public\"]`); omit for all non-system schemas\n- `include_views`: Include views alongside tables (default true)\n- `include_metadata`: Include row count estimates and sizes (default true)\n- `include_system_schemas`: Include pg_catalog, information_schema, etc. (default false)\n\n**Key parameters for GET_TABLE_SCHEMAS**:\n- `project_ref`: Project reference\n- `table_names`: Array of table names (max 20 per request); supports schema prefix like `public.users`, `auth.users`\n- `include_relationships`: Include foreign key info (default true)\n- `include_indexes`: Include index info (default true)\n- `exclude_null_values`: Cleaner output by hiding null fields (default true)\n\n**Key parameters for GENERATE_TYPE_SCRIPT_TYPES**:\n- `ref`: Project reference\n- `included_schemas`: Comma-separated schema names (default `\"public\"`)\n\n**Pitfalls**:\n- Table names without schema prefix assume `public` schema\n- `row_count` and `size_bytes` from LIST_TABLES may be null for views or recently created tables; treat as unknown, not zero\n- GET_TABLE_SCHEMAS has a max of 20 tables per request; batch if needed\n- TypeScript types include all tables in specified schemas; cannot filter individual tables\n\n### 4. Manage Edge Functions\n\n**When to use**: User wants to list, inspect, or work with Supabase Edge Functions\n\n**Tool sequence**:\n1. `SUPABASE_LIST_ALL_PROJECTS` - Find the project reference [Prerequisite]\n2. `SUPABASE_LIST_ALL_FUNCTIONS` - List all edge functions with metadata [Required]\n3. `SUPABASE_RETRIEVE_A_FUNCTION` - Get detailed info for a specific function [Optional]\n\n**Key parameters**:\n- `ref`: Project reference\n- Function slug for RETRIEVE_A_FUNCTION\n\n**Pitfalls**:\n- `LIST_ALL_FUNCTIONS` returns metadata only, not function code or logs\n- `created_at` and `updated_at` may be epoch milliseconds; convert to human-readable timestamps\n- These tools cannot create or deploy edge functions; they are read-only inspection tools\n- Permission errors may occur without org/project admin rights\n\n### 5. Manage Storage Buckets\n\n**When to use**: User wants to list storage buckets or manage file storage\n\n**Tool sequence**:\n1. `SUPABASE_LIST_ALL_PROJECTS` - Find the project reference [Prerequisite]\n2. `SUPABASE_LISTS_ALL_BUCKETS` - List all storage buckets [Required]\n\n**Key parameters**:\n- `ref`: Project reference\n\n**Pitfalls**:\n- `LISTS_ALL_BUCKETS` returns bucket list only, not bucket contents or access policies\n- For file uploads, `SUPABASE_RESUMABLE_UPLOAD_SIGN_OPTIONS_WITH_ID` handles CORS preflight for TUS resumable uploads only\n- Direct file operations may require using `proxy_execute` with the Supabase storage API\n\n## Common Patterns\n\n### ID Resolution\n- **Project reference**: `SUPABASE_LIST_ALL_PROJECTS` -- extract `ref` field (20 lowercase letters)\n- **Organization slug**: `SUPABASE_LIST_ALL_ORGANIZATIONS` -- use `slug` (not `id`) for downstream org tools\n- **Table names**: `SUPABASE_LIST_TABLES` -- enumerate available tables before querying\n- **Schema discovery**: `SUPABASE_GET_TABLE_SCHEMAS` -- inspect columns and constraints before writes\n\n### Pagination\n- `SUPABASE_SELECT_FROM_TABLE`: Uses `offset` + `limit` pagination. Increment offset by limit until fewer rows than limit are returned.\n- `SUPABASE_LIST_ALL_PROJECTS`: May paginate for large accounts; follow cursors/pages until exhausted.\n- `SUPABASE_LIST_TABLES`: May paginate for large databases.\n\n### SQL Best Practices\n- Always use `SUPABASE_GET_TABLE_SCHEMAS` or `SUPABASE_LIST_TABLES` before writing SQL\n- Use `read_only: true` for SELECT queries to prevent accidental mutations\n- Quote case-sensitive identifiers: `SELECT * FROM \"MyTable\"` not `SELECT * FROM MyTable`\n- Use PostgreSQL array syntax for array columns: `ARRAY['a', 'b']` not `['a', 'b']`\n- Break complex DDL into smaller statements to avoid timeouts\n\n## Known Pitfalls\n\n### ID Formats\n- Project references are exactly 20 lowercase letters (a-z): pattern `^[a-z]{20} \n- Organization identifiers come as both `id` (UUID) and `slug` (URL-friendly string); tools vary in which they accept\n- `LIST_MEMBERS_OF_AN_ORGANIZATION` requires `slug`, not `id`\n\n### SQL Execution\n- `BETA_RUN_SQL_QUERY` has ~60 second timeout for complex operations\n- PostgreSQL array syntax required: `ARRAY['item']` or `'{\"item\"}'`, NOT JSON syntax `'[\"item\"]'`\n- Case-sensitive identifiers must be double-quoted in SQL\n- ERROR 42P01: relation does not exist (check quoting and schema prefix)\n- ERROR 42883: function does not exist (use information_schema instead of custom helpers)\n\n### Sensitive Data\n- `GET_PROJECT_API_KEYS` returns service-role keys -- NEVER expose full values\n- Auth config tools exclude secrets but may still contain sensitive configuration\n- Always mask or truncate API keys in output\n\n### Schema Metadata\n- `row_count` and `size_bytes` from `LIST_TABLES` can be null; do not treat as zero\n- System schemas are excluded by default; set `include_system_schemas: true` to see them\n- Views appear alongside tables unless `include_views: false`\n\n### Rate Limits and Permissions\n- Enrichment tools (API keys, configs) may return 401/403 without proper scopes; skip gracefully\n- Large table listings may require pagination\n- `GETS_PROJECT_S_SERVICE_HEALTH_STATUS` fails with empty `services` array -- always specify at least one\n\n## Quick Reference\n\n| Task | Tool Slug | Key Params |\n|------|-----------|------------|\n| List organizations | `SUPABASE_LIST_ALL_ORGANIZATIONS` | (none) |\n| Get org info | `SUPABASE_GETS_INFORMATION_ABOUT_THE_ORGANIZATION` | `slug` |\n| List org members | `SUPABASE_LIST_MEMBERS_OF_AN_ORGANIZATION` | `slug` |\n| List projects | `SUPABASE_LIST_ALL_PROJECTS` | (none) |\n| List tables | `SUPABASE_LIST_TABLES` | `project_ref`, `schemas` |\n| Get table schemas | `SUPABASE_GET_TABLE_SCHEMAS` | `project_ref`, `table_names` |\n| Query table | `SUPABASE_SELECT_FROM_TABLE` | `project_ref`, `table`, `select`, `filters` |\n| Run SQL | `SUPABASE_BETA_RUN_SQL_QUERY` | `ref`, `query`, `read_only` |\n| Generate TS types | `SUPABASE_GENERATE_TYPE_SCRIPT_TYPES` | `ref`, `included_schemas` |\n| Postgres config | `SUPABASE_GETS_PROJECT_S_POSTGRES_CONFIG` | `ref` |\n| Auth config | `SUPABASE_GETS_PROJECT_S_AUTH_CONFIG` | `ref` |\n| Get API keys | `SUPABASE_GET_PROJECT_API_KEYS` | `ref` |\n| Service health | `SUPABASE_GETS_PROJECT_S_SERVICE_HEALTH_STATUS` | `ref`, `services` |\n| List edge functions | `SUPABASE_LIST_ALL_FUNCTIONS` | `ref` |\n| Get edge function | `SUPABASE_RETRIEVE_A_FUNCTION` | `ref`, function slug |\n| List storage buckets | `SUPABASE_LISTS_ALL_BUCKETS` | `ref` |\n| List DB branches | `SUPABASE_LIST_ALL_DATABASE_BRANCHES` | `ref` |\n","repo_fullName":"mk-knight23/AGENTS-COLLECTION","repo_stars":69,"repo_language":"TypeScript","repo_license":null,"repo_pushedAt":"2026-04-16T07:24:00Z","owner_login":"mk-knight23","owner_type":"User","owner_name":"KAZI MUSHARRAF","owner_avatarUrl":"https://avatars.githubusercontent.com/u/71258852?v=4"}};