@meshy-ai/meshy-mcp-server 0.2.0

package/.env.example

@@ -0,0 +1,14 @@
+# Required: Your Meshy API key
+MESHY_API_KEY=your_api_key_here
+
+# Optional: Meshy API host (default: https://api.meshy.ai)
+MESHY_API_HOST=https://api.meshy.ai
+
+# Optional: Transport mode (stdio or http, default: stdio)
+TRANSPORT=stdio
+
+# Optional: Port for HTTP transport (default: 3000)
+PORT=3000
+
+# Optional: Maximum response size in characters (default: 25000)
+CHARACTER_LIMIT=25000

package/LICENSE

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

package/README.md

@@ -0,0 +1,108 @@
+# Meshy MCP Server
+
+[Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for the [Meshy AI](https://www.meshy.ai) 3D generation platform. Enables AI agents to create, manage, and download 3D models, textures, images, rigged characters, and animations through natural conversation.
+
+## Features
+
+19 tools covering the full Meshy API:
+
+| Category | Tools |
+|----------|-------|
+| **3D Generation** | `meshy_text_to_3d`, `meshy_text_to_3d_refine`, `meshy_image_to_3d`, `meshy_multi_image_to_3d` |
+| **Post-Processing** | `meshy_remesh`, `meshy_retexture`, `meshy_rig`, `meshy_animate` |
+| **Image Generation** | `meshy_text_to_image`, `meshy_image_to_image` |
+| **Task Management** | `meshy_get_task_status`, `meshy_list_tasks`, `meshy_cancel_task`, `meshy_download_model` |
+| **Workspace** | `meshy_list_models` |
+| **3D Printing** | `meshy_send_to_slicer`, `meshy_analyze_printability`, `meshy_process_multicolor` |
+| **Account** | `meshy_check_balance` |
+
+### Key Capabilities
+
+- **Text to 3D**: Generate 3D models from text descriptions (preview + refine pipeline)
+- **Image to 3D**: Convert single or multiple images into 3D models
+- **Auto-Rigging & Animation**: Add skeletons and animations to humanoid characters
+- **Multi-Color 3D Printing**: Process textured models into multi-color 3MF files for 3D printing
+- **Slicer Integration**: Auto-detect installed slicer software and open models directly
+- **Print-Ready OBJ**: Built-in coordinate transformation (Y-up → Z-up) for 3D printing
+- **Smart File Organization**: Auto-saves to `meshy_output/` with project folders, metadata, and history tracking
+- **Built-in Workflow Intelligence**: Server instructions guide the agent through correct tool chains for each use case
+
+## Quick Start
+
+### Prerequisites
+
+- Node.js >= 18
+- A Meshy API key ([get one here](https://www.meshy.ai/settings/api) — requires Pro plan or above)
+
+### Claude Code
+
+```bash
+claude mcp add meshy -- npx -y @meshy-ai/meshy-mcp-server -e MESHY_API_KEY=msy_YOUR_API_KEY
+```
+
+That's it. The server includes built-in workflow instructions — no additional configuration needed.
+
+### Cursor
+
+Add to your Cursor MCP settings (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "meshy": {
+      "command": "npx",
+      "args": ["-y", "@meshy-ai/meshy-mcp-server"],
+      "env": {
+        "MESHY_API_KEY": "msy_YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+| Environment Variable | Description | Default |
+|---------------------|-------------|---------|
+| `MESHY_API_KEY` | **Required.** Your Meshy API key (starts with `msy_`) | — |
+| `MESHY_API_HOST` | API base URL | `https://api.meshy.ai` |
+| `TRANSPORT` | Transport mode: `stdio` or `http` | `stdio` |
+| `PORT` | Port for HTTP transport | `3000` |
+| `CHARACTER_LIMIT` | Max response size in characters | `25000` |
+
+## Development
+
+```bash
+# Clone and install
+git clone https://github.com/meshy-dev/meshy-mcp-server.git
+cd meshy-mcp-server
+npm install
+
+# Development with hot reload
+npm run dev
+
+# Build
+npm run build
+
+# Type check
+npm run lint
+
+# Run
+npm start
+```
+
+## HTTP Transport
+
+For remote access, run in HTTP mode:
+
+```bash
+TRANSPORT=http PORT=3000 npm start
+```
+
+Endpoints:
+- `POST /mcp` — MCP protocol endpoint
+- `GET /health` — Health check
+
+## License
+
+[MIT](LICENSE)

package/dist/constants.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Constants for Meshy MCP Server
+ */
+export declare const API_BASE_URL: string;
+export declare const CHARACTER_LIMIT: number;
+export declare enum ResponseFormat {
+    MARKDOWN = "markdown",
+    JSON = "json"
+}
+export declare enum TaskStatus {
+    PENDING = "PENDING",
+    IN_PROGRESS = "IN_PROGRESS",
+    SUCCEEDED = "SUCCEEDED",
+    FAILED = "FAILED",
+    CANCELED = "CANCELED"
+}
+export declare enum TaskPhase {
+    DRAFT = "draft",
+    GENERATE = "generate",
+    TEXTURE = "texture",
+    STYLIZE = "stylize",
+    ANIMATE = "animate"
+}
+export declare enum Topology {
+    QUAD = "quad",
+    TRIANGLE = "triangle"
+}
+export declare enum ModelFormat {
+    GLB = "glb",
+    FBX = "fbx",
+    USDZ = "usdz",
+    THREE_MF = "3mf"
+}
+export declare enum AIModel {
+    MESHY_5 = "meshy-5",
+    MESHY_6 = "meshy-6",
+    LATEST = "latest"
+}
+export declare enum ModelType {
+    STANDARD = "standard",
+    LOWPOLY = "lowpoly"
+}
+export declare enum SymmetryMode {
+    OFF = "off",
+    AUTO = "auto",
+    ON = "on"
+}
+export declare enum PoseMode {
+    A_POSE = "a-pose",
+    T_POSE = "t-pose"
+}
+export declare enum TaskType {
+    TEXT_TO_3D = "text-to-3d",
+    IMAGE_TO_3D = "image-to-3d",
+    MULTI_IMAGE_TO_3D = "multi-image-to-3d",
+    REMESH = "remesh",
+    RETEXTURE = "retexture",
+    RIGGING = "rigging",
+    ANIMATION = "animation",
+    TEXT_TO_IMAGE = "text-to-image",
+    IMAGE_TO_IMAGE = "image-to-image",
+    MULTI_COLOR_PRINT = "multi-color-print"
+}
+export declare enum RemeshFormat {
+    GLB = "glb",
+    FBX = "fbx",
+    OBJ = "obj",
+    USDZ = "usdz",
+    BLEND = "blend",
+    STL = "stl"
+}
+export declare enum OriginAt {
+    BOTTOM = "bottom",
+    CENTER = "center"
+}
+export declare enum TextToImageModel {
+    NANO_BANANA = "nano-banana",
+    NANO_BANANA_PRO = "nano-banana-pro"
+}
+export declare enum AspectRatio {
+    SQUARE = "1:1",
+    WIDESCREEN = "16:9",
+    PORTRAIT = "9:16",
+    STANDARD = "4:3",
+    PORTRAIT_STANDARD = "3:4"
+}
+export declare enum SlicerType {
+    AUTO = "auto",
+    BAMBU = "bambu",
+    ORCASLICER = "orcaslicer",
+    CREALITY_PRINT = "creality_print",
+    ELEGOO_SLICER = "elegoo_slicer",
+    ANYCUBIC_SLICER = "anycubic_slicer",
+    PRUSASLICER = "prusaslicer",
+    CURA = "cura"
+}
+export declare const MULTICOLOR_CAPABLE_SLICERS: SlicerType[];
+export declare const MULTI_COLOR_CREDITS = 10;
+export declare enum AnimationPostProcessOp {
+    CHANGE_FPS = "change_fps",
+    FBX2USDZ = "fbx2usdz",
+    EXTRACT_ARMATURE = "extract_armature"
+}
+export declare enum ErrorCode {
+    INSUFFICIENT_CREDITS = "InsufficientCredits",
+    TOO_MANY_PENDING_TASKS = "TooManyPendingTasks",
+    INVALID_MODEL_NOT_SUPPORTED = "InvalidModel:NotSupported",
+    INVALID_MODEL_INVALID_FORMAT = "InvalidModel:InvalidFormat",
+    LIMIT_EXCEEDED = "LimitExceeded",
+    FORBIDDEN = "Forbidden",
+    NOT_FOUND = "NotFound",
+    INTERNAL_ERROR = "InternalError"
+}
+export declare const API_TIMEOUT = 30000;
+export declare const RETRY_DELAYS: number[];
+export declare const MAX_RETRIES = 3;
+export declare const POLL_INITIAL_DELAY = 5000;
+export declare const POLL_MAX_DELAY = 30000;
+export declare const POLL_BACKOFF_FACTOR = 1.5;
+export declare const POLL_FINALIZATION_DELAY = 15000;
+export declare const POLL_DEFAULT_TIMEOUT = 300000;
+export declare const POLL_MAX_TIMEOUT = 300000;
+export declare const RIGGING_MAX_FACES = 300000;

package/dist/constants.js

@@ -0,0 +1,169 @@
+/**
+ * Constants for Meshy MCP Server
+ */
+// API Configuration
+export const API_BASE_URL = process.env.MESHY_API_HOST || "https://api.meshy.ai";
+export const CHARACTER_LIMIT = parseInt(process.env.CHARACTER_LIMIT || "25000", 10);
+// Response Formats
+export var ResponseFormat;
+(function (ResponseFormat) {
+    ResponseFormat["MARKDOWN"] = "markdown";
+    ResponseFormat["JSON"] = "json";
+})(ResponseFormat || (ResponseFormat = {}));
+// Task Status
+export var TaskStatus;
+(function (TaskStatus) {
+    TaskStatus["PENDING"] = "PENDING";
+    TaskStatus["IN_PROGRESS"] = "IN_PROGRESS";
+    TaskStatus["SUCCEEDED"] = "SUCCEEDED";
+    TaskStatus["FAILED"] = "FAILED";
+    TaskStatus["CANCELED"] = "CANCELED";
+})(TaskStatus || (TaskStatus = {}));
+// Task Phases
+export var TaskPhase;
+(function (TaskPhase) {
+    TaskPhase["DRAFT"] = "draft";
+    TaskPhase["GENERATE"] = "generate";
+    TaskPhase["TEXTURE"] = "texture";
+    TaskPhase["STYLIZE"] = "stylize";
+    TaskPhase["ANIMATE"] = "animate";
+})(TaskPhase || (TaskPhase = {}));
+// Topology Types
+export var Topology;
+(function (Topology) {
+    Topology["QUAD"] = "quad";
+    Topology["TRIANGLE"] = "triangle";
+})(Topology || (Topology = {}));
+// Model Formats
+export var ModelFormat;
+(function (ModelFormat) {
+    ModelFormat["GLB"] = "glb";
+    ModelFormat["FBX"] = "fbx";
+    ModelFormat["USDZ"] = "usdz";
+    ModelFormat["THREE_MF"] = "3mf";
+})(ModelFormat || (ModelFormat = {}));
+// AI Models
+export var AIModel;
+(function (AIModel) {
+    AIModel["MESHY_5"] = "meshy-5";
+    AIModel["MESHY_6"] = "meshy-6";
+    AIModel["LATEST"] = "latest";
+})(AIModel || (AIModel = {}));
+// Model Types
+export var ModelType;
+(function (ModelType) {
+    ModelType["STANDARD"] = "standard";
+    ModelType["LOWPOLY"] = "lowpoly";
+})(ModelType || (ModelType = {}));
+// Symmetry Modes
+export var SymmetryMode;
+(function (SymmetryMode) {
+    SymmetryMode["OFF"] = "off";
+    SymmetryMode["AUTO"] = "auto";
+    SymmetryMode["ON"] = "on";
+})(SymmetryMode || (SymmetryMode = {}));
+// Pose Modes
+export var PoseMode;
+(function (PoseMode) {
+    PoseMode["A_POSE"] = "a-pose";
+    PoseMode["T_POSE"] = "t-pose";
+})(PoseMode || (PoseMode = {}));
+// Task Types
+export var TaskType;
+(function (TaskType) {
+    TaskType["TEXT_TO_3D"] = "text-to-3d";
+    TaskType["IMAGE_TO_3D"] = "image-to-3d";
+    TaskType["MULTI_IMAGE_TO_3D"] = "multi-image-to-3d";
+    TaskType["REMESH"] = "remesh";
+    TaskType["RETEXTURE"] = "retexture";
+    TaskType["RIGGING"] = "rigging";
+    TaskType["ANIMATION"] = "animation";
+    TaskType["TEXT_TO_IMAGE"] = "text-to-image";
+    TaskType["IMAGE_TO_IMAGE"] = "image-to-image";
+    TaskType["MULTI_COLOR_PRINT"] = "multi-color-print";
+})(TaskType || (TaskType = {}));
+// Remesh Output Formats
+export var RemeshFormat;
+(function (RemeshFormat) {
+    RemeshFormat["GLB"] = "glb";
+    RemeshFormat["FBX"] = "fbx";
+    RemeshFormat["OBJ"] = "obj";
+    RemeshFormat["USDZ"] = "usdz";
+    RemeshFormat["BLEND"] = "blend";
+    RemeshFormat["STL"] = "stl";
+})(RemeshFormat || (RemeshFormat = {}));
+// Origin At (for remesh)
+export var OriginAt;
+(function (OriginAt) {
+    OriginAt["BOTTOM"] = "bottom";
+    OriginAt["CENTER"] = "center";
+})(OriginAt || (OriginAt = {}));
+// Text-to-Image Models
+export var TextToImageModel;
+(function (TextToImageModel) {
+    TextToImageModel["NANO_BANANA"] = "nano-banana";
+    TextToImageModel["NANO_BANANA_PRO"] = "nano-banana-pro";
+})(TextToImageModel || (TextToImageModel = {}));
+// Aspect Ratios
+export var AspectRatio;
+(function (AspectRatio) {
+    AspectRatio["SQUARE"] = "1:1";
+    AspectRatio["WIDESCREEN"] = "16:9";
+    AspectRatio["PORTRAIT"] = "9:16";
+    AspectRatio["STANDARD"] = "4:3";
+    AspectRatio["PORTRAIT_STANDARD"] = "3:4";
+})(AspectRatio || (AspectRatio = {}));
+// Slicer Types
+export var SlicerType;
+(function (SlicerType) {
+    SlicerType["AUTO"] = "auto";
+    SlicerType["BAMBU"] = "bambu";
+    SlicerType["ORCASLICER"] = "orcaslicer";
+    SlicerType["CREALITY_PRINT"] = "creality_print";
+    SlicerType["ELEGOO_SLICER"] = "elegoo_slicer";
+    SlicerType["ANYCUBIC_SLICER"] = "anycubic_slicer";
+    SlicerType["PRUSASLICER"] = "prusaslicer";
+    SlicerType["CURA"] = "cura";
+})(SlicerType || (SlicerType = {}));
+// Slicers that support multi-color printing (AMS/MMU)
+export const MULTICOLOR_CAPABLE_SLICERS = [
+    SlicerType.ORCASLICER,
+    SlicerType.BAMBU,
+    SlicerType.CREALITY_PRINT,
+    SlicerType.ELEGOO_SLICER,
+    SlicerType.ANYCUBIC_SLICER
+];
+// Multi-color processing credit cost
+export const MULTI_COLOR_CREDITS = 10;
+// Animation Post Process Operations
+export var AnimationPostProcessOp;
+(function (AnimationPostProcessOp) {
+    AnimationPostProcessOp["CHANGE_FPS"] = "change_fps";
+    AnimationPostProcessOp["FBX2USDZ"] = "fbx2usdz";
+    AnimationPostProcessOp["EXTRACT_ARMATURE"] = "extract_armature";
+})(AnimationPostProcessOp || (AnimationPostProcessOp = {}));
+// Error Codes
+export var ErrorCode;
+(function (ErrorCode) {
+    ErrorCode["INSUFFICIENT_CREDITS"] = "InsufficientCredits";
+    ErrorCode["TOO_MANY_PENDING_TASKS"] = "TooManyPendingTasks";
+    ErrorCode["INVALID_MODEL_NOT_SUPPORTED"] = "InvalidModel:NotSupported";
+    ErrorCode["INVALID_MODEL_INVALID_FORMAT"] = "InvalidModel:InvalidFormat";
+    ErrorCode["LIMIT_EXCEEDED"] = "LimitExceeded";
+    ErrorCode["FORBIDDEN"] = "Forbidden";
+    ErrorCode["NOT_FOUND"] = "NotFound";
+    ErrorCode["INTERNAL_ERROR"] = "InternalError";
+})(ErrorCode || (ErrorCode = {}));
+// Timeouts
+export const API_TIMEOUT = 30000; // 30 seconds
+export const RETRY_DELAYS = [2000, 4000, 8000]; // Exponential backoff
+export const MAX_RETRIES = 3;
+// Polling Configuration (for meshy_get_task_status wait mode)
+export const POLL_INITIAL_DELAY = 5000; // 5 seconds
+export const POLL_MAX_DELAY = 30000; // 30 seconds
+export const POLL_BACKOFF_FACTOR = 1.5;
+export const POLL_FINALIZATION_DELAY = 15000; // 15s when progress >= 95%
+export const POLL_DEFAULT_TIMEOUT = 300000; // 5 minutes
+export const POLL_MAX_TIMEOUT = 300000; // 5 minutes
+// Rigging Constraints
+export const RIGGING_MAX_FACES = 300000;

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * Meshy MCP Server
+ *
+ * Model Context Protocol server for Meshy AI's 3D generation platform.
+ * Enables AI agents to create and manage 3D models programmatically.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * Meshy MCP Server
+ *
+ * Model Context Protocol server for Meshy AI's 3D generation platform.
+ * Enables AI agents to create and manage 3D models programmatically.
+ */
+// Load environment variables from .env file
+import dotenv from "dotenv";
+// Redirect console.log to stderr during dotenv load to prevent stdio corruption
+// (dotenv may call console.log which would corrupt the stdio JSON-RPC transport)
+const originalLog = console.log;
+console.log = (...args) => console.error(...args);
+dotenv.config();
+console.log = originalLog;
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import express from "express";
+import { createMeshyClient } from "./services/meshy-client.js";
+import { registerGenerationTools } from "./tools/generation.js";
+import { registerTaskTools } from "./tools/tasks.js";
+import { registerWorkspaceTools } from "./tools/workspace.js";
+import { registerPostProcessingTools } from "./tools/postprocessing.js";
+import { registerImageTools } from "./tools/image.js";
+import { registerPrintingTools } from "./tools/printing.js";
+import { registerBalanceTool } from "./tools/balance.js";
+import { MESHY_INSTRUCTIONS } from "./instructions.js";
+// Create MCP server instance
+const server = new McpServer({ name: "@meshy-ai/meshy-mcp-server", version: "0.2.0" }, { instructions: MESHY_INSTRUCTIONS });
+/**
+ * Initialize server and register tools
+ */
+async function initializeServer() {
+    try {
+        // Create and validate Meshy API client
+        const meshyClient = await createMeshyClient();
+        console.error("✓ Meshy client initialized");
+        // Register all tools
+        console.error("Registering MCP tools...");
+        registerGenerationTools(server, meshyClient);
+        console.error("  ✓ Generation tools registered (text-to-3d, text-to-3d-refine, image-to-3d, multi-image-to-3d)");
+        registerTaskTools(server, meshyClient);
+        console.error("  ✓ Task management tools registered (get status, list, cancel, download)");
+        registerWorkspaceTools(server, meshyClient);
+        console.error("  ✓ Workspace tools registered (list models)");
+        registerPostProcessingTools(server, meshyClient);
+        console.error("  ✓ Post-processing tools registered (remesh, retexture, rig, animate)");
+        registerImageTools(server, meshyClient);
+        console.error("  ✓ Image tools registered (text-to-image, image-to-image)");
+        registerPrintingTools(server, meshyClient);
+        console.error("  ✓ Printing tools registered (send-to-slicer, analyze-printability, process-multicolor)");
+        registerBalanceTool(server, meshyClient);
+        console.error("  ✓ Balance tool registered (check-balance)");
+        console.error("✓ Server initialized successfully with 19 tools");
+        return meshyClient;
+    }
+    catch (error) {
+        console.error("Failed to initialize server:", error);
+        throw error;
+    }
+}
+/**
+ * Run server with stdio transport (for local integrations)
+ */
+async function runStdio() {
+    console.error("Starting Meshy MCP Server (stdio mode)...");
+    await initializeServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("✓ Meshy MCP Server running via stdio");
+    console.error("Ready to accept requests from MCP client");
+}
+/**
+ * Run server with HTTP transport (for remote access)
+ */
+async function runHTTP() {
+    console.error("Starting Meshy MCP Server (HTTP mode)...");
+    await initializeServer();
+    const app = express();
+    app.use(express.json());
+    // Health check endpoint
+    app.get("/health", (req, res) => {
+        res.json({ status: "ok", server: "meshy-mcp-server", version: "1.0.0" });
+    });
+    // MCP endpoint
+    app.post("/mcp", async (req, res) => {
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+            enableJsonResponse: true
+        });
+        res.on("close", () => transport.close());
+        await server.connect(transport);
+        await transport.handleRequest(req, res, req.body);
+    });
+    const port = parseInt(process.env.PORT || "3000", 10);
+    app.listen(port, () => {
+        console.error(`✓ Meshy MCP Server running on http://localhost:${port}/mcp`);
+        console.error(`Health check: http://localhost:${port}/health`);
+    });
+}
+/**
+ * Main entry point
+ */
+async function main() {
+    const transport = process.env.TRANSPORT || "stdio";
+    try {
+        if (transport === "http") {
+            await runHTTP();
+        }
+        else {
+            await runStdio();
+        }
+    }
+    catch (error) {
+        console.error("Fatal error:", error);
+        process.exit(1);
+    }
+}
+// Handle graceful shutdown
+process.on("SIGINT", () => {
+    console.error("\nShutting down gracefully...");
+    process.exit(0);
+});
+process.on("SIGTERM", () => {
+    console.error("\nShutting down gracefully...");
+    process.exit(0);
+});
+// Start the server
+main();

package/dist/instructions.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Server-level instructions sent to clients on connection.
+ * Provides top-level workflow routing so the agent picks the right tool chain.
+ * Specific parameter details and constraints live in each tool's description.
+ */
+export declare const MESHY_INSTRUCTIONS = "\n# Meshy AI \u2014 Workflow Guide\n\n## Rule 1: Cost Confirmation\nBefore calling ANY tool that costs credits, present the cost and wait for user confirmation.\n\n| Tool | Credits |\n|------|---------|\n| meshy_text_to_3d | 5\u201320 |\n| meshy_text_to_3d_refine | 10 |\n| meshy_image_to_3d / meshy_multi_image_to_3d | 5\u201330 |\n| meshy_retexture | 10 |\n| meshy_remesh | 5 |\n| meshy_rig | 5 (includes walking + running) |\n| meshy_animate | 3 |\n| meshy_process_multicolor | 10 |\n| meshy_text_to_image / meshy_image_to_image | 3\u20139 |\n\n## Rule 2: Determine Output Format BEFORE Generating\nThe API parameter target_formats controls which formats are produced. Decide the output format before calling any generation tool, because target_formats must be set at creation time. Ask user about their intended use first.\n\n## Rule 3: Identify the Use Case, Then Confirm with User\nDetermine which scenario below best matches, present a suggested plan to the user, and confirm before executing. Do not mix steps across scenarios.\n\n---\n\nEach scenario below is a recommended workflow. Discuss with the user to confirm the plan before executing.\n\n## Scenario A: 3D Printing (white model)\nTrigger: user mentions print, slicer, figurine, miniature, statue, physical model \u2014 single-color.\nSuggested flow:\n1. Detect installed slicers (meshy_send_to_slicer, slicer_type:\"auto\") \u2014 present list, save for later\n2. Generate untextured model (text-to-3d or image-to-3d) with target_formats:[\"obj\"]\n3. Wait for completion\n4. Download OBJ with print_ready=true (auto coordinate fix for slicer)\n5. Present slicer list from step 1, ask user which to use, execute launch_command via Bash\n\n## Scenario B: 3D Printing (multicolor)\nTrigger: user wants multicolor/color print.\nSuggested flow:\n1. Detect multicolor-capable slicers (meshy_send_to_slicer, is_multicolor:true) \u2014 present list, save for later\n2. Generate a textured model \u2014 via text-to-3d (preview + refine) or image-to-3d with textures\n3. Multi-color processing (meshy_process_multicolor) with input_task_id from the textured task \u2014 10 credits, outputs 3MF\n4. Wait for completion (task_type:\"multi-color-print\")\n5. Download 3MF\n6. Present slicer list from step 1, ask user which to use, execute launch_command via Bash\n\n## Scenario C: Game Engine (Unity/Unreal/Godot)\nTrigger: user mentions game, Unity, Unreal, Godot, game-ready.\nSuggested flow:\n1. Generate model with target_formats:[\"fbx\"]\n2. Add textures (refine or retexture)\n3. Remesh for game-ready topology (meshy_remesh, topology:\"quad\", appropriate polycount)\n4. Download FBX\n\n## Scenario D: Character Animation\nTrigger: user mentions rig, animate, walking, running, character animation.\nSuggested flow:\n1. Generate model with pose_mode:\"t-pose\"\n2. Add textures (refine or retexture)\n3. Rig the model (meshy_rig, \u2264300K faces; if over, remesh to reduce polycount first)\n4. Download \u2014 rigging includes walking+running free. Only use meshy_animate for custom animations.\n\n## Scenario E: AR / Apple\nTrigger: user mentions AR, USDZ, Vision Pro, Quick Look.\nSuggested flow:\n1. Generate model with target_formats:[\"usdz\"]\n2. Add textures (refine or retexture)\n3. Remesh for USDZ format conversion (meshy_remesh, target_formats:[\"usdz\"])\n4. Download USDZ\n\n## Scenario F: Retexture\nTrigger: user wants to change textures/style of existing model.\nSuggested flow:\n1. Ask user for text_style_prompt OR image_style_url (one required, image takes precedence)\n2. Apply retexture (meshy_retexture)\n\n## Scenario G: General 3D Model (default)\nTrigger: none of the above.\nSuggested flow:\n1. Ask user about intended use to determine format\n2. Generate model\n3. Ask: add textures (refine)?\n4. Download in chosen format\n";

package/dist/instructions.js

@@ -0,0 +1,90 @@
+/**
+ * Server-level instructions sent to clients on connection.
+ * Provides top-level workflow routing so the agent picks the right tool chain.
+ * Specific parameter details and constraints live in each tool's description.
+ */
+export const MESHY_INSTRUCTIONS = `
+# Meshy AI — Workflow Guide
+
+## Rule 1: Cost Confirmation
+Before calling ANY tool that costs credits, present the cost and wait for user confirmation.
+
+| Tool | Credits |
+|------|---------|
+| meshy_text_to_3d | 5–20 |
+| meshy_text_to_3d_refine | 10 |
+| meshy_image_to_3d / meshy_multi_image_to_3d | 5–30 |
+| meshy_retexture | 10 |
+| meshy_remesh | 5 |
+| meshy_rig | 5 (includes walking + running) |
+| meshy_animate | 3 |
+| meshy_process_multicolor | 10 |
+| meshy_text_to_image / meshy_image_to_image | 3–9 |
+
+## Rule 2: Determine Output Format BEFORE Generating
+The API parameter target_formats controls which formats are produced. Decide the output format before calling any generation tool, because target_formats must be set at creation time. Ask user about their intended use first.
+
+## Rule 3: Identify the Use Case, Then Confirm with User
+Determine which scenario below best matches, present a suggested plan to the user, and confirm before executing. Do not mix steps across scenarios.
+
+---
+
+Each scenario below is a recommended workflow. Discuss with the user to confirm the plan before executing.
+
+## Scenario A: 3D Printing (white model)
+Trigger: user mentions print, slicer, figurine, miniature, statue, physical model — single-color.
+Suggested flow:
+1. Detect installed slicers (meshy_send_to_slicer, slicer_type:"auto") — present list, save for later
+2. Generate untextured model (text-to-3d or image-to-3d) with target_formats:["obj"]
+3. Wait for completion
+4. Download OBJ with print_ready=true (auto coordinate fix for slicer)
+5. Present slicer list from step 1, ask user which to use, execute launch_command via Bash
+
+## Scenario B: 3D Printing (multicolor)
+Trigger: user wants multicolor/color print.
+Suggested flow:
+1. Detect multicolor-capable slicers (meshy_send_to_slicer, is_multicolor:true) — present list, save for later
+2. Generate a textured model — via text-to-3d (preview + refine) or image-to-3d with textures
+3. Multi-color processing (meshy_process_multicolor) with input_task_id from the textured task — 10 credits, outputs 3MF
+4. Wait for completion (task_type:"multi-color-print")
+5. Download 3MF
+6. Present slicer list from step 1, ask user which to use, execute launch_command via Bash
+
+## Scenario C: Game Engine (Unity/Unreal/Godot)
+Trigger: user mentions game, Unity, Unreal, Godot, game-ready.
+Suggested flow:
+1. Generate model with target_formats:["fbx"]
+2. Add textures (refine or retexture)
+3. Remesh for game-ready topology (meshy_remesh, topology:"quad", appropriate polycount)
+4. Download FBX
+
+## Scenario D: Character Animation
+Trigger: user mentions rig, animate, walking, running, character animation.
+Suggested flow:
+1. Generate model with pose_mode:"t-pose"
+2. Add textures (refine or retexture)
+3. Rig the model (meshy_rig, ≤300K faces; if over, remesh to reduce polycount first)
+4. Download — rigging includes walking+running free. Only use meshy_animate for custom animations.
+
+## Scenario E: AR / Apple
+Trigger: user mentions AR, USDZ, Vision Pro, Quick Look.
+Suggested flow:
+1. Generate model with target_formats:["usdz"]
+2. Add textures (refine or retexture)
+3. Remesh for USDZ format conversion (meshy_remesh, target_formats:["usdz"])
+4. Download USDZ
+
+## Scenario F: Retexture
+Trigger: user wants to change textures/style of existing model.
+Suggested flow:
+1. Ask user for text_style_prompt OR image_style_url (one required, image takes precedence)
+2. Apply retexture (meshy_retexture)
+
+## Scenario G: General 3D Model (default)
+Trigger: none of the above.
+Suggested flow:
+1. Ask user about intended use to determine format
+2. Generate model
+3. Ask: add textures (refine)?
+4. Download in chosen format
+`;