openscad-mcp-server 1.0.4 → 1.0.6

package/README.md

@@ -1,6 +1,7 @@
 # OpenSCAD MCP Server
 
 [![npm version](https://img.shields.io/npm/v/openscad-mcp-server.svg)](https://www.npmjs.com/package/openscad-mcp-server)
+[![npm downloads](https://img.shields.io/npm/dt/openscad-mcp-server.svg)](https://www.npmjs.com/package/openscad-mcp-server)
 [![CI](https://github.com/fboldo/openscad-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/fboldo/openscad-mcp-server/actions/workflows/ci.yml)
 
 An MCP (Model Context Protocol) server that renders **PNG previews** and **STL geometry** from OpenSCAD (SCAD) source code. It is designed to support **iterative, agent-driven CAD workflows**, where models can be previewed visually and exported for downstream use (e.g. fabrication, simulation, or inspection).
@@ -33,6 +34,16 @@ This MCP server is currently in beta. Performance, APIs, and capabilities may ch
   - Input: `scadCode` (string), optional `filename` (string)
   - Output: MCP embedded resource (STL)
 
+## Skill
+
+This repository also includes an [OpenSCAD iterative modeling skill](skills/openscad-iterative-modeling/SKILL.md) that demonstrates how to use this MCP server to support an iterative SCAD → PNG → critique → refine loop.
+
+## Limitations
+
+- **Performance**: Rendering complex SCAD models can be slow, especially in a WASM environment.
+- **Feature support**: Not all OpenSCAD features may be fully supported or may have limitations in the WASM version.
+- **Fonts**: Text rendering is not currently supported. Support is planned for a future release.
+
 ## Installation
 
 The published package is intended to run over stdio. Configure it in your MCP client using `npx`:
@@ -48,11 +59,29 @@ The published package is intended to run over stdio. Configure it in your MCP cl
 }
 ```
 
+To run it over HTTP instead (e.g. in Docker), pass `--http`:
+
+```bash
+MCP_PORT=3000 npx -y openscad-mcp-server --http
+```
+
+The server exposes `GET /health` and a stateless streamable HTTP MCP endpoint at `POST /mcp`.
+
+### Using the Skill
+
+[Agents skills](https://github.com/agentskills/agentskills) are a simple, open format for giving agents new capabilities and expertise.
+
+The most straightforward to use the OpenSCAD iterative modeling skill is to install it using the [skills CLI](https://github.com/vercel-labs/skills):
+
+```bash
+npx skills add fboldo/openscad-mcp-server --skill openscad-iterative-modeling
+```
+
 ## Local development
 
 - Install deps: `bun install`
 - Stdio (matches how clients run it): `bun index.ts --stdio`
-- HTTP (useful for manual testing): `bun index.ts`
+- HTTP (useful for manual testing): `bun index.ts` (or `--http`)
   - Port: `MCP_PORT` (default `3000`)
   - Endpoints: `GET /health`, MCP at `POST /mcp`
 - MCP Inspector: `bun run dev`
@@ -62,6 +91,9 @@ The published package is intended to run over stdio. Configure it in your MCP cl
 - [jhacksman/OpenSCAD-MCP-Server](https://github.com/jhacksman/OpenSCAD-MCP-Server)
   This project provides a different approach relying on generating images from user prompts, followed by 3D reconstruction and even 3D printer discovery. It's a very interesting project, and I recommend checking it out if you are interested in OpenSCAD and MCP servers.
 
+- [petrijr/openscad-mcp](https://github.com/petrijr/openscad-mcp)
+  Similar to this project, but it uses a Python-based server and relies on the OpenSCAD CLI for rendering.
+
 ## Relevant Links
 
 - [OpenSCAD](https://openscad.org/)

package/dist/index.mjs

@@ -58,24 +58,48 @@ const asTool = (fn) => {
 
 //#endregion
 //#region src/infra/openscad.ts
-const getOpenSCADInstance = async () => {
-	const writeStderr = (line) => {
-		try {
-			process.stderr.write(line.endsWith("\n") ? line : `${line}\n`);
-		} catch {
-			console.error(line);
+/**
+* Executes a callback function with an OpenSCAD instance, capturing any errors and outputs produced during the execution.
+*
+* @param callback - An async function that receives an OpenSCAD instance to perform operations
+* @returns A tuple containing the callback result (or error), an array of errors captured from OpenSCAD's stderr, and a set of outputs captured from OpenSCAD's stdout
+*/
+const executeOpenSCAD = async (callback) => {
+	const outputs = [];
+	const response = await callback(await createOpenSCAD({
+		noInitialRun: true,
+		printErr: (text) => {
+			outputs.push(text);
+		},
+		print: (text) => {
+			outputs.push(text);
 		}
-	};
-	return await createOpenSCAD({
-		print: (text) => writeStderr(`[OpenSCAD]: ${text}`),
-		printErr: (text) => writeStderr(`[OpenSCAD Error]: ${text}`)
+	})).catch((e) => {
+		return e;
 	});
+	if (response.constructor.name.includes("Error")) {
+		const errors = outputs.filter((o) => o.toLowerCase().includes("error:"));
+		const errorMessage = errors.length > 0 ? [response.message, ...errors].filter(Boolean).join("\n") : response.message;
+		throw new Error(errorMessage);
+	}
+	return response;
 };
 
 //#endregion
 //#region src/app/tools/export-scad-stl/tool.ts
 const exportScadStlTool = async ({ filename = "model.stl", scadCode }) => {
-	const stl = await (await getOpenSCADInstance()).renderToStl(scadCode);
+	const result = await executeOpenSCAD(async (instance) => {
+		const openscad = instance.getInstance();
+		openscad.FS.writeFile("input.scad", scadCode);
+		openscad.callMain([
+			"input.scad",
+			"-o",
+			"output.stl",
+			"--backend=manifold"
+		]);
+		return openscad.FS.readFile("output.stl");
+	});
+	if (!result) throw new Error("Failed to generate STL from OpenSCAD");
 	const assignedFilename = filename.endsWith(".stl") ? filename : `${filename}.stl`;
 	const defaultFilename = `model-${(/* @__PURE__ */ new Date()).getTime()}.stl`;
 	return {
@@ -83,7 +107,7 @@ const exportScadStlTool = async ({ filename = "model.stl", scadCode }) => {
 		resource: {
 			uri: `file://${assignedFilename ?? defaultFilename}`,
 			mimeType: "model/stl",
-			blob: Buffer.from(stl, "utf8").toString("base64")
+			blob: Buffer.from(result, "utf8").toString("base64")
 		}
 	};
 };
@@ -172,9 +196,21 @@ const resolveCameraPosition = (cameraPosition, cameraPreset) => {
 	return CAMERA_PRESETS[cameraPreset];
 };
 const renderScadPngTool = async ({ scadCode, width, height, cameraPreset, cameraPosition }) => {
+	const result = await executeOpenSCAD(async (instance) => {
+		const openscad = instance.getInstance();
+		openscad.FS.writeFile("input.scad", scadCode);
+		openscad.callMain([
+			"input.scad",
+			"-o",
+			"output.stl",
+			"--backend=manifold"
+		]);
+		return openscad.FS.readFile("output.stl");
+	});
+	if (!result) throw new Error("Failed to generate STL from OpenSCAD");
 	return {
 		type: "image",
-		data: await createPngBase64FromStl(await (await getOpenSCADInstance()).renderToStl(scadCode), width, height, resolveCameraPosition(cameraPosition, cameraPreset)),
+		data: await createPngBase64FromStl(result, width, height, resolveCameraPosition(cameraPosition, cameraPreset)),
 		mimeType: "image/png",
 		_meta: {
 			width,
@@ -208,20 +244,6 @@ const RenderScadPngToolInputSchema = z.object({
 	cameraPreset: RenderScadPngCameraPreset.optional().describe("A named camera preset used when `cameraPosition` is not provided"),
 	cameraPosition: RenderScadPngCamera.optional().describe("Camera position as { x,y,z }. Example: { x: 0, y: -25, z: 20 }")
 });
-const RenderScadPngToolOutputSchema = z.object({
-	image: ImageContentSchema,
-	metadata: z.object({
-		width: z.number(),
-		height: z.number(),
-		cameraPreset: RenderScadPngCameraPreset.optional(),
-		cameraPosition: RenderScadPngCamera.optional(),
-		timingsMs: z.object({
-			openscadToStl: z.number(),
-			stlToPng: z.number(),
-			total: z.number()
-		})
-	})
-});
 
 //#endregion
 //#region src/app/tools/render-scad-png/register.ts
@@ -251,8 +273,13 @@ function createServer() {
 
 //#endregion
 //#region src/entrypoints/http.ts
-const createHttpServer = async (createServer) => {
-	const transport = new WebStandardStreamableHTTPServerTransport();
+/**
+* Creates the Hono app serving the MCP endpoint in stateless mode.
+*
+* Stateless transports cannot be reused across requests, so a fresh server and
+* transport pair is created for every `/mcp` request and closed once it has responded.
+*/
+const createHttpApp = (createServer) => {
 	const app = new Hono();
 	app.use("*", cors({
 		origin: "*",
@@ -271,9 +298,24 @@ const createHttpServer = async (createServer) => {
 		exposeHeaders: ["mcp-session-id", "mcp-protocol-version"]
 	}));
 	app.get("/health", (c) => c.json({ status: "ok" }));
-	app.all("/mcp", (c) => transport.handleRequest(c.req.raw));
+	app.all("/mcp", async (c) => {
+		const transport = new WebStandardStreamableHTTPServerTransport({
+			sessionIdGenerator: void 0,
+			enableJsonResponse: true
+		});
+		const server = createServer();
+		try {
+			await server.connect(transport);
+			return await transport.handleRequest(c.req.raw);
+		} finally {
+			await server.close();
+		}
+	});
+	return app;
+};
+const createHttpServer = async (createServer) => {
+	const app = createHttpApp(createServer);
 	const PORT = process.env.MCP_PORT ? Number.parseInt(process.env.MCP_PORT, 10) : 3e3;
-	await createServer().connect(transport);
 	console.log(`Starting Hono MCP server on port ${PORT}`);
 	console.log(`Health check: http://localhost:${PORT}/health`);
 	console.log(`MCP endpoint: http://localhost:${PORT}/mcp`);
@@ -308,7 +350,16 @@ const bootstrap = (method, createServer) => {
 
 //#endregion
 //#region index.ts
-await bootstrap((process.argv.includes("--stdio"), "stdio"), createServer);
+/**
+* Explicit `--http` / `--stdio` flags win. Without a flag, the published build
+* (NODE_ENV=production) defaults to stdio and local development defaults to HTTP.
+*/
+const resolveBootstrapMethod = (argv) => {
+	if (argv.includes("--http")) return "http";
+	if (argv.includes("--stdio")) return "stdio";
+	return "stdio";
+};
+await bootstrap(resolveBootstrapMethod(process.argv), createServer);
 
 //#endregion
 export {  };

package/package.json

@@ -3,7 +3,7 @@
   "module": "./dist/index.mjs",
   "type": "module",
   "license": "MIT",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "mcpName": "io.github.fboldo/openscad-mcp-server",
   "description": "An MCP server that renders PNG previews and STL geometry from OpenSCAD (SCAD) source code.",
   "repository": {

package/server.json

@@ -8,13 +8,13 @@
     "url": "https://github.com/fboldo/openscad-mcp-server",
     "source": "github"
   },
-  "version": "1.0.4",
+  "version": "1.0.6",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "openscad-mcp-server",
-      "version": "1.0.4",
+      "version": "1.0.6",
       "transport": {
         "type": "stdio"
       }