@cookiemunch/mcp 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog: @cookiemunch/mcp
+
+Every published release, newest first. Dates are the day the version was cut. Each release tracks the same-numbered `@cookiemunch/sdk`.
+
+## 0.5.0 (2026-10-23)
+
+- Added: `get_org_controller`, `set_org_controller`, `remove_org_controller`.
+- Added: `get_consent_sync_secret`, `rotate_consent_sync_secret`, `remove_consent_sync_secret`.
+- Added: `mint_preference_center_token`.
+- Changed: built on `@cookiemunch/sdk` 0.5.0.
+
+## 0.4.1 (2026-10-22)
+
+- Added: `apply_cookie_preset` takes `referally` (`cookieDomain`, `cookieDays`, `category`).
+- Added: requests send `User-Agent: cookiemunch-mcp/<version>`.
+
+## 0.4.0 (2026-10-19)
+
+- Added: tools for site PATCH, integration health, `provision` and partner links.
+- Added: executor preset and canary tools; declaration preset tools and observed-cookie removal.
+
+## 0.3.0 (2026-10-15)
+
+- Added: `retire_cookie` and `unretire_cookie`; `scan_site` can wait for the result, including a scan already running.
+
+## 0.2.0 (2026-10-15)
+
+- Added: executor webhook test and delivery log with dry runs.
+- Added: `purposes` and `dryRun` on declared cookies; rights-page identity tools.
+- Fixed: design-warning headers say what happened; notices are not blamed on Accept.
+
+## 0.1.2 (2026-10-15)
+
+- Changed: the package builds standalone from its public repository and is published with npm provenance.
+
+## 0.1.1 (2026-10-14)
+
+- Added: tools to declare, bulk-declare and undeclare cookies and to apply an import.
+- Added: `preview_site_config` (dry run) and design warnings leading every config tool result.
+- Added: rights-page tools (read, write, preview, publish, versions, rollback) and custom-domain tools.
+
+## 0.1.0 (2026-10-14)
+
+- First release: the Developer API as MCP tools (`whoami`, sites, config, consent stats and log, DSAR, vendors, RoPA).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cookie Munch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/bin.cjs

@@ -1515,6 +1515,21 @@ ${JSON.stringify(r, null, 2)}` : r;
     { subjectId: import_zod5.z.string() },
     (a) => client.preferences.get(a.subjectId)
   );
+  tool(
+    "mint_preference_center_token",
+    "Mint a hosted preference-centre token for one visitor (POST /v1/preference-center/tokens), for a page to pass to CookieMunch.setSubjectToken. Give exactly one of email (resolved as the emailed preference link resolves it; an unknown address is subject_not_found) or subjectId. The token is a credential that opens that person\u2019s subscriptions and profile until expiresAt: never paste it into a shared URL, a ticket or a log, and keep ttlSeconds short (default 3600, max 86400). Needs subscriptions:write and profile:write, plus identity:read by email.",
+    {
+      cbid: import_zod5.z.string().describe("A site of your organisation."),
+      email: import_zod5.z.string().optional().describe("The visitor\u2019s address. Give this or subjectId, not both."),
+      subjectId: import_zod5.z.string().optional().describe("The subject id. Give this or email, not both."),
+      ttlSeconds: import_zod5.z.number().int().min(1).max(86400).optional()
+    },
+    (a) => client.preferenceCenter.mintToken({
+      cbid: a.cbid,
+      ...a.email !== void 0 ? { email: a.email } : { subjectId: a.subjectId },
+      ...a.ttlSeconds !== void 0 ? { ttlSeconds: a.ttlSeconds } : {}
+    })
+  );
   tool(
     "issue_api_key",
     "Issue a new API key. The secret is returned once and never again. Prefer the least privilege the job needs: `scopes` limits what it can do, `cbids` locks it to specific sites (it then cannot reach anything org-wide), `expiresInDays` retires it. Omitting all three mints a full-access, org-wide, non-expiring key.",
@@ -1614,7 +1629,7 @@ ${JSON.stringify(r, null, 2)}` : r;
   );
   tool(
     "list_cookie_presets",
-    "Declaration presets for the platforms a site is built on (atlas, forumulate, chatly, cookiemunch): each one\u2019s parameters, what it has declared on this site, and whether the vendor\u2019s live manifest can be imported yet. Read-only.",
+    "Declaration presets for the platforms a site is built on (atlas, forumulate, chatly, cookiemunch, referally): each one\u2019s parameters, what it has declared on this site, and whether the vendor\u2019s live manifest can be imported yet. Read-only.",
     { cbid: import_zod5.z.string() },
     (a) => client.sites.cookiePresets(a.cbid)
   );
@@ -1623,24 +1638,26 @@ ${JSON.stringify(r, null, 2)}` : r;
     "Apply (or re-sync) a vendor preset: declares exactly what that platform writes \u2014 cookies and browser storage, with domain and lifetime \u2014 marked as declared by that vendor. Re-applying removes keys the vendor no longer writes. Names the owner declared are kept (skipped). Atlas needs frontendApiHost (and crossSubdomainCookies, default true); Chatly needs publicId.",
     {
       cbid: import_zod5.z.string(),
-      vendor: import_zod5.z.enum(["atlas", "forumulate", "chatly", "cookiemunch"]),
+      vendor: import_zod5.z.enum(["atlas", "forumulate", "chatly", "cookiemunch", "referally"]),
       frontendApiHost: import_zod5.z.string().optional().describe("Atlas: your frontend API host, e.g. auth.example.com."),
       crossSubdomainCookies: import_zod5.z.boolean().optional().describe("Atlas: default true \u2014 the cookies live on the parent domain."),
       publicId: import_zod5.z.string().optional().describe("Chatly: the channel public id (ch_web_\u2026)."),
       dragging: import_zod5.z.boolean().optional().describe("Chatly: the launcher can be dragged (adds the drag-position key)."),
-      category: import_zod5.z.string().optional().describe("Chatly: the category for its keys. Default necessary."),
+      category: import_zod5.z.string().optional().describe("Chatly: the category for its keys (default necessary). Referally: default the site's referrals category, else marketing."),
+      cookieDomain: import_zod5.z.string().optional().describe("Referally: the domain aff.js sets referally_ctx on, e.g. .example.com. Default the site domain."),
+      cookieDays: import_zod5.z.number().int().min(1).max(400).optional().describe("Referally: how long the cookie lives, 1 to 400 days. Default 60."),
       dryRun: dryRunArg
     },
     (a) => {
       const params = {};
-      for (const k of ["frontendApiHost", "crossSubdomainCookies", "publicId", "dragging", "category"]) if (a[k] !== void 0) params[k] = a[k];
+      for (const k of ["frontendApiHost", "crossSubdomainCookies", "publicId", "dragging", "category", "cookieDomain", "cookieDays"]) if (a[k] !== void 0) params[k] = a[k];
       return client.sites.applyCookiePreset(a.cbid, a.vendor, params, a.dryRun ? { dryRun: true } : void 0);
     }
   );
   tool(
     "remove_cookie_preset",
     "Remove every declaration a vendor preset made on this site.",
-    { cbid: import_zod5.z.string(), vendor: import_zod5.z.enum(["atlas", "forumulate", "chatly", "cookiemunch"]), dryRun: dryRunArg },
+    { cbid: import_zod5.z.string(), vendor: import_zod5.z.enum(["atlas", "forumulate", "chatly", "cookiemunch", "referally"]), dryRun: dryRunArg },
     (a) => client.sites.removeCookiePreset(a.cbid, a.vendor, a.dryRun ? { dryRun: true } : void 0)
   );
   tool(
@@ -1742,6 +1759,37 @@ ${JSON.stringify(r, null, 2)}` : r;
       return { removed: true };
     }
   );
+  tool(
+    "get_org_controller",
+    "The organisation\u2019s own data-controller identity: who every rights notice names, before any site config controller block. `set: false` when there is none. Read-only.",
+    {},
+    () => client.org.controller.get()
+  );
+  tool(
+    "set_org_controller",
+    "Set the organisation\u2019s data-controller identity. Replaces it: a field left out is removed. Needed for a notice on a rights request filed without a cbid when the organisation has several sites. Needs an unscoped key or rights:write. Audited.",
+    {
+      legalName: import_zod5.z.string().describe("Required: the legal name of the data controller."),
+      contactEmail: import_zod5.z.string().optional().describe("Where people reach the controller about their data."),
+      address: import_zod5.z.string().optional(),
+      dpoContact: import_zod5.z.string().optional().describe("The Data Protection Officer: a name, an email address, or both.")
+    },
+    (a) => client.org.controller.set({
+      legalName: a.legalName,
+      ...a.contactEmail !== void 0 ? { contactEmail: a.contactEmail } : {},
+      ...a.address !== void 0 ? { address: a.address } : {},
+      ...a.dpoContact !== void 0 ? { dpoContact: a.dpoContact } : {}
+    })
+  );
+  tool(
+    "remove_org_controller",
+    "Remove the organisation\u2019s data-controller identity. Notices then name the request\u2019s site config controller block; a request without a cbid in an organisation with several sites gets no notice.",
+    {},
+    async () => {
+      await client.org.controller.remove();
+      return { removed: true };
+    }
+  );
   const CAPTCHA_OFF = "Off removes spam protection beyond the hidden spam-trap field, the rate limits and the email code: expect more spam requests. Own keys are recommended.";
   const captchaInput = {
     mode: import_zod5.z.enum(["own", "off"]).describe(`own: your own captcha provider keys (recommended). off: no captcha. ${CAPTCHA_OFF}`),
@@ -1757,6 +1805,24 @@ ${JSON.stringify(r, null, 2)}` : r;
     ...a.secret !== void 0 ? { secret: a.secret } : {},
     ...a.minScore !== void 0 ? { minScore: a.minScore } : {}
   });
+  tool(
+    "get_consent_sync_secret",
+    "Whether hosted consent sync is set up for a site: `configured`, `secretLast4`, `createdAt`. Never returns the secret. Read-only.",
+    { cbid: import_zod5.z.string() },
+    (a) => client.consentSyncSecret.get(a.cbid)
+  );
+  tool(
+    "rotate_consent_sync_secret",
+    "Mint a site\u2019s consent-sync signing secret, or rotate it. The answer carries `secret` this once; the site owner\u2019s server signs consent-sync tokens with it (mintConsentSyncToken in @cookiemunch/sdk). Rotating stops the old secret at once, so every page holding a token signed with it stops syncing until it gets a new token. Never put the secret in a page. Needs sites:write and consent:write.",
+    { cbid: import_zod5.z.string() },
+    (a) => client.consentSyncSecret.rotate(a.cbid)
+  );
+  tool(
+    "remove_consent_sync_secret",
+    "Remove a site\u2019s consent-sync secret: hosted consent sync stops until a new one is minted. Needs sites:write and consent:write.",
+    { cbid: import_zod5.z.string() },
+    (a) => client.consentSyncSecret.remove(a.cbid)
+  );
   tool(
     "get_rights_captcha",
     "The captcha on a site\u2019s hosted rights page: its own setting, else the organisation default, else off (`source` says which). Never returns the secret. Read-only.",
@@ -1998,8 +2064,9 @@ ${JSON.stringify(r, null, 2)}` : r;
 }
 
 // src/index.ts
+var MCP_VERSION = "0.5.0";
 function createCookieMunchMcp(opts) {
-  const client = opts.client ?? (0, import_sdk.createCookieMunch)({ apiKey: opts.apiKey, baseUrl: opts.baseUrl });
+  const client = opts.client ?? (0, import_sdk.createCookieMunch)({ apiKey: opts.apiKey, baseUrl: opts.baseUrl, userAgent: opts.userAgent ?? `cookiemunch-mcp/${MCP_VERSION}` });
   const server = new import_mcp.McpServer({ name: "cookiemunch", version: "1.0.0" });
   registerTools(server, client);
   return server;
@@ -2013,7 +2080,7 @@ async function main() {
     process.exit(1);
   }
   const baseUrl = process.env.COOKIEMUNCH_BASE_URL ?? "https://api.cookiemunch.net";
-  const server = createCookieMunchMcp({ apiKey, baseUrl });
+  const server = createCookieMunchMcp({ apiKey, baseUrl, ...process.env.COOKIEMUNCH_USER_AGENT ? { userAgent: process.env.COOKIEMUNCH_USER_AGENT } : {} });
   const transport = new import_stdio.StdioServerTransport();
   await server.connect(transport);
 }