@mapled/mcp 0.18.0 → 0.18.2

package/README.md

@@ -38,6 +38,8 @@ claude mcp add mapled -e MAPLED_MCP_TOKEN=mcp_live_… -- npx -y @mapled/mcp
 
 The token is scoped to one project. Set `MAPLED_API_URL` only if you're not on the default `https://api.mapled.io`.
 
+Over either transport, a refusal reaches the agent as Mapled words it — a key that is taken, a plan still waiting for approval, the slug it sent that another record already has. An error whose text carries anything shaped like a Mapled key or token that the call didn't send itself reaches it as one constant sentence instead: no tool answer, its errors included, hands the agent a secret.
+
 ## Setting up a site
 
 For the first integration, propose one plan and let the owner approve it on a trusted Mapled screen:
@@ -63,7 +65,7 @@ A rename or a conversion Mapled wouldn't take is refused at once with the reason
 | `propose_setup_plan` / `get_setup_run` / `apply_setup_plan` / `report_setup` / `verify_setup` | One approved plan for the whole setup — every field type including relations (`$ref` handles between plan records, ids for existing collections) and groups — verified by Mapled (see above) |
 | `get_schema` | Read the project's collections and fields |
 | `create_collection` | Add a collection or single |
-| `add_field` | Add a field (short_text, long_text, rich_text, slug, image, number, boolean, date, datetime, relation, enum, url, email, group, file, color, json — an object or list up to 32 KB, location — { lat, lng }, computed). Optional `validation` ({min, max, pattern}) and `defaultValue`; `relation` ({target, cardinality: one \| many, onDelete: restrict \| nullify}) is required for relation fields — values are record ids of the target collection, kept in the order given; `onDelete` says what a delete of a linked record does (restrict: it can't be deleted while linked, nullify: the links are cleared — the default is restrict for required fields and nullify otherwise); `options` (1–50 labels) is required for enum fields; `sensitive: true` keeps a field out of lists, history and delivery (a group's sub-fields take it too); `group` ({fields, repeatable, maxItems}) shapes a group field — its values are objects (or arrays of them) keyed by the sub-field keys; `computed` ({expression}) makes a computed field — a formula Mapled evaluates whenever a record is read or published, over the record's fields and up to two links through relations (`author.company.name`, `sum(items.product.price)`) or back along one and one link on (`count(@posts.author)`, `sum(@order-items.order.product.price)`), at most one list per path, never a sensitive field or relation; the site reads the value like any field of its result type. |
+| `add_field` | Add a field (short_text, long_text, rich_text, slug, image, number, boolean, date, datetime, relation, enum, url, email, group, file, color, json — an object or list up to 32 KB, location — { lat, lng }, computed). Optional `validation` ({min, max, pattern}) and `defaultValue`; `relation` ({target, cardinality: one \| many, onDelete: restrict \| nullify}) is required for relation fields — values are record ids of the target collection, kept in the order given; `onDelete` says what a delete of a linked record does (restrict: it can't be deleted while linked, nullify: the links are cleared — the default is restrict for required fields and nullify otherwise); `options` (1–50 labels) is required for enum fields; `sensitive: true` keeps a field out of lists, history and delivery (a group's sub-fields take it too); `group` ({fields, repeatable, maxItems}) shapes a group field — its values are objects (or arrays of them) keyed by the sub-field keys; `computed` ({expression}) makes a computed field — a formula Mapled evaluates whenever a record is read or published, over the record's fields and up to two links through relations (`author.company.name`, `sum(items.product.price)`) or back along one and one link on (`count(@posts.author)`, `sum(@order-items.order.product.price)`), at most one list per path, never a sensitive field or relation; `today()` and `now()` are the moment the value was computed — baked at publish and recomputed once a day for the current release; the site reads the value like any field of its result type. |
 | `add_records` | Insert draft records |
 | `list_records` | Read a collection's draft records, newest edit first — `query` searches their content, `limit` (1–200) and `cursor` (the previous answer's `nextCursor`) page through them; `total` counts every match |
 | `create_form` / `list_forms` | Set up public forms with spam protection |

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { createApiClient, createTools } from "./tools.js";
+import { createApiClient, registerTools } from "./tools.js";
 /** Mapled MCP server. Auth and scope come from the environment:
     MAPLED_MCP_TOKEN — the project token from Connect with AI (required)
     MAPLED_API_URL   — API origin (default https://api.mapled.io) */
@@ -12,27 +12,8 @@ if (!token) {
 }
 const baseUrl = process.env.MAPLED_API_URL ?? "https://api.mapled.io";
 const server = new McpServer({ name: "mapled", version: "0.1.0" });
-const api = createApiClient(baseUrl, token);
-for (const tool of createTools(api)) {
-    // The SDK's generic inference recurses on our union of shapes; the
-    // runtime contract is identical, so erase the generics here.
-    server.tool(tool.name, tool.description, tool.schema, async (args) => {
-        try {
-            const result = await tool.handler(args);
-            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
-        }
-        catch (err) {
-            return {
-                isError: true,
-                content: [
-                    {
-                        type: "text",
-                        text: err instanceof Error ? err.message : "Mapled request failed.",
-                    },
-                ],
-            };
-        }
-    });
-}
+// every call answers through runTool: an error reaches the model only
+// as a text without a Mapled key or token in it (§36.12)
+registerTools(server, createApiClient(baseUrl, token));
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/dist/tools.d.ts

@@ -4,6 +4,8 @@ import { z } from "zod";
 export type ApiClient = {
     request: (method: "GET" | "POST" | "PATCH", path: string, body?: unknown) => Promise<unknown>;
 };
+/** What a call answers when its request never reached Mapled. */
+export declare const UNREACHABLE = "The request didn't reach Mapled. Try again, or tell the person if it keeps failing: MAPLED_API_URL or MAPLED_MCP_TOKEN in the MCP settings may need a fresh copy. Don't ask them to paste the token into the conversation.";
 export declare function createApiClient(baseUrl: string, token: string): ApiClient;
 export declare const FIELD_TYPES: readonly ["short_text", "long_text", "rich_text", "slug", "image", "number", "boolean", "date", "relation", "enum", "url", "email", "group", "datetime", "file", "color", "json", "location", "computed"];
 export type ToolDef = {
@@ -12,4 +14,26 @@ export type ToolDef = {
     schema: z.ZodRawShape;
     handler: (args: never) => Promise<unknown>;
 };
+/** What a failed call answers when its own text can't pass. */
+export declare const HELD_BACK = "Mapled couldn't complete this call, and its error can't be shown here. Try again, or tell the person if it keeps failing.";
+/** The text an error reaches the model with (§36.12): its message when
+    routeText passes it — a route's refusal, as worded — or HELD_BACK.
+    `args` are the call's arguments, the runs the model sent. Never
+    throws: what escapes a tool's callback the SDK answers with, unread. */
+export declare function errorText(err: unknown, args?: unknown): string;
+export type ToolAnswer = {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: true;
+};
+/** One call as the model reads it, over stdio and the hosted /mcp alike:
+    the tool's answer as JSON, or an error that errorText lets through. */
+export declare function runTool(tool: ToolDef, args: unknown): Promise<ToolAnswer>;
+/** The one way a transport offers the tools: every call answers through
+    runTool, so no error text reaches the model past it. */
+export declare function registerTools(server: {
+    tool: (...args: never[]) => unknown;
+}, api: ApiClient): void;
 export declare function createTools(api: ApiClient): ToolDef[];

package/dist/tools.js

@@ -1,15 +1,26 @@
 import { z } from "zod";
+/** What a call answers when its request never reached Mapled. */
+export const UNREACHABLE = "The request didn't reach Mapled. Try again, or tell the person if it keeps failing: MAPLED_API_URL or MAPLED_MCP_TOKEN in the MCP settings may need a fresh copy. Don't ask them to paste the token into the conversation.";
 export function createApiClient(baseUrl, token) {
     return {
         async request(method, path, body) {
-            const res = await fetch(`${baseUrl}${path}`, {
-                method,
-                headers: {
-                    authorization: `Bearer ${token}`,
-                    ...(body !== undefined ? { "content-type": "application/json" } : {}),
-                },
-                body: body !== undefined ? JSON.stringify(body) : undefined,
-            });
+            let res;
+            try {
+                res = await fetch(`${baseUrl}${path}`, {
+                    method,
+                    headers: {
+                        authorization: `Bearer ${token}`,
+                        ...(body !== undefined ? { "content-type": "application/json" } : {}),
+                    },
+                    body: body !== undefined ? JSON.stringify(body) : undefined,
+                });
+            }
+            catch {
+                // the runtime's text is no route's refusal, and it may quote the
+                // request: a header it refused names the token, in pieces too short
+                // for any text filter when line breaks cut it (§36.12)
+                throw new Error(UNREACHABLE);
+            }
             const payload = (await res.json().catch(() => null));
             if (!res.ok) {
                 throw new Error(payload?.error?.message ?? `Mapled API error (${res.status}).`);
@@ -44,22 +55,93 @@ const COMPUTED_HELP = "For type computed only: { expression } — a formula over
     "Field keys as written (price, unit-cost — put spaces around a minus to subtract: price - cost); up to two links through relations: author.name, author.company.name, and lists over many-relations for aggregates: sum(items.price), count(tags), join(tags.name, \", \"), sum(items.product.price); or one link back — the records of another collection whose relation points at this record, written @collection.relation[.field], always a list, oldest first: count(@posts.author), sum(@order-items.order.total), max(@posts.author.published-on) — and one more link on from them: sum(@order-items.order.product.price). A path goes through at most one list (a many-relation, or the records that link back), so items.tags.name is refused. " +
     "Numbers: + - * / %, round(x, digits), floor, ceil, abs, min, max, sum, avg, count, fixed(x, digits) → text. Text: & joins (empty counts as \"\"), concat, upper, lower, trim, length, left(s, n), right(s, n), replace(s, from, to), contains(s, part), slug(s), text(x), number(s). " +
     "Logic: = != < <= > >=, and, or, not, if(cond, a, b), coalesce(a, b), empty(x). Dates: year, month, day, date(datetime), daysBetween(a, b), addDays(d, n), created() — when the record was added (a datetime). Literals: 12, 2.5, \"text\", true, false, null. " +
-    "Sensitive fields and relations, groups, JSON and location can't be read; there is no now(). The result type (number, text, boolean, date, datetime) follows from the formula.";
+    "today() and now() — the day and the moment the value was computed: a publish bakes them into the release, and Mapled recomputes the current release once a day (after midnight UTC), sending the publish webhook again — so daysBetween(today(), due) counts down, but not by the minute; a pinned release keeps its values. " +
+    "Sensitive fields and relations, groups, JSON and location can't be read. The result type (number, text, boolean, date, datetime) follows from the formula.";
 /** The variable the site's revalidate route verifies publishes with. */
 const WEBHOOK_SECRET_ENV = "MAPLED_WEBHOOK_SECRET";
 /** The header a publish webhook carries its signature in. */
 const SIGNATURE_HEADER = "x-mapled-signature";
-/** A text as the route words it, or nothing: an overlong text, a run of 24
-    letters and digits (a signing secret is 48 hex digits) or a Mapled
-    credential prefix never passes, so a secret sent whole or with its prefix
-    can't reach the model. A text filter can't promise more — the route's
+/** The prefix of every key and token Mapled issues — the report mask's
+    `KEYS` (apps/api/src/lib/reportRedaction.ts); the API's
+    `security/mcpErrors.test.ts` sends one of each kind through both
+    transports. */
+const CREDENTIAL_PREFIX = /(?:whsec|mk_live|msk_live|mcp_live|mcp_oauth|mcp_refresh|mcp_code|mpv|mps)_/i;
+/** What a reader takes a text for: compatibility forms read as ASCII
+    (fullwidth letters, the fullwidth low line), and marks, control
+    characters other than line breaks and tabs, and characters drawn as
+    nothing are gone — a key interleaved with them reads whole. */
+const INVISIBLE = /[\p{M}\p{Cf}\p{Default_Ignorable_Code_Point}\p{Cn}\p{Cs}\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/gu;
+const readAs = (text) => text.normalize("NFKD").replace(INVISIBLE, "");
+/** Runs of a text that read as a key's or token's random part, each with
+    what makes it one:
+    - 24 letters and digits — a hex key or secret is 32 or 48;
+    - 24 or more characters of base64 or base64url that mix upper- and
+      lower-case letters, as a random one does — a key, a slug or a path
+      Mapled writes is lower-case, a constant's name upper-case;
+    - as many characters of base64url as a token's random part has, 43
+      (`generateToken`: 32 bytes), whatever its letters — a random one
+      can come out all in one case or with no letter at all. */
+const RANDOM_RUNS = [
+    [/[A-Za-z0-9]{24,}/g, () => true],
+    [/[A-Za-z0-9+/=_-]{24,}/g, (run) => /[A-Z]/.test(run) && /[a-z]/.test(run)],
+    [/[A-Za-z0-9_-]{43,}/g, () => true],
+];
+/** A text as the route words it, or nothing. It never passes when, read as
+    a reader would, it holds a Mapled key or token prefix in any letter
+    case or a run that reads as a random part (RANDOM_RUNS) the model
+    didn't send itself — or when it is longer than 1000 characters. A run
+    the model sent (`sent` — the call's arguments), echoed back, tells it
+    nothing: the slug it asked for that another record already has passes,
+    however long. So a credential whole, with its prefix or its random
+    part alone can't reach the model. A text filter can't promise more —
+    one split into short pieces or re-encoded passes — and the route's
     refusals have to pass as worded. */
-const routeText = (value) => typeof value === "string" &&
-    value.length <= 1000 &&
-    !/[A-Za-z0-9]{24}/.test(value) &&
-    !/(?:whsec|mk_live|msk_live|mcp_live|mpv)_/i.test(value)
-    ? value
-    : undefined;
+const routeText = (value, sent = "") => {
+    if (typeof value !== "string" || value.length > 1000)
+        return undefined;
+    const read = readAs(value);
+    if (CREDENTIAL_PREFIX.test(read))
+        return undefined;
+    const random = RANDOM_RUNS.flatMap(([runs, like]) => (read.match(runs) ?? []).filter((run) => like(run)));
+    if (random.length === 0)
+        return value;
+    const known = readAs(sent);
+    return random.every((run) => known.includes(run)) ? value : undefined;
+};
+/** What a failed call answers when its own text can't pass. */
+export const HELD_BACK = "Mapled couldn't complete this call, and its error can't be shown here. Try again, or tell the person if it keeps failing.";
+/** The text an error reaches the model with (§36.12): its message when
+    routeText passes it — a route's refusal, as worded — or HELD_BACK.
+    `args` are the call's arguments, the runs the model sent. Never
+    throws: what escapes a tool's callback the SDK answers with, unread. */
+export function errorText(err, args) {
+    try {
+        return routeText(err instanceof Error ? err.message : undefined, JSON.stringify(args) ?? "") ?? HELD_BACK;
+    }
+    catch {
+        return HELD_BACK;
+    }
+}
+/** One call as the model reads it, over stdio and the hosted /mcp alike:
+    the tool's answer as JSON, or an error that errorText lets through. */
+export async function runTool(tool, args) {
+    try {
+        const result = await tool.handler(args);
+        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    }
+    catch (err) {
+        return { isError: true, content: [{ type: "text", text: errorText(err, args) }] };
+    }
+}
+/** The one way a transport offers the tools: every call answers through
+    runTool, so no error text reaches the model past it. */
+export function registerTools(server, api) {
+    for (const tool of createTools(api)) {
+        // The SDK's generic inference recurses on our union of shapes; the
+        // runtime contract is identical, so erase the generics here.
+        server.tool(tool.name, tool.description, tool.schema, (args) => runTool(tool, args));
+    }
+}
 /** The address the route saved: the agent's own, as the URL parser writes it. */
 const savedUrl = (sent, answered) => {
     try {
@@ -105,7 +187,7 @@ function configureRevalidation(api) {
                 hook = ((await api.request("PATCH", "/v1/agent/webhook", { url: args.url })) ?? {});
             }
             catch (err) {
-                throw new Error(routeText(err instanceof Error ? err.message : undefined) ?? "Mapled couldn't save the webhook. Try again.");
+                throw new Error(routeText(err instanceof Error ? err.message : undefined, JSON.stringify(args)) ?? "Mapled couldn't save the webhook. Try again.");
             }
             const status = hook.signingSecret?.status;
             return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mapled/mcp",
-  "version": "0.18.0",
+  "version": "0.18.2",
   "description": "Mapled MCP server: lets AI agents build schema and content for one Mapled project.",
   "license": "MIT",
   "homepage": "https://mapled.io",