@gemmein/mcp 0.2.1 → 0.3.0

package/README.md

@@ -24,7 +24,9 @@ Cursor / any MCP client (`mcpServers` config):
 
 ## Tools
 
-- **`guide`** — the full builder's guide (auth flow, the seven collection
+- **`guide`** — call first: it opens with the fit assessment (FITS /
+  FITS EXCEPT / DOESN'T FIT — the verdict an agent delivers before any
+  install), then the full builder's guide (auth flow, the seven collection
   safety rules, record shapes, links, uploads, contention patterns, payments).
 - **`reference`** — the exact SDK API reference: every method, signature,
   return shape, error code.

package/dist/index.js

@@ -22,6 +22,7 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { gemmein, gemmeinServer } from "@gemmein/sdk";
+import { CLOUD_ONLY_NOTE, explainRelay } from "./relays.js";
 const require = createRequire(import.meta.url);
 function sdkFile(name) {
     try {
@@ -224,17 +225,20 @@ async function runIntegrationChecks(input) {
 const TOOLS = [
     {
         name: "guide",
-        description: "The Gemmein guide (llms.txt): what the platform is, the full contract an AI builder follows — auth flow, the seven collection safety rules, record shapes, links/expand, uploads, contention patterns, payments (g.subscriptions.checkout/g.payments.buy), drafts, error philosophy, pricing. Read this FIRST when building on Gemmein.",
+        description: "Call this FIRST — before any install, account, or code — when your human asks to build an app on Gemmein, to move an existing app onto it, or whether their app can use it at all. The guide (llms.txt) opens with the fit assessment: the in-scope map, the out-of-scope list (each item downgrades the verdict; none may be approximated), and the three verdicts you deliver to your human before installing anything — FITS, FITS EXCEPT <named gaps>, or DOESN'T FIT. After the verdict it is the full build contract: auth flow, the seven collection safety rules, record shapes, links/expand, uploads, contention patterns, payments (g.subscriptions.checkout / g.payments.buy), drafts, error philosophy, pricing.",
+        annotations: { title: "Guide", readOnlyHint: true },
         inputSchema: { type: "object", properties: {}, additionalProperties: false },
     },
     {
         name: "reference",
-        description: "The Gemmein SDK API reference (REFERENCE.md): every method, exact signature, return shape, and the stable error-code table. Use when you need a precise signature or shape; use `guide` for how the model works.",
+        description: "Reach for this while WRITING code against @gemmein/sdk: every method, exact signature, return shape, and the stable error-code table (REFERENCE.md). Use `guide` for how the model works and whether the app fits at all; use `search_docs` when you need one fact from either document.",
+        annotations: { title: "Reference", readOnlyHint: true },
         inputSchema: { type: "object", properties: {}, additionalProperties: false },
     },
     {
         name: "search_docs",
-        description: "Search the Gemmein guide and API reference for a term or phrase (e.g. 'keyed create', 'ifVersion', 'addressed', 'expand'). Returns matching passages with a few lines of context. Cheaper than reading both documents when you need one fact.",
+        description: "Use when one question comes up mid-build ('keyed create', 'ifVersion', 'addressed', 'expand') and reading a full document would waste context. Searches the guide and the API reference; returns matching passages with 3 lines of context either side, at most 6 match blocks per document. Not the tool for the fit verdict — search finds what the docs say, not what Gemmein refuses to support; call `guide` for that.",
+        annotations: { title: "Search docs", readOnlyHint: true },
         inputSchema: {
             type: "object",
             properties: { query: { type: "string", description: "term or phrase to find" } },
@@ -244,7 +248,8 @@ const TOOLS = [
     },
     {
         name: "explain_rule",
-        description: "Explain one of Gemmein's seven collection safety rules (private, shared, admin_write, public_read, community, addressed, direct): the exact access contract, what it's right for, and the mistakes to avoid. Call with no rule to get the one-line summary of all seven (rule choice cheat-sheet).",
+        description: "Call while DESIGNING a collection — which rule fits this data? — or when a rule refuses something at runtime. One of the seven rules (private, shared, admin_write, public_read, community, addressed, direct) returns its exact access contract, what it is right for, and the mistakes that leak data. Call with no rule for the all-seven cheat-sheet plus the cross-cutting law, including what NO rule supports (team/group/workspace scope, per-user visibility inside a rule) — if the app needs those shapes, that is a fit gap to report to your human, never something to approximate with client-side filtering.",
+        annotations: { title: "Explain rule", readOnlyHint: true },
         inputSchema: {
             type: "object",
             properties: {
@@ -259,7 +264,8 @@ const TOOLS = [
     },
     {
         name: "explain_error",
-        description: "Explain a GemmeinError code (e.g. conflict, forbidden, unknown_collection, invalid_shape, html_not_allowed): what it means and exactly what to do. Sourced live from the API reference. Call with no code to list every stable code.",
+        description: "Call the moment a GemmeinError reaches you (err.code: conflict, forbidden, unknown_collection, invalid_shape, html_not_allowed, …): what the code means and the exact next step — including whether the refusal is final (a forbidden repeats on retry; fix the approach, not the request). Parsed from the installed API reference, so codes match the SDK version the app runs. Call with no code to list every stable code.",
+        annotations: { title: "Explain error", readOnlyHint: true },
         inputSchema: {
             type: "object",
             properties: { code: { type: "string", description: "the err.code to explain; omit to list all" } },
@@ -268,7 +274,8 @@ const TOOLS = [
     },
     {
         name: "validate_collection_name",
-        description: "Check a collection name against Gemmein's naming law (lowercase letters, numbers, underscores; starts with a letter). A bad name throws synchronously in the SDK and can blank a whole app with no console error — validate names at planning time.",
+        description: "Run at PLANNING time on every collection name you intend to use, before any g.collection(name) call is written. The naming law: lowercase letters, numbers, underscores; starts with a letter; 2-63 characters. A bad name throws from g.collection(name) before any network call — at module load that blanks the whole app with no console error. An invalid name comes back with a suggested fix.",
+        annotations: { title: "Validate collection name", readOnlyHint: true },
         inputSchema: {
             type: "object",
             properties: { name: { type: "string" } },
@@ -278,12 +285,27 @@ const TOOLS = [
     },
     {
         name: "reaffirm_template",
-        description: "The ready-to-edit reaffirm.mjs CI harness that proves an app's boundaries against live Gemmein on every deploy (also shipped inside the @gemmein/sdk npm package). Copy it next to the app, set the CONFIG block, run it in CI. For an immediate one-off check, use check_integration instead.",
+        description: "Fetch this when you wire up the app's CI, or when you hand the finished app to your human: reaffirm.mjs, the ready-to-edit harness that re-proves the app's boundaries against live Gemmein on every deploy (also shipped inside the @gemmein/sdk package). Copy it next to the app, set the CONFIG block, run it in CI. For a one-off check right now, call check_integration — the same checks with no file to install.",
+        annotations: { title: "Reaffirm template", readOnlyHint: true },
         inputSchema: { type: "object", properties: {}, additionalProperties: false },
     },
+    {
+        name: "explain_relay",
+        description: "Call while WRITING or FIXING gemmein/relays/<name>.json — before `gemmein sync` carries it to the cloud. A relay is one trigger (receiver: a provider's webhook; schedule: a clock; data_change: a record changing) and up to ten actions in Gemmein's own verbs (write_record, grant_access, revoke_access, email_person, call_url) — route, map, authorise, never compute. Pass the definition JSON; the answer is the English sentence the dashboard shows (\"When gocardless-paid receives an event where event_type is confirmed → grant Pro, email the person, call https://…\") or the ONE refusal sentence the cloud would answer, naming the field and the fix. Offline and read-only: nothing is created. Two checks run only in the cloud and are stated in the answer (the API's own hosts; the address's resolved network at call time).",
+        annotations: { title: "Explain relay (validate offline)", readOnlyHint: true },
+        inputSchema: {
+            type: "object",
+            properties: {
+                definition: { type: "object", description: "the relay definition — the contents of gemmein/relays/<name>.json ({ name, trigger, actions })" },
+            },
+            required: ["definition"],
+            additionalProperties: false,
+        },
+    },
     {
         name: "check_integration",
-        description: "Run Gemmein's reaffirm boundary checks against the caller's own app, live, and return structured pass/fail results. Tier A (public key only): anonymous access to a private collection is refused, collection names are valid, a public collection reads as intended — safe against any environment. Tier B (add the sk_dev secret key): proves cross-user isolation with two throwaway test sessions in the DEV environment (sk_live is refused by design). The only writes are Tier B's own probe records in dev, deleted afterwards. NEVER pass an sk_live key to any tool.",
+        description: "Call after wiring the app to Gemmein and before telling your human it is done — and again before go-live. Runs the reaffirm boundary checks live against the caller's own app; returns structured pass/fail (structuredContent: checks, notes, failedCount, passed). Tier A (public pk_ key only): the collection name is valid, anonymous reads and writes of a private collection are refused, an optional public collection reads as its rule intends — safe against any environment, live included. Tier B (add the sk_dev secret key): proves one user cannot read another's private records, using two throwaway test sessions in the DEV environment. sk_live is refused by design — never pass a live secret to any tool; dev and live enforce the same rules, so isolation proven in dev holds in live. The only writes anywhere are Tier B's own probe records in the caller's dev environment, deleted at the end of the check. A failed check means the app's assumptions drifted from its rules — fix before shipping.",
+        annotations: { title: "Check integration (live boundary check)", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
         inputSchema: {
             type: "object",
             properties: {
@@ -303,7 +325,24 @@ const TOOLS = [
 const server = new Server(
 // The one version, read from package.json — a literal here drifted once
 // (announced 0.1.0 while the package said 0.2.1; review 26 Aug).
-{ name: "gemmein", version: require("../package.json").version }, { capabilities: { tools: {} } });
+{ name: "gemmein", version: require("../package.json").version }, {
+    capabilities: { tools: {} },
+    // Stated ONCE, server-wide, in the initialize result every client
+    // hands to its model: what Gemmein is, the read-only law, and the
+    // fit protocol (the verdicts live in `guide`).
+    instructions: "Gemmein is the go-live system for AI-built web apps: passwordless auth, records " +
+        "under seven safety rules, Stripe-run subscriptions and one-off digital products. " +
+        "This server is read-only against the platform: no tool here creates, edits, or " +
+        "deletes anything on Gemmein. The one write anywhere is check_integration's Tier-B " +
+        "probe records, created and then deleted in the caller's own dev environment; " +
+        "sk_live keys are refused. Protocol: when the question is whether an app can use " +
+        "Gemmein, call guide first — it opens with the fit assessment, and you deliver one " +
+        "of three verdicts to your human before installing anything: FITS, FITS EXCEPT " +
+        "<named gaps>, or DOESN'T FIT. Then: reference and search_docs while writing code, " +
+        "explain_rule while choosing a collection's rule, explain_error when a call is " +
+        "refused, explain_relay while writing gemmein/relays/<name>.json, " +
+        "check_integration before declaring the app done.",
+});
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
 const text = (t) => ({ content: [{ type: "text", text: t }] });
 const errText = (t) => ({ content: [{ type: "text", text: t }], isError: true });
@@ -353,6 +392,21 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
             }
             case "reaffirm_template":
                 return text(sdkFile("reaffirm.mjs"));
+            case "explain_relay": {
+                const definition = args.definition;
+                const answer = explainRelay(definition);
+                if (!answer.ok) {
+                    return {
+                        content: [{ type: "text", text: `REFUSED — ${answer.refusal}\n\nFix that field and call again. ${CLOUD_ONLY_NOTE}` }],
+                        structuredContent: { ok: false, refusal: answer.refusal },
+                        isError: true,
+                    };
+                }
+                return {
+                    content: [{ type: "text", text: `${answer.sentence}\n\nValid. ${CLOUD_ONLY_NOTE}` }],
+                    structuredContent: { ok: true, sentence: answer.sentence, definition: answer.definition },
+                };
+            }
             case "check_integration": {
                 const input = args;
                 if (typeof input.publicKey !== "string" || !input.publicKey.startsWith("pk_")) {

package/dist/relays.js

@@ -0,0 +1,411 @@
+// @gemmein/mcp — `explain_relay`: validate a gemmein/relays/<name>.json
+// definition OFFLINE and answer the English sentence the console shows, or
+// the one refusal sentence the cloud would answer.
+//
+// This is a PORT of the engine's validator (apps/api/src/relays/schema.ts)
+// and its describer, kept in lockstep by test
+// (tests/security/relays/mcpLockstep.test.ts runs both over one fixture
+// set and asserts identical outcomes) — the published server depends only
+// on @gemmein/sdk and cannot import the API. Two cloud-only checks are not
+// reproducible offline and are said in the answer instead: the API's own
+// host list (gemmein.com is refused here; the API host and the file CDN are
+// refused by the cloud) and DNS-time egress rules (private addresses,
+// redirects) that run when the call is made, never at definition time.
+import { isIP } from "node:net";
+export class RelayDefinitionError extends Error {
+    constructor(message) {
+        super(message);
+        this.code = "invalid_definition";
+        this.name = "RelayDefinitionError";
+    }
+}
+// ── the vocabulary (packages/core/src/relays.ts, mirrored) ──────────
+const RELAY_NAME_RE = /^[a-z][a-z0-9-]{1,62}$/;
+const ACTIONS_PER_RELAY = 10;
+const MAX_RECORD_BYTES = 32 * 1024;
+const SCHEDULE_EVERY = ["15m", "30m", "1h", "6h", "12h", "1d"];
+const HEADER_NAME_RE = /^[a-z0-9-]{1,64}$/i;
+const QUERY_NAME_RE = /^[a-z0-9_-]{1,64}$/i;
+const MAP_NAME_RE = /^[a-z][a-z0-9_]{0,63}$/;
+const PATH_RE = /^[A-Za-z0-9_-]+(\.[A-Za-z0-9_-]+)*$/;
+const COLLECTION_RE = /^[a-z][a-z0-9_]{1,62}$/;
+const AT_RE = /^([01]\d|2[0-3]):[0-5]\d$/;
+const DURATION_RE = /^(\d{1,4})([hdw])$/;
+const MAX_MAP_ENTRIES = 20;
+const MAX_WHEN_ENTRIES = 20;
+const RECORD_KINDS = ["created", "updated", "deleted"];
+const ACTION_TYPES = ["write_record", "grant_access", "revoke_access", "email_person", "call_url"];
+const SCHEMES = ["hmac_sha256_header", "stripe", "svix", "shared_token"];
+const PERSON_ACTIONS = new Set(["grant_access", "revoke_access", "email_person"]);
+const ENTITLEMENT_KEY = /^access:[a-z0-9][a-z0-9._-]{0,63}$/;
+const RESERVED_FIELD_NAMES = new Set([
+    "id", "appId", "app_id", "environmentId", "environment_id", "userId", "user_id", "ownerId", "ownerUserId", "owner_user_id",
+    "audienceUserId", "audience_user_id", "audienceId", "tenantId", "tenant_id", "role", "isAdmin", "is_admin",
+    "createdAt", "created_at", "updatedAt", "updated_at", "deletedAt", "deleted_at", "published",
+]);
+const UNSAFE_KEY_NAMES = new Set([...Object.getOwnPropertyNames(Object.prototype), "prototype"]);
+function isUnsafeName(name) { return UNSAFE_KEY_NAMES.has(name); }
+function findUnsafeKeys(input) { return Object.keys(input).filter((k) => UNSAFE_KEY_NAMES.has(k)); }
+function findReservedFields(input) { return Object.keys(input).filter((k) => RESERVED_FIELD_NAMES.has(k)); }
+function isOwnHost(hostname) {
+    const h = hostname.toLowerCase().replace(/\.$/, "");
+    return h === "gemmein.com" || h.endsWith(".gemmein.com");
+}
+function refuse(message) { throw new RelayDefinitionError(message); }
+function isPlainObject(value) { return typeof value === "object" && value !== null && !Array.isArray(value); }
+function requireObject(value, what) {
+    if (!isPlainObject(value))
+        refuse(`${what} must be a JSON object`);
+    return value;
+}
+function optionalString(obj, key, what, max = 200) {
+    const v = obj[key];
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v !== "string")
+        refuse(`${what}.${key} must be text`);
+    if (v.length > max)
+        refuse(`${what}.${key} is too long (max ${max} characters)`);
+    return v;
+}
+function requireString(obj, key, what, max = 200) {
+    const v = optionalString(obj, key, what, max);
+    if (v === undefined || v.trim() === "")
+        refuse(`${what}.${key} is required`);
+    return v;
+}
+function rejectUnknownKeys(obj, allowed, what) {
+    const unknown = Object.keys(obj).filter((k) => !allowed.includes(k));
+    if (unknown.length > 0)
+        refuse(`${what} has a field the engine does not know: ${unknown.join(", ")} — the fields it knows are ${allowed.join(", ")}`);
+}
+function hasTemplate(value) { return value.includes("{{"); }
+function validateScalarFilter(raw, what) {
+    const obj = requireObject(raw, what);
+    const keys = Object.keys(obj);
+    if (keys.length === 0)
+        refuse(`${what} must name at least one field, or be left out`);
+    if (keys.length > MAX_WHEN_ENTRIES)
+        refuse(`${what} names ${keys.length} fields — at most ${MAX_WHEN_ENTRIES}`);
+    const unsafe = findUnsafeKeys(obj);
+    if (unsafe.length > 0)
+        refuse(`${what} names "${unsafe[0]}", which collides with a JavaScript built-in — pick another field name`);
+    const out = {};
+    for (const key of keys) {
+        const v = obj[key];
+        if (typeof v !== "string" && typeof v !== "number" && typeof v !== "boolean") {
+            refuse(`${what}.${key} must be a text, number or true/false value — the filter is an exact match per field`);
+        }
+        out[key] = v;
+    }
+    return out;
+}
+function validateVerify(raw) {
+    const v = requireObject(raw, "trigger.verify");
+    const scheme = requireString(v, "scheme", "trigger.verify", 40);
+    if (!SCHEMES.includes(scheme)) {
+        refuse(`trigger.verify.scheme "${scheme}" is not one the engine knows — use hmac_sha256_header (a header carrying an HMAC-SHA256 of the body), stripe (t=/v1=), svix (svix-id/svix-timestamp/svix-signature) or shared_token (a token in a header or ?token=)`);
+    }
+    switch (scheme) {
+        case "hmac_sha256_header": {
+            rejectUnknownKeys(v, ["scheme", "header", "timestampHeader", "toleranceSeconds", "encoding"], "trigger.verify");
+            const header = requireString(v, "header", "trigger.verify", 64);
+            if (!HEADER_NAME_RE.test(header))
+                refuse(`trigger.verify.header "${header}" is not a header name (letters, digits, hyphens)`);
+            const timestampHeader = optionalString(v, "timestampHeader", "trigger.verify", 64);
+            if (timestampHeader !== undefined && !HEADER_NAME_RE.test(timestampHeader))
+                refuse(`trigger.verify.timestampHeader "${timestampHeader}" is not a header name (letters, digits, hyphens)`);
+            let toleranceSeconds;
+            if (v.toleranceSeconds !== undefined) {
+                if (timestampHeader === undefined)
+                    refuse("trigger.verify.toleranceSeconds needs trigger.verify.timestampHeader — without a timestamp there is no window to tolerate");
+                if (typeof v.toleranceSeconds !== "number" || !Number.isInteger(v.toleranceSeconds) || v.toleranceSeconds < 1 || v.toleranceSeconds > 300) {
+                    refuse("trigger.verify.toleranceSeconds must be a whole number of seconds between 1 and 300 — five minutes is the most the engine tolerates");
+                }
+                toleranceSeconds = v.toleranceSeconds;
+            }
+            const encoding = optionalString(v, "encoding", "trigger.verify", 10);
+            if (encoding !== undefined && encoding !== "hex" && encoding !== "base64")
+                refuse('trigger.verify.encoding must be "hex" (default) or "base64"');
+            return {
+                scheme: "hmac_sha256_header",
+                header: header.toLowerCase(),
+                ...(timestampHeader !== undefined ? { timestampHeader: timestampHeader.toLowerCase(), toleranceSeconds: toleranceSeconds ?? 300 } : {}),
+                encoding: encoding === "base64" ? "base64" : "hex",
+            };
+        }
+        case "stripe":
+            rejectUnknownKeys(v, ["scheme"], "trigger.verify");
+            return { scheme: "stripe" };
+        case "svix":
+            rejectUnknownKeys(v, ["scheme"], "trigger.verify");
+            return { scheme: "svix" };
+        case "shared_token": {
+            rejectUnknownKeys(v, ["scheme", "header", "query"], "trigger.verify");
+            const header = optionalString(v, "header", "trigger.verify", 64);
+            if (header !== undefined && !HEADER_NAME_RE.test(header))
+                refuse(`trigger.verify.header "${header}" is not a header name (letters, digits, hyphens)`);
+            const query = optionalString(v, "query", "trigger.verify", 64);
+            if (query !== undefined && !QUERY_NAME_RE.test(query))
+                refuse(`trigger.verify.query "${query}" is not a query parameter name`);
+            return { scheme: "shared_token", header: (header ?? "x-webhook-token").toLowerCase(), query: query ?? "token" };
+        }
+    }
+}
+function validateReceiver(t) {
+    rejectUnknownKeys(t, ["kind", "verify", "map", "when"], "trigger");
+    if (t.verify === undefined)
+        refuse("trigger.verify is required on a receiver — say how the provider signs its calls (hmac_sha256_header, stripe, svix or shared_token)");
+    const verify = validateVerify(t.verify);
+    let map;
+    if (t.map !== undefined) {
+        const m = requireObject(t.map, "trigger.map");
+        const keys = Object.keys(m);
+        if (keys.length > MAX_MAP_ENTRIES)
+            refuse(`trigger.map names ${keys.length} fields — at most ${MAX_MAP_ENTRIES}`);
+        map = {};
+        for (const key of keys) {
+            if (isUnsafeName(key) || !MAP_NAME_RE.test(key))
+                refuse(`trigger.map field "${key}" must be a simple name (letters, digits, underscores, starting with a letter)`);
+            const path = m[key];
+            if (typeof path !== "string" || path.length === 0 || path.length > 200 || !PATH_RE.test(path)) {
+                refuse(`trigger.map.${key} must be a dotted path into the provider's payload, like events.0.details.customer_email`);
+            }
+            if (path.split(".").some((seg) => isUnsafeName(seg)))
+                refuse(`trigger.map.${key} walks through "${path.split(".").find((seg) => isUnsafeName(seg))}", which is never a field`);
+            map[key] = path;
+        }
+    }
+    let when;
+    if (t.when !== undefined) {
+        when = validateScalarFilter(t.when, "trigger.when");
+        for (const key of Object.keys(when)) {
+            if (!map || !(key in map))
+                refuse(`trigger.when names "${key}", which trigger.map does not define — when filters the MAPPED fields; add "${key}" to the map first`);
+        }
+    }
+    return { kind: "receiver", verify, ...(map ? { map } : {}), ...(when ? { when } : {}) };
+}
+function validateSchedule(t) {
+    rejectUnknownKeys(t, ["kind", "every", "at"], "trigger");
+    const every = requireString(t, "every", "trigger", 10);
+    if (!SCHEDULE_EVERY.includes(every))
+        refuse(`trigger.every "${every}" is not a period the engine runs — use one of ${SCHEDULE_EVERY.join(", ")} (nothing under 15 minutes)`);
+    const at = optionalString(t, "at", "trigger", 5);
+    if (at !== undefined) {
+        if (every !== "1d")
+            refuse('trigger.at is only for every: "1d" — a shorter period runs on the clock boundary');
+        if (!AT_RE.test(at))
+            refuse('trigger.at must be "HH:MM" in UTC, like "09:00"');
+    }
+    return { kind: "schedule", every: every, ...(at !== undefined ? { at } : {}) };
+}
+function validateDataChange(t) {
+    rejectUnknownKeys(t, ["kind", "collection", "on", "where"], "trigger");
+    const collection = requireString(t, "collection", "trigger", 64);
+    if (!COLLECTION_RE.test(collection))
+        refuse(`trigger.collection "${collection}" is not a collection name (lowercase letters, digits, underscores)`);
+    if (!Array.isArray(t.on) || t.on.length === 0)
+        refuse('trigger.on must be a non-empty list from "created", "updated", "deleted"');
+    const on = [];
+    for (const item of t.on) {
+        if (typeof item !== "string" || !RECORD_KINDS.includes(item))
+            refuse(`trigger.on contains "${String(item)}" — only created, updated and deleted exist`);
+        if (!on.includes(item))
+            on.push(item);
+    }
+    let where;
+    if (t.where !== undefined) {
+        where = validateScalarFilter(t.where, "trigger.where");
+        const reserved = findReservedFields(where);
+        if (reserved.length > 0)
+            refuse(`trigger.where names "${reserved[0]}", a server-managed field — filter on the record's own data`);
+    }
+    return { kind: "data_change", collection, on, ...(where ? { where } : {}) };
+}
+function validateTrigger(raw) {
+    const t = requireObject(raw, "trigger");
+    const kind = requireString(t, "kind", "trigger", 40);
+    switch (kind) {
+        case "receiver": return validateReceiver(t);
+        case "schedule": return validateSchedule(t);
+        case "data_change": return validateDataChange(t);
+        default:
+            return refuse(`trigger.kind "${kind}" is not a trigger the engine has — use receiver (a provider's webhook), schedule (a clock) or data_change (a record changing)`);
+    }
+}
+function validateEntitlementInput(value, what) {
+    if (typeof value !== "string" || value.trim() === "")
+        refuse(`${what}.entitlement is required — a plan or product name, or an access:<name> key`);
+    if (hasTemplate(value))
+        refuse(`${what}.entitlement cannot carry a template — a grant must name what it grants`);
+    if (value.length > 100)
+        refuse(`${what}.entitlement is too long (max 100 characters)`);
+    if (/^access:/i.test(value)) {
+        if (!ENTITLEMENT_KEY.test(value.toLowerCase())) {
+            refuse(`${what}.entitlement: requires must look like access:<name> — lowercase letters, numbers, dot, dash or underscore, up to 64 characters. access is the only kind that exists: credits, quotas and seats aren't supported yet`);
+        }
+        const slug = value.slice(value.indexOf(":") + 1);
+        if (isUnsafeName(slug))
+            refuse(`${what}.entitlement "${value}" collides with a JavaScript built-in — name the plan something a person would say`);
+    }
+    return value.trim();
+}
+function validateAction(raw, index, triggerKind) {
+    const what = `actions[${index}]`;
+    const a = requireObject(raw, what);
+    const type = requireString(a, "type", what, 40);
+    if (!ACTION_TYPES.includes(type)) {
+        refuse(`${what}.type "${type}" is not an action the engine has — the verbs are ${ACTION_TYPES.join(", ")}; anything else is compute, and compute runs on your own server behind call_url`);
+    }
+    if (triggerKind === "schedule" && PERSON_ACTIONS.has(type)) {
+        refuse(`${what}: a schedule has no person, so ${type} has no one to act on — trigger it from a receiver whose map names person_email, or from a data_change on a collection whose records have an owner`);
+    }
+    switch (type) {
+        case "write_record": {
+            rejectUnknownKeys(a, ["type", "collection", "data", "to"], what);
+            const collection = requireString(a, "collection", what, 64);
+            if (!COLLECTION_RE.test(collection))
+                refuse(`${what}.collection "${collection}" is not a collection name (lowercase letters, digits, underscores)`);
+            const data = requireObject(a.data, `${what}.data`);
+            if (Object.keys(data).length === 0)
+                refuse(`${what}.data must carry at least one field`);
+            const reserved = findReservedFields(data);
+            if (reserved.length > 0)
+                refuse(`${what}.data names "${reserved[0]}", a server-managed field — the engine writes it`);
+            const unsafe = findUnsafeKeys(data);
+            if (unsafe.length > 0)
+                refuse(`${what}.data names "${unsafe[0]}", which collides with a JavaScript built-in`);
+            if (Buffer.byteLength(JSON.stringify(data), "utf8") > MAX_RECORD_BYTES)
+                refuse(`${what}.data: Storage record payload exceeds ${MAX_RECORD_BYTES} bytes`);
+            const to = optionalString(a, "to", what, 10);
+            if (to !== undefined && to !== "person")
+                refuse(`${what}.to can only be "person" (the record is addressed to the event's person) — leave it out for an app-owned record`);
+            if (to === "person" && triggerKind === "schedule") {
+                refuse(`${what}: a schedule has no person, so to: "person" has no one to address — leave it out, or trigger from a receiver or a data_change`);
+            }
+            return { type: "write_record", collection, data: structuredClone(data), ...(to === "person" ? { to: "person" } : {}) };
+        }
+        case "grant_access": {
+            rejectUnknownKeys(a, ["type", "entitlement", "expiresAt", "reason"], what);
+            const entitlement = validateEntitlementInput(a.entitlement, what);
+            const expiresAt = optionalString(a, "expiresAt", what, 40);
+            if (expiresAt !== undefined && !DURATION_RE.test(expiresAt) && Number.isNaN(Date.parse(expiresAt))) {
+                refuse(`${what}.expiresAt must be a duration from the moment of the grant ("30d", "12h", "2w") or an ISO date`);
+            }
+            const reason = optionalString(a, "reason", what, 200);
+            return { type: "grant_access", entitlement, ...(expiresAt !== undefined ? { expiresAt } : {}), ...(reason !== undefined ? { reason } : {}) };
+        }
+        case "revoke_access": {
+            rejectUnknownKeys(a, ["type", "entitlement"], what);
+            return { type: "revoke_access", entitlement: validateEntitlementInput(a.entitlement, what) };
+        }
+        case "email_person": {
+            rejectUnknownKeys(a, ["type", "subject", "text", "kind"], what);
+            const subject = requireString(a, "subject", what, 300);
+            const text = requireString(a, "text", what, 10000);
+            const kind = optionalString(a, "kind", what, 10);
+            if (kind !== undefined && kind !== "event" && kind !== "account")
+                refuse(`${what}.kind must be "event" (capped per person) or "account" (account activity — sign-in, access, billing trouble)`);
+            return { type: "email_person", subject: subject.replace(/[\r\n]+/g, " ").trim(), text, ...(kind !== undefined ? { kind: kind } : {}) };
+        }
+        case "call_url": {
+            rejectUnknownKeys(a, ["type", "url"], what);
+            const url = requireString(a, "url", what, 2048);
+            if (hasTemplate(url))
+                refuse(`${what}.url cannot carry a template — the address is checked before every call, and a substituted address would be a different one`);
+            let parsed;
+            try {
+                parsed = new URL(url);
+            }
+            catch {
+                return refuse(`${what}.url must be an absolute https:// URL`);
+            }
+            const host = parsed.hostname.replace(/^\[|\]$/g, "");
+            if (parsed.protocol !== "https:")
+                refuse(`${what}.url must be https:// — http:// and every other scheme are refused`);
+            if (isIP(host) !== 0)
+                refuse(`${what}.url must name a host, not an IP address`);
+            if (isOwnHost(host))
+                refuse(`${what}.url must not point at gemmein.com, a gemmein.com subdomain, the API's own host or the file CDN`);
+            if (parsed.username || parsed.password)
+                refuse(`${what}.url must not carry credentials — put a secret in your function, not in the address`);
+            return { type: "call_url", url };
+        }
+    }
+}
+/** The cloud's rules (localMode off: https only). Throws
+ *  RelayDefinitionError with the one sentence. */
+export function validateRelayDefinition(input) {
+    const def = requireObject(input, "the relay");
+    rejectUnknownKeys(def, ["name", "trigger", "actions"], "the relay");
+    const name = requireString(def, "name", "the relay", 64);
+    if (!RELAY_NAME_RE.test(name))
+        refuse(`name "${name}" must be 2–63 lowercase letters, digits and hyphens, starting with a letter — it becomes the receiver URL and the file name`);
+    const trigger = validateTrigger(def.trigger);
+    if (!Array.isArray(def.actions) || def.actions.length === 0)
+        refuse("actions must be a non-empty list — a relay that does nothing is not one");
+    if (def.actions.length > ACTIONS_PER_RELAY)
+        refuse(`actions lists ${def.actions.length} — at most ${ACTIONS_PER_RELAY} per relay; split the rest into a second relay`);
+    const actions = def.actions.map((raw, i) => validateAction(raw, i, trigger.kind));
+    return { name, trigger, actions };
+}
+// ── the English sentence (schema.ts describeRelay, mirrored) ────────
+const EVERY_WORDS = {
+    "15m": "Every 15 minutes",
+    "30m": "Every 30 minutes",
+    "1h": "Every hour",
+    "6h": "Every 6 hours",
+    "12h": "Every 12 hours",
+    "1d": "Every day",
+};
+function filterWords(filter) {
+    if (!filter)
+        return "";
+    return " where " + Object.entries(filter).map(([k, v]) => `${k} is ${typeof v === "string" ? v : String(v)}`).join(" and ");
+}
+function listWords(items) {
+    if (items.length <= 1)
+        return items[0] ?? "";
+    return `${items.slice(0, -1).join(", ")} or ${items[items.length - 1]}`;
+}
+function entitlementWords(value) {
+    return value.startsWith("access:") ? value.slice("access:".length) : value;
+}
+export function describeRelay(def) {
+    const t = def.trigger;
+    let when;
+    if (t.kind === "receiver")
+        when = `When ${def.name} receives an event${filterWords(t.when)}`;
+    else if (t.kind === "schedule")
+        when = t.at ? `${EVERY_WORDS[t.every]} at ${t.at} UTC` : EVERY_WORDS[t.every];
+    else
+        when = `When a ${t.collection} record is ${listWords(t.on)}${filterWords(t.where)}`;
+    const actions = def.actions.map((a) => {
+        switch (a.type) {
+            case "write_record": return `write a ${a.collection} record${a.to === "person" ? " for the person" : ""}`;
+            case "grant_access": return `grant ${entitlementWords(a.entitlement)}`;
+            case "revoke_access": return `revoke ${entitlementWords(a.entitlement)}`;
+            case "email_person": return "email the person";
+            case "call_url": return `call ${a.url}`;
+        }
+    });
+    return `${when} → ${actions.join(", ")}`;
+}
+/** The tool's answer: the sentence, or the refusal, plus what only the
+ *  cloud can check. Never throws on a bad definition. */
+export function explainRelay(input) {
+    try {
+        const definition = validateRelayDefinition(input);
+        return { ok: true, sentence: describeRelay(definition), definition };
+    }
+    catch (error) {
+        if (error instanceof RelayDefinitionError)
+            return { ok: false, refusal: error.message };
+        throw error;
+    }
+}
+export const CLOUD_ONLY_NOTE = "Checked offline with the cloud's definition rules. Two things are checked only when it runs there: " +
+    "call_url must not point at the API's own host or the file CDN (gemmein.com is refused here), and at call time the address " +
+    "must resolve to a public host (loopback, private and link-local ranges are refused; redirects are not followed). " +
+    "Locally, `gemmein dev` also allows call_url to http://localhost — the cloud never does.";

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@gemmein/mcp",
-  "version": "0.2.1",
+  "version": "0.3.0",
+  "mcpName": "com.gemmein/mcp",
   "description": "Gemmein MCP server \u2014 gives coding agents the Gemmein guide, API reference, rule/error explainers, and a live integration check (reaffirm) as tools. Read-only: it never creates, edits, or deletes anything.",
   "license": "MIT",
   "type": "module",
@@ -11,7 +12,7 @@
     "dist"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "keywords": [
     "mcp",
@@ -33,7 +34,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@gemmein/sdk": "^0.4.4",
+    "@gemmein/sdk": "^0.6.0",
     "@modelcontextprotocol/sdk": "^1.29.0"
   },
   "author": "Gemmein Limited",