opentakeoff-mcp 0.1.3 → 0.2.0

package/README.md

@@ -1,5 +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).
+
 ## Run it in 60 seconds (npx)
 
 No clone, no build — point your MCP client at the published package:
@@ -25,6 +28,25 @@ app autosaves. Same engine, same math: the server imports
 `web/src/lib/{oneclick,sheets,geometry,totals}` directly, so a shape committed
 here is field-identical to one committed on the canvas.
 
+## Run with Docker
+
+Build from the repository root so the Dockerfile can bundle the shared web
+engine:
+
+```bash
+docker build -f mcp/Dockerfile -t opentakeoff-mcp .
+docker run --rm -i opentakeoff-mcp
+```
+
+Mount local plans read-only and pass that container path to `load_plan`:
+
+```bash
+docker run --rm -i -v "$PWD/demo:/plans:ro" opentakeoff-mcp
+docker run --rm -i -e OPENTAKEOFF_MCP_TRACE=1 -v "$PWD/demo:/plans:ro" opentakeoff-mcp
+```
+
+For example, load `/plans/sample-plan.pdf` after mounting `demo/`.
+
 ## Quickstart
 
 Both `web/` and `mcp/` need their dependencies (the engine's pdf.js lives in
@@ -85,6 +107,31 @@ includes document text, shape vertices, or result payload content.
 Every reply is one compact JSON text item. Failures come back as
 `isError: true` with `{"error": "..."}` — never a dropped connection.
 
+## Resources — browse before you measure
+
+Tools let an agent act; resources let it **see**. When a plan loads, the sheet
+set becomes browsable natively (`resources/list` re-announces itself via
+`list_changed`):
+
+| URI | Contents |
+|---|---|
+| `takeoff://sheets` | The plan index — file, page count, every sheet's dims, title-block number, detected scale, scale state, shape count. Always listed; before any plan loads it says so and points at `load_plan`. |
+| `takeoff://sheet/{page}` | One sheet's metadata (JSON), addressed by 1-based page number. |
+| `takeoff://sheet/{page}/text` | The sheet's text, joined — title block, room labels, schedules. Positions live in the `read_sheet_text` tool. |
+| `takeoff://sheet/{page}/image` | The page rendered to PNG, long edge capped at **1568 px** — the native resolution of vision-model eyes. Rendered lazily, cached until the next `load_plan`. |
+
+Page numbers — not file-derived sheet keys — address resources, so URIs stay
+clean regardless of the PDF's name; the human-facing key (`plan.pdf#2`) and
+title-block number (`A-101`) ride along as the resource name and title.
+Rendering uses `@napi-rs/canvas` (pdf.js's own optional dependency): on a
+platform without a prebuilt binary every non-raster capability still works and
+the image read explains exactly what's missing.
+
+The intended agent loop: read `takeoff://sheets` → look at
+`takeoff://sheet/{page}/image` → pick click targets → measure with the tools.
+An image coordinate maps to the tool space (image px at render scale 2.0) by
+multiplying by `width_px / <image pixel width>`.
+
 ## The coordinate contract
 
 All coordinates are **image pixels at render scale 2.0**: PDF points × 2,
@@ -143,3 +190,23 @@ sheet number (`A-101`) wherever a sheet is named.
 npm run typecheck
 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.
+
+```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:
+git tag mcp-v<version> && git push origin mcp-v<version>
+```
+
+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>`).

package/dist/server-core.js

@@ -14,7 +14,7 @@ if (typeof Promise.withResolvers !== "function") {
 
 // server.ts
 import { pathToFileURL } from "node:url";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer as McpServer2 } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/session.ts
@@ -126,6 +126,21 @@ function detectScale(textContent, viewport) {
 var requireHere = createRequire(import.meta.url);
 var PDFJS_ROOT = path.dirname(requireHere.resolve("pdfjs-dist/package.json"));
 var OPS2 = pdfjs.OPS;
+async function ensureCanvasGlobals() {
+  const g = globalThis;
+  if (g.Path2D && g.DOMMatrix && g.ImageData) return;
+  let napi;
+  try {
+    napi = await import("@napi-rs/canvas");
+  } catch {
+    throw new Error(
+      "Page rendering needs @napi-rs/canvas (pdfjs-dist's optional dependency), which did not install on this platform. Reinstall with optional dependencies enabled."
+    );
+  }
+  g.Path2D ??= napi.Path2D;
+  g.DOMMatrix ??= napi.DOMMatrix;
+  g.ImageData ??= napi.ImageData;
+}
 async function openPdf(filePath) {
   const bytes = await readFile(filePath);
   const doc = await pdfjs.getDocument({
@@ -151,7 +166,19 @@ async function openPdf(filePath) {
         heightPt: vp1.height,
         viewport: { width: vp.width, height: vp.height, transform: vp.transform },
         textContent,
-        operatorList: async () => await page.getOperatorList()
+        operatorList: async () => await page.getOperatorList(),
+        async renderPng(scale) {
+          await ensureCanvasGlobals();
+          const rvp = page.getViewport({ scale });
+          const factory = doc.canvasFactory;
+          const target = factory.create(Math.ceil(rvp.width), Math.ceil(rvp.height));
+          try {
+            await page.render({ canvasContext: target.context, viewport: rvp }).promise;
+            return new Uint8Array(target.canvas.toBuffer("image/png"));
+          } finally {
+            factory.destroy(target);
+          }
+        }
       };
     },
     destroy: () => doc.destroy().then(() => void 0)
@@ -859,6 +886,7 @@ var HATCH_IDS = ["solid", "diag", "diag2", "cross", "diagdense", "horiz", "vert"
 var _idn = 0;
 var uid = (p) => `${p}-${Date.now().toString(36)}-${(_idn++).toString(36)}`;
 var ANN_SCHEMA = "opentakeoff.takeoff_canvas.v1";
+var IMAGE_MAX_EDGE = 1568;
 var sheetSummary = (s) => ({
   sheet: s.key,
   page: s.pageNum,
@@ -920,6 +948,41 @@ var Session = class {
     for (const s of this.sheets.values()) if (s.sheetNumber === wanted) return s;
     throw new UserError(`Unknown sheet "${name}" \u2014 loaded sheets: ${[...this.sheets.keys()].join(", ")}.`);
   }
+  /** Resource-URI addressing: sheets by 1-based page number. */
+  sheetForPage(page) {
+    if (!this.doc) throw new UserError("No plan loaded \u2014 call load_plan first.");
+    for (const s of this.sheets.values()) if (s.pageNum === page) return s;
+    throw new UserError(`No page ${page} \u2014 the loaded plan has pages 1\u2013${this.sheets.size}.`);
+  }
+  /** Every loaded sheet, in page order — [] before any plan loads. */
+  sheetList() {
+    return [...this.sheets.values()].sort((a, b) => a.pageNum - b.pageNum);
+  }
+  /** The takeoff://sheets index payload — cheap (no geometry is built). */
+  index() {
+    if (!this.doc) {
+      return { file: null, page_count: 0, sheets: [], hint: "No plan loaded \u2014 call the load_plan tool with a PDF path, then list resources again." };
+    }
+    return {
+      file: this.file,
+      page_count: this.sheets.size,
+      sheets: this.sheetList().map((s) => ({
+        ...sheetSummary(s),
+        scale_set: s.upp != null,
+        shape_count: this.shapes.filter((x) => x.sheet_id === s.key).length
+      }))
+    };
+  }
+  /** Rendered-page PNG, long edge capped at IMAGE_MAX_EDGE (never above the
+   * canvas-native RENDER_SCALE), cached per sheet until the next load_plan. */
+  async renderSheetPng(page) {
+    const s = this.sheetForPage(page);
+    if (!s.png) {
+      const scale = Math.min(RENDER_SCALE, IMAGE_MAX_EDGE / Math.max(s.widthPt, s.heightPt));
+      s.png = await s.page.renderPng(scale);
+    }
+    return s.png;
+  }
   async ensureGeometry(s) {
     if (!s.geo) {
       const opList = await s.page.operatorList();
@@ -1151,9 +1214,13 @@ 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. ${COORDS}`,
+    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") }
-  }, run("load_plan", ({ path: path3 }) => session.loadPlan(path3)));
+  }, run("load_plan", async ({ path: path3 }) => {
+    const loaded = await session.loadPlan(path3);
+    server.sendResourceListChanged();
+    return loaded;
+  }));
   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")') }
@@ -1228,10 +1295,86 @@ function registerTools(server, session) {
   }, run("read_sheet_text", (a) => session.readSheetText(a.sheet, a.region)));
 }
 
+// src/resources.ts
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+function toBase64(bytes) {
+  return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString("base64");
+}
+function parsePage(session, raw) {
+  const s = Array.isArray(raw) ? raw[0] : raw;
+  if (!/^\d+$/.test(s ?? "")) throw new Error(`Sheet resources are addressed by page number \u2014 got ${JSON.stringify(s)}.`);
+  return session.sheetForPage(Number(s));
+}
+function registerResources(server, session) {
+  const sheetEntries = (suffix, mimeType, what) => () => ({
+    resources: session.sheetList().map((s) => ({
+      uri: `takeoff://sheet/${s.pageNum}${suffix}`,
+      name: `${s.key}${suffix.replace("/", " \xB7 ")}`,
+      ...s.sheetNumber ? { title: `${s.sheetNumber} \u2014 ${what}` } : { title: `page ${s.pageNum} \u2014 ${what}` },
+      description: `${what} for ${s.key}${s.sheetNumber ? ` (${s.sheetNumber})` : ""}`,
+      mimeType
+    }))
+  });
+  server.registerResource(
+    "sheet-index",
+    "takeoff://sheets",
+    {
+      title: "Sheet index",
+      description: "The loaded plan set at a glance: file, page count, and every sheet's dims, title-block number, detected scale, scale state, and shape count. Read this first.",
+      mimeType: "application/json"
+    },
+    async (uri) => ({
+      contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(session.index()) }]
+    })
+  );
+  server.registerResource(
+    "sheet",
+    new ResourceTemplate("takeoff://sheet/{page}", { list: sheetEntries("", "application/json", "sheet metadata") }),
+    {
+      title: "Sheet metadata",
+      description: "One sheet: dims (px and pt), title-block sheet number, detected scale, scale state, committed shape count. JSON.",
+      mimeType: "application/json"
+    },
+    async (uri, { page }) => {
+      const s = parsePage(session, page);
+      const idx = session.index();
+      const row = idx.sheets.find((x) => x.page === s.pageNum);
+      return { contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(row) }] };
+    }
+  );
+  server.registerResource(
+    "sheet-text",
+    new ResourceTemplate("takeoff://sheet/{page}/text", { list: sheetEntries("/text", "text/plain", "sheet text") }),
+    {
+      title: "Sheet text",
+      description: "The sheet's text content, reading order, joined \u2014 title block, room labels, schedules, scale notes. For positions use the read_sheet_text tool.",
+      mimeType: "text/plain"
+    },
+    async (uri, { page }) => {
+      const s = parsePage(session, page);
+      return { contents: [{ uri: uri.href, mimeType: "text/plain", text: session.readSheetText(s.key).text }] };
+    }
+  );
+  server.registerResource(
+    "sheet-image",
+    new ResourceTemplate("takeoff://sheet/{page}/image", { list: sheetEntries("/image", "image/png", "rendered page") }),
+    {
+      title: "Rendered page",
+      description: "The page rendered to PNG, long edge capped at 1568 px \u2014 sized for vision-model eyes. Coordinates in the image scale linearly to the tool coordinate space (image px at render scale 2.0).",
+      mimeType: "image/png"
+    },
+    async (uri, { page }) => {
+      const s = parsePage(session, page);
+      const png = await session.renderSheetPng(s.pageNum);
+      return { contents: [{ uri: uri.href, mimeType: "image/png", blob: toBase64(png) }] };
+    }
+  );
+}
+
 // package.json
 var package_default = {
   name: "opentakeoff-mcp",
-  version: "0.1.3",
+  version: "0.2.0",
   mcpName: "io.github.Kentucky-ai/opentakeoff",
   type: "module",
   description: "OpenTakeoff MCP server \u2014 drive the takeoff engine from your MCP client over stdio.",
@@ -1286,8 +1429,9 @@ var package_default = {
 
 // server.ts
 function buildServer(session = new Session()) {
-  const server = new McpServer({ name: "opentakeoff", version: package_default.version });
+  const server = new McpServer2({ name: "opentakeoff", version: package_default.version });
   registerTools(server, session);
+  registerResources(server, session);
   return server;
 }
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {

package/package.json

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