@bettercms-ai/mcp 0.79.1 → 0.81.0

package/dist/index.js

@@ -2907,6 +2907,19 @@ var LISTING_TAIL = /* @__PURE__ */ new Set([
   "generate_image",
   "transform_image",
   "write_alt_text",
+  // Custom integrations: reached for once a site exists and its owner names a vendor.
+  "list_integrations",
+  "get_integration",
+  "create_integration",
+  "update_integration",
+  "delete_integration",
+  "test_integration_fetch",
+  "run_integration_sync",
+  "run_integration_function",
+  "search_integration_reference",
+  "start_integration_signin",
+  "save_integration_template",
+  "install_integration_template",
   // The ABM campaign lane — also hidden from the default listing (ABM_TOOLS below).
   "research_account",
   "build_abm_page",
@@ -2990,7 +3003,19 @@ var NEW_TOOL_TEXT = {
   import_redirects: "Bulk-create redirects for a migration, from `rows` or from `text` in `format` (our CSV export, a Netlify `_redirects` file, or a vercel.json). Call it with `dryRun: true` FIRST: nothing is written and each row comes back `would-create`, `existing` or `skipped` with a reason. Rows get create_redirect's rules. Max 5000.",
   editor_setup: "Make the live build editable: derives pages, collections, forms, bindings and components from the live release (skill bindings). Run it after an import or a rebuild, before the conversion brief. Idempotent: `ready` when it already ran for the live sha, else it starts (`running`; poll with `check: true`). `state`: never or stale (run it), running, ready, failed. 409 = nothing is live yet: deploy first. Then get_next_steps.",
   transform_image: "Edit an existing Media Library image with an instruction (e.g. 'remove the background', 'make it dusk'); the result is saved as a NEW asset and the original is kept (5 AI credits). Returns the new asset (id, url, altText).",
-  write_alt_text: "Alt text for a Media Library image (mediaId) or an https image URL (url), written from its pixels (1 AI credit). A suggestion: save it with update_media."
+  write_alt_text: "Alt text for a Media Library image (mediaId) or an https image URL (url), written from its pixels (1 AI credit). A suggestion: save it with update_media.",
+  list_integrations: "List the project's custom integrations (any vendor with a public API) and the workspace's integration `templates`. Each has its hosts, secret NAMES with `secretsPresent` (never a value), syncs, hooks, endpoints, functions and `approved`. Read bettercms://skill/integrations first.",
+  get_integration: "One integration (`integration`: id or slug): `hookUrls`, `endpointUrls`, `oauthStatus`, its last sync runs, write-backs (`pushes`), function runs, webhook deliveries and vendor calls (the call log).",
+  create_integration: "Declare a custom integration. Shapes: bettercms://skill/integrations. Secret VALUES never pass through here (the user sets env vars; list_env_vars shows names). Until an admin approves it, every vendor call, sync, webhook, endpoint and function is refused: give the user `approval.approveUrl` and `approval.changes` in plain words. You cannot approve it.",
+  update_integration: "Change an integration (`integration`: id or slug); parameters as create_integration, keys left out are kept, lists replace the stored ones whole. A change to hosts, secrets, inject, allowPost, auth, oauth, hooks, endpoints, references or functions withdraws its approval (`approval.approveUrl`); name, syncs, settings and panel never need it.",
+  delete_integration: "Delete an integration and its sync runs. Entries it synced stay (their provenance still names it); the env vars stay.",
+  run_integration_sync: "Run one of an integration's syncs now (`integration`, `sync`: its key): every page of the vendor list is fetched and each item is created or updated as a DRAFT entry, matched on its externalKey, so a re-run only changes what changed (`unchanged` counts the rest); `publish: true` on the sync publishes what changed. Answers with the run: queued, running, done (counts: created, updated, unchanged, failed, pages, items) or failed (error). `waitSeconds` (\u2264 20) waits for it to finish; else follow it with get_integration. A sync with `schedule` 'hourly' or 'daily' also runs on its own.",
+  run_integration_function: "Run an integration's function (bettercms/functions/<name>.ts, trigger 'manual') with `input`. Its fetch() reaches only the integration's approved hosts and the server adds the secrets: the code never sees them. `waitSeconds` (\u2264 20) answers with output, logs or error.",
+  search_integration_reference: "Search an integration's live reference (`reference`: its key) at the vendor: up to 20 {id, title, image}. Store the pick in a json field (skill \xA712); the site resolves it live.",
+  start_integration_signin: "Start the vendor sign-in of an integration with `oauth`: a `url` the USER opens to sign in with their own OAuth app (register `redirectUri` in it first). Tokens stay on the server.",
+  save_integration_template: "Save an integration as a workspace template: its shape, never a secret value or its settings, with copies of the collections its syncs write into.",
+  install_integration_template: "Install a workspace template on this project: missing collections are created and the integration waits for approval (`approval.approveUrl`); `secretsNeeded` lists the env vars to set.",
+  test_integration_fetch: "Call the vendor once through the server, as the integration: an approved host only, with the integration's `inject` secrets added server-side and every secret redacted from the answer. The request itself takes no {{...}} templates, and the token endpoint cannot be called. Use it to read the response shape before writing a sync: `items`, `externalKey` and `map` are JSON Pointers into it. Bodies over 1 MB come back truncated. 409 integration_not_approved: an admin must approve it first."
 };
 var DELETE_PAGE_RUNTIME_BUNDLE = " Or, with no pageId, `runtimeBundle`: 'report' lists the duplicate pages derived from a server app's own bundle (`app/` folders); 'apply' retires them and their empty folders.";
 var FIELD_LOCKED_NOTE = "A readOnly 'developer' field keeps its stored value: changing or omitting it without schema access is 403 FIELD_LOCKED.";
@@ -3041,6 +3066,31 @@ var PARAM_TEXT = {
   mergeHref: "pageId only: the link field paired with `path` (the label). Both become ONE `button` field keyed `key` (default: their stem, primaryCtaHref \u2192 primaryCta). Each entry's DRAFT gets {label, href} and keeps the old values; the live copy changes on publish. ifMatch is the page's version. 409 CODE_RENDERED_ROUTE: do its `next` recipe in code",
   confirmedInput: "true only after the user explicitly approved adding this custom input (`ui.input`); else setting or changing one is refused input_needs_confirmation. Removing one needs no approval"
 };
+var INTEGRATION_PARAM_TEXT = {
+  integration: "the integration's id or slug (from list_integrations)",
+  slug: "lowercase letters, digits, hyphens; at most 48",
+  allowedHosts: "exact hostnames the server may call, e.g. ['boards-api.greenhouse.io']; https only",
+  secrets: "template name (UPPER_SNAKE) -> project env var KEY, e.g. {TOKEN: 'SHOPIFY_ADMIN_TOKEN'}; never a value",
+  inject: "where the secrets go on every vendor request: {headers?: {name: template}, query?: {name: template}}, templates {{secret.NAME}} or {{token}}",
+  allowPost: "true lets requests other than GET through (vendor writes, POST search APIs such as Apollo's); GET only when omitted",
+  auth: "optional token exchange (skill \xA75); its result is {{token}}",
+  settings: "non-secret JSON the panel reads and writes (store id, toggles); at most 16 KB",
+  syncs: "vendor list -> collection [{key, contentModelId, request, items, externalKey, map, item?, writeBack?, publish?, schedule?}] (skill \xA76; two-way \xA715)",
+  hooks: "vendor webhooks [{key, verify, action}] (skill \xA79); the vendor posts to `hookUrls`",
+  endpoints: "public reads for the site [{key, request, params, pick, cacheSeconds?}] (skill \xA711); at `endpointUrls`",
+  references: "live references [{key, label, search, lookup, items, id, title}] (skill \xA712)",
+  functions: "[{name, triggers?, cpuMs?}]: bettercms/functions/<name>.ts (skill \xA710)",
+  oauth: "sign-in with the customer's own OAuth app {authorizeUrl, tokenUrl, scopes, clientId, clientSecret} (secret NAMES; skill \xA713)",
+  alertAfter: "tell admins after this many failed runs in a row (0 = never; 3 when omitted)",
+  reference: "the reference's key (from the integration's references)",
+  template: "the template's slug (from list_integrations `templates`)",
+  panel: "the custom panel's slug: bettercms/panels/<panel>.tsx in the site repo; null for the stock page",
+  url: "the full https URL on an allowed host (no templates in the URL)",
+  sync: "the sync's key (from the integration's syncs)",
+  headers: "header -> value (no templates: the integration's inject adds the secrets)",
+  query: "query parameter -> value (no templates)",
+  json: "a JSON body for POST"
+};
 var INPUT_CONFIRMED_HEADER = "x-bcms-confirmed-input";
 var BUTTON_FIELD_NOTE = "'button' is ONE call to action, value {label, href, variant? (a Button family look), size?, arrow?, icon?, newTab?, rel?, fullWidth?} (arrow:false, icon:null off): never a text field beside a link field.";
 var LINK_VALUE_NOTE = "A link or button href: a URL string or {type: url|page|entry|email|phone|anchor|file, href, title?, newTab?, rel?, section?, ref: page/entry id}.";
@@ -3327,6 +3377,7 @@ var uiObject = z.strictObject({
   placeholder: z.string().min(1).max(120).optional().describe("ghost text, a field of any type. A prop uses its own `placeholder`."),
   synced: z.strictObject({ from: z.string().min(1).max(64) }).optional().describe("the value comes from this global; edits apply everywhere."),
   valueShape: z.enum(["string", "object"]).optional().describe("a link / image / button writes a plain string or the object."),
+  reference: z.object({ integration: z.string(), key: z.string() }).strict().optional().describe("a json field holding a live vendor item: the integration's slug and reference key."),
   access: z.strictObject({ view: z.literal("schema.view").optional(), edit: z.literal("schema.manage").optional() }).optional().describe("who sees (view: developer-only) and who changes (edit) it, gated in the editor. The enforced lock is readOnly:'developer'."),
   hidden: z.boolean().optional().describe("true: never shown in the form (a system value). A conditional hide is showIf."),
   blocks: z.record(z.string(), z.strictObject({ icon: dockIconArg.optional(), preview: z.record(z.string(), z.string()).optional() })).optional().describe("modular only: per block slug, {icon?, preview?} for its rows."),
@@ -3511,6 +3562,25 @@ function proseType(f) {
 }
 var confirmedHeaders = (confirmed) => confirmed === true ? { [INPUT_CONFIRMED_HEADER]: "true" } : {};
 var withHeaders = (headers) => Object.keys(headers).length > 0 ? { headers } : {};
+var integrationShape = {
+  allowedHosts: z.array(z.string()).max(10).optional().describe(INTEGRATION_PARAM_TEXT.allowedHosts),
+  secrets: z.record(z.string(), z.string()).optional().describe(INTEGRATION_PARAM_TEXT.secrets),
+  inject: z.object({ headers: z.record(z.string(), z.string()).optional(), query: z.record(z.string(), z.string()).optional() }).optional().describe(INTEGRATION_PARAM_TEXT.inject),
+  allowPost: z.boolean().optional().describe(INTEGRATION_PARAM_TEXT.allowPost),
+  auth: z.record(z.string(), z.unknown()).nullable().optional().describe(INTEGRATION_PARAM_TEXT.auth),
+  settings: z.record(z.string(), z.unknown()).optional().describe(INTEGRATION_PARAM_TEXT.settings),
+  syncs: z.array(z.record(z.string(), z.unknown())).max(20).optional().describe(INTEGRATION_PARAM_TEXT.syncs),
+  panel: z.string().max(48).nullable().optional().describe(INTEGRATION_PARAM_TEXT.panel),
+  hooks: z.array(z.record(z.string(), z.unknown())).max(20).optional().describe(INTEGRATION_PARAM_TEXT.hooks),
+  endpoints: z.array(z.record(z.string(), z.unknown())).max(20).optional().describe(INTEGRATION_PARAM_TEXT.endpoints),
+  references: z.array(z.record(z.string(), z.unknown())).max(10).optional().describe(INTEGRATION_PARAM_TEXT.references),
+  functions: z.array(z.record(z.string(), z.unknown())).max(20).optional().describe(INTEGRATION_PARAM_TEXT.functions),
+  oauth: z.record(z.string(), z.unknown()).nullable().optional().describe(INTEGRATION_PARAM_TEXT.oauth),
+  alertAfter: z.number().int().min(0).max(50).optional().describe(INTEGRATION_PARAM_TEXT.alertAfter)
+};
+var integrationShapeBare = Object.fromEntries(
+  Object.entries(integrationShape).map(([k, v]) => [k, v.describe(void 0)])
+);
 var DRY_RUN_SUMMARY = "Dry run: nothing was written.";
 var dryRunOf = async (client, method, path, body, headers = {}) => ok(DRY_RUN_SUMMARY, await client.fetchJSON(client.url(path), { method, body: JSON.stringify({ ...body, dryRun: true }), ...withHeaders(headers) }));
 function toField(f) {
@@ -5180,6 +5250,144 @@ ${d.outline}` : "Proposed Content structure.", d);
         // The whole body: a `test` delivery's outcome rides beside `data`.
         async (c, a) => ok("Webhook created. Store the `secret` now: it is never shown again.", await c.fetchJSON(c.url(`/management/webhooks`), { method: "POST", body: JSON.stringify({ name: a.name, url: a.url, events: a.events, isActive: a.isActive, test: a.test }) }))
       ),
+      def(
+        "list_integrations",
+        "List custom integrations",
+        NEW_TOOL_TEXT.list_integrations,
+        z.object({}).shape,
+        // The whole body: the workspace's `templates` ride beside `data`.
+        async (c) => ok("Integrations.", await c.fetchJSON(c.url(`/management/integrations`), { method: "GET" }))
+      ),
+      def(
+        "get_integration",
+        "Get a custom integration",
+        NEW_TOOL_TEXT.get_integration,
+        z.object({ integration: z.string().min(1).describe(INTEGRATION_PARAM_TEXT.integration) }).shape,
+        async (c, a) => ok("Integration.", await data(c, "GET", `/management/integrations/${s(a.integration)}`))
+      ),
+      def(
+        "create_integration",
+        "Create a custom integration",
+        NEW_TOOL_TEXT.create_integration,
+        z.object({
+          slug: z.string().min(1).max(48).describe(INTEGRATION_PARAM_TEXT.slug),
+          name: z.string().min(1).max(120).describe("a label, 1-120 chars"),
+          vendor: z.string().max(60).optional().describe("the vendor's name, e.g. 'Greenhouse'"),
+          ...integrationShape
+        }).shape,
+        // The whole body: `approval` rides beside `data`.
+        async (c, a) => ok("Integration created.", await c.fetchJSON(c.url(`/management/integrations`), { method: "POST", body: JSON.stringify(a) }))
+      ),
+      def(
+        "update_integration",
+        "Update a custom integration",
+        NEW_TOOL_TEXT.update_integration,
+        z.object({
+          integration: z.string().min(1).describe(INTEGRATION_PARAM_TEXT.integration),
+          name: z.string().min(1).max(120).optional(),
+          vendor: z.string().max(60).nullable().optional(),
+          ...integrationShapeBare
+        }).shape,
+        async (c, a) => {
+          const { integration, ...body } = a;
+          return ok("Integration updated.", await c.fetchJSON(c.url(`/management/integrations/${s(integration)}`), { method: "PATCH", body: JSON.stringify(body) }));
+        }
+      ),
+      def(
+        "delete_integration",
+        "Delete a custom integration",
+        NEW_TOOL_TEXT.delete_integration,
+        z.object({ integration: z.string().min(1).describe(INTEGRATION_PARAM_TEXT.integration) }).shape,
+        async (c, a) => ok("Integration deleted.", await data(c, "DELETE", `/management/integrations/${s(a.integration)}`))
+      ),
+      def(
+        "run_integration_sync",
+        "Run an integration's sync",
+        NEW_TOOL_TEXT.run_integration_sync,
+        z.object({
+          integration: z.string().min(1).describe(INTEGRATION_PARAM_TEXT.integration),
+          sync: z.string().min(1).describe(INTEGRATION_PARAM_TEXT.sync),
+          waitSeconds: z.number().min(0).max(50).optional().describe(PARAM_TEXT.waitSeconds)
+        }).shape,
+        async (c, a) => ok("Sync run.", await data(c, "POST", withWait(`/management/integrations/${s(a.integration)}/syncs/${s(a.sync)}/run`, a.waitSeconds)))
+      ),
+      def(
+        "run_integration_function",
+        "Run an integration's function",
+        NEW_TOOL_TEXT.run_integration_function,
+        z.object({
+          integration: z.string().min(1).describe(INTEGRATION_PARAM_TEXT.integration),
+          name: z.string().min(1).describe("the function's name"),
+          input: z.unknown().optional().describe("the function's `event` (JSON)"),
+          waitSeconds: z.number().min(0).max(50).optional().describe(PARAM_TEXT.waitSeconds)
+        }).shape,
+        async (c, a) => ok("Function run.", await data(c, "POST", withWait(`/management/integrations/${s(a.integration)}/functions/${s(a.name)}/run`, a.waitSeconds), { input: a.input }))
+      ),
+      def(
+        "search_integration_reference",
+        "Search an integration's live reference",
+        NEW_TOOL_TEXT.search_integration_reference,
+        z.object({
+          integration: z.string().min(1).describe(INTEGRATION_PARAM_TEXT.integration),
+          reference: z.string().min(1).describe(INTEGRATION_PARAM_TEXT.reference),
+          query: z.string().max(200).optional().describe("what to search for")
+        }).shape,
+        async (c, a) => ok("Vendor items.", await data(c, "POST", `/management/integrations/${s(a.integration)}/references/${s(a.reference)}/search`, { query: a.query ?? "" }))
+      ),
+      def(
+        "start_integration_signin",
+        "Start an integration's vendor sign-in",
+        NEW_TOOL_TEXT.start_integration_signin,
+        z.object({ integration: z.string().min(1).describe(INTEGRATION_PARAM_TEXT.integration) }).shape,
+        async (c, a) => ok("Sign-in URL: give it to the user to open.", await data(c, "POST", `/management/integrations/${s(a.integration)}/oauth/start`))
+      ),
+      def(
+        "save_integration_template",
+        "Save an integration as a template",
+        NEW_TOOL_TEXT.save_integration_template,
+        z.object({
+          integration: z.string().min(1).describe(INTEGRATION_PARAM_TEXT.integration),
+          slug: z.string().min(1).max(48).optional().describe(INTEGRATION_PARAM_TEXT.slug),
+          name: z.string().min(1).max(120).optional().describe("a label, 1-120 chars"),
+          description: z.string().max(500).optional().describe("what it connects, for the people installing it")
+        }).shape,
+        async (c, a) => {
+          const { integration, ...body } = a;
+          return ok("Template saved.", await data(c, "POST", `/management/integrations/${s(integration)}/template`, body));
+        }
+      ),
+      def(
+        "install_integration_template",
+        "Install an integration template",
+        NEW_TOOL_TEXT.install_integration_template,
+        z.object({
+          template: z.string().min(1).describe(INTEGRATION_PARAM_TEXT.template),
+          slug: z.string().min(1).max(48).optional().describe(INTEGRATION_PARAM_TEXT.slug),
+          name: z.string().min(1).max(120).optional().describe("a label, 1-120 chars")
+        }).shape,
+        // The whole body: `approval`, `secretsNeeded` and `collectionsCreated` ride beside `data`.
+        async (c, a) => {
+          const { template, ...body } = a;
+          return ok("Template installed.", await c.fetchJSON(c.url(`/management/integrations/templates/${s(template)}/install`), { method: "POST", body: JSON.stringify(body) }));
+        }
+      ),
+      def(
+        "test_integration_fetch",
+        "Call a vendor through an integration",
+        NEW_TOOL_TEXT.test_integration_fetch,
+        z.object({
+          integration: z.string().min(1).describe(INTEGRATION_PARAM_TEXT.integration),
+          url: z.string().url().describe(INTEGRATION_PARAM_TEXT.url),
+          method: z.enum(["GET", "POST"]).optional().describe("GET when omitted"),
+          headers: z.record(z.string(), z.string()).optional().describe(INTEGRATION_PARAM_TEXT.headers),
+          query: z.record(z.string(), z.string()).optional().describe(INTEGRATION_PARAM_TEXT.query),
+          json: z.unknown().optional().describe(INTEGRATION_PARAM_TEXT.json)
+        }).shape,
+        async (c, a) => {
+          const { integration, ...req } = a;
+          return ok("Vendor response.", await data(c, "POST", `/management/integrations/${s(integration)}/fetch`, req));
+        }
+      ),
       def(
         "list_branches",
         "List content branches",