@mapled/mcp 0.17.1 → 0.18.1

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:
@@ -46,7 +48,7 @@ For the first integration, propose one plan and let the owner approve it on a tr
 2. `propose_setup_plan` — the collections and singles (with fields and the records to import), the files you will change, the packages you will install. Nothing changes yet. Relation fields name their target — a collection of the plan by its display name, or an existing one by key; give a record a `"$ref": "jane"` and other records of the plan link to it as `"author": "jane"` (a list of refs for `many`), while links to existing collections use record ids from `list_records`. Group fields carry their sub-fields; their values are objects keyed by the sub-field keys. Mark a field — or a sub-field of a group — `sensitive: true` when editors keep it but the site must never get it. A link that does not resolve is answered right away with its path, so fix the plan before the owner sees it.
 3. Ask the user to open the returned `reviewUrl` and approve. Poll `get_setup_run` until its status is `approved` (or `rejected` — then propose a better plan).
 4. `apply_setup_plan` — Mapled creates everything in one go and tells you the keys it assigned.
-5. Wire the site: `get_connection`, then `configure_revalidation` for a site with a server — or `set_site_url` for one rendered in the browser (a React single-page app, plain HTML: no webhook, no preview route) — and deploy.
+5. Wire the site: `get_connection`, then `configure_revalidation` for a site with a server — or `set_site_url` for one rendered in the browser (a React single-page app, plain HTML: no webhook, no preview route) — and deploy. The webhook's signing secret never passes through the agent: the owner takes it from Mapled → Integrations → Your site, where Rotate secret shows a new one once, into the site's env as `MAPLED_WEBHOOK_SECRET`.
 6. Leave a guide: `get_mapled_md` renders `MAPLED.md` from the project — what the site reads and where, the content model, the working rules, the commands that verify the integration. Write it to the repository root and commit it; the next agent (or person) starts from it. When the file exists, replace everything above its `<!-- mapled:notes -->` line and keep the notes below.
 7. Close with `report_setup` (files changed, `buildPassed`, `secretsCommitted: false`, `mapledMdWritten: true`). Mapled runs its own checks — the site reads content, the webhook delivered, the preview route responds, fields have help texts, MAPLED.md was written — and the run is completed only when they pass. Fix what failed and call `verify_setup`. The result lands in the file's «Last setup run» section, so call `get_mapled_md` once more when the run is settled and commit the refreshed file.
 
@@ -70,7 +72,7 @@ A rename or a conversion Mapled wouldn't take is refused at once with the reason
 | `get_connection` | The delivery key and the API URL, plus — for the `framework` the agent names (`nextjs`, `react-spa`, `plain-html`, …) or the project's own — the package the site reads through (`@mapled/next`, `@mapled/react`, `@mapled/vanilla` — a script tag and `data-mapled-*` attributes for plain HTML — or `@mapled/client`), the env var of the key, whether the site renders on a server or in the browser, and the wire-up steps. Image values → `assetUrl(id, { width })` of the same package |
 | `set_site_url` | Where the site is deployed — for a site rendered in the browser (a React single-page app, plain HTML), which has no webhook to learn it from: Preview opens the site there, verification checks that it answers |
 | `push_site_manifest` / `list_bindings` | Tell Mapled where each field is rendered; read every binding's health (type mismatch, outdated, missing on site). Keep the repository's copy in `mapled/manifest.json` — `npx @mapled/cli scan --write` derives it from the code and `bindings push` / `bindings pull` exchange it with Mapled. A push records the integration hash — the schema and these bindings — and `list_bindings` says whether it still matches (`integration.inSync`, with `schemaChanged` / `bindingsChanged` naming what moved). `capabilities` says whether open tabs follow Publish: `{ realtime: true, releaseRoute: "/api/mapled/release" }` for a Next.js site with `<MapledLive />` and `createReleaseHandler` (on the Pages Router, `createPagesReleaseHandler`), `{ realtime: true }` for a site rendered in the browser whose tabs ask Mapled directly (`live` on `MapledProvider`, `data-mapled-live` on the script tag), `{ realtime: false }` without live updates — only these two keys; MAPLED.md's Live updates line comes from it, so send it with every push |
-| `configure_revalidation` | Point the publish webhook at the site (one with a server that caches what it reads), get the signing secret; the description also tells the agent how to add live updates for tabs that are already open (`createReleaseHandler` and `<MapledLive />`, `@mapled/next` 0.8.0+; on the Pages Router `createPagesReleaseHandler` as an API route's default export and `<MapledLive />` from `@mapled/next/live/pages`, 0.9.0+), declared then in the manifest's `capabilities` |
+| `configure_revalidation` | Point the publish webhook at the site (one with a server that caches what it reads). No answer carries the signing secret: it names the variable, `MAPLED_WEBHOOK_SECRET`, and the person takes the value from Mapled → Integrations → Your site, where Rotate secret shows a new one once, into the site's env. The description also tells the agent how to add live updates for tabs that are already open (`createReleaseHandler` and `<MapledLive />`, `@mapled/next` 0.8.0+; on the Pages Router `createPagesReleaseHandler` as an API route's default export and `<MapledLive />` from `@mapled/next/live/pages`, 0.9.0+), declared then in the manifest's `capabilities` |
 | `check_integration` | The site's integration as Mapled sees it — delivery reads, the webhook and its last delivery, the bindings summary, the integration hash (is the last push still in step with the schema and the bindings?), current package versions; `npx @mapled/cli doctor` shows the same from inside the repository |
 | `delete_collection` / `remove_field` / `clear_records` / `rename_field` / `convert_field` / `get_confirmation` | Destructive and breaking changes — each files a request a person confirms on a trusted Mapled screen (see above); `get_confirmation` reads its status |
 | `get_mapled_md` | `MAPLED.md` rendered from the project — the guide for the next agent: project, how the site reads it, content model, bindings by page, last setup run, working rules, verification commands. Never a secret. `npx @mapled/cli md pull` writes the same file; `mapled doctor` says when it is out of date |

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}).`);
@@ -45,6 +56,148 @@ const COMPUTED_HELP = "For type computed only: { expression } — a formula over
     "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.";
+/** 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";
+/** 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, 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 {
+        return typeof answered === "string" && answered === new URL(sent).href ? answered : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/** configure_revalidation: the signing secret never passes through the
+    agent (§36.12) — the answer names the variable and hands the person
+    the step, over stdio and the hosted endpoint alike. Only the route's
+    own shapes pass: the agent's address as saved, the signature header's
+    name, a status of its two words, and texts — a refusal's too — that
+    carry no secret whole or with its prefix. */
+function configureRevalidation(api) {
+    return {
+        name: "configure_revalidation",
+        description: "Point Mapled's publish webhook at the site so published changes appear instantly. Only for a site with " +
+            "a server that caches what it reads (Next.js and the like); a site rendered in the browser (react-spa, " +
+            "plain-html) shows a publish on the next load and needs none — call set_site_url for it instead. " +
+            "Pass the site's public revalidate URL (with @mapled/next: mount createRevalidateHandler " +
+            "from \"@mapled/next/server\" at /api/mapled/revalidate and pass that URL here). " +
+            "The webhook's signing secret never passes through you: the answer says how the person sets " +
+            `${WEBHOOK_SECRET_ENV} in the site's env — they copy it from Mapled → Integrations → Your site. ` +
+            "Don't ask them to paste it into the conversation. " +
+            "Local and private URLs are rejected; use the deployed site's URL. " +
+            "Optional, when the owner wants pages that are already open to follow a publish without a reload " +
+            "(@mapled/next 0.8.0+): also mount createReleaseHandler({ key: process.env.MAPLED_KEY! }) from " +
+            "\"@mapled/next/server\" as GET at /api/mapled/release and render <MapledLive /> from " +
+            "\"@mapled/next/live\" once in the root layout. On the Pages Router (@mapled/next 0.9.0+) export " +
+            "createPagesReleaseHandler({ key: process.env.MAPLED_KEY! }) from \"@mapled/next/server\" as the default " +
+            "of pages/api/mapled/release.ts and render <MapledLive /> from \"@mapled/next/live/pages\" in pages/_app; " +
+            "there only pages that read in getServerSideProps follow a publish (the @mapled/next README, Live updates → " +
+            "Pages Router). Tabs poll the site's own route, never Mapled; then declare it in push_site_manifest's " +
+            "capabilities.",
+        schema: {
+            url: z.string().min(8).max(2048),
+        },
+        handler: async (args) => {
+            let hook;
+            try {
+                hook = ((await api.request("PATCH", "/v1/agent/webhook", { url: args.url })) ?? {});
+            }
+            catch (err) {
+                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 {
+                url: savedUrl(args.url, hook.url),
+                signatureHeader: hook.signatureHeader === SIGNATURE_HEADER ? SIGNATURE_HEADER : undefined,
+                signingSecret: { env: WEBHOOK_SECRET_ENV, status: status === "created" || status === "existing" ? status : undefined },
+                next: routeText(hook.next),
+            };
+        },
+    };
+}
 export function createTools(api) {
     return [
         {
@@ -547,29 +700,7 @@ export function createTools(api) {
             },
             handler: async (args) => api.request("PATCH", "/v1/agent/site", { url: args.url }),
         },
-        {
-            name: "configure_revalidation",
-            description: "Point Mapled's publish webhook at the site so published changes appear instantly. Only for a site with " +
-                "a server that caches what it reads (Next.js and the like); a site rendered in the browser (react-spa, " +
-                "plain-html) shows a publish on the next load and needs none — call set_site_url for it instead. " +
-                "Pass the site's public revalidate URL (with @mapled/next: mount createRevalidateHandler " +
-                "from \"@mapled/next/server\" at /api/mapled/revalidate and pass that URL here). " +
-                "Returns the signing secret — store it in the site's env as MAPLED_WEBHOOK_SECRET. " +
-                "Local and private URLs are rejected; use the deployed site's URL. " +
-                "Optional, when the owner wants pages that are already open to follow a publish without a reload " +
-                "(@mapled/next 0.8.0+): also mount createReleaseHandler({ key: process.env.MAPLED_KEY! }) from " +
-                "\"@mapled/next/server\" as GET at /api/mapled/release and render <MapledLive /> from " +
-                "\"@mapled/next/live\" once in the root layout. On the Pages Router (@mapled/next 0.9.0+) export " +
-                "createPagesReleaseHandler({ key: process.env.MAPLED_KEY! }) from \"@mapled/next/server\" as the default " +
-                "of pages/api/mapled/release.ts and render <MapledLive /> from \"@mapled/next/live/pages\" in pages/_app; " +
-                "there only pages that read in getServerSideProps follow a publish (the @mapled/next README, Live updates → " +
-                "Pages Router). Tabs poll the site's own route, never Mapled; then declare it in push_site_manifest's " +
-                "capabilities.",
-            schema: {
-                url: z.string().min(8).max(2048),
-            },
-            handler: async (args) => api.request("PATCH", "/v1/agent/webhook", { url: args.url }),
-        },
+        configureRevalidation(api),
         {
             name: "get_mapled_md",
             description: "Get MAPLED.md — the guide Mapled writes for the next agent and for people: the project and how the site " +

package/package.json

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