@sealab/mcp-server 1.0.2 → 1.0.4

package/src/tools/placement-projection.test.ts

@@ -0,0 +1,185 @@
+import { describe, expect, it } from 'vitest';
+import {
+  projectElevationPlacement,
+  projectPlanPlacement,
+  projectPlanWallAnchoredPlacement,
+  isProjectedPlacementOutsideImage,
+  type ElevationCalibration,
+  type PlanCalibration,
+} from './placement-projection';
+
+const elevationCal: ElevationCalibration = {
+  canvasType: 'north',
+  imageSizePx: { width: 1000, height: 600 },
+  horizontalPixelsPerInch: 5,
+  verticalPixelsPerInch: 5,
+  floorZ0Px: 550,
+  horizontalOriginPx: { x: 100, y: 550 },
+  horizontalOriginCoordinateInches: 0,
+  horizontalAxisPositiveDirection: 'right',
+  verticalAxisPositiveDirection: 'up',
+};
+
+describe('projectElevationPlacement', () => {
+  it('places a base cabinet face from the floor up', () => {
+    // 36" wide base cabinet starting 12" along the wall, 30" body height, on the floor.
+    const result = projectElevationPlacement(
+      { horizontalStartInches: 12, widthInches: 36, heightInches: 30, bottomFromFloorInches: 0 },
+      elevationCal
+    );
+    // left = 100 + 12*5 = 160, right = 100 + 48*5 = 340 => centerX 250, width 180
+    expect(result.centerX).toBe(250);
+    expect(result.width).toBe(180);
+    // bottom = floor 550, top = 550 - 30*5 = 400 => centerY 475, height 150
+    expect(result.centerY).toBe(475);
+    expect(result.height).toBe(150);
+    expect(result.rotation).toBe(0);
+  });
+
+  it('lifts an upper cabinet off the floor by bottomFromFloorInches', () => {
+    // upper: bottom at 54" above floor, 42" tall.
+    const result = projectElevationPlacement(
+      { horizontalStartInches: 0, widthInches: 24, heightInches: 42, bottomFromFloorInches: 54 },
+      elevationCal
+    );
+    // bottom = 550 - 54*5 = 280, top = 550 - 96*5 = 70 => centerY 175, height 210
+    expect(result.centerY).toBe(175);
+    expect(result.height).toBe(210);
+  });
+
+  it('produces gap-free adjacent boxes for a run of equal modules (no cumulative drift)', () => {
+    const widths = [24, 24, 24, 24];
+    let cursor = 0;
+    const rights: number[] = [];
+    const lefts: number[] = [];
+    for (const w of widths) {
+      const r = projectElevationPlacement(
+        { horizontalStartInches: cursor, widthInches: w, heightInches: 30 },
+        elevationCal
+      );
+      lefts.push(r.centerX - r.width / 2);
+      rights.push(r.centerX + r.width / 2);
+      cursor += w;
+    }
+    // Each box's right edge equals the next box's left edge exactly.
+    expect(rights[0]).toBeCloseTo(lefts[1], 6);
+    expect(rights[1]).toBeCloseTo(lefts[2], 6);
+    expect(rights[2]).toBeCloseTo(lefts[3], 6);
+  });
+
+  it('honors a left-positive horizontal axis (e.g. east/west wall reading reversed)', () => {
+    const leftPositive: ElevationCalibration = {
+      ...elevationCal,
+      horizontalAxisPositiveDirection: 'left',
+    };
+    const result = projectElevationPlacement(
+      { horizontalStartInches: 12, widthInches: 36, heightInches: 30 },
+      leftPositive
+    );
+    // left = 100 - 12*5 = 40, right = 100 - 48*5 = -140 => centerX -50, width 180
+    expect(result.centerX).toBe(-50);
+    expect(result.width).toBe(180);
+  });
+});
+
+const planCal: PlanCalibration = {
+  canvasType: 'plan',
+  imageSizePx: { width: 800, height: 800 },
+  pixelsPerInch: 2,
+  roomOriginPx: { x: 50, y: 750 },
+  xPositiveDirection: 'right',
+  yPositiveDirection: 'up',
+};
+
+describe('projectPlanPlacement', () => {
+  it('projects a footprint with width along X and depth along Y at rotation 0', () => {
+    const result = projectPlanPlacement(
+      { centerXInches: 100, centerYInches: 50, widthInches: 30, depthInches: 24, rotation: 0 },
+      planCal
+    );
+    // centerX = 50 + 100*2 = 250, centerY = 750 - 50*2 = 650
+    expect(result.centerX).toBe(250);
+    expect(result.centerY).toBe(650);
+    expect(result.width).toBe(60); // 30 * 2
+    expect(result.height).toBe(48); // 24 * 2
+  });
+
+  it('swaps width/depth for a quarter-turn rotation', () => {
+    const result = projectPlanPlacement(
+      { centerXInches: 100, centerYInches: 50, widthInches: 30, depthInches: 24, rotation: 90 },
+      planCal
+    );
+    expect(result.width).toBe(48); // depth 24 * 2 now along X
+    expect(result.height).toBe(60); // width 30 * 2 now along Y
+    expect(result.rotation).toBe(0);
+  });
+});
+
+describe('projectPlanWallAnchoredPlacement', () => {
+  // Room origin at pixel (50,750); +x is right, +y is up (screen y decreases as room y rises).
+  it('pins the back edge to the north wall and grows depth into the room', () => {
+    // North wall face at room y = 120; interior is toward smaller y (depthDirection negative).
+    const result = projectPlanWallAnchoredPlacement(
+      {
+        wallBackEdgeInches: 120,
+        depthAxis: 'y',
+        depthDirection: 'negative',
+        alongWallStartInches: 30,
+        widthInches: 36,
+        depthInches: 24,
+      },
+      planCal
+    );
+    // along-wall center x = 30 + 18 = 48 -> px = 50 + 48*2 = 146
+    expect(result.centerX).toBe(146);
+    // depth center y = 120 - 12 = 108 -> px = 750 - 108*2 = 534
+    expect(result.centerY).toBe(534);
+    expect(result.width).toBe(72); // 36 along wall * 2
+    expect(result.height).toBe(48); // 24 depth * 2
+
+    // The back edge (room y = 120) must land exactly on its wall-face pixel, with
+    // the whole box on the interior side of it (larger pixel-y / lower on screen).
+    const backEdgePx = 750 - 120 * 2; // 510
+    const boxNearWallEdge = result.centerY - result.height / 2; // 534 - 24 = 510
+    expect(boxNearWallEdge).toBe(backEdgePx);
+  });
+
+  it('handles a cabinet backing an east wall (depth along x)', () => {
+    const result = projectPlanWallAnchoredPlacement(
+      {
+        wallBackEdgeInches: 200,
+        depthAxis: 'x',
+        depthDirection: 'negative',
+        alongWallStartInches: 40,
+        widthInches: 30,
+        depthInches: 24,
+      },
+      planCal
+    );
+    expect(result.width).toBe(48); // depth 24 * 2 along x
+    expect(result.height).toBe(60); // width 30 * 2 along y
+    const backEdgePx = 50 + 200 * 2; // 450
+    const boxWallEdge = result.centerX + result.width / 2; // depthDirection negative => box on smaller-x side
+    expect(boxWallEdge).toBe(backEdgePx);
+  });
+});
+
+describe('isProjectedPlacementOutsideImage', () => {
+  it('flags a box that extends past the image edge', () => {
+    expect(
+      isProjectedPlacementOutsideImage(
+        { centerX: 990, centerY: 300, width: 60, height: 60, rotation: 0 },
+        { width: 1000, height: 600 }
+      )
+    ).toBe(true);
+  });
+
+  it('accepts a box fully inside the image', () => {
+    expect(
+      isProjectedPlacementOutsideImage(
+        { centerX: 250, centerY: 475, width: 180, height: 150, rotation: 0 },
+        { width: 1000, height: 600 }
+      )
+    ).toBe(false);
+  });
+});

package/src/tools/placement-projection.ts

@@ -0,0 +1,247 @@
+// ---------------------------------------------------------------------------
+// Deterministic AIDrawingTool placement projection.
+//
+// Root cause of inaccurate cabinet placement: the agent was asked to eyeball
+// raw centerX/centerY/width/height pixel rectangles directly from a drawing.
+// Vision-language models are unreliable at precise pixel localization, so boxes
+// drifted, overlapped, doubled, and overshot — especially across rows of
+// near-identical modules where per-box error accumulates.
+//
+// This module removes that guesswork. The agent establishes ONE pixels-per-inch
+// calibration per canvas (from a visible dimension string + the floor/Z0 line +
+// one origin reference) and supplies each cabinet's REAL inch dimensions and
+// position. Every placement rectangle is then computed from the same scale, so
+// the entire layout is internally consistent and free of cumulative drift.
+//
+// These functions are pure (no IO) so they can be unit-tested directly.
+// ---------------------------------------------------------------------------
+
+export type ElevationCanvasType = 'north' | 'south' | 'east' | 'west';
+export type HorizontalDirection = 'left' | 'right';
+export type VerticalDirection = 'up' | 'down';
+
+export interface PixelPoint {
+  x: number;
+  y: number;
+}
+
+export interface ImageSizePx {
+  width: number;
+  height: number;
+}
+
+/**
+ * Lean elevation calibration. Mirrors the geometry fields of the stored
+ * canvasMeta.projectionCalibration (ElevationProjectionCalibrationSchema) but
+ * carries only what the pixel projection needs.
+ */
+export interface ElevationCalibration {
+  canvasType: ElevationCanvasType;
+  imageSizePx: ImageSizePx;
+  /** Pixels per inch along the wall (horizontal screen axis). */
+  horizontalPixelsPerInch: number;
+  /** Pixels per inch vertically (height screen axis). */
+  verticalPixelsPerInch: number;
+  /** Pixel Y of the finished-floor / Z0 reference line. */
+  floorZ0Px: number;
+  /** A pixel point whose horizontal inch coordinate is known. */
+  horizontalOriginPx: PixelPoint;
+  /** The along-wall inch coordinate that horizontalOriginPx maps to. */
+  horizontalOriginCoordinateInches: number;
+  /** Direction in which the along-wall inch coordinate increases on screen. */
+  horizontalAxisPositiveDirection: HorizontalDirection;
+  /** Direction in which height-above-floor increases on screen (normally 'up'). */
+  verticalAxisPositiveDirection: VerticalDirection;
+}
+
+/** Lean plan calibration mirroring PlanProjectionCalibrationSchema geometry. */
+export interface PlanCalibration {
+  canvasType: 'plan';
+  imageSizePx: ImageSizePx;
+  pixelsPerInch: number;
+  /** Pixel point that maps to room/global coordinate origin (0, 0). */
+  roomOriginPx: PixelPoint;
+  xPositiveDirection: HorizontalDirection;
+  yPositiveDirection: VerticalDirection;
+}
+
+/** Real-world spec for one cabinet front face on an elevation. */
+export interface ElevationPlacementSpec {
+  /** Left edge of the face along the wall, in the wall's horizontal inch coordinate. */
+  horizontalStartInches: number;
+  /** Cabinet face width in inches. */
+  widthInches: number;
+  /** Cabinet face height in inches (body height for a base cabinet — excludes toekick/counter). */
+  heightInches: number;
+  /** Finished-floor-to-bottom of this face, in inches. 0 for a base cabinet on the floor. */
+  bottomFromFloorInches?: number;
+}
+
+/** Real-world spec for one cabinet footprint on the plan. */
+export interface PlanPlacementSpec {
+  /** Cabinet center X in room/global plan inches. */
+  centerXInches: number;
+  /** Cabinet center Y in room/global plan inches. */
+  centerYInches: number;
+  /** Cabinet width in inches (along the cabinet's face). */
+  widthInches: number;
+  /** Cabinet depth in inches (front-to-back). */
+  depthInches: number;
+  /** Wall rotation 0/90/180/270. Swaps which inch dimension runs along X vs Y. */
+  rotation?: number;
+}
+
+export interface ProjectedPlacement {
+  centerX: number;
+  centerY: number;
+  width: number;
+  height: number;
+  rotation: number;
+}
+
+const PIXEL_PRECISION = 2;
+
+function roundPx(value: number): number {
+  const factor = 10 ** PIXEL_PRECISION;
+  return Math.round(value * factor) / factor;
+}
+
+function horizontalSign(direction: HorizontalDirection): number {
+  return direction === 'right' ? 1 : -1;
+}
+
+function elevationVerticalSign(direction: VerticalDirection): number {
+  // Height-above-floor grows upward; screen Y grows downward.
+  // 'up' positive => increasing height moves toward smaller pixel Y.
+  return direction === 'up' ? -1 : 1;
+}
+
+function planVerticalSign(direction: VerticalDirection): number {
+  return direction === 'down' ? 1 : -1;
+}
+
+function elevationPixelX(horizontalInches: number, cal: ElevationCalibration): number {
+  return (
+    cal.horizontalOriginPx.x +
+    horizontalSign(cal.horizontalAxisPositiveDirection) *
+      (horizontalInches - cal.horizontalOriginCoordinateInches) *
+      cal.horizontalPixelsPerInch
+  );
+}
+
+function elevationPixelY(heightAboveFloorInches: number, cal: ElevationCalibration): number {
+  return (
+    cal.floorZ0Px +
+    elevationVerticalSign(cal.verticalAxisPositiveDirection) *
+      heightAboveFloorInches *
+      cal.verticalPixelsPerInch
+  );
+}
+
+/** Project one elevation cabinet face spec into an image-pixel rectangle. */
+export function projectElevationPlacement(
+  spec: ElevationPlacementSpec,
+  cal: ElevationCalibration
+): ProjectedPlacement {
+  const bottomFromFloor = spec.bottomFromFloorInches ?? 0;
+  const leftPx = elevationPixelX(spec.horizontalStartInches, cal);
+  const rightPx = elevationPixelX(spec.horizontalStartInches + spec.widthInches, cal);
+  const bottomPx = elevationPixelY(bottomFromFloor, cal);
+  const topPx = elevationPixelY(bottomFromFloor + spec.heightInches, cal);
+
+  return {
+    centerX: roundPx((leftPx + rightPx) / 2),
+    centerY: roundPx((topPx + bottomPx) / 2),
+    width: roundPx(Math.abs(rightPx - leftPx)),
+    height: roundPx(Math.abs(bottomPx - topPx)),
+    rotation: 0,
+  };
+}
+
+function planPixelX(xInches: number, cal: PlanCalibration): number {
+  return cal.roomOriginPx.x + horizontalSign(cal.xPositiveDirection) * xInches * cal.pixelsPerInch;
+}
+
+function planPixelY(yInches: number, cal: PlanCalibration): number {
+  return cal.roomOriginPx.y + planVerticalSign(cal.yPositiveDirection) * yInches * cal.pixelsPerInch;
+}
+
+/** Project one plan cabinet footprint spec into an image-pixel rectangle. */
+export function projectPlanPlacement(spec: PlanPlacementSpec, cal: PlanCalibration): ProjectedPlacement {
+  const rotation = ((spec.rotation ?? 0) % 360 + 360) % 360;
+  const rotatedQuarterTurn = rotation === 90 || rotation === 270;
+  const inchesAlongX = rotatedQuarterTurn ? spec.depthInches : spec.widthInches;
+  const inchesAlongY = rotatedQuarterTurn ? spec.widthInches : spec.depthInches;
+
+  return {
+    centerX: roundPx(planPixelX(spec.centerXInches, cal)),
+    centerY: roundPx(planPixelY(spec.centerYInches, cal)),
+    width: roundPx(inchesAlongX * cal.pixelsPerInch),
+    height: roundPx(inchesAlongY * cal.pixelsPerInch),
+    // The rectangle is axis-aligned to the room/image; orientation is captured
+    // by the dimension swap above, so the rendered box rotation stays 0.
+    rotation: 0,
+  };
+}
+
+/**
+ * Wall-anchored plan footprint spec. The agent pins the cabinet's BACK edge to
+ * the wall's inner face it can see, and depth grows into the room — so the
+ * footprint can never bleed into the wall band, the way a free center ± half
+ * depth can. This is the plan analog of anchoring elevation height to the floor.
+ */
+export interface PlanWallAnchoredSpec {
+  /** Room-inch coordinate of the cabinet back edge on the depth axis (the wall inner face). */
+  wallBackEdgeInches: number;
+  /** Which room axis runs perpendicular to the wall (the depth direction). */
+  depthAxis: 'x' | 'y';
+  /** Direction, in room coordinates, that depth grows from the wall into the room. */
+  depthDirection: 'positive' | 'negative';
+  /** Start of the run along the wall, in room inches on the other axis. */
+  alongWallStartInches: number;
+  /** Extent along the wall in inches. */
+  widthInches: number;
+  /** Cabinet depth in inches, growing from the wall face into the room. */
+  depthInches: number;
+}
+
+/**
+ * Project a wall-anchored plan footprint. The back edge lands exactly on
+ * wallBackEdgeInches; the box extends widthInches along the wall and depthInches
+ * into the room. The rendered rectangle is axis-aligned (rotation 0).
+ */
+export function projectPlanWallAnchoredPlacement(
+  spec: PlanWallAnchoredSpec,
+  cal: PlanCalibration
+): ProjectedPlacement {
+  const sign = spec.depthDirection === 'positive' ? 1 : -1;
+  const alongCenter = spec.alongWallStartInches + spec.widthInches / 2;
+  const depthCenter = spec.wallBackEdgeInches + sign * (spec.depthInches / 2);
+
+  const centerXInches = spec.depthAxis === 'x' ? depthCenter : alongCenter;
+  const centerYInches = spec.depthAxis === 'y' ? depthCenter : alongCenter;
+  const inchesAlongX = spec.depthAxis === 'x' ? spec.depthInches : spec.widthInches;
+  const inchesAlongY = spec.depthAxis === 'y' ? spec.depthInches : spec.widthInches;
+
+  return {
+    centerX: roundPx(planPixelX(centerXInches, cal)),
+    centerY: roundPx(planPixelY(centerYInches, cal)),
+    width: roundPx(inchesAlongX * cal.pixelsPerInch),
+    height: roundPx(inchesAlongY * cal.pixelsPerInch),
+    rotation: 0,
+  };
+}
+
+/** True when any part of the rectangle falls outside the calibration image. */
+export function isProjectedPlacementOutsideImage(
+  placement: ProjectedPlacement,
+  imageSizePx: ImageSizePx
+): boolean {
+  const halfWidth = placement.width / 2;
+  const halfHeight = placement.height / 2;
+  const minX = placement.centerX - halfWidth;
+  const maxX = placement.centerX + halfWidth;
+  const minY = placement.centerY - halfHeight;
+  const maxY = placement.centerY + halfHeight;
+  return minX < 0 || minY < 0 || maxX > imageSizePx.width || maxY > imageSizePx.height;
+}

package/src/tools/projects.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import * as apiClientModule from '../client/api-client';
+
+vi.mock('../client/api-client', () => ({
+  client: { get: vi.fn(), post: vi.fn(), put: vi.fn(), patch: vi.fn(), delete: vi.fn() },
+  handleAxiosError: vi.fn((e) => { throw e; }),
+  McpApiError: class McpApiError extends Error {
+    constructor(public status: number, message: string) { super(message); }
+  },
+}));
+
+import {
+  listProjects,
+  getProject,
+  createProject,
+  updateProject,
+  attachOrderToProject,
+  updateProjectArticleMaterials,
+  shareProjectAccess,
+} from './projects';
+
+describe('project MCP tools', () => {
+  beforeEach(() => vi.clearAllMocks());
+
+  it('lists compact project summaries', async () => {
+    vi.mocked(apiClientModule.client.get).mockResolvedValue({
+      data: [{ projectId: 1, name: 'Smith Kitchen', status: 'Active', orders: [{ orderId: 'ORD-1' }] }],
+    });
+
+    const result = await listProjects({});
+
+    expect(vi.mocked(apiClientModule.client.get)).toHaveBeenCalledWith('/projects');
+    expect(result).toContain('Smith Kitchen');
+    expect(result).toContain('orderCount');
+  });
+
+  it('gets full project detail', async () => {
+    vi.mocked(apiClientModule.client.get).mockResolvedValue({
+      data: { projectId: 1, name: 'Smith Kitchen', summary: { projectTotalValue: 100 } },
+    });
+
+    const result = await getProject({ projectId: 1 });
+
+    expect(vi.mocked(apiClientModule.client.get)).toHaveBeenCalledWith('/projects/1');
+    expect(result).toContain('projectTotalValue');
+  });
+
+  it('creates a project', async () => {
+    vi.mocked(apiClientModule.client.post).mockResolvedValue({
+      data: { projectId: 2, name: 'New Project' },
+    });
+
+    const result = await createProject({ name: 'New Project', status: 'Active' });
+
+    expect(vi.mocked(apiClientModule.client.post)).toHaveBeenCalledWith('/projects', {
+      name: 'New Project',
+      status: 'Active',
+    });
+    expect(result).toContain('Project ID: 2');
+  });
+
+  it('merges current project before update', async () => {
+    vi.mocked(apiClientModule.client.get).mockResolvedValue({
+      data: { projectId: 3, name: 'Old Name', address1: '1 Main', status: 'Active' },
+    });
+    vi.mocked(apiClientModule.client.put).mockResolvedValue({
+      data: { projectId: 3, name: 'New Name', address1: '1 Main', status: 'Active' },
+    });
+
+    const result = await updateProject({ projectId: 3, name: 'New Name' });
+
+    expect(vi.mocked(apiClientModule.client.get)).toHaveBeenCalledWith('/projects/3');
+    expect(vi.mocked(apiClientModule.client.put)).toHaveBeenCalledWith('/projects/3', {
+      projectId: 3,
+      name: 'New Name',
+      address1: '1 Main',
+      status: 'Active',
+    });
+    expect(result).toContain('New Name');
+  });
+
+  it('attaches an order to a project', async () => {
+    vi.mocked(apiClientModule.client.post).mockResolvedValue({ data: 'ok' });
+
+    const result = await attachOrderToProject({ projectId: 4, orderId: 'ORD-1' });
+
+    expect(vi.mocked(apiClientModule.client.post)).toHaveBeenCalledWith('/projects/4/orders/ORD-1');
+    expect(result).toContain('attached');
+  });
+
+  it('bulk updates project article materials', async () => {
+    vi.mocked(apiClientModule.client.patch).mockResolvedValue({
+      data: { updatedArticles: 2 },
+    });
+
+    const result = await updateProjectArticleMaterials({
+      projectId: 5,
+      orderId: 'ORD-2',
+      positionNames: ['Base_01', 'Base_02'],
+      field: 'caseMaterial',
+      materialDescription: 'Prefinished Maple',
+    });
+
+    expect(vi.mocked(apiClientModule.client.patch)).toHaveBeenCalledWith(
+      '/projects/5/orders/ORD-2/articles/materials',
+      {
+        positionNames: ['Base_01', 'Base_02'],
+        field: 'caseMaterial',
+        materialDescription: 'Prefinished Maple',
+      }
+    );
+    expect(result).toContain('updatedArticles');
+  });
+
+  it('shares project access', async () => {
+    vi.mocked(apiClientModule.client.post).mockResolvedValue({ data: 'ok' });
+
+    const result = await shareProjectAccess({
+      projectId: 6,
+      grantedToEmail: 'client@example.com',
+      permissionType: 'VIEW',
+      hidePrice: true,
+    });
+
+    expect(vi.mocked(apiClientModule.client.post)).toHaveBeenCalledWith(
+      '/projects/6/permissions/grant',
+      {
+        grantedToEmail: 'client@example.com',
+        permissionType: 'VIEW',
+        hidePrice: true,
+      }
+    );
+    expect(result).toContain('Pricing will be hidden');
+  });
+});