opentakeoff-mcp 0.7.0 → 0.8.0

package/README.md

@@ -115,8 +115,10 @@ 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. |
 | `edit_shape` | **Revise** a committed shape instead of redoing it: new `verts`, a different `condition`, a different `role`, or any combination — quantities recomputed from the result. Refuses shapes a human affirmed. |
-| `undo_last` | Step back over your own last `n` mutations, newest first. Exact inverses: a commit is removed, an edit restored verbatim, a delete re-inserted where it was. A whole `detect_rooms` sweep is **one** step. |
+| `edit_materials` | Add/remove/patch supporting-materials rows on a condition — the coverage-rate lines (adhesive at N sf/gal, grout at N lf/bag, …) that turn a measured quantity into an order quantity, matching the canvas's Supporting Materials panel. `condition` mints on first touch, like `one_click`/`measure_polygon`. No review gate (materials rows are quantity config, not traced geometry) — edits directly, reversible with `undo_last`. |
+| `undo_last` | Step back over your own last `n` mutations, newest first. Exact inverses: a commit is removed, an edit restored verbatim, a delete re-inserted where it was, a materials edit's whole array restored. A whole `detect_rooms` sweep is **one** step. |
 | `read_sheet_text` | Positioned page text (image px), optionally restricted to a region — title blocks, room labels, finish schedules. |
+| `find_text` | **Locate** a known string — the complement to `read_sheet_text` (which returns what a region *says*; this finds *where* a string sits). Case-insensitive substring match per pdf.js text run; each hit's center feeds straight into `one_click`'s seed. |
 | `sheet_context` | The region's STRUCTURE in one frame: classified vector segments (endpoints as drawn, meta byte per segment), text spans with bboxes, and hatch-family instances with content-derived ids — same pattern spec ⇒ same id anywhere on the sheet, so plan↔legend matching is `id === id`. Decimation is declared and counted on every reply: `kept + dropped === total_in_region`, cap applies longest-first so walls survive. |
 | `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. |
 

package/dist/server-core.js

@@ -1711,6 +1711,64 @@ var Session = class {
       agent_edits: this.shapes[i].origin?.agent_edits ?? 0
     };
   }
+  /** Add/remove/patch supporting-materials rows on a condition, in one call.
+   * Unlike editShape there is no review gate to check — materials rows carry
+   * no origin/reviewed field, because they are quantity CONFIG (a coverage
+   * rate), not geometry a human traced. Validated all-or-nothing before
+   * anything is written: a bad id anywhere in remove/patch throws and nothing
+   * changes, same discipline as the shapes tools. Reversible with undo_last —
+   * one journal entry snapshots the condition's whole materials array before
+   * the call, restored verbatim on undo (same pattern as editShape's `before`
+   * capture, simpler here because there is no per-row provenance to preserve). */
+  editMaterials(tag, opts) {
+    const add = opts.add ?? [], remove = opts.remove ?? [], patch = opts.patch ?? [];
+    if (!add.length && !remove.length && !patch.length) {
+      throw new UserError("Nothing to change \u2014 pass at least one of add, remove, patch.");
+    }
+    for (let i = 0; i < add.length; i++) {
+      if (!add[i].name.trim()) throw new UserError(`add[${i}]: name required.`);
+    }
+    const existingMaterials = this.conditions.find((x) => x.finish_tag === tag)?.materials ?? [];
+    const byId = new Map(existingMaterials.map((m) => [m.id, m]));
+    for (const id of remove) {
+      if (!byId.has(id)) throw new UserError(`remove: no material row ${JSON.stringify(id)} on condition ${JSON.stringify(tag)}.`);
+    }
+    for (let i = 0; i < patch.length; i++) {
+      if (!byId.has(patch[i].id)) throw new UserError(`patch[${i}]: no material row ${JSON.stringify(patch[i].id)} on condition ${JSON.stringify(tag)}.`);
+      if (!Object.keys(patch[i].fields).length) throw new UserError(`patch[${i}]: fields must be non-empty.`);
+    }
+    const c = this.conditionFor(tag);
+    const before = structuredClone(c.materials);
+    const added = [];
+    for (const a of add) {
+      const row = {
+        id: uid("mat"),
+        name: a.name.trim(),
+        per: Math.max(0, a.per ?? 0),
+        basis: a.basis ?? "area",
+        unit: a.unit ?? "",
+        round: a.round ?? true,
+        ...a.note ? { note: a.note } : {}
+      };
+      c.materials.push(row);
+      added.push(row.id);
+    }
+    const removed = new Set(remove);
+    if (removed.size) c.materials = c.materials.filter((m) => !removed.has(m.id));
+    const patched = [];
+    for (const p of patch) {
+      const m = c.materials.find((x) => x.id === p.id);
+      Object.assign(m, p.fields);
+      patched.push(p.id);
+    }
+    this.record({ op: "materials", tool: "edit_materials", condition_id: c.id, before });
+    return {
+      condition: tag,
+      condition_id: c.id,
+      changed: { added, removed: [...removed], patched },
+      materials: c.materials
+    };
+  }
   /** Step back over this session's own last n mutations, newest first. Each
    * entry's inverse is exact (see JournalEntry), so this restores state rather
    * than approximating it. Reads are not journaled, so undo never has to step
@@ -1728,6 +1786,10 @@ var Session = class {
         const i = this.shapes.findIndex((x) => x.id === e.before.id);
         if (i >= 0) this.shapes[i] = e.before;
         undone.push({ seq: e.seq, op: e.op, tool: e.tool, shapes: i >= 0 ? 1 : 0 });
+      } else if (e.op === "materials") {
+        const c = this.conditions.find((x) => x.id === e.condition_id);
+        if (c) c.materials = e.before;
+        undone.push({ seq: e.seq, op: e.op, tool: e.tool, shapes: 0 });
       } else {
         for (const { shape, index } of e.removed) {
           this.shapes.splice(Math.min(index, this.shapes.length), 0, shape);
@@ -1766,6 +1828,30 @@ var Session = class {
     const items = region ? s.text.filter((t) => t.x >= region.x0 && t.x <= region.x1 && t.y >= region.y0 && t.y <= region.y1) : s.text;
     return { sheet: s.key, items, text: items.map((t) => t.str).join(" ") };
   }
+  /** LOCATE a known string — the complement to readSheetText (which returns
+   * what a region SAYS; this finds WHERE a string you already know sits).
+   * Case-insensitive substring match per pdf.js text run, so a room label
+   * split across runs ("OFFICE" then "134" as separate items) needs its own
+   * find_text call per fragment, or read_sheet_text over a region to see the
+   * whole thing at once — this tool doesn't merge runs into lines. Reuses the
+   * bbox spans sheet_context lazily builds (same cache, same textSpans()
+   * call), so calling both on one sheet costs the extraction once. */
+  findText(name, q, opts = {}) {
+    const query = q.trim();
+    if (!query) throw new UserError("q must be a non-empty string.");
+    const s = this.sheet(name);
+    if (!s.spans) s.spans = textSpans(s.page);
+    const r = opts.region;
+    const needle = query.toLowerCase();
+    const limit = opts.limit ?? 200;
+    const all = s.spans.filter((sp) => sp.str.toLowerCase().includes(needle) && (!r || sp.x0 <= r.x1 && sp.x1 >= r.x0 && sp.y0 <= r.y1 && sp.y1 >= r.y0));
+    const hits = all.slice(0, limit).map((sp) => ({
+      str: sp.str,
+      bbox: [sp.x0, sp.y0, sp.x1, sp.y1],
+      center: [round1((sp.x0 + sp.x1) / 2), round1((sp.y0 + sp.y1) / 2)]
+    }));
+    return { sheet: s.key, q: query, count: all.length, truncated: all.length > hits.length, hits };
+  }
 };
 
 // src/tools.ts
@@ -1949,14 +2035,44 @@ var undoLastOutput = {
   undone: z.number().int().describe("Steps actually reversed"),
   steps: z.array(z.object({
     seq: z.number().int(),
-    op: z.enum(["commit", "edit", "delete"]),
+    op: z.enum(["commit", "edit", "delete", "materials"]),
     tool: z.string().describe("The tool call this step came from"),
-    shapes: z.number().int().describe("Shapes affected by reversing this step")
+    shapes: z.number().int().describe("Shapes affected by reversing this step \u2014 0 for a materials step (it restores a condition's supporting-materials rows, not shapes)")
   })).describe("Newest first"),
   shape_count: z.number().int().describe("Committed shapes after the undo"),
   remaining: z.number().int().describe("Steps still available to undo"),
   note: z.string().optional()
 };
+var findTextOutput = {
+  sheet: z.string(),
+  q: z.string(),
+  count: z.number().int().describe("Total matches before the limit cap"),
+  truncated: z.boolean().describe("true = count exceeds hits.length; narrow the region or raise limit"),
+  hits: z.array(z.object({
+    str: z.string().describe("The matched pdf.js text run, verbatim (may be shorter than the full label \u2014 runs aren't merged into lines)"),
+    bbox: z.tuple([z.number(), z.number(), z.number(), z.number()]).describe("[x0, y0, x1, y1] image px"),
+    center: z.tuple([z.number(), z.number()]).describe("Bbox center, image px \u2014 feed straight into one_click's seed")
+  }))
+};
+var materialRow = z.object({
+  id: z.string(),
+  name: z.string(),
+  per: z.number().describe("Coverage rate: basis \xF7 per = order quantity"),
+  basis: z.enum(["area", "linear", "count"]).describe("Which of the condition's totals this row's quantity is computed against"),
+  unit: z.string(),
+  round: z.boolean().describe("true = round up to whole purchase units (the default \u2014 you buy whole bags/buckets)"),
+  note: z.string().optional()
+});
+var editMaterialsOutput = {
+  condition: z.string().describe("The finish tag passed in"),
+  condition_id: z.string(),
+  changed: z.object({
+    added: z.array(z.string()).describe("Ids of newly added rows"),
+    removed: z.array(z.string()).describe("Ids removed"),
+    patched: z.array(z.string()).describe("Ids whose fields changed")
+  }),
+  materials: z.array(materialRow).describe("The condition's full materials array after this write")
+};
 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)"),
@@ -2129,8 +2245,28 @@ function registerTools(server, session) {
     },
     outputSchema: editShapeOutput
   }, run("edit_shape", (a) => session.editShape(a.shape_id, { verts: a.verts, condition: a.condition, role: a.role })));
+  server.registerTool("edit_materials", {
+    description: `Add, remove, or patch supporting-materials rows on a condition \u2014 the coverage-rate lines that turn a measured area/length/count into an order quantity (adhesive at N sf/gal, grout at N lf/bag, \u2026), matching the canvas's per-condition Supporting Materials panel. Each row is {name, per, basis, unit, round, note}: quantity = the condition's basis total (area/linear/count) \xF7 per, rounded up to whole purchase units unless round:false. condition names an existing OR NEW finish tag (minted on first touch, same as one_click/measure_polygon) \u2014 add alone is enough to seed materials on a condition before you've traced anything. remove/patch target existing row ids from this reply or export_takeoff (takeoff_summary strips materials for a compact quantities-only reply); a bad id 404s the WHOLE call before anything is written, and referencing an id on a tag with no condition yet errors rather than silently minting an empty one. No review gate here \u2014 materials rows are quantity config, not traced geometry, so this edits directly; undo_last reverses a call in one step (the condition's whole materials array, snapshotted before the write, restored verbatim).`,
+    inputSchema: {
+      condition: z2.string().describe("Finish tag, e.g. 'CPT-1'"),
+      add: z2.array(z2.object({
+        name: z2.string().min(1),
+        per: z2.number().min(0).optional().describe("Coverage rate \u2014 basis units per purchase unit, e.g. 250 for 1 gal / 250 sf. Default 0 (quantity 0 until set)"),
+        basis: z2.enum(["area", "linear", "count"]).optional().describe("Which of the condition's totals this row divides against \u2014 default 'area' (total SF)"),
+        unit: z2.string().optional().describe("Purchase unit, e.g. 'gal', 'bag', 'roll'"),
+        round: z2.boolean().optional().describe("Round up to whole purchase units \u2014 default true"),
+        note: z2.string().optional()
+      })).optional().describe("New rows to add"),
+      remove: z2.array(z2.string()).optional().describe("Existing row ids to remove"),
+      patch: z2.array(z2.object({
+        id: z2.string(),
+        fields: z2.record(z2.union([z2.string(), z2.number(), z2.boolean()])).describe("Field:value pairs \u2014 name/per/basis/unit/round/note only")
+      })).optional().describe("Field changes on existing rows")
+    },
+    outputSchema: editMaterialsOutput
+  }, run("edit_materials", (a) => session.editMaterials(a.condition, { add: a.add, remove: a.remove, patch: a.patch })));
   server.registerTool("undo_last", {
-    description: `Step back over your OWN last n mutations, newest first \u2014 a committed one_click, a whole detect_rooms sweep, an edit_shape, or a delete_shape. Each step is reversed exactly (a commit is removed, an edit is restored verbatim, a delete is re-inserted where it was), so this restores state rather than approximating it. Reads are never journaled, so n counts gestures that changed something, not tool calls you made. Use it when a sweep committed against the wrong condition or a batch went in on the wrong sheet \u2014 one call instead of N deletes. Scope: this session's own history only. It is not the browser canvas's undo stack, and load_plan clears it along with the shapes it refers to.`,
+    description: `Step back over your OWN last n mutations, newest first \u2014 a committed one_click, a whole detect_rooms sweep, an edit_shape, a delete_shape, or an edit_materials call. Each step is reversed exactly (a commit is removed, an edit is restored verbatim, a delete is re-inserted where it was, a materials edit's whole array is restored), so this restores state rather than approximating it. Reads are never journaled, so n counts gestures that changed something, not tool calls you made. Use it when a sweep committed against the wrong condition or a batch went in on the wrong sheet \u2014 one call instead of N deletes. Scope: this session's own history only. It is not the browser canvas's undo stack, and load_plan clears it along with the shapes it refers to.`,
     inputSchema: {
       n: z2.number().int().min(1).max(UNDO_CAP).default(1).describe(`How many steps to reverse (1\u2013${UNDO_CAP})`)
     },
@@ -2144,6 +2280,16 @@ function registerTools(server, session) {
     },
     outputSchema: readSheetTextOutput
   }, run("read_sheet_text", (a) => session.readSheetText(a.sheet, a.region)));
+  server.registerTool("find_text", {
+    description: `LOCATE a known string on a sheet \u2014 the complement to read_sheet_text (which returns what a region SAYS; this finds WHERE a string you already know sits). Case-insensitive substring match against each pdf.js text run, so a room label split across runs ("OFFICE" then "134" as separate items) needs a find_text call per fragment, or read_sheet_text over a region to see the whole thing joined. Every hit's center feeds straight into one_click as the seed \u2014 the locate-then-trace workflow: find_text the room number, one_click at (or just past) its center. Optionally restrict to a region {x0, y0, x1, y1}; results cap at limit (default 200), with count/truncated telling you exactly how much a tighter region or higher limit would recover. ${COORDS}`,
+    inputSchema: {
+      sheet: z2.string(),
+      q: z2.string().min(1).describe("Text to find \u2014 a room number ('134'), a label fragment ('RECEPTION'), a schedule tag ('CPT-1')"),
+      region: z2.object({ x0: z2.number(), y0: z2.number(), x1: z2.number(), y1: z2.number() }).optional().describe("Rect in image px (origin top-left, y down); omit for the full sheet"),
+      limit: z2.number().int().min(1).max(2e3).default(200).describe("Max hits returned")
+    },
+    outputSchema: findTextOutput
+  }, run("find_text", (a) => session.findText(a.sheet, a.q, { region: a.region, limit: a.limit })));
   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: {
@@ -2246,7 +2392,7 @@ function registerResources(server, session) {
 // package.json
 var package_default = {
   name: "opentakeoff-mcp",
-  version: "0.7.0",
+  version: "0.8.0",
   mcpName: "io.github.Kentucky-ai/opentakeoff",
   type: "module",
   description: "OpenTakeoff MCP server \u2014 drive the takeoff engine from your MCP client over stdio.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opentakeoff-mcp",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "mcpName": "io.github.Kentucky-ai/opentakeoff",
   "type": "module",
   "description": "OpenTakeoff MCP server \u2014 drive the takeoff engine from your MCP client over stdio.",