openscad-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

OpenSCAD MCP Server — a Python MCP (Model Context Protocol) server built with FastMCP that exposes OpenSCAD 3D rendering capabilities to AI assistants. It wraps the OpenSCAD CLI, rendering SCAD code to PNG images and returning results as base64 or file paths.

External dependency: OpenSCAD must be installed on the system. The server auto-detects it via PATH or common install locations.

Build and Run Commands

# Install dependencies (uses uv, lockfile committed)
uv sync --dev

# Run the MCP server
uv run openscad-mcp
# or: uv run python -m openscad_mcp

# Run all tests with coverage
uv run pytest

# Run specific test markers
uv run pytest -m unit
uv run pytest -m performance
uv run pytest -m "not slow"

# Run a single test file
uv run pytest tests/test_openscad_mcp.py

# Run a single test
uv run pytest tests/test_openscad_mcp.py::TestParameterParsers::test_parse_camera_param_list

# Lint
uv run ruff check src/ tests/
uv run black --check src/ tests/

# Format
uv run black src/ tests/

# Type check
uv run mypy src/

Architecture

Core module: src/openscad_mcp/server.py

This file contains the FastMCP server instance, all MCP tools, helpers, and rendering logic:

• mcp = FastMCP("OpenSCAD MCP Server") — the server instance
• find_openscad() — locates the OpenSCAD binary on the system
• render_scad_to_png() — synchronous subprocess call to OpenSCAD with caching, security validation, include path support, and timeout enforcement
• Parameter parsers (parse_camera_param, parse_list_param, parse_dict_param, parse_image_size_param) — accept flexible input formats (JSON strings, lists, dicts, CSV) for AI assistant compatibility
• Response size management (manage_response_size) — auto-selects between base64, compressed, or file-path output based on size thresholds
• VIEW_PRESETS — predefined camera positions (front, back, top, isometric, etc.)
• QUALITY_PRESETS — draft/normal/high rendering quality via $fn/$fa/$fs variables
• Render caching (_compute_render_cache_key, _check_cache, _save_to_cache, _evict_cache_if_needed) — SHA-256 hash of all render parameters, TTL-based expiration, LRU eviction