@polymorphism-tech/morph-spec 3.0.1 → 3.1.0

package/stacks/nextjs-supabase/.morph/docs/supabase-mcp-setup.md

@@ -0,0 +1,247 @@
+# Supabase MCP Server Setup Guide
+
+> Direct database management from Claude Code via Model Context Protocol
+
+## What It Provides
+
+The Supabase MCP Server lets Claude Code interact directly with your Supabase project's database. This enables:
+
+- Running SQL queries and viewing results
+- Creating and managing database migrations
+- Inspecting table schemas, indexes, and RLS policies
+- Managing Supabase Auth, Storage, and Edge Functions
+- Schema diffing and migration generation
+
+## CRITICAL WARNING
+
+```
+==========================================================
+  NEVER connect to a PRODUCTION Supabase project via MCP.
+
+  MCP provides direct database access. A single bad query
+  can DROP tables, DELETE data, or DISABLE RLS.
+
+  ONLY connect to:
+  - Local Supabase (supabase start)
+  - Development/staging projects
+  - Disposable test projects
+==========================================================
+```
+
+## Setup
+
+### 1. Get Your Supabase Connection Details
+
+From your Supabase Dashboard > Project Settings > API:
+- **Project URL**: `https://xxxxxxxxxxxx.supabase.co`
+- **Service Role Key**: `eyJhbGc...` (Settings > API > service_role key)
+
+For local Supabase (`supabase start`):
+- **Project URL**: `http://127.0.0.1:54321`
+- **Service Role Key**: Output from `supabase status`
+
+### 2. Configure Claude Desktop / Claude Code
+
+Add the Supabase MCP server to your configuration.
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "supabase": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@supabase/mcp-server-supabase@latest",
+        "--supabase-url",
+        "https://xxxxxxxxxxxx.supabase.co",
+        "--supabase-service-role-key",
+        "eyJhbGc...",
+        "--read-only"
+      ]
+    }
+  }
+}
+```
+
+**Claude Code** (`.claude/settings.local.json`):
+
+```json
+{
+  "mcpServers": {
+    "supabase": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@supabase/mcp-server-supabase@latest",
+        "--supabase-url",
+        "https://xxxxxxxxxxxx.supabase.co",
+        "--supabase-service-role-key",
+        "eyJhbGc...",
+        "--read-only"
+      ]
+    }
+  }
+}
+```
+
+### 3. Default: Read-Only Mode
+
+The `--read-only` flag is included by default. In this mode:
+
+| Operation | Allowed |
+|-----------|---------|
+| SELECT queries | Yes |
+| DESCRIBE / schema inspection | Yes |
+| LIST tables, policies, indexes | Yes |
+| INSERT / UPDATE / DELETE | No |
+| CREATE / ALTER / DROP | No |
+| Migration creation | No |
+
+To enable write access (development only), remove `--read-only`:
+
+```json
+{
+  "mcpServers": {
+    "supabase": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@supabase/mcp-server-supabase@latest",
+        "--supabase-url",
+        "http://127.0.0.1:54321",
+        "--supabase-service-role-key",
+        "your-local-service-role-key"
+      ]
+    }
+  }
+}
+```
+
+Write mode should ONLY be used with local Supabase or disposable dev projects.
+
+## Available Tool Groups
+
+The Supabase MCP Server exposes these tool groups:
+
+### Database Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_tables` | List all tables in the project |
+| `list_extensions` | List installed PostgreSQL extensions |
+| `list_migrations` | List applied migrations |
+| `apply_migration` | Apply a new SQL migration |
+| `execute_sql` | Run arbitrary SQL (read-only by default) |
+| `get_migration_status` | Check pending vs applied migrations |
+
+### Auth Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_auth_config` | View auth provider configuration |
+| `list_auth_users` | List authenticated users |
+
+### Storage Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_storage_buckets` | List storage buckets |
+| `get_storage_config` | View storage configuration |
+
+### Project Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_project_config` | View project settings |
+| `get_project_api_keys` | View API keys |
+
+## Usage for Migrations and Schema Management
+
+### Inspecting Current Schema
+
+Ask Claude Code to use the MCP tools:
+
+```
+"Show me all tables and their RLS policies"
+"What indexes exist on the documents table?"
+"List all migrations applied so far"
+```
+
+### Creating Migrations
+
+With write mode enabled on a local/dev project:
+
+```
+"Create a migration to add a 'tags' column to the documents table"
+"Add an RLS policy so only tenant admins can delete documents"
+"Enable the pgvector extension and create the embedding column"
+```
+
+The MCP server will generate and apply SQL migrations through Supabase's migration system.
+
+### Schema Diffing
+
+```
+"Compare the current schema against the migration files"
+"Show me what would change if I apply the pending migration"
+```
+
+## Usage with MORPH-SPEC Workflow
+
+During MORPH-SPEC phases, the MCP server is useful for:
+
+| Phase | MCP Usage |
+|-------|-----------|
+| **Phase 2 (Design)** | Inspect existing schema to inform spec |
+| **Phase 4 (Tasks)** | Verify migration dependencies |
+| **Phase 5 (Implement)** | Apply migrations, verify RLS policies, test queries |
+
+### Example Workflow
+
+```
+1. Design phase: "List current tables and extensions"
+2. Write migration SQL in supabase/migrations/
+3. Apply via MCP: "Apply migration 003_add_search_logs.sql"
+4. Verify: "Show RLS policies on search_logs table"
+5. Test: "Run SELECT * FROM search_logs LIMIT 5"
+```
+
+## Security Best Practices
+
+1. **Always use `--read-only` unless actively running migrations**
+2. **Never store service_role keys in version control** -- use environment variables or a secrets manager
+3. **Use local Supabase for development** (`supabase start`) instead of cloud projects
+4. **Rotate keys if accidentally exposed** -- Supabase Dashboard > Settings > API > Regenerate
+5. **Restrict MCP to development machines only** -- never configure on CI/CD or shared servers
+6. **Review SQL before applying** -- the MCP server executes SQL with service_role privileges, bypassing all RLS
+
+### Environment Variable Alternative
+
+Instead of hardcoding keys in the config file:
+
+```json
+{
+  "mcpServers": {
+    "supabase": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@supabase/mcp-server-supabase@latest",
+        "--read-only"
+      ],
+      "env": {
+        "SUPABASE_URL": "${SUPABASE_URL}",
+        "SUPABASE_SERVICE_ROLE_KEY": "${SUPABASE_SERVICE_ROLE_KEY}"
+      }
+    }
+  }
+}
+```
+
+Set the environment variables in your shell profile or `.env` file (never committed).
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*