fluidcad 0.0.33 → 0.0.35

package/README.md

@@ -115,6 +115,11 @@ Import and export STEP files with full color support. Bring in existing CAD mode
 
 FluidCAD ships official extensions for **VS Code** and **Neovim**, but works with any editor -- just point the CLI at your project.
 
+### LLM / AI Agent Integration (MCP)
+
+FluidCAD ships an [MCP](https://modelcontextprotocol.io) server so AI agents (Claude Code, Claude Desktop, Cursor, opencode, etc.) can drive a running workspace -- take screenshots, inspect geometry, edit `.fluid.js` files, and look up the API by symbol. See [Set Up the MCP Server](#3-optional-set-up-the-mcp-server) below.
+
+
 ---
 
 ## Tutorials
@@ -216,10 +221,10 @@ See the full list of commands in the [Neovim plugin README](extension/neovim/REA
 <details>
 <summary><strong>Any Other Editor</strong></summary>
 
-Run the FluidCAD server directly:
+From your project directory, run the FluidCAD server directly:
 
 ```bash
-npx fluidcad -w ./my-app
+npx fluidcad serve
 ```
 
 This starts a local server and opens a 3D viewport in your browser. Edit your `.fluid.js` files in any editor -- the viewport updates on save.
@@ -230,9 +235,74 @@ This starts a local server and opens a 3D viewport in your browser. Edit your `.
 |------|-------------|---------|
 | `-w, --workspace <path>` | Path to your project | Current directory |
 | `-p, --port <port>` | Server port | `3100` |
+| `--open` | Open the viewport in your default browser when ready | _off_ |
+
+</details>
+
+### 3. (Optional) Set Up the MCP Server
+
+FluidCAD bundles an [MCP](https://modelcontextprotocol.io) server so LLM agents can drive your workspace -- screenshots, geometry inspection, source edits, API lookup. It's included in the `fluidcad` package; no separate install needed.
+
+Wire it into your MCP client:
+
+<details>
+<summary><strong>Claude Code</strong></summary>
+
+Register at user scope so it's available in every project:
+
+```bash
+claude mcp add --scope user FluidCAD -- npx -y fluidcad mcp
+```
+
+</details>
+
+<details>
+<summary><strong>Claude Desktop / Cursor</strong></summary>
+
+Add to `claude_desktop_config.json` or `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "FluidCAD": {
+      "command": "npx",
+      "args": ["-y", "fluidcad", "mcp"]
+    }
+  }
+}
+```
 
 </details>
 
+<details>
+<summary><strong>opencode</strong></summary>
+
+Run `opencode mcp add` and answer the prompts, or add to `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "FluidCAD": {
+      "type": "local",
+      "command": ["npx", "-y", "fluidcad", "mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+</details>
+
+Then install the companion skill so agents follow the FluidCAD workflow:
+
+```bash
+npx skills add Fluid-CAD/FluidCAD
+```
+
+See the [MCP README](mcp/README.md) for the full tool surface, transport details, and local-testing guide.
+
+
 ---
 
 ## License

package/bin/commands/init.js

@@ -0,0 +1,55 @@
+import { writeFileSync, existsSync } from 'fs';
+import { resolve } from 'path';
+
+const INIT_JS = `import { init } from 'fluidcad'\n\nexport default await init()\n`;
+
+const TEST_FLUID_JS = `import { extrude, fillet, rect, shell, sketch } from "fluidcad/core";
+
+sketch("xy", () => {
+    rect(100, 50).radius(10).centered();
+});
+
+const e = extrude(30);
+
+fillet(4, e.startEdges());
+
+shell(-2, e.endFaces());
+`;
+
+const JSCONFIG = JSON.stringify({
+  compilerOptions: {
+    checkJs: true,
+    module: 'node20',
+  },
+}, null, 2) + '\n';
+
+function runInit() {
+  const cwd = process.cwd();
+
+  const initPath = resolve(cwd, 'init.js');
+  if (existsSync(initPath)) {
+    console.error('init.js already exists in this directory.');
+    process.exit(1);
+  }
+
+  writeFileSync(initPath, INIT_JS);
+
+  const testPath = resolve(cwd, 'test.fluid.js');
+  if (!existsSync(testPath)) {
+    writeFileSync(testPath, TEST_FLUID_JS);
+  }
+
+  const jsconfigPath = resolve(cwd, 'jsconfig.json');
+  if (!existsSync(jsconfigPath)) {
+    writeFileSync(jsconfigPath, JSCONFIG);
+  }
+
+  console.log('FluidCAD initialized.');
+}
+
+export function registerInitCommand(program) {
+  program
+    .command('init')
+    .description('Scaffold init.js, test.fluid.js, and jsconfig.json in the current directory')
+    .action(runInit);
+}

package/bin/commands/login.js

@@ -0,0 +1,120 @@
+import http from 'http';
+import { randomBytes, createHash } from 'crypto';
+import { getHubUrl, writeCredentials } from '../lib/config.js';
+import { HubClient } from '../lib/api-client.js';
+import { openBrowser } from '../lib/browser.js';
+
+const CLIENT_ID = 'fluidcad-cli';
+const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+
+function base64url(buf) {
+  return buf.toString('base64url');
+}
+
+/**
+ * Loopback + PKCE login (RFC 8252): spin up a one-shot 127.0.0.1 server, send
+ * the browser to the hub's /cli/authorize, receive the code on /callback,
+ * exchange it (with the PKCE verifier) for a token, and save it.
+ */
+function runLogin(opts) {
+  return new Promise((resolve, reject) => {
+    const hubUrl = getHubUrl(opts.hub);
+    const verifier = base64url(randomBytes(32));
+    const challenge = base64url(createHash('sha256').update(verifier).digest());
+    const state = base64url(randomBytes(16));
+    let redirectUri;
+    let settled = false;
+
+    const finish = (fn, arg) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timer);
+      server.close();
+      fn(arg);
+    };
+
+    const server = http.createServer((req, res) => {
+      const url = new URL(req.url, 'http://127.0.0.1');
+      if (url.pathname !== '/callback') {
+        res.writeHead(404);
+        res.end();
+        return;
+      }
+      res.writeHead(200, { 'content-type': 'text/html' });
+      res.end(
+        '<!doctype html><meta charset="utf-8"><body style="font-family:system-ui;text-align:center;padding-top:3rem">' +
+          '<h2>FluidCAD CLI</h2><p>You can close this tab and return to your terminal.</p>',
+      );
+      const error = url.searchParams.get('error');
+      const code = url.searchParams.get('code');
+      const returnedState = url.searchParams.get('state');
+
+      (async () => {
+        if (error) {
+          throw new Error(`authorization ${error}`);
+        }
+        if (returnedState !== state) {
+          throw new Error('state mismatch — aborting (possible CSRF)');
+        }
+        if (!code) {
+          throw new Error('no authorization code in callback');
+        }
+        const { status, body } = await new HubClient(hubUrl).postJson('/api/cli/token', {
+          client_id: CLIENT_ID,
+          code,
+          code_verifier: verifier,
+          redirect_uri: redirectUri,
+        });
+        if (status !== 200 || !body.access_token) {
+          throw new Error(`token exchange failed: ${body.error_description || body.error || `HTTP ${status}`}`);
+        }
+        writeCredentials({ token: body.access_token, email: body.user?.email ?? null, hubUrl });
+        return body.user?.email ?? null;
+      })().then(
+        (email) => finish(resolve, email),
+        (err) => finish(reject, err),
+      );
+    });
+
+    const timer = setTimeout(
+      () => finish(reject, new Error('login timed out — no response within 5 minutes')),
+      LOGIN_TIMEOUT_MS,
+    );
+
+    server.on('error', (err) => finish(reject, err));
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address();
+      redirectUri = `http://127.0.0.1:${port}/callback`;
+      const authorizeUrl =
+        `${hubUrl}/cli/authorize?` +
+        new URLSearchParams({
+          response_type: 'code',
+          client_id: CLIENT_ID,
+          redirect_uri: redirectUri,
+          code_challenge: challenge,
+          code_challenge_method: 'S256',
+          state,
+        });
+      console.log('Opening your browser to authorize the FluidCAD CLI…');
+      console.log(`\n  ${authorizeUrl}\n`);
+      openBrowser(authorizeUrl);
+    });
+  });
+}
+
+export function registerLoginCommand(program) {
+  program
+    .command('login')
+    .description('Authenticate this machine with the FluidCAD hub')
+    .option('--hub <url>', 'Hub base URL (default: $FLUIDCAD_HUB_URL or https://hub.fluidcad.io)')
+    .action((opts) => {
+      runLogin(opts)
+        .then((email) => console.log(`Logged in as ${email ?? 'your account'}`))
+        .catch((err) => {
+          console.error(err?.message ?? err);
+          process.exit(1);
+        });
+    });
+}

package/bin/commands/mcp.js

@@ -0,0 +1,33 @@
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const mcpEntry = resolve(__dirname, '..', '..', 'mcp', 'dist', 'server.js');
+
+async function runMcp() {
+  // stdout is reserved for the MCP protocol. Any incidental console.log from
+  // FluidCAD internals would corrupt the stream — route everything to stderr.
+  console.log = (...args) => console.error(...args);
+  console.info = (...args) => console.error(...args);
+
+  const mod = await import(mcpEntry);
+  if (typeof mod.runStdio !== 'function') {
+    console.error('mcp/dist/server.js does not export runStdio.');
+    process.exit(1);
+  }
+  await mod.runStdio();
+}
+
+export function registerMcpCommand(program) {
+  program
+    .command('mcp')
+    .description('Run the FluidCAD MCP server over stdio (for Claude Desktop, Claude Code, Cursor, ...)')
+    .action(async () => {
+      try {
+        await runMcp();
+      } catch (err) {
+        console.error(err?.stack || err?.message || String(err));
+        process.exit(1);
+      }
+    });
+}

package/bin/commands/pack.js

@@ -0,0 +1,49 @@
+import { writeFileSync } from 'fs';
+import { resolve, basename } from 'path';
+import { findEntry, readPackageVersion } from '../lib/workspace.js';
+
+async function runPack(opts) {
+  // The packer lives in server/ because esbuild + jszip belong at that layer;
+  // import it lazily so the rest of the CLI doesn't pay the cost.
+  const { packModel } = await import('../../server/dist/model-package/pack.js');
+
+  const workspace = resolve(opts.workspace ?? process.cwd());
+  const entry = findEntry(workspace, opts.entry);
+  const fluidcadVersion = readPackageVersion();
+
+  const { manifest, zip } = await packModel({
+    entryPath: entry,
+    workspacePath: workspace,
+    fluidcadVersion,
+    name: opts.name,
+    description: opts.description,
+  });
+
+  const outPath = opts.out
+    ? resolve(opts.out)
+    : resolve(workspace, basename(entry).replace(/\.fluid\.js$/i, '') + '.fluidpkg');
+  writeFileSync(outPath, zip);
+  const fileCount = manifest.files?.length ?? 0;
+  const assetCount = manifest.assets.length;
+  console.log(
+    `Wrote ${outPath} (${zip.length} bytes, ${fileCount} file${fileCount === 1 ? '' : 's'}, ` +
+      `${assetCount} asset${assetCount === 1 ? '' : 's'})`,
+  );
+}
+
+export function registerPackCommand(program) {
+  program
+    .command('pack')
+    .description('Package a .fluid.js model into a shareable .fluidpkg archive')
+    .option('-w, --workspace <path>', 'Workspace directory (defaults to cwd)')
+    .option('-e, --entry <file>', 'Entry .fluid.js file (auto-detected if only one exists)')
+    .option('-o, --out <path>', 'Output path (defaults to <entry-basename>.fluidpkg in the workspace)')
+    .option('-n, --name <name>', 'Package name (defaults to the entry file basename)')
+    .option('-d, --description <text>', 'Optional human description')
+    .action((opts) => {
+      runPack(opts).catch((err) => {
+        console.error(err?.message ?? err);
+        process.exit(1);
+      });
+    });
+}

package/bin/commands/publish.js

@@ -0,0 +1,136 @@
+import { resolve } from 'path';
+import { getHubUrl, readCredentials } from '../lib/config.js';
+import { HubClient } from '../lib/api-client.js';
+import { findEntry, readPackageVersion, readWorkspacePackage } from '../lib/workspace.js';
+import { readModelId, writeModelId } from '../lib/model-config.js';
+import { openBrowser } from '../lib/browser.js';
+
+async function runPublish(opts) {
+  const creds = readCredentials();
+  if (!creds) {
+    throw new Error('Not logged in. Run `fluidcad login` first.');
+  }
+  const hubUrl = getHubUrl(opts.hub || creds.hubUrl);
+
+  const workspace = resolve(opts.workspace ?? process.cwd());
+  const entry = findEntry(workspace, opts.entry);
+
+  // Prefills from the model's own package.json + the stable identity from
+  // fluidcad.json (null on the first publish → the hub mints one).
+  const pkg = readWorkspacePackage(workspace);
+  const name = opts.name ?? pkg.name;
+  const description = opts.description ?? pkg.description;
+  const modelId = readModelId(workspace);
+
+  // Render once to capture the full param schema for the manifest. This also
+  // acts as a build gate — a compile/runtime error fails the publish here,
+  // before anything is uploaded.
+  //
+  // Dynamic import is deliberate (and necessary): this pulls in the whole
+  // engine — Vite + OC wasm, ~40MB / ~110ms. bin/fluidcad.js eagerly loads
+  // every command module at startup, so a top-level import here would make
+  // `init`, `serve`, `login`, `--help` etc. pay that cost too. Loading it only
+  // when `publish` actually runs is the justified exception to "no inline
+  // imports".
+  console.log('Building model…');
+  const { captureParamDefinitions } = await import(
+    '../../server/dist/model-package/capture-params.js'
+  );
+  let paramDefinitions;
+  try {
+    paramDefinitions = await captureParamDefinitions(entry, workspace);
+  } catch (err) {
+    throw new Error(`Model failed to build — fix the error and retry:\n${err?.message ?? err}`);
+  }
+
+  // Pack the whole workspace (Pack v2), embedding the captured params. Lazy
+  // import for the same reason (keeps esbuild/jszip off the startup path of
+  // non-publish commands), consistent with how `pack` loads it.
+  const { packModel } = await import('../../server/dist/model-package/pack.js');
+  const { manifest, zip } = await packModel({
+    entryPath: entry,
+    workspacePath: workspace,
+    fluidcadVersion: readPackageVersion(),
+    name,
+    description,
+    paramDefinitions,
+  });
+
+  // Show exactly what's going up so stray files/secrets get caught before they
+  // leave the machine (the .gitignore guard plus an always-exclude list).
+  const files = manifest.files ?? [];
+  console.log(`\nUploading ${files.length} file${files.length === 1 ? '' : 's'} (${(zip.length / 1024).toFixed(1)} KB):`);
+  for (const f of files) {
+    console.log(`  ${f}`);
+  }
+
+  const form = new FormData();
+  form.append('fluidpkg', new Blob([zip], { type: 'application/zip' }), 'model.fluidpkg');
+  if (modelId) {
+    form.append('modelId', modelId);
+  }
+  if (name) {
+    form.append('name', name);
+  }
+  if (opts.visibility) {
+    form.append('visibility', opts.visibility);
+  }
+
+  const { status, body } = await new HubClient(hubUrl, creds.token).postForm('/api/publish', form);
+  if (status === 401) {
+    throw new Error('Your session has expired. Run `fluidcad login` again.');
+  }
+  if (status === 403) {
+    throw new Error(body.error || 'That model belongs to another account.');
+  }
+  if (status === 422) {
+    throw new Error(body.error || 'That FluidCAD version is not hosted yet.');
+  }
+  if (status !== 200 && status !== 201) {
+    throw new Error(body.error || `Publish failed (HTTP ${status})`);
+  }
+
+  // First publish for this workspace → persist the hub-minted id so the next
+  // publish lands as a new version of the same model.
+  if (!modelId && body.modelId) {
+    writeModelId(workspace, body.modelId);
+  }
+
+  console.log('');
+  if (body.isNewVersion) {
+    console.log(`A new version (v${body.version}) will be published — add details in your browser.`);
+  } else {
+    console.log('Created model — finish setup in your browser.');
+  }
+
+  if (body.formUrl) {
+    const formUrl = body.formUrl.startsWith('http') ? body.formUrl : hubUrl + body.formUrl;
+    console.log(`\n  ${formUrl}\n`);
+    await openBrowser(formUrl);
+  } else if (body.shareUrl) {
+    // Fallback for a pre-v2 hub that deployed synchronously and has no form.
+    console.log(`\n  ${body.shareUrl}\n`);
+  }
+}
+
+export function registerPublishCommand(program) {
+  program
+    .command('publish')
+    .description('Pack the current model and publish it to the FluidCAD hub')
+    .option('-w, --workspace <path>', 'Workspace directory (defaults to cwd)')
+    .option('-e, --entry <file>', 'Entry .fluid.js file (auto-detected if only one exists)')
+    .option('-n, --name <name>', 'Model name (defaults to the package name)')
+    .option('-d, --description <text>', 'Optional human description')
+    .option('--visibility <visibility>', 'public | unlisted | private (default: unlisted)')
+    .option('--hub <url>', 'Hub base URL (default: the hub you logged into)')
+    .action((opts) => {
+      runPublish(opts)
+        // The render spins up engine + Vite handles; exit explicitly so a
+        // successful publish doesn't hang waiting for the loop to drain.
+        .then(() => process.exit(0))
+        .catch((err) => {
+          console.error(err?.message ?? err);
+          process.exit(1);
+        });
+    });
+}

package/bin/commands/serve.js

@@ -0,0 +1,77 @@
+import { fork } from 'child_process';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import open from 'open';
+import { createFileWatcher, findFluidFiles } from '../watcher.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const serverEntry = resolve(__dirname, '..', '..', 'server', 'dist', 'index.js');
+
+function runServe(opts) {
+  const workspacePath = resolve(opts.workspace);
+  const port = String(opts.port);
+
+  const server = fork(serverEntry, [], {
+    env: {
+      ...process.env,
+      FLUIDCAD_SERVER_PORT: port,
+      FLUIDCAD_WORKSPACE_PATH: workspacePath,
+    },
+    stdio: ['pipe', 'pipe', 'pipe', 'ipc'],
+  });
+
+  server.stdout.on('data', (data) => { process.stdout.write(data); });
+  server.stderr.on('data', (data) => { process.stderr.write(data); });
+
+  let watcher;
+
+  server.on('message', (msg) => {
+    if (msg.type === 'ready') {
+      console.log(`FluidCAD server ready at ${msg.url}`);
+      if (opts.open) {
+        open(msg.url).catch((err) => {
+          console.error(`Failed to open browser: ${err.message}`);
+        });
+      }
+    }
+    if (msg.type === 'init-complete') {
+      if (msg.success) {
+        console.log('FluidCAD initialized successfully.');
+        watcher = createFileWatcher(workspacePath, server);
+
+        const files = findFluidFiles(workspacePath);
+        if (files.length > 0) {
+          server.send({ type: 'process-file', filePath: files[0] });
+        }
+      } else {
+        console.error(`FluidCAD initialization failed: ${msg.error}`);
+        process.exit(1);
+      }
+    }
+  });
+
+  server.on('exit', (code) => {
+    if (watcher) { watcher.close(); }
+    process.exit(code || 0);
+  });
+
+  process.on('SIGINT', () => {
+    if (watcher) { watcher.close(); }
+    server.kill('SIGINT');
+  });
+
+  process.on('SIGTERM', () => {
+    if (watcher) { watcher.close(); }
+    server.kill('SIGTERM');
+  });
+}
+
+export function registerServeCommand(program) {
+  program
+    .command('serve')
+    .description('Start the FluidCAD server and watch .fluid.js files')
+    .option('-w, --workspace <path>', 'workspace directory', process.cwd())
+    .option('-p, --port <port>', 'server port', '3100')
+    .option('--open', 'open the UI in the default browser when ready', false)
+    .action(runServe);
+}