@bettercms-ai/mcp 0.80.1 → 0.81.0

package/dist/index.js

@@ -2915,6 +2915,11 @@ var LISTING_TAIL = /* @__PURE__ */ new Set([
   "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",
@@ -2999,12 +3004,17 @@ var NEW_TOOL_TEXT = {
   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.",
-  list_integrations: "List the project's custom integrations (any vendor with a public API: jobs boards, stores, CRMs, video). Each has its allowed hosts, secret NAMES with `secretsPresent` (is the env var set; never the value), `inject` (where the secrets go), syncs, panel and `approved`. Read bettercms://skill/integrations before building one.",
-  get_integration: "One integration (`integration`: id or slug) with its last 20 sync runs (status, counts, error).",
-  create_integration: "Declare a custom integration: `allowedHosts` (exact hostnames the server may call), `secrets` (template name -> project env var KEY), `inject` (the headers / query parameters that carry them on every request, e.g. {headers: {authorization: 'Bearer {{secret.TOKEN}}'}}), `allowPost` (GET only unless true), optional `auth` token exchange (inject {{token}}), `syncs` (vendor list -> collection) and `panel`. Secret VALUES never pass through here: the user sets them under Settings \u2192 Environment variables (production); list_env_vars shows the names. Until an admin approves it, vendor calls and syncs are refused: give the user `approval.approveUrl` and the `approval.changes` in plain words. You cannot approve it yourself.",
-  update_integration: "Change an integration (`integration`: id or slug); keys you leave out are kept, and `secrets`, `inject` and `syncs` replace the stored ones whole. Changing `allowedHosts`, `secrets`, `inject`, `allowPost` or `auth` withdraws its approval until an admin approves again (`approval.approveUrl`). Name, syncs, settings and panel never need approval.",
+  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.";
@@ -3063,9 +3073,17 @@ var INTEGRATION_PARAM_TEXT = {
   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: {request:{method,url,headers?,query?,form?}, tokenPath, expiresInPath?, ttlSeconds?}; {{secret.NAME}} in its values; its result is {{token}}",
+  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: "[{key, contentModelId, request:{method,url,headers?,query?}, pagination?:{style:'none'|'page'|'cursor'|'link', param?, cursorPath?, maxPages?}, items, externalKey, slug?, map:{fieldKey: pointer | {path, transform?:'string'|'number'|'boolean'|'join'}}, publish?, schedule?:'hourly'|'daily'|null}]; pointers are JSON Pointers",
+  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)",
@@ -3359,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."),
@@ -3551,8 +3570,17 @@ var integrationShape = {
   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)
+  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) {
@@ -5227,7 +5255,8 @@ ${d.outline}` : "Proposed Content structure.", d);
         "List custom integrations",
         NEW_TOOL_TEXT.list_integrations,
         z.object({}).shape,
-        async (c) => ok("Integrations.", await data(c, "GET", `/management/integrations`))
+        // 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",
@@ -5255,9 +5284,9 @@ ${d.outline}` : "Proposed Content structure.", d);
         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().describe("a label, 1-120 chars"),
-          vendor: z.string().max(60).nullable().optional().describe("the vendor's name"),
-          ...integrationShape
+          name: z.string().min(1).max(120).optional(),
+          vendor: z.string().max(60).nullable().optional(),
+          ...integrationShapeBare
         }).shape,
         async (c, a) => {
           const { integration, ...body } = a;
@@ -5282,6 +5311,66 @@ ${d.outline}` : "Proposed Content structure.", d);
         }).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",