@sealab/mcp-server 1.0.0

package/SEALAB_MCP_DOCUMENTATION.md

@@ -0,0 +1,1136 @@
+# Sealab MCP Server — Full Documentation
+
+## Overview
+
+The Sealab MCP Server is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes the Sealab cabinetry platform to AI assistants. It allows an AI agent to browse the Sealab cabinet catalog, configure individual articles, build orders or saved carts, manage saved configuration presets, and interact with the drawing tool canvas (cabinet placement coordinates, background images, and calibration metadata).
+
+The server runs as a long-lived Node.js process and communicates with MCP clients over **stdio** (standard input/output). All cabinet data is fetched from the live Sealab REST API at `https://thesealab.com/api/mcp/v1`.
+
+---
+
+## Architecture
+
+```
+MCP Client (e.g. Claude Code)
+        │  stdio (JSON-RPC)
+        ▼
+  src/index.ts          ← MCP server entry point
+        │
+        ├── src/tools/catalog.ts
+        ├── src/tools/configuration.ts
+        ├── src/tools/configuration-info.ts
+        ├── src/tools/orders.ts
+        ├── src/tools/saved-settings.ts
+        └── src/tools/canvas.ts
+                │
+                ▼
+        src/client/api-client.ts   ← Axios HTTP client
+                │
+                ▼
+        https://thesealab.com/api/mcp/v1
+```
+
+### Tech Stack
+
+| Component | Technology |
+|---|---|
+| Language | TypeScript 5.3+ |
+| Runtime | Node.js ≥ 18 |
+| MCP SDK | `@modelcontextprotocol/sdk` v1.x |
+| HTTP client | Axios 1.6+ |
+| Schema/validation | Zod 3.22+ |
+| Schema → JSON Schema | `zod-to-json-schema` |
+| File uploads | `form-data` |
+| Build | TypeScript compiler (`tsc`) |
+| Tests | Vitest |
+
+### Entry Point (`src/index.ts`)
+
+Instantiates an MCP `Server` named `sealab` (version `1.0.0`) with `tools` capability. Registers two request handlers:
+- `ListToolsRequestSchema` — returns all tool names, descriptions, and JSON Schemas (converted from Zod schemas via `zodToJsonSchema`)
+- `CallToolRequestSchema` — finds the matching tool, validates input with Zod `safeParse`, calls the handler, and returns the result as a text content block
+
+All tool results are returned as plain text strings. Errors are returned as text (not thrown), so the MCP client always receives a readable message.
+
+---
+
+## Authentication & Configuration
+
+### Environment Variables
+
+| Variable | Required | Default | Purpose |
+|---|---|---|---|
+| `SEALAB_API_KEY` | **Yes** | — | API key sent as `X-API-Key` header on every request. Server throws on startup if missing. |
+| `SEALAB_API_URL` | No | `https://thesealab.com` | Base URL for the Sealab API. Can be overridden for local/staging environments. |
+
+All API requests target `{SEALAB_API_URL}/api/mcp/v1` with a `10,000 ms` timeout.
+
+### Error Handling (`src/client/api-client.ts`)
+
+`handleAxiosError` maps HTTP status codes to typed `McpApiError` instances:
+- `401` → `"Invalid API key"`
+- `404` → message from API response body
+- `422` → message from API response body
+- Other → `"API error: {message}"`
+- Network failure → `"Unable to reach Sealab API — check SEALAB_API_URL"`
+
+---
+
+## Tools Reference
+
+The server exposes **35 tools** across 6 modules.
+
+---
+
+### Module 1: Catalog (`src/tools/catalog.ts`)
+
+Tools for browsing and retrieving cabinet articles from the Sealab catalog.
+
+---
+
+#### `search_catalog`
+
+Search the Sealab cabinetry catalog by keyword, filter tags, and/or dimension ranges.
+
+**Input parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `q` | string | No | Keyword search query |
+| `tags` | string[] | No | Filter by tag (e.g. `BASE`, `WALL`, `PANTRY`, `TALL`) |
+| `minH` | number | No | Minimum height in inches |
+| `maxH` | number | No | Maximum height in inches |
+| `minW` | number | No | Minimum width in inches |
+| `maxW` | number | No | Maximum width in inches |
+| `minD` | number | No | Minimum depth in inches |
+| `maxD` | number | No | Maximum depth in inches |
+
+**API call:** `GET /catalog/search?q=...&tags=BASE&tags=WALL&minH=...`
+
+Tags are serialized without array brackets (`tags=BASE&tags=WALL`, not `tags[]=`).
+
+**Returns:** JSON array of matching articles, or `"No articles found matching your search."` if empty.
+
+---
+
+#### `get_article`
+
+Get full details for a single cabinet article by its serial number.
+
+**Input parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `serialNumber` | string | Yes | Article serial number (e.g. `B30`) |
+
+**API call:** `GET /catalog/{serialNumber}`
+
+**Returns:** JSON object with full article details.
+
+---
+
+#### `list_filter_tags`
+
+List all available filter tag categories in the catalog.
+
+**Input parameters:** None
+
+**API call:** `GET /catalog/filter-tags`
+
+**Returns:** Newline-separated list of tags (e.g. `BASE`, `WALL`, `PANTRY`, `TALL`, `Leg_Levelers`, etc.).
+
+---
+
+### Module 2: Configuration (`src/tools/configuration.ts`)
+
+Low-level access to raw article configuration flags.
+
+---
+
+#### `get_article_configuration`
+
+Get the raw feature flags and dimension ranges for a cabinet article. Returns boolean flags such as `hasCase`, `hasFront`, `doors`, `drawers`, `adjShelves`, `gapControl`, `jointControl`, `cornerVariables`, etc., along with `heightRange`, `widthRange`, `depthRange`.
+
+**When to use:** Only when you need raw boolean flags without guidance text. For guided configuration, use `get_article_context` instead.
+
+**Input parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `serialNumber` | string | Yes | Article serial number |
+
+**API call:** `GET /catalog/{serialNumber}/configuration`
+
+**Returns:** JSON object of feature flags and dimension ranges.
+
+---
+
+### Module 3: Configuration Info (`src/tools/configuration-info.ts`)
+
+Higher-level tools for guided article configuration. These are the primary tools used in the ordering workflow.
+
+**Applicable configuration fields** (derived from feature flags):
+
+| Field | Triggered by flag |
+|---|---|
+| `positionName`, `height`, `width`, `depth` | Always included |
+| `caseMaterial` | `hasCase = true` or `hasMatCaseThin = true` |
+| `frontMaterial` | `hasFront = true` |
+| `excludeFronts` | `hasCase = true` AND `hasFront = true` |
+| `backPanelMaterial`, `backPanel` | `matBack = true` |
+| `caseEdge` | `caseEdge = true` |
+| `frontEdge` | `frontEdge = true` |
+| `hingePlate` | `doors = true` |
+| `drawerType` | `drawers = true` |
+| `topDrwrHeight` | `topDrwrHeight = true` |
+| `numOfShelves` | `adjShelves = true` |
+| `gapTop`, `gapBottom`, `gapLeft`, `gapRight`, `gapCenter` | `gapControl = true` |
+| `jointMethod` | `jointControl = true` |
+| `leftCornerWidth`, `rightCornerDepth` | `cornerVariables = true` |
+| `edgeBandingType` | Serial number starts with `LP_SP` or `LP_GP` |
+| `includeLegLevelers` | `filterTags` contains `"Leg_Levelers"` |
+
+---
+
+#### `get_article_context`
+
+Load all configuration context for a cabinet article in a single call. Fetches the configuration, determines which fields apply to this specific article, and returns dimension ranges plus the full guidance text for each applicable field (read from `.txt` tooltip files on disk).
+
+**Input parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `serialNumber` | string | Yes | Article serial number |
+
+**API call:** `GET /catalog/{serialNumber}/configuration`
+
+**Returns:** Plain-text block containing:
+- Dimension ranges (height / width / depth)
+- All applicable configuration fields with their guidance descriptions
+- Embedded instructions directing the AI to present options to the user, ask for explicit choices, and NOT auto-select or assume values
+
+**Intended workflow:**
+1. Call `get_article_context` immediately when a user selects an article
+2. Call `get_article_options` to get valid option values
+3. Present both to the user, ask for all choices explicitly
+4. Only proceed to create order/cart once all fields are confirmed
+
+---
+
+#### `get_article_options`
+
+Fetch the valid selectable values for all applicable configuration fields for a cabinet article.
+
+**Input parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `serialNumber` | string | Yes | Article serial number |
+
+**API call:** `GET /catalog/{serialNumber}/options`
+
+**Returns:** Plain-text block organized by option group:
+- `MATERIALS` — valid strings for `caseMaterial`, `frontMaterial`, `backPanelMaterial`, `innerCaseMaterial`
+- `EDGEBANDING` — valid strings for `caseEdge`, `frontEdge`
+- `JOINT METHOD` — valid strings for `jointMethod`
+- `DRAWER TYPE` — valid strings for `drawerType`
+- `HINGE PLATE` — valid strings for `hingePlate`
+- `BACK PANEL METHOD` — valid strings for `backPanel`
+- `NUMBER OF ADJUSTABLE SHELVES` — valid strings for `numOfShelves`
+
+Only fields applicable to the article are included. Values returned are the **exact strings** the order system expects.
+
+---
+
+#### `get_configuration_info`
+
+Get full guidance text for a single configuration field. Reads and strips HTML from the corresponding `.txt` file in `resources/tooltips/`.
+
+**Input parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `field` | enum | Yes | One of the 25 valid field names (see list below) |
+
+**Valid field names:** `backPanel`, `backPanelMaterial`, `caseEdge`, `caseMaterial`, `depth`, `drawerType`, `edgeBandingType`, `excludeFronts`, `frontEdge`, `frontMaterial`, `gapBottom`, `gapCenter`, `gapLeft`, `gapRight`, `gapTop`, `height`, `hingePlate`, `includeLegLevelers`, `jointMethod`, `leftCornerWidth`, `numOfShelves`, `positionName`, `rightCornerDepth`, `topDrwrHeight`, `width`
+
+**Returns:** Plain-text guidance for the specified field. Use only when the user explicitly asks for more detail about a specific option.
+
+---
+
+### Module 4: Orders (`src/tools/orders.ts`)
+
+The largest and most complex module. Handles order creation, saved carts, order revisions, and BOM reporting.
+
+---
+
+#### Article Item Schema
+
+Every article in an order or cart uses the following fields. All string values for materials, edgebanding, joint method, etc. must be the exact strings returned by `get_article_options`.
+
+**Identification and dimensions:**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `serialNumber` | string | Yes | Article serial number (cabinet type) |
+| `positionName` | string | Yes | Unique label within the order. Max 25 chars, no dashes (underscores OK). For qty > 1, must include `_01` suffix — server increments it per unit (e.g. `DR_B2_01` qty=3 → `DR_B2_01`, `DR_B2_02`, `DR_B2_03`). |
+| `quantity` | integer ≥ 1 | Yes | Number of this cabinet to order |
+| `height` | number | Yes | Height in inches |
+| `width` | number | Yes | Width in inches |
+| `depth` | number | Yes | Depth in inches |
+
+**Materials:**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `caseMaterial` | string | Conditional | Case/box material. Exact string from `get_article_options`. |
+| `frontMaterial` | string | Conditional | Door/drawer front material. Omit when `excludeFronts` is true. |
+| `innerCaseMaterial` | string | Conditional | Inner case material. Only for articles with `hasMatCaseThin = true`. |
+| `backPanelMaterial` | string | Conditional | Back panel material. |
+
+**Edgebanding:**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `caseEdge` | string | Conditional | Case edgebanding. Standard articles only. |
+| `frontEdge` | string | Conditional | Front edgebanding. Standard articles only. |
+| `edgeBandingType` | string | Conditional | Edgebanding for LP_SP/LP_GP series only. Applied to all four edge positions. |
+
+**Configuration options:**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `drawerType` | string | Conditional | Drawer box construction type. |
+| `jointMethod` | string | Conditional | Case joinery method. |
+| `hingePlate` | string | Conditional | Hinge plate type. |
+| `backPanel` | string | Conditional | Back panel attachment method. |
+| `numOfShelves` | string | Conditional | Number of adjustable shelves (e.g. `"3"`, `"0"`, `"Parametric Shelves"`). |
+
+**Gap control** (only for articles with `gapControl = true`):
+
+| Field | Type | Valid Values |
+|---|---|---|
+| `gapTop` | string | `"0"` (flush), `"0.0625"` (1/16"), `"0.125"` (1/8") |
+| `gapBottom` | string | same |
+| `gapLeft` | string | same |
+| `gapRight` | string | same |
+| `gapCenter` | string | same (gap between adjacent doors/drawers) |
+
+**Gap default behavior:** If an article has `gapControl = true` and any gap field is omitted, the server client-side auto-applies `"0.125"` (1/8") as a default. This is done by fetching the article configuration and filling in missing gap fields before submitting to the API.
+
+**Other options:**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `topDrwrHeightValue` | string | Conditional | Custom top drawer height in inches (e.g. `"12"`). Valid range: 4–28. Only for articles with `topDrwrHeight` feature. |
+| `leftCornerWidth` | number | Conditional | Left corner width in inches. Corner cabinets with `cornerVariables = true` only. |
+| `rightCornerDepth` | number | Conditional | Right corner depth in inches. Corner cabinets only. |
+| `excludeFronts` | boolean | No | When true, fronts excluded from order. Do not also set `frontMaterial`. |
+| `includeLegLevelers` | boolean | No | When true, leg levelers included. Only valid for articles with `Leg_Levelers` filter tag. |
+| `settingsName` | string | Conditional | **Required** when any configuration values were taken from a saved setting. The exact name of the saved setting (e.g. `"Modern Euro"`). Ensures database traceability. ARTICLE-LEVEL only — never pass at order level. |
+
+**Coordinates (optional):**
+
+If an architectural drawing is provided, coordinates can be supplied to place cabinets in the CAD file. If omitted, cabinets are placed in a fallback row.
+
+| Field | Type | Description |
+|---|---|---|
+| `x` | number | Center X on plan in decimal inches (see coordinate convention below) |
+| `y` | number | Center Y on plan in decimal inches |
+| `z` | number | Height from floor in decimal inches. 0 for base cabinets. Stacked units: sum of all cabinet heights below. |
+| `rotation` | number | Plan orientation in degrees (clockwise). 0 = north wall, 90 = east wall, 180 = south wall, 270 = west wall. |
+
+**Coordinate convention for `create_order` / `create_saved_cart`:**
+
+The coordinates passed at order creation represent CENTER X and CENTER Y directly — the server stores them as-is (no conversion applied).
+
+| Wall | x formula | y formula |
+|---|---|---|
+| North wall (rotation=0) | `D_adj_west + (sum of widths to the left) + this_width/2` | `room_depth - depth/2` |
+| South wall (rotation=180) | `D_adj_west + (sum of widths to the left) + this_width/2` | `depth/2` |
+| East wall (rotation=90) | `room_width - depth/2` (fixed for all on this wall) | `room_depth - D_adj_north - (sum of preceding widths) - this_width/2` |
+| West wall (rotation=270) | `depth/2` (fixed) | same formula as east wall |
+
+- `D_adj_west` = depth of west-wall cabinets if present, else 0 (applies to north/south wall x only)
+- `D_adj_north` = depth of north-wall base cabinets if present, else 0
+- Upper cabinets front-flush with base: `x` or `y` offset from base by `(base_depth - upper_depth)`
+- East/west wall upper cabinets: y = same as the base cabinet y (no formula). Front-flush is an x change only.
+
+---
+
+#### `list_orders`
+
+List orders on the account with pagination.
+
+**Input parameters:**
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `limit` | integer 1–100 | 20 | Max results |
+| `offset` | integer ≥ 0 | 0 | Pagination offset |
+
+**API call:** `GET /orders?limit=...&offset=...`
+
+**Returns:** JSON array of orders, or `"No orders found."` if empty.
+
+---
+
+#### `get_order`
+
+Get full details and current status for a specific order.
+
+**Input parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `orderId` | string | Yes | Order ID (e.g. `ORD-001`) |
+
+**API call:** `GET /orders/{orderId}`
+
+**Returns:** JSON object with order details including status, date, price, projectName, purchaseOrder, and articles array. Each article has `positionName` (unique identifier), `serialNumber`, `quantity`, `height`, `width`, `depth`.
+
+**Important:** Use `positionName` (not `serialNumber`) to identify specific cabinets, as multiple cabinets can share the same serial number.
+
+---
+
+#### `get_order_breakdown`
+
+Get the full Bill of Materials (BOM) for a placed order.
+
+**Input parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `orderId` | string | Yes | Order ID |
+
+**API call:** `GET /orders/{orderId}/breakdown`
+
+**Returns:** Formatted plain-text BOM report containing:
+- Number of cabinets
+- Materials: square footage per material type + estimated sheet count (based on 32 sqft/sheet × 1.2 waste factor)
+- Edgebanding: linear footage per edgebanding type
+- Hardware quantities
+- Drawer boxes with dimensions (W × H × D)
+- Stretchable purchased parts with footage
+- Door panels with dimensions
+- Drawer fronts with dimensions
+- Blind fronts with dimensions
+
+---
+
+#### `get_position_breakdown`
+
+Get detailed breakdown for a single cabinet position within an order.
+
+**Input parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `orderId` | string | Yes | Order ID |
+| `positionName` | string | Yes | Position name (e.g. `"Base"`, `"Upper.1"`) |
+
+**API call:** `GET /orders/{orderId}/position/{positionName}/breakdown`
+
+**Returns:** JSON object with materials (sqft), edgebanding, hardware, and drawer boxes for this specific cabinet.
+
+---
+
+#### `update_order_options`
+
+Update order-level options on a placed order without creating a new version. Changes are persisted immediately and broadcast to the frontend in real time.
+
+**Input parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `orderId` | string | Yes | Order ID to update |
+| `includeDrawerboxes` | boolean | No | Include drawer boxes. Omit to leave unchanged. |
+| `includeAssembly` | boolean | No | Include assembly. Omit to leave unchanged. |
+| `includeHardware` | boolean | No | Include hardware. Omit to leave unchanged. |
+| `includeFinishing` | boolean | No | Include finishing. Omit to leave unchanged. |
+| `finishingType` | `"Matte"` \| `"Satin"` \| `"Primed"` | Conditional | Required when `includeFinishing` is true. |
+| `finishingColor` | string | Conditional | Required when `includeFinishing` is true (e.g. `"White"`, `"Black"`, `"Natural"`). |
+| `specialInstructions` | string | No | Special instructions. Pass `""` to clear. |
+| `notes` | string | No | Internal notes. Pass `""` to clear. |
+| `projectName` | string | No | Project name. |
+| `purchaseOrder` | string | No | Purchase order number. |
+
+**API call:** `PATCH /orders/{orderId}/options`
+
+Only fields explicitly provided are sent. Omitted fields are unchanged.
+
+**Returns:** JSON of the full updated order options.
+
+---
+
+#### `create_order`
+
+Place a new cabinet order. Creates a completely new order with a new order ID.
+
+**Input parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `articles` | ArticleItem[] | Yes | Line items to order (see article schema above) |
+| `projectName` | string | Yes | Project name |
+| `purchaseOrder` | string | Yes | Purchase order number |
+| `projectAddress` | object | No | `{projectAddress1, projectAddress2, projectCity, projectState, projectZipcode}` |
+| `includeDrawerboxes` | boolean | No | Include drawer boxes |
+| `includeAssembly` | boolean | No | Include assembly |
+| `includeHardware` | boolean | No | Include hardware |
+| `includeFinishing` | boolean | No | Include finishing |
+| `finishingType` | `"Matte"` \| `"Satin"` \| `"Primed"` | Conditional | Required if `includeFinishing` is true |
+| `finishingColor` | string | Conditional | Required if `includeFinishing` is true |
+| `specialInstructions` | string | No | Special instructions |
+| `savedCartId` | string | No | tempOrderId of a saved cart whose canvas metadata should be copied to the new order (preserves drawing tool calibration) |
+
+**Pre-submission client-side processing:**
+1. Duplicate `positionName` check — returns error if duplicates detected
+2. Apply saved setting preset values to each article (user-provided values take precedence)
+3. Apply gap defaults (`"0.125"`) to gap fields for articles with `gapControl = true`
+
+**API call:** `POST /orders`
+
+**Returns:** `"Order created successfully. Order ID: {orderId}"`
+
+**Required pre-call confirmations from user:** projectName, purchaseOrder, all add-on flags, all article-level configuration fields. The AI must never auto-fill, assume, or default any field.
+
+---
+
+#### `create_saved_cart`
+
+Save a NEW cabinet configuration as a saved cart for user review before committing to an order. Same input schema as `create_order`.
+
+**Use when:** Creating a brand new order from scratch. NOT for editing existing orders.
+
+**Pre-submission client-side processing:** Same as `create_order` (duplicate check, preset application, gap defaults).
+
+**API call:** `POST /saved-carts`
+
+**Returns:** `"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."`
+
+---
+
+#### `list_saved_carts`
+
+List all saved carts for the authenticated user.
+
+**Input parameters:** None
+
+**API call:** `GET /saved-carts`
+
+**Returns:** Summary list of carts, each showing: `tempOrderId`, project name, PO number, article count, date, and whether it is an edit cart (revision of an existing order) with its `sourceOrderId`.
+
+---
+
+#### `get_saved_cart`
+
+Read the current state of a saved cart including all articles and their configurations.
+
+**Input parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `tempOrderId` | string | Yes | Saved cart reference ID (plain numeric string, e.g. `"901787"`) |
+
+**API call:** `GET /saved-carts/{tempOrderId}`
+
+**Returns:** Formatted plain-text summary of the cart: project name, PO, and for each article: positionName, displayName, serialNumber, dimensions, all material/edge/config fields, gaps, corner dimensions, and preset name.
+
+**Important:** Call this before making edits — users may have updated the cart directly in the Sealab web portal.
+
+---
+
+#### `add_articles_to_cart`
+
+Add new articles to an existing saved cart.
+
+**Input parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `tempOrderId` | string | Yes | Saved cart reference ID (plain numeric string) |
+| `articles` | ArticleItem[] | Yes | Articles to add. Accepts native JSON array or JSON string. |
+
+**Pre-submission processing:** Same as `create_order` (duplicate check within the batch, preset application, gap defaults).
+
+**API call:** `POST /saved-carts/{tempOrderId}/articles`
+
+**Returns:** `"Added {N} article(s) to saved cart {tempOrderId}. Total cart ID: {tempOrderId}"`
+
+---
+
+#### `update_saved_cart_articles`
+
+Update the configuration of one or more existing articles in a saved cart. Only the fields that have changed need to be sent — `positionName` is required to identify each article; all other fields are optional. Can also change the cabinet type by patching `serialNumber`.
+
+**Input parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `tempOrderId` | string | Yes | Saved cart reference ID |
+| `articles` | UpdateArticleItem[] | Yes | Articles to update. Each must have `positionName`; all other fields optional. Accepts native JSON array or JSON string. |
+
+Note: The PATCH update does NOT include coordinate fields (x, y, z, rotation) — those are updated via `update_cabinet_coordinates` or `patch_cabinet_coordinates`.
+
+**Pre-submission processing:** Applies saved setting preset values where `settingsName` is specified.
+
+**API call:** `PATCH /saved-carts/{tempOrderId}/articles`
+
+**Returns:** `"Updated {N} article(s) in saved cart {tempOrderId}."`
+
+---
+
+#### `delete_saved_cart_articles`
+
+Remove one or more articles from a saved cart by `positionName`.
+
+**Input parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `tempOrderId` | string | Yes | Saved cart reference ID |
+| `positionNames` | string[] | Yes | Position names to delete. Accepts native JSON array or JSON string. |
+
+**API call:** `DELETE /saved-carts/{tempOrderId}/articles`
+
+**Returns:** `"Deleted {N} article(s) from saved cart {tempOrderId}: [{names}]."`
+
+---
+
+#### `create_edit_cart`
+
+Create a saved cart from an EXISTING placed order for editing. Copies all articles and order settings from the source order into a new saved cart. Sets `sourceOrderId` and `isEditCart` flags required for versioned submission.
+
+**Use when:** User wants to edit or revise a previously placed order (e.g. "edit order 429308").
+
+**Input parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `orderId` | string | Yes | Order ID to create edit cart from |
+
+**API call:** `POST /saved-carts/{orderId}/create-edit-cart`
+
+**Returns:** `"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."`
+
+---
+
+#### `submit_cart_as_version`
+
+Submit a saved edit cart as a versioned order revision (e.g. `ORDER123_v2`). Copies canvas data, coordinates, and permissions from the source order, applies modified articles, then deletes the saved cart.
+
+**Use ONLY when:** The cart was created via `create_edit_cart` (has `sourceOrderId` set).
+
+**Input parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `tempOrderId` | string | Yes | Saved cart reference ID (plain numeric string — no prefix like `"SavedCart_"`) |
+| `projectName` | string | No | Overrides saved cart value if provided |
+| `purchaseOrder` | string | No | Overrides saved cart value if provided |
+| `includeDrawerboxes` | boolean | No | |
+| `includeAssembly` | boolean | No | |
+| `includeHardware` | boolean | No | |
+| `includeFinishing` | boolean | No | |
+| `finishingType` | `"Matte"` \| `"Satin"` \| `"Primed"` | Conditional | Required if `includeFinishing` is true |
+| `finishingColor` | string | Conditional | Required if `includeFinishing` is true |
+| `specialInstructions` | string | No | |
+| `projectAddress` | object | No | `{projectAddress1, projectAddress2, projectCity, projectState, projectZipcode}` |
+
+**API call:** `POST /saved-carts/{tempOrderId}/submit-as-version`
+
+**Returns:** `"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."`
+
+---
+
+### Module 5: Saved Settings (`src/tools/saved-settings.ts`)
+
+Saved settings are reusable configuration presets that store material, edge, joint, drawer, hinge, and shelf selections. They can be applied to articles via the `settingsName` field, reducing repetitive data entry.
+
+**Saved setting fields:**
+
+| Field | Type | Description |
+|---|---|---|
+| `savedSettingsId` | number | Auto-assigned ID |
+| `name` | string | Descriptive name (e.g. `"Modern Euro"`, `"Traditional"`) |
+| `frontMaterial` | string | Front material specification |
+| `caseMaterial` | string | Case material specification |
+| `backPanelMaterial` | string | Back panel material |
+| `backPanel` | string | Back panel type |
+| `drawerType` | string | Drawer type |
+| `jointMethod` | string | Joint method |
+| `caseEdge` | string | Case edge treatment |
+| `frontEdge` | string | Front edge treatment |
+| `numOfShelves` | string | Number of shelves |
+| `bottomPanelConnector` | string | Bottom panel connector (e.g. `"Leg Levelers"`) |
+| `topDrwrHeightValue` | string | Top drawer height value |
+| `hingePlate` | string | Hinge plate type |
+| `includeLegLevelers` | string | Include leg levelers flag |
+| `isPreset` | number | `1` = public preset available to all users, `0` = user-specific |
+
+**Usage rule:** When values from a saved setting are used to configure any article, the `settingsName` field MUST be set on that article object to the exact name of the saved setting. This is an article-level field — never pass at the order level.
+
+---
+
+#### `get_saved_settings_presets`
+
+Get all public preset saved settings (available to all users).
+
+**Input parameters:** None
+
+**API call:** `GET /saved-settings/presets`
+
+**Returns:** JSON array of preset saved settings, or `"No preset saved settings found."` if empty.
+
+---
+
+#### `get_my_saved_settings`
+
+Get all saved settings for the currently authenticated user — both personal settings and public presets.
+
+**Input parameters:** None
+
+**API call:** `GET /saved-settings/user`
+
+**Returns:** JSON array of saved settings, or `"No saved settings found for your account."` if empty.
+
+---
+
+#### `get_saved_setting_by_id`
+
+Get a specific saved setting by its numeric ID.
+
+**Input parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `id` | number | Yes | Saved setting ID |
+
+**API call:** `GET /saved-settings/{id}`
+
+**Authorization:** Presets available to all authenticated users; user settings available only to the owner.
+
+**Returns:** JSON object for the saved setting.
+
+---
+
+#### `create_saved_setting`
+
+Create a new saved setting for the current user.
+
+**Input parameters:** All saved setting fields except `savedSettingsId` and `isPreset` (optional boolean — `true` creates a public preset, requires admin privileges).
+
+**API call:** `POST /saved-settings/user`
+
+**Returns:** `"Saved setting created successfully. ID: {savedSettingsId}"`
+
+---
+
+#### `update_saved_setting`
+
+Update an existing saved setting. Can only update the user's own settings (not presets).
+
+**Input parameters:** All saved setting fields. `savedSettingsId` is required.
+
+**API call:** `PUT /saved-settings/{savedSettingsId}`
+
+**Returns:** `"Saved setting updated successfully. ID: {savedSettingsId}"`
+
+---
+
+#### `delete_saved_setting`
+
+Delete a saved setting. Can only delete the user's own settings.
+
+**Input parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `id` | number | Yes | Saved setting ID to delete |
+
+**API call:** `DELETE /saved-settings/{id}`
+
+**Returns:** `"Saved setting {id} deleted successfully."`
+
+---
+
+### Module 6: Canvas (`src/tools/canvas.ts`)
+
+Tools for managing the Sealab Drawing Tool — the web-based canvas where users position cabinets on floor plan and elevation views. Supports both placed orders and saved carts.
+
+#### Canvas Types
+
+| Canvas Type | Description |
+|---|---|
+| `plan` | Floor plan view (overhead) |
+| `north` | North elevation view |
+| `south` | South elevation view |
+| `east` | East elevation view |
+| `west` | West elevation view |
+
+---
+
+#### Canvas Coordinate System (for `update_cabinet_coordinates` and `patch_cabinet_coordinates`)
+
+The coordinate system used by the canvas tools differs slightly from the `create_order` / `create_saved_cart` coordinate system. Coordinates are stored as **back-edge** values (not center) for the depth axis.
+
+| Coordinate | Meaning |
+|---|---|
+| `x` | **Back-edge X** in decimal inches (absolute room coordinate: 0 = west wall face) |
+| `y` | **Back-edge Y** in decimal inches (absolute room coordinate: 0 = south wall face, room_depth = north wall face) |
+| `z` | Height from floor in decimal inches (0 for base cabinets on floor) |
+| `rotation` | Wall orientation in degrees clockwise (0=north, 90=east, 180=south, 270=west) |
+
+**x formulas by wall:**
+
+| Wall | Formula |
+|---|---|
+| North/South | `x = D_adj_west + (sum of widths of cabinets to the left) + this_width/2` |
+| West wall base | `x = 0` (back against west wall) |
+| West wall upper (front-flush) | `x = base_depth - upper_depth` |
+| East wall base | `x = room_width` (back against east wall) |
+| East wall upper (front-flush) | `x = base_x - (base_depth - upper_depth)` |
+
+**y formulas by wall:**
+
+| Wall | Formula |
+|---|---|
+| South wall base | `y = 0` (back against south wall) |
+| South wall upper (front-flush) | `y = base_depth - upper_depth` |
+| North wall base | `y = room_depth` (back against north wall) |
+| North wall upper (front-flush) | `y = base_y - (base_depth - upper_depth)` |
+| East/West wall | `y = room_depth - D_adj_north - (sum of widths of all preceding cabinets) - this_width/2` |
+| East/West upper | `y = same as base cabinet on that position` (front-flush is x change only) |
+
+**Multi-quantity articles:** When an article was added with `quantity > 1`, the server expands it into separate articles with incrementing suffixes (e.g. `DR_B2_01` qty=3 → `DR_B2_01`, `DR_B2_02`, `DR_B2_03`). Every expanded position name must have its own coordinate entry.
+
+---
+
+#### `get_drawing_tool_state`
+
+Retrieve the full drawing tool state for an order in a single call.
+
+**Input parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `orderId` | string | Yes | Order ID |
+
+**API call:** `GET /canvas/{orderId}`
+
+**Returns:** JSON with three sections:
+1. `metadata` — canvas scale, calibration, Z0 floor references, elevation visibility, active canvases, and all other drawing tool state
+2. `images` — S3 keys for background and snapshot images per canvas type
+3. `coordinates` — all cabinet positions keyed by positionName
+
+Returns 404 if no drawing tool state exists yet for this order.
+
+---
+
+#### `get_canvas_metadata`
+
+Retrieve canvas metadata only (without images or coordinates).
+
+**Input parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `orderId` | string | Yes | Order ID |
+
+**API call:** `GET /canvas/{orderId}/metadata`
+
+**Returns:** JSON containing: `activeCanvases`, `canvasMeta` (scale/position/zoom per canvas type), `z0References` (floor calibration per elevation), `verticalCalibration`, `elevationVisibility`, `calibrationOffsets`, `itemRotations`, `fixedElevationPositions`, `elevationCalibrated`, `globalElevationOffsets`, `calibratedCabinets`.
+
+---
+
+#### `update_canvas_metadata`
+
+Replace all canvas metadata fields for an order. All existing metadata is overwritten. Fields not included are set to null.
+
+**Input parameters:** `orderId` + any subset of these metadata fields:
+
+| Field | Type | Description |
+|---|---|---|
+| `canvasMeta` | object | Per-canvas display metadata keyed by canvas type. Each entry: scale (ratio, unit), position (x, y), rotation, zoom, backgroundImage (S3 URL). |
+| `z0References` | object | Floor reference line calibration per elevation. Each entry: imagePercentFromBottom, originalImageDimensions, realWorldHeight, timestamp. |
+| `verticalCalibration` | object | Vertical height mapping calibration per elevation. Each entry: scale, offset, unit, timestamp. |
+| `elevationVisibility` | object | Item visibility per elevation, keyed by itemId. Each value maps elevation name to boolean. |
+| `calibrationOffsets` | object | Coordinate positioning offsets per canvas type. Each entry: x, y offset values in pixels. |
+| `itemRotations` | object | Item-specific rotation values keyed by itemId. Values are rotation in degrees. |
+| `activeCanvases` | string[] | List of active canvas types (`"plan"`, `"north"`, `"south"`, `"east"`, `"west"`). |
+| `fixedElevationPositions` | object | Pinned cabinet pixel positions after global calibration, keyed by elevation then positionName. |
+| `elevationCalibrated` | object | Global calibration status per elevation (boolean values). |
+| `globalElevationOffsets` | object | Coordinate system transformations per elevation (maps plan coordinates to elevation coordinates). Each entry: x, y offset in inches. |
+| `calibratedCabinets` | object | Which cabinets have been globally calibrated per elevation, keyed by elevation then positionName. |
+
+**API call:** `PUT /canvas/{orderId}/metadata`
+
+**Returns:** JSON of updated metadata.
+
+---
+
+#### `get_canvas_images`
+
+Retrieve canvas image records for an order.
+
+**Input parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `orderId` | string | Yes | Order ID |
+
+**API call:** `GET /canvas/{orderId}/images`
+
+**Returns:** JSON array of entries, each with: `canvasType` (plan/north/south/east/west), `imageType` (background/snapshot), `s3Key` (S3 path to the image file).
+
+---
+
+#### `get_cabinet_coordinates`
+
+Retrieve all stored cabinet coordinates for an order or saved cart.
+
+**Input parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `orderId` | string | Yes | Order ID or saved cart tempOrderId |
+
+**API call:** `GET /canvas/{orderId}/coordinates`
+
+**Returns:** JSON of all cabinet coordinates. Each entry has: `positionName`, `x` (back-edge X), `y` (back-edge Y), `z` (height from floor), `rotation`. Use these values directly in `update_cabinet_coordinates` for round-trip operations.
+
+---
+
+#### `update_cabinet_coordinates`
+
+Replace ALL cabinet coordinates for an order or saved cart. All existing coordinates are deleted and replaced with the provided list. To remove a cabinet's coordinates, omit it from the list.
+
+**Recommended workflow for saved carts:**
+1. `create_edit_cart` or use existing saved cart tempOrderId
+2. `update_cabinet_coordinates(tempOrderId, [...])` ← set coordinates on the cart BEFORE submitting
+3. `submit_cart_as_version` — coordinates stored on the cart are written to the XML at submit time
+
+**Input parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `orderId` | string | Yes | Order ID or saved cart tempOrderId |
+| `coordinates` | CoordinateItem[] | Yes | Full replacement list. Each item: positionName, x, y, z, rotation. |
+
+**API call:** `PUT /canvas/{orderId}/coordinates`
+
+**Returns:** JSON of stored coordinates.
+
+---
+
+#### `patch_cabinet_coordinates`
+
+Partially update coordinates for specific cabinets only. Other cabinets keep their existing coordinates unchanged.
+
+**Use when:** Repositioning one or a few specific cabinets without disturbing the rest of the layout.
+
+**Use `update_cabinet_coordinates` instead when:** Setting coordinates for the first time, or removing cabinets' coordinates.
+
+**Input parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `orderId` | string | Yes | Order ID or saved cart tempOrderId |
+| `coordinates` | CoordinateItem[] (min 1) | Yes | Cabinets to update. Only these positionNames are affected. |
+
+**API call:** `PATCH /canvas/{orderId}/coordinates`
+
+**Returns:** JSON with `patched` count (positions sent), `total` (all stored coordinates), and the full updated coordinate list. The frontend is notified in real time via WebSocket.
+
+---
+
+#### `upload_canvas_background_image`
+
+Upload a background image for a specific canvas from a local file path. The existing background image for that canvas type is automatically removed from S3 and replaced. Canvas defaults (scale 1, zoom 1, position 0/0) are initialized for the uploaded canvas type, and it is added to `activeCanvases`. The drawing tool frontend is notified in real time via WebSocket.
+
+**Input parameters:**
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `orderId` | string | Yes | Order ID |
+| `canvasType` | `"plan"` \| `"north"` \| `"south"` \| `"east"` \| `"west"` | Yes | Which canvas view to upload to |
+| `imagePath` | string | Yes | Absolute local filesystem path to the image file. Supported formats: `.png`, `.jpg`, `.jpeg`, `.webp`. |
+
+The MCP server reads and encodes the file itself — do not convert it before passing.
+
+**API call:** `POST /canvas/{orderId}/images/{canvasType}/background` (multipart/form-data)
+
+**Returns:** JSON of the uploaded image record.
+
+---
+
+## Internal Behaviors
+
+### `flexArray` Helper (`orders.ts`)
+
+Array fields in order/cart tools accept either a native JSON array or a JSON string representing an array. This handles the behavior of some MCP clients (including Claude Code) that validate tool arguments against the JSON Schema before sending — a plain `z.array()` schema causes the client to reject string values. The `flexArray` helper generates a `{ anyOf: [array, string] }` schema so strings pass client-side validation, and are parsed and re-validated server-side.
+
+### Saved Setting Application (`orders.ts`)
+
+When an article has a `settingsName` set, the server client-side fetches that saved setting (from user settings first, then public presets) and merges its values as defaults into the article. User-explicitly-provided values always take precedence. The following fields are mapped from the saved setting: `caseMaterial`, `frontMaterial`, `backPanelMaterial`, `backPanel`, `drawerType`, `jointMethod`, `caseEdge`, `frontEdge`, `hingePlate`, `numOfShelves`, `topDrwrHeightValue`, `includeLegLevelers`.
+
+### Settings Cache (`orders.ts`)
+
+Fetched saved settings are cached in memory with a **5-minute TTL** (`SETTINGS_CACHE_TTL_MS = 300,000 ms`) to avoid redundant API calls within a session. The cache handles updates made from the web portal — entries older than the TTL are re-fetched on next use.
+
+### Duplicate `positionName` Guard
+
+`create_order`, `create_saved_cart`, `add_articles_to_cart`, and `update_saved_cart_articles` all perform a client-side check for duplicate `positionName` values within the submitted articles before calling the API. If duplicates are found, a descriptive error is returned immediately without making an API call.
+
+### Gap Default Application (`orders.ts`)
+
+For articles that have `gapControl = true` (determined by fetching `GET /catalog/{serialNumber}/configuration`), any gap field (`gapTop`, `gapBottom`, `gapLeft`, `gapRight`, `gapCenter`) that is not provided by the user is automatically set to `"0.125"` (1/8 inch). This is applied in `create_order`, `create_saved_cart`, and `add_articles_to_cart`.
+
+---
+
+## Tooltip Resources (`resources/tooltips/`)
+
+Twenty-five `.txt` files containing HTML-formatted guidance text for each configurable field. These are read at runtime by `get_article_context` (to build the full context block) and `get_configuration_info` (for single-field deep dives). HTML is stripped to plain text before returning.
+
+| File | Field |
+|---|---|
+| `backPanel.txt` | Back panel attachment method |
+| `backPanelMaterial.txt` | Back panel material |
+| `caseEdge.txt` | Case edgebanding |
+| `caseMaterial.txt` | Case/box material |
+| `depth.txt` | Cabinet depth |
+| `drawerType.txt` | Drawer box construction type (undermount glides only) |
+| `edgeBandingType.txt` | Edgebanding type (LP_SP/LP_GP series) |
+| `excludeFronts.txt` | Exclude fronts flag |
+| `frontEdge.txt` | Front edgebanding |
+| `frontMaterial.txt` | Door/drawer front material |
+| `gapBottom.txt` | Bottom reveal gap |
+| `gapCenter.txt` | Center gap between adjacent doors/drawers |
+| `gapLeft.txt` | Left reveal gap |
+| `gapRight.txt` | Right reveal gap |
+| `gapTop.txt` | Top reveal gap |
+| `height.txt` | Cabinet height |
+| `hingePlate.txt` | Hinge plate type (Cross Plate / Inline Plate, Euro-style cup hinges) |
+| `includeLegLevelers.txt` | Leg levelers flag |
+| `jointMethod.txt` | Case joinery method (biscuit joints, Lamello #20, biscuits ~5" apart) |
+| `leftCornerWidth.txt` | Left corner width (corner cabinets) |
+| `numOfShelves.txt` | Number of adjustable shelves |
+| `positionName.txt` | Position name field guidance |
+| `rightCornerDepth.txt` | Right corner depth (corner cabinets) |
+| `topDrwrHeight.txt` | Top drawer height |
+| `width.txt` | Cabinet width |
+
+---
+
+## Build and Development
+
+### Scripts (`package.json`)
+
+| Script | Command | Purpose |
+|---|---|---|
+| `build` | `tsc` | Compile TypeScript to `dist/` |
+| `start` | `node dist/index.js` | Run compiled server |
+| `dev` | `ts-node src/index.ts` | Run directly from TypeScript (no compile step) |
+| `test` | `vitest run` | Run test suite once |
+| `test:watch` | `vitest` | Run tests in watch mode |
+
+### Binary
+
+The package exposes `sealab-mcp-server` as a CLI binary pointing to `dist/index.js`.
+
+### TypeScript Configuration (`tsconfig.json`)
+
+- Target: `ES2022`
+- Module: `commonjs`
+- Strict mode enabled
+- Output: `dist/`
+- Source root: `src/`
+- Test files (`*.test.ts`) excluded from compilation
+
+---
+
+## API Surface Summary
+
+All endpoints target `{SEALAB_API_URL}/api/mcp/v1`:
+
+| Endpoint | Method | Tool |
+|---|---|---|
+| `/catalog/search` | GET | `search_catalog` |
+| `/catalog/{sn}` | GET | `get_article` |
+| `/catalog/filter-tags` | GET | `list_filter_tags` |
+| `/catalog/{sn}/configuration` | GET | `get_article_configuration`, `get_article_context`, internal (gap/preset logic) |
+| `/catalog/{sn}/options` | GET | `get_article_options` |
+| `/orders` | GET | `list_orders` |
+| `/orders` | POST | `create_order` |
+| `/orders/{id}` | GET | `get_order` |
+| `/orders/{id}/breakdown` | GET | `get_order_breakdown` |
+| `/orders/{id}/position/{pos}/breakdown` | GET | `get_position_breakdown` |
+| `/orders/{id}/options` | PATCH | `update_order_options` |
+| `/saved-carts` | GET | `list_saved_carts` |
+| `/saved-carts` | POST | `create_saved_cart` |
+| `/saved-carts/{id}` | GET | `get_saved_cart` |
+| `/saved-carts/{id}/articles` | POST | `add_articles_to_cart` |
+| `/saved-carts/{id}/articles` | PATCH | `update_saved_cart_articles` |
+| `/saved-carts/{id}/articles` | DELETE | `delete_saved_cart_articles` |
+| `/saved-carts/{id}/create-edit-cart` | POST | `create_edit_cart` |
+| `/saved-carts/{id}/submit-as-version` | POST | `submit_cart_as_version` |
+| `/saved-settings/presets` | GET | `get_saved_settings_presets`, internal (preset lookup) |
+| `/saved-settings/user` | GET | `get_my_saved_settings`, internal (preset lookup) |
+| `/saved-settings/user` | POST | `create_saved_setting` |
+| `/saved-settings/{id}` | GET | `get_saved_setting_by_id` |
+| `/saved-settings/{id}` | PUT | `update_saved_setting` |
+| `/saved-settings/{id}` | DELETE | `delete_saved_setting` |
+| `/canvas/{id}` | GET | `get_drawing_tool_state` |
+| `/canvas/{id}/metadata` | GET | `get_canvas_metadata` |
+| `/canvas/{id}/metadata` | PUT | `update_canvas_metadata` |
+| `/canvas/{id}/images` | GET | `get_canvas_images` |
+| `/canvas/{id}/coordinates` | GET | `get_cabinet_coordinates` |
+| `/canvas/{id}/coordinates` | PUT | `update_cabinet_coordinates` |
+| `/canvas/{id}/coordinates` | PATCH | `patch_cabinet_coordinates` |
+| `/canvas/{id}/images/{type}/background` | POST (multipart) | `upload_canvas_background_image` |
+
+---
+
+## Proposed Future Enhancements (`PROPOSED-CHANGES-INSERTION-POINTS.md`)
+
+The following changes are documented as proposals (not yet implemented, as of the file's 2026-03-27 date):
+
+| # | Change | Status | Priority |
+|---|---|---|---|
+| 1 | Add coordinate acknowledgment (echo stored coordinates) to `create_order` / `create_saved_cart` response | Not implemented | P1 |
+| 2 | Add `lastModifiedAt` timestamp to canvas coordinate entries | Not implemented | P1 |
+| 3 | Add `diff_cabinet_coordinates` tool for efficient change detection | Not implemented | P2 |
+| 4 | Add `get_cabinet_coordinates_batch` for reading coordinates across multiple orders at once | Not implemented | P2 |
+| 5 | Add JSDoc block documenting the coordinate convention in `orders.ts` | Not implemented | P0 |
+
+These changes are motivated by an integration with "Openclaw" — a proposal engine that extracts cabinet insertion points from architectural drawings. The proposals are all additive (no breaking changes) and several require backend API modifications in addition to MCP tool changes.
+
+---
+
+## Intended Usage Workflow
+
+### Standard New Order Flow
+
+1. **Browse catalog** — `search_catalog` + `list_filter_tags` to find candidate articles
+2. **Select article** — `get_article` to see full details
+3. **Load context** — `get_article_context` to understand which fields apply and get guidance
+4. **Load options** — `get_article_options` to get valid string values for each field
+5. **Collect user input** — present all applicable options, ask user to confirm every value
+6. **Save as cart** — `create_saved_cart` with all confirmed values (user reviews at thesealab.com)
+7. **Place order** — `create_order` once user is satisfied (or submit cart separately)
+
+### Order Editing Flow
+
+1. **Find the order** — `list_orders` or `get_order`
+2. **Create edit cart** — `create_edit_cart(orderId)` → returns `tempOrderId`
+3. **Review current state** — `get_saved_cart(tempOrderId)`
+4. **Modify articles** — `update_saved_cart_articles` / `add_articles_to_cart` / `delete_saved_cart_articles`
+5. **Update coordinates** — `update_cabinet_coordinates(tempOrderId, ...)` BEFORE submitting
+6. **Submit revision** — `submit_cart_as_version(tempOrderId, ...)`
+
+### Configuration Presets Flow
+
+1. **Browse presets** — `get_saved_settings_presets` or `get_my_saved_settings`
+2. **Apply to article** — include preset field values in article AND set `settingsName` to the preset's exact name
+3. **Server merges** — the MCP server fetches the preset client-side and fills in any fields not explicitly provided