@genlobe/mcp-server 3.7.0 → 3.7.2

package/dist/index.js

@@ -3504,11 +3504,11 @@ const ENTITY_SCHEMA_RECIPES = {
         description: "Catalog product with price, stock, category, description.",
         fields_definition: {
             name: { type: "string", required: true, max_length: 200 },
-            price: { type: "number", required: true, min: 0 },
-            stock: { type: "number", required: true, min: 0, default: 0 },
+            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: "string", required: false },
+            description: { type: "text", required: false },
             is_active: { type: "boolean", required: false, default: true },
         },
         bulk_seed_example: [
@@ -3525,15 +3525,15 @@ const ENTITY_SCHEMA_RECIPES = {
         fields_definition: {
             name: { type: "string", required: true, max_length: 200 },
             phone: { type: "string", required: false, max_length: 50 },
-            email: { type: "string", required: false, max_length: 200 },
-            notes: { type: "string", required: false },
-            tags: { type: "array", required: false },
+            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.",
+        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",
@@ -3546,28 +3546,17 @@ const ENTITY_SCHEMA_RECIPES = {
                 required: false,
                 on_delete: "set_null",
             },
-            items: {
-                type: "array",
+            items_json: {
+                type: "text",
                 required: true,
-                item_schema: {
-                    product_id: {
-                        type: "reference",
-                        target_schema_slug: "product",
-                        required: true,
-                        on_delete: "restrict",
-                    },
-                    name_snapshot: { type: "string", required: true },
-                    price_snapshot: { type: "number", required: true, min: 0 },
-                    qty: { type: "number", required: true, min: 1 },
-                },
             },
-            total: { type: "number", required: true, min: 0 },
+            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: "string", required: false },
+            notes: { type: "text", required: false },
         },
-        notes: "Always snapshot `name` and `price` into `items[]` at write time. Reading a 6-month-old order should show the price the customer paid, not the current product price. Cross-schema reads (customer name on the order list) are 1 EXISTS sub-select via POST /v1/entity/records/search with `join` (ADR-0009).",
+        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",
@@ -3583,7 +3572,7 @@ const ENTITY_SCHEMA_RECIPES = {
                 enum: ["draft", "published", "archived"],
                 default: "draft",
             },
-            tags: { type: "array", required: false },
+            tags: { type: "text", required: false },
             published_at: { type: "datetime", required: false },
             cover_image_url: { type: "string", required: false },
         },
@@ -3658,7 +3647,7 @@ const ENTITY_SCHEMA_RECIPES = {
         fields_definition: {
             title: { type: "string", required: false, max_length: 200 },
             body: { type: "string", required: true },
-            tags: { type: "array", required: false },
+            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).",
@@ -3685,6 +3674,14 @@ function ENTITY_SCHEMA_RECIPE(entityType) {
 
 ${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
@@ -3734,6 +3731,30 @@ 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
 
 \`\`\`
@@ -3752,6 +3773,43 @@ assistant" / "product Q&A" / "support deflection" use case).
 
 ## 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
@@ -3905,11 +3963,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);
 }
 \`\`\`
 
@@ -3917,12 +3992,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: {
@@ -3965,18 +4047,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",
@@ -4959,6 +5046,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.
 
 ---
 
@@ -5186,7 +5279,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.`,
                         },
                     ],
                 };

package/package.json

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