openscad-mcp 0.6.1__tar.gz

openscad_mcp-0.6.1/.claude-plugin/marketplace.json

@@ -0,0 +1,15 @@
+{
+  "name": "openscad-mcp",
+  "owner": {
+    "name": "Coop",
+    "url": "https://github.com/robertcoop"
+  },
+  "description": "OpenSCAD tooling for AI assistants: rendering, measurement, validation, and export, plus a design skill for 3D-printable parts.",
+  "plugins": [
+    {
+      "name": "openscad-mcp",
+      "source": "./",
+      "description": "OpenSCAD rendering, measurement, validation, and export as MCP tools, plus the openscad-design skill."
+    }
+  ]
+}

openscad_mcp-0.6.1/.claude-plugin/plugin.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
+  "name": "openscad-mcp",
+  "displayName": "OpenSCAD MCP",
+  "version": "0.6.1",
+  "description": "Render, measure, validate, and export OpenSCAD models from Claude Code, with a skill that teaches the measure-before-you-look design loop for 3D-printable parts.",
+  "author": {
+    "name": "Coop",
+    "url": "https://github.com/robertcoop"
+  },
+  "homepage": "https://github.com/robertcoop/openscad-mcp#readme",
+  "repository": "https://github.com/robertcoop/openscad-mcp",
+  "license": "MIT",
+  "keywords": [
+    "openscad",
+    "cad",
+    "3d-printing",
+    "mcp",
+    "rendering"
+  ],
+  "mcpServers": "./mcp-config.json"
+}

openscad_mcp-0.6.1/.gitignore

@@ -0,0 +1,199 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+# ...but src/openscad_mcp/parts/ is the purchased-parts catalog, not a build
+# artifact. It is package data that parts_catalog.py reads at runtime, so it
+# must be tracked and must ship in the wheel.
+!src/openscad_mcp/parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+.python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+test-env/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+.idea/
+
+# VS Code
+.vscode/
+*.code-workspace
+
+# macOS
+.DS_Store
+
+# Windows
+Thumbs.db
+ehthumbs.db
+
+# OpenSCAD specific
+*.scad.bak
+*.stl
+*.3mf
+*.amf
+*.dxf
+*.svg
+*.csg
+renders/
+temp/
+
+# Project specific
+/tmp/
+/temp/
+/cache/
+*.png
+*.jpg
+*.jpeg
+*.gif
+!docs/images/**
+test_output/
+# Claude Code / Impeccable local caches
+.impeccable/
+
+# Local research notes (not published)
+docs/research/

openscad_mcp-0.6.1/AGENTS.md

@@ -0,0 +1,56 @@
+# AGENTS.md
+
+Agent brief for the OpenSCAD MCP server. Claude Code should read the richer
+`skills/openscad-design/SKILL.md` instead.
+
+A Model Context Protocol server wrapping the OpenSCAD CLI: it renders `.scad` source
+to images, exports meshes, and returns exact geometric measurements. OpenSCAD must be
+installed on the host. Everything is in millimetres; OpenSCAD itself is unitless.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `render` | Images. `mode=views\|section\|parts\|compare`. `grounded=true` gives an orthographic render with a stated mm/px scale and drawn annotations. |
+| `measure` | Exact numbers from the exported mesh. `mode=model\|parts\|section\|mass\|probe\|features\|printability\|orientation\|anchors`: bounding box, volume, area, component count, watertightness, point-in-solid probes, holes read off the CSG tree. Also takes an existing STL via `mesh`. |
+| `check` | Relations between named parts of an assembly. `mode=interference\|clearance\|contact\|alignment\|motion\|rules`. Each part is exported separately, so identity survives; `mode=rules` runs a YAML check file and returns an exit code. |
+| `validate` | `mode=syntax\|geometry\|predicates\|includes\|printability`. Diagnostics parsed from stderr, never from the exit code. |
+| `scad_eval` | Evaluates expressions in the design's own parameter space, returning typed values. |
+| `reference` | Shipped engineering data: fits, fasteners, inserts, bearings, magnets, joints, parts, conventions, cheatsheet, dfm, materials. |
+| `export_model` | STL, 3MF, AMF, OFF, NEF3, DXF, SVG, PDF, CSG. `parts=` writes one named-object 3MF. |
+| `check_openscad` | Binary presence, version, capabilities. |
+| `get_libraries` | Libraries installed on this machine, with the exact import line for each. |
+| `get_project_files` | `.scad` files in a directory and their include/use dependency graph. `mode=trace` follows a constant's dependents. |
+| `clear_cache` | Drops the render cache. |
+| `model` | Workspace file CRUD: `action=create\|get\|update\|list\|delete`. `template="part:<id>"` writes a catalogued purchased part. |
+
+## The design loop
+
+1. State units, orientation, datum, and print process first. They are invisible in the source and wrong in half of all first attempts.
+2. Declare every meaningful dimension as a named variable at the top; derive the rest with expressions.
+3. Run `validate(mode="syntax")` before anything else. OpenSCAD exits 0 on failed asserts, unknown modules, and missing includes, so the exit code proves nothing.
+4. Run `measure` before trusting any picture. Numbers decide, pictures confirm; a vision model reads broken geometry as fine.
+5. Then `render(grounded=true)` with one to three views. More images make counting and comparison worse, not better.
+6. For assemblies: one module per part, overlap coplanar faces by an epsilon, and take clearances from `reference(topic="fits")` rather than memory. Never union the assembly.
+   Then hand the parts to `check` by name: `interference` and `clearance` for fit, `contact` for what should touch, `alignment` for a hole that is off by half a millimetre (interference and clearance both read zero there), `motion` for a sweep, `mass` for weight, centre-of-mass and inertia limits. Every row carries `quality.fn`; a distance inside the tessellation error bound comes back `UNRESOLVED`, so re-run at higher `$fn` rather than believing it. `measure(mode="features")` lists the holes a part cuts, and `reference(topic="parts")` plus `model(action="create", template="part:<id>")` gives you a sourced purchased part with named anchors and a clearance mask instead of guessed dimensions. Freeze the rules in a check file and re-run `check(mode="rules")` after every edit.
+7. Confirm `measure(mode="parts")` reports the component count you designed, and that `validate(mode="geometry")` returns `mesh_health.manifold == true`. A `null` there means the check did not run, not that it passed.
+8. Iterate by changing one variable and re-measuring. Use `scad_eval` to check derived expressions before spending a render.
+9. On every response read `errors`, then `warnings`, then `hints`, then the payload. Check `cached`: a cached result can predate an edit to an included file.
+10. `export_model` last, once the numbers and the manifold check pass.
+
+## Reading a render
+
+The text digest before the image carries the camera eye/center/up, the projection, the
+bounding box, and the scale in mm per pixel. That scale is valid only under
+orthographic projection, which is what `grounded=true` selects. Auto-framed
+(`--viewall`) renders fit the model to the frame, so absolute scale is unknown and a
+2 mm cube looks identical to a 500 mm one.
+
+## Gotchas
+
+Variables are compile-time and scope-final, so assigning inside an `if` or `for` does
+not change the outer value; use `x = cond ? a : b`. `difference()` subtracts every
+child after the first, so order changes the result. 2D and 3D geometry cannot be
+combined without extruding first. A global `$fn` applies to every curve and makes
+exports slow and huge. `import()` needs `convexity=10` or it renders with holes.
+Solids that touch exactly, and any zero-thickness wall, produce non-manifold output.

openscad_mcp-0.6.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 quellant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.