@sealab/mcp-server 1.0.0

package/PROPOSED-CHANGES-INSERTION-POINTS.md

@@ -0,0 +1,220 @@
+# Proposed MCP Changes — Insertion Point Accuracy & Bi-Directional Sync
+
+**Date**: 2026-03-27
+**Author**: Openclaw integration review
+**Status**: DRAFT — for review and implementation at a later date
+**Priority**: High — blocks accurate coordinate round-tripping between Openclaw agent and Sealab platform
+
+---
+
+## Context
+
+The Openclaw proposal engine extracts cabinet insertion points from architectural drawings and submits them to the Sealab MCP via `create_order` / `create_saved_cart`. The Sealab drawing tool allows users to interactively adjust these positions. Currently there is no formal mechanism to:
+
+1. Confirm that submitted coordinates were received and stored correctly
+2. Read back modified coordinates and propagate changes to the Openclaw database
+3. Handle the coordinate space conversion (bottom-left → center X) in a way that is explicit and auditable
+
+---
+
+## Proposed Change 1: Add Coordinate Acknowledgment to Order Response
+
+### Current Behavior
+`POST /orders` returns the created order with articles, but does not echo back the stored coordinates in a normalized form.
+
+### Proposed Behavior
+The order creation response should include a `coordinates` field confirming what was stored:
+
+```json
+{
+  "orderId": "ORD-123",
+  "articles": [...],
+  "coordinates": [
+    {
+      "positionName": "UFAS.B1",
+      "stored_x_center": 15.0,
+      "stored_y_center": 12.0,
+      "stored_z": 0,
+      "stored_rotation": 0,
+      "input_x_bottomleft": 0.0,
+      "input_z_height": 0,
+      "conversion_applied": "center_x = input_x + width/2 = 0.0 + 30/2 = 15.0"
+    }
+  ]
+}
+```
+
+### Why
+This allows the Openclaw agent to verify that the coordinate conversion was applied correctly at submission time, without requiring a separate `get_cabinet_coordinates` call.
+
+### Files to Modify
+- `src/tools/orders.ts` — Add coordinate echo to `createOrder` and `createSavedCart` response handlers
+
+---
+
+## Proposed Change 2: Add `last_modified_at` Timestamp to Canvas Coordinates
+
+### Current Behavior
+`GET /canvas/{orderId}/coordinates` returns position, x, y, z, rotation — but no timestamp indicating when the coordinates were last changed.
+
+### Proposed Behavior
+Each coordinate entry should include a `lastModifiedAt` ISO timestamp:
+
+```json
+{
+  "positionName": "UFAS.B1",
+  "x": 15.0,
+  "y": 12.0,
+  "z": 0,
+  "rotation": 0,
+  "lastModifiedAt": "2026-03-27T14:30:00Z"
+}
+```
+
+### Why
+The Openclaw sync module needs to determine whether a coordinate was modified since the last sync. Without timestamps, the only option is full-diff comparison, which cannot distinguish "user intentionally set it back to the original value" from "no change."
+
+### Files to Modify
+- `src/tools/canvas.ts` — Add `lastModifiedAt` to `CoordinateItemSchema`
+- Backend API: Ensure the `/canvas/{orderId}/coordinates` endpoint populates timestamps
+
+---
+
+## Proposed Change 3: Add Coordinate Diff Endpoint
+
+### Current Behavior
+To detect changes, the Openclaw agent must:
+1. Call `get_cabinet_coordinates`
+2. Compare every value against its local state
+3. Compute diffs manually
+
+### Proposed Behavior
+Add a new tool `diff_cabinet_coordinates` that accepts the agent's current known coordinates and returns only the differences:
+
+```typescript
+const DiffCabinetCoordinatesSchema = z.object({
+  orderId: z.string(),
+  knownCoordinates: z.array(z.object({
+    positionName: z.string(),
+    x: z.number(),
+    y: z.number(),
+    z: z.number(),
+    rotation: z.number(),
+    lastSyncedAt: z.string().optional(),
+  })),
+});
+```
+
+Response:
+```json
+{
+  "changed": [
+    {
+      "positionName": "UFAS.B3",
+      "field": "x",
+      "old_value": 45.0,
+      "new_value": 46.5,
+      "changed_at": "2026-03-27T15:00:00Z"
+    }
+  ],
+  "added": [],
+  "removed": [],
+  "unchanged_count": 7
+}
+```
+
+### Why
+Reduces token cost and network overhead for the sync module. Instead of transferring all coordinates and diffing locally, the MCP does the comparison server-side.
+
+### Files to Modify
+- `src/tools/canvas.ts` — Add `diff_cabinet_coordinates` tool
+- `src/index.ts` — Register new tool
+
+---
+
+## Proposed Change 4: Support Batch Coordinate Read Across Multiple Orders
+
+### Current Behavior
+`get_cabinet_coordinates` works for one order at a time. For 24 orders, the agent must make 24 sequential calls.
+
+### Proposed Behavior
+Add `get_cabinet_coordinates_batch`:
+
+```typescript
+const GetBatchCoordinatesSchema = z.object({
+  orderIds: z.array(z.string()).max(50),
+});
+```
+
+Response: Map of orderId → coordinates array.
+
+### Why
+The Openclaw system manages 24+ orders per project. Batch retrieval reduces API calls from 24 to 1 during sync.
+
+### Files to Modify
+- `src/tools/canvas.ts` — Add batch retrieval tool
+- `src/index.ts` — Register new tool
+
+---
+
+## Proposed Change 5: Document the Coordinate Convention in orders.ts
+
+### Current Issue
+The `ArticleItemSchema` comments (lines 230-235) describe x, z, y conventions but do not explicitly state:
+- That `x` is wall-local (not kitchen-local)
+- How `x` relates to the canvas center X
+- That the server performs the bottom-left → center conversion
+
+### Proposed Enhancement
+Add a detailed JSDoc block above the insertion point fields:
+
+```typescript
+/**
+ * INSERTION POINT COORDINATE CONVENTION
+ *
+ * Input (order creation):
+ *   x = bottom-left corner X from left wall edge (wall-local cumulative position)
+ *   z = height from floor (0 for base cabinets)
+ *   y = NOT provided — server computes as depth/2
+ *   rotation = degrees (0, 90, 180, 270)
+ *
+ * Storage (canvas):
+ *   x = center X = input_x + (width / 2)
+ *   y = depth / 2
+ *   z = input_z (unchanged)
+ *   rotation = unchanged
+ *
+ * Round-trip:
+ *   When reading from get_cabinet_coordinates, x is center X.
+ *   When writing to update_cabinet_coordinates, x must be center X.
+ *   When creating new orders, x must be bottom-left corner X.
+ *
+ * For multi-wall kitchens:
+ *   x is ALWAYS relative to the wall the cabinet is on, not kitchen-global.
+ *   The rotation field identifies which wall (0=south, 90=east, 180=north, 270=west).
+ */
+```
+
+### Files to Modify
+- `src/tools/orders.ts` — Add documentation block above line 230
+
+---
+
+## Implementation Priority
+
+| Change | Impact | Effort | Priority |
+|--------|--------|--------|----------|
+| 5. Document conventions | High (prevents bugs) | Low | P0 — do first |
+| 1. Coordinate acknowledgment | Medium (verification) | Medium | P1 |
+| 2. Timestamps on coordinates | High (sync correctness) | Medium | P1 |
+| 3. Diff endpoint | Medium (efficiency) | Medium | P2 |
+| 4. Batch read | Low (convenience) | Low | P2 |
+
+---
+
+## Notes
+
+- None of these changes break existing API contracts — all are additive
+- Change 5 (documentation) can be done immediately with zero risk
+- Changes 1-4 require backend API modifications in addition to MCP tool changes
+- The Openclaw sync module will be built to work without changes 3-4 initially (using individual `get_cabinet_coordinates` calls), but will benefit from them once available