@sealab/mcp-server 1.0.0

package/dist/client/api-client.js

@@ -0,0 +1,44 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpApiError = exports.client = void 0;
+exports.handleAxiosError = handleAxiosError;
+const axios_1 = __importDefault(require("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');
+}
+exports.client = axios_1.default.create({
+    baseURL: `${API_URL}/api/mcp/v1`,
+    headers: {
+        'X-API-Key': API_KEY,
+    },
+    timeout: 10000,
+});
+class McpApiError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = 'McpApiError';
+    }
+}
+exports.McpApiError = McpApiError;
+function handleAxiosError(error) {
+    if (axios_1.default.isAxiosError(error)) {
+        const axiosErr = error;
+        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/dist/index.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const zod_to_json_schema_1 = require("zod-to-json-schema");
+const catalog_1 = require("./tools/catalog");
+const orders_1 = require("./tools/orders");
+const configuration_1 = require("./tools/configuration");
+const configuration_info_1 = require("./tools/configuration-info");
+const saved_settings_1 = require("./tools/saved-settings");
+const canvas_1 = require("./tools/canvas");
+const allTools = [...catalog_1.catalogTools, ...orders_1.orderTools, ...configuration_1.configurationTools, ...configuration_info_1.configurationInfoTools, ...saved_settings_1.savedSettingsTools, ...canvas_1.canvasTools];
+const server = new index_js_1.Server({ name: 'sealab', version: '1.0.0' }, { capabilities: { tools: {} } });
+server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+    tools: allTools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: (0, zod_to_json_schema_1.zodToJsonSchema)(t.inputSchema, { target: 'openApi3' }),
+    })),
+}));
+server.setRequestHandler(types_js_1.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(parsed.data);
+    return { content: [{ type: 'text', text: result }] };
+});
+async function main() {
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch(console.error);

package/dist/tools/canvas.js

@@ -0,0 +1,446 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canvasTools = void 0;
+const zod_1 = require("zod");
+const api_client_1 = require("../client/api-client");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const form_data_1 = __importDefault(require("form-data"));
+// ---------------------------------------------------------------------------
+// Schemas
+// ---------------------------------------------------------------------------
+const GetDrawingToolStateSchema = zod_1.z.object({
+    orderId: zod_1.z.string().describe('Order ID to retrieve full drawing tool state for (metadata + images + coordinates).'),
+});
+const GetCanvasMetadataSchema = zod_1.z.object({
+    orderId: zod_1.z.string().describe('Order ID to retrieve canvas metadata for.'),
+});
+const GetCanvasImagesSchema = zod_1.z.object({
+    orderId: zod_1.z.string().describe('Order ID to retrieve canvas image records for.'),
+});
+const GetCabinetCoordinatesSchema = zod_1.z.object({
+    orderId: zod_1.z.string().describe('Order ID to retrieve cabinet coordinates for.'),
+});
+const CoordinateItemSchema = zod_1.z.object({
+    positionName: zod_1.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: zod_1.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: zod_1.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: zod_1.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: zod_1.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 = zod_1.z.object({
+    orderId: zod_1.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: zod_1.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 = zod_1.z.object({
+    orderId: zod_1.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: zod_1.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 = zod_1.z.object({
+    orderId: zod_1.z.string().describe('Order ID whose canvas background image will be replaced.'),
+    canvasType: zod_1.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: zod_1.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 = zod_1.z.object({
+    orderId: zod_1.z.string().describe('Order ID whose canvas metadata will be replaced.'),
+    canvasMeta: zod_1.z.record(zod_1.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: zod_1.z.record(zod_1.z.unknown()).optional().describe('Floor reference line calibration per elevation canvas. ' +
+        'Each entry contains imagePercentFromBottom, originalImageDimensions, realWorldHeight, and timestamp.'),
+    verticalCalibration: zod_1.z.record(zod_1.z.unknown()).optional().describe('Vertical height mapping calibration per elevation canvas. ' +
+        'Each entry contains scale, offset, unit, and timestamp.'),
+    elevationVisibility: zod_1.z.record(zod_1.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: zod_1.z.record(zod_1.z.unknown()).optional().describe('Coordinate positioning offsets per canvas type. ' +
+        'Each entry contains x and y offset values in pixels.'),
+    itemRotations: zod_1.z.record(zod_1.z.unknown()).optional().describe('Item-specific rotation values keyed by itemId. Values are rotation in degrees.'),
+    activeCanvases: zod_1.z.array(zod_1.z.string()).optional().describe('List of active canvas types. Valid values: "plan", "north", "south", "east", "west".'),
+    fixedElevationPositions: zod_1.z.record(zod_1.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: zod_1.z.record(zod_1.z.unknown()).optional().describe('Global calibration status per elevation. Keys are elevation names, values are booleans.'),
+    globalElevationOffsets: zod_1.z.record(zod_1.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: zod_1.z.record(zod_1.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) {
+    try {
+        const { data } = await api_client_1.client.get(`/canvas/${input.orderId}`);
+        return JSON.stringify(data, null, 2);
+    }
+    catch (error) {
+        try {
+            (0, api_client_1.handleAxiosError)(error);
+        }
+        catch (e) {
+            return e.message;
+        }
+        return 'Unexpected error fetching drawing tool state.';
+    }
+}
+async function getCanvasMetadata(input) {
+    try {
+        const { data } = await api_client_1.client.get(`/canvas/${input.orderId}/metadata`);
+        return JSON.stringify(data, null, 2);
+    }
+    catch (error) {
+        try {
+            (0, api_client_1.handleAxiosError)(error);
+        }
+        catch (e) {
+            return e.message;
+        }
+        return 'Unexpected error fetching canvas metadata.';
+    }
+}
+async function updateCanvasMetadata(input) {
+    const { orderId, ...fields } = input;
+    try {
+        const { data } = await api_client_1.client.put(`/canvas/${orderId}/metadata`, fields);
+        return JSON.stringify(data, null, 2);
+    }
+    catch (error) {
+        try {
+            (0, api_client_1.handleAxiosError)(error);
+        }
+        catch (e) {
+            return e.message;
+        }
+        return 'Unexpected error updating canvas metadata.';
+    }
+}
+async function getCanvasImages(input) {
+    try {
+        const { data } = await api_client_1.client.get(`/canvas/${input.orderId}/images`);
+        return JSON.stringify(data, null, 2);
+    }
+    catch (error) {
+        try {
+            (0, api_client_1.handleAxiosError)(error);
+        }
+        catch (e) {
+            return e.message;
+        }
+        return 'Unexpected error fetching canvas images.';
+    }
+}
+async function getCabinetCoordinates(input) {
+    try {
+        const { data } = await api_client_1.client.get(`/canvas/${input.orderId}/coordinates`);
+        return JSON.stringify(data, null, 2);
+    }
+    catch (error) {
+        try {
+            (0, api_client_1.handleAxiosError)(error);
+        }
+        catch (e) {
+            return e.message;
+        }
+        return 'Unexpected error fetching cabinet coordinates.';
+    }
+}
+async function updateCabinetCoordinates(input) {
+    try {
+        const { data } = await api_client_1.client.put(`/canvas/${input.orderId}/coordinates`, input.coordinates);
+        return JSON.stringify(data, null, 2);
+    }
+    catch (error) {
+        try {
+            (0, api_client_1.handleAxiosError)(error);
+        }
+        catch (e) {
+            return e.message;
+        }
+        return 'Unexpected error updating cabinet coordinates.';
+    }
+}
+async function patchCabinetCoordinates(input) {
+    try {
+        const { data } = await api_client_1.client.patch(`/canvas/${input.orderId}/coordinates`, input.coordinates);
+        return JSON.stringify(data, null, 2);
+    }
+    catch (error) {
+        try {
+            (0, api_client_1.handleAxiosError)(error);
+        }
+        catch (e) {
+            return e.message;
+        }
+        return 'Unexpected error patching cabinet coordinates.';
+    }
+}
+const MIME_TYPES = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.webp': 'image/webp',
+};
+async function uploadCanvasBackground(input) {
+    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 form_data_1.default();
+    form.append('file', fs.createReadStream(input.imagePath), {
+        filename: path.basename(input.imagePath),
+        contentType: mimeType,
+    });
+    try {
+        const { data } = await api_client_1.client.post(`/canvas/${input.orderId}/images/${input.canvasType}/background`, form, { headers: form.getHeaders() });
+        return JSON.stringify(data, null, 2);
+    }
+    catch (error) {
+        try {
+            (0, api_client_1.handleAxiosError)(error);
+        }
+        catch (e) {
+            return e.message;
+        }
+        return 'Unexpected error uploading canvas background image.';
+    }
+}
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+exports.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/dist/tools/catalog.js

@@ -0,0 +1,95 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.catalogTools = void 0;
+exports.searchCatalog = searchCatalog;
+exports.getArticle = getArticle;
+exports.listFilterTags = listFilterTags;
+const zod_1 = require("zod");
+const api_client_1 = require("../client/api-client");
+// --- Schemas ---
+const SearchSchema = zod_1.z.object({
+    q: zod_1.z.string().optional().describe('Keyword search query'),
+    tags: zod_1.z.array(zod_1.z.string()).optional().describe('Filter by tag (e.g. BASE, WALL, PANTRY)'),
+    minH: zod_1.z.number().optional().describe('Minimum height in inches'),
+    maxH: zod_1.z.number().optional().describe('Maximum height in inches'),
+    minW: zod_1.z.number().optional().describe('Minimum width in inches'),
+    maxW: zod_1.z.number().optional().describe('Maximum width in inches'),
+    minD: zod_1.z.number().optional().describe('Minimum depth in inches'),
+    maxD: zod_1.z.number().optional().describe('Maximum depth in inches'),
+});
+const GetArticleSchema = zod_1.z.object({
+    serialNumber: zod_1.z.string().describe('Article serial number, e.g. B30'),
+});
+const ListFilterTagsSchema = zod_1.z.object({});
+// --- Handlers ---
+async function searchCatalog(input) {
+    try {
+        const { data } = await api_client_1.client.get('/catalog/search', {
+            params: { ...input },
+            paramsSerializer: { indexes: null }, // produces tags=BASE&tags=WALL (not tags[]=)
+        });
+        if (!data || data.length === 0)
+            return 'No articles found matching your search.';
+        return JSON.stringify(data, null, 2);
+    }
+    catch (error) {
+        try {
+            (0, api_client_1.handleAxiosError)(error);
+        }
+        catch (e) {
+            return e.message;
+        }
+        return 'Unexpected error searching catalog.';
+    }
+}
+async function getArticle(input) {
+    try {
+        const { data } = await api_client_1.client.get(`/catalog/${input.serialNumber}`);
+        return JSON.stringify(data, null, 2);
+    }
+    catch (error) {
+        try {
+            (0, api_client_1.handleAxiosError)(error);
+        }
+        catch (e) {
+            return e.message;
+        }
+        return 'Unexpected error fetching article.';
+    }
+}
+async function listFilterTags(_input) {
+    try {
+        const { data } = await api_client_1.client.get('/catalog/filter-tags');
+        return data.join('\n');
+    }
+    catch (error) {
+        try {
+            (0, api_client_1.handleAxiosError)(error);
+        }
+        catch (e) {
+            return e.message;
+        }
+        return 'Unexpected error fetching filter tags.';
+    }
+}
+// --- Tool definitions (consumed by index.ts) ---
+exports.catalogTools = [
+    {
+        name: 'search_catalog',
+        description: 'Search the Sealab cabinetry catalog by keyword, filter tags, or dimension ranges. Returns matching articles with serial numbers, dimensions, and feature flags.',
+        inputSchema: SearchSchema,
+        handler: searchCatalog,
+    },
+    {
+        name: 'get_article',
+        description: 'Get full details for a single cabinet article by its serial number.',
+        inputSchema: GetArticleSchema,
+        handler: getArticle,
+    },
+    {
+        name: 'list_filter_tags',
+        description: 'List all available filter tag categories in the catalog (e.g. BASE, WALL, PANTRY, TALL).',
+        inputSchema: ListFilterTagsSchema,
+        handler: listFilterTags,
+    },
+];