mcp-printable AGENTS.md

AGENTS.md

Cross-agent instructions for working with Printable — an MCP server for AI-driven 3D modeling, optimized for FDM-printable geometry.

This file is the entry point for any AI coding agent (Codex, Cursor, Goose, Sourcegraph Amp, JetBrains AI, etc.). Claude Code reads it too, plus the project-specific CLAUDE.md if present.

For human-facing setup and overview, see README.md.

What this project ships

• An MCP server (server.py) exposing 30 tools across two backends:
  • Blender (blender_*, 25 tools) — TCP to a bundled Blender addon. Requires Blender 3.6+ + addon enabled.
  • OpenSCAD (scad_*, 5 tools) — shells out to the openscad CLI. Requires OpenSCAD installed.
• Domain-knowledge MCP resources under printable://… URIs (5 of them).
• Always-on rules baked into the MCP server's instructions field — every connecting agent sees them automatically on initialize.

Required: image-capable model

Many tools (blender_render_*, blender_cross_section*, blender_get_screenshot, scad_render_views, scad_cross_section) return base64 PNGs that the model is expected to look at — that's how the design loop catches shape-level mistakes the geometry math doesn't. If you're a text-only model, you'll receive the images but be unable to interpret them; treat that as a hard limitation and tell the user up front rather than continuing without visual feedback.

Always-on rules

These are also embedded in the MCP instructions field, but if your agent doesn't surface that, here they are directly:

Blender

• Start every modeling task with blender_clear_scene — it auto-sets units to mm. Building at the default 1m scale produces zero-volume meshes that pass watertight checks but are useless.
• Use blender_boolean for boolean operations. Never use bpy.ops.object.join() (creates internal faces) or raw bpy boolean modifiers in execute_code (failures are silent).
• 1–3 operations per blender_execute_code, then blender_validate(checks=['HEALTH']) to verify (watertight? face count sane? connected_components == 1?).
• Renders show silhouettes only — use blender_cross_section_gallery to verify internal geometry truth.
• For any joint/hinge, you must call blender_check_clearance_sweep before export.
• Run blender_validate(checks=['ALL']) on every part before blender_export_stl.