@mapled/mcp 0.10.0 → 0.12.0

package/README.md

@@ -64,9 +64,9 @@ For the first integration, propose one plan and let the owner approve it on a tr
 | `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`) |
-| `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 |
+| `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, current package versions; `npx @mapled/cli doctor` shows the same from inside the repository |
+| `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 |
 | `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.d.ts

@@ -5,7 +5,7 @@ export type ApiClient = {
     request: (method: "GET" | "POST" | "PATCH", path: string, body?: unknown) => Promise<unknown>;
 };
 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"];
+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 = {
     name: string;
     description: string;

package/dist/tools.js

@@ -37,12 +37,19 @@ export const FIELD_TYPES = [
     "color",
     "json",
     "location",
+    "computed",
 ];
+/** 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, \", \"). " +
+    "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. " +
+    "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 [
         {
             name: "get_schema",
-            description: "Read the project's full content schema: collections with their fields.",
+            description: "Read the project's full content schema: collections with their fields (a computed field carries its formula and result type under `computed`).",
             schema: {},
             handler: async () => api.request("GET", "/v1/agent/schema"),
         },
@@ -82,6 +89,10 @@ export function createTools(api) {
                             .max(50)
                             .optional()
                             .describe("For type enum only: the values a record may hold, in display order."),
+                        computed: z
+                            .object({ expression: z.string().min(1).max(500) })
+                            .optional()
+                            .describe(`${COMPUTED_HELP} In a plan the formula may read fields of this plan (this collection, or another one through a relation); one that doesn't check is skipped with a warning when the plan is applied.`),
                         relation: z
                             .object({
                             target: z
@@ -206,7 +217,7 @@ export function createTools(api) {
         },
         {
             name: "clear_records",
-            description: "Destructive: move every record of a collection to Trash (kept 7 days), e.g. before re-importing content. " +
+            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. " +
                 "Needs a person's confirmation on a trusted Mapled screen (returns a reviewUrl to send to the user); poll " +
                 "get_confirmation.",
             schema: { collectionKey: z.string().min(1).max(120) },
@@ -229,7 +240,9 @@ 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. Needs the builder plan.",
+                "collections or fields. 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: {
                 framework: z.string().max(40).optional(),
                 pages: z.array(z.object({ route: z.string().max(200), file: z.string().max(300).optional() })).max(200).optional(),
@@ -266,7 +279,11 @@ export function createTools(api) {
             name: "list_bindings",
             description: "Read the bindings with their health: healthy, missing_on_site, type_mismatch, outdated (the field or " +
                 "collection changed since the manifest), not_checked, disabled. Fix the site or the schema, then push " +
-                "the manifest again.",
+                "the manifest again. `integration` says whether the last push still matches Mapled: inSync false with " +
+                "schemaChanged means the schema moved after the site was wired — run `npx @mapled/cli schema diff`, " +
+                "update the site, then `scan --write` and push the manifest again; bindingsChanged means someone " +
+                "replaced or deleted bindings in Mapled — `npx @mapled/cli bindings pull` brings them into the " +
+                "repository, then update the site to match.",
             schema: {},
             handler: async () => api.request("GET", "/v1/agent/bindings"),
         },
@@ -290,7 +307,7 @@ export function createTools(api) {
         },
         {
             name: "add_field",
-            description: "Add a field to a collection. Types: short_text, long_text, rich_text (Markdown: headings, lists, links, bold/italic, images as ![alt](file URL)), slug, image, number, boolean, date, relation (a link to records of another collection: pass `relation`; values are record ids), enum (a choice: pass `options`), url, email, group (an object shaped by its own `group.fields`, or a list of them when repeatable — feature cards, FAQ items; values are objects / arrays of objects keyed by the sub-field keys), datetime (ISO 8601, stored in UTC), file (an asset id of any uploaded file), color (#rrggbb), json (any object or list up to 32 KB — settings, specs, structured data the site reads as is), location ({ lat, lng } in degrees).",
+            description: "Add a field to a collection. Types: short_text, long_text, rich_text (Markdown: headings, lists, links, bold/italic, images as ![alt](file URL)), slug, image, number, boolean, date, relation (a link to records of another collection: pass `relation`; values are record ids), enum (a choice: pass `options`), url, email, group (an object shaped by its own `group.fields`, or a list of them when repeatable — feature cards, FAQ items; values are objects / arrays of objects keyed by the sub-field keys), datetime (ISO 8601, stored in UTC), file (an asset id of any uploaded file), color (#rrggbb), json (any object or list up to 32 KB — settings, specs, structured data the site reads as is), location ({ lat, lng } in degrees), computed (a value derived from the record's other fields: pass `computed.expression`; never required or sensitive).",
             schema: {
                 collectionKey: z.string().min(1).max(120),
                 displayName: z.string().min(1).max(120),
@@ -354,6 +371,7 @@ export function createTools(api) {
                 })
                     .optional()
                     .describe("For type group only. Sub-field keys are the lowercase, hyphenated names."),
+                computed: z.object({ expression: z.string().min(1).max(500) }).optional().describe(COMPUTED_HELP),
             },
             handler: async (args) => api.request("POST", `/v1/agent/collections/${encodeURIComponent(args.collectionKey)}/fields`, {
                 displayName: args.displayName,
@@ -366,6 +384,7 @@ export function createTools(api) {
                 ...(args.options ? { options: args.options } : {}),
                 ...(args.sensitive !== undefined ? { sensitive: args.sensitive } : {}),
                 ...(args.group ? { group: args.group } : {}),
+                ...(args.computed ? { computed: args.computed } : {}),
             }),
         },
         {
@@ -449,7 +468,8 @@ export function createTools(api) {
                 "reads it, the content model, where the site renders each field, the last setup run, the working rules and " +
                 "the verification commands, rendered from the project as it is now. Write `markdown` to MAPLED.md at the " +
                 "repository root and commit it. If the file exists, replace everything above its `<!-- mapled:notes -->` " +
-                "line and keep what is below — that part belongs to the repository. Refresh it after every schema or " +
+                "line and keep what is below — that part belongs to the repository. Its first line is a stamp with the " +
+                "schema hash, the manifest version and the integration hash. Refresh it after every schema or " +
                 "manifest change and at the end of a setup; `npx @mapled/cli md pull` does the same from the repository " +
                 "and `mapled doctor` says when it is out of date. It never contains a secret — don't add one.",
             schema: {},
@@ -459,9 +479,14 @@ 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 and the package versions Mapled considers current (@mapled/next, @mapled/mcp, " +
-                "the mapled CLI). Use it to find what is left to wire up; `npx @mapled/cli doctor` shows the same picture " +
-                "from inside the repository, plus the local checks (env, routes, generated types, secrets in git).",
+                "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 " +
+                "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 " +
+                "hash from mapled/schema.json and mapled/manifest.json, and `npx @mapled/cli doctor` compares the two in " +
+                "its Integration line. Use it to find what is left to wire up; doctor shows the same picture from inside " +
+                "the repository, plus the local checks (env, routes, generated types, secrets in git).",
             schema: {},
             handler: async () => api.request("GET", "/v1/agent/integration"),
         },

package/package.json

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