@sealab/mcp-server 1.0.0

package/src/tools/orders.ts

@@ -0,0 +1,1229 @@
+import { z } from 'zod';
+import { client, handleAxiosError } from '../client/api-client';
+
+// ---------------------------------------------------------------------------
+// Helper: flexible array schema that accepts both native arrays and JSON strings.
+//
+// WHY: MCP clients (e.g. Claude Code) validate tool arguments against the
+// advertised JSON schema BEFORE sending the request to the server. A plain
+// z.preprocess(..., z.array(...)) generates { type: "array" }, so the client
+// rejects string values immediately with "params/<field> must be array" and
+// the request never reaches the server's preprocess rescue logic.
+//
+// This helper generates { anyOf: [{ type: "array", ... }, { type: "string" }] }
+// so the client validator passes strings through, while runtime validation in
+// the string branch parses and re-validates the JSON before the handler runs.
+// ---------------------------------------------------------------------------
+function flexArray<T extends z.ZodTypeAny>(itemSchema: T, minItems = 1) {
+  return z.union([
+    z.array(itemSchema).min(minItems),
+    z.string().transform((str, ctx): z.infer<T>[] => {
+      let parsed: unknown;
+      try { parsed = JSON.parse(str); } catch {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, message: 'Value is not valid JSON' });
+        return z.NEVER as never;
+      }
+      const result = z.array(itemSchema).min(minItems).safeParse(parsed);
+      if (!result.success) {
+        for (const issue of result.error.issues) ctx.addIssue(issue);
+        return z.NEVER as never;
+      }
+      return result.data;
+    }),
+  ]);
+}
+
+// ---------------------------------------------------------------------------
+// Helper: Apply default gaps when gapControl = true
+// ---------------------------------------------------------------------------
+
+/**
+ * Checks if an article has gapControl = true and applies default gap values ("0.125" = 1/8")
+ * when gaps are not provided. Returns a new article object with defaults applied.
+ */
+async function applyGapDefaults(article: z.infer<typeof ArticleItemSchema>): Promise<z.infer<typeof ArticleItemSchema>> {
+  try {
+    // Fetch article configuration to check gapControl flag
+    const { data: config } = await client.get(`/catalog/${article.serialNumber}/configuration`);
+    
+    // Check if gapControl is enabled for this article
+    if (config.gapControl === true) {
+      // Create a copy of the article to avoid mutating the original
+      const articleWithDefaults = { ...article };
+      
+      // Apply default "0.125" (1/8") to any gap fields that are not provided
+      if (articleWithDefaults.gapTop === undefined) articleWithDefaults.gapTop = "0.125";
+      if (articleWithDefaults.gapBottom === undefined) articleWithDefaults.gapBottom = "0.125";
+      if (articleWithDefaults.gapLeft === undefined) articleWithDefaults.gapLeft = "0.125";
+      if (articleWithDefaults.gapRight === undefined) articleWithDefaults.gapRight = "0.125";
+      if (articleWithDefaults.gapCenter === undefined) articleWithDefaults.gapCenter = "0.125";
+      
+      return articleWithDefaults;
+    }
+  } catch (error) {
+    // If we can't fetch configuration, proceed without applying defaults
+    // The API will handle any validation errors
+  }
+  
+  // No gapControl or error fetching config - return article as-is
+  return article;
+}
+
+/**
+ * Process an array of articles, applying gap defaults to each one.
+ * Returns a new array with defaults applied where applicable.
+ */
+async function applyGapDefaultsToArticles(
+  articles: z.infer<typeof ArticleItemSchema>[]
+): Promise<z.infer<typeof ArticleItemSchema>[]> {
+  return Promise.all(articles.map(applyGapDefaults));
+}
+
+// ---------------------------------------------------------------------------
+// Helper: Apply saved setting preset values to articles
+// ---------------------------------------------------------------------------
+
+/**
+ * Cache for fetched saved settings to avoid redundant API calls.
+ * Each entry stores the data alongside a fetchedAt timestamp so entries
+ * older than SETTINGS_CACHE_TTL_MS are treated as stale and re-fetched.
+ * This handles updates made from the web portal (not just via MCP tools).
+ */
+const SETTINGS_CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const savedSettingsCache = new Map<string, { data: any; fetchedAt: number }>();
+
+/**
+ * Fetch a saved setting by name (from user settings or presets)
+ */
+async function fetchSavedSettingByName(name: string): Promise<any | null> {
+  // Return cached entry only if it is still within the TTL window
+  const cached = savedSettingsCache.get(name);
+  if (cached && Date.now() - cached.fetchedAt < SETTINGS_CACHE_TTL_MS) {
+    return cached.data;
+  }
+
+  try {
+    // Try fetching from user's saved settings first
+    const { data: userSettings } = await client.get('/saved-settings/user');
+    const userSetting = (userSettings as any[]).find((s: any) => s.name === name);
+    if (userSetting) {
+      savedSettingsCache.set(name, { data: userSetting, fetchedAt: Date.now() });
+      return userSetting;
+    }
+
+    // Try fetching from public presets
+    const { data: presets } = await client.get('/saved-settings/presets');
+    const preset = (presets as any[]).find((s: any) => s.name === name);
+    if (preset) {
+      savedSettingsCache.set(name, { data: preset, fetchedAt: Date.now() });
+      return preset;
+    }
+  } catch (error) {
+    // If we can't fetch settings, proceed without applying preset values
+    // The API will handle validation
+  }
+
+  return null;
+}
+
+/**
+ * Applies saved setting preset values to an article when settingsName is specified.
+ * This ensures ALL preset values are applied to the article fields, not just the
+ * settingsName reference. Fields explicitly set by the user take precedence over preset values.
+ * 
+ * @param article - The article to apply preset values to
+ * @returns The article with preset values applied (or original if no preset)
+ */
+async function applySavedSettingToArticle<T extends { settingsName?: string; [key: string]: any }>(
+  article: T
+): Promise<T> {
+  // If no settingsName is specified, return article as-is
+  if (!article.settingsName) {
+    return article;
+  }
+
+  // Fetch the saved setting by name
+  const savedSetting = await fetchSavedSettingByName(article.settingsName);
+  if (!savedSetting) {
+    // Could not find the saved setting - return article as-is
+    // The API will return an error if the settingsName is invalid
+    return article;
+  }
+
+  // Create a copy of the article to avoid mutating the original
+  const articleWithPreset = { ...article } as any;
+
+  // Mapping of saved setting fields to article fields
+  // Only apply preset values if the article field is not already set (user values take precedence)
+  if (savedSetting.caseMaterial && !articleWithPreset.caseMaterial) {
+    articleWithPreset.caseMaterial = savedSetting.caseMaterial;
+  }
+  if (savedSetting.frontMaterial && !articleWithPreset.frontMaterial) {
+    articleWithPreset.frontMaterial = savedSetting.frontMaterial;
+  }
+  if (savedSetting.backPanelMaterial && !articleWithPreset.backPanelMaterial) {
+    articleWithPreset.backPanelMaterial = savedSetting.backPanelMaterial;
+  }
+  if (savedSetting.backPanel && !articleWithPreset.backPanel) {
+    articleWithPreset.backPanel = savedSetting.backPanel;
+  }
+  if (savedSetting.drawerType && !articleWithPreset.drawerType) {
+    articleWithPreset.drawerType = savedSetting.drawerType;
+  }
+  if (savedSetting.jointMethod && !articleWithPreset.jointMethod) {
+    articleWithPreset.jointMethod = savedSetting.jointMethod;
+  }
+  if (savedSetting.caseEdge && !articleWithPreset.caseEdge) {
+    articleWithPreset.caseEdge = savedSetting.caseEdge;
+  }
+  if (savedSetting.frontEdge && !articleWithPreset.frontEdge) {
+    articleWithPreset.frontEdge = savedSetting.frontEdge;
+  }
+  if (savedSetting.hingePlate && !articleWithPreset.hingePlate) {
+    articleWithPreset.hingePlate = savedSetting.hingePlate;
+  }
+  if (savedSetting.numOfShelves && !articleWithPreset.numOfShelves) {
+    articleWithPreset.numOfShelves = savedSetting.numOfShelves;
+  }
+  if (savedSetting.topDrwrHeightValue && !articleWithPreset.topDrwrHeightValue) {
+    articleWithPreset.topDrwrHeightValue = savedSetting.topDrwrHeightValue;
+  }
+  
+  // Handle includeLegLevelers - convert string to boolean if needed
+  if (savedSetting.includeLegLevelers !== undefined && articleWithPreset.includeLegLevelers === undefined) {
+    // The saved setting stores this as a string ("true"/"false" or "1"/"0")
+    const val = savedSetting.includeLegLevelers;
+    articleWithPreset.includeLegLevelers = val === true || val === 'true' || val === '1' || val === 1;
+  }
+
+  // Note: bottomPanelConnector maps to includeLegLevelers logic in some cases
+  // but we don't have a direct field mapping for it in ArticleItemSchema
+
+  return articleWithPreset as T;
+}
+
+/**
+ * Process an array of articles, applying saved setting preset values to each one.
+ * Returns a new array with preset values applied where settingsName is specified.
+ */
+async function applySavedSettingsToArticles<T extends { settingsName?: string; [key: string]: any }>(
+  articles: T[]
+): Promise<T[]> {
+  return Promise.all(articles.map(applySavedSettingToArticle));
+}
+
+const ArticleItemSchema = z.object({
+  serialNumber: z.string(),
+  positionName: z.string().max(25).describe(
+    'Unique label for this cabinet within the order. Must be unique across ALL articles in the order. ' +
+    'Derive from the cabinet display name: "Upper 1125" → "Upper", "Base Cabinet" → "Base". ' +
+    'First of a type: just the prefix ("Upper"). Additional same-type cabinets: dot-number suffix ("Upper.1", "Upper.2"). ' +
+    'MULTI-QUANTITY NAMING (qty > 1): You MUST include the "_01" suffix in the positionName you provide. ' +
+    'The server starts from the number in your positionName and increments it for each unit. ' +
+    'Example: positionName "DR_B2_01" with quantity=3 → server creates "DR_B2_01", "DR_B2_02", "DR_B2_03". ' +
+    'Do NOT omit the suffix — a bare name like "DR_B2" triggers incorrect fallback parsing that produces wrong names (e.g. "DR_B_02"). ' +
+    'COORDINATE CONSEQUENCE: When you later call update_cabinet_coordinates for a qty>1 article, ' +
+    'you must supply a separate coordinate entry for EVERY expanded positionName (e.g. all three of "DR_B2_01", "DR_B2_02", "DR_B2_03"). ' +
+    'Max 25 characters, no dashes (use underscores).'
+  ),
+  quantity: z.number().int().min(1),
+  height: z.number().describe('Height in inches'),
+  width: z.number().describe('Width in inches'),
+  depth: z.number().describe('Depth in inches'),
+
+  // Materials — use exact description strings returned by get_article_options
+  caseMaterial: z.string().optional().describe('Case/box material. Use exact string from get_article_options materials list.'),
+  frontMaterial: z.string().optional().describe('Door/drawer front material. Use exact string from get_article_options. Omit when excludeFronts is true.'),
+  innerCaseMaterial: z.string().optional().describe('Inner case material (only for articles with hasMatCaseThin=true). Use exact string from get_article_options materials list.'),
+  backPanelMaterial: z.string().optional().describe('Back panel material. Use exact string from get_article_options materials list.'),
+
+  // Edgebanding — standard articles
+  caseEdge: z.string().optional().describe('Case edgebanding. Use exact string from get_article_options edgebanding list.'),
+  frontEdge: z.string().optional().describe('Front edgebanding. Use exact string from get_article_options edgebanding list.'),
+
+  // Edgebanding — LP_SP/LP_GP series only
+  edgeBandingType: z.string().optional().describe('Edgebanding type for LP_SP/LP_GP series articles. Applied to all four edge positions. Use exact string from get_article_options edgebanding list.'),
+
+  // Configuration options — use exact description strings returned by get_article_options
+  drawerType: z.string().optional().describe('Drawer box construction type. Use exact string from get_article_options drawerType list.'),
+  jointMethod: z.string().optional().describe('Case joinery method. Use exact string from get_article_options jointMethod list.'),
+  hingePlate: z.string().optional().describe('Hinge plate type. Use exact string from get_article_options hingePlate list.'),
+  backPanel: z.string().optional().describe('Back panel attachment method. Use exact string from get_article_options backPanel list.'),
+  numOfShelves: z.string().optional().describe('Number of adjustable shelves. Use exact string from get_article_options numOfShelves list (e.g. "3", "0", "Parametric Shelves").'),
+
+  // Gap control — decimal inch strings
+  gapTop: z.string().optional().describe('Top reveal gap in inches. Valid values: "0" (flush), "0.0625" (1/16"), "0.125" (1/8").'),
+  gapBottom: z.string().optional().describe('Bottom reveal gap in inches. Valid values: "0", "0.0625", "0.125".'),
+  gapLeft: z.string().optional().describe('Left reveal gap in inches. Valid values: "0", "0.0625", "0.125".'),
+  gapRight: z.string().optional().describe('Right reveal gap in inches. Valid values: "0", "0.0625", "0.125".'),
+  gapCenter: z.string().optional().describe('Center gap between adjacent doors/drawers in inches. Valid values: "0", "0.0625", "0.125".'),
+
+  // Top drawer height (only for articles with topDrwrHeight feature)
+  topDrwrHeightValue: z.string().optional().describe('Custom top drawer height in inches (e.g. "12"). Only for articles that support topDrwrHeight. Valid range: 4–28.'),
+
+  // Corner cabinet dimensions
+  leftCornerWidth: z.number().optional().describe('Left corner width in inches. Only for corner cabinet articles with cornerVariables=true.'),
+  rightCornerDepth: z.number().optional().describe('Right corner depth in inches. Only for corner cabinet articles with cornerVariables=true.'),
+
+  // Boolean flags
+  excludeFronts: z.boolean().optional().describe('When true, fronts are excluded from this order (supplied by others). Sets frontMaterial to "Fronts By Others". Do not also set frontMaterial.'),
+  includeLegLevelers: z.boolean().optional().describe('When true, leg levelers are included. Only valid for articles with the Leg_Levelers filter tag.'),
+
+  // INSERTION POINT COORDINATE CONVENTION
+  // x, y, z, rotation = 2D plan coordinates + height + orientation, all in decimal inches / degrees.
+  // Pass CENTER X and CENTER Y directly — server stores as-is, no conversion applied.
+  //
+  // x: CENTER X of the cabinet on the plan in decimal inches.
+  //    North wall (rotation=0)  : x = left_edge + width/2   (left_edge = sum of widths of cabinets to the left + any filler)
+  //    South wall (rotation=180): x = left_edge + width/2   (same — reading left-to-right on plan)
+  //    East wall  (rotation=90) : x = room_width - depth/2  (fixed value for all cabinets on this wall)
+  //    West wall  (rotation=270): x = depth/2               (fixed value for all cabinets on this wall)
+  //
+  // y: CENTER Y of the cabinet on the plan in decimal inches. REQUIRED for multi-wall kitchens.
+  //    South wall (rotation=180): y = depth / 2
+  //    North wall (rotation=0)  : y = room_depth - (depth / 2)
+  //    East wall  (rotation=90) : y = bottom_edge + width/2  (bottom_edge = sum of widths of cabinets south of this one + any filler from corner)
+  //    West wall  (rotation=270): y = bottom_edge + width/2  (same method)
+  //    If omitted, server defaults to depth/2 — correct only for south-wall single-wall layouts.
+  //
+  // z: height from floor. 0 for base cabinets. Stacked units: sum heights of all cabinets below.
+  //
+  // rotation: plan orientation in degrees (clockwise). 0 = north wall, 90 = east wall, 180 = south wall, 270 = west wall.
+  //    If no compass rose, assume top=north, bottom=south, left=west, right=east.
+  //    Determines which direction the cabinet face points in CAD.
+  //    Omit or use 0 if all cabinets are on a single north wall.
+  x: z.number().optional().describe(
+    'Center X in decimal inches. See the coordinate formulas in the tool description — same rules apply here. ' +
+    'North/South wall: x = D_adj_west + cumulative_widths_left + this_width/2. ' +
+    'West wall base: x = depth/2 (NEVER negative). West wall upper front-flush: x = base_depth - upper_depth/2. ' +
+    'East wall base: x = room_width - depth/2. East wall upper front-flush: x = room_width - base_depth + upper_depth/2.'
+  ),
+  y: z.number().optional().describe(
+    'Center Y in decimal inches. See the coordinate formulas in the tool description — same rules apply here. ' +
+    'South wall base: y = depth/2. South wall upper front-flush: y = base_depth - upper_depth/2. ' +
+    'North wall base: y = room_depth - depth/2. North wall upper front-flush: y = room_depth - base_depth + upper_depth/2. ' +
+    'East/West wall: cabinets run north-to-south (y decreases going south). List them northernmost first. ' +
+    'D_adj_north = north wall cabinet depth if present, else 0. ' +
+    'Northernmost cabinet: y = room_depth - D_adj_north - this_width/2. ' +
+    'Each next going south: y = room_depth - D_adj_north - (sum of widths of all preceding cabinets) - this_width/2. ' +
+    'NEVER add widths — adding goes north (wrong direction). ' +
+    'UPPER cabinets on east/west walls: y = same as the base cabinet below — do NOT change y for front-flush. Front-flush = x change only.'
+  ),
+  z: z.number().optional().describe(
+    'Height from floor in decimal inches. ' +
+    'Base cabinets on the floor = 0. ' +
+    'Stacked units: sum the heights of all cabinets directly below this one. ' +
+    'Example: niche above a 28.375" base cabinet has z=28.375; upper above niche (14.125" tall) has z=42.5.'
+  ),
+  rotation: z.number().optional().describe(
+    'Plan orientation in degrees (clockwise). ' +
+    '0 = north wall, 90 = east wall, 180 = south wall, 270 = west wall. ' +
+    'If the drawing has no compass rose, assume: top wall = north, bottom wall = south, left wall = west, right wall = east. ' +
+    'Determines which direction the cabinet face points on the plan and in CAD. ' +
+    'Default 0 for single-wall or north-wall installations.'
+  ),
+
+  // Saved setting preset name — references a saved configuration preset applied to this article
+  // CRITICAL: If you are using values from a saved setting (obtained via get_my_saved_settings or get_saved_settings_presets),
+  // you MUST also set settingsName to the exact name of that saved setting.
+  // This ensures the preset_setting column is populated in the database for traceability.
+  // Example: If using "Zach's Kitchen" preset, set settingsName: "Zach's Kitchen"
+  settingsName: z.string().optional().describe(
+    'REQUIRED when using a saved setting preset: The exact name of the saved setting (e.g., "Zach\'s Kitchen", "Modern Euro"). ' +
+    'Obtain this from get_my_saved_settings or get_saved_settings_presets. ' +
+    'This field MUST be set when any configuration values (caseMaterial, frontMaterial, edgebanding, etc.) are taken from a saved setting.'
+  ),
+});
+
+const ProjectAddressSchema = z.object({
+  projectAddress1: z.string().optional().describe('Project address line 1'),
+  projectAddress2: z.string().nullable().optional().describe('Project address line 2'),
+  projectCity: z.string().optional().describe('Project city'),
+  projectState: z.string().optional().describe('Project state'),
+  projectZipcode: z.string().optional().describe('Project zipcode'),
+});
+
+const ListOrdersSchema = z.object({
+  limit: z.number().int().min(1).max(100).default(20).describe('Max results (default 20, max 100)'),
+  offset: z.number().int().min(0).default(0).describe('Pagination offset'),
+});
+
+const GetOrderSchema = z.object({
+  orderId: z.string().describe('Order ID, e.g. ORD-001'),
+});
+
+const GetOrderBreakdownSchema = z.object({
+  orderId: z.string().describe('Order ID, e.g. ORD-001'),
+});
+
+const GetPositionBreakdownSchema = z.object({
+  orderId: z.string().describe('Order ID, e.g. ORD-001'),
+  positionName: z.string().describe('Position name of the cabinet, e.g. "Base", "Upper.1"'),
+});
+
+const UpdateOrderOptionsSchema = z.object({
+  orderId: z.string().describe('Order ID to update, e.g. ORD-001'),
+  includeDrawerboxes: z.boolean().optional().describe('Include drawer boxes in the order. Omit to leave unchanged.'),
+  includeAssembly: z.boolean().optional().describe('Include assembly in the order. Omit to leave unchanged.'),
+  includeHardware: z.boolean().optional().describe('Include hardware in the order. Omit to leave unchanged.'),
+  includeFinishing: z.boolean().optional().describe('Include finishing in the order. Omit to leave unchanged.'),
+  finishingType: z.enum(['Matte', 'Satin', 'Primed']).optional().describe('Finishing type. Required when setting includeFinishing to true. Options: Matte, Satin, Primed.'),
+  finishingColor: z.string().optional().describe('Finishing color (e.g. "White", "Black", "Natural"). Required when setting includeFinishing to true.'),
+  specialInstructions: z.string().optional().describe('Special instructions for the order. Pass an empty string to clear.'),
+  notes: z.string().optional().describe('Internal notes for the order. Pass an empty string to clear.'),
+  projectName: z.string().optional().describe('Project name for the order.'),
+  purchaseOrder: z.string().optional().describe('Purchase order number for the order.'),
+});
+
+const ListSavedCartsSchema = z.object({});
+
+const CreateEditCartSchema = z.object({
+  orderId: z.string().describe('Order ID to create edit cart from'),
+});
+
+const SubmitCartAsVersionSchema = z.object({
+  tempOrderId: z.string().describe('Saved cart reference ID — a plain numeric string returned by create_saved_cart or list_saved_carts (e.g. "901787"). Do NOT add any prefix such as "SavedCart_".'),
+  projectName: z.string().optional().describe('Project name for the order (optional, uses saved cart value if not provided)'),
+  purchaseOrder: z.string().optional().describe('Purchase order number (optional, uses saved cart value if not provided)'),
+  includeDrawerboxes: z.boolean().optional().describe('Include drawer boxes in the order'),
+  includeAssembly: z.boolean().optional().describe('Include assembly in the order'),
+  includeHardware: z.boolean().optional().describe('Include hardware in the order'),
+  includeFinishing: z.boolean().optional().describe('Include finishing in the order'),
+  finishingType: z.enum(['Matte', 'Satin', 'Primed']).optional().describe('Finishing type (required if includeFinishing is true). Options: Matte, Satin, Primed'),
+  finishingColor: z.string().optional().describe('Finishing color (required if includeFinishing is true)'),
+  specialInstructions: z.string().optional().describe('Special instructions for the order'),
+  projectAddress: ProjectAddressSchema.optional().describe('Project address (optional, uses saved cart value if not provided)'),
+});
+
+const AddArticlesToCartSchema = z.object({
+  tempOrderId: z.string().describe('Saved cart reference ID — a plain numeric string returned by create_saved_cart or list_saved_carts (e.g. "901787"). Do NOT add any prefix such as "SavedCart_".'),
+  articles: flexArray(ArticleItemSchema).describe('Articles to add to the cart.'),
+});
+
+const GetSavedCartSchema = z.object({
+  tempOrderId: z.string().describe('Saved cart reference ID — a plain numeric string returned by create_saved_cart or list_saved_carts (e.g. "901787"). Do NOT add any prefix such as "SavedCart_".'),
+});
+
+const UpdateArticleItemSchema = z.object({
+  positionName: z.string(),
+  serialNumber: z.string().optional(),
+  height: z.number().optional(),
+  width: z.number().optional(),
+  depth: z.number().optional(),
+  caseMaterial: z.string().optional(),
+  frontMaterial: z.string().optional(),
+  innerCaseMaterial: z.string().optional(),
+  backPanelMaterial: z.string().optional(),
+  caseEdge: z.string().optional(),
+  frontEdge: z.string().optional(),
+  edgeBandingType: z.string().optional(),
+  excludeFronts: z.boolean().optional(),
+  drawerType: z.string().optional(),
+  jointMethod: z.string().optional(),
+  hingePlate: z.string().optional(),
+  backPanel: z.string().optional(),
+  numOfShelves: z.string().optional(),
+  gapTop: z.string().optional(),
+  gapBottom: z.string().optional(),
+  gapLeft: z.string().optional(),
+  gapRight: z.string().optional(),
+  gapCenter: z.string().optional(),
+  topDrwrHeightValue: z.string().optional(),
+  leftCornerWidth: z.number().optional(),
+  rightCornerDepth: z.number().optional(),
+  includeLegLevelers: z.boolean().optional(),
+  // CRITICAL: If updating article to use a saved setting, MUST include settingsName
+  settingsName: z.string().optional().describe(
+    'REQUIRED when using a saved setting preset: The exact name of the saved setting. ' +
+    'Must be set when any configuration values are taken from a saved setting.'
+  ),
+});
+
+const UpdateSavedCartArticlesSchema = z.object({
+  tempOrderId: z.string().describe('Saved cart reference ID — a plain numeric string returned by create_saved_cart or list_saved_carts (e.g. "901787"). Do NOT add any prefix such as "SavedCart_".'),
+  // x, z, rotation omitted — PATCH endpoint updates article configuration only, not CAD coordinates
+  articles: flexArray(UpdateArticleItemSchema).describe('Articles to update. positionName is required to identify each article; all other fields are optional.'),
+});
+
+const DeleteSavedCartArticlesSchema = z.object({
+  tempOrderId: z.string().describe('Saved cart reference ID — a plain numeric string returned by create_saved_cart or list_saved_carts (e.g. "901787"). Do NOT add any prefix such as "SavedCart_".'),
+  positionNames: flexArray(z.string()).describe('Position names of the articles to delete.'),
+});
+
+const CreateOrderSchema = z.object({
+  articles: flexArray(ArticleItemSchema).describe('Line items to order.'),
+  projectName: z.string().describe('Project name for this order'),
+  purchaseOrder: z.string().describe('Purchase order number'),
+  projectAddress: ProjectAddressSchema.optional().describe('Project address (where cabinets will be installed)'),
+  includeDrawerboxes: z.boolean().optional(),
+  includeAssembly: z.boolean().optional(),
+  includeHardware: z.boolean().optional(),
+  includeFinishing: z.boolean().optional(),
+  finishingType: z.enum(['Matte', 'Satin', 'Primed']).optional().describe('Finishing type (required if includeFinishing is true). Options: Matte, Satin, Primed'),
+  finishingColor: z.string().optional().describe('Finishing color (required if includeFinishing is true)'),
+  specialInstructions: z.string().optional(),
+  savedCartId: z.string().optional().describe(
+    'Optional: the tempOrderId of a saved cart whose canvas metadata (background image, scale calibration, ' +
+    'elevation setup) should be copied to the new order. Provide this when the user set up a drawing tool ' +
+    'canvas on a saved cart and wants that calibration carried over to the placed order.'
+  ),
+});
+
+function formatOrderBreakdown(data: any): string {
+  const lines: string[] = [];
+  const info = data.orderInfo ?? {};
+
+  lines.push(`Order Breakdown: ${info.orderId ?? ''}`);
+  lines.push(`Project: ${info.projectName ?? ''} | PO: ${info.purchaseOrder ?? ''}`);
+  lines.push(`Cabinets: ${data.numOfCabinets ?? 0}`);
+
+  const matEntries = Object.entries(data.materialSqft ?? {}) as [string, number][];
+  if (matEntries.length > 0) {
+    lines.push('');
+    lines.push('MATERIALS');
+    for (const [name, sqft] of matEntries) {
+      const sheets = Math.max(1, Math.ceil((sqft / 32) * 1.2));
+      lines.push(`  ${name}: ${sqft.toFixed(2)} sqft (est. ${sheets} sheet${sheets !== 1 ? 's' : ''})`);
+    }
+  }
+
+  const prfEntries = Object.entries(data.prfFt ?? {}) as [string, number][];
+  if (prfEntries.length > 0) {
+    lines.push('');
+    lines.push('EDGEBANDING');
+    for (const [name, footage] of prfEntries) {
+      lines.push(`  ${name}: ${footage.toFixed(2)} ft`);
+    }
+  }
+
+  const hwEntries = Object.entries(data.hardwareQuantity ?? {}) as [string, number][];
+  if (hwEntries.length > 0) {
+    lines.push('');
+    lines.push('HARDWARE');
+    for (const [name, qty] of hwEntries) {
+      lines.push(`  ${name}: ${qty}`);
+    }
+  }
+
+  const drawers: any[] = data.drawers ?? [];
+  if (drawers.length > 0) {
+    lines.push('');
+    lines.push(`DRAWER BOXES (${drawers.length})`);
+    for (const d of drawers) {
+      const parts = [d.pos];
+      if (d.cpId) parts.push(d.cpId);
+      if (d.width != null && d.height != null && d.depth != null) {
+        parts.push(`${d.width}" W × ${d.height}" H × ${d.depth}" D`);
+      }
+      lines.push(`  ${parts.join(' — ')}`);
+    }
+  }
+
+  const spp: any[] = data.spp ?? [];
+  if (spp.length > 0) {
+    lines.push('');
+    lines.push(`STRETCHABLE PARTS (${spp.length})`);
+    for (const s of spp) {
+      lines.push(`  ${s.sppName}: ${s.sppLength} ft`);
+    }
+  }
+
+  const doors: any[] = data.doorDimensions ?? [];
+  if (doors.length > 0) {
+    lines.push('');
+    lines.push(`DOOR PANELS (${doors.length})`);
+    for (const d of doors) {
+      const parts = [d.pos];
+      if (d.name1) parts.push(d.name1);
+      if (d.matId) parts.push(d.matId);
+      if (d.width != null && d.height != null) parts.push(`${d.width}" W × ${d.height}" H`);
+      lines.push(`  ${parts.join(' — ')}`);
+    }
+  }
+
+  const drawerFronts: any[] = data.drawerFronts ?? [];
+  if (drawerFronts.length > 0) {
+    lines.push('');
+    lines.push(`DRAWER FRONTS (${drawerFronts.length})`);
+    for (const d of drawerFronts) {
+      const parts = [d.pos];
+      if (d.matId) parts.push(d.matId);
+      if (d.width != null && d.height != null) parts.push(`${d.width}" W × ${d.height}" H`);
+      lines.push(`  ${parts.join(' — ')}`);
+    }
+  }
+
+  const blindFronts: any[] = data.blindFronts ?? [];
+  if (blindFronts.length > 0) {
+    lines.push('');
+    lines.push(`BLIND FRONTS (${blindFronts.length})`);
+    for (const d of blindFronts) {
+      const parts = [d.pos];
+      if (d.matId) parts.push(d.matId);
+      if (d.width != null && d.height != null) parts.push(`${d.width}" W × ${d.height}" H`);
+      lines.push(`  ${parts.join(' — ')}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+export async function getOrderBreakdown(input: z.infer<typeof GetOrderBreakdownSchema>): Promise<string> {
+  try {
+    const { data } = await client.get(`/orders/${input.orderId}/breakdown`);
+    return formatOrderBreakdown(data);
+  } catch (error) {
+    try { handleAxiosError(error); } catch (e: any) { return e.message; }
+    return 'Unexpected error fetching order breakdown.';
+  }
+}
+
+export async function getPositionBreakdown(input: z.infer<typeof GetPositionBreakdownSchema>): Promise<string> {
+  try {
+    const { data } = await client.get(`/orders/${input.orderId}/position/${input.positionName}/breakdown`);
+    return JSON.stringify(data, null, 2);
+  } catch (error) {
+    try { handleAxiosError(error); } catch (e: any) { return e.message; }
+    return 'Unexpected error fetching position breakdown.';
+  }
+}
+
+export async function createEditCart(input: z.infer<typeof CreateEditCartSchema>): Promise<string> {
+  try {
+    const { data } = await client.post(`/saved-carts/${input.orderId}/create-edit-cart`);
+    const tempOrderId: string = data.tempOrderId ?? 'unknown';
+    const sourceOrderId: string = data.sourceOrderId ?? input.orderId;
+    return `Edit cart created successfully. Reference ID: ${tempOrderId}. Source order: ${sourceOrderId}. Inform the user that they can log in to their Sealab account at thesealab.com and navigate to Saved Carts to review their cabinet configuration before submitting the revised order.`;
+  } catch (error) {
+    try { handleAxiosError(error); } catch (e: any) { return e.message; }
+    return 'Unexpected error creating edit cart.';
+  }
+}
+
+export async function submitCartAsVersion(input: z.infer<typeof SubmitCartAsVersionSchema>): Promise<string> {
+  try {
+    const { data } = await client.post(`/saved-carts/${input.tempOrderId}/submit-as-version`, input);
+    const newOrderId: string = data.newOrderId ?? 'unknown';
+    const versionNumber: number = data.versionNumber ?? 0;
+    return `Order version created successfully. New order ID: ${newOrderId} (version ${versionNumber}). The saved cart has been deleted. Inform the user that they will receive an email notification and must log in to complete payment for the revised order.`;
+  } catch (error) {
+    try { handleAxiosError(error); } catch (e: any) { return e.message; }
+    return 'Unexpected error submitting cart as version.';
+  }
+}
+
+export async function listOrders(input: z.infer<typeof ListOrdersSchema>): Promise<string> {
+  try {
+    const { data } = await client.get('/orders', { params: { limit: input.limit, offset: input.offset } });
+    if (!data || data.length === 0) return 'No orders found.';
+    return JSON.stringify(data, null, 2);
+  } catch (error) {
+    try { handleAxiosError(error); } catch (e: any) { return e.message; }
+    return 'Unexpected error listing orders.';
+  }
+}
+
+export async function getOrder(input: z.infer<typeof GetOrderSchema>): Promise<string> {
+  try {
+    const { data } = await client.get(`/orders/${input.orderId}`);
+    return JSON.stringify(data, null, 2);
+  } catch (error) {
+    try { handleAxiosError(error); } catch (e: any) { return e.message; }
+    return 'Unexpected error fetching order.';
+  }
+}
+
+export async function createOrder(input: z.infer<typeof CreateOrderSchema>): Promise<string> {
+  // Enforce unique positionNames before sending to server
+  const names = input.articles.map((a) => a.positionName);
+  const seen = new Set<string>();
+  const duplicates = names.filter((n) => {
+    if (seen.has(n)) return true;
+    seen.add(n);
+    return false;
+  });
+  if (duplicates.length > 0) {
+    return `Cannot create order: duplicate positionName(s) detected: ${[...new Set(duplicates)].join(', ')}. Each article must have a unique positionName.`;
+  }
+
+  // Step 1: Apply saved setting preset values to articles (user values take precedence)
+  const articlesWithPresets = await applySavedSettingsToArticles(input.articles);
+
+  // Step 2: Apply gap defaults for articles with gapControl = true
+  const articlesWithDefaults = await applyGapDefaultsToArticles(articlesWithPresets);
+  const inputWithDefaults = { ...input, articles: articlesWithDefaults };
+
+  try {
+    const { data } = await client.post('/orders', inputWithDefaults);
+    return `Order created successfully. Order ID: ${data.orderId}`;
+  } catch (error) {
+    try { handleAxiosError(error); } catch (e: any) { return e.message; }
+    return 'Unexpected error creating order.';
+  }
+}
+
+function formatSavedCart(data: any): string {
+  const lines: string[] = [];
+  lines.push(`Saved cart: ${data.tempOrderId}`);
+  lines.push(`Project: ${data.projectName ?? ''} | PO: ${data.purchaseOrder ?? ''}`);
+  lines.push('');
+  lines.push(`Articles (${data.articles?.length ?? 0} total):`);
+
+  for (let i = 0; i < (data.articles?.length ?? 0); i++) {
+    const a = data.articles[i];
+    lines.push(`${i + 1}. ${a.positionName} — ${a.displayName ?? ''} (${a.serialNumber ?? ''})`);
+
+    const sizeParts: string[] = [];
+    if (a.height != null) sizeParts.push(`${a.height}" H`);
+    if (a.width != null) sizeParts.push(`${a.width}" W`);
+    if (a.depth != null) sizeParts.push(`${a.depth}" D`);
+    if (sizeParts.length > 0) lines.push(`   Size: ${sizeParts.join(' × ')}`);
+
+    const matParts: string[] = [];
+    if (a.caseMaterial != null) matParts.push(`Case: ${a.caseMaterial}`);
+    if (a.frontMaterial != null) matParts.push(`Front: ${a.frontMaterial}`);
+    if (a.excludeFronts === true) matParts.push('Exclude Fronts: true');
+    if (matParts.length > 0) lines.push(`   ${matParts.join(' | ')}`);
+
+    const innerParts: string[] = [];
+    if (a.innerCaseMaterial != null) innerParts.push(`Inner Case: ${a.innerCaseMaterial}`);
+    if (a.backPanelMaterial != null) innerParts.push(`Back Panel Material: ${a.backPanelMaterial}`);
+    if (innerParts.length > 0) lines.push(`   ${innerParts.join(' | ')}`);
+
+    const edgeParts: string[] = [];
+    if (a.caseEdge != null) edgeParts.push(`Case Edge: ${a.caseEdge}`);
+    if (a.frontEdge != null) edgeParts.push(`Front Edge: ${a.frontEdge}`);
+    if (a.edgeBandingType != null) edgeParts.push(`Edge Banding: ${a.edgeBandingType}`);
+    if (edgeParts.length > 0) lines.push(`   ${edgeParts.join(' | ')}`);
+
+    const configParts: string[] = [];
+    if (a.drawerType != null) configParts.push(`Drawer Type: ${a.drawerType}`);
+    if (a.jointMethod != null) configParts.push(`Joint Method: ${a.jointMethod}`);
+    if (a.hingePlate != null) configParts.push(`Hinge Plate: ${a.hingePlate}`);
+    if (configParts.length > 0) lines.push(`   ${configParts.join(' | ')}`);
+
+    const panelParts: string[] = [];
+    if (a.backPanel != null) panelParts.push(`Back Panel: ${a.backPanel}`);
+    if (a.numOfShelves != null) panelParts.push(`Shelves: ${a.numOfShelves}`);
+    if (a.includeLegLevelers === true) panelParts.push('Leg Levelers: true');
+    if (panelParts.length > 0) lines.push(`   ${panelParts.join(' | ')}`);
+
+    const gapKeys = ['gapTop', 'gapBottom', 'gapLeft', 'gapRight', 'gapCenter'] as const;
+    const gapLabels: Record<string, string> = { gapTop: 'Top', gapBottom: 'Bottom', gapLeft: 'Left', gapRight: 'Right', gapCenter: 'Center' };
+    const gapParts = gapKeys.filter(k => a[k] != null).map(k => `${gapLabels[k]}: ${a[k]}`);
+    if (gapParts.length > 0) lines.push(`   Gaps — ${gapParts.join(' | ')}`);
+
+    if (a.topDrwrHeightValue != null) lines.push(`   Top Drawer Height: ${a.topDrwrHeightValue}`);
+
+    const cornerParts: string[] = [];
+    if (a.leftCornerWidth != null) cornerParts.push(`Left Width: ${a.leftCornerWidth}`);
+    if (a.rightCornerDepth != null) cornerParts.push(`Right Depth: ${a.rightCornerDepth}`);
+    if (cornerParts.length > 0) lines.push(`   Corner: ${cornerParts.join(' | ')}`);
+
+    if (a.settingsName != null) lines.push(`   Preset: ${a.settingsName}`);
+  }
+
+  return lines.join('\n');
+}
+
+export async function listSavedCarts(_input: z.infer<typeof ListSavedCartsSchema>): Promise<string> {
+  try {
+    const { data } = await client.get('/saved-carts');
+    const carts = data as any[];
+    if (!carts || carts.length === 0) return 'No saved carts found.';
+
+    const lines = carts.map((cart) => {
+      const parts: string[] = [`• ${cart.tempOrderId}`];
+      if (cart.projectName) parts.push(`  Project: ${cart.projectName}`);
+      if (cart.purchaseOrder) parts.push(`  PO: ${cart.purchaseOrder}`);
+      parts.push(`  Articles: ${cart.articleCount}`);
+      if (cart.isEditCart && cart.sourceOrderId) parts.push(`  Edit of order: ${cart.sourceOrderId}`);
+      if (cart.date) parts.push(`  Date: ${cart.date}`);
+      return parts.join('\n');
+    });
+
+    return `Saved carts (${carts.length}):\n\n${lines.join('\n\n')}`;
+  } catch (error) {
+    try { handleAxiosError(error); } catch (e: any) { return e.message; }
+    return 'Unexpected error listing saved carts.';
+  }
+}
+
+export async function getSavedCart(input: z.infer<typeof GetSavedCartSchema>): Promise<string> {
+  try {
+    const { data } = await client.get(`/saved-carts/${input.tempOrderId}`);
+    return formatSavedCart(data);
+  } catch (error) {
+    try { handleAxiosError(error); } catch (e: any) { return e.message; }
+    return 'Unexpected error fetching saved cart.';
+  }
+}
+
+export async function createSavedCart(input: z.infer<typeof CreateOrderSchema>): Promise<string> {
+  // Client-side duplicate positionName guard
+  const names = input.articles.map((a) => a.positionName);
+  const seen = new Set<string>();
+  const duplicates = names.filter((n) => {
+    if (seen.has(n)) return true;
+    seen.add(n);
+    return false;
+  });
+  if (duplicates.length > 0) {
+    return `Cannot create saved cart: duplicate positionName(s) detected: ${[...new Set(duplicates)].join(', ')}. Each article must have a unique positionName.`;
+  }
+
+  // Step 1: Apply saved setting preset values to articles (user values take precedence)
+  const articlesWithPresets = await applySavedSettingsToArticles(input.articles);
+
+  // Step 2: Apply gap defaults for articles with gapControl = true
+  const articlesWithDefaults = await applyGapDefaultsToArticles(articlesWithPresets);
+  const inputWithDefaults = { ...input, articles: articlesWithDefaults };
+
+  try {
+    const { data } = await client.post('/saved-carts', inputWithDefaults);
+    const tempOrderId: string = data.tempOrderId ?? 'unknown';
+    return `Saved cart created successfully. Reference ID: ${tempOrderId}. Please inform the user that they can log in to their Sealab account at thesealab.com and navigate to Saved Carts to review their cabinet configuration before placing the order.`;
+  } catch (error) {
+    try { handleAxiosError(error); } catch (e: any) { return e.message; }
+    return 'Unexpected error creating saved cart.';
+  }
+}
+
+export async function updateSavedCartArticles(input: z.infer<typeof UpdateSavedCartArticlesSchema>): Promise<string> {
+  // Client-side duplicate positionName guard (same pattern as createSavedCart)
+  const names = input.articles.map((a) => a.positionName);
+  const seen = new Set<string>();
+  const duplicates = names.filter((n) => {
+    if (seen.has(n)) return true;
+    seen.add(n);
+    return false;
+  });
+  if (duplicates.length > 0) {
+    return `Cannot update saved cart: duplicate positionName(s) in request: ${[...new Set(duplicates)].join(', ')}. Each article must appear only once per update call.`;
+  }
+
+  // Step 1: Apply saved setting preset values to articles (user values take precedence)
+  const articlesWithPresets = await applySavedSettingsToArticles(input.articles);
+
+  try {
+    const { data } = await client.patch(`/saved-carts/${input.tempOrderId}/articles`, {
+      articles: articlesWithPresets,
+    });
+    return `Updated ${data.updated} article(s) in saved cart ${input.tempOrderId}.`;
+  } catch (error) {
+    try { handleAxiosError(error); } catch (e: any) { return e.message; }
+    return 'Unexpected error updating saved cart articles.';
+  }
+}
+
+export async function addArticlesToCart(input: z.infer<typeof AddArticlesToCartSchema>): Promise<string> {
+  // Client-side duplicate positionName guard
+  const names = input.articles.map((a) => a.positionName);
+  const seen = new Set<string>();
+  const duplicates = names.filter((n) => {
+    if (seen.has(n)) return true;
+    seen.add(n);
+    return false;
+  });
+  if (duplicates.length > 0) {
+    return `Cannot add articles: duplicate positionName(s) in request: ${[...new Set(duplicates)].join(', ')}. Each article must have a unique positionName.`;
+  }
+
+  // Step 1: Apply saved setting preset values to articles (user values take precedence)
+  const articlesWithPresets = await applySavedSettingsToArticles(input.articles);
+
+  // Step 2: Apply gap defaults for articles with gapControl = true
+  const articlesWithDefaults = await applyGapDefaultsToArticles(articlesWithPresets);
+
+  try {
+    const { data } = await client.post(`/saved-carts/${input.tempOrderId}/articles`, { articles: articlesWithDefaults });
+    return `Added ${data.added} article(s) to saved cart ${input.tempOrderId}. Total cart ID: ${data.tempOrderId}`;
+  } catch (error) {
+    try { handleAxiosError(error); } catch (e: any) { return e.message; }
+    return 'Unexpected error adding articles to saved cart.';
+  }
+}
+
+export async function deleteSavedCartArticles(input: z.infer<typeof DeleteSavedCartArticlesSchema>): Promise<string> {
+  try {
+    const { data } = await client.delete(`/saved-carts/${input.tempOrderId}/articles`, {
+      data: { positionNames: input.positionNames },
+    });
+    return `Deleted ${data.deleted} article(s) from saved cart ${input.tempOrderId}: [${input.positionNames.join(', ')}].`;
+  } catch (error) {
+    try { handleAxiosError(error); } catch (e: any) { return e.message; }
+    return 'Unexpected error deleting saved cart articles.';
+  }
+}
+
+export async function updateOrderOptions(input: z.infer<typeof UpdateOrderOptionsSchema>): Promise<string> {
+  const { orderId, ...fields } = input;
+  // Only send keys the caller explicitly provided (strip undefined values)
+  const payload: Record<string, unknown> = {};
+  for (const [key, val] of Object.entries(fields)) {
+    if (val !== undefined) payload[key] = val;
+  }
+  if (Object.keys(payload).length === 0) {
+    return 'No options provided. Supply at least one of: includeDrawerboxes, includeAssembly, includeHardware, includeFinishing, finishingType, finishingColor.';
+  }
+  try {
+    const { data } = await client.patch(`/orders/${orderId}/options`, payload);
+    return JSON.stringify(data, null, 2);
+  } catch (error) {
+    try { handleAxiosError(error); } catch (e: any) { return e.message; }
+    return 'Unexpected error updating order options.';
+  }
+}
+
+export const orderTools = [
+  {
+    name: 'list_orders',
+    description: 'List orders on this account. Supports pagination via limit (default 20, max 100) and offset.',
+    inputSchema: ListOrdersSchema,
+    handler: listOrders,
+  },
+  {
+    name: 'get_order',
+    description: `Get full details and current status for a specific order by its order ID.
+
+Returns order information including:
+- orderId, status, date, price, projectName, purchaseOrder
+- articles: Array of cabinet articles, each with:
+  - positionName: UNIQUE identifier for the cabinet (e.g., "Base", "Upper.1", "SouthU_009") — USE THIS to identify cabinets
+  - serialNumber: Cabinet type/model number (e.g., "BC_O_1048")
+  - quantity, height, width, depth
+
+IMPORTANT: When referencing a specific cabinet in an order, ALWAYS use positionName (not serialNumber), as multiple cabinets can have the same serialNumber but different positionNames.`,
+    inputSchema: GetOrderSchema,
+    handler: getOrder,
+  },
+  {
+    name: 'get_order_breakdown',
+    description: 'Get the full Bill of Materials (BOM) breakdown for a placed order. Returns aggregated materials with square footage and estimated sheet counts, edgebanding footage, hardware quantities, drawer boxes with dimensions, drawer fronts, door panels, blind fronts, and stretchable purchased parts. Call this after get_order when the user needs component-level detail for an order.',
+    inputSchema: GetOrderBreakdownSchema,
+    handler: getOrderBreakdown,
+  },
+  {
+    name: 'get_position_breakdown',
+    description: 'Get detailed breakdown for a single cabinet position within an order. Returns materials (sqft), edgebanding, hardware, and drawer boxes for the specified positionName. Use this when the user asks about a specific cabinet\'s construction, materials, or components.',
+    inputSchema: GetPositionBreakdownSchema,
+    handler: getPositionBreakdown,
+  },
+  {
+    name: 'update_order_options',
+    description: `Update order-level options on a placed order WITHOUT creating a new version or going through the cart/edit workflow. Changes are persisted immediately and broadcast to the frontend in real time.
+
+Use this tool when the user wants to:
+- Add or remove an add-on service: "Add drawer boxes to order ORD-123", "Remove hardware from my order"
+- Enable finishing: "Enable finishing on order ORD-456, Matte, White"
+- Update special instructions: "Change the special instructions on ORD-123 to 'deliver to back entrance'"
+- Update notes: "Add a note to order ORD-456"
+- Rename the project: "Change the project name on ORD-123 to 'Smith Kitchen'"
+- Update the PO number: "Set purchase order to PO-9981 on ORD-456"
+
+Only the fields you pass are updated. Omitted fields are left exactly as they are on the order.
+
+If includeFinishing is being set to true, you MUST also provide finishingType and finishingColor.
+
+Returns the full updated state of all options after the change.`,
+    inputSchema: UpdateOrderOptionsSchema,
+    handler: updateOrderOptions,
+  },
+  {
+    name: 'create_edit_cart',
+    description: `Create a saved cart from an EXISTING order for editing. Use this tool when the user wants to edit or revise a previously placed order.
+
+⚠️ USE THIS TOOL when:
+- User says "edit order 429308" or "revise order ORD-123"
+- User wants to modify cabinets in an existing order
+- You have an existing order ID to work with
+
+DO NOT use this tool when:
+- User is creating a BRAND NEW order (use create_saved_cart instead)
+- There is no existing order ID
+
+This tool:
+1. Creates a saved cart with ALL articles from the source order
+2. Sets the sourceOrderId and isEditCart flags (required for versioned submission)
+3. Returns a tempOrderId for the edit cart
+
+After calling this tool:
+- The user can review the cart at thesealab.com in Saved Carts
+- Use update_saved_cart_articles to modify cabinet configurations
+- Use submit_cart_as_version to create a versioned order (ORDER123_v2)
+
+The saved cart preserves all order settings (project name, PO, special instructions) from the source order.`,
+    inputSchema: CreateEditCartSchema,
+    handler: createEditCart,
+  },
+  {
+    name: 'submit_cart_as_version',
+    description: `Submit a saved cart as a VERSIONED ORDER (revision of an existing order). This creates a new version like ORDER123_v2.
+
+⚠️ USE THIS TOOL ONLY WHEN EDITING AN EXISTING ORDER ⚠️
+
+This tool:
+1. Creates a new VERSION of an existing order (e.g., ORDER123_v2)
+2. Copies canvas data, coordinates, and permissions from the source order
+3. Applies the modified articles from the saved cart
+4. Deletes the saved cart after successful submission
+
+Use submit_cart_as_version ONLY when:
+- User explicitly says "edit order XXX" or "revise order XXX"
+- The saved cart was created using create_edit_cart (which sets sourceOrderId)
+- You are submitting changes to a previously placed order
+
+DO NOT use this tool for:
+- New orders (use create_order instead)
+- Saved carts created via create_saved_cart (use create_order instead)
+
+BEFORE calling this tool, you MUST explicitly ask the user to confirm ALL of the following:
+- includeDrawerboxes: should drawer boxes be included? (true or false)
+- includeAssembly: should assembly be included? (true or false)
+- includeHardware: should hardware be included? (true or false)
+- includeFinishing: should finishing be included? (true or false)
+  - If includeFinishing is true, you MUST also ask:
+    - finishingType: select from Matte, Satin, or Primed
+    - finishingColor: the desired color name (e.g., "White", "Black", "Natural")
+- specialInstructions: any special notes or instructions? (optional)
+- projectAddress: project address where cabinets will be installed (optional)
+  - projectAddress1, projectAddress2, projectCity, projectState, projectZipcode
+
+After submission:
+- The user will receive an email notification
+- Payment must be completed by the user via the web portal
+- The saved cart is deleted`,
+    inputSchema: SubmitCartAsVersionSchema,
+    handler: submitCartAsVersion,
+  },
+  {
+    name: 'create_order',
+    description: `Place a NEW cabinet order. Use this tool when the user wants to submit a brand new order (not an edit/revision of an existing order).
+
+This tool creates a completely new order with a new order ID.
+
+Use create_order when:
+- User is placing a first-time order
+- User has a saved cart created via create_saved_cart (not create_edit_cart)
+- User says "submit my order" or "place the order" for a new order
+
+DO NOT use this tool when editing an existing order — use submit_cart_as_version instead.
+
+BEFORE calling this tool, you MUST explicitly ask the user to confirm ALL of the following — do not assume or skip any:
+
+ORDER-LEVEL (ask once for the whole order):
+- projectName: the name for this project/order
+- purchaseOrder: their PO or reference number
+- includeDrawerboxes: should drawer boxes be included? (true or false)
+- includeAssembly: should assembly be included? (true or false)
+- includeHardware: should hardware be included? (true or false)
+- includeFinishing: should finishing be included? (true or false)
+  - If includeFinishing is true, you MUST also ask:
+    - finishingType: select from Matte, Satin, or Primed
+    - finishingColor: the desired color name (e.g., "White", "Black", "Natural")
+- specialInstructions: any special notes or instructions? (optional — ask if they have any)
+- projectAddress: project address where cabinets will be installed (optional)
+  - projectAddress1, projectAddress2, projectCity, projectState, projectZipcode
+
+ARTICLE-LEVEL (must be confirmed per article, or as a shared spec across articles):
+- All applicable configuration fields: materials, edgebanding, joint method, drawer type, hinge plate, back panel, shelves, gaps, leg levelers, etc.
+- positionName for each article (unique, derived from cabinet type/location)
+- x, y, z, rotation: if an architectural drawing is provided, derive from the layout.
+    Pass back-edge X and back-edge Y directly — server stores as-is, no conversion applied.
+    x (back-edge X, decimal inches):
+      North/South wall (rotation=0/180):
+        x = D_adj_west + (sum of widths of all cabinets to the left on that wall + any filler) + width/2.
+        D_adj_west = depth of west-wall cabinets if west wall cabinets exist in this layout, else 0.
+        CORNER CLEARANCE: north/south wall cabinets must start at x=D_adj_west, NOT x=0.
+        D_adj_west applies ONLY here — it does NOT affect east/west wall cabinet x.
+        Similarly, the rightmost north/south cabinet must end no further right than x = room_width - D_adj_east.
+      West wall (rotation=270): back-edge coordinate (distance from west wall to cabinet BACK).
+        Base cabinet: x = 0 (back edge against west wall).
+        Shallower cabinet (e.g. upper) front-flush with base: x = base_depth - upper_depth.
+        Example: 24" base + 15" upper → x = 24 - 15 = 9".
+        Verification: base front at 0+24=24", upper front at 9+15=24" ✅ MATCH.
+      East wall (rotation=90): back-edge coordinate (distance from west wall to cabinet BACK).
+        Base cabinet: x = room_width (back edge against east wall). Requires room_width from drawing.
+        Shallower cabinet front-flush: x = base_x - (base_depth - upper_depth).
+        Example: base x=120 (24" deep) + 15" upper → upper x = 120 - 9 = 111".
+        Verification: base front at 120-24=96", upper front at 111-15=96" ✅ MATCH.
+        CRITICAL: Upper x = base_x - (base_depth - upper_depth). Just offset from base — no room dimension math.
+        IF room_width IS UNKNOWN: ask the user for room dimensions from the drawing to set base x.
+    y (back-edge Y, decimal inches) — ABSOLUTE room coordinate (0 = south wall face, room_depth = north wall face).
+      CRITICAL: Y is the BACK-EDGE coordinate (distance from south wall face to cabinet BACK), NOT center.
+      North wall and all east/west y values require room_depth — ask the user if unknown.
+      South wall (rotation=180):
+        Base cabinet: y = 0 (back edge against wall).
+        Shallower cabinet (e.g. upper) front-flush with base: y = base_depth - upper_depth.
+        Example: 24" base + 15" upper front-flush → upper y = 24 - 15 = 9".
+        BASE cabinet y is NEVER modified. Only the shallower cabinet y shifts north (away from wall).
+      North wall (rotation=0):
+        Base cabinet: y = room_depth (back edge against north wall).
+        Shallower cabinet front-flush: y = base_y - (base_depth - upper_depth).
+        Example: base y=120 (24" deep) + 15" upper → upper y = 120 - 9 = 111".
+        Verification: base front at 120-24=96", upper front at 111-15=96" ✅ MATCH.
+        CRITICAL: Upper y = base_y - (base_depth - upper_depth). Just offset from base — no room dimension math.
+      East wall (rotation=90):
+        "Width" = this cabinet's own width dimension, running north-south after 90° rotation.
+        East/west wall cabinets run from the north wall SOUTHWARD (decreasing y). List them north-to-south.
+        D_adj_north = the catalog DEPTH of the north-wall BASE cabinet (the "depth" used in north wall y = room_depth).
+          Example: north wall has 24"-deep bases → D_adj_north = 24.
+          NEVER set D_adj_north = 0 when north wall cabinets exist — that places east/west cabinet inside the north wall footprint.
+        Northernmost cabinet (1st in list): y = room_depth - D_adj_north - width/2.
+        Each next cabinet going south: y = room_depth - D_adj_north - (sum of widths of preceding cabinets) - width/2.
+        y DECREASES with each cabinet going south. NEVER add widths — adding goes north (wrong direction).
+        IF room_depth IS UNKNOWN: ask the user for room dimensions before computing east/west wall y.
+        UPPER cabinets: DO NOT compute y — copy the base cabinet y value exactly. No formula. No D_adj_north.
+        Do NOT apply north/south front-flush y formulas to east/west wall cabinets.
+      West wall (rotation=270):  y = same formula as east wall.
+    z = height from floor in inches. 0 for base cabinets on the floor. Stacked units: sum heights of all cabinets below.
+    rotation: 0 = north wall, 90 = east wall, 180 = south wall, 270 = west wall.
+              If no compass rose, assume top = north, bottom = south, left = west, right = east.
+  If no drawing is provided, omit coordinates (cabinets placed in fallback row in CAD file).
+
+Only call this tool once ALL of the above have been explicitly confirmed by the user. Never auto-fill, assume, or default any of these fields.`,
+    inputSchema: CreateOrderSchema,
+    handler: createOrder,
+  },
+  {
+    name: 'create_saved_cart',
+    description: `Save a NEW cabinet configuration as a saved cart for the user to review before committing to an order.
+
+⚠️ For NEW orders ONLY — DO NOT use when editing an existing order ⚠️
+
+Use create_saved_cart ONLY when:
+- User is creating a BRAND NEW order from scratch
+- User is configuring cabinets for the first time
+- There is NO existing order ID to edit
+
+Use create_edit_cart when:
+- User says "edit order 429308" or "revise order ORD-123"
+- User wants to modify a previously placed order
+- You have an existing order ID to work with
+
+BEFORE calling this tool, you MUST explicitly ask the user to confirm ALL of the following — do not assume or skip any:
+
+ORDER-LEVEL (ask once for the whole order):
+- projectName: the name for this project/order
+- purchaseOrder: their PO or reference number
+- includeDrawerboxes: should drawer boxes be included? (true or false)
+- includeAssembly: should assembly be included? (true or false)
+- includeHardware: should hardware be included? (true or false)
+- includeFinishing: should finishing be included? (true or false)
+- specialInstructions: any special notes or instructions? (optional — ask if they have any)
+- projectAddress: project address where cabinets will be installed (optional)
+  - projectAddress1, projectAddress2, projectCity, projectState, projectZipcode
+
+ARTICLE-LEVEL (must be confirmed per article, or as a shared spec across articles):
+- All applicable configuration fields: materials, edgebanding, joint method, drawer type, hinge plate, back panel, shelves, gaps, leg levelers, etc.
+- positionName for each article (unique, derived from cabinet type/location)
+- x, y, z, rotation: if an architectural drawing is provided, derive from the layout.
+    Pass back-edge X and back-edge Y directly — server stores as-is, no conversion applied.
+    x (back-edge X, decimal inches):
+      North/South wall (rotation=0/180):
+        x = D_adj_west + (sum of widths of all cabinets to the left on that wall + any filler) + width/2.
+        D_adj_west = depth of west-wall cabinets if west wall cabinets exist in this layout, else 0.
+        CORNER CLEARANCE: north/south wall cabinets must start at x=D_adj_west, NOT x=0.
+        D_adj_west applies ONLY here — it does NOT affect east/west wall cabinet x.
+        Similarly, the rightmost north/south cabinet must end no further right than x = room_width - D_adj_east.
+      West wall (rotation=270): back-edge coordinate (distance from west wall to cabinet BACK).
+        Base cabinet: x = 0 (back edge against west wall).
+        Shallower cabinet (e.g. upper) front-flush with base: x = base_depth - upper_depth.
+        Example: 24" base + 15" upper → x = 24 - 15 = 9".
+        Verification: base front at 0+24=24", upper front at 9+15=24" ✅ MATCH.
+      East wall (rotation=90): back-edge coordinate (distance from west wall to cabinet BACK).
+        Base cabinet: x = room_width (back edge against east wall). Requires room_width from drawing.
+        Shallower cabinet front-flush: x = base_x - (base_depth - upper_depth).
+        Example: base x=120 (24" deep) + 15" upper → upper x = 120 - 9 = 111".
+        Verification: base front at 120-24=96", upper front at 111-15=96" ✅ MATCH.
+        CRITICAL: Upper x = base_x - (base_depth - upper_depth). Just offset from base — no room dimension math.
+        IF room_width IS UNKNOWN: ask the user for room dimensions from the drawing to set base x.
+    y (back-edge Y, decimal inches) — ABSOLUTE room coordinate (0 = south wall face, room_depth = north wall face).
+      CRITICAL: Y is the BACK-EDGE coordinate (distance from south wall face to cabinet BACK), NOT center.
+      North wall and all east/west y values require room_depth — ask the user if unknown.
+      South wall (rotation=180):
+        Base cabinet: y = 0 (back edge against wall).
+        Shallower cabinet (e.g. upper) front-flush with base: y = base_depth - upper_depth.
+        Example: 24" base + 15" upper front-flush → upper y = 24 - 15 = 9".
+        BASE cabinet y is NEVER modified. Only the shallower cabinet y shifts north (away from wall).
+      North wall (rotation=0):
+        Base cabinet: y = room_depth (back edge against north wall).
+        Shallower cabinet front-flush: y = base_y - (base_depth - upper_depth).
+        Example: base y=120 (24" deep) + 15" upper → upper y = 120 - 9 = 111".
+        Verification: base front at 120-24=96", upper front at 111-15=96" ✅ MATCH.
+        CRITICAL: Upper y = base_y - (base_depth - upper_depth). Just offset from base — no room dimension math.
+      East wall (rotation=90):
+        "Width" = this cabinet's own width dimension, running north-south after 90° rotation.
+        East/west wall cabinets run from the north wall SOUTHWARD (decreasing y). List them north-to-south.
+        D_adj_north = the catalog DEPTH of the north-wall BASE cabinet (the "depth" used in north wall y = room_depth).
+          Example: north wall has 24"-deep bases → D_adj_north = 24.
+          NEVER set D_adj_north = 0 when north wall cabinets exist — that places east/west cabinet inside the north wall footprint.
+        Northernmost cabinet (1st in list): y = room_depth - D_adj_north - width/2.
+        Each next cabinet going south: y = room_depth - D_adj_north - (sum of widths of preceding cabinets) - width/2.
+        y DECREASES with each cabinet going south. NEVER add widths — adding goes north (wrong direction).
+        IF room_depth IS UNKNOWN: ask the user for room dimensions before computing east/west wall y.
+        UPPER cabinets: DO NOT compute y — copy the base cabinet y value exactly. No formula. No D_adj_north.
+        Do NOT apply north/south front-flush y formulas to east/west wall cabinets.
+      West wall (rotation=270):  y = same formula as east wall.
+    z = height from floor in inches. 0 for base cabinets on the floor. Stacked units: sum heights of all cabinets below.
+    rotation: 0 = north wall, 90 = east wall, 180 = south wall, 270 = west wall.
+              If no compass rose, assume top = north, bottom = south, left = west, right = east.
+  If no drawing is provided, omit coordinates (cabinets placed in fallback row in CAD file).
+
+Only call this tool once ALL of the above have been explicitly confirmed by the user. Never auto-fill, assume, or default any of these fields.
+
+After the cart is created, inform the user of the Reference ID and direct them to log in at thesealab.com and navigate to Saved Carts to review their configuration before placing the order.`,
+    inputSchema: CreateOrderSchema,
+    handler: createSavedCart,
+  },
+  {
+    name: 'list_saved_carts',
+    description: `List all saved carts for the authenticated user. Returns a summary of each cart: tempOrderId, project name, purchase order, article count, date, and whether it is an edit cart (revision of an existing order).
+
+Use this tool when:
+- The user asks "what saved carts do I have?" or "show my saved carts"
+- You need to find a tempOrderId before calling get_saved_cart, update_saved_cart_articles, or submit_cart_as_version
+- You want to confirm whether a cart already exists before creating a new one`,
+    inputSchema: ListSavedCartsSchema,
+    handler: listSavedCarts,
+  },
+  {
+    name: 'get_saved_cart',
+    description: `Read the current state of a saved cart including all articles and their configurations.
+Use this tool before making any edits to a saved cart — the user may have updated
+the cart directly in the Sealab web portal since it was created.`,
+    inputSchema: GetSavedCartSchema,
+    handler: getSavedCart,
+  },
+  {
+    name: 'update_saved_cart_articles',
+    description: `Update the configuration of one or more articles in a saved cart. Only send the fields that have changed — positionName is required to identify each article, all other fields are optional. You can also change the cabinet type by patching serialNumber. Call get_saved_cart first to read current state before making edits.`,
+    inputSchema: UpdateSavedCartArticlesSchema,
+    handler: updateSavedCartArticles,
+  },
+  {
+    name: 'add_articles_to_cart',
+    description: `Add NEW articles to an existing saved cart. Use this when the user wants to add more cabinets to a saved cart without recreating it.
+
+This tool:
+- Validates that new article positionNames don't conflict with existing articles
+- Enriches articles with catalog data (same as create_saved_cart)
+- Returns the number of articles added
+
+Use add_articles_to_cart when:
+- User has an existing saved cart and wants to add more items
+- User says "add another cabinet to my cart" or "add this to my saved cart"
+
+DO NOT use this tool to:
+- Modify existing articles (use update_saved_cart_articles instead)
+- Create a new saved cart (use create_saved_cart instead)`,
+    inputSchema: AddArticlesToCartSchema,
+    handler: addArticlesToCart,
+  },
+  {
+    name: 'delete_saved_cart_articles',
+    description: `Remove one or more articles from a saved cart by positionName. Use this when the user wants to remove an article entirely. To replace an article with a different cabinet type, use update_saved_cart_articles with the new serialNumber instead of deleting and re-adding.`,
+    inputSchema: DeleteSavedCartArticlesSchema,
+    handler: deleteSavedCartArticles,
+  },
+];