@genlobe/mcp-server 3.1.1 → 3.1.8

package/README.md

@@ -159,35 +159,6 @@ To point your IDE at a local build instead of npm:
 
 ---
 
-## Releasing a new version
-
-The MCP version follows semver and is bumped independently of the backend API:
-
-- **patch** — bug fix in a tool's behavior, doc correction
-- **minor** — new tool, new optional field, new env var with a default
-- **major** — tool removed/renamed, env var removed, breaking change in returned shape
-
-Publish flow (works around the subtree quirk where `npm version` doesn't always commit cleanly):
-
-```bash
-cd mcp-server
-# 1. Move CHANGELOG [Unreleased] section under the new version header.
-# 2. Bump versions without letting npm touch git:
-npm version <patch|minor|major> --no-git-tag-version
-# 3. One commit + one tag, both intentional:
-git add package.json package-lock.json CHANGELOG.md
-git commit -m "chore(mcp): release vX.Y.Z"
-git tag -a vX.Y.Z -m "@genlobe/mcp-server vX.Y.Z"
-# 4. Publish (prepublishOnly runs `tsc` automatically):
-npm publish --access public
-# 5. Push commit + tag:
-git push origin main && git push origin vX.Y.Z
-```
-
-The CI workflow `.github/workflows/publish-mcp.yml` automates steps 4–5 when you push a `mcp-v*` tag (see [Automated publishing](#automated-publishing) below).
-
----
-
 ## License
 
 MIT — see [package.json](./package.json).

package/dist/index.js

@@ -271,7 +271,7 @@ const END_USER_ENDPOINTS = {
                     email: "string (required) - valid email address"
                 },
                 response: { message: "Verification email sent" },
-                note: "Always returns success even if email doesn't exist (security). Rate limited to prevent abuse."
+                note: "Returns 200 with a generic 'will be sent if the user exists' message when the user does not exist (security). Returns 400 with `{ detail: \"<reason>\" }` when delivery cannot proceed — the detail mirrors the underlying provider error, e.g. `\"destination is suppressed: BOUNCE\"` or `\"destination is suppressed: COMPLAINT\"` when AWS SES has the destination on its account suppression list. The email cannot be delivered until the destination's MX/inbox is fixed by its owner, or an admin force-verifies the user from the tenant dashboard. Rate limited to prevent abuse."
             },
             {
                 method: "GET",
@@ -1434,7 +1434,7 @@ const END_USER_ENDPOINTS = {
                 method: "GET",
                 path: "/v1/entity/schemas",
                 summary: "List all entity schemas in the organization",
-                auth: { api_key: "sk_live_*", jwt: true, headers: "X-Organization-Id required" },
+                auth: { api_key: "sk_live_*", jwt: false, headers: "X-Organization-Id required when key is not organization-scoped" },
                 query_params: {
                     page: "number (default 1)",
                     size: "number (default 20, max 100)"
@@ -1444,26 +1444,49 @@ const END_USER_ENDPOINTS = {
                 method: "POST",
                 path: "/v1/entity/schemas",
                 summary: "Create a new entity schema",
-                auth: { api_key: "sk_live_*", jwt: true, headers: "X-Organization-Id required" },
+                auth: { api_key: "sk_live_*", jwt: false, headers: "X-Organization-Id required when key is not organization-scoped" },
                 request_body: {
                     name: "string (required) - unique per organization",
                     slug: "string (required) - unique per organization, lowercase/hyphens only",
                     description: "string (optional)",
-                    fields_definition: "object (required) - field definitions with type, required, constraints"
+                    fields_definition: `object (required) - keys are field names (regex ^[a-zA-Z_][a-zA-Z0-9_]*$, max 64 chars; reserved: id, created_at, updated_at, tenant_id), values are objects with at least { "type": <one-of-the-supported-types>, "required": boolean }. Per-type shapes below.`
                 },
-                notes: "Supported field types: string, integer, float, boolean, datetime, text, enum, email, url, phone. Returns 409 if name or slug already exists."
+                fields_definition_per_type: {
+                    string: '{"type":"string","required":true,"max_length":255,"pattern":"^[a-z]+$"}     // pattern is optional regex',
+                    text: '{"type":"text","required":false,"max_length":5000}',
+                    integer: '{"type":"integer","required":true,"min":0,"max":100}',
+                    float: '{"type":"float","required":false,"min":0.0,"max":1.0}',
+                    boolean: '{"type":"boolean","required":true}',
+                    datetime: '{"type":"datetime","required":false}',
+                    enum: '{"type":"enum","required":true,"values":["draft","published","archived"]}     // KEY IS "values", NOT "choices" — Genlobe rejects "choices" with 400.',
+                    email: '{"type":"email","required":true,"max_length":255}',
+                    url: '{"type":"url","required":false,"max_length":2048}',
+                    phone: '{"type":"phone","required":false,"max_length":20}'
+                },
+                example_request: `{
+  "name": "Blog Post",
+  "slug": "blog-post",
+  "description": "Journal / blog content",
+  "fields_definition": {
+    "title":  {"type": "string",  "required": true,  "max_length": 255},
+    "body":   {"type": "text",    "required": true},
+    "status": {"type": "enum",    "required": true,  "values": ["draft", "published", "archived"]},
+    "views":  {"type": "integer", "required": false, "min": 0}
+  }
+}`,
+                notes: "Returns 409 if name or slug already exists. Common pitfall: the enum field uses 'values' (an array) — 'choices' is rejected with a 400 that names this directly. The validator runs at field level, so all errors come back together in `detail.errors[]`."
             },
             {
                 method: "GET",
                 path: "/v1/entity/schemas/{schema_id}",
                 summary: "Get a specific schema by ID",
-                auth: { api_key: "sk_live_*", jwt: true, headers: "X-Organization-Id required" }
+                auth: { api_key: "sk_live_*", jwt: false, headers: "X-Organization-Id required when key is not organization-scoped" }
             },
             {
                 method: "PUT",
                 path: "/v1/entity/schemas/{schema_id}",
                 summary: "Update an existing schema",
-                auth: { api_key: "sk_live_*", jwt: true, headers: "X-Organization-Id required" },
+                auth: { api_key: "sk_live_*", jwt: false, headers: "X-Organization-Id required when key is not organization-scoped" },
                 request_body: {
                     name: "string (optional)",
                     slug: "string (optional)",
@@ -1476,47 +1499,47 @@ const END_USER_ENDPOINTS = {
                 method: "DELETE",
                 path: "/v1/entity/schemas/{schema_id}",
                 summary: "Delete a schema (may fail if records exist)",
-                auth: { api_key: "sk_live_*", jwt: true, headers: "X-Organization-Id required" }
+                auth: { api_key: "sk_live_*", jwt: false, headers: "X-Organization-Id required when key is not organization-scoped" }
             },
-            // ── End-User Record Endpoints ──
+            // ── Entity Record Endpoints (tenant-scoped or user-scoped) ──
             {
                 method: "POST",
                 path: "/v1/entity/records",
                 summary: "Create a new entity record",
-                auth: { api_key: "sk_live_* or pk_live_*", jwt: true, headers: "X-Organization-Id required" },
+                auth: { api_key: "sk_live_* or pk_live_*", jwt: false, headers: "X-Organization-Id required when key is not organization-scoped" },
                 request_body: {
                     schema_id: "uuid (required)",
                     data: "object (required) - validated against schema fields_definition"
                 },
-                notes: "Sets created_by_id to the authenticated end-user."
+                notes: "Two modes: (1) sk_live_* without JWT -> tenant-scoped record, created_by_id is NULL (e.g. catalog/blog/global config). (2) API key + end-user JWT -> user-scoped record, created_by_id = user.id. The endpoint accepts both shapes; ownership is determined by whether a JWT is present."
             },
             {
                 method: "GET",
                 path: "/v1/entity/records/{record_id}",
                 summary: "Get a specific record by ID",
-                auth: { api_key: "sk_live_* or pk_live_*", jwt: true, headers: "X-Organization-Id required" }
+                auth: { api_key: "sk_live_* or pk_live_*", jwt: false, headers: "X-Organization-Id required when key is not organization-scoped" }
             },
             {
                 method: "PUT",
                 path: "/v1/entity/records/{record_id}",
                 summary: "Update a record",
-                auth: { api_key: "sk_live_* or pk_live_*", jwt: true, headers: "X-Organization-Id required" },
+                auth: { api_key: "sk_live_* or pk_live_*", jwt: false, headers: "X-Organization-Id required when key is not organization-scoped" },
                 request_body: {
                     data: "object (required) - validated against schema fields_definition"
                 },
-                notes: "Sets updated_by_id to the authenticated end-user."
+                notes: "updated_by_id follows the same rule as create: NULL for tenant-scoped (sk_live_* alone) or user.id for user-scoped (API key + JWT)."
             },
             {
                 method: "DELETE",
                 path: "/v1/entity/records/{record_id}",
                 summary: "Delete a record",
-                auth: { api_key: "sk_live_* or pk_live_*", jwt: true, headers: "X-Organization-Id required" }
+                auth: { api_key: "sk_live_* or pk_live_*", jwt: false, headers: "X-Organization-Id required when key is not organization-scoped" }
             },
             {
                 method: "POST",
                 path: "/v1/entity/records/search",
                 summary: "Advanced search for entity records with filters and ordering",
-                auth: { api_key: "sk_live_*", jwt: true, headers: "X-Organization-Id required" },
+                auth: { api_key: "sk_live_* or pk_live_*", jwt: false, headers: "X-Organization-Id required when key is not organization-scoped" },
                 request_body: {
                     schema_id: "uuid (optional) - filter by schema",
                     query: "object (optional) - filters: {field: value} for equality, {field: {operator: 'gt', value: 100}} for operators"
@@ -2570,6 +2593,16 @@ for those.
   session token: keep it in memory or HTTP-only cookies, never in
   localStorage if XSS is a real threat for your app.
 
+## ⚠️ For agents: don't invent end-user credentials
+
+If your task requires acting as an end-user (calling a \`jwt: true\`
+endpoint) and the human has not given you an email + password, **stop
+and ask**. Do not register a new end-user with an email you generated
+(\`admin@<their-domain>\`, \`seed@<their-domain>\`, etc.) — invented
+addresses bounce, AWS SES suppresses the domain at the account level,
+and the tenant loses email delivery to that destination. See
+\`get_authentication_flow\` for the full guardrail.
+
 ## Recommended next step
 
 Run \`recommend_stack\` with the kind of app you want to build to get a
@@ -2642,6 +2675,22 @@ browser app holds for that session.
   Refuse — the key belongs in env.
 - Logging \`console.log(headers)\` in middleware on a public-facing app.
 
+## ⚠️ For agents: don't invent end-user credentials
+
+A secret key gives you tenant-admin reach, but it does **not** give you
+the right to fabricate end-user accounts. If a task requires acting as
+an end-user (calling a \`jwt: true\` endpoint) and the human has not
+given you an email + password, **stop and ask** them to either share
+existing credentials or create an end-user in the dashboard. Inventing
+an email (\`admin@<their-domain>\`, \`seed@<their-domain>\`, etc.) leads
+to bounces, account-level SES suppression, and email delivery being
+locked out for that destination — see incident #168 for the canonical
+example. \`get_authentication_flow\` has the full guardrail.
+
+Note also: \`/v1/entity/schemas\` is **not** a \`jwt: true\` endpoint —
+it accepts \`sk_live_*\` alone. Don't register an end-user just to call
+it. Read \`get_endpoint_details\` first.
+
 ## Recommended next step
 
 Run \`recommend_stack\` with your app_type to get a server-aware framework
@@ -3445,6 +3494,17 @@ Use search_endpoints tool to find available endpoints.`,
                             type: "text",
                             text: `# Authentication Flow Guide
 
+> ## ⚠️ When you (the agent) need an end-user JWT
+>
+> Some endpoints document themselves as \`jwt: true\` (e.g. some \`/v1/entity/records\` modes, profile updates, anything user-scoped). If your task requires calling one of these and you do **not** have an end-user email and password supplied by the human you are working with:
+>
+> 1. **Stop.** Ask the human for credentials of an existing end-user, or ask them to create one in the dashboard and give you the credentials.
+> 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.
+
+---
+
 ## 1. Registration Flow
 
 \`\`\`typescript

package/package.json

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