@genlobe/mcp-server 3.1.3 → 3.3.0

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

@@ -64,8 +64,13 @@ There are TWO types of authentication contexts:
 - These endpoints ARE for building end-user frontends
 
 ## API Key Types
-- \`pk_live_*\`: Public key - safe to expose in frontend code (LIMITED to auth endpoints only)
-- \`sk_live_*\`: Secret key - backend only, never expose (FULL API access)
+
+- \`pk_live_*\`: Public key — safe to expose in frontend code.
+  - **By itself** (no JWT) the key only unlocks \`/v1/auth/*\` (register, login, refresh, logout, me, forgot-password, reset-password). These are the seven scopes auto-assigned to public keys.
+  - **Combined with an end-user JWT** returned by \`/v1/auth/login\`, the same public key unlocks the full end-user API: \`/v1/user/agents/*\`, \`/v1/entity/records/*\`, \`/v1/plans\`, \`/v1/billing/*\`, \`/v1/users/me\`, etc. Once the JWT is in play, the JWT carries end-user identity and the public key just keeps verifying the tenant context.
+  - Restricted by an Origin allowlist (configured per key) and per-IP rate limits.
+
+- \`sk_live_*\`: Secret key — backend-only, never expose. Required for server-to-server work that no end-user JWT can cover: defining entity schemas (\`/v1/entity/schemas/*\`), bulk record operations (\`/v1/entity/records/bulk\`, \`/v1/entity/records/search\`), webhooks, batch jobs, and other admin tooling on the tenant's own server.
 
 ## API Key Organization Scope (B2B2C)
 
@@ -102,6 +107,38 @@ If you're building a frontend application for end-users, you should:
 2. Use the public API key (pk_live_*) for client-side requests
 3. Include X-API-Key header in ALL requests
 4. After login, also include Authorization: Bearer <jwt> for authenticated requests
+
+## End-User App Flow (the canonical two-phase pattern)
+
+A common confusion: the public key looks restricted to \`/v1/auth/*\`, so developers assume they need to ship the secret key in their frontend to call agents or records. They don't. The pattern is two phases:
+
+\`\`\`
+[Tenant's app frontend in the user's browser]
+  │
+  │ Phase 1 — auth gateway (public key alone is enough)
+  │ X-API-Key: pk_live_xxx
+  ▼
+POST /v1/auth/register   ─┐
+POST /v1/auth/login       ├─ returns { access_token (JWT), refresh_token, user }
+POST /v1/auth/refresh    ─┘
+  │
+  │ Phase 2 — end-user features (public key + JWT)
+  │ X-API-Key: pk_live_xxx
+  │ Authorization: Bearer <end-user JWT>
+  ▼
+GET  /v1/user/agents/available
+POST /v1/user/agents/{id}/chat
+GET/POST/PUT/DELETE /v1/entity/records/...     ← custom-entity records as your app's DB
+GET  /v1/plans
+POST /v1/billing/checkout
+GET  /v1/users/me
+\`\`\`
+
+The \`sk_live_*\` key never reaches the browser. It lives only on the tenant's own server, used for:
+- defining entity schemas (\`/v1/entity/schemas/*\`),
+- bulk record operations (\`/v1/entity/records/bulk\`, \`/search\`),
+- receiving webhooks from the platform,
+- cron jobs and admin tooling.
 `,
     base_url: API_URL,
     documentation_urls: {
@@ -787,7 +824,7 @@ const END_USER_ENDPOINTS = {
         ]
     },
     billing: {
-        description: "Billing operations - checkout, plan changes, cancellation. All endpoints require SECRET key (sk_live_*) only.",
+        description: "Billing operations. Two flavors:\n\n- **Tier 1 (legacy / platform-level)**: endpoints under /v1/billing/* use the platform's Stripe and a SECRET key (sk_live_*) only. They were originally for Genlobe → Tenant billing and a since-superseded Tier 2 prototype; keep using them for tenant-internal flows.\n\n- **Tier 3 (Organization → end-user, Epic #209)**: each Organization runs its OWN Stripe (BYO key). End-users subscribe via /v1/organizations/{org_id}/billing/* (api key + JWT + active OrganizationMember). The Org's plan catalog is read via the public /v1/organizations/{org_id}/plans (api key only — no JWT). See the master spec at specs/features/billing/three-tier-billing.spec.md.",
         endpoints: [
             {
                 method: "GET",
@@ -880,6 +917,91 @@ const END_USER_ENDPOINTS = {
                     total_invoices: "number"
                 },
                 note: "Returns 404 if organization not found or doesn't belong to tenant."
+            },
+            // ---------------------------------------------------------------
+            // Tier 3 endpoints (Epic #209). Each Organization runs its OWN
+            // Stripe (BYO key). These run against the org's Stripe, not the
+            // platform's, and require an active OrganizationMember of the path's
+            // org. Plans are sold by the Organization to its end-users.
+            // ---------------------------------------------------------------
+            {
+                method: "GET",
+                path: "/v1/organizations/{organization_id}/plans",
+                summary: "List the Organization's active plans (Tier 3) — public to anonymous visitors of the org's app",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: false },
+                response: {
+                    items: "array of OrganizationPlan: id (uuid), organization_id (uuid), name (string), slug (string), description (string | null), price_amount (decimal), currency (ISO-4217), billing_interval ('month' | 'year'), stripe_product_id (string | null), stripe_price_id (string | null), stripe_price_id_yearly (string | null), features (array of strings), limits (object<string, int | null>), is_active (boolean), created_at (ISO datetime), updated_at (ISO datetime)",
+                    total: "number"
+                },
+                note: "Tenant-scoped: returns 404 if the Organization doesn't belong to the API key's tenant (no existence leak across tenants). Only plans with is_active=true and stripe_price_id != null are returned — use one of those plan ids when calling /billing/checkout-session.",
+                example_request: `GET /v1/organizations/660e8400-e29b-41d4-a716-446655440001/plans`
+            },
+            {
+                method: "POST",
+                path: "/v1/organizations/{organization_id}/billing/checkout-session",
+                summary: "Start a Stripe Checkout subscription flow for the calling end-user against an Org plan (Tier 3)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                request_body: {
+                    plan_id: "uuid (required) — OrganizationPlan id (NOT a Stripe price id). Get it from /v1/organizations/{organization_id}/plans.",
+                    success_url: "string url (required) — Stripe redirects here on success.",
+                    cancel_url: "string url (required) — Stripe redirects here if the user cancels."
+                },
+                response: {
+                    checkout_url: "string — Stripe-hosted Checkout URL (redirect the user here).",
+                    session_id: "string — Stripe Checkout session id (cs_*)."
+                },
+                errors: {
+                    "403": "Caller is not an active OrganizationMember of the path's org.",
+                    "404": "Plan not found / belongs to a different org / inactive (collapsed to the same 404 to avoid cross-org existence leaks).",
+                    "409": "Plan has no stripe_price_id yet OR the Organization has no Stripe configured (the Org Owner must finish setup first)."
+                },
+                note: "The caller becomes the end-user customer in the Organization's Stripe account, not in the platform's. The actual Subscription row is created by the webhook handler after Stripe fires checkout.session.completed.",
+                example_request: `{
+  "plan_id": "770e8400-e29b-41d4-a716-446655440002",
+  "success_url": "https://claude.example.com/billing/success?cs={CHECKOUT_SESSION_ID}",
+  "cancel_url": "https://claude.example.com/pricing"
+}`
+            },
+            {
+                method: "POST",
+                path: "/v1/organizations/{organization_id}/billing/customer-portal-session",
+                summary: "Open a Stripe Customer Portal session for the calling end-user (Tier 3, manage / cancel)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                request_body: {
+                    return_url: "string url (required) — Stripe redirects here when the user closes the Portal."
+                },
+                response: {
+                    portal_url: "string — Stripe-hosted Customer Portal URL."
+                },
+                errors: {
+                    "403": "Caller is not an active OrganizationMember of the path's org.",
+                    "409": "Caller has no Subscription / no Stripe customer for this Organization yet, OR the Organization has no Stripe configured."
+                },
+                note: "Portal allowed actions (cancel / update payment method / etc.) are configured by the Organization Owner in their own Stripe Dashboard."
+            },
+            {
+                method: "GET",
+                path: "/v1/organizations/{organization_id}/billing/subscription",
+                summary: "Read the calling end-user's current subscription in this Organization (Tier 3)",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                response: {
+                    id: "uuid",
+                    organization_id: "uuid",
+                    user_id: "uuid",
+                    plan_id: "uuid | null",
+                    status: "string | null — Stripe Subscription.status (active, past_due, canceled, …)",
+                    billing_cycle: "string — 'monthly' or 'yearly'",
+                    current_period_start: "ISO datetime | null",
+                    current_period_end: "ISO datetime | null",
+                    cancel_at_period_end: "boolean",
+                    canceled_at: "ISO datetime | null",
+                    trial_start: "ISO datetime | null",
+                    trial_end: "ISO datetime | null"
+                },
+                errors: {
+                    "403": "Caller is not an active OrganizationMember of the path's org.",
+                    "404": "Caller has no Subscription for this Organization yet."
+                }
             }
         ]
     },
@@ -1026,6 +1148,29 @@ const END_USER_ENDPOINTS = {
                     error: "string | null"
                 },
                 note: "Returns 402 Payment Required if usage limits exceeded."
+            },
+            {
+                method: "GET",
+                path: "/v1/organizations/{organization_id}/usage",
+                summary: "Get aggregate usage for one Organization in the queried period",
+                auth: { api_key: "pk_live_* or sk_live_*", jwt: true },
+                query_params: {
+                    period_start: "ISO datetime (optional) - Inclusive start of the aggregation window (UTC). Defaults to the current calendar month.",
+                    period_end: "ISO datetime (optional) - Exclusive end of the aggregation window (UTC). Must be supplied together with period_start.",
+                },
+                response: {
+                    organization_id: "uuid",
+                    organization_name: "string | null - Human-readable name from organizations row, null if the org row was deleted",
+                    organization_slug: "string | null",
+                    period_start: "ISO datetime - resolved window start",
+                    period_end: "ISO datetime - resolved window end",
+                    messages_count: "number - Sum of messages_count across plan_usages rows for the org in the period",
+                    tokens_count: "number - Sum of tokens_count (input + output)",
+                    input_tokens_count: "number",
+                    output_tokens_count: "number",
+                    cost_usd: "string - Decimal as string (e.g. '12.345600')",
+                },
+                note: "Auth requires the caller to be an active OrganizationMember of the path's org. Returns a zero row when the org had no activity in the period, so callers can always render a header without a 404 fallback. Read-only — does not consume usage.",
             }
         ]
     },
@@ -1434,7 +1579,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 +1589,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.`
+                },
+                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}'
                 },
-                notes: "Supported field types: string, integer, float, boolean, datetime, text, enum, email, url, phone. Returns 409 if name or slug already exists."
+                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 +1644,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 +2738,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 +2820,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 +3639,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.3",
+  "version": "3.3.0",
   "description": "MCP Server for GenLobe SaaS API - Provides AI assistants with comprehensive API documentation for building frontend applications",
   "main": "dist/index.js",
   "bin": {