openscad-mcp-server 0.8.0__tar.gz

openscad_mcp_server-0.8.0/.github/workflows/auto-tag.yml

@@ -0,0 +1,55 @@
+name: Auto Tag and Release
+
+on:
+  pull_request:
+    types: [closed]
+    branches: [main]
+
+jobs:
+  auto-tag:
+    if: github.event.pull_request.merged == true
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Read version from pyproject.toml
+        id: version
+        run: |
+          VERSION=$(python3 -c "
+          import re, pathlib
+          text = pathlib.Path('pyproject.toml').read_text()
+          match = re.search(r'^version\s*=\s*\"([^\"]+)\"', text, re.MULTILINE)
+          print(match.group(1))
+          ")
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "tag=v$VERSION" >> "$GITHUB_OUTPUT"
+
+      - name: Check if tag exists
+        id: check_tag
+        run: |
+          if git ls-remote --tags origin "refs/tags/${{ steps.version.outputs.tag }}" | grep -q .; then
+            echo "exists=true" >> "$GITHUB_OUTPUT"
+            echo "Tag ${{ steps.version.outputs.tag }} already exists, skipping."
+          else
+            echo "exists=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create tag and release
+        if: steps.check_tag.outputs.exists == 'false'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          git tag "${{ steps.version.outputs.tag }}"
+          git push origin "${{ steps.version.outputs.tag }}"
+
+      - name: Create GitHub release
+        if: steps.check_tag.outputs.exists == 'false'
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create "${{ steps.version.outputs.tag }}" \
+            --title "${{ steps.version.outputs.tag }}" \
+            --generate-notes

openscad_mcp_server-0.8.0/.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Verify version matches tag
+        run: |
+          TAG="${GITHUB_REF#refs/tags/v}"
+          VERSION=$(python3 -c "
+          import re, pathlib
+          text = pathlib.Path('pyproject.toml').read_text()
+          match = re.search(r'^version\s*=\s*\"([^\"]+)\"', text, re.MULTILINE)
+          print(match.group(1))
+          ")
+          if [ "$TAG" != "$VERSION" ]; then
+            echo "::error::Tag v$TAG does not match package version $VERSION"
+            exit 1
+          fi
+          echo "Version $VERSION matches tag."
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

openscad_mcp_server-0.8.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.pytest_cache/
+.hypothesis/

openscad_mcp_server-0.8.0/.kiro/specs/openscad-mcp-server/tasks.md

@@ -0,0 +1,188 @@
+# Implementation Plan: OpenSCAD MCP Server
+
+## Overview
+
+Incremental implementation of the OpenSCAD MCP server in Python, building from core data models and services up through tool handlers, resources, prompts, container images, packaging, and CI/CD. Each task builds on previous work so there is no orphaned code.
+
+NOTE: After completing each task, always create a feature branch, commit, push, merge to main, and push main. Never leave work unmerged.
+
+## Tasks
+
+- [x] 1. Project scaffolding and package configuration
+  - [x] 1.1 Create `pyproject.toml` with PEP 621 metadata, dependencies (`mcp`, `aiohttp`, `beautifulsoup4`), test extras (`pytest`, `pytest-asyncio`, `hypothesis`), console script entry point `openscad-mcp-server`, and build backend
+    - _Requirements: 13.1, 13.2, 13.4, 13.5_
+  - [x] 1.2 Create directory structure: `src/openscad_mcp_server/` with `__init__.py`, `__main__.py`, `tools/__init__.py`, `services/__init__.py`, `resources/__init__.py`, `prompts/__init__.py`, and `tests/__init__.py`
+    - _Requirements: 13.3_
+  - [x] 1.3 Implement `__main__.py` entry point that calls `main()` from `server.py`
+    - _Requirements: 13.3_
+
+- [x] 2. Data models and session state
+  - [x] 2.1 Create `src/openscad_mcp_server/models.py` with dataclasses: `ContainerResult`, `LibraryCatalogEntry`, `ModuleSignature`, `LibrarySource`, `CameraAngle`, `InspectionImage`, `FeedbackRecord`, `FeedbackIndexEntry`, and the `CAMERA_ANGLES` constant (8 predefined angles)
+    - _Requirements: 6.2, 7.2, 12.5_
+  - [x] 2.2 Create `src/openscad_mcp_server/services/session.py` with `SessionState` class: `reviewed_libraries` set, `latest_confidence_score`, `container_runtime`, `container_executable`, `working_dir`, and methods `mark_library_reviewed`, `is_library_reviewed`, `set_confidence`
+    - _Requirements: 17.6, 7.5_
+  - [x] 2.3 Write property test for session state (Property 25: Reviewed libraries tracking round trip)
+    - **Property 25: Reviewed libraries tracking round trip**
+    - **Validates: Requirements 17.6**
+  - [x] 2.4 Write property test for confidence score computation (Property 22: Overall confidence is minimum of per-angle scores)
+    - **Property 22: Overall confidence is minimum of per-angle scores**
+    - **Validates: Requirements 16.8**
+
+- [x] 3. Container manager service
+  - [x] 3.1 Create `src/openscad_mcp_server/services/container.py` with `ContainerManager` class: `__init__(runtime, executable)`, `detect()` static method probing Docker then Finch, `run(image, command, mounts, timeout)` executing container via `asyncio.create_subprocess_exec`, `image_exists(image)`, `build_image(dockerfile, tag)`
+    - _Requirements: 5.1, 5.2, 6.3, 8.3, 10.1_
+  - [x] 3.2 Write property test for container command generation (Property 3: Runtime-agnostic commands)
+    - **Property 3: Container command generation is runtime-agnostic**
+    - **Validates: Requirements 5.2, 6.3**
+  - [x] 3.3 Write property test for container mount correctness (Property 4: Container mount correctness)
+    - **Property 4: Container mount correctness**
+    - **Validates: Requirements 5.5, 9.6**
+  - [x] 3.4 Write property test for build error propagation (Property 5: Build error propagation)
+    - **Property 5: Build error propagation**
+    - **Validates: Requirements 5.4**
+  - [x] 3.5 Write property test for container start failure diagnostics (Property 6: Container start failure diagnostics)
+    - **Property 6: Container start failure diagnostics**
+    - **Validates: Requirements 5.6, 8.4**
+
+- [x] 4. File manager service
+  - [x] 4.1 Create `src/openscad_mcp_server/services/file_manager.py` with `FileManager` class: manages working area (`working/`), final output (`output/`), libraries (`libraries/`), feedback (`feedback/`) directories. Methods: `save_code(code, filename)` with `.scad` extension normalization, `save_stl(data, filename)`, `save_renders(images)`, `clear_renders()`, `finalize()` copying working area to output, `ensure_dirs()` for auto-creation
+    - _Requirements: 4.1, 4.3, 4.4, 11.1, 11.2, 11.3, 11.4, 11.5, 11.6_
+  - [x] 4.2 Write property test for save-code round trip (Property 1: Save-code round trip)
+    - **Property 1: Save-code round trip**
+    - **Validates: Requirements 4.1, 4.4**
+  - [x] 4.3 Write property test for filename extension normalization (Property 2: Filename extension normalization)
+    - **Property 2: Filename extension normalization**
+    - **Validates: Requirements 4.3**
+  - [x] 4.4 Write property test for working area overwrite invariant (Property 16: Working area overwrite invariant)
+    - **Property 16: Working area overwrite invariant**
+    - **Validates: Requirements 11.1, 11.2, 11.3, 11.4**
+  - [x] 4.5 Write property test for finalize copies all artifacts (Property 17: Finalize copies all working area artifacts)
+    - **Property 17: Finalize copies all working area artifacts**
+    - **Validates: Requirements 11.5**
+
+- [x] 5. Checkpoint - Core services
+  - Ensure all tests pass, ask the user if questions arise.
+
+- [x] 6. Library service
+  - [x] 6.1 Create `src/openscad_mcp_server/services/library_service.py` with `LibraryService` class: `browse_catalog(force_refresh)` fetching and parsing `openscad.org/libraries.html` with BeautifulSoup, `fetch_library(name, source_url, force_refresh)` cloning/downloading from source repo, `read_source(name)` reading `.scad` files and extracting module signatures. Includes session-level catalog cache and library cache with force-refresh support
+    - _Requirements: 9.1, 9.2, 9.3, 9.4, 9.5, 9.7, 9.8, 17.1, 17.4_
+  - [x] 6.2 Write property test for catalog parser (Property 11: Catalog parser extracts structured entries)
+    - **Property 11: Catalog parser extracts structured entries**
+    - **Validates: Requirements 9.1**
+  - [x] 6.3 Write property test for library cache hit (Property 12: Library cache hit avoids re-download)
+    - **Property 12: Library cache hit avoids re-download**
+    - **Validates: Requirements 9.5**
+  - [x] 6.4 Write property test for fetch success (Property 13: Fetch-library success returns valid path)
+    - **Property 13: Fetch-library success returns valid path**
+    - **Validates: Requirements 9.7**
+  - [x] 6.5 Write property test for fetch failure (Property 14: Fetch-library failure includes source URL)
+    - **Property 14: Fetch-library failure includes source URL**
+    - **Validates: Requirements 9.8**
+  - [x] 6.6 Write property test for read-library-source (Property 23: Read-library-source returns source and summary)
+    - **Property 23: Read-library-source returns source and summary**
+    - **Validates: Requirements 2.2, 2.4, 17.1, 17.4**
+
+- [x] 7. Feedback service
+  - [x] 7.1 Create `src/openscad_mcp_server/services/feedback_service.py` with `FeedbackService` class: `submit(critique, root_cause, working_area, confidence_score)` creating timestamped feedback record with artifact copies and index update, `list_records()` returning all feedback summaries. Feedback index stored as `feedback-index.json`
+    - _Requirements: 12.1, 12.2, 12.3, 12.4, 12.5, 12.6, 12.7, 12.8, 12.9, 12.10_
+  - [x] 7.2 Write property test for feedback record completeness (Property 18: Feedback record completeness)
+    - **Property 18: Feedback record completeness**
+    - **Validates: Requirements 12.2, 12.3, 12.4, 12.5, 12.8**
+  - [x] 7.3 Write property test for feedback index round trip (Property 19: Feedback index round trip)
+    - **Property 19: Feedback index round trip**
+    - **Validates: Requirements 12.6, 12.7, 12.10**
+  - [x] 7.4 Write property test for confidence disagreement flag (Property 20: Confidence disagreement flag logic)
+    - **Property 20: Confidence disagreement flag logic**
+    - **Validates: Requirements 12.9**
+
+- [x] 8. Checkpoint - All services complete
+  - Ensure all tests pass, ask the user if questions arise.
+
+- [x] 9. MCP tool handlers - init and save-code
+  - [x] 9.1 Create `src/openscad_mcp_server/tools/init_tool.py` with `init` tool: probes Docker then Finch via `ContainerManager.detect()`, runs test container, returns runtime info and persistence content for LLM memory
+    - _Requirements: 10.1, 10.5, 10.6_
+  - [x] 9.2 Write property test for init runtime detection (Property 15: Init tool runtime detection)
+    - **Property 15: Init tool runtime detection**
+    - **Validates: Requirements 10.1, 10.5**
+  - [x] 9.3 Create `src/openscad_mcp_server/tools/save_code.py` with `save-code` tool: validates filename, parses `include`/`use` statements, checks session for library review status, delegates to `FileManager.save_code()`. Rejects save if referenced libraries not reviewed
+    - _Requirements: 4.1, 4.2, 4.3, 4.4, 17.2, 17.3_
+  - [x] 9.4 Write property test for library review enforcement (Property 24: Library review enforcement on save)
+    - **Property 24: Library review enforcement on save**
+    - **Validates: Requirements 17.2, 17.3**
+
+- [x] 10. MCP tool handlers - build and render
+  - [x] 10.1 Create `src/openscad_mcp_server/tools/build_stl.py` with `build-stl` tool: launches build container via `ContainerManager.run()` with working directory and library mounts, runs `openscad -o output.stl <file>`, returns STL path or full error output
+    - _Requirements: 5.1, 5.2, 5.3, 5.4, 5.5, 5.6_
+  - [x] 10.2 Create `src/openscad_mcp_server/tools/render_images.py` with `render-images` tool: launches render container for each of 8 camera angles, generates 1024x1024 PNG images, reads PNGs from disk, returns list of MCP `TextContent` (camera metadata) and `ImageContent` blocks (base64 PNG). Handles partial failures by reporting failed angles
+    - _Requirements: 6.1, 6.2, 6.3, 6.4, 6.5, 6.6, 7.1, 7.2_
+  - [x] 10.3 Write property test for render produces 8 images (Property 7: Render produces exactly 8 images with correct angles)
+    - **Property 7: Render produces exactly 8 images with correct angles**
+    - **Validates: Requirements 6.1, 6.2, 6.4**
+  - [x] 10.4 Write property test for render command spec (Property 8: Render command specifies PNG at 1024x1024)
+    - **Property 8: Render command specifies PNG at 1024x1024**
+    - **Validates: Requirements 6.5**
+  - [x] 10.5 Write property test for partial render failure (Property 9: Partial render failure reports failed angles)
+    - **Property 9: Partial render failure reports failed angles**
+    - **Validates: Requirements 6.6**
+  - [x] 10.6 Write property test for MCP ImageContent blocks (Property 10: Render tool returns MCP ImageContent blocks)
+    - **Property 10: Render tool returns MCP ImageContent blocks**
+    - **Validates: Requirements 7.1, 7.2**
+
+- [ ] 11. MCP tool handlers - library and feedback tools
+  - [ ] 11.1 Create `src/openscad_mcp_server/tools/library_tools.py` with four tools: `browse-library-catalog` (delegates to `LibraryService.browse_catalog`), `fetch-library` (delegates to `LibraryService.fetch_library`), `read-library-source` (delegates to `LibraryService.read_source`, marks library reviewed in session), `list-reviewed-libraries` (reads from session state)
+    - _Requirements: 9.1, 9.2, 9.3, 9.4, 9.5, 9.6, 9.7, 9.8, 17.1, 17.4, 17.5, 17.6_
+  - [ ] 11.2 Create `src/openscad_mcp_server/tools/feedback_tools.py` with two tools: `submit-feedback` (delegates to `FeedbackService.submit`, records confidence score and disagreement flag), `list-feedback` (delegates to `FeedbackService.list_records`)
+    - _Requirements: 12.1, 12.2, 12.3, 12.4, 12.5, 12.6, 12.7, 12.8, 12.9, 12.10_
+  - [ ] 11.3 Create `src/openscad_mcp_server/tools/finalize.py` with `finalize` tool: delegates to `FileManager.finalize()`, returns final output directory path and file list
+    - _Requirements: 11.5, 11.6_
+
+- [ ] 12. Checkpoint - All tools implemented
+  - Ensure all tests pass, ask the user if questions arise.
+
+- [ ] 13. MCP resources
+  - [ ] 13.1 Create `src/openscad_mcp_server/resources/openscad_syntax.py` with `openscad://syntax-reference` resource: returns OpenSCAD language reference covering primitives, transformations, boolean operations, module definitions, variable scoping
+    - _Requirements: 2.1_
+  - [ ] 13.2 Create `src/openscad_mcp_server/resources/library_ref.py` with `openscad://library-reference/{library_name}` dynamic resource: generates reference from fetched library source including module signatures, parameter types/defaults, coordinate system conventions, usage examples
+    - _Requirements: 2.2, 2.3, 2.4_
+  - [ ] 13.3 Create `src/openscad_mcp_server/resources/pitfalls.py` with `openscad://pitfalls` resource: returns common pitfalls (manifold errors, z-fighting, boolean order, coordinate mismatches, missing `$fn`)
+    - _Requirements: 2.5_
+
+- [ ] 14. MCP workflow prompt
+  - [ ] 14.1 Create `src/openscad_mcp_server/prompts/workflow.py` with `openscad-workflow` prompt: full step-by-step instructions covering init/settings check, library discovery/fetch/review, code generation, build, render, systematic per-angle inspection with checklist, per-angle confidence scoring, overall confidence as min of per-angle scores, iteration on low confidence, finalize, and feedback handling. Includes prohibitions on skipping angles, declaring complete below 0.5 confidence, and guessing at library APIs
+    - _Requirements: 3.1, 3.2, 3.3, 3.4, 3.5, 3.6, 7.4, 7.5, 7.6, 7.7, 9.9, 10.2, 10.3, 10.4, 16.1, 16.2, 16.3, 16.4, 16.5, 16.6, 16.7, 16.8, 16.9, 17.5_
+
+- [ ] 15. MCP server wiring
+  - [ ] 15.1 Create `src/openscad_mcp_server/server.py`: instantiate `Server("openscad-mcp-server")`, create shared `SessionState`, register all 11 tools via `@app.tool()` decorators, register 3 resources via `@app.resource()`, register workflow prompt via `@app.prompt()`, implement `main()` async function running stdio transport
+    - _Requirements: 1.1, 1.2, 1.3_
+  - [ ] 15.2 Write unit tests for server initialization verifying tool/resource/prompt registration returns expected names
+    - _Requirements: 1.1, 1.2_
+
+- [ ] 16. Checkpoint - Server fully wired
+  - Ensure all tests pass, ask the user if questions arise.
+
+- [ ] 17. Container images
+  - [ ] 17.1 Create `Dockerfile.build` based on `ubuntu:24.04`, installing `openscad` package, with entrypoint `openscad`, working directory mount at `/work`, and `OPENSCADPATH` set to `/work/libraries`
+    - _Requirements: 8.1, 5.5, 9.6_
+  - [ ] 17.2 Create `Dockerfile.render` based on same base image, configured for OpenSCAD PNG export with `--camera` and `--imgsize` parameters
+    - _Requirements: 8.2_
+
+- [ ] 18. GitHub Actions CI/CD
+  - [ ] 18.1 Create `.github/workflows/auto-tag.yml`: triggers on PR merge to main, reads version from `pyproject.toml`, creates git tag `v{version}`, creates GitHub release with auto-generated notes. Skips if tag already exists. Uses `GITHUB_TOKEN`
+    - _Requirements: 15.1, 15.2, 15.3, 15.4, 15.5_
+  - [ ] 18.2 Create `.github/workflows/publish.yml`: triggers on `v*` tag push, builds Python package, publishes to PyPI using trusted publishing (OIDC). Verifies package version matches tag. Reports errors on build or publish failure
+    - _Requirements: 14.1, 14.2, 14.3, 14.4, 14.5_
+  - [ ] 18.3 Write property test for version-tag matching (Property 21: Version-tag matching)
+    - **Property 21: Version-tag matching**
+    - **Validates: Requirements 14.5**
+
+- [ ] 19. Final checkpoint - Full integration
+  - Ensure all tests pass, ask the user if questions arise.
+
+## Notes
+
+- All tasks are required — no optional tasks
+- Each task references specific requirements for traceability
+- Checkpoints ensure incremental validation
+- Property tests validate universal correctness properties from the design document (25 properties)
+- The design uses Python throughout — all code examples and tests use Python with Hypothesis for PBT
+- Container images may share a single base image since OpenSCAD handles both STL compilation and PNG export

openscad_mcp_server-0.8.0/Dockerfile.build

@@ -0,0 +1,11 @@
+FROM ubuntu:24.04
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends openscad xvfb \
+    && rm -rf /var/lib/apt/lists/*
+
+ENV OPENSCADPATH=/work/libraries
+
+WORKDIR /work
+
+ENTRYPOINT ["xvfb-run", "--auto-servernum", "openscad"]

openscad_mcp_server-0.8.0/Dockerfile.render

@@ -0,0 +1,13 @@
+FROM ubuntu:24.04
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends openscad xvfb \
+    && rm -rf /var/lib/apt/lists/*
+
+ENV OPENSCADPATH=/work/libraries
+
+WORKDIR /work
+
+# Render entrypoint: OpenSCAD with xvfb for headless PNG export.
+# Callers supply --camera, --imgsize, --export-format, -o, and input file.
+ENTRYPOINT ["xvfb-run", "--auto-servernum", "openscad"]

openscad_mcp_server-0.8.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Lenk
+
+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.

openscad_mcp_server-0.8.0/PKG-INFO

@@ -0,0 +1,219 @@
+Metadata-Version: 2.4
+Name: openscad-mcp-server
+Version: 0.8.0
+Summary: MCP server for OpenSCAD 3D model generation, compilation, and visual inspection
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: mcp>=1.0
+Provides-Extra: test
+Requires-Dist: hypothesis>=6.100; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# openscad-mcp-server
+
+An MCP server that gives LLMs the ability to design, build, and visually verify 3D models using [OpenSCAD](https://openscad.org) — all through natural conversation.
+
+The server handles the entire workflow: discovering and downloading OpenSCAD libraries on demand, saving code, compiling STL files in Docker/Finch containers, rendering 8-angle inspection images, and returning those images directly to the LLM's vision model as inline base64 PNGs. A built-in workflow prompt guides the LLM through systematic per-angle inspection with confidence scoring, so it catches defects before declaring a model complete.
+
+## Why this exists
+
+LLMs can write OpenSCAD code, but they can't run it, see the result, or iterate on mistakes. This server closes that loop. The LLM writes code, the server compiles and renders it in a container, and the LLM sees the rendered model from 8 angles — then decides whether to fix issues or finalize.
+
+Key design choices:
+- **Vision-native**: Rendered images come back as MCP `ImageContent` blocks, not file paths. The LLM sees the model directly.
+- **Zero config**: The `init` tool auto-detects Docker or Finch and persists settings via the LLM's memory mechanism. No env vars or config files needed.
+- **Library-aware**: Libraries are discovered from the [official OpenSCAD catalog](https://openscad.org/libraries.html) and downloaded on demand. The server enforces that the LLM reads library source code before using it — no guessing at APIs.
+- **Correctness-first**: The workflow prompt requires per-angle confidence scoring (overall = min of all angles) and forbids declaring a model complete below 0.5 confidence.
+
+## Quick start
+
+### Prerequisites
+
+- [Docker](https://docs.docker.com/get-docker/) or [Finch](https://runfinch.com/) installed and running
+- Python 3.11+ (for development) or [uv](https://docs.astral.sh/uv/) (for running directly)
+
+### Run with uvx (no install needed)
+
+```bash
+uvx openscad-mcp-server
+```
+
+### Or install and run
+
+```bash
+pip install openscad-mcp-server
+openscad-mcp-server
+```
+
+The server communicates over stdio, so it's meant to be launched by an MCP client (Claude Desktop, Kiro, etc.), not run interactively.
+
+### Build the container images
+
+The server needs two container images for compiling and rendering. Build them from the included Dockerfiles:
+
+```bash
+docker build -f Dockerfile.build -t openscad-build .
+docker build -f Dockerfile.render -t openscad-render .
+```
+
+Or with Finch:
+
+```bash
+finch build -f Dockerfile.build -t openscad-build .
+finch build -f Dockerfile.render -t openscad-render .
+```
+
+## MCP client configuration
+
+### Kiro
+
+Add to `.kiro/settings/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "openscad": {
+      "command": "uvx",
+      "args": ["openscad-mcp-server"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to your Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "openscad": {
+      "command": "uvx",
+      "args": ["openscad-mcp-server"]
+    }
+  }
+}
+```
+
+
+## Tools
+
+The server exposes 11 tools:
+
+| Tool | Description |
+|---|---|
+| `init` | Auto-detect Docker/Finch, configure working directory, return persistence content |
+| `save-code` | Save OpenSCAD code to the working area (enforces library review) |
+| `build-stl` | Compile `.scad` → `.stl` in a container |
+| `render-images` | Render STL from 8 camera angles, return inline base64 PNG images |
+| `browse-library-catalog` | Fetch the official OpenSCAD library listing |
+| `fetch-library` | Download a library from its source repository |
+| `read-library-source` | Read library `.scad` files and extract module signatures |
+| `list-reviewed-libraries` | Show which libraries have been reviewed this session |
+| `submit-feedback` | Record user feedback with artifact snapshots and confidence data |
+| `list-feedback` | List all feedback records for analysis |
+| `finalize` | Copy working area artifacts to the final output directory |
+
+## Resources
+
+| Resource | URI | Description |
+|---|---|---|
+| Syntax Reference | `openscad://syntax-reference` | OpenSCAD language reference (primitives, transforms, booleans, modules) |
+| Library Reference | `openscad://library-reference/{name}` | Dynamic reference generated from fetched library source |
+| Common Pitfalls | `openscad://pitfalls` | Manifold errors, z-fighting, boolean order, missing `$fn`, etc. |
+
+## Prompts
+
+| Prompt | Description |
+|---|---|
+| `openscad-workflow` | Full step-by-step workflow: init → library discovery → code → build → render → inspect → iterate → finalize |
+
+## How the workflow works
+
+```
+User: "Make me a phone stand with a 75° angle"
+  │
+  ▼
+┌─────────────────────────────────────────────┐
+│ 1. init          → detect Docker/Finch      │
+│ 2. browse-catalog → find relevant libraries │
+│ 3. fetch-library  → download BOSL2          │
+│ 4. read-source    → understand the API      │
+│ 5. save-code      → write OpenSCAD code     │
+│ 6. build-stl      → compile to STL          │
+│ 7. render-images  → 8 angles, inline PNGs   │
+│ 8. inspect        → per-angle confidence     │
+│ 9. iterate        → fix issues, re-render   │
+│ 10. finalize      → copy to output dir      │
+└─────────────────────────────────────────────┘
+  │
+  ▼
+Output: model.stl + model.scad + 8 inspection images
+```
+
+The LLM inspects each rendered angle individually, assigns per-angle confidence scores, and computes the overall confidence as the minimum across all angles. If any angle scores below 0.5, the LLM must iterate before finalizing.
+
+## Artifact layout
+
+```
+{working_dir}/
+├── working/          # Latest iteration (overwritten each cycle)
+│   ├── model.scad
+│   ├── model.stl
+│   └── renders/
+│       ├── front.png
+│       ├── back.png
+│       ├── left.png
+│       ├── right.png
+│       ├── top.png
+│       ├── bottom.png
+│       ├── front-right-top-iso.png
+│       └── back-left-top-iso.png
+├── output/           # Final output (populated on finalize)
+├── libraries/        # Downloaded OpenSCAD libraries
+└── feedback/         # User feedback records with artifact snapshots
+```
+
+## Development
+
+```bash
+# Clone and install with test dependencies
+git clone https://github.com/your-org/openscad-mcp-server.git
+cd openscad-mcp-server
+uv sync --extra test
+
+# Run tests
+uv run pytest tests/ -v
+
+# Run with Hypothesis verbose output
+uv run pytest tests/ -v --hypothesis-show-statistics
+```
+
+### Test suite
+
+The test suite includes 51 tests covering all 25 correctness properties from the design spec, validated with [Hypothesis](https://hypothesis.readthedocs.io/) property-based testing:
+
+- Save-code round trip and filename normalization
+- Container command generation (runtime-agnostic)
+- Mount correctness and error propagation
+- Render output (8 angles, PNG format, MCP ImageContent blocks)
+- Library catalog parsing, caching, and fetch error handling
+- Feedback record completeness, index round trip, confidence disagreement
+- Working area overwrite invariant and finalize correctness
+- Session state tracking and confidence score computation
+- Version-tag matching for release pipeline
+- Server registration (tools, resources, prompts)
+
+## CI/CD
+
+- **PR merge → main**: Automatically creates a git tag and GitHub release from the version in `pyproject.toml`
+- **Tag push (`v*`)**: Builds and publishes to PyPI using trusted publishing (OIDC)
+
+## License
+
+MIT