opentakeoff-mcp 0.7.0 → 0.9.0

package/README.md

@@ -1,7 +1,8 @@
 # OpenTakeoff MCP server
 
 Listed in the [official MCP registry](https://registry.modelcontextprotocol.io) as
-`io.github.Kentucky-ai/opentakeoff` and on [Glama](https://glama.ai/mcp/servers/Kentucky-ai/opentakeoff).
+`io.github.Kentucky-ai/opentakeoff`, on [Glama](https://glama.ai/mcp/servers/Kentucky-ai/opentakeoff),
+and on [Smithery](https://smithery.ai/servers/Kentucky-ai/opentakeoff).
 
 ## Run it in 60 seconds (npx)
 
@@ -115,8 +116,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. |
 
@@ -238,23 +241,48 @@ npm test        # session + tool-layer + e2e, against demo/sample-plan.pdf
 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). 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.
+runs straight through — no approval click — and 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. The `release` environment's required-reviewer gate existed
+briefly and was deliberately removed (2026-07-22) — the tag push is the one
+human decision, and it's already admin-gated, so a second click added
+friction without adding safety.
 
 ```bash
 # 1. bump the version — all three fields together:
 #    package.json .version, server.json .version, server.json .packages[0].version
-# 2. tag and push — this fires the whole release:
+# 2. tag and push — this fires the whole release, fully unattended:
 git tag mcp-v<version> && git push origin mcp-v<version>
-# 3. approve the run (GitHub → Actions → the paused "Publish to MCP Registry" run)
 ```
 
+⚠️ Because there's no approval step, an accidental or mistyped `mcp-v*` tag
+publishes to npm immediately, and npm unpublish is heavily restricted —
+double-check the version before tagging.
+
 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.
+
+### Refreshing the Smithery listing
+
+Smithery isn't part of the automated release above — it needs a **separate,
+manual** publish after any tool signature change, because of a genuine spec
+conflict between two validators: the official MCPB validator (what
+`npm run mcpb` gates on) rejects a `tools[].inputSchema` key outright, while
+Smithery's registry rejects a bundle *without* real `inputSchema` per tool
+(smithery-ai/cli#770, #797, #787 — no manifest satisfies both). The canonical
+`dist-mcpb/opentakeoff-mcp.mcpb` stays spec-compliant for Claude Desktop / the
+official registry / Glama; `scripts/build-smithery-mcpb.mjs` builds a
+Smithery-only bundle instead, with live-introspected tools + inputSchema baked
+in, packed with a plain zip (bypassing `mcpb validate`, which would reject it):
+
+```bash
+npm run build
+node scripts/build-smithery-mcpb.mjs
+smithery mcp publish dist-smithery/opentakeoff-mcp.mcpb -n Kentucky-ai/opentakeoff
+```

package/dist/server-core.js

@@ -1073,7 +1073,7 @@ function drawShapes(ctx, toCanvas, shapes, sheetW, sheetH, longEdge) {
 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 HATCH_IDS = ["solid", "diag", "diag2", "cross", "diagdense", "horiz", "vert", "grid", "brick", "plank", "herring", "basket", "checker", "wave", "dots", "speckle", "iso", "honeycomb", "scan", "plus", "circuit", "topo"];
 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";
@@ -1121,6 +1121,7 @@ var Session = class {
   doc = null;
   sheets = /* @__PURE__ */ new Map();
   conditions = [];
+  markups = [];
   shapes = [];
   /** Newest-last. Capped at UNDO_CAP; the oldest entry falls off the front. */
   journal = [];
@@ -1148,6 +1149,7 @@ var Session = class {
     this.sheets.clear();
     this.conditions = [];
     this.shapes = [];
+    this.markups = [];
     this.file = null;
     this.journal = [];
     this.pendingCommits = [];
@@ -1711,6 +1713,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 +1788,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);
@@ -1743,6 +1807,95 @@ var Session = class {
       ...undone.length < n ? { note: `Only ${undone.length} step(s) were available to undo.` } : {}
     };
   }
+  /** Place an annotation. A note ABOUT the work — it never measures anything
+   *  and never touches a quantity, which is why there is no review gate here:
+   *  the pencil-not-ink rule exists to stop an agent inventing GEOMETRY, and a
+   *  cloud saying "verify substrate" is not geometry.
+   *
+   *  `condition` attaches it to a scope by finish tag, minting the condition on
+   *  first touch exactly like one_click/measure_polygon — so an agent can note
+   *  something about CPT-1 before anything is traced for CPT-1. Omit it for a
+   *  note about the sheet rather than about a finish. */
+  annotate(a) {
+    const s = this.sheet(a.sheet);
+    const n = ([x, y]) => [x / s.widthPx, y / s.heightPx];
+    if ((a.type === "cloud" || a.type === "highlight") && !a.rect) throw new UserError(`a ${a.type} needs rect: [[x0,y0],[x1,y1]] in image px`);
+    if ((a.type === "text" || a.type === "callout") && !a.at) throw new UserError(`a ${a.type} needs at: [x,y] in image px`);
+    if (a.type === "callout" && !a.target) throw new UserError("a callout needs target: [x,y] \u2014 the point the leader line aims at");
+    const cond = a.condition ? this.conditionFor(a.condition) : null;
+    const m = {
+      id: uid("mk"),
+      sheet_id: s.key,
+      type: a.type,
+      text: a.text || "",
+      condition_id: cond?.id ?? "",
+      rfi_id: "",
+      created_at: (/* @__PURE__ */ new Date()).toISOString(),
+      ...a.at ? { at: n(a.at) } : {},
+      ...a.target ? { target: n(a.target) } : {},
+      ...a.rect ? { rect: [n(a.rect[0]), n(a.rect[1])] } : {}
+    };
+    this.markups.push(m);
+    return {
+      id: m.id,
+      sheet: s.key,
+      type: m.type,
+      text: m.text,
+      condition: cond?.finish_tag ?? "",
+      condition_id: m.condition_id,
+      note: cond ? `Attached to ${cond.finish_tag} \u2014 it wears that condition's colour on the canvas and in the marked set.` : "Unattached \u2014 a note about the sheet. Pass condition to tie it to a scope."
+    };
+  }
+  /** Read annotations, optionally narrowed to a sheet and/or a condition.
+   *  Resolves condition_id to its finish tag so a caller can act on the reply
+   *  without joining against the conditions array. */
+  listAnnotations(f = {}) {
+    const tagById = new Map(this.conditions.map((c) => [c.id, c.finish_tag]));
+    let rows = this.markups;
+    if (f.sheet) {
+      const s = this.sheet(f.sheet);
+      rows = rows.filter((m) => m.sheet_id === s.key);
+    }
+    if (f.condition) {
+      const c = this.conditions.find((x) => x.finish_tag === f.condition);
+      if (!c) throw new UserError(`no condition "${f.condition}" \u2014 tags: ${this.conditions.map((x) => x.finish_tag).join(", ") || "(none)"}`);
+      rows = rows.filter((m) => m.condition_id === c.id);
+    }
+    const s0 = this.sheets;
+    const px = (m, p) => {
+      const sh = s0.get(m.sheet_id);
+      if (!p || !sh) return void 0;
+      return [round1(p[0] * sh.widthPx), round1(p[1] * sh.heightPx)];
+    };
+    return {
+      annotations: rows.map((m) => ({
+        id: m.id,
+        sheet: m.sheet_id,
+        type: m.type,
+        text: m.text,
+        condition: tagById.get(m.condition_id) ?? "",
+        condition_id: m.condition_id,
+        ...m.at ? { at: px(m, m.at) } : {},
+        ...m.target ? { target: px(m, m.target) } : {},
+        ...m.rect ? { rect: [px(m, m.rect[0]), px(m, m.rect[1])] } : {}
+      })),
+      count: rows.length,
+      unattached: rows.filter((m) => !m.condition_id).length
+    };
+  }
+  /** Attach an existing annotation to a condition, or detach it with "". The
+   *  canvas's Attach/Detach, reachable by an agent. */
+  linkAnnotation(id, condition) {
+    const m = this.markups.find((x) => x.id === id);
+    if (!m) throw new UserError(`no annotation "${id}" \u2014 call list_annotations for real ids`);
+    if (!condition) {
+      m.condition_id = "";
+      return { id: m.id, condition: "", note: "Detached \u2014 now a note about the sheet." };
+    }
+    const c = this.conditionFor(condition);
+    m.condition_id = c.id;
+    return { id: m.id, condition: c.finish_tag, condition_id: c.id, note: `Attached to ${c.finish_tag}.` };
+  }
   /** The exact browser save payload (TakeoffCanvas.jsx autosave + the schema key
    * store.saveAnnotations stamps) — importable by the app. */
   exportPayload() {
@@ -1754,7 +1907,7 @@ var Session = class {
       sheets: [...this.sheets.values()].filter((s) => s.upp != null).map((s) => ({ sheet_id: s.key, units_per_px: s.upp })),
       conditions: this.conditions,
       shapes: this.shapes,
-      markups: [],
+      markups: this.markups,
       sheet_group: [],
       last_group: [],
       sheet_tabs: [],
@@ -1766,6 +1919,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 +2126,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)"),
@@ -1997,6 +2204,37 @@ var sheetContextOutput = {
   }),
   hatch: z.object({ families: z.array(hatchFamilyRow), count: z.number().int() })
 };
+var annotationRow = z.object({
+  id: z.string(),
+  sheet: z.string(),
+  type: z.string(),
+  text: z.string(),
+  condition: z.string().describe("Resolved finish tag, or '' when unattached \u2014 saves joining against conditions[]"),
+  condition_id: z.string(),
+  at: z.tuple([z.number(), z.number()]).optional(),
+  target: z.tuple([z.number(), z.number()]).optional(),
+  rect: z.array(z.tuple([z.number(), z.number()]).optional()).optional()
+});
+var annotateOutput = {
+  id: z.string(),
+  sheet: z.string(),
+  type: z.string(),
+  text: z.string(),
+  condition: z.string(),
+  condition_id: z.string(),
+  note: z.string()
+};
+var listAnnotationsOutput = {
+  annotations: z.array(annotationRow),
+  count: z.number().int(),
+  unattached: z.number().int().describe("How many carry no condition \u2014 candidates for link_annotation")
+};
+var linkAnnotationOutput = {
+  id: z.string(),
+  condition: z.string(),
+  condition_id: z.string().optional(),
+  note: z.string()
+};
 
 // 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.";
@@ -2129,8 +2367,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 +2402,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: {
@@ -2165,6 +2433,39 @@ function registerTools(server, session) {
     traceToolCall("view_sheet", a, startedAt, reply);
     return reply;
   });
+  server.registerTool("annotate", {
+    description: `Place an annotation on a sheet \u2014 a note ABOUT the work, never a measurement of it. Types: cloud and highlight take rect:[[x0,y0],[x1,y1]] (a revision cloud around an area, a highlight box over it), text takes at:[x,y], callout takes at:[x,y] plus target:[x,y] (the point its leader aims at). 
+
+Pass condition to attach the note to a finish tag, which is what makes it part of that SCOPE rather than a floating remark: it then wears the condition's colour on the canvas and in the marked-set PDF, and travels with it into the report. The tag is minted on first touch like one_click/measure_polygon, so you can annotate CPT-1 before anything is traced for it. Omit condition for a note about the sheet itself. 
+
+No review gate: the pencil-not-ink rule exists to stop an agent inventing geometry, and a cloud reading "verify substrate" is not geometry. It touches no quantity. ${COORDS}`,
+    inputSchema: {
+      sheet: z2.string().describe("Sheet name or number, as sheet_info reports it"),
+      type: z2.enum(["cloud", "text", "callout", "highlight"]).describe("cloud/highlight need rect; text/callout need at; callout also needs target"),
+      text: z2.string().default("").describe("The note. A cloud with no text still reads as 'look here'"),
+      condition: z2.string().optional().describe("Finish tag to attach this note to, e.g. 'CPT-1' (minted on first use). Omit for an unattached sheet note"),
+      at: pointSchema.optional().describe("Anchor point (image px) \u2014 text and callout"),
+      target: pointSchema.optional().describe("What a callout's leader line points at (image px)"),
+      rect: z2.tuple([pointSchema, pointSchema]).optional().describe("Corners (image px) \u2014 cloud and highlight")
+    },
+    outputSchema: annotateOutput
+  }, run("annotate", (a) => session.annotate(a)));
+  server.registerTool("list_annotations", {
+    description: `Every annotation on the takeoff, with condition_id RESOLVED to its finish tag so you can act on the reply without joining against conditions[]. Filter by sheet, by condition, or both. Coordinates come back in image px (the same frame you passed in), not the normalized form they're stored as. \`unattached\` counts the notes carrying no condition \u2014 the candidates for link_annotation. ${COORDS}`,
+    inputSchema: {
+      sheet: z2.string().optional().describe("Only annotations on this sheet"),
+      condition: z2.string().optional().describe("Only annotations attached to this finish tag")
+    },
+    outputSchema: listAnnotationsOutput
+  }, run("list_annotations", (a) => session.listAnnotations(a)));
+  server.registerTool("link_annotation", {
+    description: `Attach an existing annotation to a condition, or detach it by passing an empty condition \u2014 the canvas's Attach/Detach control, reachable by an agent. Use it to tie up notes left unattached (list_annotations reports how many), or to move one to the finish it actually concerns. Attaching mints the tag on first use.`,
+    inputSchema: {
+      annotation_id: z2.string().describe("Id from annotate or list_annotations"),
+      condition: z2.string().describe("Finish tag to attach to; empty string detaches")
+    },
+    outputSchema: linkAnnotationOutput
+  }, run("link_annotation", (a) => session.linkAnnotation(a.annotation_id, a.condition)));
 }
 
 // src/resources.ts
@@ -2246,7 +2547,7 @@ function registerResources(server, session) {
 // package.json
 var package_default = {
   name: "opentakeoff-mcp",
-  version: "0.7.0",
+  version: "0.9.0",
   mcpName: "io.github.Kentucky-ai/opentakeoff",
   type: "module",
   description: "OpenTakeoff MCP server \u2014 drive the takeoff engine from your MCP client over stdio.",
@@ -2297,7 +2598,12 @@ var package_default = {
     "estimating",
     "pdf",
     "quantity-takeoff",
-    "flooring"
+    "flooring",
+    "ai-agent",
+    "agentic-ai",
+    "preconstruction",
+    "construction-management",
+    "project-management"
   ],
   overrides: {
     "fast-uri": "^3.1.4",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opentakeoff-mcp",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "mcpName": "io.github.Kentucky-ai/opentakeoff",
   "type": "module",
   "description": "OpenTakeoff MCP server \u2014 drive the takeoff engine from your MCP client over stdio.",
@@ -51,10 +51,15 @@
     "estimating",
     "pdf",
     "quantity-takeoff",
-    "flooring"
+    "flooring",
+    "ai-agent",
+    "agentic-ai",
+    "preconstruction",
+    "construction-management",
+    "project-management"
   ],
   "overrides": {
     "fast-uri": "^3.1.4",
     "@hono/node-server": "^2.0.5"
   }
-}
+}