@genlobe/mcp-server 3.7.2 → 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
@@ -4299,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({
@@ -4636,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"],
+                },
+            },
         ],
     };
 });
@@ -5827,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.2",
+  "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": {