@gemmein/mcp 0.2.2 → 0.3.0

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 {
@@ -288,6 +289,19 @@ const TOOLS = [
         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: "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.",
@@ -326,7 +340,8 @@ const server = new Server(
         "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, check_integration before declaring the app done.",
+        "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 }] });
@@ -377,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,8 +1,8 @@
 {
   "name": "@gemmein/mcp",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "mcpName": "com.gemmein/mcp",
-  "description": "Gemmein MCP server — 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.",
+  "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",
   "bin": {
@@ -12,7 +12,7 @@
     "dist"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "keywords": [
     "mcp",
@@ -34,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",