@mapled/mcp 0.13.2 → 0.14.1

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`, `configure_revalidation`, deploy, then close with `report_setup` (files changed, `buildPassed`, `secretsCommitted: false`). Mapled runs its own checks — the site reads content, the webhook delivered, the preview route responds, fields have help texts — and the run is completed only when they pass. Fix what failed and call `verify_setup`.
+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) — deploy, then close with `report_setup` (files changed, `buildPassed`, `secretsCommitted: false`). Mapled runs its own checks — the site reads content, the webhook delivered, the preview route responds, fields have help texts — and the run is completed only when they pass. Fix what failed and call `verify_setup`.
 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.
 
 ## Destructive and breaking changes
@@ -66,9 +66,10 @@ A rename or a conversion Mapled wouldn't take is refused at once with the reason
 | `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 |
-| `get_connection` (image values → `assetUrl(id, { width })` from @mapled/next) | Delivery key + API URL for wiring the site (`@mapled/next`) |
+| `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) |
-| `configure_revalidation` | Point the publish webhook at the site, 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+) |
+| `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+) |
 | `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

@@ -286,7 +286,12 @@ export function createTools(api) {
                 "image_alt, link, number, date, boolean, collection for a repeated list, route_param, form_field). " +
                 "Push the full list every time; bindings you leave out are marked missing on the site. Mapled grades " +
                 "each binding against the schema (healthy, type mismatch, outdated) and returns warnings for unknown " +
-                "collections or fields. The answer's manifest.integrationHash is the hash of the schema and these " +
+                "collections or fields. `framework` is what the site is built with, as a short key: \"nextjs\", " +
+                "\"react-spa\" (a React single-page app — Vite and the like), \"plain-html\", or astro, remix, nuxt, " +
+                "sveltekit…; react-spa and plain-html tell Mapled the site renders in the browser, so verification " +
+                "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. " +
+                "The answer's manifest.integrationHash is the hash of the schema and these " +
                 "bindings — what the site is synced with from now on; check_integration reports inSync against it. " +
                 "Needs the builder plan.",
             schema: {
@@ -484,21 +489,47 @@ export function createTools(api) {
         },
         {
             name: "get_connection",
-            description: "Get what the site needs to read published Mapled content: the delivery key and API URL. " +
-                "Wire-up: npm install @mapled/next, put the key in the site's env as MAPLED_KEY, then " +
-                'createClient({ key: process.env.MAPLED_KEY! }).getRecords("<collection>") in server components. ' +
+            description: "Get what the site needs to read published Mapled content: the delivery key, the API URL, the package " +
+                "for the site's framework (`sdk`), the env var the key goes in (`envVar`), how the site renders " +
+                "(`rendering`: server or browser) and `wireUp` — the steps for that framework; follow them. Pass " +
+                '`framework` as you see it in the repository: "nextjs" (@mapled/next), "react-spa" for a React ' +
+                'single-page app such as Vite (@mapled/react), "plain-html" for pages without a build step ' +
+                "(@mapled/vanilla: one script tag and data-mapled-* attributes on the elements — no reading code to " +
+                "write, wireUp lists the attributes), or another short key (astro, remix, … — " +
+                "@mapled/client on the server); left out, the project's own is used. The JavaScript packages have the same reads: " +
+                'createClient({ key }).getRecords("<collection>"), getSingle, getRecordBySlug. ' +
                 "Reads take filter ({ field: value } or { field: { gte, lt, in, contains… } }), sort, limit/offset, " +
                 "fields, and expand (relation fields, e.g. [\"author\"]) — linked records arrive under record.expanded; " +
                 "getRecordBySlug(collection, slug) reads one record by its slug field. " +
-                "Image values are asset ids: assetUrl(id, { width, format }) from @mapled/next gives the URL of a resized variant. " +
-                "rich_text values are Markdown — render them with a Markdown component (e.g. react-markdown), never as raw HTML. " +
+                "Image values are asset ids: assetUrl(id, { width, format }) from the same package gives the URL of a resized variant. " +
+                "rich_text values are Markdown — render them with a Markdown component (e.g. react-markdown), never as raw HTML " +
+                "(@mapled/vanilla renders them itself: data-mapled-format=\"markdown\"). " +
                 "Content appears on the site only after a human presses Publish in Mapled.",
-            schema: {},
-            handler: async () => api.request("GET", "/v1/agent/connection"),
+            schema: {
+                framework: z
+                    .string()
+                    .regex(/^[a-z0-9][a-z0-9.-]{0,39}$/)
+                    .optional(),
+            },
+            handler: async (args) => api.request("GET", `/v1/agent/connection${args.framework ? `?framework=${encodeURIComponent(args.framework)}` : ""}`),
+        },
+        {
+            name: "set_site_url",
+            description: "Tell Mapled where the site is deployed — for a site without a publish webhook, that is one rendered in " +
+                'the browser (framework "react-spa" or "plain-html"): Preview opens the site there and verification ' +
+                "checks that it answers. Pass the public URL of the deployed site; local and private addresses are " +
+                "rejected. Mapled keeps its origin as the project's production domain, which the owner sees in Project " +
+                "settings. A site with a webhook doesn't need this: its address comes from configure_revalidation.",
+            schema: {
+                url: z.string().min(4).max(2048),
+            },
+            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. " +
+            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. " +
@@ -529,8 +560,9 @@ export function createTools(api) {
             name: "check_integration",
             description: "See the site's integration as Mapled sees it: whether the site has read content with the delivery key " +
                 "and when, the publish webhook's URL and its last delivery, the bindings summary of the last manifest, " +
-                "the connection you hold, the package versions Mapled considers current (@mapled/next, @mapled/mcp, " +
-                "the mapled CLI) and `integration` — the integration hash: `hash` is the schema and the bindings as " +
+                "`site` (the framework Mapled takes the site for, whether it renders on a server or in the browser, and " +
+                "the address Preview opens), the connection you hold, the package versions Mapled considers current " +
+                "and `integration` — the integration hash: `hash` is the schema and the bindings as " +
                 "Mapled holds them now, `synced` what the last manifest push recorded; inSync false means the site was " +
                 "wired against an older schema (schemaChanged) or bindings were edited in Mapled (bindingsChanged) — " +
                 "re-sync it (schema diff, update the site, push the manifest again). The repository computes the same " +

package/package.json

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