opencode-supabase 0.2.2 → 0.2.3-alpha.0

package/README.md

@@ -26,9 +26,32 @@ Connect your account and ask your agent about Supabase capabilities.
 
 - `supabase`
 - `supabase-postgres-best-practices`
+- `opencode-supabase-guide`
 
 No separate `skills` CLI setup is required. Installing the plugin makes these skills available to OpenCode through the plugin server config hook.
 
+## Supabase MCP Onboarding
+
+Ask your agent:
+
+```text
+Set up Supabase MCP for my project
+```
+
+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.
+
+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:
+
+```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.
+
 ### Disable Bundled Skills
 
 If you want Supabase tools without bundled skills, disable them in plugin options:
@@ -65,7 +88,7 @@ Bundled skills are vendored as real files under `skills/` from `supabase/agent-s
 bun run skills:sync
 # or: bun run skills:sync <commit-sha-or-ref>
 bun run typecheck
-bun test
+bun run test
 bun run verify:pack
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-supabase",
-  "version": "0.2.2",
+  "version": "0.2.3-alpha.0",
   "type": "module",
   "description": "OpenCode plugin for Supabase integration with server and TUI components",
   "license": "Apache-2.0",

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

@@ -0,0 +1,52 @@
+---
+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.
+---
+
+# OpenCode Supabase Guide
+
+## Question Tool Rule
+
+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.
+- Choosing whether to apply Studio config to the repo.
+- Any yes/no or selection prompt.
+
+No prose "ask" — always `question` tool invocation.
+
+## 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.
+
+## 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.json`.
+
+## 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.
+
+## Config Rules
+
+Prefer repo-root `opencode.json` (or `.jsonc`). Global (`~/.config/opencode/opencode.json`) only on explicit request. Use `question` tool before editing. Remind to restart OpenCode.
+
+## Common Mistakes
+
+| Mistake                                 | Fix                                      |
+| --------------------------------------- | ---------------------------------------- |
+| Rebuilding/normalizing Studio URLs      | Preserve pasted URLs exactly             |
+| Omitting setup URL from output          | Always print exact returned URL          |
+| Installing separate Agent Skills        | Already bundled in this plugin           |
+| Writing global config by default        | Prefer repo-root `opencode.json`            |
+| 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 |
+
+## Troubleshooting
+
+MCP tools missing after config? Restart OpenCode, run `opencode mcp auth supabase`.

package/src/server/skills.ts

@@ -5,6 +5,7 @@ import { fileURLToPath } from "node:url";
 export const BUNDLED_SUPABASE_SKILLS = [
   "supabase",
   "supabase-postgres-best-practices",
+  "opencode-supabase-guide",
 ] as const;
 
 export type BundledSupabaseSkill = (typeof BUNDLED_SUPABASE_SKILLS)[number];

package/src/server/tools.ts

@@ -1,6 +1,7 @@
 import type { PluginOptions } from "@opencode-ai/plugin";
 import { tool } from "@opencode-ai/plugin";
 import type { ToolContext } from "@opencode-ai/plugin/tool";
+import open from "open";
 
 import { supabaseManagementApiFetch } from "../shared/api.ts";
 import {
@@ -23,6 +24,7 @@ type ToolDeps = {
   fetch?: FetchLike;
   logger?: SupabaseLogger;
   now?: () => Date;
+  open?: (target: string) => Promise<unknown>;
 };
 
 type InFlightRefresh = {
@@ -421,6 +423,28 @@ export async function ensureSupabaseToolAuth(
   return refreshEntry.promise;
 }
 
+function createMcpSetupUrl(projectRef: string) {
+  const url = new URL(`https://supabase.com/dashboard/project/${encodeURIComponent(projectRef)}`);
+  url.searchParams.set("showConnect", "true");
+  url.searchParams.set("connectTab", "mcp");
+  url.searchParams.set("mcpClient", "opencode");
+  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.`;
+}
+
 export function createSupabaseTools(
   input: SupabaseToolInput,
   options?: PluginOptions,
@@ -525,6 +549,26 @@ 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>)?",
+      args: {
+        project_ref: tool.schema.string().describe("Supabase project reference ID"),
+      },
+      async execute(args, _context: SupabaseToolContext) {
+        await ensureSupabaseToolAuth(input, options, deps);
+        const url = createMcpSetupUrl(args.project_ref);
+        const openBrowser = deps.open ?? open;
+        await openBrowser(url);
+        await deps.logger?.info("supabase mcp setup opened", {
+          tool: "supabase_open_mcp_setup",
+          sessionID: _context.sessionID,
+          messageID: _context.messageID,
+          agent: _context.agent,
+        });
+        return formatMcpSetupResult(args.project_ref, url);
+      },
+    }),
     supabase_login: tool({
       description: "Explain how to connect Supabase in the TUI.",
       args: {},

package/src/tui/dialog.tsx

@@ -22,14 +22,16 @@ type SupabaseDialogProps = {
 
 const ONBOARDING_MESSAGE = `Supabase is connected.
 
-You can ask me about:
+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.
+
+You can also ask about:
 - your organizations and projects
 - API keys for a project
 - available database regions
 - creating a new project
 
 Try this:
-list my Supabase projects`;
+Set up Supabase MCP for my project`;
 
 const onboardedSessionIDsByApi = new WeakMap<TuiPluginApi, Set<string>>();