@mapled/mcp 0.18.0 → 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:

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}).`);
@@ -49,17 +60,87 @@ const COMPUTED_HELP = "For type computed only: { expression } — a formula over
 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 +186,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.1",
   "description": "Mapled MCP server: lets AI agents build schema and content for one Mapled project.",
   "license": "MIT",
   "homepage": "https://mapled.io",