@mapled/mcp 0.12.0 → 0.13.1

package/README.md

@@ -2,6 +2,8 @@
 
 MCP server for [Mapled](https://mapled.io) — a hosted headless CMS built for sites created with AI. Connect it to Claude, Cursor, or any MCP-capable agent, and the agent can model collections, fill in content, and wire the site up end to end.
 
+No agent at hand? Everything an agent does here can be done by a person: [Integrate by hand](https://www.npmjs.com/package/@mapled/next#integrate-by-hand) in the `@mapled/next` README is the same integration, step by step.
+
 ## Setup
 
 The quickest way is the hosted endpoint with OAuth — no token to copy. In Claude Code:
@@ -14,7 +16,6 @@ Your browser opens Mapled, you pick the project and authorize; the connection ap
 
 The local stdio server below is the alternative for clients without OAuth support.
 
-
 Create a token in Mapled: project → Integrations → **Connect with AI**. Then add the server to your agent's MCP config:
 
 ```json
@@ -48,9 +49,11 @@ For the first integration, propose one plan and let the owner approve it on a tr
 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`.
 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 changes
+## Destructive and breaking changes
+
+`delete_collection`, `remove_field` and `clear_records` never act on their own, and neither do the two breaking schema changes — `rename_field` (a field's key, what the site's code reads) and `convert_field` (its type, converting the stored values). Each one files a request and returns a `reviewUrl`: send it to the user, who confirms on a trusted Mapled screen by typing the name. Poll `get_confirmation` until the status is `applied` (the result says what changed), `denied` or `expired` (after an hour). Nothing changes until then.
 
-`delete_collection`, `remove_field` and `clear_records` never act on their own. Each one files a request and returns a `reviewUrl`: send it to the user, who confirms on a trusted Mapled screen by typing the name. Poll `get_confirmation` until the status is `applied` (the result says what changed), `denied` or `expired` (after an hour). Nothing is deleted until then.
+A rename or a conversion Mapled wouldn't take is refused at once with the reason: a key that is taken or malformed, a type the field can't become, a formula that reads the field, values that can't be converted (with their count and examples — fix the content, or ask again with `clearFailed: true`; the person confirming sees how many will be cleared). After a rename the old key keeps working as an alias until a person removes it, so move the site's code to the new key first. Both can be undone from Field settings.
 
 ## Tools
 
@@ -67,6 +70,7 @@ For the first integration, propose one plan and let the owner approve it on a tr
 | `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 |
 | `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 |
 
 Agents write drafts only — publishing stays with humans in the Mapled app, and nothing changes on the live site until someone presses Publish.

package/dist/tools.js

@@ -41,9 +41,9 @@ export const FIELD_TYPES = [
 ];
 /** What add_field and propose_setup_plan say about formulas (§14.9). */
 const COMPUTED_HELP = "For type computed only: { expression } — a formula over the record's other fields that Mapled evaluates when a record is read or published (read-only for editors and agents; the site reads the value like any field of the result type, filters and sorts included; writes ignore it). " +
-    "Field keys as written (price, unit-cost — put spaces around a minus to subtract: price - cost); one link deep through relations: author.name, and lists over many-relations for aggregates: sum(items.price), count(tags), join(tags.name, \", \"). " +
+    "Field keys as written (price, unit-cost — put spaces around a minus to subtract: price - cost); one link deep through relations: author.name, and lists over many-relations for aggregates: sum(items.price), count(tags), join(tags.name, \", \"); 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). " +
     "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). Literals: 12, 2.5, \"text\", true, false, null. " +
+    "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, groups, JSON and location can't be read; there is no now(). The result type (number, text, boolean, date, datetime) follows from the formula.";
 export function createTools(api) {
     return [
@@ -215,6 +215,52 @@ export function createTools(api) {
                 fieldKey: args.fieldKey,
             }),
         },
+        {
+            name: "rename_field",
+            description: "Breaking change, a person's decision: rename a field's key (what the site's code reads). The values follow, formulas and the " +
+                "schema are updated, and the old key keeps working as an alias — delivery serves the value under both keys, and get_schema lists " +
+                "it under `aliases` — until a person removes it in Field settings, so the site never breaks mid-change. Nothing changes until a " +
+                "person confirms it on a trusted Mapled screen by typing the field's name (returns a reviewUrl to send to the user); poll " +
+                "get_confirmation. After it is applied: update the code to read the new key, regenerate the types, push the manifest. A refusal " +
+                "(key taken, malformed key) comes back at once. It can be undone from Field settings.",
+            schema: {
+                collectionKey: z.string().min(1).max(120),
+                fieldKey: z.string().min(1).max(120).describe("The field's current key."),
+                newKey: z.string().min(1).max(50).describe("Lowercase letters, digits and hyphens, up to 50 characters."),
+            },
+            handler: async (args) => api.request("POST", "/v1/agent/confirmations", {
+                action: "rename_field",
+                collectionKey: args.collectionKey,
+                fieldKey: args.fieldKey,
+                newKey: args.newKey,
+            }),
+        },
+        {
+            name: "convert_field",
+            description: "Breaking change, a person's decision: change a field's type, converting the stored values (get_schema lists the types a field " +
+                "can become under `convertibleTo`). Mapled works the conversion out over every record first: if some values can't be converted " +
+                "the request is refused with their count and a few examples — fix the content, or ask again with clearFailed: true to clear " +
+                "those values (the person confirming sees how many). A conversion that would break a formula reading the field is refused too. " +
+                "Nothing changes until a person confirms it on a trusted Mapled screen by typing the field's name (returns a reviewUrl to send " +
+                "to the user); poll get_confirmation. It can be undone from Field settings, with the previous values.",
+            schema: {
+                collectionKey: z.string().min(1).max(120),
+                fieldKey: z.string().min(1).max(120),
+                type: z.string().min(1).max(40).describe("The type to convert to — one of the field's convertibleTo."),
+                cardinality: z.enum(["one", "many"]).optional().describe("For a relation: one ↔ many."),
+                options: z.array(z.string().min(1).max(60)).max(60).optional().describe("For enum: the choices; derived from the values when omitted."),
+                clearFailed: z.boolean().optional().describe("Clear the values that can't be converted instead of refusing."),
+            },
+            handler: async (args) => api.request("POST", "/v1/agent/confirmations", {
+                action: "convert_field",
+                collectionKey: args.collectionKey,
+                fieldKey: args.fieldKey,
+                type: args.type,
+                ...(args.cardinality !== undefined ? { cardinality: args.cardinality } : {}),
+                ...(args.options !== undefined ? { options: args.options } : {}),
+                ...(args.clearFailed !== undefined ? { clearFailed: args.clearFailed } : {}),
+            }),
+        },
         {
             name: "clear_records",
             description: "Destructive: move every record of a collection to Trash (kept 7 to 90 days by the project's plan), e.g. before re-importing content. " +
@@ -228,8 +274,8 @@ export function createTools(api) {
         },
         {
             name: "get_confirmation",
-            description: "Check a destructive-change request: status is pending (waiting for the person), applied (done — result " +
-                "says what changed), denied, expired (after an hour; request again if still needed) or failed.",
+            description: "Check a request that waits for a person (a destructive change, a rename, a conversion): status is pending (waiting for the " +
+                "person), applied (done — result says what changed), denied, expired (after an hour; request again if still needed) or failed.",
             schema: { confirmationId: z.string().uuid() },
             handler: async (args) => api.request("GET", `/v1/agent/confirmations/${encodeURIComponent(args.confirmationId)}`),
         },

package/package.json

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