@solumflow-app/crm-mcp-server 0.5.0 → 0.7.0

package/README.md

@@ -52,6 +52,7 @@ scope the key lacks answers `forbidden` and names the scope it needs.
 
 | Tool | Scope | What it does |
 | --- | --- | --- |
+| `server_info` | none | The version of this server and of its client, the API address, and the fingerprint of the tool definitions it serves. |
 | `list_forms` | `website:manage` | Published forms, with their link and embed snippet. |
 | `list_booking_pages` | `website:manage` | Every page a visitor can book on, with its embed snippet. |
 | `list_chat_widgets` | `website:manage` | Chat widgets, the sites each may run on, and the script tag. |
@@ -60,10 +61,10 @@ scope the key lacks answers `forbidden` and names the scope it needs.
 | `update_site_tracking` | `website:manage` | Add or remove those domains. |
 | `list_catalogs` | `catalog:read` | The product catalogues the key can write to, and their slugs. |
 | `list_catalog_fields` | `catalog:read` | The public custom fields of a catalogue, including how each content block is built. |
-| `list_products` | `catalog:read` | One page of published products, by category or catalogue. |
+| `list_products` | `catalog:read` | One page of published products, by category or catalogue. With `status` (`draft`, `archived`, `all`) and a key that has `catalog:write`, the concepts and archived ones too. |
 | `get_product` | `catalog:read` | One product as its page needs it. |
 | `get_product_availability` | `catalog:read` | Whether a product can be bought now, live. |
-| `list_categories` | `catalog:read` | The category tree, with product counts. |
+| `list_categories` | `catalog:read` | The category tree, with product counts. `status` `draft` or `all` (with `catalog:write`) adds the concept categories. |
 | `get_category` | `catalog:read` | One category page and a page of its products. |
 | `read_configurator` | `catalog:read` | A product's 3D configurator document. |
 | `check_configurator_shape` | none | Check a configurator structure or shape the way the app does, without saving it. |
@@ -81,6 +82,21 @@ scope the key lacks answers `forbidden` and names the scope it needs.
 Every catalogue tool takes an optional `object`: the slug of another catalogue
 of the account (from `list_catalogs`). Left out, it is the account's own.
 
+## After an update
+
+An agent keeps the tool definitions it was handed when its session began, and a
+session that outlives an update of this server talks to the new server with the
+old definitions. The server cannot make the agent reload. What it does:
+
+- `server_info` says which version is running and carries
+  `definitionsVersion`, a fingerprint of every tool definition it serves.
+- Each write tool names that fingerprint in its description and takes it back
+  as `schemaHash`. When the two differ, the call is still carried out and the
+  answer adds a note that the definitions are older than the server.
+- It announces a changed tool list to clients that listen for it. Claude Code
+  does not always: **restart the session** (in Claude Code `/mcp` and
+  reconnect, or start a new session) after you update the package.
+
 ## Writing the catalogue
 
 The write tools change a customer's live catalogue, so it helps to know what the
@@ -96,6 +112,12 @@ API does with them:
 - **Typos do not become data.** A category or a select choice that does not
   exist is refused, unless `createMissingCategories` or `addMissingOptions` asks
   for it.
+- **A repeater's items may leave out `id`.** SolumFlow makes one, and the
+  answer's `fields` holds it; send it back to change that item. Leave it out
+  again and the items are replaced by new ones, and their files fetched again.
+- **Read back what you wrote** with `get_product_by_ref`: every field as stored
+  (`fields`), what a visitor sees of them (`publicFields`), and every category
+  with its `status`, a concept too.
 - **Archiving keeps the product** for the invoices that name it;
   `upsert_product` with `archived: false` brings it back.
 

package/dist/index.js

@@ -6,7 +6,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { createClient } from "@solumflow-app/crm-client";
 
 // package.json
-var version = "0.5.0";
+var version = "0.7.0";
 
 // src/catalog-migration-tools.ts
 import { z as z4 } from "zod";
@@ -38,6 +38,11 @@ var CatalogFieldSlugSchema = z.string().max(63).regex(FIELD_SLUG, {
   )
 });
 var cents = z.number().int().min(0).max(MAX_AMOUNT_CENTS);
+var CatalogCategoryPlacementSchema = z.object({
+  slug: CatalogWebSlugSchema,
+  /** Lowest first; equal places stand in id order. */
+  position: z.number().int().min(-1e6).max(1e6).optional()
+}).strict();
 var text = (max) => z.string().trim().max(max).nullable().optional();
 var CatalogPriceSchema = z.object({
   /** The price's own id at the source, so a renamed price stays itself. */
@@ -199,8 +204,13 @@ var CatalogProductUpsertSchema = z.object({
   socialTitle: text(300),
   socialDescription: text(1e3),
   socialImage: CatalogFileRefSchema.nullable().optional(),
-  /** Replaces the product's categories, by slug. */
-  categories: z.array(CatalogWebSlugSchema).max(50).optional(),
+  /**
+   * Replaces the product's categories, by slug, the first one leading. An
+   * entry may be `{ slug, position }` instead, to also set where the
+   * product stands on that category's page (`?sort=position`, lowest
+   * first); a plain slug leaves a stored place as it is.
+   */
+  categories: z.array(z.union([CatalogWebSlugSchema, CatalogCategoryPlacementSchema])).max(50).optional(),
   /**
    * Make a category that does not exist yet instead of refusing. Off unless
    * asked for, so a typo cannot become a category on a customer's website.
@@ -387,7 +397,13 @@ var CatalogAttributeUpsertSchema = z.object({
    * Bring the field back from the trash under its own id, with every value
    * the products kept. Nothing else may be sent with it.
    */
-  restore: z.literal(true).optional()
+  restore: z.literal(true).optional(),
+  /**
+   * For a new content field (`content_text`, `repeater`, `cta`): put its
+   * block at the end of the product page. On by default; `false` makes the
+   * field only. Never moves or restores a block of an existing field.
+   */
+  placeOnPage: z.boolean().optional()
 }).strict();
 var CONFIGURATOR_FILE_KINDS = ["model", "texture"];
 var CONFIGURATOR_TEXTURE_CONTENT_TYPES = [
@@ -500,10 +516,15 @@ var objectInput = {
     "The slug of the catalogue (see list_catalogs). Leave out for the account\u2019s own catalogue."
   )
 };
-var CONTENT_BLOCKS = 'Besides plain values (text, number, choice), a product can carry content blocks, three field types: "content_text" is { html, links? } with already-sanitised html; "cta" is { heading, body, primary: {label,url}, secondary? }, a call to action; "repeater" is { items: [{ id, ...one value per item field }] } and covers lists, accordions (FAQ), downloads and testimonials. A repeater\u2019s field says how to draw it: "display" is "list" or "accordion", "preset" names where it started (list, faq, downloads, testimonials), "itemFields" is the structure of one item (key, label, type: text, richtext, url {label,url}, icon {set,name}, image or file {url,name,size,contentType}) and "titleKey" is the item field that names an item, such as the question of a FAQ. A "configurator" is a 3D product configurator: a listing carries only { configurator: true }, a product\u2019s own page the whole document (see read_configurator). A block that is public but empty is null; a block that is not public is not there at all.';
+var CONTENT_BLOCKS = 'Besides plain values (text, number, choice), a product can carry content blocks, three field types: "content_text" is { html, links? } with already-sanitised html; "cta" is { heading, body, primary: {label,url}, secondary? }, a call to action; "repeater" is { items: [{ id, ...one value per item field }] } and covers lists, accordions (FAQ), downloads and testimonials. A repeater\u2019s field says how to draw it: "display" is "list" or "accordion", "preset" names where it started (list, faq, downloads, testimonials), "itemFields" is the structure of one item (key, label, type: text, richtext, url {label,url}, icon {set,name}, image or file {url,name,size,contentType}) and "titleKey" is the item field that names an item, such as the question of a FAQ. A "configurator" is a 3D product configurator: a listing carries only { configurator: true }, a product\u2019s own page the whole document (see read_configurator). A block that is public but empty is null; a block that is not public is not there at all. A new block field stands at the end of the product page from the moment upsert_field makes it (`placeOnPage: false` skips that).';
 var currency = z3.string().regex(/^[A-Z]{3}$/).optional().describe(
   "Every price in this currency (see list_currencies), each with its origin: base, fixed or converted. Left out, every price in its own currency."
 );
+var READ_STATUS_HINT = 'Left out, only published ones. "draft" is what is not on the website yet (concept, internal or scheduled), "archived" what was taken out, "all" everything; each answers with a `status` and `publishedAt` per item. Anything but published needs a key with catalog:write.';
+var productStatus = z3.enum(["published", "draft", "archived", "all"]).optional().describe(`Which products. ${READ_STATUS_HINT}`);
+var categoryStatus = z3.enum(["published", "draft", "all"]).optional().describe(
+  `Which categories. ${READ_STATUS_HINT.replace('"archived" what was taken out, ', "")} A category cannot be archived.`
+);
 var slugOrId = z3.string().min(1).max(200).describe("The address (slug) or the id of the product.");
 function registerCatalogTools(server, client) {
   server.registerTool(
@@ -578,15 +599,18 @@ function registerCatalogTools(server, client) {
     "get_product",
     {
       title: "Read one product",
-      description: "One product as its page needs it: name, prices, pictures, categories, variants and `fields`, keyed by field slug. Published products only, and may be a minute old: to read back what you just wrote, use get_product_by_ref. Answers that it is not found for an unknown product. " + CONTENT_BLOCKS,
-      inputSchema: { slugOrId, currency },
+      description: "One product as its page needs it: name, prices, pictures, categories, variants and `fields`, keyed by field slug. Published products only unless you pass `status` (needs a server key), and a published one may be a minute old: to read back exactly what you just wrote, use get_product_by_ref. Answers that it is not found for an unknown product, or one not in the status asked. " + CONTENT_BLOCKS,
+      inputSchema: { slugOrId, currency, status: productStatus },
       annotations: { readOnlyHint: true, idempotentHint: true }
     },
-    async ({ slugOrId: wanted, currency: inCurrency }) => {
+    async ({ slugOrId: wanted, currency: inCurrency, status }) => {
       try {
         const product = await client.getProduct(
           wanted,
-          inCurrency ? { currency: inCurrency } : void 0
+          inCurrency || status ? {
+            ...inCurrency ? { currency: inCurrency } : {},
+            ...status ? { status } : {}
+          } : void 0
         );
         if (!product) {
           return answer(`No product "${wanted}" on this account.`, null);
@@ -604,8 +628,8 @@ function registerCatalogTools(server, client) {
   server.registerTool(
     "list_products",
     {
-      title: "List the published products",
-      description: "One page of the catalogue: name, address (slug), lowest price, whether it is in stock, its first picture and the public fields a listing shows. Narrow it to one category\u2019s whole branch by its id or address, or by the reference upsert_category recorded (`categorySource` + `categoryRef`), to one catalogue by the slug of its object, or to the product carrying an article number (`sku`). Read get_product for everything a product page needs. May be a minute old.",
+      title: "List the products",
+      description: "One page of the catalogue: name, address (slug), lowest price, whether it is in stock, its first picture and the public fields a listing shows. Narrow it to one category\u2019s whole branch by its id or address, or by the reference upsert_category recorded (`categorySource` + `categoryRef`), to one catalogue by the slug of its object, or to the product carrying an article number (`sku`). Read get_product for everything a product page needs. Published products only, and may be a minute old; `status` lists concepts, scheduled and archived ones too (needs a server key). `sort` orders the published ones: -publishedAt (newest first, the default), publishedAt, name, or position -- the seller\u2019s own order on the page of `category`, which it needs. Each item carries `sku`, `publishedAt` and `stockQuantity` (null when not counted).",
       inputSchema: {
         ...page,
         category: z3.string().regex(
@@ -621,7 +645,11 @@ function registerCatalogTools(server, client) {
         object: z3.string().min(1).max(63).optional().describe(
           'One catalogue, by the slug of its object, such as "product".'
         ),
-        currency
+        currency,
+        status: productStatus,
+        sort: z3.enum(["-publishedAt", "publishedAt", "name", "position"]).optional().describe(
+          "The order: newest first by default; position needs `category`."
+        )
       },
       annotations: { readOnlyHint: true, idempotentHint: true }
     },
@@ -637,7 +665,7 @@ function registerCatalogTools(server, client) {
           } : {}
         });
         return answer(
-          list.data.length === 0 ? "No published products match." : [...list.data.map(describeProduct), more(list.nextCursor)].filter(Boolean).join("\n"),
+          list.data.length === 0 ? `No ${input.status && input.status !== "published" ? input.status : "published"} products match.` : [...list.data.map(describeProduct), more(list.nextCursor)].filter(Boolean).join("\n"),
           list
         );
       } catch (error) {
@@ -648,11 +676,12 @@ function registerCatalogTools(server, client) {
   server.registerTool(
     "list_categories",
     {
-      title: "List the published categories",
-      description: 'The categories of the catalogue, each with its path from the top and how many products are in it. Left without `parent`, every category comes back, which is what building a menu in one go needs; "root" asks for the top level, a category id for its children.',
+      title: "List the categories",
+      description: 'The categories of the catalogue, each with its path from the top and how many products are in it. Left without `parent`, every category comes back, which is what building a menu in one go needs; "root" asks for the top level, a category id for its children. Published categories only unless you pass `status` (draft or all, needs a server key).',
       inputSchema: {
         ...page,
-        parent: z3.union([z3.literal("root"), z3.string().uuid()]).optional().describe('"root" or the id of a category.')
+        parent: z3.union([z3.literal("root"), z3.string().uuid()]).optional().describe('"root" or the id of a category.'),
+        status: categoryStatus
       },
       annotations: { readOnlyHint: true, idempotentHint: true }
     },
@@ -660,7 +689,7 @@ function registerCatalogTools(server, client) {
       try {
         const list = await client.getCategories(input);
         return answer(
-          list.data.length === 0 ? "No published categories." : [...list.data.map(describeCategory), more(list.nextCursor)].filter(Boolean).join("\n"),
+          list.data.length === 0 ? `No ${input.status && input.status !== "published" ? input.status : "published"} categories.` : [...list.data.map(describeCategory), more(list.nextCursor)].filter(Boolean).join("\n"),
           list
         );
       } catch (error) {
@@ -672,10 +701,11 @@ function registerCatalogTools(server, client) {
     "get_category",
     {
       title: "Read one category page",
-      description: "One category as its page needs it: name, description, the texts for search engines and social media, and the first page of its products. Pass the nextCursor back to page through the products.",
+      description: "One category as its page needs it: name, description, the texts for search engines and social media, and the first page of its products. Pass the nextCursor back to page through the products. A category that is not on the website yet needs `status` (draft or all, a server key); its products are the published ones.",
       inputSchema: {
         slugOrId: z3.string().min(1).max(200).describe("The address (slug) or the id of the category."),
-        ...page
+        ...page,
+        status: categoryStatus
       },
       annotations: { readOnlyHint: true, idempotentHint: true }
     },
@@ -724,23 +754,49 @@ function registerCatalogTools(server, client) {
   );
 }
 function describeProduct(product) {
-  const stock = product.inStock ? "" : ", out of stock";
+  const stock = `${product.inStock ? "" : ", out of stock"}${product.status ? `, ${product.status}` : ""}`;
   const from = product.priceFromCents === null ? `no price in ${product.currency}` : `from ${money(product.priceFromCents, product.currency)}`;
   return `- ${product.name} (${product.slug}): ${from}${stock}`;
 }
 function describeCategory(category) {
   const path = category.path.map((step) => step.name).join(" / ");
-  return `- ${path || category.name} (${category.slug}, id ${category.id}): ${category.productCount} products`;
+  const state = category.status ? `, ${category.status}` : "";
+  return `- ${path || category.name} (${category.slug || "no address yet"}, id ${category.id}${state}): ${category.productCount} products`;
 }
 function describeField(field) {
   if (field.type !== "repeater") {
-    return `- ${field.slug}: ${field.label}, ${field.type}`;
+    return `- ${field.slug}: ${field.label}, ${field.type}${settingsOf(field)}`;
   }
   const items = (field.itemFields ?? []).map(({ key, type }) => `${key}:${type}`).join(", ");
   const preset = field.preset ? `, ${field.preset}` : "";
   const title = field.titleKey ? `; titled by ${field.titleKey}` : "";
   return `- ${field.slug}: ${field.label}, repeater (${field.display ?? "list"}${preset}; items: ${items}${title})`;
 }
+var SETTING_KEYS = [
+  "prefix",
+  "suffix",
+  "currency",
+  "symbolPosition",
+  "thousandsSeparator",
+  "decimalSeparator",
+  "decimals",
+  "display",
+  "layout",
+  "mode",
+  "secondary"
+];
+function settingsOf(field) {
+  const given = SETTING_KEYS.flatMap(
+    (key) => field[key] === void 0 ? [] : [`${key} ${JSON.stringify(field[key])}`]
+  );
+  if (field.rows) {
+    given.push(`${field.rows.length} rows`);
+  }
+  if (field.columns) {
+    given.push(`${field.columns.length} columns`);
+  }
+  return given.length > 0 ? ` (${given.join(", ")})` : "";
+}
 
 // src/catalog-migration-tools.ts
 import { readFile, stat } from "fs/promises";
@@ -781,7 +837,7 @@ function registerCatalogMigrationTools(server, client) {
     "get_product_by_ref",
     {
       title: "Read back a product you wrote",
-      description: "One product by the reference it was written under (`source` + `externalRef`), a draft too: its page, its sku and shelf per variant, the shared-link texts and picture, and `files` -- for every picture or file of the last write whether it is `pending`, `stored` or `refused`, with a reason code. Live, never cached: read this after upsert_product to see what arrived.",
+      description: "One product by the reference it was written under (`source` + `externalRef`), a draft too. `fields` holds every field the product has a value for, public or not, as stored -- list item ids and file paths included, which a write accepts back; `publicFields` is what a visitor sees of them. `categories` lists every category it is filed under, a concept one too, each with its `status`. Also `status` and `publishedAt`, its sku and shelf per variant, the shared-link texts and picture, and `files` -- for every picture or file of the last write whether it is `pending`, `stored` or `refused`, with a reason code. Live, never cached: read this after upsert_product to see what arrived.",
       inputSchema: {
         externalRef: CatalogExternalRefSchema,
         source: CatalogSourceSchema,
@@ -809,7 +865,7 @@ function registerCatalogMigrationTools(server, client) {
           (file) => file.status === "pending"
         );
         return answer(
-          `${product.name} (${product.slug || "no address"}), ${product.availability}; ${product.images.length} pictures; files: ${pending.length} pending, ${refused.length} refused${refused.length ? ` (${refused.map((file) => `${file.ref}: ${file.reason}`).join("; ")})` : ""}.`,
+          `${product.name} (${product.slug || "no address"}), ${product.status} (${product.availability}); ${Object.keys(product.fields).length} fields, ${product.categories.length} categories, ${product.images.length} pictures; files: ${pending.length} pending, ${refused.length} refused${refused.length ? ` (${refused.map((file) => `${file.ref}: ${file.reason}`).join("; ")})` : ""}.`,
           product
         );
       } catch (error) {
@@ -906,18 +962,25 @@ function registerCatalogMigrationTools(server, client) {
     "get_category_by_ref",
     {
       title: "Find a category by its reference",
-      description: "The category upsert_category recorded with this `source` and `externalRef` -- the id of a series in your own system -- also after its address was changed in the app. Only a published category.",
+      description: 'The category upsert_category recorded with this `source` and `externalRef` -- the id of a series in your own system -- also after its address was changed in the app. A published category unless you pass `status`: "draft" finds a concept or scheduled one, "all" any (needs a server key).',
       inputSchema: {
         source: CatalogSourceSchema,
-        externalRef: CatalogExternalRefSchema
+        externalRef: CatalogExternalRefSchema,
+        status: z4.enum(["published", "draft", "all"]).optional().describe(
+          "Which categories to look in; anything but published needs catalog:write."
+        )
       },
       annotations: { readOnlyHint: true, idempotentHint: true }
     },
-    async ({ source, externalRef }) => {
+    async ({ source, externalRef, status }) => {
       try {
-        const category = await client.getCategoryByRef(source, externalRef);
+        const category = await client.getCategoryByRef(
+          source,
+          externalRef,
+          status ? { status } : void 0
+        );
         return answer(
-          category ? `${category.name} (${category.slug}), id ${category.id}.` : `No published category with reference "${externalRef}" from "${source}".`,
+          category ? `${category.name} (${category.slug || "no address yet"}), id ${category.id}${category.status ? `, ${category.status}` : ""}.` : `No ${status && status !== "published" ? status : "published"} category with reference "${externalRef}" from "${source}"${status ? "" : ' (a concept category needs status "all")'}.`,
           category
         );
       } catch (error) {
@@ -972,6 +1035,16 @@ function registerCatalogMigrationTools(server, client) {
 }
 
 // src/catalog-write-tools.ts
+import { CrmApiError as CrmApiError2 } from "@solumflow-app/crm-client";
+function usedIn(details) {
+  const blockers = details?.blockers;
+  if (!Array.isArray(blockers) || blockers.length === 0) {
+    return null;
+  }
+  return blockers.map(
+    (entry) => `${String(entry.kind).replaceAll("_", " ")} (${String(entry.count)})`
+  ).join(", ");
+}
 function target2(object2) {
   return object2 ? { object: object2 } : void 0;
 }
@@ -982,7 +1055,7 @@ function registerCatalogWriteTools(server, client) {
     "upsert_product",
     {
       title: "Make or change a product",
-      description: IDENTITY + ' Every field but `source` may be left out, and left out means "leave it as it is"; null empties a field. A new product needs a `name` and is a draft unless `availability` says otherwise: do not publish without the user asking. `prices`, `categories`, `images` and `variants` each replace what the product had as a whole, and a variant left out is archived. Categories are named by slug and a missing one is refused unless `createMissingCategories` is true; a choice a select field does not offer is refused unless `addMissingOptions` is true. Pictures are https URLs, fetched after the answer (`images: "pending"`). Amounts are in cents. A price without `currency` is in the product\'s own; one with another `currency` is the fixed price for that currency, may share its label with the euro price, and can never be the default. `stock` (physical only; per variant when there are variants) is a count, not a movement: a second run writes it again over a correction made in the app, so send it only when the source keeps the count. A picture is { url } or { upload } (upload_catalog_file), with `alt`, a `role` in your own words ("insitu") and flat `details` ({ widthCm: 120 }); `socialImage` is the shared-link picture beside `socialTitle` and `socialDescription`. Files arrive after the answer: get_product_by_ref says per file whether it came. `description` is plain text (5,000 characters); `longDescription` is HTML, cleaned to headings, paragraphs, lists, links, bold and italic. To write many products use upsert_products. Read list_catalog_fields first for the slugs `fields` takes.',
+      description: IDENTITY + ' Every field but `source` may be left out, and left out means "leave it as it is"; null empties a field. A new product needs a `name` and is a draft unless `availability` says otherwise: do not publish without the user asking. `prices`, `categories`, `images` and `variants` each replace what the product had as a whole, and a variant left out is archived. Categories are named by slug and a missing one is refused unless `createMissingCategories` is true; a choice a select field does not offer is refused unless `addMissingOptions` is true. Pictures are https URLs, fetched after the answer (`images: "pending"`). Amounts are in cents. A price without `currency` is in the product\'s own; one with another `currency` is the fixed price for that currency, may share its label with the euro price, and can never be the default. `stock` (physical only; per variant when there are variants) is a count, not a movement: a second run writes it again over a correction made in the app, so send it only when the source keeps the count. A picture is { url } or { upload } (upload_catalog_file), with `alt`, a `role` in your own words ("insitu") and flat `details` ({ widthCm: 120 }); `socialImage` is the shared-link picture beside `socialTitle` and `socialDescription`. Files arrive after the answer: get_product_by_ref says per file whether it came. `description` is plain text (5,000 characters); `longDescription` is HTML, cleaned to headings, paragraphs, lists, links, bold and italic. A repeater is sent whole: `items` replaces the list. An item may leave out its `id` -- SolumFlow makes one, and `fields` in the answer holds it; send the id back to change that item, or the items are replaced by new ones and their files fetched again. An image or file item key is { url: "https://..." } (fetched after the answer) or { upload }; a wrong one is refused with the path of the item. To write many products use upsert_products. Read list_catalog_fields first for the slugs `fields` takes.',
       inputSchema: {
         externalRef: CatalogExternalRefSchema.describe(
           "The id of the product in the system named by `source`."
@@ -1039,6 +1112,49 @@ function registerCatalogWriteTools(server, client) {
       }
     }
   );
+  server.registerTool(
+    "delete_product",
+    {
+      title: "Delete a product for good",
+      description: IDENTITY + " Deleting removes the product, its variants, prices and pictures for good; it cannot be undone. It only works for a product that nothing uses: one that is on an order, a payment page, a subscription, a booking or a hosting service is refused, and the answer says where. Then archive_product is the way out. Archive when in doubt, and ask the user before deleting anything they did not name.",
+      inputSchema: {
+        externalRef: CatalogExternalRefSchema.describe(
+          "The id of the product in the system named by `source`."
+        ),
+        ...CatalogProductArchiveSchema.shape,
+        ...objectInput
+      },
+      annotations: { destructiveHint: true, idempotentHint: true }
+    },
+    async ({ externalRef, source, object: object2 }) => {
+      try {
+        const result = await client.deleteProduct(
+          externalRef,
+          source,
+          target2(object2)
+        );
+        return answer("Deleted for good.", result);
+      } catch (error) {
+        if (error instanceof CrmApiError2 && error.code === "conflict") {
+          const places = usedIn(error.details);
+          if (places) {
+            return {
+              isError: true,
+              content: [
+                {
+                  type: "text",
+                  text: `conflict: ${error.message}
+Used in: ${places}.
+Archive it with archive_product instead.`
+                }
+              ]
+            };
+          }
+        }
+        return refusal(error, "catalog:write");
+      }
+    }
+  );
   server.registerTool(
     "upsert_category",
     {
@@ -1073,7 +1189,7 @@ function registerCatalogWriteTools(server, client) {
     "upsert_field",
     {
       title: "Make or change a catalogue field",
-      description: "A custom field on products, known by its slug: sending the same slug again changes it. A new field needs a `label`. " + FIELD_KINDS + " `config` replaces the settings as a whole. `options` makes sure choices exist and never removes one; `removeOptions` takes choices off the list, which empties them on every product that had them. `public` decides whether the website may show the field at all. `dryRun: true` answers what would change -- and how many products hold each choice that would go -- and writes nothing. A slug in the trash is taken until restore_field or a permanent delete_field.",
+      description: "A custom field on products, known by its slug: sending the same slug again changes it. A new field needs a `label`. " + FIELD_KINDS + " `config` replaces the settings as a whole. `options` makes sure choices exist and never removes one; `removeOptions` takes choices off the list, which empties them on every product that had them. `public` decides whether the website may show the field at all. A new content field (content_text, repeater, cta) gets its block at the end of the product page in the same save, and the answer says `placedOnPage`; `placeOnPage: false` makes the field only. An existing field is never placed again, so a block somebody took off the page stays off. `dryRun: true` answers what would change -- and how many products hold each choice that would go -- and writes nothing. A slug in the trash is taken until restore_field or a permanent delete_field.",
       inputSchema: {
         slug: CatalogFieldSlugSchema.describe(
           "The slug of the field: a lower-case letter, then lower case, digits and underscores."
@@ -1092,7 +1208,7 @@ function registerCatalogWriteTools(server, client) {
         }
         const field = await client.upsertField(slug, input, target2(object2));
         return answer(
-          `${field.created ? "Made" : "Changed"} ${field.label} (${field.slug}), ${field.type}, ${field.public ? "public" : "not public"}.`,
+          `${field.created ? "Made" : "Changed"} ${field.label} (${field.slug}), ${field.type}, ${field.public ? "public" : "not public"}.` + (field.placedOnPage === void 0 ? "" : field.placedOnPage ? " Its block is at the end of the product page." : ` Its block is not on the product page (${field.notPlacedBecause ?? "not placed"}).`),
           field
         );
       } catch (error) {
@@ -3550,7 +3666,119 @@ function readServerConfig(env) {
   return { ok: true, apiKey, baseUrl };
 }
 
+// src/server-info-tool.ts
+function registerServerInfoTool(server, info) {
+  server.registerTool(
+    "server_info",
+    {
+      title: "Which version of this server is running",
+      description: "The version of this MCP server and of the API client it uses, the address of the API it talks to, and `definitionsVersion`, a fingerprint of every tool definition it serves. A write tool names the same fingerprint in its description; when the two differ, your session was started before an update of this server and works from older tool definitions -- restart the session (in Claude Code `/mcp` and reconnect, or a new session). The server cannot do that for you.",
+      inputSchema: {},
+      annotations: { readOnlyHint: true, idempotentHint: true }
+    },
+    async () => {
+      const result = {
+        version: info.version,
+        clientVersion: info.clientVersion,
+        baseUrl: info.baseUrl,
+        definitionsVersion: info.definitionsVersion()
+      };
+      return answer(
+        `crm-mcp-server ${result.version} (client ${result.clientVersion}), API ${result.baseUrl}, tool definitions ${result.definitionsVersion}.`,
+        result
+      );
+    }
+  );
+}
+
+// src/tool-definitions-version.ts
+import { z as z11 } from "zod";
+import { createHash } from "crypto";
+function toolDefinitionsHash(tools) {
+  const definitions = [...tools].sort((left, right) => left.name.localeCompare(right.name)).map(({ name, config }) => ({
+    name,
+    title: config.title ?? null,
+    description: config.description ?? null,
+    inputSchema: config.inputSchema ? z11.toJSONSchema(z11.object(config.inputSchema), {
+      io: "input",
+      unrepresentable: "any"
+    }) : null,
+    annotations: config.annotations ?? null
+  }));
+  return createHash("sha256").update(JSON.stringify(definitions)).digest("hex").slice(0, 12);
+}
+function writesSomething(config) {
+  return config.annotations?.readOnlyHint !== true;
+}
+function holdToolRegistrations(real) {
+  const pending = [];
+  let hash;
+  const server = new Proxy(real, {
+    get(target3, property) {
+      if (property === "registerTool") {
+        return (name, config, handler) => {
+          pending.push({ name, config, handler });
+          return void 0;
+        };
+      }
+      const value = Reflect.get(target3, property, target3);
+      return typeof value === "function" ? value.bind(target3) : value;
+    }
+  });
+  function currentHash() {
+    hash ??= toolDefinitionsHash(pending);
+    return hash;
+  }
+  function publish() {
+    const version2 = currentHash();
+    for (const { name, config, handler } of pending) {
+      if (!writesSomething(config)) {
+        real.registerTool(
+          name,
+          config,
+          handler
+        );
+        continue;
+      }
+      real.registerTool(
+        name,
+        {
+          ...config,
+          description: `${config.description ?? ""} Definitions version ${version2}: send it as schemaHash and the answer tells you when these tool definitions are older than the server.`,
+          inputSchema: {
+            ...config.inputSchema,
+            schemaHash: z11.string().max(64).optional().describe(
+              `The definitions version named in this tool's description (${version2}).`
+            )
+          }
+        },
+        (async ({ schemaHash, ...input }, extra) => {
+          const result = await handler(input, extra);
+          return schemaHash !== void 0 && schemaHash !== version2 ? {
+            ...result,
+            content: [
+              ...result.content ?? [],
+              { type: "text", text: staleDefinitions(version2) }
+            ]
+          } : result;
+        })
+      );
+    }
+    return version2;
+  }
+  return { server, publish, currentHash };
+}
+function staleDefinitions(version2) {
+  return `Note: your tool definitions are older than this server (its version is ${version2}). The call was carried out as given. Restart the session, or reconnect the server with /mcp in Claude Code, to load the current definitions; server_info says which version is running.`;
+}
+
 // src/index.ts
+import { createRequire } from "module";
+function installedClientVersion() {
+  return createRequire(import.meta.url)(
+    "@solumflow-app/crm-client/package.json"
+  ).version;
+}
 async function main() {
   const config = readServerConfig(process.env);
   if (!config.ok) {
@@ -3567,13 +3795,26 @@ async function main() {
     apiKey: config.apiKey,
     baseUrl: config.baseUrl
   });
-  registerPlacementTools(server, client);
-  registerCatalogTools(server, client);
-  registerCatalogWriteTools(server, client);
-  registerCatalogMigrationTools(server, client);
-  registerEventTools(server, client);
-  registerConfiguratorTools(server, client);
+  const held = holdToolRegistrations(server);
+  registerServerInfoTool(held.server, {
+    version,
+    clientVersion: installedClientVersion(),
+    baseUrl: config.baseUrl,
+    definitionsVersion: held.currentHash
+  });
+  registerPlacementTools(held.server, client);
+  registerCatalogTools(held.server, client);
+  registerCatalogWriteTools(held.server, client);
+  registerCatalogMigrationTools(held.server, client);
+  registerEventTools(held.server, client);
+  registerConfiguratorTools(held.server, client);
+  held.publish();
   await server.connect(new StdioServerTransport());
+  try {
+    server.sendToolListChanged();
+  } catch (error) {
+    console.error("crm-mcp-server: could not announce the tool list:", error);
+  }
 }
 main().catch((error) => {
   console.error("crm-mcp-server:", error);