@mapled/mcp 0.17.0 → 0.18.0

package/README.md

@@ -46,7 +46,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.
 
@@ -69,8 +69,8 @@ A rename or a conversion Mapled wouldn't take is refused at once with the reason
 | `create_form` / `list_forms` | Set up public forms with spam protection |
 | `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`, `{ 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+), declared then in the manifest's `capabilities` |
+| `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). 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/tools.js

@@ -45,6 +45,78 @@ 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";
+/** 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
+    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;
+/** 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) ?? "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 [
         {
@@ -297,7 +369,8 @@ export function createTools(api) {
                 "expects no webhook and no preview route. A plain HTML page that shows one record keeps the slug in its " +
                 "query — name it \"/post.html?slug=[slug]\", with a route_param binding on the slug field. " +
                 "`capabilities` says whether pages that are already open follow a publish (live updates): a Next.js site " +
-                "that renders <MapledLive /> (or calls watchRelease) and serves createReleaseHandler as GET at a route " +
+                "that renders <MapledLive /> (or calls watchRelease) and serves createReleaseHandler as GET at a route — " +
+                "on the Pages Router createPagesReleaseHandler as an API route's default export — " +
                 "sends { realtime: true, releaseRoute: \"/api/mapled/release\" } — the path its tabs ask; a site " +
                 "rendered in the browser whose tabs ask Mapled directly (live on MapledProvider, data-mapled-live on the " +
                 "script tag) sends { realtime: true }; a site without live updates sends { realtime: false }. Only these two keys " +
@@ -546,25 +619,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 — 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.0",
+  "version": "0.18.0",
   "description": "Mapled MCP server: lets AI agents build schema and content for one Mapled project.",
   "license": "MIT",
   "homepage": "https://mapled.io",