opentakeoff-mcp 0.5.0 → 0.6.0

package/README.md

@@ -27,9 +27,9 @@ No Node, no npm: download **`opentakeoff-mcp.mcpb`** from the
 double-click it — Claude Desktop installs the server with its dependencies
 bundled. Built by `npm run mcpb` and attached automatically to every `mcp-v*`
 release. The bundle is platform-neutral on purpose: it excludes the optional
-native canvas, so every tool and the text/metadata resources work everywhere,
-and the sheet-image resource says exactly what's missing where rendering isn't
-available.
+native canvas, so every JSON tool and the text/metadata resources work
+everywhere; the sheet-image resource and the `view_sheet` tool say exactly
+what's missing where rendering isn't available.
 
 
 The takeoff engine — One-Click Area, the scale model, conditions, totals — on
@@ -115,12 +115,15 @@ includes document text, shape vertices, or result payload content.
 | `export_takeoff` | The full `opentakeoff.takeoff_canvas.v1` payload — exactly what the app autosaves. Inline, and to disk with `path`. |
 | `delete_shape` | Remove a committed shape by id. |
 | `read_sheet_text` | Positioned page text (image px), optionally restricted to a region — title blocks, room labels, finish schedules. |
+| `view_sheet` | The agent's eyes: render the sheet (or an image-px crop) to PNG. `overlay` burns committed shapes in (solid = human-affirmed, dashed = unreviewed) to verify geometry landed; `grid` burns in a calibrated 1-ft/5-ft measuring grid with foot labels (`"auto"` from the set scale, or the drawing scale like `"1/4"`) so dimensions are counted off cells, not guessed. |
 
-Every tool declares an **`outputSchema`**, and every reply carries the payload
-as **`structuredContent`** — typed, machine-validated on every call — alongside
-the same compact JSON in a single text item for clients that predate structured
-output. Failures come back as `isError: true` with `{"error": "..."}` — never a
-dropped connection.
+Every JSON tool declares an **`outputSchema`**, and every reply carries the
+payload as **`structuredContent`** — typed, machine-validated on every call —
+alongside the same compact JSON in a single text item for clients that predate
+structured output. `view_sheet` is the one image tool: its reply is a PNG
+content item plus a JSON meta text item (image replies aren't structured
+output, so it declares no schema by design). Failures come back as
+`isError: true` with `{"error": "..."}` — never a dropped connection.
 
 ## Resources — browse before you measure
 
@@ -209,19 +212,25 @@ npm test        # session + tool-layer + e2e, against demo/sample-plan.pdf
 ## Releasing (maintainers)
 
 MCP releases live in the **`mcp-v*`** tag namespace — bare `v*` tags belong to
-the app (v0.2.0, v0.3.0 are app releases). The npm artifact publishes manually
-(hardware-key 2FA) **before** the tag is pushed; the workflow refuses to run
-ahead of it.
+the app (v0.2.0, v0.3.0 are app releases). Releases publish via **npm trusted
+publishing**: the tag push fires `.github/workflows/publish-mcp.yml`, which
+pauses at the `release` environment for maintainer approval, then publishes
+the npm artifact over OIDC with a **provenance attestation** (no npm token
+exists anywhere — the npm package designates that exact repo + workflow as
+its trusted publisher), followed by the MCP registry entry, the GitHub
+release, and the MCPB bundle.
 
 ```bash
 # 1. bump the version — all three fields together:
 #    package.json .version, server.json .version, server.json .packages[0].version
-# 2. from mcp/, publish with the hardware key:
-npm publish
-# 3. tag and push — this fires .github/workflows/publish-mcp.yml:
+# 2. tag and push — this fires the whole release:
 git tag mcp-v<version> && git push origin mcp-v<version>
+# 3. approve the run (GitHub → Actions → the paused "Publish to MCP Registry" run)
 ```
 
-The workflow checks version consistency, requires the npm artifact to exist,
-publishes to the official MCP registry via GitHub OIDC, verifies the listing,
-and creates the GitHub release (titled `opentakeoff-mcp <version>`).
+The workflow checks version consistency, runs the full publish gate
+(`prepublishOnly` = typecheck + tests + build), publishes to npm and the
+official MCP registry, verifies the registry listing, and creates the GitHub
+release (titled `opentakeoff-mcp <version>`). A re-run skips the npm publish
+if that version already shipped, so a transient failure downstream is safe to
+retry.

package/dist/server-core.js

@@ -178,6 +178,28 @@ async function openPdf(filePath) {
           } finally {
             factory.destroy(target);
           }
+        },
+        async renderRegionPng(region, longEdge, draw) {
+          await ensureCanvasGlobals();
+          const w = region.x1 - region.x0;
+          const h = region.y1 - region.y0;
+          const zoom = longEdge / Math.max(w, h);
+          const width = Math.max(1, Math.round(w * zoom));
+          const height = Math.max(1, Math.round(h * zoom));
+          const rvp = page.getViewport({
+            scale: RENDER_SCALE * zoom,
+            offsetX: -region.x0 * zoom,
+            offsetY: -region.y0 * zoom
+          });
+          const factory = doc.canvasFactory;
+          const target = factory.create(width, height);
+          try {
+            await page.render({ canvasContext: target.context, viewport: rvp }).promise;
+            draw?.(target.context, (x, y) => [(x - region.x0) * zoom, (y - region.y0) * zoom]);
+            return { png: new Uint8Array(target.canvas.toBuffer("image/png")), width, height, zoom };
+          } finally {
+            factory.destroy(target);
+          }
         }
       };
     },
@@ -202,6 +224,12 @@ var ok = (payload) => ({
   structuredContent: payload,
   content: [{ type: "text", text: JSON.stringify(payload) }]
 });
+var okImage = (png, meta) => ({
+  content: [
+    { type: "image", data: Buffer.from(png.buffer, png.byteOffset, png.byteLength).toString("base64"), mimeType: "image/png" },
+    { type: "text", text: JSON.stringify(meta) }
+  ]
+});
 var fail = (err) => ({
   isError: true,
   content: [{ type: "text", text: JSON.stringify({ error: err instanceof Error ? err.message : String(err) }) }]
@@ -900,6 +928,86 @@ function grandTotals(rows) {
   };
 }
 
+// src/view.ts
+var INK = "#d91a1a";
+var PENCIL = "#2659e6";
+var GRID_MINOR = "rgba(184, 191, 217, 0.55)";
+var GRID_MAJOR = "rgba(51, 107, 242, 0.6)";
+var GRID_LABEL = "#336bf2";
+function gridPxPerFoot(spec, upp) {
+  const s = (spec || "").trim().toLowerCase();
+  if (!s) return null;
+  if (s === "auto") {
+    if (upp == null) {
+      throw new UserError(`grid "auto" needs this sheet's scale set \u2014 call set_scale first, or pass the drawing scale read off the title block instead (e.g. grid: "1/4").`);
+    }
+    return 1 / upp;
+  }
+  let inPerFt;
+  if (s.includes("/")) {
+    const [num, den] = s.split("/", 2);
+    inPerFt = Number(num) / Number(den);
+  } else {
+    inPerFt = Number(s);
+  }
+  if (!Number.isFinite(inPerFt)) {
+    throw new UserError(`Bad grid scale ${JSON.stringify(spec)} \u2014 use inches-per-foot like "1/4", "3/16", or "0.25" (or "auto" once the scale is set).`);
+  }
+  if (inPerFt < 0.01 || inPerFt > 12) {
+    throw new UserError(`Grid scale out of range: ${JSON.stringify(spec)} \u2014 inches-per-foot must be between 0.01 and 12.`);
+  }
+  return inPerFt * 72 * RENDER_SCALE;
+}
+function drawGrid(ctx, toCanvas, region, ppf) {
+  const [ox, oy] = toCanvas(region.x0, region.y0);
+  const step = toCanvas(region.x0 + ppf, region.y0)[0] - ox;
+  const [ex, ey] = toCanvas(region.x1, region.y1);
+  const nx = Math.ceil((region.x1 - region.x0) / ppf);
+  const ny = Math.ceil((region.y1 - region.y0) / ppf);
+  ctx.setLineDash([]);
+  for (const major of [false, true]) {
+    ctx.strokeStyle = major ? GRID_MAJOR : GRID_MINOR;
+    ctx.lineWidth = major ? 1.5 : 0.75;
+    if (!major && step < 3) continue;
+    ctx.beginPath();
+    for (let i = 0; i <= nx; i++) {
+      if (i % 5 === 0 !== major) continue;
+      const x = ox + i * step;
+      ctx.moveTo(x, oy);
+      ctx.lineTo(x, ey);
+    }
+    for (let j = 0; j <= ny; j++) {
+      if (j % 5 === 0 !== major) continue;
+      const y = oy + j * step;
+      ctx.moveTo(ox, y);
+      ctx.lineTo(ex, y);
+    }
+    ctx.stroke();
+  }
+  const size = Math.max(9, Math.min(36, step * 0.38));
+  ctx.font = `${size}px sans-serif`;
+  ctx.fillStyle = GRID_LABEL;
+  for (let i = 0; i <= nx; i += 5) ctx.fillText(String(i), ox + i * step + 3, oy + size + 2);
+  for (let j = 5; j <= ny; j += 5) ctx.fillText(String(j), ox + 3, oy + j * step - 3);
+}
+function drawShapes(ctx, toCanvas, shapes, sheetW, sheetH, longEdge) {
+  const w = Math.max(1.4, longEdge / 700);
+  for (const s of shapes) {
+    const pts = s.verts_norm.map(([nx, ny]) => toCanvas(nx * sheetW, ny * sheetH));
+    if (pts.length < 2) continue;
+    const pending = s.origin?.reviewed === false;
+    ctx.strokeStyle = pending ? PENCIL : INK;
+    ctx.lineWidth = w;
+    ctx.setLineDash(pending ? [w * 4, w * 3] : []);
+    ctx.beginPath();
+    ctx.moveTo(pts[0][0], pts[0][1]);
+    for (let i = 1; i < pts.length; i++) ctx.lineTo(pts[i][0], pts[i][1]);
+    if (s.measure_role !== "linear") ctx.closePath();
+    ctx.stroke();
+  }
+  ctx.setLineDash([]);
+}
+
 // src/session.ts
 var SNAP_CELL = 24;
 var SNAP_TOL = 7;
@@ -909,6 +1017,9 @@ var mintUuid = () => globalThis.crypto && typeof globalThis.crypto.randomUUID ==
 var uid = (p) => `${p}-${mintUuid()}`;
 var ANN_SCHEMA = "opentakeoff.takeoff_canvas.v1";
 var IMAGE_MAX_EDGE = 1568;
+var VIEW_MIN_PX = 200;
+var VIEW_DEFAULT_PX = 1400;
+var VIEW_MAX_PX = 2e3;
 var sheetSummary = (s) => ({
   sheet: s.key,
   page: s.pageNum,
@@ -1005,6 +1116,39 @@ var Session = class {
     }
     return s.png;
   }
+  /** view_sheet: render a sheet (or an image-px crop of it) to PNG, with an
+   * optional committed-shapes overlay and calibrated measuring grid. The grid
+   * draws under the overlay, both in canvas space after the page rasterizes. */
+  async viewSheet(name, opts) {
+    const s = this.sheet(name);
+    const px = Math.max(VIEW_MIN_PX, Math.min(VIEW_MAX_PX, Math.round(opts.px ?? VIEW_DEFAULT_PX)));
+    const clampX = (v) => Math.max(0, Math.min(v, s.widthPx));
+    const clampY = (v) => Math.max(0, Math.min(v, s.heightPx));
+    const r = opts.region ? { x0: clampX(opts.region.x0), y0: clampY(opts.region.y0), x1: clampX(opts.region.x1), y1: clampY(opts.region.y1) } : { x0: 0, y0: 0, x1: s.widthPx, y1: s.heightPx };
+    if (!(r.x1 - r.x0 >= 1 && r.y1 - r.y0 >= 1)) {
+      throw new UserError(`Empty view region \u2014 need x1 > x0 and y1 > y0 in image px inside the sheet (${s.widthPx} \xD7 ${s.heightPx}).`);
+    }
+    const ppf = gridPxPerFoot(opts.grid, s.upp);
+    const sheetShapes = this.shapes.filter((x) => x.sheet_id === s.key);
+    const { png, width, height, zoom } = await s.page.renderRegionPng(r, px, (ctx, toCanvas) => {
+      if (ppf) drawGrid(ctx, toCanvas, r, ppf);
+      if (opts.overlay) drawShapes(ctx, toCanvas, sheetShapes, s.widthPx, s.heightPx, px);
+    });
+    return {
+      png,
+      meta: {
+        sheet: s.key,
+        page: s.pageNum,
+        sheet_px: [s.widthPx, s.heightPx],
+        region: [round1(r.x0), round1(r.y0), round1(r.x1), round1(r.y1)],
+        img_px: [width, height],
+        zoom: +zoom.toFixed(4),
+        overlay: !!opts.overlay,
+        ...opts.overlay ? { shapes_drawn: sheetShapes.length } : {},
+        grid_px_per_foot: ppf ? round2(ppf) : 0
+      }
+    };
+  }
   async ensureGeometry(s) {
     if (!s.geo) {
       const opList = await s.page.operatorList();
@@ -1255,7 +1399,7 @@ import { z as z2 } from "zod";
 var TRACE_ENV = "OPENTAKEOFF_MCP_TRACE";
 function traceToolCall(tool, args, startedAt, reply) {
   if (process.env[TRACE_ENV] !== "1") return;
-  const text = reply.content[0]?.text ?? "";
+  const text = reply.content.map((c) => "text" in c ? c.text : c.data).join("");
   const durationMs = Number(process.hrtime.bigint() - startedAt) / 1e6;
   const sheet = args && typeof args === "object" && "sheet" in args ? args.sheet : void 0;
   const event = {
@@ -1528,6 +1672,27 @@ function registerTools(server, session) {
     },
     outputSchema: readSheetTextOutput
   }, run("read_sheet_text", (a) => session.readSheetText(a.sheet, a.region)));
+  server.registerTool("view_sheet", {
+    description: `SEE the sheet \u2014 render the page (or a crop of it) to a PNG image. This is your eyes on the plan: full-sheet overview first, then tight crops at higher px until dimension strings and room labels read cleanly. region is in image px \u2014 the same space as every other tool \u2014 so a feature at pixel (ix, iy) of the returned image sits at x = region_x0 + ix \xD7 (region_x1 \u2212 region_x0) / img_w (same for y), and those coordinates go straight into one_click, measure_polygon, or read_sheet_text. overlay:true burns the session's committed shapes into the render (human-affirmed ink solid red, unreviewed machine shapes dashed blue) \u2014 render again after committing to verify your geometry landed where you intended, and sanity-check what you see: a fixture-sized ring where a room should be means the seed landed inside a stall or casework; an outsized ring means the flood escaped through an opening. To MEASURE rather than guess, pass grid: a calibrated measuring grid is burned in \u2014 thin lines every 1 ft, heavy blue every 5 ft, foot labels along the crop edges, feet counted from the crop's top-left corner. Count grid cells between walls exactly like an estimator scaling a plan; never derive a dimension by eye when the grid can give it to you. grid "auto" uses the sheet's set scale; before set_scale, pass the drawing scale read off the title block as inches-per-foot \u2014 "1/4" for a 1/4" = 1'-0" plan, "3/16", "0.25". Rendering needs the optional native canvas (@napi-rs/canvas); where it isn't installed this tool errors cleanly and every other tool still works. ${COORDS}`,
+    inputSchema: {
+      sheet: z2.string(),
+      region: z2.object({ x0: z2.number(), y0: z2.number(), x1: z2.number(), y1: z2.number() }).optional().describe("Crop rect in image px (origin top-left, y down); omit for the full sheet"),
+      px: z2.number().int().min(200).max(2e3).optional().describe("Long-side pixel budget of the returned image (default 1400) \u2014 small region + high px = readable dimension strings"),
+      overlay: z2.boolean().optional().describe("Burn committed shapes into the render (solid = human-affirmed, dashed = unreviewed)"),
+      grid: z2.string().optional().describe(`Burn in a calibrated 1-ft/5-ft measuring grid: "auto" = the sheet's set scale; otherwise the drawing scale as inches-per-foot, e.g. "1/4", "3/16", "0.25"`)
+    }
+  }, async (a) => {
+    const startedAt = process.hrtime.bigint();
+    let reply;
+    try {
+      const { png, meta } = await session.viewSheet(a.sheet, { region: a.region, px: a.px, overlay: a.overlay, grid: a.grid });
+      reply = okImage(png, meta);
+    } catch (e) {
+      reply = fail(e);
+    }
+    traceToolCall("view_sheet", a, startedAt, reply);
+    return reply;
+  });
 }
 
 // src/resources.ts
@@ -1609,7 +1774,7 @@ function registerResources(server, session) {
 // package.json
 var package_default = {
   name: "opentakeoff-mcp",
-  version: "0.5.0",
+  version: "0.6.0",
   mcpName: "io.github.Kentucky-ai/opentakeoff",
   type: "module",
   description: "OpenTakeoff MCP server \u2014 drive the takeoff engine from your MCP client over stdio.",
@@ -1625,7 +1790,7 @@ var package_default = {
     mcpb: "npm run build && node scripts/build-mcpb.mjs",
     prepublishOnly: "npm run typecheck && npm test && npm run build",
     typecheck: "tsc --noEmit",
-    test: "node --import tsx --test test/conformance.test.ts test/e2e.test.ts test/resources.test.ts test/session.test.ts test/tools.test.ts"
+    test: "node --import tsx --test test/conformance.test.ts test/e2e.test.ts test/resources.test.ts test/session.test.ts test/tools.test.ts test/view.test.ts"
   },
   dependencies: {
     "@modelcontextprotocol/sdk": "^1.12.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opentakeoff-mcp",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "mcpName": "io.github.Kentucky-ai/opentakeoff",
   "type": "module",
   "description": "OpenTakeoff MCP server — drive the takeoff engine from your MCP client over stdio.",
@@ -16,7 +16,7 @@
     "mcpb": "npm run build && node scripts/build-mcpb.mjs",
     "prepublishOnly": "npm run typecheck && npm test && npm run build",
     "typecheck": "tsc --noEmit",
-    "test": "node --import tsx --test test/conformance.test.ts test/e2e.test.ts test/resources.test.ts test/session.test.ts test/tools.test.ts"
+    "test": "node --import tsx --test test/conformance.test.ts test/e2e.test.ts test/resources.test.ts test/session.test.ts test/tools.test.ts test/view.test.ts"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",