@meshy-ai/meshy-mcp-server 0.2.0

package/dist/tools/generation.js

@@ -0,0 +1,419 @@
+/**
+ * Generation tools (text-to-3d, image-to-3d)
+ */
+import { handleMeshyError } from "../services/error-handler.js";
+import { resolveImageSource, fileToDataUri } from "../services/file-utils.js";
+import { TextTo3DInputSchema, ImageTo3DInputSchema, TextTo3DRefineInputSchema, MultiImageTo3DInputSchema } from "../schemas/generation.js";
+import { TaskCreatedOutputSchema } from "../schemas/output.js";
+import { formatTaskCreatedResponse } from "../utils/response-formatter.js";
+/**
+ * Register generation tools with the MCP server
+ */
+export function registerGenerationTools(server, client) {
+    // Text-to-3D tool
+    server.registerTool("meshy_text_to_3d", {
+        title: "Generate 3D Model from Text",
+        description: `Generate a 3D model from a text description using Meshy AI.
+
+This tool creates a new 3D generation task and returns a task_id that can be used to poll the status. The generation process is asynchronous and typically takes 2-3 minutes.
+
+Args:
+  - prompt (string): Text description of the 3D model (2-600 characters)
+  - ai_model (enum): AI model - "meshy-5" (previous gen, 5 credits), "meshy-6" (best quality, 20 credits), "latest" (default, resolves to meshy-6). IMPORTANT: Ask the user which model to use before proceeding
+  - model_type (enum, optional): "standard" (default) or "lowpoly". When "lowpoly", ai_model/topology/target_polycount/should_remesh are ignored
+  - topology (enum, optional): Mesh topology - "quad" or "triangle"
+  - target_polycount (number, optional): Target polygon count (100–300,000)
+  - symmetry_mode (enum, optional): "off", "auto" (default), or "on"
+  - should_remesh (boolean, optional): Whether to remesh. Default false for meshy-6, true for others
+  - pose_mode (enum, optional): "a-pose" or "t-pose". IMPORTANT: Use "t-pose" when the user intends to rig or animate the model
+  - target_formats (string[], optional): Output formats. Default: all except 3mf. For 3D printing white model, pass ["obj"].
+  - auto_size (boolean, optional): AI auto-estimate real-world height. Default false.
+  - origin_at (enum, optional): "bottom" or "center". Default "bottom" when auto_size is true.
+  - response_format (enum): Output format - "markdown" or "json" (default: "markdown")
+
+Workflow: This creates a PREVIEW (untextured mesh). After completion, ask the user if they want to add textures via meshy_text_to_3d_refine. Preview and refine ai_model should match — all models (meshy-5, meshy-6, latest) support both preview and refine.
+
+For 3D printing: pass target_formats: ["obj"] to only generate OBJ format (faster).
+For rigging/animation: use pose_mode: "t-pose" for best results.
+
+Returns:
+  { "task_id": "abc-123-def", "status": "PENDING", "estimated_time": "2-3 minutes" }
+
+Next Steps:
+  Use meshy_get_task_status with the task_id to wait for completion.
+
+Examples:
+  - "Create a low-poly dragon" → { prompt: "dragon", model_type: "lowpoly" }
+  - "Generate for 3D print" → { prompt: "cat", target_formats: ["obj"] }
+  - "Character for animation" → { prompt: "warrior", pose_mode: "t-pose" }`,
+        inputSchema: TextTo3DInputSchema,
+        outputSchema: TaskCreatedOutputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true
+        }
+    }, async (params) => {
+        try {
+            // Prepare API request - flat structure matching Meshy API
+            const request = {
+                mode: "preview",
+                prompt: params.prompt,
+                ai_model: params.ai_model,
+                moderation: false
+            };
+            if (params.model_type) {
+                request.model_type = params.model_type;
+            }
+            if (params.target_polycount) {
+                request.target_polycount = params.target_polycount;
+            }
+            if (params.topology) {
+                request.topology = params.topology;
+            }
+            if (params.symmetry_mode) {
+                request.symmetry_mode = params.symmetry_mode;
+            }
+            if (params.should_remesh !== undefined) {
+                request.should_remesh = params.should_remesh;
+            }
+            if (params.pose_mode) {
+                request.pose_mode = params.pose_mode;
+            }
+            if (params.target_formats) {
+                request.target_formats = params.target_formats;
+            }
+            if (params.auto_size !== undefined)
+                request.auto_size = params.auto_size;
+            if (params.origin_at)
+                request.origin_at = params.origin_at;
+            // Create task via API
+            const response = await client.post("/openapi/v2/text-to-3d", request);
+            // API returns { "result": "task-id" }
+            const taskId = response.result;
+            const output = {
+                task_id: taskId,
+                status: "PENDING",
+                message: `3D generation task created successfully. Task ID: ${taskId}`,
+                estimated_time: "2-3 minutes"
+            };
+            return formatTaskCreatedResponse(output, params.response_format, "3D Generation Task Created", `Your 3D model is being generated from the prompt: "${params.prompt}"`);
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [{
+                        type: "text",
+                        text: handleMeshyError(error)
+                    }]
+            };
+        }
+    });
+    // Image-to-3D tool
+    server.registerTool("meshy_image_to_3d", {
+        title: "Generate 3D Model from Image",
+        description: `Generate a 3D model from a single image using Meshy AI.
+
+This tool creates a new 3D generation task from an image and returns a task_id.
+
+IMAGE INPUT (provide ONE, NEVER both):
+  - Local file → file_path: "/absolute/path/to/image.jpg" (RECOMMENDED)
+  - Remote URL → image_url: "https://example.com/image.jpg"
+  - NEVER manually base64-encode. NEVER use both file_path and image_url.
+
+Other Args:
+  - ai_model: "meshy-5", "meshy-6", or "latest" (default). Ask user which model before proceeding
+  - model_type, pose_mode, topology, target_polycount, should_remesh, symmetry_mode
+  - should_texture: Whether to generate textures (default true). Set false for untextured mesh
+  - enable_pbr: PBR maps (default false). Set true for metallic/roughness/normal maps
+  - texture_prompt, texture_image_url: Guide texturing
+  - image_enhancement: Optimize input image (default true, meshy-6/latest only)
+  - remove_lighting: Remove highlights/shadows from base color texture (default true, meshy-6/latest only)
+  - save_pre_remeshed_model, response_format
+
+Note: Image-to-3D does NOT have a separate refine step. Texturing is controlled by should_texture (default true).
+
+Examples:
+  - Local file: { file_path: "/path/to/cat.jpg" }
+  - Public URL: { image_url: "https://example.com/cat.jpg" }
+  - With pose: { file_path: "/path/to/character.png", pose_mode: "a-pose" }
+
+Error Handling:
+  - Returns "InvalidImageUrl" if image is not accessible
+  - Returns "File not found" if file_path doesn't exist`,
+        inputSchema: ImageTo3DInputSchema,
+        outputSchema: TaskCreatedOutputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true
+        }
+    }, async (params) => {
+        try {
+            const imageUrl = await resolveImageSource(params.image_url, params.file_path);
+            const request = {
+                image_url: imageUrl,
+                enable_pbr: params.enable_pbr,
+                moderation: false
+            };
+            if (params.ai_model) {
+                request.ai_model = params.ai_model;
+            }
+            if (params.model_type) {
+                request.model_type = params.model_type;
+            }
+            if (params.pose_mode) {
+                request.pose_mode = params.pose_mode;
+            }
+            if (params.topology) {
+                request.topology = params.topology;
+            }
+            if (params.target_polycount) {
+                request.target_polycount = params.target_polycount;
+            }
+            if (params.should_remesh !== undefined) {
+                request.should_remesh = params.should_remesh;
+            }
+            if (params.symmetry_mode) {
+                request.symmetry_mode = params.symmetry_mode;
+            }
+            if (params.should_texture !== undefined) {
+                request.should_texture = params.should_texture;
+            }
+            if (params.texture_prompt) {
+                request.texture_prompt = params.texture_prompt;
+            }
+            if (params.texture_image_url) {
+                request.texture_image_url = params.texture_image_url;
+            }
+            if (params.image_enhancement !== undefined) {
+                request.image_enhancement = params.image_enhancement;
+            }
+            if (params.remove_lighting !== undefined) {
+                request.remove_lighting = params.remove_lighting;
+            }
+            if (params.save_pre_remeshed_model !== undefined) {
+                request.save_pre_remeshed_model = params.save_pre_remeshed_model;
+            }
+            if (params.target_formats) {
+                request.target_formats = params.target_formats;
+            }
+            if (params.auto_size !== undefined)
+                request.auto_size = params.auto_size;
+            if (params.origin_at)
+                request.origin_at = params.origin_at;
+            // Create task via API (image-to-3d uses v1, not v2)
+            const response = await client.post("/openapi/v1/image-to-3d", request);
+            // API returns { "result": "task-id" }
+            const taskId = response.result;
+            const output = {
+                task_id: taskId,
+                status: "PENDING",
+                message: `3D generation task created successfully. Task ID: ${taskId}`,
+                estimated_time: "2-3 minutes"
+            };
+            return formatTaskCreatedResponse(output, params.response_format, "3D Generation Task Created (Image-to-3D)", "Your 3D model is being generated from the provided image.", "image-to-3d");
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [{
+                        type: "text",
+                        text: handleMeshyError(error, { tool: "meshy_image_to_3d" })
+                    }]
+            };
+        }
+    });
+    // Text-to-3D Refine tool
+    server.registerTool("meshy_text_to_3d_refine", {
+        title: "Refine Text-to-3D Preview",
+        description: `Apply textures to a completed text-to-3D preview mesh using Meshy AI.
+
+This tool takes a completed preview task and generates a fully textured model. Run meshy_text_to_3d first to get a preview, then use this tool to add high-quality textures.
+
+Args:
+  - preview_task_id (string): Task ID of the completed preview task to refine (required)
+  - enable_pbr (boolean): Enable physically-based rendering textures (default: false)
+  - texture_prompt (string, optional): Text to guide texturing. Max 600 characters
+  - texture_image_url (string, optional): Image URL to guide texturing
+  - ai_model (enum): AI model - "meshy-5", "meshy-6", or "latest" (default). Should match the preview's ai_model to avoid model mismatch errors.
+  - remove_lighting (boolean, optional): Remove highlights/shadows from base color texture. Default true. Only meshy-6/latest
+  - target_formats (string[], optional): Output formats. Default: all except 3mf.
+  - auto_size (boolean, optional): AI auto-estimate real-world height. Default false.
+  - origin_at (enum, optional): "bottom" or "center".
+  - response_format (enum): Output format - "markdown" or "json" (default: "markdown")
+
+IMPORTANT: The ai_model used for refine should match the preview's ai_model. All models (meshy-5, meshy-6, latest) support refine.
+
+Returns:
+  { "task_id": "abc-123-def", "status": "PENDING", "estimated_time": "2-3 minutes" }
+
+Next Steps:
+  Use meshy_get_task_status with task_id and task_type="text-to-3d" to check progress.
+
+Examples:
+  - Basic refine: { preview_task_id: "abc-123" }
+  - With PBR: { preview_task_id: "abc-123", enable_pbr: true }
+  - Guided texture: { preview_task_id: "abc-123", texture_prompt: "rusty metal" }`,
+        inputSchema: TextTo3DRefineInputSchema,
+        outputSchema: TaskCreatedOutputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true
+        }
+    }, async (params) => {
+        try {
+            const request = {
+                mode: "refine",
+                preview_task_id: params.preview_task_id,
+                enable_pbr: params.enable_pbr,
+                ai_model: params.ai_model
+            };
+            if (params.texture_prompt) {
+                request.texture_prompt = params.texture_prompt;
+            }
+            if (params.texture_image_url) {
+                request.texture_image_url = params.texture_image_url;
+            }
+            if (params.remove_lighting !== undefined) {
+                request.remove_lighting = params.remove_lighting;
+            }
+            if (params.target_formats) {
+                request.target_formats = params.target_formats;
+            }
+            if (params.auto_size !== undefined)
+                request.auto_size = params.auto_size;
+            if (params.origin_at)
+                request.origin_at = params.origin_at;
+            const response = await client.post("/openapi/v2/text-to-3d", request);
+            const taskId = response.result;
+            const output = {
+                task_id: taskId,
+                status: "PENDING",
+                message: `Text-to-3D refine task created successfully. Task ID: ${taskId}`,
+                estimated_time: "2-3 minutes"
+            };
+            return formatTaskCreatedResponse(output, params.response_format, "Text-to-3D Refine Task Created", `Texturing the preview model from task "${params.preview_task_id}".`);
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [{
+                        type: "text",
+                        text: handleMeshyError(error)
+                    }]
+            };
+        }
+    });
+    // Multi-image-to-3D tool
+    server.registerTool("meshy_multi_image_to_3d", {
+        title: "Generate 3D Model from Multiple Images",
+        description: `Generate a 3D model from 1–4 images using Meshy AI.
+
+Use multiple views of the same object for better 3D reconstruction.
+
+Image Input (provide ONE of these):
+  - image_urls (array): 1–4 publicly accessible image URLs
+  - file_paths (array): 1–4 absolute paths to LOCAL image files. Server reads and encodes them automatically.
+
+IMPORTANT: For local files, always use file_paths instead of manually base64-encoding.
+
+Other Args:
+  - ai_model: "meshy-5", "meshy-6", or "latest" (default). Ask user which model before proceeding
+  - model_type, pose_mode, topology, target_polycount, should_remesh, symmetry_mode
+  - should_texture: Whether to generate textures (default true)
+  - enable_pbr: PBR maps (default false)
+  - texture_prompt, texture_image_url: Guide texturing
+  - image_enhancement: Optimize input images (default true, meshy-6/latest only)
+  - remove_lighting: Remove highlights/shadows from base color texture (default true, meshy-6/latest only)
+  - save_pre_remeshed_model, response_format
+
+Examples:
+  - Local files: { file_paths: ["/path/front.jpg", "/path/side.jpg"] }
+  - Public URLs: { image_urls: ["https://example.com/front.jpg", "https://example.com/side.jpg"] }
+
+Error Handling:
+  - Returns "InvalidImageUrl" if any image is not accessible
+  - Returns "File not found" if any file_path doesn't exist`,
+        inputSchema: MultiImageTo3DInputSchema,
+        outputSchema: TaskCreatedOutputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true
+        }
+    }, async (params) => {
+        try {
+            let resolvedUrls;
+            if (params.file_paths && params.file_paths.length > 0) {
+                resolvedUrls = await Promise.all(params.file_paths.map(fp => fileToDataUri(fp)));
+            }
+            else if (params.image_urls && params.image_urls.length > 0) {
+                resolvedUrls = params.image_urls;
+            }
+            else {
+                throw new Error("Either image_urls or file_paths must be provided.");
+            }
+            const request = {
+                image_urls: resolvedUrls,
+                enable_pbr: params.enable_pbr,
+                moderation: false
+            };
+            if (params.ai_model)
+                request.ai_model = params.ai_model;
+            if (params.model_type)
+                request.model_type = params.model_type;
+            if (params.pose_mode)
+                request.pose_mode = params.pose_mode;
+            if (params.topology)
+                request.topology = params.topology;
+            if (params.target_polycount)
+                request.target_polycount = params.target_polycount;
+            if (params.should_remesh !== undefined)
+                request.should_remesh = params.should_remesh;
+            if (params.symmetry_mode)
+                request.symmetry_mode = params.symmetry_mode;
+            if (params.should_texture !== undefined)
+                request.should_texture = params.should_texture;
+            if (params.texture_prompt)
+                request.texture_prompt = params.texture_prompt;
+            if (params.texture_image_url)
+                request.texture_image_url = params.texture_image_url;
+            if (params.image_enhancement !== undefined)
+                request.image_enhancement = params.image_enhancement;
+            if (params.remove_lighting !== undefined)
+                request.remove_lighting = params.remove_lighting;
+            if (params.save_pre_remeshed_model !== undefined)
+                request.save_pre_remeshed_model = params.save_pre_remeshed_model;
+            if (params.target_formats)
+                request.target_formats = params.target_formats;
+            if (params.auto_size !== undefined)
+                request.auto_size = params.auto_size;
+            if (params.origin_at)
+                request.origin_at = params.origin_at;
+            const response = await client.post("/openapi/v1/multi-image-to-3d", request);
+            const taskId = response.result;
+            const output = {
+                task_id: taskId,
+                status: "PENDING",
+                message: `Multi-image 3D generation task created successfully. Task ID: ${taskId}`,
+                estimated_time: "2-3 minutes"
+            };
+            return formatTaskCreatedResponse(output, params.response_format, "3D Generation Task Created (Multi-Image-to-3D)", `Your 3D model is being generated from ${resolvedUrls.length} image(s).`, "multi-image-to-3d");
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [{
+                        type: "text",
+                        text: handleMeshyError(error, { tool: "meshy_multi_image_to_3d" })
+                    }]
+            };
+        }
+    });
+}

package/dist/tools/image.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Image generation tools (text-to-image, image-to-image)
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { MeshyClient } from "../services/meshy-client.js";
+/**
+ * Register image generation tools with the MCP server
+ */
+export declare function registerImageTools(server: McpServer, client: MeshyClient): void;

package/dist/tools/image.js

@@ -0,0 +1,154 @@
+/**
+ * Image generation tools (text-to-image, image-to-image)
+ */
+import { handleMeshyError } from "../services/error-handler.js";
+import { fileToDataUri } from "../services/file-utils.js";
+import { TextToImageInputSchema, ImageToImageInputSchema } from "../schemas/image.js";
+import { TaskCreatedOutputSchema } from "../schemas/output.js";
+import { formatTaskCreatedResponse } from "../utils/response-formatter.js";
+/**
+ * Register image generation tools with the MCP server
+ */
+export function registerImageTools(server, client) {
+    // Text-to-image tool
+    server.registerTool("meshy_text_to_image", {
+        title: "Generate 2D Image from Text",
+        description: `Generate a 2D image from a text description using Meshy AI.
+
+Useful for creating reference images that can then be used with image-to-3d or image-to-image.
+
+Args:
+  - ai_model (enum): AI model to use - "nano-banana" or "nano-banana-pro" (required)
+  - prompt (string): Text description of the image to generate (2-600 characters, required)
+  - generate_multi_view (boolean, optional): Generate multiple viewpoint images (default: false)
+  - pose_mode (enum, optional): Pose for character images - "a-pose" or "t-pose"
+  - aspect_ratio (enum, optional): Image aspect ratio (default: "1:1"). Options: "1:1", "16:9", "9:16", "4:3", "3:4"
+  - response_format (enum): Output format - "markdown" or "json" (default: "markdown")
+
+Returns:
+  {
+    "task_id": "abc-123-def",
+    "status": "PENDING",
+    "message": "Image generation task created...",
+    "estimated_time": "1-2 minutes"
+  }
+
+Next Steps:
+  Use meshy_get_task_status with task_id and task_type="text-to-image" to check progress.
+
+Examples:
+  - Basic image: { ai_model: "nano-banana", prompt: "a cute cartoon cat" }
+  - Widescreen: { ai_model: "nano-banana-pro", prompt: "fantasy landscape", aspect_ratio: "16:9" }
+  - Multi-view character: { ai_model: "nano-banana-pro", prompt: "game character", generate_multi_view: true }
+
+Error Handling:
+  - Returns "InsufficientCredits" if account needs upgrade`,
+        inputSchema: TextToImageInputSchema,
+        outputSchema: TaskCreatedOutputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true
+        }
+    }, async (params) => {
+        try {
+            const request = {
+                ai_model: params.ai_model,
+                prompt: params.prompt,
+                generate_multi_view: params.generate_multi_view,
+                aspect_ratio: params.aspect_ratio
+            };
+            if (params.pose_mode)
+                request.pose_mode = params.pose_mode;
+            const response = await client.post("/openapi/v1/text-to-image", request);
+            const taskId = response.result;
+            const output = {
+                task_id: taskId,
+                status: "PENDING",
+                message: `Text-to-image task created successfully. Task ID: ${taskId}`,
+                estimated_time: "1-2 minutes"
+            };
+            return formatTaskCreatedResponse(output, params.response_format, "Image Generation Task Created", `Generating image from prompt: "${params.prompt}"`, "text-to-image");
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [{
+                        type: "text",
+                        text: handleMeshyError(error)
+                    }]
+            };
+        }
+    });
+    // Image-to-image tool
+    server.registerTool("meshy_image_to_image", {
+        title: "Transform Image using AI",
+        description: `Transform images using AI with a text prompt and reference images using Meshy AI.
+
+Reference Image Input (provide ONE of these):
+  - reference_image_urls (array): 1–5 publicly accessible reference image URLs
+  - reference_file_paths (array): 1–5 absolute paths to LOCAL image files. Server reads and encodes them automatically.
+
+IMPORTANT: For local files, always use reference_file_paths instead of manually base64-encoding.
+
+Other Args:
+  - ai_model (enum): "nano-banana" or "nano-banana-pro" (required)
+  - prompt (string): Text description guiding the transformation (required)
+  - generate_multi_view (boolean, optional): Generate multiple viewpoint images (default: false)
+  - response_format (enum): Output format (default: "markdown")
+
+Examples:
+  - Local file: { ai_model: "nano-banana", prompt: "make it a robot", reference_file_paths: ["/path/to/image.jpg"] }
+  - Public URL: { ai_model: "nano-banana", prompt: "make it a robot", reference_image_urls: ["https://..."] }
+
+Error Handling:
+  - Returns "InvalidImageUrl" if any reference image is not accessible
+  - Returns "File not found" if any file_path doesn't exist`,
+        inputSchema: ImageToImageInputSchema,
+        outputSchema: TaskCreatedOutputSchema,
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: false,
+            openWorldHint: true
+        }
+    }, async (params) => {
+        try {
+            let resolvedUrls;
+            if (params.reference_file_paths && params.reference_file_paths.length > 0) {
+                resolvedUrls = await Promise.all(params.reference_file_paths.map(fp => fileToDataUri(fp)));
+            }
+            else if (params.reference_image_urls && params.reference_image_urls.length > 0) {
+                resolvedUrls = params.reference_image_urls;
+            }
+            else {
+                throw new Error("Either reference_image_urls or reference_file_paths must be provided.");
+            }
+            const request = {
+                ai_model: params.ai_model,
+                prompt: params.prompt,
+                reference_image_urls: resolvedUrls,
+                generate_multi_view: params.generate_multi_view
+            };
+            const response = await client.post("/openapi/v1/image-to-image", request);
+            const taskId = response.result;
+            const output = {
+                task_id: taskId,
+                status: "PENDING",
+                message: `Image-to-image task created successfully. Task ID: ${taskId}`,
+                estimated_time: "1-2 minutes"
+            };
+            return formatTaskCreatedResponse(output, params.response_format, "Image-to-Image Task Created", `Transforming ${resolvedUrls.length} reference image(s) with AI.`, "image-to-image");
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [{
+                        type: "text",
+                        text: handleMeshyError(error)
+                    }]
+            };
+        }
+    });
+}

package/dist/tools/postprocessing.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Post-processing tools (remesh, retexture, rig, animate)
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { MeshyClient } from "../services/meshy-client.js";
+/**
+ * Register post-processing tools with the MCP server
+ */
+export declare function registerPostProcessingTools(server: McpServer, client: MeshyClient): void;