Silhouette Studio MCP Server (v1.1.0)

A production-hardened Model Context Protocol (MCP) server (stdio) for programmatically creating, validating, nesting, previewing, and exporting vector cut designs in millimetres (mm) for Silhouette Studio (including Standard/Basic Edition, which opens DXF files natively but does not import SVG natively).

Because Silhouette Studio exposes no public live API, this server models designs as persistent .design.json scenes, converts vector geometry, external SVGs, TrueType/OpenType text, offsets, registration marks, nested layouts, and parametric box dielines into clean DXF (R2000/R12), SVG, and PNG preview files, and opens them directly in Silhouette Studio.

Key Features

• 28 MCP Tools covering canvas presets, geometric primitives, TrueType/OpenType text vectorization (fontTools + built-in geometric vector fallback), hardened contour offsetting (round / miter / bevel), deterministic 2D sheet nesting (silhouette_nest_shapes via MaxRects), grid duplication, transforms with flip_x / flip_y, hardened SVG path import, Print & Cut registration marks, parametric packaging templates, PNG visual proofs, DXF/SVG export, and Silhouette Studio launch.

• Layer & Line-Color Workflow: Built-in layer mapping (CUT, SCORE/FOLD, PERF, ENGRAVE, REGMARK) using AutoCAD Color Index (ACI) values for DXF and matching hex strokes for SVG/PNG so Silhouette Studio's Cut by Line Color panel separates cut lines from creases and perforations automatically.

• Inter-Process Concurrency & Crash Recovery: Protected by _InterProcessLock (combining re-entrant threading.RLock with OS-level locking on .silhouette.lock via msvcrt.locking on Windows and fcntl.flock on POSIX), os.fsync atomic temp-file writes, monotonically incremented revision tracking, and automatic recovery from .design.json.bak on corrupted primary files.

• Security & Hard Limits: Rejects bool-as-int coercion, NaN/inf, extreme coordinates (abs <= 100000 mm), oversized canvases (10..5000 mm), oversized text (<= 500 chars), self-intersecting closed contours, XML DTD/<!ENTITY/<script/external URI payloads in SVG (10 MB, 10000 elements, depth 64, 100000 points, defusedxml when available), and atomically enforces MAX_SHAPES = 5000 across all batch tools.

• MCP v2 Error Reporting, Annotations & STDIO Hygiene: Dual-inheritance exceptions (SilhouetteValueError, SilhouetteRuntimeError) preserve full diagnostic messages in MCP v2 is_error=True tool responses while remaining standard ValueError/RuntimeError subclasses for Python callers. Operational logs route exclusively to sys.stderr so JSON-RPC stdout is never corrupted.

• Clean Silhouette-Ready DXF: Sets $INSUNITS/$EXTMIN/$EXTMAX headers, avoids duplicate closing vertices on closed polylines (LWPOLYLINE), and flattens curves within a 0.05 mm chord tolerance (CHORD_TOL_MM).

Related MCP server: SmartCut

Requirements

• Python: >= 3.10

• Dependencies (pyproject.toml):

  • mcp>=1.3.0

  • ezdxf>=1.4.0

  • svgelements>=1.9.0

  • fonttools>=4.40.0

  • Pillow>=10.0.0

• Dev Dependencies:

  • pytest>=8.0.0

  • pytest-cov>=5.0.0

Installation

git clone https://github.com/WarlemJung/Silhouette-Studio-MCP-Server.git
cd Silhouette-Studio-MCP-Server
pip install -e ".[dev]"

For runtime-only installation:

pip install -e .

MCP Client Configuration

Add the server to your MCP host configuration (stdio transport):

{
  "mcpServers": {
    "silhouette-studio": {
      "command": "python",
      "args": ["/absolute/path/to/silhouette_studio_mcp/src/silhouette_mcp/server.py"]
    }
  }
}

If installed as a package (pip install -e .), you can also launch the console script entry point:

{
  "mcpServers": {
    "silhouette-studio": {
      "command": "silhouette-studio-mcp"
    }
  }
}

Optional Environment Variables

Coordinate System, Layers & Presets

Coordinate System & Operational Limits

• Units: Millimetres (mm)

• Origin: Top-left (0, 0) of the page/mat

• Axes: +X grows right, +Y grows down

• Rotation: Degrees, clockwise

• Safety Limits: Warns on details smaller than MIN_FEATURE_MM = 2.0 mm or shapes extending outside cut_margin_mm; enforces MIN_PAGE_MM = 10.0 mm, MAX_PAGE_MM = 5000.0 mm, MAX_COORD_MM = 100000.0 mm, MAX_TEXT_LENGTH = 500, MAX_ARC_SEGMENTS = 512, MAX_POINTS_PER_SHAPE = 20000, MAX_SVG_BYTES = 10 MB, MAX_SVG_ELEMENTS = 10000, MAX_SVG_DEPTH = 64, MAX_SVG_TOTAL_POINTS = 100000, and atomic pre-checked MAX_SHAPES = 5000 per design.

Supported Layers

Page / Mat Presets

MCP Tools Reference (28 Tools)

1. Design Lifecycle (6 tools)

2. Vector Primitives (7 tools)

3. Typography, Registration Marks & Parametric Templates (3 tools)

4. Editing, Offsetting, Nesting, Duplication & SVG Import (7 tools)

5. Inspection, Export, Calibration & Launch (5 tools)

Documentation

• docs/architecture.md — Layered server -> tools -> services -> {core, persistence, exporters, integrations} architecture, dependency matrix, and STDIO transport isolation.

• docs/geometry.md — Y-down/CAD Y-up coordinate mapping, polygon validation, self-intersection detection, and hardened contour offsetting.

• docs/nesting.md — Modular core/nesting/ 2D MaxRects (BSSF + BAF) packing domain, collision/clearance validation, and REGMARK preservation.

• docs/security.md — SVG/XXE protections, numeric/capacity bounds, atomic batch enforcement, and desktop subprocess security.

• docs/testing.md — Layered automated test suite (unit/, integration/, regression/, performance/), real STDIO end-to-end integration, and benchmarks.

• CHANGELOG.md — Release history (0.2.0 -> 1.0.0 -> 1.1.0).

Silhouette Studio DXF Calibration

1. Run silhouette_make_calibration_file() to generate calibration-100mm.dxf.

2. Open the file in Silhouette Studio (silhouette_open_in_studio("calibration-100mm.dxf")).

3. Verify the imported square measures 100.0 mm × 100.0 mm.

4. If the dimensions differ, configure Silhouette Studio Preferences -> Import -> DXF -> Open As Is (Centered or As-Is, 1:1 / mm units) instead of Fit to Page.

Note on Homologation: silhouette_open_in_studio verifies OS process launch (process_launched: true) and returns homologated_import: false because visual DXF verification inside the desktop GUI and physical blade cuts require manual inspection.

Examples

• examples/create_sample_design.py: Builds a rounded tag with a keyhole perforation, exports DXF + SVG, and opens it in Silhouette Studio.

• examples/generate_caixa_milk.py: Standalone script demonstrating programmatic packaging generation with CUT, SCORE, and ENGRAVE layers.

Package Architecture

The project follows a clean layered src/ + categorized tests/ layout configured in pyproject.toml (silhouette-studio-mcp = "silhouette_mcp.server:main"), organizing responsibilities under src/silhouette_mcp/ and tests into unit/{core,services,tools,exporters,persistence}/, integration/{mcp,persistence,studio}/, regression/, performance/, and fixtures/:

• src/silhouette_mcp/config/settings.py: Presets, layer palettes, limits, _DynamicStderrHandler, and monkeypatch-transparent runtime resolution (get_runtime_attr()).

• src/silhouette_mcp/core/ & core/nesting/: Exceptions & MCP v1/v2 shims (exceptions.py), validators (validators.py), shape models (models.py), 2D geometry/offset engine (geometry_engine.py), and pure 2D nesting domain (nesting/{models,collision,maxrects,metrics}.py).

• src/silhouette_mcp/persistence/: Cross-process .silhouette.lock (_InterProcessLock) & atomic writes (storage.py) plus .design.json.bak crash recovery (repository.py).

• src/silhouette_mcp/exporters/ & integrations/: DXF, SVG, and PNG exporters plus Windows/OS Silhouette Studio launcher (silhouette_studio.py).

• src/silhouette_mcp/services/: Use-case orchestration layer (document_service, geometry_service, nesting_service, export_service, import_service, template_service) decoupled from MCP transport.

• src/silhouette_mcp/tools/ & server.py: 28 thin MCP adapter tools registered centrally via TOOL_REGISTRATIONS (self-bootstrapping STDIO entrypoint).

See docs/architecture.md for the full layered diagram and dependency matrix.

Testing, Benchmarks & Verification

Run the automated test suite with coverage reporting:

python -m pytest -v -p no:cacheprovider --cov=silhouette_mcp --cov-report=term-missing

All tests automatically isolate SILHOUETTE_OUTPUT_DIR to a temporary directory via tests/conftest.py and mock OS GUI launches. Latest verified status: 94 passed, 0 failed, 0 skipped, 96% line coverage (2224 statements across src/silhouette_mcp/), covering:

• Strict AST architectural dependency boundaries across core/, services/, and tools/

• Pure core/nesting/ unit validation + deterministic MaxRects 2D nesting invariants (tests/unit/core/test_nesting.py)

• Direct services/ orchestration tests + 4-process parallel concurrency (subprocess.Popen + _InterProcessLock) and .design.json.bak crash recovery

• Hardened convex, concave, self-intersecting, and inradius-exceeded contour offsets + seeded property invariants

• Atomic MAX_SHAPES = 5000 batch guards and SVG XXE/<script>/depth/element/URI protections

• Unmocked real MCP STDIO JSON-RPC client-server end-to-end execution (list_tools, new_design, add_rectangle, add_text, nest_shapes, export dxf/svg/png, delete_design)

• Automated performance sanity checks in tests/performance/test_benchmarks.py (with full 100 to 5,000 shape scale tables published in docs/testing.md)