{"openapi": "3.1.0", "info": {"title": "PrintPal 3D Printing API (MCP tools over REST)", "version": "1.0.0", "description": "PrintPal (printpal.io) is a 3D printing platform: a community library of printable 3D models, free 3D-printing tools and calculators, AI text/image-to-3D generation, an AI CAD agent for parametric OpenSCAD parts, Arduino + 3D-printing build guides, video tutorials, Academy courses and a troubleshooting wiki. Use `search` for any 3D-printing question and `fetch` to read a result in full. Prefer `search_3d_models` when the user wants something to print, `find_3d_printing_tool` for calculators/generators, the `calculate_*` tools for instant numbers, `search_build_guides` for projects, and `search_learning_resources` for how-to content. `generate_3d_model` and `design_parametric_cad` return a PrintPal link with the user's prompt prefilled (or run for real when an API key header is present). Always surface the returned PrintPal URL so the user can open it; cite wiki/docs pages by URL when answering troubleshooting questions.", "termsOfService": "https://printpal.io/terms", "contact": {"name": "PrintPal", "url": "https://printpal.io/contact-us"}, "x-privacy-policy": "https://printpal.io/privacy"}, "servers": [{"url": "https://printpal.io"}], "components": {"securitySchemes": {"ApiKeyAuth": {"type": "apiKey", "in": "header", "name": "X-API-Key", "description": "Optional PrintPal API key; needed only for AI generation tools."}}}, "security": [{}, {"ApiKeyAuth": []}], "paths": {"/mcp/rest/search": {"post": {"operationId": "search", "summary": "Search PrintPal", "description": "Search everything on PrintPal for a 3D-printing query: community 3D models, free tools and calculators, wiki troubleshooting articles, OpenSCAD/AI-CAD docs, video tutorials, build guides and Academy courses. Returns ids accepted by `fetch` for the full content. Suited to general 3D printing questions such as \"why is my first layer not sticking\", \"PETG temperature\" or \"3D printed phone stand\".", "x-openai-isConsequential": false, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"query": {"type": "string", "description": "Natural-language search query."}}, "additionalProperties": false, "required": ["query"]}}}}, "responses": {"200": {"description": "Tool result", "content": {"application/json": {"schema": {"type": "object", "properties": {"results": {"type": "array", "items": {"type": "object", "properties": {"id": {"type": "string"}, "title": {"type": "string"}, "url": {"type": "string"}, "type": {"type": "string"}, "snippet": {"type": "string"}}, "required": ["id", "title", "url"]}}}, "required": ["results"]}}}}, "400": {"description": "Invalid input or tool-reported error", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}}}}}}}}, "/mcp/rest/fetch": {"post": {"operationId": "fetch", "summary": "Fetch a PrintPal item", "description": "Fetch the full content of a PrintPal item returned by `search` (or any id of the form `model:<uid>`, `tool:<slug>`, `wiki:<slug>`, `doc:<slug>`, `resource:<slug>`, `project:<slug>`, `course:<slug>`). Returns the complete text (article body, transcript, build steps, BOM, model description and files) plus the canonical URL for citation.", "x-openai-isConsequential": false, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"id": {"type": "string", "description": "Item id from `search`, e.g. \"wiki:stringing-and-oozing\"."}}, "additionalProperties": false, "required": ["id"]}}}}, "responses": {"200": {"description": "Tool result", "content": {"application/json": {"schema": {"type": "object", "properties": {"id": {"type": "string"}, "title": {"type": "string"}, "text": {"type": "string"}, "url": {"type": "string"}, "metadata": {"type": "object"}}, "required": ["id", "title", "text", "url"]}}}}, "400": {"description": "Invalid input or tool-reported error", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}}}}}}}}, "/mcp/rest/search_3d_models": {"post": {"operationId": "search3dModels", "summary": "Search 3D models to print", "description": "Find printable 3D models (STL/3MF/OBJ) in the PrintPal community library by keyword — e.g. \"articulated dragon\", \"headphone stand\", \"Raspberry Pi 5 case\". Returns cards with thumbnail, author, tags, likes and a link to the model page where the files can be downloaded. Searches existing uploads only; new models are made by `generate_3d_model` (AI mesh) or `design_parametric_cad` (exact dimensions).", "x-openai-isConsequential": false, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"query": {"type": "string", "description": "What the user wants to print, 1–6 words works best."}, "category": {"type": "string", "description": "Optional category filter.", "enum": ["Art", "Fashion", "Gadgets", "Hobby", "Household", "Learning", "Miniatures", "Tools", "Toys & Games", "Other"]}, "limit": {"type": "integer", "minimum": 1, "maximum": 30, "default": 12}}, "additionalProperties": false, "required": ["query"]}}}}, "responses": {"200": {"description": "Tool result", "content": {"application/json": {"schema": {"type": "object", "properties": {"query": {"type": "string"}, "count": {"type": "integer"}, "results": {"type": "array", "items": {"type": "object", "properties": {"uid": {"type": "string"}, "title": {"type": "string"}, "description": {"type": "string"}, "url": {"type": "string"}, "thumbnail_url": {"type": ["string", "null"]}, "author": {"type": ["string", "null"]}, "category": {"type": ["string", "null"]}, "tags": {"type": "array", "items": {"type": "string"}}, "price_usd": {"type": "number"}, "is_free": {"type": "boolean"}, "likes": {"type": "integer"}, "views": {"type": "integer"}}}}, "explore_url": {"type": "string"}, "generate_url": {"type": "string"}}, "required": ["query", "count", "results"]}}}}, "400": {"description": "Invalid input or tool-reported error", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}}}}}}}}, "/mcp/rest/get_3d_model": {"post": {"operationId": "get3dModel", "summary": "Get 3D model details", "description": "Get full details for one PrintPal model by uid: description, license, file formats, author, stats, and the page URL to download it. Accepts a uid from `search_3d_models` results or a printpal.io/model/<uid> URL.", "x-openai-isConsequential": false, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"uid": {"type": "string", "description": "Model uid from search results or a printpal.io/model/<uid> URL."}}, "additionalProperties": false, "required": ["uid"]}}}}, "responses": {"200": {"description": "Tool result", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": true}}}}, "400": {"description": "Invalid input or tool-reported error", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}}}}}}}}, "/mcp/rest/find_3d_printing_tool": {"post": {"operationId": "find3dPrintingTool", "summary": "Find a PrintPal tool or calculator", "description": "Recommend the right free PrintPal browser tool for a task: print cost / resin cost / layer height (magic numbers) / E-steps / flow rate / volumetric flow / filament spool / drying / shrinkage / Vref / Etsy profit calculators; generators for lithophanes, vases, name plates, 3D text, QR codes, bins, puzzles, mold boxes, flexi models, fidget clickers, Desk Pal, terrain maps, Minecraft maps; mesh repair, model splitter, converter, viewer, G-code viewer, AMS/multicolor painters; AI generators. Returns matching tools with links. Pass an empty task to list every tool.", "x-openai-isConsequential": false, "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"task": {"type": "string", "description": "What the user is trying to do, e.g. \"split a big model to fit my bed\"."}, "limit": {"type": "integer", "minimum": 1, "maximum": 50, "default": 6}}, "additionalProperties": false}}}}, "responses": {"200": {"description": "Tool result", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": true}}}}, "400": {"description": "Invalid input or tool-reported error", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}}}}}}}}, "/mcp/rest/calculate_print_cost": {"post": {"operationId": "calculatePrintCost", "summary": "Calculate 3D print cost", "description": "Estimate what an FDM print costs (material, electricity, machine wear, labor, failure allowance) and a suggested selling price. Needs the print weight in grams and time in hours from the slicer; all other inputs have sensible defaults (1 kg spool at $20, 120 W printer, $0.12/kWh, 5% failures).", "x-openai-isConsequential": false, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"print_weight_grams": {"type": "number", "description": "Filament used, from the slicer."}, "print_time_hours": {"type": "number", "description": "Print time in hours (e.g. 3.5)."}, "spool_price_usd": {"type": "number", "default": 20}, "spool_weight_kg": {"type": "number", "default": 1}, "printer_power_watts": {"type": "number", "default": 120}, "electricity_cost_per_kwh": {"type": "number", "default": 0.12}, "printer_cost_usd": {"type": "number", "description": "Printer purchase price, for depreciation. 0 to skip.", "default": 0}, "printer_lifespan_hours": {"type": "number", "default": 5000}, "failure_rate_percent": {"type": "number", "default": 5}, "labor_rate_per_hour": {"type": "number", "default": 0}, "labor_minutes": {"type": "number", "description": "Hands-on time: slicing, removal, post-processing.", "default": 0}, "markup_percent": {"type": "number", "description": "Profit markup to compute a selling price.", "default": 0}, "quantity": {"type": "integer", "default": 1}}, "additionalProperties": false, "required": ["print_weight_grams", "print_time_hours"]}}}}, "responses": {"200": {"description": "Tool result", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": true}}}}, "400": {"description": "Invalid input or tool-reported error", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}}}}}}}}, "/mcp/rest/calculate_filament_usage": {"post": {"operationId": "calculateFilamentUsage", "summary": "Filament weight ⇄ length ⇄ cost", "description": "Convert filament grams to metres (and back), compute volume and cost, and estimate how much is left on a spool from its gross weight. Knows densities for PLA, PETG, ABS, ASA, TPU, Nylon, PC, CF blends. Give either `grams` or `meters`.", "x-openai-isConsequential": false, "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"grams": {"type": "number"}, "meters": {"type": "number"}, "material": {"type": "string", "description": "pla, petg, abs, asa, tpu, nylon, pc, pla-cf, petg-cf, pa-cf …", "default": "pla"}, "density_g_cm3": {"type": "number", "description": "Override density if known."}, "diameter_mm": {"type": "number", "default": 1.75}, "spool_price_usd": {"type": "number"}, "spool_weight_kg": {"type": "number", "default": 1}, "spool_gross_weight_grams": {"type": "number", "description": "Weight of spool + remaining filament, to estimate what is left."}, "empty_spool_weight_grams": {"type": "number", "description": "Weight of the empty spool (typ. 130–250 g)."}}, "additionalProperties": false}}}}, "responses": {"200": {"description": "Tool result", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": true}}}}, "400": {"description": "Invalid input or tool-reported error", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}}}}}}}}, "/mcp/rest/calculate_layer_heights": {"post": {"operationId": "calculateLayerHeights", "summary": "Layer height magic numbers", "description": "Compute the Z-axis \"magic number\" layer heights for a printer from its stepper step angle, microstepping and lead-screw pitch/starts, filtered to what suits the nozzle. Defaults match most Ender/Prusa-style printers (1.8°, 1/16, T8 2 mm × 4 starts → 0.04 mm steps).", "x-openai-isConsequential": false, "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"step_angle_degrees": {"type": "number", "default": 1.8}, "microstepping": {"type": "integer", "default": 16}, "lead_screw_pitch_mm": {"type": "number", "default": 2}, "lead_screw_starts": {"type": "integer", "default": 4}, "nozzle_diameter_mm": {"type": "number", "default": 0.4}, "max_layer_height_mm": {"type": "number"}}, "additionalProperties": false}}}}, "responses": {"200": {"description": "Tool result", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": true}}}}, "400": {"description": "Invalid input or tool-reported error", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}}}}}}}}, "/mcp/rest/calculate_volumetric_flow": {"post": {"operationId": "calculateVolumetricFlow", "summary": "Volumetric flow / max speed check", "description": "Check whether a hotend can keep up: volumetric flow (mm³/s) = layer height × line width × speed, compared against the hotend limit, plus the maximum safe speed. Accepts a hotend preset name (stock, v6, bambu, volcano, rapido, high-flow, goliath…) or an explicit max flow.", "x-openai-isConsequential": false, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"layer_height_mm": {"type": "number", "default": 0.2}, "line_width_mm": {"type": "number", "default": 0.42}, "print_speed_mm_s": {"type": "number"}, "max_volumetric_flow_mm3_s": {"type": "number"}, "hotend": {"type": "string", "description": "Preset: stock, v6, ender3, prusa-mk3, prusa-mk4, bambu, volcano, rapido, dragon-hf, high-flow, chc-pro, goliath, voron"}}, "additionalProperties": false, "required": ["print_speed_mm_s"]}}}}, "responses": {"200": {"description": "Tool result", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": true}}}}, "400": {"description": "Invalid input or tool-reported error", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}}}}}}}}, "/mcp/rest/search_build_guides": {"post": {"operationId": "searchBuildGuides", "summary": "Search build guides & projects", "description": "Find step-by-step PrintPal build guides: Arduino/ESP32 electronics + 3D-printed enclosures, robots, functional prints, printer mods, STEM classroom projects, props and toys. Each result lists difficulty, time, cost, part/file/step counts. Filter by category (electronics-robotics, functional-prints, home-workshop, stem-education, printer-mods, art-props, toys-games) or difficulty (beginner, intermediate, advanced). Leave query empty to browse featured guides.", "x-openai-isConsequential": false, "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {"query": {"type": "string"}, "category": {"type": "string", "description": "Category slug or name."}, "difficulty": {"type": "string", "enum": ["beginner", "intermediate", "advanced"]}, "sort": {"type": "string", "enum": ["featured", "recent", "popular", "liked"], "default": "featured"}, "limit": {"type": "integer", "minimum": 1, "maximum": 25, "default": 8}}, "additionalProperties": false}}}}, "responses": {"200": {"description": "Tool result", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": true}}}}, "400": {"description": "Invalid input or tool-reported error", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}}}}}}}}, "/mcp/rest/get_build_guide": {"post": {"operationId": "getBuildGuide", "summary": "Get a build guide (steps, BOM, files)", "description": "Read a full PrintPal build guide by slug: summary, bill of materials with quantities and links, downloadable files (STL/3MF/code), every build step, callouts and code blocks. Use when the user wants to actually follow or adapt a project.", "x-openai-isConsequential": false, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"slug": {"type": "string", "description": "Project slug from search results or a printpal.io/projects/<slug> URL."}}, "additionalProperties": false, "required": ["slug"]}}}}, "responses": {"200": {"description": "Tool result", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": true}}}}, "400": {"description": "Invalid input or tool-reported error", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}}}}}}}}, "/mcp/rest/search_learning_resources": {"post": {"operationId": "searchLearningResources", "summary": "Search guides, videos & courses", "description": "Search PrintPal's how-to content: the vendor-neutral 3D printing wiki (print quality, filaments, slicer settings, maintenance, error codes, safety), OpenSCAD + AI-CAD docs, short video tutorials with transcripts, and free Academy courses with certificates. Use `type` to narrow. Results include ids accepted by `fetch` for the full article text.", "x-openai-isConsequential": false, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"query": {"type": "string"}, "type": {"type": "string", "enum": ["all", "wiki", "docs", "videos", "courses"], "default": "all"}, "limit": {"type": "integer", "minimum": 1, "maximum": 25, "default": 8}}, "additionalProperties": false, "required": ["query"]}}}}, "responses": {"200": {"description": "Tool result", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": true}}}}, "400": {"description": "Invalid input or tool-reported error", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}}}}}}}}, "/mcp/rest/generate_3d_model": {"post": {"operationId": "generate3dModel", "summary": "Generate a 3D model with AI (text or image → STL/GLB/OBJ)", "description": "Turn a text prompt or an image into a print-ready 3D mesh (STL/GLB/OBJ geometry) with PrintPal's AI generator. Without a PrintPal API key this returns a link that opens the generator on printpal.io with the prompt prefilled; nothing is generated until the user clicks it. With an API key header (`Authorization: Bearer pp_live_…`) it submits the job to the user's own account, spends that account's credits, and returns a `generation_uid` that `check_3d_generation` accepts. Suited to organic/sculptural objects (figurines, animals, props); exact-dimension mechanical parts are handled by `design_parametric_cad`.", "x-openai-isConsequential": true, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"prompt": {"type": "string", "description": "What to generate, e.g. \"low-poly fox figurine, sitting\"."}, "image_url": {"type": "string", "description": "Optional public PNG/JPEG/WebP URL for image-to-3D (API-key mode only)."}, "quality": {"type": "string", "enum": ["default", "high", "ultra", "super", "super_texture", "superplus", "superplus_texture", "superplus_1280", "superplus_1280_texture", "superplus_1536", "superplus_1536_texture"], "default": "default", "description": "default/high/ultra for text or image; super*/superplus* tiers are image-only high-res."}, "format": {"type": "string", "enum": ["glb", "stl", "obj", "ply", "fbx"], "default": "glb"}}, "additionalProperties": false, "required": ["prompt"]}}}}, "responses": {"200": {"description": "Tool result", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": true}}}}, "400": {"description": "Invalid input or tool-reported error", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}}}}}}}}, "/mcp/rest/check_3d_generation": {"post": {"operationId": "check3dGeneration", "summary": "Check AI 3D generation status / get download", "description": "Poll a PrintPal AI generation started with `generate_3d_model` in API-key mode. Returns status (queued/processing/completed/failed) and, when completed, a time-limited download URL for the mesh.", "x-openai-isConsequential": false, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"generation_uid": {"type": "string"}}, "additionalProperties": false, "required": ["generation_uid"]}}}}, "responses": {"200": {"description": "Tool result", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": true}}}}, "400": {"description": "Invalid input or tool-reported error", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}}}}}}}}, "/mcp/rest/design_parametric_cad": {"post": {"operationId": "designParametricCad", "summary": "Design a parametric part with the AI CAD agent", "description": "For mechanical / functional parts with exact dimensions — brackets, enclosures, adapters, gears, bins, knobs, mounts — open PrintPal's AI CAD agent with a ready-to-run brief. The agent writes editable OpenSCAD with parameter sliders, live 3D preview and STL/3MF/STEP export. This tool improves the user's description into a precise CAD brief (dimensions, tolerances, mounting, print orientation) and returns the link; the user clicks it to generate.", "x-openai-isConsequential": false, "requestBody": {"required": true, "content": {"application/json": {"schema": {"type": "object", "properties": {"description": {"type": "string", "description": "What the part is and what it must fit/do."}, "dimensions": {"type": "string", "description": "Known dimensions in mm, e.g. \"60 x 40 x 20 mm, M3 holes 50 mm apart\"."}, "material": {"type": "string", "description": "Intended filament (affects tolerances), e.g. PLA, PETG, TPU."}, "export_format": {"type": "string", "enum": ["stl", "3mf", "step", "scad"], "default": "stl"}}, "additionalProperties": false, "required": ["description"]}}}}, "responses": {"200": {"description": "Tool result", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": true}}}}, "400": {"description": "Invalid input or tool-reported error", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}}}}}}}}, "/mcp/rest/get_pricing_and_plans": {"post": {"operationId": "getPricingAndPlans", "summary": "PrintPal pricing, credits & plans", "description": "Explain what is free on PrintPal, how AI generation credits and the CAD agent are priced, API access and the on-demand 3D printing service — with links to sign up, buy credits or subscribe. Call when the user asks about cost, limits, subscriptions or how to get more generations.", "x-openai-isConsequential": false, "requestBody": {"required": false, "content": {"application/json": {"schema": {"type": "object", "properties": {}, "additionalProperties": false}}}}, "responses": {"200": {"description": "Tool result", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": true}}}}, "400": {"description": "Invalid input or tool-reported error", "content": {"application/json": {"schema": {"type": "object", "properties": {"error": {"type": "string"}}}}}}}}}}}