openscad-wasm-mcp: Instructions file for Codex

AGENTS.md

Development notes for agents working on openscad-wasm-mcp.

Project Contract

This project is an OpenSCAD MCP server that runs OpenSCAD through openscad-wasm in Node.js. Do not add a native OpenSCAD binary dependency, do not automate the browser-based OpenSCAD UI, and do not expose arbitrary shell commands or raw OpenSCAD CLI args.

The server should remain runnable through Docker Compose with:

docker compose up --build

The default MCP transport is Streamable HTTP on /mcp, port 3333. Keep server creation separate from transport wiring so stdio can be added later.

Development Commands

npm install
npm run dev
npm test
npm run build
npm run lint

Use the mock backend for local development that should not depend on real WASM behavior:

OPENSCAD_BACKEND=mock npm run dev

Before handing off code changes, run at least:

npm test
npm run build

Run npm run lint when touching TypeScript, config, or formatting-sensitive files.

Runtime Configuration

Environment defaults are documented in .env.example:

• PORT=3333
• HOST=0.0.0.0
• WORKSPACE_DIR=/workspace
• ARTIFACT_DIR=/workspace/artifacts
• JOB_TMP_DIR=/tmp/openscad-jobs
• MAX_RENDER_MS=30000
• MAX_OUTPUT_MB=50
• MAX_INPUT_MB=10
• MAX_PARALLEL_JOBS=2
• CLEANUP_JOBS=true
• OPENSCAD_BACKEND=wasm|mock
• PUBLIC_BASE_URL=http://127.0.0.1:3333
• PREVIEW_TTL_SECONDS=3600
• PREVIEW_ENABLED=true
• MCP_AUTH_TOKEN (optional; when set, /mcp requires Authorization: Bearer <token>)

Docker Compose binds only 127.0.0.1:3333:3333 and uses a read-only root filesystem, /tmp tmpfs, cap_drop: ALL, and no-new-privileges.

Architecture Map

• src/index.ts: process entry point; loads config, creates dependencies, starts HTTP transport.
• src/config.ts: env parsing and runtime limits.
• src/server/createMcpServer.ts: MCP server construction and tool registration.
• src/server/transport.ts: Streamable HTTP wiring.
• src/tools/: zod schemas and MCP tool handlers.
• src/openscad/OpenScadRunner.ts: runner interface and shared runner result types.
• src/openscad/OpenScadWasmRunner.ts: real server-side openscad-wasm integration boundary.
• src/openscad/MockOpenScadRunner.ts: deterministic runner for tests and development.
• src/openscad/args.ts: allowlisted OpenSCAD CLI-compatible args builder.
• src/workspace/: job workspace, artifact storage, path safety, and workspace tools.
• src/security/: size limits, semaphore, and sanitization helpers.
• test/: vitest coverage for safety, formats, diagnostics, workspace, and mock tool flows.