@genlobe/mcp-server 3.7.0 → 3.7.1

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
 
 \`\`\`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@genlobe/mcp-server",
-  "version": "3.7.0",
+  "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": {