@obenor/mcp 0.1.0

package/README.md

@@ -0,0 +1,53 @@
+# @obenor/mcp
+
+Build parametric solid models in [Obenor3D](https://3d.obenor.com) from an MCP
+client — Codex, Claude Code, or anything else that speaks the protocol.
+
+```
+codex mcp add obenor3d --env OBENOR_LINK=<token> -- npx -y @obenor/mcp
+```
+
+`<token>` is the eight characters after `/s/` in an **Edit** share link. Make
+one from the Share sheet in the app; the sheet also writes this line out for
+you, with the token already in it.
+
+## What it is
+
+A full OpenCASCADE modelling kernel, driven as MCP tools: sketches, extrudes,
+booleans, fillets, sheet metal, surfacing, drawings, materials and offscreen
+renders. It edits the same document the browser has open, so a model built here
+appears on screen as it is built, and edits made on screen are adopted before
+the next tool runs.
+
+## The kernel is fetched, not shipped
+
+The geometry kernel is 24 MB of WebAssembly. Rather than put it in the tarball,
+the first run fetches it from the deployment you are connected to — by content
+hash, into `~/.obenor/kernel` — and every run after that is instant. `npx` is
+therefore a ~800 kB download rather than a 50 MB one, and a new kernel does not
+need a new release of this package.
+
+Point `OBENOR_ORIGIN` at your own deployment if you are not using
+`https://3d.obenor.com`; the kernel comes from wherever the app does.
+
+## Hosted alternative
+
+If you would rather install nothing at all, the app also speaks MCP over HTTP:
+
+```
+codex mcp add obenor3d --url https://3d.obenor.com/api/agent/mcp --bearer-token <token>
+```
+
+That runs every tool in the browser tab that has the model open, so the model
+has to be open — and it cannot read files on your machine. This package can do
+both: it works with no browser running, and it can read the blueprint sitting in
+your downloads folder.
+
+## Environment
+
+| | |
+|---|---|
+| `OBENOR_LINK` | Edit share-link token. Required to mirror a model. |
+| `OBENOR_ORIGIN` | Defaults to `https://3d.obenor.com`. |
+| `OBENOR_KERNEL_CACHE` | Defaults to `~/.obenor/kernel`. |
+| `OBENOR_BAKE` | `0` to stop baking meshes and a poster on publish. |

package/bin/obenor-mcp.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+/**
+ * The published entry point: `npx -y @obenor/mcp`.
+ *
+ * ── what this exists to avoid ──────────────────────────────────────────────
+ *
+ * The kernel is 24 MB of wasm, and there are two builds of it because -pthread
+ * changes the ABI. Putting them in the tarball makes a 50 MB package that has
+ * to be republished every time the geometry changes, and makes the first `npx`
+ * a long silent wait on whatever connection the person has.
+ *
+ * So the tarball carries the server and the emscripten glue - about a megabyte
+ * - and the binary is fetched on first run from the origin the session is
+ * already talking to, then cached under ~/.obenor/kernel. Second run is
+ * instant. And because the fetch is BY CONTENT HASH, the copy on disk can never
+ * be paired with a different build of the glue: a new kernel is a new directory
+ * rather than an overwrite, which is the failure `build-id.ts` was written to
+ * prevent inside the browser and the same failure out here.
+ *
+ * ── why the origin is the source ───────────────────────────────────────────
+ *
+ * `/k/<hash>/obenor-kernel.wasm` is already served by the app - it is how the
+ * browser gets its kernel - so there is no second artefact store to operate and
+ * no way for the two to disagree. A self-hosted install points OBENOR_ORIGIN at
+ * itself and gets its own kernel, which is the behaviour somebody running their
+ * own deployment would otherwise have to be told is impossible.
+ */
+import { createWriteStream } from 'node:fs';
+import { mkdir, rename, stat, unlink } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+
+const ORIGIN = (process.env['OBENOR_ORIGIN'] ?? 'https://3d.obenor.com').replace(/\/+$/u, '');
+const CACHE = process.env['OBENOR_KERNEL_CACHE'] ?? join(homedir(), '.obenor', 'kernel');
+
+
+/** stderr, never stdout: stdout is the MCP transport and a byte on it is a protocol error. */
+const say = (line) => { process.stderr.write(`obenor: ${line}\n`); };
+
+const exists = async (path) => {
+  try {
+    const info = await stat(path);
+    return info.isFile() && info.size > 0;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * WHICH kernel this deployment serves, asked rather than assumed.
+ *
+ * The obvious thing is to bake the hash into the tarball at publish time. It is
+ * also wrong: the hash changes whenever the geometry kernel is rebuilt, so a
+ * baked one would mean an npm republish per kernel change - which is the exact
+ * cost this whole design exists to avoid, reintroduced at the last step. The
+ * deployment knows what it is serving; this asks it.
+ */
+async function currentKernelId() {
+  const response = await fetch(`${ORIGIN}/api/health`);
+  if (!response.ok) {
+    throw new Error(`${ORIGIN}/api/health answered ${response.status}, so this cannot find out `
+      + 'which kernel to fetch. Set OBENOR_ORIGIN if the app is not the deployed one.');
+  }
+  const body = await response.json();
+  const id = body?.kernel;
+  if (typeof id !== 'string' || !/^[0-9a-f]{6,}$/u.test(id)) {
+    throw new Error('that origin does not report a kernel build, so it is either an older '
+      + 'deployment or not an Obenor3D one.');
+  }
+  return id;
+}
+
+/**
+ * One artefact, cached under the hash the deployment named.
+ *
+ * Downloaded to a temporary name and renamed into place, because a half-written
+ * wasm that looks complete is the worst outcome available here: emscripten does
+ * not validate it, `_malloc` resolves to some other function, and every
+ * operation afterwards dies with a bogus out-of-memory a long way from the
+ * cause. A rename is atomic on every filesystem this runs on.
+ */
+async function ensure(id, name) {
+  const dir = join(CACHE, id);
+  const path = join(dir, name);
+  if (await exists(path)) return path;
+
+  await mkdir(dir, { recursive: true });
+  const url = `${ORIGIN}/k/${id}/${name}`;
+  say(`fetching the kernel from ${url} (once - it is cached in ${dir})`);
+  const response = await fetch(url);
+  if (!response.ok || response.body === null) {
+    throw new Error(
+      `could not fetch the kernel: ${url} answered ${response.status}. `
+      + 'Set OBENOR_ORIGIN if the app is not the deployed one.');
+  }
+  const temp = `${path}.${process.pid}.part`;
+  try {
+    await pipeline(Readable.fromWeb(response.body), createWriteStream(temp));
+    await rename(temp, path);
+  } catch (error) {
+    await unlink(temp).catch(() => {});
+    throw error;
+  }
+  say(`kernel cached (${name})`);
+  return path;
+}
+
+/*
+ * Both builds, because which one loads is decided inside the kernel from
+ * whether this Node has SharedArrayBuffer and enough of a thread pool, and the
+ * decision happens after this point. Fetching only the one we predict would put
+ * a network round trip in the middle of `Kernel.load` on the day the prediction
+ * is wrong.
+ */
+let kernelId;
+try {
+  kernelId = await currentKernelId();
+} catch (error) {
+  say(error.message);
+  process.exit(1);
+}
+
+const wanted = ['obenor-kernel.wasm', 'obenor-kernel-mt.wasm'];
+const located = new Map();
+for (const name of wanted) {
+  try {
+    located.set(name, await ensure(kernelId, name));
+  } catch (error) {
+    /* One of the two is enough to start: a machine without threads never asks
+     * for the mt build, and a fetch that failed for it must not stop a session
+     * that was only ever going to use the other. */
+    say(`${name} unavailable: ${error.message}`);
+  }
+}
+if (located.size === 0) {
+  say('no kernel could be fetched, so there is nothing to build geometry with.');
+  process.exit(1);
+}
+
+/* Handed to `Kernel.load` through the environment, because the server module
+ * constructs its own kernel deep inside a worker and threading a parameter down
+ * to it would mean a signature change in four packages for one deployment
+ * concern. */
+process.env['OBENOR_KERNEL_DIR'] = dirname(located.values().next().value);
+
+await import('../bundle/server.mjs');