opencode-supabase 0.3.0 → 0.3.1-alpha.1

package/README.md

@@ -32,25 +32,21 @@ No separate `skills` CLI setup is required. Installing the plugin makes these sk
 
 ## Supabase MCP Onboarding
 
-Ask your agent:
+After connecting Supabase, start by asking OpenCode to list projects:
 
 ```text
-Set up Supabase MCP for my project
+List my Supabase projects
 ```
 
-The agent can explain Supabase MCP, help you choose the target project, and open the Supabase Studio Connect Sheet with the MCP tab and OpenCode client selected.
+Pick the project you want to work with, then ask OpenCode to connect Supabase MCP for that project. OpenCode opens Supabase Studio so you can choose MCP permissions and copy the generated OpenCode config.
 
-Studio remains the source of truth for MCP feature groups, permissions, generated OpenCode config, and auth steps. If you want help applying the Studio output to this repository, paste the Studio prompt or OpenCode config snippet back into OpenCode.
-
-You can skip any Studio instruction to install Supabase Agent Skills separately. This plugin already bundles Supabase skills.
-
-After changing OpenCode MCP config, restart OpenCode. If OAuth is not prompted automatically, run:
+After config is added, restart OpenCode and authenticate the MCP server:
 
 ```bash
 opencode mcp auth supabase
 ```
 
-This plugin opens the MCP setup page and guides the workflow. It does not automatically edit MCP config or choose read-only/feature-group settings for you.
+Complete OAuth in the browser. Skip any `install Supabase Agent Skills` step in Studio; this plugin already bundles the Supabase skills.
 
 ### Disable Bundled Skills
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-supabase",
-  "version": "0.3.0",
+  "version": "0.3.1-alpha.1",
   "type": "module",
   "description": "OpenCode plugin for Supabase integration with server and TUI components",
   "license": "Apache-2.0",
@@ -49,4 +49,4 @@
     "solid-js": "1.9.11",
     "typescript": "^5"
   }
-}
+}

package/skills/opencode-supabase-guide/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: opencode-supabase-guide
-description: Use when users ask to set up Supabase MCP in OpenCode, paste Supabase Studio MCP config, or need MCP tools connected.
+description: Use when users ask to set up Supabase MCP in OpenCode, connect project to MCP, connect a project to MCP, connect MCP, conenct MCP, connect MCP server, connect Supabase MCP, paste Supabase Studio MCP config, or need MCP tools connected.
 ---
 
 # OpenCode Supabase Guide
@@ -9,31 +9,200 @@ description: Use when users ask to set up Supabase MCP in OpenCode, paste Supaba
 
 Every interactive choice MUST use `question` tool. Never assume, never auto-pick. This includes:
 
-- Selecting a project when multiple exist — list options with name + ref in the question.
-- Confirming before opening browser — include project name + ref in the question.
+- Selecting a project when multiple exist -- list options with name + ref in the question.
+- Confirming before opening browser -- include project name + ref in the question.
 - Choosing whether to apply Studio config to the repo.
 - Any yes/no or selection prompt.
 
-No prose "ask" — always `question` tool invocation.
+No prose "ask" -- always `question` tool invocation.
+
+Question tool rules:
+
+- Do not add `Other`, `Something else`, `Type your own answer`, or catch-all options.
+- OpenCode adds `Type your own answer` automatically.
+- Put the recommended option first and include `(Recommended)` in the label.
+- Keep labels short and put explanatory text in `description`.
 
 ## Overview
 
-Supabase MCP adds project-scoped Supabase tools to OpenCode. Before MCP setup, tell user to run `/supabase` to connect their account — plugin tools (list projects, create project) need OAuth. MCP config comes from Studio prompt, not rebuilt from code.
+List projects first. Do not lead with MCP setup immediately after `/supabase` auth.
+
+Supabase MCP adds project-scoped Supabase tools to OpenCode. Before MCP setup, tell user to run `/supabase` to connect their account -- plugin tools (list projects, create project) need OAuth. MCP config comes from Studio prompt, not rebuilt from code.
 
 ## MCP Setup Flow
 
-1. Resolve project with `supabase_list_projects`. If auth fails, tell user: "Run `/supabase` to connect your Supabase account." If multiple projects, use `question` tool listing name + ref for each.
-2. Use `question` tool to confirm: "Open Supabase MCP Connect for `<name>` (`<ref>`)?"
-3. Call `supabase_open_mcp_setup`. Always print returned URL in output.
-4. Tell user to paste Studio prompt/config back for wiring into `.opencode/opencode.json`.
+1. If user has not chosen a project, call `supabase_list_projects`.
+2. If multiple projects exist, use the Question tool to choose one.
+3. After a project is selected, offer to connect that project to Supabase MCP.
+4. If user confirms, call `supabase_open_mcp_setup`.
+5. Tell user to paste the Studio prompt or OpenCode config snippet back here.
+6. After config is added, tell user to close OpenCode or exit the current session, run `opencode mcp auth supabase`, complete OAuth in the browser, then start OpenCode again.
+
+User phrases that MUST trigger this flow include: `connect project to MCP`, `connect a project to MCP`, `connect MCP`, `conenct MCP`, `connect MCP server`, `connect Supabase MCP`, and `connect to Supabase MCP`.
+
+Never list projects as bullets and ask the user to reply in prose. Use this Question tool shape for project selection:
+
+```json
+{
+  "questions": [
+    {
+      "header": "Choose Project",
+      "question": "Which project do you want to connect to Supabase MCP?",
+      "multiple": false,
+      "options": [
+        {
+          "label": "opencode-tester",
+          "description": "Project ref: abcdefghijklmnopqrst"
+        },
+        {
+          "label": "analytics-prod",
+          "description": "Project ref: zyxwvutsrqponmlkjihg"
+        }
+      ]
+    }
+  ]
+}
+```
+
+Use this Question tool shape before opening Studio:
+
+```json
+{
+  "questions": [
+    {
+      "header": "Connect Supabase",
+      "question": "Connect opencode-tester to Supabase MCP?",
+      "multiple": false,
+      "options": [
+        {
+          "label": "Open browser (Recommended)",
+          "description": "Open Supabase Studio to choose permissions and copy config"
+        },
+        {
+          "label": "Skip setup",
+          "description": "Do not connect Supabase MCP now"
+        }
+      ]
+    }
+  ]
+}
+```
+
+Replace `opencode-tester` with the selected project name.
+
+## Required Phrases
+
+Use explicit wording. Do not improvise around auth/setup state.
+
+After `/supabase` auth succeeds:
+
+Say this:
+
+```text
+Ask me to list your Supabase projects first.
+Then pick a project and ask me to connect it to MCP.
+```
+
+Do not say:
+
+```text
+Set up Supabase MCP for my project.
+```
+
+After project selection:
+
+Say this:
+
+```text
+Connect this project to Supabase MCP?
+```
+
+Do not say:
+
+```text
+I will set up MCP now.
+```
+
+After Studio config is pasted or applied:
+
+OAuth is a required separate step. The current OpenCode TUI session cannot reload the MCP config. Close OpenCode or exit the current session, then `opencode mcp auth supabase` starts browser OAuth for that MCP server. Start OpenCode again after OAuth completes.
+
+Say this:
+
+```text
+Close OpenCode or exit the current session, then run `opencode mcp auth supabase`.
+Complete OAuth in the browser.
+Start OpenCode again after OAuth completes.
+```
+
+Do not say:
+
+```text
+OAuth starts by itself after restart.
+Run auth only if MCP fails.
+```
+
+Never tell the user to wait for automatic OAuth. Always tell them to close OpenCode or exit the current session, run `opencode mcp auth supabase`, complete OAuth in the browser, and start OpenCode again after OAuth completes.
+
+If config already exists:
+
+Say this:
+
+```text
+Supabase MCP config already exists for this workspace. No file changes needed.
+Close OpenCode or exit the current session, then run `opencode mcp auth supabase`.
+Complete OAuth in the browser.
+Start OpenCode again after OAuth completes.
+```
+
+Do not say:
+
+```text
+Config already wired.
+```
+
+If user says MCP works after only restarting:
+
+Say this:
+
+```text
+MCP auth may already be cached from an earlier setup.
+Restarting loaded the config; cached auth let the MCP server work without a new browser auth step.
+```
+
+## OpenCode Auth
+
+OpenCode does not automatically start OAuth after config is added. OAuth is a required separate step. After adding MCP config, tell the user:
+
+```text
+Close OpenCode or exit the current session, then run:
+opencode mcp auth supabase
+
+Complete OAuth in the browser.
+Start OpenCode again after OAuth completes.
+```
 
 ## Studio Prompt Handling
 
-Extract MCP JSON from Studio prompt. Strip line numbers (`1{`). Preserve URLs exactly — never rebuild from `project_ref`. MCP server key usually `supabase`; auth: `opencode mcp auth supabase`. Skip `npx skills add supabase/agent-skills` — already bundled.
+Extract MCP JSON from Studio prompt. Strip line numbers (`1{`). Preserve URLs exactly -- never rebuild from `project_ref`. MCP server key usually `supabase`; auth: `opencode mcp auth supabase`. Skip `npx skills add supabase/agent-skills` -- already bundled.
 
 ## Config Rules
 
-Prefer `.opencode/opencode.json` (or `.opencode/opencode.jsonc`). Global (`~/.config/opencode/opencode.json`) only on explicit request. Use `question` tool before editing. Remind to restart OpenCode.
+Prefer `.opencode/opencode.json` (or `.opencode/opencode.jsonc`). Global (`~/.config/opencode/opencode.json`) only on explicit request. Use `question` tool before editing. Remind to close OpenCode or exit the current session before auth, then start OpenCode again after OAuth completes.
+
+If the Studio config is already present in `.opencode/opencode.json` or `.opencode/opencode.jsonc`, say:
+
+```text
+Supabase MCP config already exists for this workspace. No file changes needed.
+
+Close OpenCode or exit the current session, then run:
+opencode mcp auth supabase
+
+Complete OAuth in the browser.
+Start OpenCode again after OAuth completes.
+```
+
+Do not say `already wired` without explaining the restart and auth steps.
 
 ## Common Mistakes
 
@@ -46,7 +215,8 @@ Prefer `.opencode/opencode.json` (or `.opencode/opencode.jsonc`). Global (`~/.co
 | Choosing MCP features for user          | Studio decides read-only, feature groups |
 | Calling MCP setup while unauthenticated | Tell user to run `/supabase` first         |
 | Asking user without `question` tool     | Always use `question` tool for confirmations, project selection, any interactive choice |
+| Saying OAuth happens automatically      | OAuth is a required separate step: close OpenCode or exit the current session, run `opencode mcp auth supabase`, complete browser OAuth, start OpenCode again |
 
 ## Troubleshooting
 
-MCP tools missing after config? Restart OpenCode, run `opencode mcp auth supabase`.
+MCP tools missing after config? Say: `Close OpenCode or exit the current session, run opencode mcp auth supabase, complete OAuth, then start OpenCode again.`

package/src/server/auth-html.ts

@@ -103,6 +103,8 @@ export const HTML_SUCCESS = `<!doctype html>
       <p>You can <strong>close this window</strong> and return to OpenCode.</p>
       <div class="prompt-label">Try this next:</div>
       <div class="prompt-box">list my Supabase projects</div>
+      <div class="prompt-label">Then try:</div>
+      <div class="prompt-box">connect a project to MCP</div>
       <div class="footer">Having troubles or found a bug?<br><a href="${REPO_URL}" target="_blank" rel="noopener">Report it on GitHub</a></div>
     </div>
     <script>setTimeout(function(){window.close()},2000)</script>

package/src/server/tools.ts

@@ -431,18 +431,25 @@ function createMcpSetupUrl(projectRef: string) {
   return url.toString();
 }
 
-function formatMcpSetupResult(projectRef: string, url: string) {
-  return `Opened Supabase MCP setup for project ${projectRef} in Studio.
-
-URL: ${url}
-
-On the Connect page:
-1. Confirm MCP tab and OpenCode client are selected.
-2. Choose the feature groups and permissions you want in Studio.
-3. Follow the OpenCode config and auth steps shown by Studio.
-4. If you want me to wire this into the current repo, paste the Studio prompt or OpenCode config snippet back here.
-5. You can skip any "install Supabase Agent Skills" step because this plugin already bundles them.
-6. Restart OpenCode after changing config; run \`opencode mcp auth supabase\` if OAuth is not prompted automatically.`;
+function formatMcpSetupResult(url: string) {
+  return [
+    "MCP Connect page is open:",
+    url,
+    "",
+    "Grab config from Supabase Studio:",
+    "1. In Connect -> MCP -> OpenCode, choose permissions.",
+    "2. Copy the generated config under Configure MCP.",
+    "3. Paste the Studio prompt or config snippet back here.",
+    "",
+    "Skip any install Supabase Agent Skills step; this plugin already bundles them.",
+    "",
+    "After adding config:",
+    "1. Close OpenCode or exit the current session.",
+    "2. Run:",
+    "opencode mcp auth supabase",
+    "3. Complete OAuth in the browser.",
+    "4. Start OpenCode again.",
+  ].join("\n")
 }
 
 export function createSupabaseTools(
@@ -551,7 +558,7 @@ export function createSupabaseTools(
     }),
     supabase_open_mcp_setup: tool({
       description:
-        "Open Supabase Studio MCP Connect page for a project after the user confirms the project. Use when the user asks to set up, connect, configure, or use Supabase MCP in OpenCode. Before calling, explain MCP briefly and ask: Open Supabase MCP Connect page for <project name> (<project-ref>)?",
+        "Open Supabase Studio MCP Connect page for a project after the user confirms the project. Use when the user asks to set up, connect, configure, or use Supabase MCP in OpenCode. Before calling, briefly explain that MCP adds project-scoped database, docs, advisor, and management tools. Ask a Question tool confirmation with an Open browser recommended option and a Skip setup option.",
       args: {
         project_ref: tool.schema.string().describe("Supabase project reference ID"),
       },
@@ -566,7 +573,7 @@ export function createSupabaseTools(
           messageID: _context.messageID,
           agent: _context.agent,
         });
-        return formatMcpSetupResult(args.project_ref, url);
+        return formatMcpSetupResult(url);
       },
     }),
     supabase_login: tool({

package/src/tui/dialog.tsx

@@ -22,16 +22,16 @@ type SupabaseDialogProps = {
 
 const ONBOARDING_MESSAGE = `Supabase is connected.
 
-Now unlock project-scoped tools with Supabase MCP — ask me to set it up to get database inspection, docs, advisors, and more for your project in OpenCode.
+Start by listing your Supabase projects, then connect project-scoped MCP tools for database inspection, docs, advisors, and more in OpenCode.
 
 You can also ask about:
-- your organizations and projects
-- API keys for a project
-- available database regions
+- organizations and projects
+- API keys
+- regions
 - creating a new project
 
 Try this:
-Set up Supabase MCP for my project`;
+List my Supabase projects`;
 
 const onboardedSessionIDsByApi = new WeakMap<TuiPluginApi, Set<string>>();
 
@@ -679,7 +679,8 @@ export function SupabaseDialog(props: SupabaseDialogProps) {
 
   return props.api.ui.DialogAlert({
     title: "Connected to Supabase",
-    message: "Your account is ready. Close this dialog and ask me to list your Supabase projects.",
+    message:
+      "Your account is ready. Close this dialog, ask me to list your Supabase projects, then ask me to connect one to MCP.",
     onConfirm: closeDialog,
   });
 }