@sealab/mcp-server 1.0.0

package/resources/tooltips/width.txt

@@ -0,0 +1,5 @@
+<h1>Cabinet Width</h1>
+
+    <p>The <strong>width</strong> represents the horizontal dimension of the cabinet, measured from the left side to the right side of the carcass. This measurement does not include any additional elements like side panels, fillers, or countertops-it only refers to the case of the cabinet.</p>
+
+    <p><strong>Note:</strong> The width of the cabinet may differ from the width of the fronts. For more information on front sizing, refer to the <strong>GAP SETTINGS</strong> page.</p>

package/src/client/api-client.ts

@@ -0,0 +1,37 @@
+import axios, { AxiosInstance, AxiosError } from 'axios';
+
+const API_KEY = process.env.SEALAB_API_KEY;
+const API_URL = process.env.SEALAB_API_URL ?? 'https://thesealab.com';
+
+if (!API_KEY) {
+  throw new Error('SEALAB_API_KEY environment variable is required');
+}
+
+export const client: AxiosInstance = axios.create({
+  baseURL: `${API_URL}/api/mcp/v1`,
+  headers: {
+    'X-API-Key': API_KEY,
+  },
+  timeout: 10000,
+});
+
+export class McpApiError extends Error {
+  constructor(public readonly status: number, message: string) {
+    super(message);
+    this.name = 'McpApiError';
+  }
+}
+
+export function handleAxiosError(error: unknown): never {
+  if (axios.isAxiosError(error)) {
+    const axiosErr = error as AxiosError<{ error?: string }>;
+    const status = axiosErr.response?.status ?? 0;
+    const message = axiosErr.response?.data?.error ?? axiosErr.message;
+
+    if (status === 401) throw new McpApiError(401, 'Invalid API key');
+    if (status === 404) throw new McpApiError(404, message);
+    if (status === 422) throw new McpApiError(422, message);
+    throw new McpApiError(status, `API error: ${message}`);
+  }
+  throw new McpApiError(0, 'Unable to reach Sealab API — check SEALAB_API_URL');
+}

package/src/index.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+
+import { catalogTools } from './tools/catalog';
+import { orderTools } from './tools/orders';
+import { configurationTools } from './tools/configuration';
+import { configurationInfoTools } from './tools/configuration-info';
+import { savedSettingsTools } from './tools/saved-settings';
+import { canvasTools } from './tools/canvas';
+
+const allTools = [...catalogTools, ...orderTools, ...configurationTools, ...configurationInfoTools, ...savedSettingsTools, ...canvasTools];
+
+const server = new Server(
+  { name: 'sealab', version: '1.0.0' },
+  { capabilities: { tools: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: allTools.map((t) => ({
+    name: t.name,
+    description: t.description,
+    inputSchema: zodToJsonSchema(t.inputSchema as any, { target: 'openApi3' }),
+  })),
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const tool = allTools.find((t) => t.name === request.params.name);
+  if (!tool) {
+    return { content: [{ type: 'text', text: `Unknown tool: ${request.params.name}` }], isError: true };
+  }
+
+  const parsed = tool.inputSchema.safeParse(request.params.arguments ?? {});
+  if (!parsed.success) {
+    return {
+      content: [{ type: 'text', text: `Invalid input: ${parsed.error.message}` }],
+      isError: true,
+    };
+  }
+
+  const result = await (tool.handler as (input: any) => Promise<string>)(parsed.data);
+  return { content: [{ type: 'text', text: result }] };
+});
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch(console.error);

package/src/tools/canvas.ts

@@ -0,0 +1,442 @@
+import { z } from 'zod';
+import { client, handleAxiosError } from '../client/api-client';
+import * as fs from 'fs';
+import * as path from 'path';
+import FormData from 'form-data';
+
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+
+const GetDrawingToolStateSchema = z.object({
+  orderId: z.string().describe('Order ID to retrieve full drawing tool state for (metadata + images + coordinates).'),
+});
+
+const GetCanvasMetadataSchema = z.object({
+  orderId: z.string().describe('Order ID to retrieve canvas metadata for.'),
+});
+
+const GetCanvasImagesSchema = z.object({
+  orderId: z.string().describe('Order ID to retrieve canvas image records for.'),
+});
+
+const GetCabinetCoordinatesSchema = z.object({
+  orderId: z.string().describe('Order ID to retrieve cabinet coordinates for.'),
+});
+
+const CoordinateItemSchema = z.object({
+  positionName: z.string().describe(
+    'Position name of the cabinet as stored in the order (e.g. "Base_01", "Upper_01"). ' +
+    'Must match the positionName used in the order articles exactly. ' +
+    'MULTI-QUANTITY: if a cabinet was added with quantity > 1, the server expanded it into individual ' +
+    'articles with incrementing suffixes (e.g. "DR_B2_01" qty=3 → "DR_B2_01", "DR_B2_02", "DR_B2_03"). ' +
+    'You must include a separate coordinate entry for EACH expanded name — one entry for "DR_B2_01" ' +
+    'alone does not set coordinates for "DR_B2_02" or "DR_B2_03".'
+  ),
+  x: z.number().describe(
+    'Center X coordinate in decimal inches. Absolute room coordinate: 0 = west wall face, room_width = east wall face.\n' +
+    'North/South wall (rotation=0/180): variable x — position along the wall.\n' +
+    '  x = D_adj_west + (sum of widths of cabinets to the LEFT on this wall + any filler) + this_cabinet_width / 2.\n' +
+    '  D_adj_west = depth of west-wall cabinets if west wall cabinets exist in this layout, else 0.\n' +
+    '  CORNER CLEARANCE: north/south wall cabinets must start at x=D_adj_west, NOT x=0.\n' +
+    '  SCOPE: D_adj_west applies ONLY to north/south wall x — it does NOT affect east/west wall x.\n' +
+    'West wall (rotation=270): back-edge based — x is the BACK-EDGE coordinate (distance from west wall to cabinet BACK).\n' +
+    '  Base cabinet: x = 0 (back edge against west wall).\n' +
+    '  Shallower cabinet (e.g. upper) front-flush with base: x = base_depth - upper_depth.\n' +
+    '  Example: 24" base + 15" upper → x = 24 - 15 = 9".\n' +
+    '  Verification: base front edge at 0+24=24", upper front edge at 9+15=24" ✅ MATCH.\n' +
+    'East wall (rotation=90): back-edge based — x is the BACK-EDGE coordinate (distance from west wall to cabinet BACK).\n' +
+    '  Base cabinet: x = room_width (back edge against east wall). Requires room_width from drawing.\n' +
+    '  Shallower cabinet front-flush: x = base_x - (base_depth - upper_depth).\n' +
+    '  Example: base x=120 (24" deep) + 15" upper → upper x = 120 - 9 = 111".\n' +
+    '  Verification: base front at 120-24=96", upper front at 111-15=96" ✅ MATCH.\n' +
+    '  CRITICAL: Upper x = base_x - (base_depth - upper_depth). Just offset from base — no room dimension math.\n' +
+    '  IF room_width IS UNKNOWN: ask the user for room dimensions from the drawing to set base x.\n' +
+    'Values from get_cabinet_coordinates are already center X; pass directly for round-trip operations.'
+  ),
+  y: z.number().describe(
+    'Back-edge Y coordinate in decimal inches. Absolute room coordinate: 0 = south wall face, room_depth = north wall face.\n' +
+    'CRITICAL: Y is the BACK-EDGE coordinate (distance from south wall face to cabinet BACK), NOT center.\n' +
+    'South wall (rotation=180): back-edge based — y is distance from south wall face to cabinet BACK.\n' +
+    '  Base cabinet: y = 0 (back edge against south wall).\n' +
+    '  Shallower cabinet (e.g. upper) front-flush with base: y = base_depth - upper_depth.\n' +
+    '  Example: 24" base + 15" upper → y = 24 - 15 = 9". Front edges align at 24".\n' +
+    'North wall (rotation=0): back-edge based — y is distance from south wall face to cabinet BACK.\n' +
+    '  Base cabinet: y = room_depth (back edge against north wall). Requires room_depth from drawing.\n' +
+    '  Shallower cabinet front-flush: y = base_y - (base_depth - upper_depth).\n' +
+    '  Example: base y=120 (24" deep) + 15" upper → upper y = 120 - 9 = 111".\n' +
+    '  Verification: base front at 120-24=96", upper front at 111-15=96" ✅ MATCH.\n' +
+    '  CRITICAL: Upper y = base_y - (base_depth - upper_depth). Just offset from base — no room dimension math.\n' +
+    '  IF room_depth IS UNKNOWN: ask the user for room dimensions from the drawing to set base y.\n' +
+    'East wall (rotation=90): variable y — position along the wall (north-south).\n' +
+    '  "Width" = cabinet\'s own width dimension, running north-south after rotation.\n' +
+    '  East/west wall cabinets run from the north wall SOUTHWARD (decreasing y). List them north-to-south.\n' +
+    '  D_adj_north = the catalog DEPTH of the north-wall BASE cabinet (the "depth" used in north wall y = room_depth).\n' +
+    '    Example: north wall has 24"-deep base cabinets → D_adj_north = 24.\n' +
+    '    NEVER set D_adj_north = 0 when north wall cabinets exist — that places east/west cabinet inside the north wall footprint.\n' +
+    '  Northernmost cabinet (1st in list): y = room_depth - D_adj_north - this_width / 2.\n' +
+    '  Each next cabinet going south: subtract all preceding widths.\n' +
+    '  General: y = room_depth - D_adj_north - (sum of widths of all cabinets listed before this one) - this_width / 2.\n' +
+    '  y DECREASES with each cabinet going south. NEVER add widths — adding goes north (wrong direction).\n' +
+    'West wall (rotation=270): y = same formula as east wall.\n' +
+    'EAST/WEST UPPER CABINETS: DO NOT compute y for uppers — copy the base cabinet y value exactly. No formula. No D_adj_north.\n' +
+    'Front-flush on east/west walls is achieved by changing X only — y is unchanged from the base.\n' +
+    'Do NOT apply the north/south front-flush y formulas to east/west wall cabinets.'
+  ),
+  z: z.number().describe(
+    'Height from floor in decimal inches. ' +
+    '0 for base cabinets sitting on the floor. ' +
+    'Stacked units: sum of the heights of all cabinets below this one.'
+  ),
+  rotation: z.number().describe(
+    'Identifies which wall this cabinet is on and its orientation in CAD. ' +
+    '0 = north wall, 90 = east wall, 180 = south wall, 270 = west wall. ' +
+    'If the drawing has no compass rose, assume top = north, bottom = south, left = west, right = east. ' +
+    'All cabinets on the same wall share the same rotation value. ' +
+    'Default 0 for single-wall or north-wall installations.'
+  ),
+});
+
+const UpdateCabinetCoordinatesSchema = z.object({
+  orderId: z.string().describe(
+    'Order ID or saved cart tempOrderId whose coordinates will be replaced. ' +
+    'Accepts both placed order IDs (e.g. "307104_v2") and saved cart reference IDs (e.g. "623265"). ' +
+    'Use the saved cart tempOrderId to set coordinates on a cart BEFORE submitting — ' +
+    'this is the correct workflow so coordinates are passed directly to the XML at submit time.'
+  ),
+  coordinates: z.array(CoordinateItemSchema).describe(
+    'Full replacement list of cabinet coordinates. ALL existing coordinates for this order or cart are deleted ' +
+    'and replaced with this list. Omit a cabinet from this list to remove its stored coordinates.'
+  ),
+});
+
+const PatchCabinetCoordinatesSchema = z.object({
+  orderId: z.string().describe(
+    'Order ID or saved cart tempOrderId whose coordinates will be partially updated. ' +
+    'Accepts both placed order IDs (e.g. "307104_v2") and saved cart reference IDs (e.g. "623265").'
+  ),
+  coordinates: z.array(CoordinateItemSchema).min(1).describe(
+    'Partial list of cabinet coordinates to update. Only the positionNames included here are affected — ' +
+    'all other cabinets keep their existing coordinates unchanged. ' +
+    'Use this tool instead of update_cabinet_coordinates when you need to move or reposition one or a few ' +
+    'cabinets without disturbing the rest of the layout.'
+  ),
+});
+
+
+const UploadCanvasBackgroundSchema = z.object({
+  orderId: z.string().describe('Order ID whose canvas background image will be replaced.'),
+  canvasType: z.enum(['plan', 'north', 'south', 'east', 'west']).describe(
+    'Canvas type to upload the background image for. ' +
+    '"plan" is the floor plan view; "north", "south", "east", "west" are elevation views.'
+  ),
+  imagePath: z.string().describe(
+    'Absolute path to the image file on the local filesystem. ' +
+    'Supported formats: .png, .jpg / .jpeg, .webp. ' +
+    'The MCP server reads and encodes the file — do not convert it yourself. ' +
+    'The existing background image for this canvas type is automatically deleted from S3 and replaced.'
+  ),
+});
+
+const CanvasMetadataFieldsSchema = z.object({
+  orderId: z.string().describe('Order ID whose canvas metadata will be replaced.'),
+  canvasMeta: z.record(z.unknown()).optional().describe(
+    'Per-canvas display metadata keyed by canvas type (plan, north, south, east, west). ' +
+    'Each entry contains scale (ratio, unit), position (x, y), rotation, zoom, and backgroundImage (S3 URL).'
+  ),
+  z0References: z.record(z.unknown()).optional().describe(
+    'Floor reference line calibration per elevation canvas. ' +
+    'Each entry contains imagePercentFromBottom, originalImageDimensions, realWorldHeight, and timestamp.'
+  ),
+  verticalCalibration: z.record(z.unknown()).optional().describe(
+    'Vertical height mapping calibration per elevation canvas. ' +
+    'Each entry contains scale, offset, unit, and timestamp.'
+  ),
+  elevationVisibility: z.record(z.unknown()).optional().describe(
+    'Item visibility per elevation, keyed by itemId. ' +
+    'Each entry is a map of elevation name to boolean (e.g. {"north": true, "south": false}).'
+  ),
+  calibrationOffsets: z.record(z.unknown()).optional().describe(
+    'Coordinate positioning offsets per canvas type. ' +
+    'Each entry contains x and y offset values in pixels.'
+  ),
+  itemRotations: z.record(z.unknown()).optional().describe(
+    'Item-specific rotation values keyed by itemId. Values are rotation in degrees.'
+  ),
+  activeCanvases: z.array(z.string()).optional().describe(
+    'List of active canvas types. Valid values: "plan", "north", "south", "east", "west".'
+  ),
+  fixedElevationPositions: z.record(z.unknown()).optional().describe(
+    'Pinned cabinet positions after global calibration, keyed by elevation then positionName. ' +
+    'Each position entry contains x and y pixel coordinates.'
+  ),
+  elevationCalibrated: z.record(z.unknown()).optional().describe(
+    'Global calibration status per elevation. Keys are elevation names, values are booleans.'
+  ),
+  globalElevationOffsets: z.record(z.unknown()).optional().describe(
+    'Coordinate system transformations per elevation (maps plan coordinates to elevation coordinates). ' +
+    'Each entry contains x and y offset values in inches.'
+  ),
+  calibratedCabinets: z.record(z.unknown()).optional().describe(
+    'Which cabinets have been globally calibrated per elevation. ' +
+    'Keyed by elevation then positionName, values are booleans.'
+  ),
+});
+
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+
+async function getDrawingToolState(input: z.infer<typeof GetDrawingToolStateSchema>): Promise<string> {
+  try {
+    const { data } = await client.get(`/canvas/${input.orderId}`);
+    return JSON.stringify(data, null, 2);
+  } catch (error) {
+    try { handleAxiosError(error); } catch (e: any) { return e.message; }
+    return 'Unexpected error fetching drawing tool state.';
+  }
+}
+
+async function getCanvasMetadata(input: z.infer<typeof GetCanvasMetadataSchema>): Promise<string> {
+  try {
+    const { data } = await client.get(`/canvas/${input.orderId}/metadata`);
+    return JSON.stringify(data, null, 2);
+  } catch (error) {
+    try { handleAxiosError(error); } catch (e: any) { return e.message; }
+    return 'Unexpected error fetching canvas metadata.';
+  }
+}
+
+async function updateCanvasMetadata(input: z.infer<typeof CanvasMetadataFieldsSchema>): Promise<string> {
+  const { orderId, ...fields } = input;
+  try {
+    const { data } = await client.put(`/canvas/${orderId}/metadata`, fields);
+    return JSON.stringify(data, null, 2);
+  } catch (error) {
+    try { handleAxiosError(error); } catch (e: any) { return e.message; }
+    return 'Unexpected error updating canvas metadata.';
+  }
+}
+
+async function getCanvasImages(input: z.infer<typeof GetCanvasImagesSchema>): Promise<string> {
+  try {
+    const { data } = await client.get(`/canvas/${input.orderId}/images`);
+    return JSON.stringify(data, null, 2);
+  } catch (error) {
+    try { handleAxiosError(error); } catch (e: any) { return e.message; }
+    return 'Unexpected error fetching canvas images.';
+  }
+}
+
+async function getCabinetCoordinates(input: z.infer<typeof GetCabinetCoordinatesSchema>): Promise<string> {
+  try {
+    const { data } = await client.get(`/canvas/${input.orderId}/coordinates`);
+    return JSON.stringify(data, null, 2);
+  } catch (error) {
+    try { handleAxiosError(error); } catch (e: any) { return e.message; }
+    return 'Unexpected error fetching cabinet coordinates.';
+  }
+}
+
+async function updateCabinetCoordinates(input: z.infer<typeof UpdateCabinetCoordinatesSchema>): Promise<string> {
+  try {
+    const { data } = await client.put(`/canvas/${input.orderId}/coordinates`, input.coordinates);
+    return JSON.stringify(data, null, 2);
+  } catch (error) {
+    try { handleAxiosError(error); } catch (e: any) { return e.message; }
+    return 'Unexpected error updating cabinet coordinates.';
+  }
+}
+
+async function patchCabinetCoordinates(input: z.infer<typeof PatchCabinetCoordinatesSchema>): Promise<string> {
+  try {
+    const { data } = await client.patch(`/canvas/${input.orderId}/coordinates`, input.coordinates);
+    return JSON.stringify(data, null, 2);
+  } catch (error) {
+    try { handleAxiosError(error); } catch (e: any) { return e.message; }
+    return 'Unexpected error patching cabinet coordinates.';
+  }
+}
+
+
+const MIME_TYPES: Record<string, string> = {
+  '.png':  'image/png',
+  '.jpg':  'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.webp': 'image/webp',
+};
+
+async function uploadCanvasBackground(input: z.infer<typeof UploadCanvasBackgroundSchema>): Promise<string> {
+  const ext = path.extname(input.imagePath).toLowerCase();
+  const mimeType = MIME_TYPES[ext];
+  if (!mimeType) {
+    return `Unsupported file extension "${ext}". Supported: .png, .jpg, .jpeg, .webp`;
+  }
+
+  if (!fs.existsSync(input.imagePath)) {
+    return `File not found at "${input.imagePath}"`;
+  }
+
+  const form = new FormData();
+  form.append('file', fs.createReadStream(input.imagePath), {
+    filename: path.basename(input.imagePath),
+    contentType: mimeType,
+  });
+
+  try {
+    const { data } = await client.post(
+      `/canvas/${input.orderId}/images/${input.canvasType}/background`,
+      form,
+      { headers: form.getHeaders() }
+    );
+    return JSON.stringify(data, null, 2);
+  } catch (error) {
+    try { handleAxiosError(error); } catch (e: any) { return e.message; }
+    return 'Unexpected error uploading canvas background image.';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+export const canvasTools = [
+  {
+    name: 'get_drawing_tool_state',
+    description:
+      'Retrieve the full drawing tool state for an order in a single call. ' +
+      'Returns 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 (plan, north, south, east, west); ' +
+      '(3) coordinates — all cabinet positions (center X, back-edge Y, Z height, rotation) keyed by positionName. ' +
+      'Returns 404 if no drawing tool state exists for this order.',
+    inputSchema: GetDrawingToolStateSchema,
+    handler: getDrawingToolState,
+  },
+  {
+    name: 'get_canvas_metadata',
+    description:
+      'Retrieve canvas metadata for an order. ' +
+      'Includes: activeCanvases, canvasMeta (scale/position/zoom per canvas), z0References (floor calibration per elevation), ' +
+      'verticalCalibration, elevationVisibility (which cabinets are visible on which elevations), ' +
+      'calibrationOffsets, itemRotations, fixedElevationPositions, elevationCalibrated, ' +
+      'globalElevationOffsets, and calibratedCabinets. ' +
+      'Use get_drawing_tool_state if you also need images and coordinates.',
+    inputSchema: GetCanvasMetadataSchema,
+    handler: getCanvasMetadata,
+  },
+  {
+    name: 'update_canvas_metadata',
+    description:
+      'Replace all canvas metadata fields for an order. ' +
+      'All existing metadata is overwritten with the provided values. ' +
+      'Fields not included in the request are set to null — provide all fields you want to preserve. ' +
+      'Use get_canvas_metadata first to read the current state before making targeted updates.',
+    inputSchema: CanvasMetadataFieldsSchema,
+    handler: updateCanvasMetadata,
+  },
+  {
+    name: 'get_canvas_images',
+    description:
+      'Retrieve canvas image records for an order. ' +
+      'Returns a list of entries each containing canvasType (plan/north/south/east/west), ' +
+      'imageType (background/snapshot), and s3Key (the S3 path to the image file). ' +
+      'Background images are the floor plan or elevation photos used for cabinet placement. ' +
+      'Snapshot images are rendered exports of the canvas used in order submission.',
+    inputSchema: GetCanvasImagesSchema,
+    handler: getCanvasImages,
+  },
+  {
+    name: 'get_cabinet_coordinates',
+    description:
+      'Retrieve all stored cabinet coordinates for an order. ' +
+      'Each entry contains positionName, x (center X in inches), y (back-edge Y / depth-direction in inches), ' +
+      'z (height from floor in inches), and rotation (degrees). ' +
+      'Note: x is center X, not bottom-left. Y is back-edge coordinate (distance from south wall to cabinet BACK). ' +
+      'Use these values directly in update_cabinet_coordinates for round-trip operations.',
+    inputSchema: GetCabinetCoordinatesSchema,
+    handler: getCabinetCoordinates,
+  },
+  {
+    name: 'update_cabinet_coordinates',
+    description:
+      'Replace all cabinet coordinates for a placed order OR a saved cart. ' +
+      'Accepts both placed order IDs and saved cart tempOrderIds. ' +
+      '\n\n' +
+      'CORRECT WORKFLOW FOR SAVED CARTS:\n' +
+      '1. create_edit_cart (or use existing saved cart tempOrderId)\n' +
+      '2. update_cabinet_coordinates(tempOrderId, [...]) ← call this tool with the cart tempOrderId\n' +
+      '3. submit_cart_as_version — coordinates stored on the cart are picked up and written to the XML\n' +
+      'Do NOT submit first and update coordinates after — that requires a second redundant version.\n' +
+      '\n' +
+      'MULTI-QUANTITY ARTICLES: When a cabinet was added with quantity > 1, the server expanded it into\n' +
+      'individual articles with incrementing suffixes. Example: positionName "DR_B2_01" with quantity=3\n' +
+      'produces three separate cabinets: "DR_B2_01", "DR_B2_02", "DR_B2_03". This tool does NOT\n' +
+      'auto-expand — you must list every expanded name explicitly. Setting coordinates only for\n' +
+      '"DR_B2_01" leaves "DR_B2_02" and "DR_B2_03" without coordinates in the CAD file.\n' +
+      'Rule: for each article with quantity=N, include N entries — one per expanded positionName.\n' +
+      '\n' +
+      'All existing coordinates are deleted and replaced with the provided list.\n' +
+      'x = back-edge X in inches:\n' +
+      '  North/South wall: x = D_adj_west + cumulative_widths_left + this_width/2 (position along wall).  D_adj_west = west wall cabinet depth, else 0.\n' +
+      '    D_adj_west applies ONLY to north/south wall x — NEVER to east/west wall x.\n' +
+      '  West wall — base: x = 0 (back against west wall).  Upper front-flush: x = base_depth - upper_depth.\n' +
+      '  East wall — base: x = room_width (back against east wall).  Upper front-flush: x = base_x - (base_depth - upper_depth).\n' +
+      '  CRITICAL: For upper cabinets, use x = base_x - (base_depth - upper_depth). For west wall where base_x=0, simplifies to x = base_depth - upper_depth.\n' +
+      'y = back-edge Y in inches — ABSOLUTE room coordinate (0 = south wall face, room_depth = north wall face):\n' +
+      '  South wall — base: y = 0 (back against south wall).  Upper front-flush: y = base_depth - upper_depth.\n' +
+      '  North wall — base: y = room_depth (back against north wall).  Upper front-flush: y = base_y - (base_depth - upper_depth).\n' +
+      '  CRITICAL: For upper cabinets, use y = base_y - (base_depth - upper_depth). For south wall where base_y=0, simplifies to y = base_depth - upper_depth.\n' +
+      '  East/West wall: cabinets run north-to-south (decreasing y). List them northernmost first.\n' +
+      '    D_adj_north = north wall cabinet depth if present, else 0.\n' +
+      '    Northernmost cabinet: y = room_depth - D_adj_north - this_width/2.\n' +
+      '    Each next going south: y = room_depth - D_adj_north - (sum of widths of all preceding cabinets) - this_width/2.\n' +
+      '    y DECREASES going south. NEVER add widths — adding goes north (wrong direction).\n' +
+      '    UPPER cabinets: y = same as the base cabinet at that position. Front-flush = x change only, NOT y.\n' +
+      '    Do NOT apply north/south front-flush y formulas to east/west wall cabinets.\n' +
+      'z = height from floor in inches (0 for base cabinets on the floor).\n' +
+      'rotation: 0=north wall, 90=east wall, 180=south wall, 270=west wall.\n' +
+      'To remove a cabinet\'s coordinates, omit it from the list.\n' +
+      'Call get_cabinet_coordinates first to read current positions before making targeted changes.',
+    inputSchema: UpdateCabinetCoordinatesSchema,
+    handler: updateCabinetCoordinates,
+  },
+  {
+    name: 'patch_cabinet_coordinates',
+    description:
+      'Partially update cabinet coordinates for specific cabinets only. ' +
+      'Only the positionNames you include are affected — all other cabinets keep their existing coordinates unchanged. ' +
+      '\n\n' +
+      'Use this tool when:\n' +
+      '- You need to move or reposition one or a few cabinets without disturbing the rest of the layout\n' +
+      '- The user says "move cabinet X to position Y" or "adjust the coordinates for Base_01"\n' +
+      '\n' +
+      'Use update_cabinet_coordinates (PUT) instead when:\n' +
+      '- You are setting coordinates for the first time on a new cart or order (full replacement is correct)\n' +
+      '- You want to remove a cabinet\'s coordinates (omit it from the full replacement list)\n' +
+      '\n' +
+      'The response includes "patched" (count of positions you sent), "total" (all coordinates now stored), ' +
+      'and the full updated coordinate list is broadcast to the frontend in real time via WebSocket.\n' +
+      '\n' +
+      'MULTI-QUANTITY ARTICLES: Same rule as update_cabinet_coordinates — if a cabinet was expanded server-side ' +
+      'from qty>1 (e.g. "DR_B2_01" qty=3 → "DR_B2_01", "DR_B2_02", "DR_B2_03"), each expanded name is a ' +
+      'separate entry. To move all three, include all three in the coordinates list.',
+    inputSchema: PatchCabinetCoordinatesSchema,
+    handler: patchCabinetCoordinates,
+  },
+  {
+    name: 'upload_canvas_background_image',
+    description:
+      'Upload a background image for a specific canvas (plan or elevation view) from a local file path. ' +
+      'Provide the absolute path to the image file — the MCP server reads and encodes it automatically. ' +
+      'Supported formats: .png, .jpg / .jpeg, .webp. ' +
+      'The existing background image for this canvas type is automatically removed from S3 and replaced. ' +
+      'Canvas defaults (scale ratio 1, zoom 1, position 0/0) are initialized automatically for the uploaded ' +
+      'canvas type. The canvas is added to activeCanvases so the user sees it when they open the order — ' +
+      'no separate initialization step is needed. Call this once per canvas type you want to populate. ' +
+      'After upload the drawing tool is notified in real time via WebSocket. ' +
+      'Use get_canvas_images to check the current image before replacing.',
+    inputSchema: UploadCanvasBackgroundSchema,
+    handler: uploadCanvasBackground,
+  },
+];

package/src/tools/catalog.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import * as apiClientModule from '../client/api-client';
+
+// Mock the client module
+vi.mock('../client/api-client', () => ({
+  client: { get: vi.fn() },
+  handleAxiosError: vi.fn((e) => { throw e; }),
+  McpApiError: class McpApiError extends Error {
+    constructor(public status: number, message: string) { super(message); }
+  },
+}));
+
+import { searchCatalog, getArticle, listFilterTags } from './catalog';
+
+describe('searchCatalog', () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it('calls /catalog/search with query param', async () => {
+    const mockGet = vi.mocked(apiClientModule.client.get);
+    mockGet.mockResolvedValue({ data: [{ serialNumber: 'B30', displayName: 'Base 30' }] });
+
+    const result = await searchCatalog({ q: 'base' });
+
+    expect(mockGet).toHaveBeenCalledWith('/catalog/search', expect.objectContaining({
+      params: expect.objectContaining({ q: 'base' }),
+    }));
+    expect(result).toContain('B30');
+  });
+
+  it('returns error text on 401', async () => {
+    const mockGet = vi.mocked(apiClientModule.client.get);
+    const err = new (apiClientModule.McpApiError as any)(401, 'Invalid API key');
+    mockGet.mockRejectedValue(err);
+    vi.mocked(apiClientModule.handleAxiosError).mockImplementation(() => { throw err; });
+
+    const result = await searchCatalog({ q: 'base' });
+    expect(result).toContain('Invalid API key');
+  });
+});
+
+describe('getArticle', () => {
+  it('returns article details', async () => {
+    const mockGet = vi.mocked(apiClientModule.client.get);
+    mockGet.mockResolvedValue({ data: { serialNumber: 'B30', displayName: 'Base 30', heightRange: '700-900' } });
+
+    const result = await getArticle({ serialNumber: 'B30' });
+    expect(result).toContain('B30');
+    expect(result).toContain('700-900');
+  });
+});
+
+describe('listFilterTags', () => {
+  it('returns tags as formatted list', async () => {
+    const mockGet = vi.mocked(apiClientModule.client.get);
+    mockGet.mockResolvedValue({ data: ['BASE', 'WALL', 'PANTRY'] });
+
+    const result = await listFilterTags({});
+    expect(result).toContain('BASE');
+    expect(result).toContain('WALL');
+  });
+});