@mapled/mcp 0.14.1 → 0.16.0

package/README.md

@@ -46,8 +46,9 @@ 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) — 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) — and deploy.
 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.
 
 ## Destructive and breaking changes
 
@@ -62,7 +63,7 @@ A rename or a conversion Mapled wouldn't take is refused at once with the reason
 | `propose_setup_plan` / `get_setup_run` / `apply_setup_plan` / `report_setup` / `verify_setup` | One approved plan for the whole setup — every field type including relations (`$ref` handles between plan records, ids for existing collections) and groups — verified by Mapled (see above) |
 | `get_schema` | Read the project's collections and fields |
 | `create_collection` | Add a collection or single |
-| `add_field` | Add a field (short_text, long_text, rich_text, slug, image, number, boolean, date, datetime, relation, enum, url, email, group, file, color, json — an object or list up to 32 KB, location — { lat, lng }). Optional `validation` ({min, max, pattern}) and `defaultValue`; `relation` ({target, cardinality: one \| many, onDelete: restrict \| nullify}) is required for relation fields — values are record ids of the target collection, kept in the order given; `onDelete` says what a delete of a linked record does (restrict: it can't be deleted while linked, nullify: the links are cleared — the default is restrict for required fields and nullify otherwise); `options` (1–50 labels) is required for enum fields; `sensitive: true` keeps a field out of lists, history and delivery (a group's sub-fields take it too); `group` ({fields, repeatable, maxItems}) shapes a group field — its values are objects (or arrays of them) keyed by the sub-field keys. |
+| `add_field` | Add a field (short_text, long_text, rich_text, slug, image, number, boolean, date, datetime, relation, enum, url, email, group, file, color, json — an object or list up to 32 KB, location — { lat, lng }, computed). Optional `validation` ({min, max, pattern}) and `defaultValue`; `relation` ({target, cardinality: one \| many, onDelete: restrict \| nullify}) is required for relation fields — values are record ids of the target collection, kept in the order given; `onDelete` says what a delete of a linked record does (restrict: it can't be deleted while linked, nullify: the links are cleared — the default is restrict for required fields and nullify otherwise); `options` (1–50 labels) is required for enum fields; `sensitive: true` keeps a field out of lists, history and delivery (a group's sub-fields take it too); `group` ({fields, repeatable, maxItems}) shapes a group field — its values are objects (or arrays of them) keyed by the sub-field keys; `computed` ({expression}) makes a computed field — a formula Mapled evaluates whenever a record is read or published, over the record's fields and up to two links through relations (`author.company.name`, `sum(items.product.price)`) or back along one and one link on (`count(@posts.author)`, `sum(@order-items.order.product.price)`), at most one list per path, never a sensitive field or relation; the site reads the value like any field of its result type. |
 | `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 |

package/dist/tools.js

@@ -41,10 +41,10 @@ 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, \", \"); 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). " +
+    "Field keys as written (price, unit-cost — put spaces around a minus to subtract: price - cost); up to two links through relations: author.name, author.company.name, and lists over many-relations for aggregates: sum(items.price), count(tags), join(tags.name, \", \"), sum(items.product.price); 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) — and one more link on from them: sum(@order-items.order.product.price). A path goes through at most one list (a many-relation, or the records that link back), so items.tags.name is refused. " +
     "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, groups, JSON and location can't be read; there is no now(). The result type (number, text, boolean, date, datetime) follows from the formula.";
+    "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.";
 export function createTools(api) {
     return [
         {
@@ -160,17 +160,21 @@ export function createTools(api) {
             name: "apply_setup_plan",
             description: "Apply an approved setup plan. Mapled creates the collections, fields and records in one go and returns " +
                 "what was created (keys, counts) plus warnings for records it had to skip. Then wire the site " +
-                "(get_connection, configure_revalidation), write MAPLED.md (get_mapled_md) and finish with report_setup.",
+                "(get_connection, configure_revalidation), write MAPLED.md (get_mapled_md), finish with report_setup and " +
+                "refresh MAPLED.md once more.",
             schema: { runId: z.string().uuid() },
             handler: async (args) => api.request("POST", `/v1/agent/runs/${encodeURIComponent(args.runId)}/apply`, {}),
         },
         {
             name: "report_setup",
             description: "Close a setup run with your report: the files you changed, what stayed hardcoded, warnings the owner " +
-                "should know about, whether the site builds (buildPassed) and that no secrets were committed " +
-                "(secretsCommitted: false), plus the preview URL if the site is deployed. Mapled then runs its own " +
+                "should know about, whether the site builds (buildPassed), that no secrets were committed " +
+                "(secretsCommitted: false) and whether you wrote MAPLED.md from get_mapled_md before this call " +
+                "(mapledMdWritten), plus the preview URL if the site is deployed. Mapled then runs its own " +
                 "checks (site reads content, webhook delivered, preview route responds, help texts) and returns them; " +
-                "the run is completed only when every check passes — fix what failed and call verify_setup.",
+                "the run is completed only when every check passes — fix what failed and call verify_setup. The report " +
+                "and the checks change the file's «Last setup run» section, so once the run is settled call get_mapled_md " +
+                "again and rewrite MAPLED.md — a refresh keeps the check passed and the file current.",
             schema: {
                 runId: z.string().uuid(),
                 filesChanged: z.array(z.string().max(300)).max(50).optional(),
@@ -179,6 +183,7 @@ export function createTools(api) {
                 previewUrl: z.string().url().optional(),
                 buildPassed: z.boolean().optional(),
                 secretsCommitted: z.boolean().optional(),
+                mapledMdWritten: z.boolean().optional(),
             },
             handler: async (args) => {
                 const { runId, ...body } = args;
@@ -551,7 +556,7 @@ export function createTools(api) {
                 "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. 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 " +
+                "manifest change and at the end of a setup, after report_setup or verify_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: {},
             handler: async () => api.request("GET", "/v1/agent/mapled-md"),

package/package.json

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