@genlobe/mcp-server 3.6.2 → 3.7.1

package/dist/index.js

@@ -3497,6 +3497,741 @@ has a different shape because of where the API key can safely live.`,
     const body = sections[appType] ?? sections["unsure"];
     return `# Stack recommendation\n\n${keyLine}\n\n${body}\n\n---\n\nRun \`get_security_guide\` for the full security cheat-sheet that matches your key type.`;
 }
+const ENTITY_SCHEMA_RECIPES = {
+    product: {
+        slug: "product",
+        name: "Product",
+        description: "Catalog product with price, stock, category, description.",
+        fields_definition: {
+            name: { type: "string", required: true, max_length: 200 },
+            price: { type: "float", required: true, min: 0 },
+            stock: { type: "integer", required: true, min: 0, default: 0 },
+            currency: { type: "string", required: false, default: "USD", max_length: 3 },
+            category: { type: "string", required: false, max_length: 100 },
+            description: { type: "text", required: false },
+            is_active: { type: "boolean", required: false, default: true },
+        },
+        bulk_seed_example: [
+            { name: "Sugar 1kg", price: 2.5, stock: 100, category: "groceries" },
+            { name: "Rice 1kg", price: 3.0, stock: 50, category: "groceries" },
+            { name: "Coffee 250g", price: 6.75, stock: 30, category: "groceries" },
+        ],
+        notes: "If you need product variants (size/color), keep `name` for the base product and add a separate `variant` entity with a `product_id` reference (type=reference, target_schema_slug='product').",
+    },
+    customer: {
+        slug: "customer",
+        name: "Customer",
+        description: "Store-side customer record (NOT a Genlobe end-user — those go through /v1/auth/register). Use this when you want to track purchases without forcing email signup.",
+        fields_definition: {
+            name: { type: "string", required: true, max_length: 200 },
+            phone: { type: "string", required: false, max_length: 50 },
+            email: { type: "email", required: false, max_length: 200 },
+            notes: { type: "text", required: false },
+            tags: { type: "text", required: false },
+        },
+        bulk_seed_example: [
+            { name: "Ana Pérez", phone: "+1-809-555-0100" },
+            { name: "Walk-in", notes: "no-data anonymous buyer" },
+        ],
+        notes: "Common mistake: registering each store customer as a Genlobe end-user. Don't — that requires real email + SES delivery. Keep store customers as this custom entity unless they need to log into the storefront. `tags` is a comma-separated string (the schema validator does NOT support `array` as a field type — see the global notes at the top of every recipe).",
+    },
+    order: {
+        slug: "order",
+        name: "Order / Sale",
+        description: "A completed sale with line items (price + name snapshotted at the time of sale, so editing a product later does NOT mutate past orders).",
+        fields_definition: {
+            customer_id: {
+                type: "reference",
+                target_schema_slug: "customer",
+                required: false,
+                on_delete: "set_null",
+            },
+            items_json: {
+                type: "text",
+                required: true,
+            },
+            total: { type: "float", required: true, min: 0 },
+            currency: { type: "string", required: false, default: "USD" },
+            paid: { type: "boolean", required: true, default: false },
+            paid_at: { type: "datetime", required: false },
+            notes: { type: "text", required: false },
+        },
+        notes: "**Line items modeling — important.** Genlobe's schema validator does NOT support `array` as a field type (validated types: string, integer, float, boolean, datetime, text, enum, email, url, phone, reference). Two ways to model line items:\n\n**Option A — simple, recommended for MVP**: store the items as a JSON string in `items_json` (type=text). Parse client-side. Each item should already include `product_id`, `name_snapshot`, `price_snapshot`, `qty`. Trade-off: you cannot search/filter by items via `POST /v1/entity/records/search` — items are opaque to the engine.\n\n**Option B — queryable, for production**: create a separate `order_item` schema with `order_id: reference->order`, `product_id: reference->product`, `name_snapshot`, `price_snapshot`, `qty`. Cross-schema joins (ADR-0009) make `\"top 5 products sold this month\"` a single search call.\n\nEither way: **always snapshot `name` and `price` at write time** so editing the product later does NOT mutate past orders.",
+    },
+    post: {
+        slug: "post",
+        name: "Blog post / Article",
+        description: "Authored content with title, body, status, tags.",
+        fields_definition: {
+            title: { type: "string", required: true, max_length: 200 },
+            slug: { type: "string", required: true, max_length: 200 },
+            body: { type: "string", required: true },
+            status: {
+                type: "string",
+                required: true,
+                enum: ["draft", "published", "archived"],
+                default: "draft",
+            },
+            tags: { type: "text", required: false },
+            published_at: { type: "datetime", required: false },
+            cover_image_url: { type: "string", required: false },
+        },
+        notes: "`created_by_id` is the author (auto-stamped by the API from the JWT, no need to include in records). For multi-author orgs the elevated-role bypass on /v1/entity/records/search lets editors see everyone's posts.",
+    },
+    comment: {
+        slug: "comment",
+        name: "Comment",
+        description: "User-authored comment that points at another record (post, product, order, anything).",
+        fields_definition: {
+            target_id: {
+                type: "string",
+                required: true,
+                notes: "UUID of the commented record. Not a reference field because the target schema varies — store the target schema slug in `target_schema` if you need polymorphism.",
+            },
+            target_schema: { type: "string", required: true, max_length: 100 },
+            body: { type: "string", required: true },
+            is_deleted: { type: "boolean", required: false, default: false },
+        },
+        notes: "Polymorphic targets defeat the ADR-0009 `reference` validator. If your comments only ever point at ONE schema (e.g. `post`), drop `target_schema` and convert `target_id` to a proper reference for FK integrity.",
+    },
+    message: {
+        slug: "message",
+        name: "Chat / direct message",
+        description: "A single message in a conversation. Pair with the native `conversations` table (Genlobe AI agents) or roll your own thread entity.",
+        fields_definition: {
+            conversation_id: { type: "string", required: true },
+            sender_user_id: { type: "string", required: false },
+            sender_role: {
+                type: "string",
+                required: true,
+                enum: ["user", "assistant", "system"],
+            },
+            body: { type: "string", required: true },
+            read_at: { type: "datetime", required: false },
+        },
+        notes: "If you're building a chatbot powered by a Genlobe agent, you do NOT need this entity — agent conversations are persisted automatically (see `/v1/user/agents/{id}/conversations`). Use this only for human-to-human messaging.",
+    },
+    task: {
+        slug: "task",
+        name: "Task / To-do",
+        description: "Single task with title, status, due date, assignee.",
+        fields_definition: {
+            title: { type: "string", required: true, max_length: 200 },
+            description: { type: "string", required: false },
+            status: {
+                type: "string",
+                required: true,
+                enum: ["pending", "in_progress", "completed", "cancelled"],
+                default: "pending",
+            },
+            priority: {
+                type: "string",
+                required: false,
+                enum: ["low", "medium", "high"],
+                default: "medium",
+            },
+            assigned_to_id: {
+                type: "reference",
+                target_schema_slug: "users",
+                required: false,
+                on_delete: "set_null",
+            },
+            due_date: { type: "datetime", required: false },
+        },
+        notes: "`assigned_to_id` references the native `users` table (Genlobe end-users), not a custom entity. The reference validator enforces `OrganizationMember` active membership server-side.",
+    },
+    note: {
+        slug: "note",
+        name: "Personal note",
+        description: "A free-text note owned by the creator. Row-level scope means each end-user only sees their own notes via /v1/entity/records/mine.",
+        fields_definition: {
+            title: { type: "string", required: false, max_length: 200 },
+            body: { type: "string", required: true },
+            tags: { type: "text", required: false },
+            is_pinned: { type: "boolean", required: false, default: false },
+        },
+        notes: "Perfect for ADR-0007 row-level scope: regular end-users see only their own notes via `GET /v1/entity/records/mine` (no extra filter needed in the frontend).",
+    },
+};
+function ENTITY_SCHEMA_RECIPE(entityType) {
+    const recipe = ENTITY_SCHEMA_RECIPES[entityType];
+    if (!recipe) {
+        return `# Unknown entity_type "${entityType}"\n\nAvailable: ${Object.keys(ENTITY_SCHEMA_RECIPES).join(", ")}.`;
+    }
+    const postBody = {
+        name: recipe.name,
+        slug: recipe.slug,
+        description: recipe.description,
+        fields_definition: recipe.fields_definition,
+    };
+    const bulkBody = recipe.bulk_seed_example
+        ? {
+            schema_id: "<paste the id returned by POST /v1/entity/schemas above>",
+            records: recipe.bulk_seed_example,
+        }
+        : null;
+    return `# Entity schema recipe — ${recipe.name}
+
+${recipe.description}
+
+## Schema field types — what the backend actually accepts
+
+The Custom Entities validator only accepts these types in \`fields_definition\`:
+
+\`string\`, \`text\`, \`integer\`, \`float\`, \`boolean\`, \`datetime\`, \`enum\`, \`email\`, \`url\`, \`phone\`, \`reference\` (ADR-0009).
+
+**There is no \`array\` type and no \`number\` type.** Use \`integer\`/\`float\` instead of \`number\`. For list-shaped data either (a) store as a comma-separated \`text\` (simple, not queryable), or (b) model as a separate entity with a \`reference\` field pointing back (queryable, ADR-0009 cross-schema search).
+
+## Step 1 — Create the schema
+
+\`\`\`http
+POST /v1/entity/schemas
+Content-Type: application/json
+X-API-Key: <your sk_live_*>
+X-Organization-Id: <your organization_id>
+\`\`\`
+
+Body:
+\`\`\`json
+${JSON.stringify(postBody, null, 2)}
+\`\`\`
+
+${bulkBody
+        ? `## Step 2 — Seed sample rows (bulk)
+
+\`\`\`http
+POST /v1/entity/records/bulk
+Content-Type: application/json
+X-API-Key: <your sk_live_*>
+X-Organization-Id: <your organization_id>
+\`\`\`
+
+Body:
+\`\`\`json
+${JSON.stringify(bulkBody, null, 2)}
+\`\`\`
+
+Bulk insert is capped at 500 records per call; chunk larger migrations.
+All-or-nothing: any validation failure rolls back the whole batch.
+`
+        : ""}
+${recipe.notes ? `## Notes\n\n${recipe.notes}\n` : ""}
+
+---
+
+**Before posting**, call \`get_reserved_schema_slugs()\` to confirm \`${recipe.slug}\` is not on the reserved list. It is not, today, but slug-collision checking is part of the contract.`;
+}
+// =============================================================================
+// Chatbot setup recipe (v3.7.0) — closes G2.
+// =============================================================================
+function CHATBOT_SETUP_RECIPE() {
+    return `# Chatbot setup recipe — agent + KB bound by \`rag_role\`
+
+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)
+
+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):
+
+- **(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.
+
+**What is NOT allowed** (and what some agents mis-read as "no LLM bot is
+possible"): inventing/synthesizing fake email addresses to bulk-create
+end-users on the fly. That bypass would route through SES and burn the
+sender reputation — exactly the incident pattern of #168. Registering one
+or a few real bot accounts that you actually own is fine.
+
+If you cannot or do not want to register a bot user, an acceptable fallback
+for MVP is a deterministic keyword search over the catalog (no LLM, no JWT
+required) — useful when the storefront has to be live before you set up the
+LLM layer. The bot user path is still the canonical way to get a real LLM bot.
+
+## Architecture in one diagram
+
+\`\`\`
+  Custom-entity catalog
+  (e.g. products)
+        │
+        │ 1. snapshot to plain text
+        ▼
+  KnowledgeBase (per-Org)
+        │
+        │ 2. uploaded as a Document
+        ▼
+  Agent (rag_role bound to KB)   ←─  end-user chats
+                                     /v1/user/agents/{id}/chat
+\`\`\`
+
+## Step-by-step
+
+### 1. Create the KnowledgeBase
+
+\`\`\`http
+POST /v1/organization-admin/{org_id}/knowledge-bases
+\`\`\`
+
+Body:
+\`\`\`json
+{
+  "name": "Vendy catalog",
+  "description": "Snapshot of products, updated on demand",
+  "rag_role": "product_catalog"
+}
+\`\`\`
+
+Save the returned \`kb_id\`. The \`rag_role\` value is the binding key — the
+agent will reference the same role string to find this KB at chat time.
+
+### 2. Snapshot your catalog and upload it as a Document
+
+Pull every product record:
+
+\`\`\`http
+POST /v1/entity/records/search
+\`\`\`
+
+Body: \`{ "schema_id": "<your product schema id>", "query": { "is_active": true } }\`
+
+Format each row as one paragraph the LLM can read:
+
+\`\`\`text
+Product: Sugar 1kg
+Price: $2.50
+Stock: 100
+Category: groceries
+Description: white sugar in 1kg bags
+---
+Product: Rice 1kg
+...
+\`\`\`
+
+Upload as a document:
+
+\`\`\`http
+POST /v1/organization-admin/{org_id}/knowledge-bases/{kb_id}/documents
+\`\`\`
+
+Body:
+\`\`\`json
+{
+  "title": "Catalog snapshot 2026-05-26",
+  "content": "<the multi-paragraph text from above>",
+  "metadata": { "source": "catalog_snapshot", "snapshotted_at": "<ISO timestamp>" }
+}
+\`\`\`
+
+### 3. Create the Agent
+
+\`\`\`http
+POST /v1/agents
+\`\`\`
+
+Body:
+\`\`\`json
+{
+  "name": "Vendy Assistant",
+  "description": "Answers customer questions about the store catalog.",
+  "system_prompt": "You are a helpful store assistant for Vendy. Answer ONLY about products in the catalog you have access to. If the customer asks about anything else (delivery, billing, hours), reply that you can only help with product questions. Never invent products or prices.",
+  "is_public": true,
+  "rag_role": "product_catalog"
+}
+\`\`\`
+
+\`is_public: true\` lets every end-user of the Org talk to the same agent (no
+per-user fork). \`rag_role: "product_catalog"\` is the binding to the KB
+created in step 1.
+
+### 4. End-user chat (frontend)
+
+\`\`\`http
+POST /v1/user/agents/{agent_id}/chat
+\`\`\`
+
+Body:
+\`\`\`json
+{
+  "message": "do you have rice?",
+  "conversation_id": "<optional, persist in sessionStorage to keep context>"
+}
+\`\`\`
+
+Returns the assistant's response plus a \`conversation_id\` you should pass on
+subsequent messages to keep the same thread.
+
+## Refresh policy
+
+When products change (price update, new SKU), regenerate the snapshot text
+and either:
+
+- **Replace the document** (\`DELETE /v1/organization-admin/{org_id}/knowledge-bases/{kb_id}/documents/{doc_id}\` then re-upload) — simplest.
+- **Append a delta document** (\`POST\` a new document with only the changes) — faster but you need to manage stale entries.
+
+For an MVP the first option is what we recommend.
+
+## Server-side TypeScript snippet
+
+\`\`\`typescript
+// lib/genlobe.server.ts
+import 'server-only';
+
+const API = process.env.SAAS_API_URL!;
+const KEY = process.env.SAAS_API_KEY!; // sk_live_*
+const ORG = process.env.SAAS_ORGANIZATION_ID!;
+
+async function api(path: string, body: any, jwt?: string) {
+  const res = await fetch(\`\${API}\${path}\`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-API-Key': KEY,
+      'X-Organization-Id': ORG,
+      ...(jwt ? { 'Authorization': \`Bearer \${jwt}\` } : {}),
+    },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) throw new Error(\`\${res.status} \${await res.text()}\`);
+  return res.json();
+}
+
+export async function refreshCatalogKB(productSchemaId: string, kbId: string, existingDocId?: string) {
+  const { records } = await api('/v1/entity/records/search', {
+    schema_id: productSchemaId,
+    query: { is_active: true },
+  });
+  const content = records
+    .map((r: any) =>
+      \`Product: \${r.data.name}\\nPrice: $\${r.data.price}\\nStock: \${r.data.stock}\\nCategory: \${r.data.category ?? 'n/a'}\\nDescription: \${r.data.description ?? ''}\`
+    )
+    .join('\\n---\\n');
+
+  if (existingDocId) {
+    await fetch(\`\${API}/v1/organization-admin/\${ORG}/knowledge-bases/\${kbId}/documents/\${existingDocId}\`, {
+      method: 'DELETE',
+      headers: { 'X-API-Key': KEY, 'X-Organization-Id': ORG },
+    });
+  }
+  return api(\`/v1/organization-admin/\${ORG}/knowledge-bases/\${kbId}/documents\`, {
+    title: \`Catalog snapshot \${new Date().toISOString()}\`,
+    content,
+    metadata: { source: 'catalog_snapshot' },
+  });
+}
+
+export async function chatWithAgent(agentId: string, message: string, conversationId?: string) {
+  return api(\`/v1/user/agents/\${agentId}/chat\`, {
+    message,
+    ...(conversationId ? { conversation_id: conversationId } : {}),
+  });
+}
+\`\`\`
+
+## Notes
+
+- \`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.
+- 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.`;
+}
+const APP_SCAFFOLDS = {
+    pos: {
+        template: "pos",
+        title: "POS / small-store register",
+        description: "A storefront with a chatbot for product questions and an owner dashboard for products, customers, sales.",
+        entities: [
+            { slug: "product", recipe_key: "product", purpose: "Catalog the owner manages." },
+            {
+                slug: "customer",
+                recipe_key: "customer",
+                purpose: "Store-side customer record (NOT a Genlobe end-user).",
+            },
+            {
+                slug: "order",
+                recipe_key: "order",
+                purpose: "Completed sales with snapshotted line items (FK to product + customer).",
+            },
+        ],
+        agents: [
+            {
+                name: "Store Assistant",
+                rag_role: "product_catalog",
+                purpose: "Answers customer questions about the product catalog. Read-only.",
+            },
+        ],
+        kbs: [{ rag_role: "product_catalog", source: "Snapshot of `product` records" }],
+        kpis: [
+            {
+                name: "Today's revenue",
+                how: "POST /v1/entity/records/search with `query: { paid: true, paid_at: { operator: 'gte', value: <today_iso> } }`, sum `data.total` client-side.",
+            },
+            {
+                name: "Top product this month",
+                how: "Search orders, flatten `items[]`, group by `product_id`, sum `qty`. Cross-schema `join` with `product` to get the name in the same call.",
+            },
+            {
+                name: "New customers this week",
+                how: "Search customers with `created_at` filter; show count + names.",
+            },
+        ],
+        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).",
+        ],
+        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.",
+    },
+    crm: {
+        template: "crm",
+        title: "Lightweight CRM",
+        description: "Track contacts, deals, notes, and a sales pipeline. No marketing automation, no email integration — that's later.",
+        entities: [
+            { slug: "customer", recipe_key: "customer", purpose: "Contact records." },
+            {
+                slug: "deal",
+                recipe_key: "order",
+                purpose: "Reuse the `order` recipe but rename to `deal`; line items become deliverables and `paid` becomes `closed_won`.",
+            },
+            {
+                slug: "note",
+                recipe_key: "note",
+                purpose: "Free-text notes per contact (rename `note` → `interaction` if you want to scope it to the contact).",
+            },
+        ],
+        agents: [
+            {
+                name: "CRM Helper",
+                purpose: "Internal-only agent that drafts follow-up emails based on the most recent notes on a contact. No KB needed; works with conversation context.",
+            },
+        ],
+        kbs: [],
+        kpis: [
+            { name: "Open pipeline value", how: "Search deals where `closed_won: false`, sum `total`." },
+            {
+                name: "Conversion rate",
+                how: "Count deals `closed_won: true` / total deals over a period.",
+            },
+            {
+                name: "Stale contacts",
+                how: "Customers with no `note` records in the last 30 days (cross-schema NOT-EXISTS).",
+            },
+        ],
+        build_order: [
+            "1. Same bootstrap as POS.",
+            "2. Customer CRUD (list + detail + edit).",
+            "3. Notes per customer (reference field to customer).",
+            "4. Deals pipeline view (kanban by `status`).",
+            "5. CRM Helper agent (no KB) for drafting follow-ups.",
+        ],
+        notes: "If you want incoming email parsing, that's a Stage-3 deploy capability — not in MVP.",
+    },
+    blog: {
+        template: "blog",
+        title: "Multi-author blog",
+        description: "Posts, comments, tags. Public read, authenticated write.",
+        entities: [
+            { slug: "post", recipe_key: "post", purpose: "Articles." },
+            { slug: "comment", recipe_key: "comment", purpose: "User comments on posts." },
+        ],
+        agents: [
+            {
+                name: "Blog Recommender",
+                rag_role: "blog_archive",
+                purpose: "Suggests related posts based on what the reader is browsing.",
+            },
+        ],
+        kbs: [{ rag_role: "blog_archive", source: "Snapshot of published `post` records" }],
+        kpis: [
+            { name: "Posts published this month", how: "Search posts where `status: published`, count." },
+            {
+                name: "Most commented post",
+                how: "Search comments, group by `target_id`, count, cross-schema join with `post` for the title.",
+            },
+        ],
+        build_order: [
+            "1. Bootstrap.",
+            "2. Post CRUD (admin only — gate with role check).",
+            "3. Public reader view (`/blog/[slug]`) with comments form.",
+            "4. Comments moderation page.",
+            "5. Recommender bot via KB.",
+        ],
+    },
+    task_manager: {
+        template: "task_manager",
+        title: "Personal / team task manager",
+        description: "To-do list with assignees, due dates, and status. Per-user view by default (ADR-0007 row-level scope).",
+        entities: [{ slug: "task", recipe_key: "task", purpose: "Tasks." }],
+        agents: [
+            {
+                name: "Task Coach",
+                purpose: "Suggests next-best task based on due dates and priorities (no KB; uses context).",
+            },
+        ],
+        kbs: [],
+        kpis: [
+            {
+                name: "My open tasks",
+                how: "GET /v1/entity/records/mine?schema_id=<task> — returns only the caller's tasks via row-level scope, no extra filter.",
+            },
+            {
+                name: "Overdue tasks (team)",
+                how: "Search tasks where `due_date < now` AND `status != completed`. Elevated role only.",
+            },
+        ],
+        build_order: [
+            "1. Bootstrap.",
+            "2. End-user signup + login (`pk_live_*` + JWT flow).",
+            "3. `/tasks` list using `GET /v1/entity/records/mine`.",
+            "4. Create / edit task.",
+            "5. Coach bot.",
+        ],
+        notes: "Use `GET /v1/entity/records/mine` instead of POST /search with `created_by_id` filter — row-level scope is enforced server-side, the frontend MUST NOT be the filter.",
+    },
+    notes: {
+        template: "notes",
+        title: "Personal notes app",
+        description: "Free-text notes per user, scoped to the author. Inspired by Apple Notes / Bear.",
+        entities: [{ slug: "note", recipe_key: "note", purpose: "Notes." }],
+        agents: [
+            {
+                name: "Notes Search",
+                rag_role: "user_notes",
+                purpose: "Semantic search across the user's notes. Per-user KB scoped via row-level scope on the search side.",
+            },
+        ],
+        kbs: [
+            {
+                rag_role: "user_notes",
+                source: "Each user's notes uploaded as one document per note. Could also be one consolidated doc per user, refreshed on each save.",
+            },
+        ],
+        kpis: [
+            { name: "Total notes", how: "GET /v1/entity/records/mine — count." },
+            { name: "Pinned", how: "GET /v1/entity/records/mine with `is_pinned: true` filter." },
+        ],
+        build_order: [
+            "1. Bootstrap + end-user auth.",
+            "2. Note CRUD (`/v1/entity/records/mine` for the list).",
+            "3. Search bot per user.",
+            "4. Pin / tag filters.",
+        ],
+    },
+    support_inbox: {
+        template: "support_inbox",
+        title: "Customer support inbox",
+        description: "Capture support tickets, route to agents, let an AI first-responder handle FAQs before escalation.",
+        entities: [
+            {
+                slug: "ticket",
+                recipe_key: "task",
+                purpose: "Reuse `task` recipe. Rename `task` → `ticket`. `assigned_to_id` becomes the support agent (human end-user).",
+            },
+            {
+                slug: "message",
+                recipe_key: "message",
+                purpose: "Conversation thread per ticket.",
+            },
+        ],
+        agents: [
+            {
+                name: "First Responder",
+                rag_role: "support_kb",
+                purpose: "Answers from the support knowledge base before escalating to a human.",
+            },
+        ],
+        kbs: [
+            {
+                rag_role: "support_kb",
+                source: "Help docs / FAQs. Upload manually or sync from your existing help center.",
+            },
+        ],
+        kpis: [
+            { name: "Open tickets", how: "Search tickets where `status != completed`." },
+            {
+                name: "Avg time to first response",
+                how: "For each ticket, find the first `message` where `sender_role != 'user'`, compute delta. Aggregate client-side.",
+            },
+        ],
+        build_order: [
+            "1. Bootstrap.",
+            "2. Public form (`/contact`) that creates a `ticket` + an initial `message`.",
+            "3. Internal queue view (`/support/inbox`).",
+            "4. First Responder bot, with escalation flag.",
+            "5. SLA dashboard.",
+        ],
+    },
+};
+function APP_SCAFFOLD(template) {
+    const s = APP_SCAFFOLDS[template];
+    if (!s) {
+        return `# Unknown template "${template}"\n\nAvailable: ${Object.keys(APP_SCAFFOLDS).join(", ")}.`;
+    }
+    const entitySection = s.entities
+        .map((e) => `- **\`${e.slug}\`** — ${e.purpose} Get the schema recipe with \`get_entity_schema_recipe({ entity_type: "${e.recipe_key}" })\`.`)
+        .join("\n");
+    const agentSection = s.agents
+        .map((a) => `- **${a.name}**${a.rag_role ? ` (\`rag_role: "${a.rag_role}"\`)` : ""} — ${a.purpose}`)
+        .join("\n");
+    const kbSection = s.kbs.length
+        ? s.kbs
+            .map((kb) => `- \`rag_role: "${kb.rag_role}"\` ← ${kb.source}`)
+            .join("\n")
+        : "_(none — agents work from conversation context)_";
+    const kpiSection = s.kpis
+        .map((k) => `- **${k.name}** — ${k.how}`)
+        .join("\n");
+    const orderSection = s.build_order.map((step) => step).join("\n");
+    return `# App scaffold — ${s.title}
+
+${s.description}
+
+## Custom entities to create
+
+${entitySection}
+
+## Agents to create
+
+${agentSection}
+
+## Knowledge bases
+
+${kbSection}
+
+## Typical KPIs and how to compute them
+
+${kpiSection}
+
+## Suggested build order
+
+${orderSection}
+
+${s.notes ? `## Notes\n\n${s.notes}\n` : ""}
+
+---
+
+**Next calls**:
+- For each entity above, call \`get_entity_schema_recipe({ entity_type: "..." })\` and POST the result.
+- For the chatbot wiring, call \`get_chatbot_setup_recipe()\`.
+- For the auth shape (sk_live_* / pk_live_* + cookies), call \`get_authentication_flow()\` and \`get_security_guide()\`.`;
+}
 // =============================================================================
 // MCP Server Implementation
 // =============================================================================
@@ -3800,6 +4535,41 @@ developer says "I want to build X" before writing code.`,
                     required: ["app_type"],
                 },
             },
+            {
+                name: "get_entity_schema_recipe",
+                description: `Return a ready-to-POST custom entity schema for a common entity type. Removes the guesswork of building \`fields_definition\` JSON by hand and ensures the agent picks the right field types (\`string\`, \`number\`, \`boolean\`, \`reference\` per ADR-0009, \`datetime\`, ...). Pure data, no network call. Pair with \`get_reserved_schema_slugs\` to avoid native-table collisions, and with \`POST /v1/entity/records/bulk\` for a fast seed of sample rows. Available entity types: product, customer, order, post, comment, message, task, note. Each recipe ships with the matching POST body, a sample \`fields_definition\`, and \`bulk_seed_example\` if applicable.`,
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        entity_type: {
+                            type: "string",
+                            enum: ["product", "customer", "order", "post", "comment", "message", "task", "note"],
+                            description: "Which common entity pattern do you want a recipe for?",
+                        },
+                    },
+                    required: ["entity_type"],
+                },
+            },
+            {
+                name: "get_chatbot_setup_recipe",
+                description: `End-to-end recipe for wiring a chatbot agent to a knowledge base populated from your custom-entity catalog. Returns the ordered list of API calls (create agent → create KB → upload doc → bind via rag_role) plus a TypeScript snippet (server-side, sk_live_* required). Aimed at the canonical "store assistant" / "product Q&A bot" / "support deflection" use case. Pure data; no network call.`,
+                inputSchema: { type: "object", properties: {}, required: [] },
+            },
+            {
+                name: "get_app_scaffold",
+                description: `Return a complete app scaffold for a common product template (\`pos\`, \`crm\`, \`blog\`, \`task_manager\`, \`notes\`, \`support_inbox\`). Each scaffold emits: the custom-entity schemas to create (with field types pre-decided), the agent(s) + KBs to set up, the typical KPIs and how to compute them (cross-schema search with \`join\` per ADR-0009), and the suggested build order. Designed to short-circuit the agent's "what should I build first" deliberation when the prompt is vibecoder-style ("armame un POS para una tiendita"). Pure data; no network call.`,
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        template: {
+                            type: "string",
+                            enum: ["pos", "crm", "blog", "task_manager", "notes", "support_inbox"],
+                            description: "Which app template do you want to scaffold?",
+                        },
+                    },
+                    required: ["template"],
+                },
+            },
         ],
     };
 });
@@ -4853,6 +5623,23 @@ type to pick.`,
                     ],
                 };
             }
+            case "get_entity_schema_recipe": {
+                const entityType = args.entity_type;
+                return {
+                    content: [{ type: "text", text: ENTITY_SCHEMA_RECIPE(entityType) }],
+                };
+            }
+            case "get_chatbot_setup_recipe": {
+                return {
+                    content: [{ type: "text", text: CHATBOT_SETUP_RECIPE() }],
+                };
+            }
+            case "get_app_scaffold": {
+                const template = args.template;
+                return {
+                    content: [{ type: "text", text: APP_SCAFFOLD(template) }],
+                };
+            }
             default:
                 throw new Error(`Unknown tool: ${name}`);
         }

package/package.json

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