@genlobe/mcp-server 3.7.1 → 3.8.0

package/dist/index.js

@@ -3731,18 +3731,44 @@ End-to-end recipe to wire a chatbot agent that answers from a knowledge base
 populated by a snapshot of your custom-entity catalog (typical "store
 assistant" / "product Q&A" / "support deflection" use case).
 
-## Auth context — clarification (frequent confusion)
+## ⭐ Public chatbots: use service-mode (ADR-0013) — the simple path
 
-The end-user chat endpoint \`POST /v1/user/agents/{agent_id}/chat\` requires
-an end-user JWT. **There are two legitimate ways to obtain that JWT**, and a
-public-facing bot needs option (b):
+For a **public chatbot** (anonymous visitors, no human login), call the
+service-mode endpoint with your \`sk_live_*\` ONLY — no end-user JWT, no bot
+user, no email verification:
+
+\`\`\`http
+POST /v1/server/agents/{agent_id}/chat
+X-API-Key: <your sk_live_*>          ← server-side only
+X-Organization-Id: <org_id>          (or organization_id in the body)
+\`\`\`
+
+Body:
+\`\`\`json
+{ "messages": [{"role":"user","content":"do you have rice?"}], "session_id": "anon-visitor-abc" }
+\`\`\`
+
+Usage is billed to the Tenant + Organization; \`user_id\` on the execution is
+NULL (no human). \`session_id\` (optional) groups one anonymous conversation.
+This is the **recommended path** for storefront/support bots — it removes the
+old bot-user + email-verification wall entirely.
+
+Your Next.js \`/api/chat\` route handler calls this server-side; the browser
+only talks to \`/api/chat\`, never to Genlobe directly.
+
+## Per-user chat (when there IS a logged-in human)
+
+If the chat belongs to an authenticated end-user (e.g. an in-app assistant),
+use \`POST /v1/user/agents/{agent_id}/chat\` with that user's JWT instead — it
+attributes usage per user and applies their plan limits. Two ways to get the
+JWT:
 
 - **(a) Real human end-user**: customer signs up via \`POST /v1/auth/register\`,
   logs in, and chats with the agent. The JWT is theirs.
-- **(b) Bot service account**: register **one real bot user** for the chat
-  surface (use a real email you control, e.g. \`bot@yourshop.com\`), keep its
-  credentials in your server env, log in server-side, attach the resulting
-  JWT to incoming chat requests. This is what "register a bot user" means.
+- **(b) Bot service account (legacy fallback)**: register **one real bot user**
+  (real email you control), log in server-side, attach the JWT. Only needed if
+  you specifically want per-"user" attribution for the bot. For public bots,
+  prefer service-mode above — it is simpler.
 
 **What is NOT allowed** (and what some agents mis-read as "no LLM bot is
 possible"): inventing/synthesizing fake email addresses to bulk-create
@@ -3773,6 +3799,43 @@ LLM layer. The bot user path is still the canonical way to get a real LLM bot.
 
 ## Step-by-step
 
+### 0. Register the bot service-account user (only once per project)
+
+The chat endpoint requires an end-user JWT. Register **one** real user that
+the server uses to obtain that JWT — this is not the same as inventing fake
+emails for bulk signups (which is what the security guide prohibits). Use a
+mailbox you actually own.
+
+\`\`\`http
+POST /v1/auth/register
+Content-Type: application/json
+X-API-Key: <your pk_live_*  ← register works with the public key>
+\`\`\`
+
+Body:
+\`\`\`json
+{
+  "email": "bot@yourshop.com",
+  "password": "<32-char random string, store it once and never again in plain text>",
+  "display_name": "Store Bot"
+}
+\`\`\`
+
+Save the email and the password in your server-side env (\`.env.local\`):
+
+\`\`\`
+BOT_USER_EMAIL=bot@yourshop.com
+BOT_USER_PASSWORD=<that random string>
+\`\`\`
+
+From then on the server logs in this user on demand and caches the JWT for
+its lifetime. **Never** ship \`BOT_USER_PASSWORD\` to the browser. See the
+"Server-side TypeScript snippet" further down for the cached login helper.
+
+If your project does not allow public chat (the bot is internal-only and
+every conversation already belongs to a logged-in human), skip this step
+and pass each user's own JWT to the chat endpoint.
+
 ### 1. Create the KnowledgeBase
 
 \`\`\`http
@@ -3926,11 +3989,28 @@ export async function refreshCatalogKB(productSchemaId: string, kbId: string, ex
   });
 }
 
+// Cached login for the bot service-account user. The JWT is reused until it
+// nears expiry; on next call we refresh server-side.
+let cachedBotJwt: { token: string; expiresAt: number } | null = null;
+
+export async function getBotJwt(): Promise<string> {
+  if (cachedBotJwt && cachedBotJwt.expiresAt > Date.now() + 60_000) {
+    return cachedBotJwt.token;
+  }
+  const email = process.env.BOT_USER_EMAIL!;
+  const password = process.env.BOT_USER_PASSWORD!;
+  const r = await api('/v1/auth/login', { email, password });
+  const ttl = (r.expires_in ?? 3600) * 1000;
+  cachedBotJwt = { token: r.access_token, expiresAt: Date.now() + ttl };
+  return r.access_token;
+}
+
 export async function chatWithAgent(agentId: string, message: string, conversationId?: string) {
+  const jwt = await getBotJwt();
   return api(\`/v1/user/agents/\${agentId}/chat\`, {
     message,
     ...(conversationId ? { conversation_id: conversationId } : {}),
-  });
+  }, jwt);
 }
 \`\`\`
 
@@ -3938,12 +4018,19 @@ export async function chatWithAgent(agentId: string, message: string, conversati
 
 - \`POST /v1/agents\` is the Tenant Dashboard endpoint — when configuring from
   your scaffolding script, use \`sk_live_*\`. End-user chat (\`/v1/user/agents/{id}/chat\`)
-  is reached with \`pk_live_*\` + the end-user's JWT.
+  is reached with \`pk_live_*\` (or \`sk_live_*\` on the server) + the end-user's
+  JWT (or the bot's, if you registered one in Step 0).
 - Tool calling vs RAG: for MVP / low-frequency catalog updates, RAG via KB is
   simpler. Switch to tool calling when the catalog updates faster than the
   refresh cadence you can sustain.
 - The bot does not write to the catalog and does not take orders unless you
-  add a separate tool / API path. Keep the system prompt strict.`;
+  add a separate tool / API path. Keep the system prompt strict.
+- **Fallback for MVP without an LLM** — if the project explicitly cannot
+  register a bot user (no email domain available yet), a deterministic
+  keyword-search bot over the catalog is acceptable. Implement \`/api/chat\` as
+  a server-side \`POST /v1/entity/records/search\` with the user's query as an
+  \`ilike\` filter. Not equivalent to the LLM bot but ships a working surface;
+  swap it for the LLM later.`;
 }
 const APP_SCAFFOLDS = {
     pos: {
@@ -3986,18 +4073,23 @@ const APP_SCAFFOLDS = {
             },
         ],
         build_order: [
-            "1. Next.js 16 app router + Tailwind + shadcn. Add `lib/genlobe.server.ts` with `import 'server-only'`.",
-            "2. Bootstrap script: create `product`, `customer`, `order` schemas via `get_entity_schema_recipe`. Bulk-seed 5-10 sample products.",
-            "3. Owner login: `/admin/login` → POST /v1/auth/login server-side → cookie httpOnly with JWT.",
-            "4. Owner CRUD products (single end-to-end vertical slice first).",
-            "5. Sales form (`/admin/sales/new`): customer autocomplete, multi-product line items, total auto-calc, POST one `order` record.",
-            "6. Sales list + detail.",
-            "7. Customers list + per-customer purchase history (cross-schema join from order → customer).",
-            "8. Dashboard KPIs (search + sum client-side; switch to server-side aggregates later if data grows).",
-            "9. Public storefront `/` + `/chat`. Bot via `get_chatbot_setup_recipe`.",
-            "10. Catalog refresh button in `/admin` (regenerates the KB document).",
+            "**0. Pre-flight.** Call `validate_credentials` to confirm sk_live_* and the org context. Restart any long-running uvicorn on the Genlobe backend if it predates today — the bulk endpoint is only available on backends started after the v3.6.2 merge.",
+            "**1. Scaffold a Next.js 16 app router project under `vendy-app/` (or similar).** Tailwind + shadcn. `pnpm dev -p 3100` so it doesn't collide with the Genlobe Tenant UI on 3000. Verify `.gitignore` lists `.env*.local`, `.env`, `node_modules`, `.next`.",
+            "**2. Create `lib/genlobe.server.ts` with `import 'server-only';` at the top.** Wrap fetch with X-API-Key + X-Organization-Id + optional JWT — see Section 10 of `get_authentication_flow`.",
+            "**3. `.env.local`**: SAAS_API_URL, SAAS_API_KEY (sk_live_*), SAAS_ORGANIZATION_ID, BOT_USER_EMAIL, BOT_USER_PASSWORD, STORE_NAME, STORE_CURRENCY. Once schemas are created in step 5, append PRODUCT_SCHEMA_ID, CUSTOMER_SCHEMA_ID, ORDER_SCHEMA_ID.",
+            "**4. Bot service-account user (Step 0 of `get_chatbot_setup_recipe`).** Register `bot@<your-shop>` via `POST /v1/auth/register`. Save credentials in `.env.local`. The server logs in this user on demand to obtain the chat JWT — never the human's.",
+            "**5. Bootstrap script (`scripts/bootstrap.ts`)**: idempotent. Reads each schema slug from `.env.local`; if missing, calls `get_entity_schema_recipe({entity_type:'product|customer|order'})` shape and `POST /v1/entity/schemas`; appends the returned id to `.env.local`. Then `POST /v1/entity/records/bulk` with 5-10 sample products in ONE call (this is the saboreo demo of bulk insert).",
+            "**6. Owner login**: `/admin/login` → server-side `POST /v1/auth/login` → set `genlobe_jwt` cookie httpOnly. Use the email the human gave you (NOT the bot user).",
+            "**7. Admin layout gate**: `app/(admin)/layout.tsx` reads `genlobe_jwt` cookie, redirects to `/admin/login` if missing.",
+            "**8. Products vertical slice end-to-end first**: list, create, edit, delete. Confirms the full stack works before fanning out to other entities.",
+            "**9. Sales (`/admin/sales/new`)**: customer autocomplete (search customers with `ilike`), product picker (paginated), line items with `name_snapshot` + `price_snapshot` per item, total auto-calc. POST one `order` record. Stock decrement is best-effort (continue if it fails — the sale is recorded).",
+            "**10. Sales list (`/admin/sales`) + per-customer history (`/admin/customers/{id}`)**: cross-schema join (`POST /v1/entity/records/search` with `join` clause on `customer_id`/`product_id`) to pull customer / product names in the same call.",
+            "**11. Dashboard KPIs (`/admin`)**: today's revenue, top 3 products, new customers this week. Client-side sums for MVP; flag any KPI taking >300ms as a candidate for server-side aggregation later.",
+            "**12. KB + bot setup (`scripts/sync-catalog-kb.ts`)**: snapshot the catalog to plain text, create KB with `rag_role: 'product_catalog'`, upload document, create the Store Assistant agent with the same `rag_role`. Add a button in `/admin` that re-runs this script when the catalog changes.",
+            "**13. Public storefront (`/`) + `/chat`**: storefront uses the catalog directly via a server route (no auth on the customer); `/chat` UI posts to `/api/chat` which calls `chatWithAgent(agentId, message, conversationId)` — JWT handled server-side by the cached bot login.",
+            "**14. Smoke**: open `http://localhost:3100`, place one test order, confirm it shows up in `/admin/sales`, ask the bot \"¿tienen X?\", verify it answers from the KB.",
         ],
-        notes: "Stock decrement on sale is intentionally NOT automatic — for MVP let the owner adjust stock manually after a sale, to avoid double-decrement bugs.",
+        notes: "Stock decrement on sale is intentionally NOT automatic to the level of a DB transaction — for MVP it is best-effort. If the stock UPDATE fails, the order is still saved. The owner reconciles manually. This avoids the double-decrement and partial-failure bugs that a naive transactional implementation hits without a row-lock primitive.\n\nReal-life pitfall (Vendy build, 2026-05-26): an agent built this 95% successfully but skipped the LLM bot setup because it mis-read the security guidance as 'no bot users allowed'. The Step 0 in `get_chatbot_setup_recipe` and the bot service-account clarification in `get_authentication_flow` exist to prevent that exact regression. If you find yourself building a keyword-search fallback because LLM 'isn't possible', re-read both — the LLM bot IS possible with one registered bot user, and the recipes spell out the ceremony.",
     },
     crm: {
         template: "crm",
@@ -4233,6 +4325,87 @@ ${s.notes ? `## Notes\n\n${s.notes}\n` : ""}
 - For the auth shape (sk_live_* / pk_live_* + cookies), call \`get_authentication_flow()\` and \`get_security_guide()\`.`;
 }
 // =============================================================================
+// Supabase → Genlobe migration recipe (G10 from the DX audit).
+// =============================================================================
+function SUPABASE_MIGRATION_RECIPE() {
+    return `# Supabase → Genlobe migration recipe
+
+Move a Supabase project's data into Genlobe. The tricky part is **users +
+foreign keys**; data tables are the easy part (bulk insert). Do it in this
+order so foreign keys never dangle.
+
+## Mental model (ADR-0012)
+
+- Genlobe \`users\` (native, auth) ← Supabase \`auth.users\`. Auth stays in the
+  native table; do NOT model users as a custom entity.
+- Genlobe custom entities ← Supabase \`public.*\` data tables.
+- One Genlobe **Organization = one namespace** (≈ a Supabase project). Your
+  app's *customers* are rows in a custom entity, NOT Organizations.
+
+## Step 1 — Import users FIRST (preserve UUIDs)
+
+\`\`\`http
+POST /v1/server/users/import        (sk_live_* — server/agent callable)
+\`\`\`
+\`\`\`json
+{
+  "organization_id": "<target org>",
+  "users": [
+    {
+      "id": "<the Supabase auth.users.id — PRESERVE IT>",
+      "email": "ada@shop.com",
+      "password_hash": "<Supabase encrypted_password — bcrypt, imported as-is>",
+      "profile_data": { "...": "from raw_user_meta_data" },
+      "is_email_verified": true,
+      "status": "active"
+    }
+  ]
+}
+\`\`\`
+
+- **Preserve \`id\`**: pass the Supabase UUID so every foreign key that pointed
+  at it stays valid. This is the single most important step.
+- **\`password_hash\`**: Supabase and Genlobe both use bcrypt, so the hash is
+  imported as-is — users keep their password, NO reset.
+- Capped at 500 per call, all-or-nothing. Chunk larger sets.
+
+## Step 2 — Create the entity schemas for the data tables
+
+For each Supabase \`public.<table>\`, define a custom entity schema. Use
+\`get_entity_schema_recipe\` for common shapes. Map a column that was a FK to
+\`auth.users\` as a \`reference\` field with \`target_schema_slug: "users"\`
+(ADR-0009) — it validates against the native users table.
+
+\`POST /v1/entity/schemas\` (one per table). Valid field types: string, text,
+integer, float, boolean, datetime, enum, email, url, phone, reference.
+(No \`array\`, no \`number\` — see get_entity_schema_recipe.)
+
+## Step 3 — Bulk-insert the rows
+
+\`\`\`http
+POST /v1/entity/records/bulk
+\`\`\`
+Because you preserved user UUIDs in Step 1, any \`reference→users\` field in
+these rows already points at a valid user. For FKs between data tables,
+preserve those source ids too (store them in a field) or rewrite them with a
+mapping you keep while importing.
+
+## Step 4 — Verify
+
+- Spot-check: a migrated user can log in with their old password.
+- A migrated row's \`reference→users\` resolves (the user exists).
+- Counts match the Supabase source.
+
+## Auth for the import endpoints
+
+All three steps accept \`sk_live_*\` from a server/agent:
+- Users: \`POST /v1/server/users/import\` (server-scoped, sk_live_*). The
+  dashboard variant \`POST /v1/dashboard/organizations/users/import\` (TenantMember
+  auth) does the same thing for a human in the dashboard.
+- Schemas: \`POST /v1/entity/schemas\`.
+- Rows: \`POST /v1/entity/records/bulk\`.`;
+}
+// =============================================================================
 // MCP Server Implementation
 // =============================================================================
 const server = new Server({
@@ -4570,6 +4743,24 @@ developer says "I want to build X" before writing code.`,
                     required: ["template"],
                 },
             },
+            {
+                name: "get_supabase_migration_recipe",
+                description: `Step-by-step recipe to migrate a Supabase project into Genlobe (G10). Covers the tricky part — users + foreign keys — in the correct order: import users FIRST preserving their UUIDs (so FKs stay valid) and their bcrypt password hash (Supabase + Genlobe both use bcrypt — no password reset), then create entity schemas mapping FK columns to reference fields (target_schema_slug: "users"), then bulk-insert rows. Explains the ADR-0012 mental model (Organization = namespace; your app's customers are rows, not Organizations). Pure data; no network call.`,
+                inputSchema: { type: "object", properties: {}, required: [] },
+            },
+            {
+                name: "invite_organization_owner",
+                description: `Invite the owner of an Organization (F2/F4). Creates the owner end-user and EMAILS them their sign-in credentials. The agent NEVER sees the password — it is delivered by email only (MCP "no raw secrets" invariant). Ask the human for the owner's REAL email; never invent one (a bounced address gets SES-suppressed — incident #168). Requires sk_live_*. Returns { user_id, email, email_sent }. If email_sent is false, tell the human to grab the temporary credential from the Tenant Dashboard. Calls POST /v1/server/organizations/invite-owner.`,
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        organization_id: { type: "string", description: "UUID of the Organization the owner will administer." },
+                        email: { type: "string", description: "The owner's REAL email address. Ask the human — never fabricate it." },
+                        display_name: { type: "string", description: "Optional display name for the owner." },
+                    },
+                    required: ["organization_id", "email"],
+                },
+            },
         ],
     };
 });
@@ -4980,6 +5171,12 @@ Use search_endpoints tool to find available endpoints.`,
 > 2. **Do NOT register a new end-user with an email you generated.** Inventing an email (e.g. \`admin@<their-domain>\`, \`seed@<their-domain>\`) leads to bounces. AWS SES then suppresses the address at the account level and locks the tenant out of email delivery for that destination — recovery requires manual operator action. This is exactly how production incident #168 happened.
 > 3. **Schemas don't need a JWT.** \`/v1/entity/schemas\` is a tenant-admin operation: \`sk_live_*\` alone is enough (see issue #177). Read \`get_endpoint_details\` for the schemas endpoint before assuming you need to register a user.
 > 4. If the human says \"register a user with this email: ...\" — fine, that's an explicit instruction. Inventing one is not.
+>
+> ### Bot service-account user (LLM chat surface)
+>
+> **Public chatbot surfaces are an exception that is fully permitted**: you can — and should — register **one real bot service-account user** to obtain the JWT the agent chat endpoint requires. The human is implicitly authorizing this when they ask for "an LLM chatbot the customers can use". Use a real email you control (e.g. \`bot@<their-shop-domain>\` or a personal mailbox). Save the credentials in the server-side env (\`.env.local\` with \`BOT_USER_EMAIL\` + \`BOT_USER_PASSWORD\`), log in server-side, attach the JWT to incoming chat requests. See \`get_chatbot_setup_recipe()\` Step 0 for the full ceremony.
+>
+> Registering **one** bot account is not the same thing as "inventing emails in bulk" — that distinction matters.
 
 ---
 
@@ -5207,7 +5404,122 @@ await fetch('/v1/auth/logout', {
 
 localStorage.removeItem('access_token');
 localStorage.removeItem('refresh_token');
-\`\`\``,
+\`\`\`
+
+---
+
+## 10. Server-side auth pattern (sk_live_* + cookies httpOnly) — Next.js App Router
+
+When the app uses a **secret key** (\`sk_live_*\`), the browser must never see the key OR the API base URL. All Genlobe calls go through your own \`/api/*\` routes on the Next.js server. End-user sessions are kept in **httpOnly cookies**, not \`localStorage\`.
+
+### Project layout (recommended)
+
+\`\`\`
+app/
+├─ (admin)/                    Owner dashboard, gated
+│  ├─ layout.tsx               Reads cookie, redirects to /admin/login if missing
+│  ├─ admin/login/page.tsx
+│  └─ admin/page.tsx
+├─ (public)/                   No auth, anonymous customer surface
+│  ├─ page.tsx                 Storefront / POS / catalog
+│  └─ chat/page.tsx            Public chatbot UI
+├─ api/
+│  ├─ admin/login/route.ts     POST → server-side call to /v1/auth/login, sets cookie
+│  ├─ admin/logout/route.ts    Clears cookie
+│  └─ chat/route.ts            POST → server-side call to /v1/user/agents/{id}/chat with bot JWT
+└─ middleware.ts               Gates (admin)/*; refreshes bot JWT in background
+lib/
+└─ genlobe.server.ts           'server-only', wraps the API
+.env.local                     SAAS_API_URL, SAAS_API_KEY, SAAS_ORGANIZATION_ID, BOT_USER_EMAIL, BOT_USER_PASSWORD
+\`\`\`
+
+### lib/genlobe.server.ts
+
+\`\`\`typescript
+import 'server-only';
+
+const API = process.env.SAAS_API_URL!;            // e.g. http://localhost:8001
+const KEY = process.env.SAAS_API_KEY!;            // sk_live_*  — server only
+const ORG = process.env.SAAS_ORGANIZATION_ID!;    // organization scope
+
+export async function genlobeApi<T = any>(
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+  path: string,
+  body?: any,
+  jwt?: string
+): Promise<T> {
+  const res = await fetch(\`\${API}\${path}\`, {
+    method,
+    headers: {
+      'Content-Type': 'application/json',
+      'X-API-Key': KEY,
+      'X-Organization-Id': ORG,
+      ...(jwt ? { Authorization: \`Bearer \${jwt}\` } : {}),
+    },
+    body: body ? JSON.stringify(body) : undefined,
+    cache: 'no-store',
+  });
+  if (!res.ok) throw new Error(\`Genlobe \${res.status}: \${await res.text()}\`);
+  return res.json();
+}
+\`\`\`
+
+### app/api/admin/login/route.ts
+
+\`\`\`typescript
+import { NextResponse } from 'next/server';
+import { cookies } from 'next/headers';
+import { genlobeApi } from '@/lib/genlobe.server';
+
+export async function POST(req: Request) {
+  const { email, password } = await req.json();
+  const { access_token, refresh_token, user } = await genlobeApi(
+    'POST',
+    '/v1/auth/login',
+    { email, password }
+  );
+
+  const jar = cookies();
+  jar.set('genlobe_jwt', access_token, {
+    httpOnly: true, secure: process.env.NODE_ENV === 'production',
+    sameSite: 'lax', path: '/', maxAge: 60 * 60 * 24,
+  });
+  jar.set('genlobe_refresh', refresh_token, {
+    httpOnly: true, secure: process.env.NODE_ENV === 'production',
+    sameSite: 'lax', path: '/', maxAge: 60 * 60 * 24 * 30,
+  });
+
+  return NextResponse.json({ user });
+}
+\`\`\`
+
+### app/(admin)/layout.tsx (gate)
+
+\`\`\`typescript
+import { cookies } from 'next/headers';
+import { redirect } from 'next/navigation';
+
+export default async function AdminLayout({ children }: { children: React.ReactNode }) {
+  const jwt = cookies().get('genlobe_jwt')?.value;
+  if (!jwt) redirect('/admin/login');
+  return <>{children}</>;
+}
+\`\`\`
+
+### .gitignore (critical)
+
+\`\`\`
+.env*.local
+.env
+\`\`\`
+
+Next.js boilerplate puts this in by default if you used \`create-next-app\`. **Always verify it before the first commit** — the \`sk_live_*\` and \`BOT_USER_PASSWORD\` live in \`.env.local\` and must never leave your machine.
+
+### Three rules that keep this safe
+
+1. \`SAAS_API_KEY\` env var is **never** prefixed with \`NEXT_PUBLIC_\`. Same for \`BOT_USER_PASSWORD\` and \`SAAS_ORGANIZATION_ID\`.
+2. The wrapper file (\`lib/genlobe.server.ts\`) starts with \`import 'server-only'\`. If a client component ever imports it, the Next.js build fails with a clear message — that's the contract.
+3. The browser only talks to *your* \`/api/*\` routes, never to the Genlobe host directly.`,
                         },
                     ],
                 };
@@ -5640,6 +5952,41 @@ type to pick.`,
                     content: [{ type: "text", text: APP_SCAFFOLD(template) }],
                 };
             }
+            case "get_supabase_migration_recipe": {
+                return {
+                    content: [{ type: "text", text: SUPABASE_MIGRATION_RECIPE() }],
+                };
+            }
+            case "invite_organization_owner": {
+                if (!API_KEY) {
+                    return {
+                        content: [{ type: "text", text: `❌ Cannot invite owner: SAAS_API_KEY is not configured. A secret key (sk_live_*) is required.` }],
+                    };
+                }
+                const { organization_id, email, display_name } = args;
+                try {
+                    const r = await fetch(`${API_URL}/v1/server/organizations/invite-owner`, {
+                        method: "POST",
+                        headers: { "X-API-Key": API_KEY, "Content-Type": "application/json" },
+                        body: JSON.stringify({ organization_id, email, display_name }),
+                    });
+                    const body = await r.json();
+                    if (!r.ok) {
+                        return {
+                            content: [{ type: "text", text: `HTTP ${r.status} from /v1/server/organizations/invite-owner — ${body.detail ?? JSON.stringify(body)}.\n\nNeeds a secret key (sk_live_*). The org must belong to this key's tenant.` }],
+                        };
+                    }
+                    const note = body.email_sent
+                        ? "✅ The owner has been emailed their sign-in credentials. They can now sign in at the Org Owner Dashboard and change their password."
+                        : "⚠️ Owner created, but the credentials email could NOT be sent (SMTP not configured). Ask the human to retrieve the temporary credential from the Tenant Dashboard → Organizations → invite owner. The password is never exposed here.";
+                    return {
+                        content: [{ type: "text", text: `Owner invited.\n${JSON.stringify(body, null, 2)}\n\n${note}` }],
+                    };
+                }
+                catch (err) {
+                    return { content: [{ type: "text", text: `Network error: ${err}` }] };
+                }
+            }
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genlobe/mcp-server",
-  "version": "3.7.1",
+  "version": "3.8.0",
   "description": "MCP Server for GenLobe SaaS API - Provides AI assistants with comprehensive API documentation for building frontend applications",
   "main": "dist/index.js",
   "bin": {