opentakeoff-mcp 0.2.0 → 0.4.0

package/README.md

@@ -20,6 +20,17 @@ No clone, no build — point your MCP client at the published package:
 
 Works with Claude Code (`claude mcp add opentakeoff -- npx -y opentakeoff-mcp`), Claude Desktop, Cursor, or any stdio MCP client. Node 20+.
 
+## One-click install (Claude Desktop)
+
+No Node, no npm: download **`opentakeoff-mcp.mcpb`** from the
+[latest release](https://github.com/Kentucky-ai/opentakeoff/releases) and
+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.
+
 
 The takeoff engine — One-Click Area, the scale model, conditions, totals — on
 **stdio for your MCP client**. An agent can open a plan, read the title block,
@@ -104,8 +115,11 @@ includes document text, shape vertices, or result payload content.
 | `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. |
 
-Every reply is one compact JSON text item. Failures come back as
-`isError: true` with `{"error": "..."}` — never a dropped connection.
+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.
 
 ## Resources — browse before you measure
 

package/dist/server-core.js

@@ -199,6 +199,7 @@ function positionedText(ph) {
 var UserError = class extends Error {
 };
 var ok = (payload) => ({
+  structuredContent: payload,
   content: [{ type: "text", text: JSON.stringify(payload) }]
 });
 var fail = (err) => ({
@@ -883,8 +884,8 @@ var SNAP_CELL = 24;
 var SNAP_TOL = 7;
 var PALETTE = ["#c96442", "#2f7d54", "#2563eb", "#9333ea", "#b8860b", "#0d9488", "#be185d", "#1f2937", "#dc2626", "#0891b2"];
 var HATCH_IDS = ["solid", "diag", "diag2", "cross", "diagdense", "horiz", "vert", "grid", "brick", "plank", "herring", "basket", "checker", "wave", "fleur", "speckle"];
-var _idn = 0;
-var uid = (p) => `${p}-${Date.now().toString(36)}-${(_idn++).toString(36)}`;
+var mintUuid = () => globalThis.crypto && typeof globalThis.crypto.randomUUID === "function" ? globalThis.crypto.randomUUID() : `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+var uid = (p) => `${p}-${mintUuid()}`;
 var ANN_SCHEMA = "opentakeoff.takeoff_canvas.v1";
 var IMAGE_MAX_EDGE = 1568;
 var sheetSummary = (s) => ({
@@ -1114,8 +1115,9 @@ var Session = class {
     if (opts.condition) {
       shape_id = this.commit(s, opts.condition, opts.role, ring, { area_sf, perimeter_lf }, {
         method: "one_click_v1",
+        actor: "agent",
         seed_norm: [x / s.widthPx, y / s.heightPx],
-        reviewed: true,
+        reviewed: false,
         ...f.hatchFiltered ? { hatch_filtered: true } : {}
       }).id;
     }
@@ -1128,7 +1130,7 @@ var Session = class {
     const area_sf = round2(met.area * s.upp * s.upp);
     const perimeter_lf = round2(met.perim * s.upp);
     let shape_id;
-    if (opts.condition) shape_id = this.commit(s, opts.condition, opts.role, verts, { area_sf, perimeter_lf }).id;
+    if (opts.condition) shape_id = this.commit(s, opts.condition, opts.role, verts, { area_sf, perimeter_lf }, { method: "manual", actor: "agent" }).id;
     return { area_sf, perimeter_lf, nverts: verts.length, ...shape_id ? { shape_id } : {} };
   }
   measureLine(name, pts, opts) {
@@ -1136,7 +1138,7 @@ var Session = class {
     if (s.upp == null) throw new UserError(this.scaleGate(s));
     const length_lf = round2(openLen(pts) * s.upp);
     let shape_id;
-    if (opts.condition) shape_id = this.commit(s, opts.condition, "linear", pts, { area_sf: 0, perimeter_lf: length_lf }).id;
+    if (opts.condition) shape_id = this.commit(s, opts.condition, "linear", pts, { area_sf: 0, perimeter_lf: length_lf }, { method: "manual", actor: "agent" }).id;
     return { length_lf, npts: pts.length, ...shape_id ? { shape_id } : {} };
   }
   summary() {
@@ -1176,7 +1178,7 @@ var Session = class {
 };
 
 // src/tools.ts
-import { z } from "zod";
+import { z as z2 } from "zod";
 
 // src/trace.ts
 var TRACE_ENV = "OPENTAKEOFF_MCP_TRACE";
@@ -1197,10 +1199,136 @@ function traceToolCall(tool, args, startedAt, reply) {
 `);
 }
 
+// src/outputs.ts
+import { z } from "zod";
+var point = z.tuple([z.number(), z.number()]);
+var sheetSummary2 = {
+  sheet: z.string().describe('Sheet key: page 1 is the bare file name ("plan.pdf"), pages 2+ are "plan.pdf#2"'),
+  page: z.number().int().describe("1-based page number"),
+  width_pt: z.number(),
+  height_pt: z.number(),
+  width_px: z.number().describe("Image px at render scale 2.0 \u2014 the coordinate space every tool speaks"),
+  height_px: z.number(),
+  sheet_number: z.string().optional().describe('Title-block sheet number ("A-101") where detected'),
+  detected_scale: z.string().optional().describe("Drawn scale note read off the sheet \u2014 a suggestion, never auto-applied")
+};
+var loadPlanOutput = {
+  file: z.string(),
+  page_count: z.number().int(),
+  sheets: z.array(z.object(sheetSummary2)),
+  note: z.string()
+};
+var sheetInfoOutput = {
+  ...sheetSummary2,
+  seg_count: z.number().int().describe("Vector segment count"),
+  has_vector_linework: z.boolean().describe("one_click needs vector linework"),
+  scale_set: z.boolean(),
+  upp: z.number().optional().describe("Real feet per image px at render scale 2.0 \u2014 present once the scale is set"),
+  shape_count: z.number().int().describe("Committed shapes on this sheet")
+};
+var setScaleOutput = {
+  sheet: z.string(),
+  upp: z.number().describe("Real feet per image px at render scale 2.0"),
+  label: z.string().optional().describe("The standard scale label, when set by label or detected note"),
+  source: z.enum(["label", "upp", "calibrate", "detected"])
+};
+var oneClickOutput = {
+  status: z.literal("ok"),
+  nverts: z.number().int().describe("Vertex count of the traced polygon"),
+  hatch_filtered: z.literal(true).optional().describe("Present when hatch/pattern linework was classified out of the boundary"),
+  verts: z.array(point).optional().describe("Traced polygon vertices (image px), when return_verts was set"),
+  area_sf: z.number().optional().describe("Scaled mode: traced area in SF"),
+  perimeter_lf: z.number().optional().describe("Scaled mode: traced perimeter in LF"),
+  shape_id: z.string().optional().describe("Scaled mode: id of the committed shape, when condition was passed"),
+  area_px2: z.number().optional().describe("Preview mode (no scale): raw area in px\xB2"),
+  perimeter_px: z.number().optional().describe("Preview mode (no scale): raw perimeter in px"),
+  warning: z.string().optional().describe("Preview mode (no scale): why quantities are unavailable and what to do")
+};
+var measurePolygonOutput = {
+  area_sf: z.number(),
+  perimeter_lf: z.number(),
+  nverts: z.number().int(),
+  shape_id: z.string().optional().describe("Present when condition was passed and the shape committed")
+};
+var measureLineOutput = {
+  length_lf: z.number(),
+  npts: z.number().int(),
+  shape_id: z.string().optional().describe("Present when condition was passed and the shape committed")
+};
+var summaryRow = z.object({
+  id: z.string(),
+  finish_tag: z.string(),
+  multiplier: z.number(),
+  waste_pct: z.number(),
+  shape_count: z.number().int(),
+  floor_sf: z.number(),
+  wall_sf: z.number(),
+  border_sf: z.number(),
+  lf: z.number(),
+  ea: z.number(),
+  total_sf: z.number(),
+  floor_sf_net: z.number(),
+  wall_sf_net: z.number(),
+  border_sf_net: z.number(),
+  lf_net: z.number(),
+  total_sf_net: z.number(),
+  sy_net: z.number()
+}).passthrough();
+var takeoffSummaryOutput = {
+  conditions: z.array(summaryRow),
+  totals: z.object({
+    total_sf: z.number(),
+    total_sf_net: z.number(),
+    lf: z.number(),
+    lf_net: z.number(),
+    ea: z.number(),
+    sy_net: z.number()
+  }).passthrough()
+};
+var exportTakeoffOutput = {
+  schema: z.string(),
+  project_name: z.string(),
+  units: z.string(),
+  sheets: z.array(z.object({ sheet_id: z.string(), units_per_px: z.number() })),
+  conditions: z.array(z.object({
+    id: z.string(),
+    finish_tag: z.string(),
+    color: z.string(),
+    fill: z.string(),
+    hatch: z.string(),
+    multiplier: z.number(),
+    waste_pct: z.number(),
+    materials: z.array(z.unknown())
+  }).passthrough()),
+  shapes: z.array(z.object({
+    id: z.string(),
+    sheet_id: z.string(),
+    condition_id: z.string(),
+    measure_role: z.enum(["floor_area", "deduct", "linear"]),
+    verts_norm: z.array(point).describe("Vertices normalized to sheet dims (0\u20131)"),
+    computed: z.object({ area_sf: z.number(), perimeter_lf: z.number() }).passthrough(),
+    origin: z.object({}).passthrough().optional().describe("Provenance: method (manual|one_click_v1), actor (omitted=human, 'agent'=MCP/automation), reviewed (human affirmed at an explicit gate), and correction fields (edited, edited_before_create, copied, proposed_verts_norm, edits)")
+  }).passthrough()),
+  markups: z.array(z.unknown()),
+  sheet_group: z.array(z.unknown()),
+  last_group: z.array(z.unknown()),
+  sheet_tabs: z.array(z.unknown()),
+  sheet_levels: z.object({}).passthrough()
+};
+var deleteShapeOutput = {
+  deleted: z.string().describe("The removed shape's id"),
+  shape_count: z.number().int().describe("Committed shapes remaining")
+};
+var readSheetTextOutput = {
+  sheet: z.string(),
+  items: z.array(z.object({ str: z.string(), x: z.number(), y: z.number() })).describe("Positioned text items (image px)"),
+  text: z.string().describe("The items joined with spaces")
+};
+
 // src/tools.ts
 var COORDS = "Coordinates are image px at render scale 2.0: PDF pt \xD7 2, origin top-left, y down (the browser canvas's native space). Sheet payloads carry dims in both px and pt.";
-var pointSchema = z.tuple([z.number(), z.number()]);
-var roleSchema = z.enum(["floor_area", "deduct"]).default("floor_area");
+var pointSchema = z2.tuple([z2.number(), z2.number()]);
+var roleSchema = z2.enum(["floor_area", "deduct"]).default("floor_area");
 var run = (tool, fn) => async (args) => {
   const startedAt = process.hrtime.bigint();
   let reply;
@@ -1215,7 +1343,8 @@ var run = (tool, fn) => async (args) => {
 function registerTools(server, session) {
   server.registerTool("load_plan", {
     description: `Open a plan PDF from disk and replace the whole session (previous document, scales, conditions, and shapes are cleared). Returns file, page_count, and one entry per sheet: dims, title-block sheet_number, and the detected drawn scale where present. The loaded sheets also become browsable resources (takeoff://sheets). ${COORDS}`,
-    inputSchema: { path: z.string().describe("Path to a plan PDF on disk") }
+    inputSchema: { path: z2.string().describe("Path to a plan PDF on disk") },
+    outputSchema: loadPlanOutput
   }, run("load_plan", async ({ path: path3 }) => {
     const loaded = await session.loadPlan(path3);
     server.sendResourceListChanged();
@@ -1223,17 +1352,19 @@ function registerTools(server, session) {
   }));
   server.registerTool("sheet_info", {
     description: `Sheet detail: dims (px and pt), vector segment count, whether the sheet has vector linework (one_click needs it), scale status, the detected scale suggestion, and this sheet's committed shape count. ${COORDS}`,
-    inputSchema: { sheet: z.string().describe('Sheet key ("plan.pdf", "plan.pdf#2") or title-block number ("A-101")') }
+    inputSchema: { sheet: z2.string().describe('Sheet key ("plan.pdf", "plan.pdf#2") or title-block number ("A-101")') },
+    outputSchema: sheetInfoOutput
   }, run("sheet_info", ({ sheet }) => session.sheetInfo(sheet)));
   server.registerTool("set_scale", {
     description: `Set a sheet's scale \u2014 exactly ONE of: label (a standard scale, e.g. '1/4" = 1'-0"'), upp (real feet per image px), calibrate (two points along a known dimension plus its real feet), or use_detected (adopt the drawn scale note read off the sheet). The detected scale is never applied automatically \u2014 setting it is always this explicit call. ${COORDS}`,
     inputSchema: {
-      sheet: z.string(),
-      label: z.string().optional().describe("A standard scale label, exactly as listed in the error on a miss"),
-      upp: z.number().optional().describe("Real feet per image px at render scale 2.0"),
-      calibrate: z.object({ p1: pointSchema, p2: pointSchema, feet: z.number() }).optional().describe("Two points (image px) a known real distance apart, and that distance in feet"),
-      use_detected: z.boolean().optional().describe("true = adopt the sheet's detected scale")
-    }
+      sheet: z2.string(),
+      label: z2.string().optional().describe("A standard scale label, exactly as listed in the error on a miss"),
+      upp: z2.number().optional().describe("Real feet per image px at render scale 2.0"),
+      calibrate: z2.object({ p1: pointSchema, p2: pointSchema, feet: z2.number() }).optional().describe("Two points (image px) a known real distance apart, and that distance in feet"),
+      use_detected: z2.boolean().optional().describe("true = adopt the sheet's detected scale")
+    },
+    outputSchema: setScaleOutput
   }, run("set_scale", (a) => {
     const given = [a.label !== void 0, a.upp !== void 0, a.calibrate !== void 0, a.use_detected !== void 0].filter(Boolean).length;
     if (given !== 1) throw new UserError("Provide exactly one of: label, upp, calibrate, use_detected.");
@@ -1242,38 +1373,43 @@ function registerTools(server, session) {
   server.registerTool("one_click", {
     description: `One-Click Area: click inside a room (image px) and the plan's vector linework bounds it \u2014 flood fill, contour trace, vertices snapped to true PDF endpoints. With the sheet's scale set, returns area_sf / perimeter_lf; pass condition (a finish tag, e.g. "CPT-1") to commit the traced shape to the takeoff. Without a scale it returns px-only quantities with a warning and commits nothing. role "deduct" makes the committed shape subtract. ${COORDS}`,
     inputSchema: {
-      sheet: z.string(),
-      x: z.number(),
-      y: z.number(),
-      condition: z.string().optional().describe("Finish tag to commit under (minted on first use)"),
+      sheet: z2.string(),
+      x: z2.number(),
+      y: z2.number(),
+      condition: z2.string().optional().describe("Finish tag to commit under (minted on first use)"),
       role: roleSchema,
-      return_verts: z.boolean().default(false).describe("Include the traced polygon's vertices (image px)")
-    }
+      return_verts: z2.boolean().default(false).describe("Include the traced polygon's vertices (image px)")
+    },
+    outputSchema: oneClickOutput
   }, run("one_click", (a) => session.oneClick(a.sheet, a.x, a.y, { condition: a.condition, role: a.role, returnVerts: a.return_verts })));
   server.registerTool("measure_polygon", {
     description: `Measure a closed polygon you supply (min 3 vertices, image px): area_sf and perimeter_lf at the sheet's scale. Requires the scale to be set. Pass condition to commit it; role "deduct" subtracts. ${COORDS}`,
     inputSchema: {
-      sheet: z.string(),
-      verts: z.array(pointSchema).min(3),
-      condition: z.string().optional(),
+      sheet: z2.string(),
+      verts: z2.array(pointSchema).min(3),
+      condition: z2.string().optional(),
       role: roleSchema
-    }
+    },
+    outputSchema: measurePolygonOutput
   }, run("measure_polygon", (a) => session.measurePolygon(a.sheet, a.verts, { condition: a.condition, role: a.role })));
   server.registerTool("measure_line", {
     description: `Measure an open polyline (min 2 points, image px): length_lf at the sheet's scale. Requires the scale to be set. Pass condition to commit it as a linear shape (base, transitions, feature strips). ${COORDS}`,
     inputSchema: {
-      sheet: z.string(),
-      pts: z.array(pointSchema).min(2),
-      condition: z.string().optional()
-    }
+      sheet: z2.string(),
+      pts: z2.array(pointSchema).min(2),
+      condition: z2.string().optional()
+    },
+    outputSchema: measureLineOutput
   }, run("measure_line", (a) => session.measureLine(a.sheet, a.pts, { condition: a.condition })));
   server.registerTool("takeoff_summary", {
     description: `Per-condition totals (floor/wall/border SF, LF, EA, SY, with and without waste) plus grand totals \u2014 the Report's numbers, computed by the same rules. ${COORDS}`,
-    inputSchema: {}
+    inputSchema: {},
+    outputSchema: takeoffSummaryOutput
   }, run("takeoff_summary", () => session.summary()));
   server.registerTool("export_takeoff", {
     description: `The full "opentakeoff.takeoff_canvas.v1" annotations payload \u2014 exactly what the app autosaves, importable by it. Returned inline; pass path to also write it to disk as JSON. ${COORDS}`,
-    inputSchema: { path: z.string().optional().describe("File path to write the payload to") }
+    inputSchema: { path: z2.string().optional().describe("File path to write the payload to") },
+    outputSchema: exportTakeoffOutput
   }, run("export_takeoff", async ({ path: outPath }) => {
     const payload = session.exportPayload();
     if (outPath) {
@@ -1284,14 +1420,16 @@ function registerTools(server, session) {
   }));
   server.registerTool("delete_shape", {
     description: `Remove a committed shape by the id returned when it was committed. ${COORDS}`,
-    inputSchema: { shape_id: z.string() }
+    inputSchema: { shape_id: z2.string() },
+    outputSchema: deleteShapeOutput
   }, run("delete_shape", ({ shape_id }) => session.deleteShape(shape_id)));
   server.registerTool("read_sheet_text", {
     description: `The sheet's text with positions \u2014 items [{str, x, y}] in image px plus the joined text. Optionally restrict to a region {x0, y0, x1, y1}. Use it to read title blocks, room labels, finish schedules, and scale notes. ${COORDS}`,
     inputSchema: {
-      sheet: z.string(),
-      region: z.object({ x0: z.number(), y0: z.number(), x1: z.number(), y1: z.number() }).optional()
-    }
+      sheet: z2.string(),
+      region: z2.object({ x0: z2.number(), y0: z2.number(), x1: z2.number(), y1: z2.number() }).optional()
+    },
+    outputSchema: readSheetTextOutput
   }, run("read_sheet_text", (a) => session.readSheetText(a.sheet, a.region)));
 }
 
@@ -1374,7 +1512,7 @@ function registerResources(server, session) {
 // package.json
 var package_default = {
   name: "opentakeoff-mcp",
-  version: "0.2.0",
+  version: "0.4.0",
   mcpName: "io.github.Kentucky-ai/opentakeoff",
   type: "module",
   description: "OpenTakeoff MCP server \u2014 drive the takeoff engine from your MCP client over stdio.",
@@ -1386,9 +1524,11 @@ var package_default = {
     dev: "node --import tsx server.ts",
     start: "node dist/server.js",
     build: "esbuild server.ts --bundle --platform=node --format=esm --packages=external --outfile=dist/server-core.js && node scripts/finish-build.mjs",
+    "smoke:dist": "node scripts/smoke-dist.mjs",
+    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/*.test.ts"
+    test: "node --import tsx --test test/e2e.test.ts test/resources.test.ts test/session.test.ts test/tools.test.ts"
   },
   dependencies: {
     "@modelcontextprotocol/sdk": "^1.12.0",

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "opentakeoff-mcp",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "mcpName": "io.github.Kentucky-ai/opentakeoff",
   "type": "module",
-  "description": "OpenTakeoff MCP server \u2014 drive the takeoff engine from your MCP client over stdio.",
+  "description": "OpenTakeoff MCP server — drive the takeoff engine from your MCP client over stdio.",
   "license": "Apache-2.0",
   "engines": {
     "node": ">=20"
@@ -12,9 +12,11 @@
     "dev": "node --import tsx server.ts",
     "start": "node dist/server.js",
     "build": "esbuild server.ts --bundle --platform=node --format=esm --packages=external --outfile=dist/server-core.js && node scripts/finish-build.mjs",
+    "smoke:dist": "node scripts/smoke-dist.mjs",
+    "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/*.test.ts"
+    "test": "node --import tsx --test test/e2e.test.ts test/resources.test.ts test/session.test.ts test/tools.test.ts"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",