@bettercms-ai/mcp 0.33.0 → 0.35.0

package/dist/index.js

@@ -11,6 +11,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { BetterCMS } from "@bettercms-ai/sdk";
 
 // src/tools.ts
+import { AsyncLocalStorage } from "async_hooks";
 import { z } from "zod";
 
 // ../types/src/component.ts
@@ -2217,19 +2218,32 @@ function authPrompt(err) {
   ].join("\n");
   return { content: [{ type: "text", text }], isError: true };
 }
+var currentProject = new AsyncLocalStorage();
+var projectIdArg = z.string().min(1).optional().describe(
+  "only needed when your grant covers the whole WORKSPACE: the project to act on (from list_projects). A project-scoped key ignores it."
+);
+var withProjectId = (def) => ({
+  ...def,
+  config: def.config.inputSchema.projectId ? def.config : { ...def.config, inputSchema: { ...def.config.inputSchema, projectId: projectIdArg } },
+  handler: (args) => {
+    const project = typeof args?.projectId === "string" && args.projectId ? args.projectId : void 0;
+    return currentProject.run(project, () => def.handler(args));
+  }
+});
 function buildToolDefs(deps) {
   async function withClient(fn) {
     const token = await deps.auth.getAccessToken();
+    const project = currentProject.getStore();
     try {
-      return await fn(deps.createClient(token));
+      return await fn(deps.createClient(token, project));
     } catch (err) {
       if (err instanceof BetterCMSError && err.status === 401) {
         const next = await deps.auth.refresh() ?? await deps.auth.getAccessToken();
-        return await fn(deps.createClient(next));
+        return await fn(deps.createClient(next, project));
       }
       if (err instanceof BetterCMSError && err.status === 409 && err.bodyCode === "PROJECT_DELETED") {
         const next = await deps.auth.resetAndReauthorize();
-        return await fn(deps.createClient(next));
+        return await fn(deps.createClient(next, project));
       }
       throw err;
     }
@@ -2882,14 +2896,14 @@ function buildToolDefs(deps) {
       def(
         "set_binding_mode",
         "Set how the site's bindings are resolved",
-        "Switch this project between the two binding resolvers, from the NEXT release on. `declaredBindings: true` makes the annotator trust the template's own data-bcms-field / data-bcms-props and never guess from rendered text \u2014 the durable state; `false` returns to text-matching, which works once (at import, when the CMS values equal the built copy) and breaks the first time anyone edits a value. Call it ONLY after every page's copy is declared in the template: undeclared fields stop being editable. The order is push \u2192 release \u2192 get_binding_report shows mode 'text-match' with 0 unmatched \u2192 set_binding_mode \u2192 release again \u2192 get_binding_report shows mode 'declared'. Flipping back is the same call. REQUIRES a project-scoped connection carrying the artifact:write scope \u2014 the same authority that deploys the site \u2014 because this decides what every future release does to every page; a workspace-wide grant is refused with 403. See section 13 of the bettercms://playbook/schema resource.",
+        "Switch this project between the two binding resolvers, from the NEXT release on. `declaredBindings: true` makes the annotator trust the template's own data-bcms-field / data-bcms-props and never guess from rendered text \u2014 the durable state; `false` returns to text-matching, which works once (at import, when the CMS values equal the built copy) and breaks the first time anyone edits a value. Call it ONLY after every page's copy is declared in the template: undeclared fields stop being editable. The order is push \u2192 release \u2192 get_binding_report shows mode 'text-match' with 0 unmatched \u2192 set_binding_mode \u2192 release again \u2192 get_binding_report shows mode 'declared'. Flipping back is the same call. REQUIRES the artifact:write scope \u2014 the same authority that deploys the site \u2014 because this decides what every future release does to every page. On a workspace-wide connection pass `projectId`: the scope is there, but the human who authorized the connection must be able to publish THAT project or it is refused with 403 PROJECT_PUBLISH_DENIED. See section 13 of the bettercms://playbook/schema resource.",
         z.object({ declaredBindings: z.boolean().describe("true = trust the template's declared bindings; false = text-match (the default)") }).shape,
         async (c, a) => ok("Recorded the binding mode.", await data(c, "PATCH", `/management/projects/current/binding-mode`, { declaredBindings: a.declaredBindings }))
       ),
       def(
         "submit_conversion_receipt",
         "Record what the conversion codemod could and could not do",
-        "Hand BetterCMS the codemod's own account of a conversion run, so the coverage meter can say WHY a path is not declared instead of only that it is not. Submit the receipt `npx @bettercms-ai/convert` wrote (`--receipt out.json`) for the SAME `briefDigest` get_conversion_brief { complete: true } returned: `{ briefDigest, receipt }`, where the receipt carries `paths: { declared, rewritten, alreadyDeclared, pending[{ route, scope, path, kind, file, reason, message }] }`. `paths.declared` must equal rewritten + alreadyDeclared + pending.length, and each pending `reason` is one of the converter's own (IN_EXPRESSION, AMBIGUOUS_LITERAL, REPEATER_FIXED_LENGTH, PARSE_ERROR, \u2026) \u2014 a path with no receipt row simply reads `not-declared`. It is a RECORD, not a release: it changes nothing about the site, and the meter picks it up on the next get_binding_report after the next deploy. A 404 `unknown-brief` means that digest was never issued here, so convert against a brief this project actually returned. Requires a project-scoped connection carrying artifact:write, the same authority as set_binding_mode.",
+        "Hand BetterCMS the codemod's own account of a conversion run, so the coverage meter can say WHY a path is not declared instead of only that it is not. Submit the receipt `npx @bettercms-ai/convert` wrote (`--receipt out.json`) for the SAME `briefDigest` get_conversion_brief { complete: true } returned: `{ briefDigest, receipt }`, where the receipt carries `paths: { declared, rewritten, alreadyDeclared, pending[{ route, scope, path, kind, file, reason, message }] }`. `paths.declared` must equal rewritten + alreadyDeclared + pending.length, and each pending `reason` is one of the converter's own (IN_EXPRESSION, AMBIGUOUS_LITERAL, REPEATER_FIXED_LENGTH, PARSE_ERROR, \u2026) \u2014 a path with no receipt row simply reads `not-declared`. It is a RECORD, not a release: it changes nothing about the site, and the meter picks it up on the next get_binding_report after the next deploy. A 404 `unknown-brief` means that digest was never issued here, so convert against a brief this project actually returned. Requires artifact:write, the same authority as set_binding_mode; on a workspace-wide connection pass `projectId`.",
         z.object({
           briefDigest: z.string().min(1).describe("The `briefDigest` get_conversion_brief { complete: true } returned. Must match the receipt's own."),
           receipt: z.record(z.string(), z.unknown()).describe("The receipt `npx @bettercms-ai/convert --receipt out.json` wrote, verbatim.")
@@ -2955,17 +2969,19 @@ function buildToolDefs(deps) {
         async (c, a) => ok("Updated page.", await data(c, "PATCH", `/management/pages/${s(a.pageId)}/meta`, { title: a.title, slug: a.slug, blockJson: a.blockJson, metaTitle: a.metaTitle, metaDescription: a.metaDescription, status: a.status }))
       ),
       // ── Code + deploy (parity with remote /mcp; needs artifact:write) ──
+      // Both grant shapes carry that scope now; a workspace-wide one names its target per
+      // call via `projectId` and is re-checked against it. @see management/projects.ts
       def(
         "pull_project_source",
         "Pull the project's live source",
-        "Get the connected project's CURRENT live source/build so you can edit it locally. Returns a presigned tarball download url (1h) + the live commit sha \u2014 download it, extract, edit the files, then call deploy_project. If the project is connected to a GitHub repo, returns `github: {owner, repo}` so you can `git clone` that instead.",
+        "Get the connected project's CURRENT live source/build so you can edit it locally. Returns a presigned tarball download url (1h) + the live commit sha \u2014 download it, extract, edit the files, then call deploy_project. If the project is connected to a GitHub repo, `github` carries owner, repo, branch and cloneUrl \u2014 clone it and work on THAT branch, because it is the one the provisioned Action builds from; a commit on any other branch never reaches the live site. On a workspace-wide connection pass `projectId` (from list_projects) to say which site's source to pull.",
         z.object({}).shape,
         async (c) => ok("Project source.", await data(c, "GET", `/management/projects/source`))
       ),
       def(
         "deploy_project",
         "Deploy new source/build",
-        "Deploy new source/build for the connected project and make it live at its <handle>.bettercms.site. Pass a .tgz or .zip of the project as a base64 string in `data`: SOURCE (has package.json) is built server-side in an isolated sandbox; a prebuilt static site is served as-is. Returns the release id + sha \u2014 then poll get_deploy_status until it is live. IMPORTANT \u2014 you MUST exclude node_modules, .git, and build output/caches (dist, build, .next, .astro, .cache) BEFORE creating the archive: a source deploy is reinstalled and built server-side, so those are never needed, and the upload has a hard size ceiling (~100 MB) enforced before the request reaches the server \u2014 an archive that includes node_modules is rejected in transit (a 413/502 with no server-side detail). Keep the archive to your own source files. Server-side stripping exists as a safety net, but it runs AFTER the upload and cannot rescue an over-limit body. For a LARGE archive (or if this returns a 413/502), use create_deploy_upload + deploy_from_upload instead \u2014 that path uploads straight to storage with no size ceiling. Returns `canvas.lane` \u2014 which live-preview lane the last release gave the editor (`bridge` / `draft-route` / `none`; see the playbook's section 11) \u2014 and `editorUrl`, the visual editor to hand the user.",
+        "Deploy new source/build for the connected project and make it live at its <handle>.bettercms.site. Pass a .tgz or .zip of the project as a base64 string in `data`: SOURCE (has package.json) is built server-side in an isolated sandbox; a prebuilt static site is served as-is. Returns the release id + sha \u2014 then poll get_deploy_status until it is live. IMPORTANT \u2014 you MUST exclude node_modules, .git, and build output/caches (dist, build, .next, .astro, .cache) BEFORE creating the archive: a source deploy is reinstalled and built server-side, so those are never needed, and the upload has a hard size ceiling (~100 MB) enforced before the request reaches the server \u2014 an archive that includes node_modules is rejected in transit (a 413/502 with no server-side detail). Keep the archive to your own source files. Server-side stripping exists as a safety net, but it runs AFTER the upload and cannot rescue an over-limit body. For a LARGE archive (or if this returns a 413/502), use create_deploy_upload + deploy_from_upload instead \u2014 that path uploads straight to storage with no size ceiling. Returns `canvas.lane` \u2014 which live-preview lane the last release gave the editor (`bridge` / `draft-route` / `none`; see the playbook's section 11) \u2014 and `editorUrl`, the visual editor to hand the user. On a workspace-wide connection pass `projectId` (from list_projects) to say which site this ships to.",
         z.object({ data: z.string().min(1).describe("base64 .tgz/.zip of the project"), mimeType: z.string().optional() }).shape,
         async (c, a) => ok("Deploy queued.", await raw(c, `/management/projects/deploy`, s(a.data), a.mimeType))
       ),
@@ -3025,7 +3041,7 @@ function buildToolDefs(deps) {
       def(
         "get_conversion_plan",
         "Get the approved conversion to apply",
-        "The APPROVED conversion a human reviewed in the BetterCMS dashboard: the exact new contents of each template file, already checked against this project's real field paths. Apply it instead of writing the bindings by hand. Check out `baseHeadOid` (the exact commit it was written against \u2014 a plan applied to a different base is a different change), branch from there, write each file's `content` verbatim (whole file, no merge, no reformatting), then push or deploy however this project ships. `stale.head` / `stale.brief` say the repository or the CMS moved since it was approved: stop and ask for a fresh proposal rather than applying it anyway. `receipt.paths.pending` lists every field the codemod could NOT bind, each with a reason (`DIALECT_UNSUPPORTED`, `PROP_TARGET_NOT_FOUND`, `REPEATER_FIXED_LENGTH`, \u2026) \u2014 apply the plan first, then bind those by hand. Finish the loop the same way as a hand conversion \u2014 get_binding_report until `unmatched` is empty, then set_binding_mode { declaredBindings: true } and release once more. 404 with `code: \"no-approved-plan\"` means nobody has approved one: use get_conversion_brief and do the conversion yourself. Requires a project-scoped connection carrying artifact:write.",
+        "The APPROVED conversion a human reviewed in the BetterCMS dashboard: the exact new contents of each template file, already checked against this project's real field paths. Apply it instead of writing the bindings by hand. Check out `baseHeadOid` (the exact commit it was written against \u2014 a plan applied to a different base is a different change), branch from there, write each file's `content` verbatim (whole file, no merge, no reformatting), then push or deploy however this project ships. `stale.head` / `stale.brief` say the repository or the CMS moved since it was approved: stop and ask for a fresh proposal rather than applying it anyway. `receipt.paths.pending` lists every field the codemod could NOT bind, each with a reason (`DIALECT_UNSUPPORTED`, `PROP_TARGET_NOT_FOUND`, `REPEATER_FIXED_LENGTH`, \u2026) \u2014 apply the plan first, then bind those by hand. Finish the loop the same way as a hand conversion \u2014 get_binding_report until `unmatched` is empty, then set_binding_mode { declaredBindings: true } and release once more. 404 with `code: \"no-approved-plan\"` means nobody has approved one: use get_conversion_brief and do the conversion yourself. Requires artifact:write; on a workspace-wide connection pass `projectId`.",
         z.object({}).shape,
         async (c) => ok("Approved conversion plan.", await data(c, "GET", `/management/projects/current/conversion-plan`))
       ),
@@ -3757,7 +3773,7 @@ ${lines.join("\n")}`, found);
     // through the client's request plumbing — no bespoke SDK method per endpoint.
     ...lifecycleTools()
   ];
-  return defs;
+  return defs.map(withProjectId);
 }
 function registerTools(server, deps) {
   const withElicit = {
@@ -3949,11 +3965,18 @@ in preview and is blank in production. Always pass the project's id.
 accepts it and ignores it**, silently. No error, no warning, wrong project.
 
 So call \`get_project\` (no arguments) first \u2014 it reports the project you are actually
-writing to. If that is not where the work belongs \u2014 or it answers that the grant covers the
-whole workspace \u2014 stop and tell the user the one-step fix: in the BetterCMS dashboard open
-**Settings \u2192 Connected AI clients** and use **Scope to project** on this connection. No tool
-can switch it, but the user does NOT need to re-authorize or re-add the server: the next call
-after that runs with the new scope. Then retry.
+writing to.
+
+**If the grant covers the WHOLE WORKSPACE, that is not a blocker and there is nothing to
+stop for.** Pass \`projectId\` on every project tool \u2014 \`list_projects\` gives you the id, and
+\`get_project { projectId }\` confirms you are addressing the right site. Every tool takes it,
+including the code and deploy ones. Do NOT send the user to re-scope the connection; the only
+thing that genuinely blocks you is a grant on a different WORKSPACE, which is what an empty or
+foreign \`list_projects\` tells you.
+
+If the connected project is simply the WRONG one for the work \u2014 a project-scoped grant pointed
+elsewhere \u2014 that is the case the user has to fix, in the BetterCMS dashboard under
+**Settings \u2192 Connected AI clients**. No tool can switch it.
 
 If you must probe, probe with a \`create_content_model\` \u2014 models are deletable
 (\`delete_content_model\`, soft-delete) and **there is no \`delete_component\`**. A component
@@ -4135,6 +4158,17 @@ the canvas but skips release annotation and publish-time injection, because ther
 disk to annotate. Copy rendered on the client must carry the attributes in the HYDRATED DOM,
 and only the canvas sees it \u2014 a release scan cannot.
 
+**On a workspace-wide connection, pass \`projectId\` on every call in this section** \u2014 that is
+all it takes; the code and deploy tools work from such a connection and nobody needs to re-scope
+anything. See \xA79.
+
+**Which recipe.** There are TWO below and they are not alternatives you pick by taste \u2014 call
+\`get_binding_report\` and \`get_conversion_brief\` first and let the answer choose. A brief that
+comes back WITH PAGES means this project was imported and deployed, so its schema and values were
+derived for you already \u2192 **Recipe A**. A 404 or an empty brief means the site is not in the CMS
+yet \u2192 **Recipe B**. \`get_next_steps\` works on every plan and names the next unfinished step
+either way.
+
 **If you know Sanity, this is the same shape under different names:**
 
     defineType schema in code   ->  content models / page fields (create_content_model,
@@ -4152,11 +4186,12 @@ and only the canvas sees it \u2014 a release scan cannot.
 its build, the schema and the values already exist \u2014 a page per route, a field per element, and
 the original copy carried on each field as its \`defaultValue\`. Call \`get_conversion_brief\`
 first: it lists those pages, their routes, every bindable path with its current and original
-value, and the attributes to declare. SKIP steps 3 and 4 below and bind the keys it names \u2014
-registering the schema again builds a second one over the first.
+value, and the attributes to declare. SKIP Recipe B's steps 3 and 4 below and bind the keys it
+names \u2014 registering the schema again builds a second one over the first.
 
-**Run the CODEMOD rather than editing by hand.** For a derived site the whole of step 5 is
-mechanical, and there is a tool that does it. THE ORDER, and every step of it matters:
+**Recipe A \u2014 imported and deployed: the codemod order.** For a derived site the whole of Recipe
+B's step 5 is mechanical, and there is a tool that does it. Run the codemod rather than editing by
+hand. THE ORDER, and every step of it matters:
 
 1. \`get_conversion_brief { complete: true }\` \u2014 the COMPLETE brief, not the capped one. It comes
    back uncapped and paged (50 pages at a time): follow \`cursor\` until it stops coming back and
@@ -4176,7 +4211,11 @@ mechanical, and there is a tool that does it. THE ORDER, and every step of it ma
    what lets the coverage meter say WHY a path is undeclared instead of only that it is; without
    it every one of them reads \`not-declared\`, which looks like a broken site rather than work
    with a reason. It records and releases nothing.
-5. Push, or \`deploy_project\`, and wait for the release to be live (step 6 below).
+5. Push, or \`deploy_project\`. A PLAIN HTML repo \u2014 no \`package.json\` \u2014 deploys by PUSH ONLY:
+   \`deploy_project\` refuses such an archive by design, so pushing is the whole lane. Either way,
+   poll \`get_deploy_status\` until \`slot\` is \`current\` (or \`awaitingPromote\` is false) before you
+   read the report in step 6 \u2014 a report read against the previous release is the previous
+   release's verdict.
 6. \`get_binding_report\`. Alongside \`unmatched\` it now carries \`coverage\` \u2014 \`declared\` (what the
    brief listed), \`bound\` (what the build declares) and \`pending\` with the reasons. Fix what it
    names and release again until \`coverage.pending\` is empty.
@@ -4185,14 +4224,15 @@ mechanical, and there is a tool that does it. THE ORDER, and every step of it ma
 
 **Or let BetterCMS propose the edit.** \`get_conversion_plan\` returns an APPROVED conversion \u2014 the
 exact new contents of each template file, reviewed by a human in the dashboard and already checked
-against this project's real field paths. When there is one, apply it instead of doing step 5 by
-hand: check out its \`baseHeadOid\`, branch from there, write each file's \`content\` verbatim, and
-carry on from step 6. A 404 with \`code: "no-approved-plan"\` means nobody approved one, so the
+against this project's real field paths. When there is one, apply it instead of Recipe A's step 2
+(the codemod): check out its \`baseHeadOid\`, branch from there, write each file's \`content\`
+verbatim, and carry on from Recipe A's step 5. A 404 with \`code: "no-approved-plan"\` means nobody approved one, so the
 conversion is yours to write.
 
-**The steps.**
+**Recipe B \u2014 not in the CMS yet: the steps.**
 
-1. \`pull_project_source\` (or clone the \`github\` remote it returns). Read the SOURCE. Never
+1. \`pull_project_source\` (or clone the \`github\` remote it returns \u2014 \`cloneUrl\` on the \`branch\`
+   it names, which is the branch the provisioned Action builds). Read the SOURCE. Never
    reconstruct content from the deployed HTML \u2014 that is how a site ends up bound to a copy of
    its own stale build.
 2. Decide the architecture WITH the human (\xA710) and record it: \`set_authoring_preference\`.
@@ -4266,7 +4306,9 @@ conversion is yours to write.
       then switch the project to "Run as a server app" on the Hosting page. Never migrate a
       static site to SSR without asking the human first.
     Then \`get_binding_report.canvas.lane\` reads \`bridge\` or \`draft-route\` instead of \`none\`.
-6. Push, or \`deploy_project\`; poll \`get_deploy_status\` until it is live. Then
+6. Push, or \`deploy_project\`. A PLAIN HTML repo \u2014 no \`package.json\` \u2014 deploys by PUSH ONLY:
+   \`deploy_project\` refuses such an archive by design. Poll \`get_deploy_status\` until \`slot\` is
+   \`current\` (or \`awaitingPromote\` is false). Then
    \`get_binding_report\` \u2014 still \`text-match\`, and \`unmatched\` should be EMPTY because the
    values are byte-equal to what the build renders. On a converted site read \`coverage\` too: it
    counts the PINNED brief's paths, which \`unmatched\` cannot, because \`unmatched\` only ever
@@ -4279,6 +4321,10 @@ conversion is yours to write.
    text against its entry values yourself before you call the page done. Then publish, and
    fetch the live URL cache-busted (\xA712: publish and deploy are separate claims).
    \`get_next_steps\` keeps reporting the gap until every one of these holds.
+
+**Done means.** Whichever recipe you ran: \`get_binding_report\` reads \`mode "declared"\`,
+\`unmatched\` empty, \`bound\` above 0, \`coverage.pending\` empty, and \`canvas.lane\` is \`bridge\` or
+\`draft-route\` when the site should show structural drafts.
 `;
 
 // src/prompts.ts
@@ -4735,7 +4781,10 @@ function buildServer(deps) {
     { name: SERVER_NAME, version: SERVER_VERSION, ...SERVER_DISPLAY },
     {
       capabilities: { tools: {}, prompts: {}, resources: {} },
-      instructions: "BetterCMS never executes a customer's Section renderer or app code. An ordinary MCP connection is not a push runner: explicitly poll list_section_validation_requests, claim one request at an exact git commit, run implementation and responsive checks inside the user's own repository and real app shell, then submit manifest + validation with that requestId and complete it\u2014or truthfully fail it when implementation/evidence is missing. Never invent a manifest, a passing validation, or visual evidence; these tools cannot grant the separate human Visual Approval required for publication."
+      // 🔴 The plain-language ask, routed — the stdio twin of the hosted connector's line
+      // (src/routes/mcp/index.ts MCP_INSTRUCTIONS). "Make my site editable" has one recipe and
+      // one definition of done; without this an agent converts the page it landed on and stops.
+      instructions: "When the user asks to make a site or all of its pages editable, to convert it, or to componentize the whole site: this is playbook \xA713. Read `bettercms://playbook/schema` \xA713, call get_binding_report and get_conversion_brief { complete: true }, convert EVERY route the brief lists, and finish only when get_binding_report shows coverage.pending empty on every route \u2014 not when the first page works. On a workspace-wide connection pass projectId on every call; never ask the user to re-scope the connection. BetterCMS never executes a customer's Section renderer or app code. An ordinary MCP connection is not a push runner: explicitly poll list_section_validation_requests, claim one request at an exact git commit, run implementation and responsive checks inside the user's own repository and real app shell, then submit manifest + validation with that requestId and complete it\u2014or truthfully fail it when implementation/evidence is missing. Never invent a manifest, a passing validation, or visual evidence; these tools cannot grant the separate human Visual Approval required for publication."
     }
   );
   server.registerResource(
@@ -4752,7 +4801,10 @@ function buildServer(deps) {
   );
   registerTools(server, {
     auth: deps.auth,
-    createClient: (apiKey) => BetterCMS.management({ apiKey, baseUrl: deps.managementBaseUrl })
+    // `project` is the per-call target of a workspace-wide grant; the SDK sends it as
+    // X-BCMS-Project. Omitted entirely when absent so a project-scoped key's request is
+    // byte-identical to before.
+    createClient: (apiKey, project) => BetterCMS.management({ apiKey, baseUrl: deps.managementBaseUrl, ...project ? { project } : {} })
   });
   registerPrompts(server);
   return server;