@meshy-ai/meshy-mcp-server 0.2.0

package/dist/schemas/tasks.js

@@ -0,0 +1,85 @@
+/**
+ * Zod schemas for task management tools
+ */
+import { z } from "zod";
+import { TaskStatus, TaskPhase, TaskType, POLL_MAX_TIMEOUT } from "../constants.js";
+import { ResponseFormatSchema, PaginationSchema, TaskIdSchema, TaskTypeSchema } from "./common.js";
+/**
+ * Get task status input schema (also supports wait mode)
+ */
+export const GetTaskStatusInputSchema = z.object({
+    task_id: TaskIdSchema,
+    task_type: TaskTypeSchema,
+    wait: z.boolean()
+        .default(true)
+        .describe("If true (default), auto-poll until task completes. If false, return current status immediately."),
+    timeout_seconds: z.number()
+        .int()
+        .min(10, "Timeout must be at least 10 seconds")
+        .max(POLL_MAX_TIMEOUT / 1000, `Timeout cannot exceed ${POLL_MAX_TIMEOUT / 1000} seconds`)
+        .default(300)
+        .describe("Maximum wait time in seconds when wait=true (default: 300, max: 300)"),
+    response_format: ResponseFormatSchema
+}).strict();
+/**
+ * List tasks input schema
+ */
+export const ListTasksInputSchema = z.object({
+    task_type: z.nativeEnum(TaskType)
+        .optional()
+        .describe("Filter by task type. If omitted, queries ALL task types (text-to-3d, image-to-3d, multi-image-to-3d, remesh, retexture, text-to-image, image-to-image) and merges results. Note: rigging and animation do not have list endpoints."),
+    sort_by: z.enum(["+created_at", "-created_at"])
+        .default("-created_at")
+        .describe("Sort order by creation time. '-created_at' = newest first (default), '+created_at' = oldest first"),
+    status: z.nativeEnum(TaskStatus)
+        .optional()
+        .describe("Filter by task status"),
+    phase: z.nativeEnum(TaskPhase)
+        .optional()
+        .describe("Filter by task phase"),
+    response_format: ResponseFormatSchema
+}).merge(PaginationSchema).strict();
+/**
+ * Cancel task input schema
+ */
+export const CancelTaskInputSchema = z.object({
+    task_id: TaskIdSchema,
+    task_type: TaskTypeSchema
+}).strict();
+/**
+ * Download model input schema
+ */
+export const DownloadModelInputSchema = z.object({
+    task_id: TaskIdSchema,
+    task_type: TaskTypeSchema,
+    format: z.enum(["glb", "fbx", "usdz", "stl", "obj", "3mf"])
+        .default("glb")
+        .describe("Model format to download. IMPORTANT: Ask the user which format they need before downloading. Recommendations: GLB (general viewing), OBJ (white model printing), 3MF (multicolor printing), FBX (game engines/animation), USDZ (AR/Apple). Do NOT download all formats."),
+    include_textures: z.boolean()
+        .default(true)
+        .describe("Include texture files in response"),
+    save_to: z.string()
+        .optional()
+        .describe("Override auto-save path with a custom ABSOLUTE path. If omitted, auto-saves to meshy_output/{timestamp}_{prompt}_{id}/. Example: /Users/me/models/chair.glb"),
+    parent_task_id: z.string()
+        .optional()
+        .describe("Parent task ID for chaining (e.g., preview_task_id for refine, input_task_id for rig). Places output in the same project folder as the parent."),
+    print_ready: z.boolean()
+        .optional()
+        .describe("If true and format is OBJ, auto-fix coordinates for 3D printing: rotates Y-up to Z-up, scales to target height, centers on XY, aligns bottom to Z=0. Default false."),
+    print_height_mm: z.number()
+        .optional()
+        .describe("Target height in mm when print_ready is true. Default 75. Adjust per user request (e.g. 'print at 15cm' → 150).")
+}).strict();
+/**
+ * List models input schema
+ */
+export const ListModelsInputSchema = z.object({
+    workspace_id: z.string()
+        .optional()
+        .describe("Workspace ID (uses default if omitted)"),
+    filter: z.enum(["all", "published", "private"])
+        .default("all")
+        .describe("Filter models by visibility"),
+    response_format: ResponseFormatSchema
+}).merge(PaginationSchema).strict();

package/dist/services/error-handler.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Centralized error handling for Meshy API
+ */
+export interface MeshyError {
+    code: string;
+    message: string;
+    status?: number;
+}
+/**
+ * Optional context for richer error messages
+ */
+export interface ErrorContext {
+    tool?: string;
+    taskId?: string;
+}
+/**
+ * Handle Meshy API errors and convert to user-friendly messages.
+ * When context is provided, appends tool-specific recovery suggestions.
+ */
+export declare function handleMeshyError(error: unknown, context?: ErrorContext): string;
+/**
+ * Check if error is a rate limit error
+ */
+export declare function isRateLimitError(error: unknown): boolean;
+/**
+ * Check if error is a network error that should be retried
+ */
+export declare function isRetryableError(error: unknown): boolean;
+/**
+ * Extract error message from various error formats
+ */
+export declare function extractErrorMessage(error: unknown): string;

package/dist/services/error-handler.js

@@ -0,0 +1,141 @@
+/**
+ * Centralized error handling for Meshy API
+ */
+import { AxiosError } from "axios";
+import { ErrorCode } from "../constants.js";
+/**
+ * Handle Meshy API errors and convert to user-friendly messages.
+ * When context is provided, appends tool-specific recovery suggestions.
+ */
+export function handleMeshyError(error, context) {
+    // Handle Axios errors
+    if (error instanceof AxiosError) {
+        if (error.response) {
+            const status = error.response.status;
+            const errorData = error.response.data;
+            const errorCode = errorData?.error_code || errorData?.code;
+            // Map specific error codes
+            switch (errorCode) {
+                case ErrorCode.INSUFFICIENT_CREDITS:
+                    return "Error: Insufficient credits. Use `meshy_check_balance` to check your balance. Upgrade at https://meshy.ai/pricing";
+                case ErrorCode.TOO_MANY_PENDING_TASKS:
+                    return "Error: Too many pending tasks. Please wait for current tasks to complete or cancel some tasks.";
+                case ErrorCode.INVALID_MODEL_NOT_SUPPORTED:
+                    return "Error: Model format not supported. Supported formats: GLB, FBX, USDZ, 3MF";
+                case ErrorCode.INVALID_MODEL_INVALID_FORMAT:
+                    return "Error: Model file is corrupted or invalid. Please try generating again.";
+                case ErrorCode.LIMIT_EXCEEDED:
+                    return "Error: Rate limit exceeded. Please wait a moment before making more requests.";
+                case ErrorCode.FORBIDDEN:
+                    return "Error: Permission denied. Please check your API key has the required permissions.";
+                case ErrorCode.NOT_FOUND:
+                    return "Error: Resource not found. Please verify the task ID is correct.";
+                case ErrorCode.INTERNAL_ERROR:
+                    return "Error: Meshy service error. Please try again later.";
+            }
+            // Handle HTTP status codes
+            switch (status) {
+                case 400:
+                    return `Error: Invalid request. ${errorData?.message || "Please check your parameters."}`;
+                case 401:
+                    return "Error: Authentication failed. Please check your MESHY_API_KEY is valid.";
+                case 403:
+                    return "Error: Permission denied. Your API key may not have access to this resource.";
+                case 404:
+                    return "Error: Resource not found. Please check the ID is correct.";
+                case 429:
+                    return "Error: Rate limit exceeded. Please wait before making more requests.";
+                case 500:
+                case 502:
+                case 503:
+                    return "Error: Meshy service is temporarily unavailable. Please try again later.";
+                default:
+                    return `Error: API request failed with status ${status}. ${errorData?.message || ""}`;
+            }
+        }
+        // Handle network errors
+        if (error.code === "ECONNABORTED") {
+            return "Error: Request timed out. Please check your network connection and try again.";
+        }
+        if (error.code === "ENOTFOUND") {
+            return "Error: Cannot reach Meshy API. Please check your internet connection.";
+        }
+        if (error.code === "ECONNREFUSED") {
+            return "Error: Meshy API is unavailable. Please try again later.";
+        }
+        return `Error: Network error occurred. ${error.message}`;
+    }
+    // Handle generic errors
+    let baseMessage;
+    if (error instanceof Error) {
+        baseMessage = `Error: ${error.message}`;
+    }
+    else {
+        baseMessage = `Error: An unexpected error occurred. ${String(error)}`;
+    }
+    // Append context-aware suggestions if context is provided
+    return appendContextSuggestions(baseMessage, error, context);
+}
+/**
+ * Append context-specific recovery suggestions to error messages
+ */
+function appendContextSuggestions(message, error, context) {
+    if (!context?.tool)
+        return message;
+    const errorText = message.toLowerCase();
+    const tool = context.tool;
+    // Rig + face limit
+    if (tool === "meshy_rig" && (errorText.includes("face") || errorText.includes("300,000") || errorText.includes("300000") || errorText.includes("limit"))) {
+        return message + `\n\n**Fix**: The model exceeds the 300K face limit for rigging. Call \`meshy_remesh\` with target_polycount 100000 first, then rig the remeshed output.`;
+    }
+    // Image-to-3D + image errors
+    if ((tool === "meshy_image_to_3d" || tool === "meshy_multi_image_to_3d") && (errorText.includes("image") || errorText.includes("url"))) {
+        return message + `\n\n**Fix**: For local images, use \`file_path\` parameter (absolute path like "/Users/me/photo.jpg"). The server handles encoding automatically. Do NOT manually base64-encode.`;
+    }
+    // Multi-color + missing texture
+    if (tool === "meshy_process_multicolor" && (errorText.includes("texture") || errorText.includes("input") || errorText.includes("task"))) {
+        return message + `\n\n**Fix**: The input model must have textures. Run \`meshy_text_to_3d_refine\` or \`meshy_retexture\` first to add textures, then use the resulting task ID as input_task_id.`;
+    }
+    // Insufficient credits
+    if (errorText.includes("insufficient") || errorText.includes("credit")) {
+        return message + `\n\n**Fix**: Check your credit balance at https://meshy.ai/pricing. Current tool: ${tool}.`;
+    }
+    return message;
+}
+/**
+ * Check if error is a rate limit error
+ */
+export function isRateLimitError(error) {
+    if (error instanceof AxiosError) {
+        return error.response?.status === 429;
+    }
+    return false;
+}
+/**
+ * Check if error is a network error that should be retried
+ */
+export function isRetryableError(error) {
+    if (error instanceof AxiosError) {
+        // Retry on network errors
+        if (!error.response) {
+            return true;
+        }
+        // Retry on 5xx server errors
+        const status = error.response.status;
+        return status >= 500 && status < 600;
+    }
+    return false;
+}
+/**
+ * Extract error message from various error formats
+ */
+export function extractErrorMessage(error) {
+    if (error instanceof AxiosError && error.response?.data) {
+        const data = error.response.data;
+        return data.message || data.error || data.error_message || "Unknown error";
+    }
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}

package/dist/services/file-utils.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Utility for reading local image files and converting to base64 data URIs.
+ * Used by image-to-3d, multi-image-to-3d, and image-to-image tools
+ * so agents don't need to pass huge base64 strings through MCP arguments.
+ */
+/**
+ * Read a local image file and return a base64 data URI.
+ * Throws descriptive errors for missing files, unsupported formats, or oversized files.
+ */
+export declare function fileToDataUri(filePath: string): Promise<string>;
+/**
+ * Resolve an image source: if file_path is provided, convert to data URI;
+ * otherwise return image_url as-is.
+ */
+export declare function resolveImageSource(image_url?: string, file_path?: string): Promise<string>;

package/dist/services/file-utils.js

@@ -0,0 +1,55 @@
+/**
+ * Utility for reading local image files and converting to base64 data URIs.
+ * Used by image-to-3d, multi-image-to-3d, and image-to-image tools
+ * so agents don't need to pass huge base64 strings through MCP arguments.
+ */
+import { readFile } from "fs/promises";
+import { extname } from "path";
+const MIME_TYPES = {
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+    ".webp": "image/webp",
+};
+const MAX_FILE_SIZE = 20 * 1024 * 1024; // 20MB
+/**
+ * Read a local image file and return a base64 data URI.
+ * Throws descriptive errors for missing files, unsupported formats, or oversized files.
+ */
+export async function fileToDataUri(filePath) {
+    const ext = extname(filePath).toLowerCase();
+    const mime = MIME_TYPES[ext];
+    if (!mime) {
+        throw new Error(`Unsupported image format "${ext}". Supported: ${Object.keys(MIME_TYPES).join(", ")}`);
+    }
+    let buffer;
+    try {
+        buffer = await readFile(filePath);
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            throw new Error(`File not found: ${filePath}`);
+        }
+        throw new Error(`Failed to read file ${filePath}: ${err.message}`);
+    }
+    if (buffer.length > MAX_FILE_SIZE) {
+        const sizeMB = (buffer.length / (1024 * 1024)).toFixed(1);
+        throw new Error(`File too large (${sizeMB} MB). Maximum is ${MAX_FILE_SIZE / (1024 * 1024)} MB.`);
+    }
+    const base64 = buffer.toString("base64");
+    return `data:${mime};base64,${base64}`;
+}
+/**
+ * Resolve an image source: if file_path is provided, convert to data URI;
+ * otherwise return image_url as-is.
+ */
+export async function resolveImageSource(image_url, file_path) {
+    if (file_path) {
+        return fileToDataUri(file_path);
+    }
+    if (image_url) {
+        return image_url;
+    }
+    throw new Error("Either image_url or file_path must be provided. " +
+        "Use file_path for local files, image_url for public URLs.");
+}

package/dist/services/meshy-client.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Meshy API client with authentication and error handling
+ */
+import { GetTaskResponse } from "../types.js";
+export declare class MeshyClient {
+    private client;
+    private apiKey;
+    constructor(apiKey: string);
+    /**
+     * Make a GET request with retry logic
+     */
+    get<T>(endpoint: string, params?: Record<string, unknown>): Promise<T>;
+    /**
+     * Make a POST request with retry logic
+     */
+    post<T>(endpoint: string, data?: Record<string, unknown>): Promise<T>;
+    /**
+     * Make a DELETE request with retry logic
+     */
+    delete<T>(endpoint: string): Promise<T>;
+    /**
+     * Make a request with exponential backoff retry logic
+     */
+    private requestWithRetry;
+    /**
+     * Sleep for specified milliseconds
+     */
+    private sleep;
+    /**
+     * Validate API key by making a test request
+     */
+    validateApiKey(): Promise<boolean>;
+}
+/**
+ * Try to fetch a task by ID from all known API endpoints.
+ * Tries endpoints in priority order until one succeeds.
+ * Useful when the task type is unknown.
+ */
+export declare function fetchTaskByIdFromKnownEndpoints(client: MeshyClient, taskId: string): Promise<{
+    task: GetTaskResponse;
+    endpoint: string;
+} | null>;
+/**
+ * Fetch a task, trying the given endpoint first, then falling back to auto-inference.
+ * Returns the task data and the resolved endpoint.
+ */
+export declare function getTaskWithAutoInference(client: MeshyClient, taskId: string, preferredEndpoint: string): Promise<{
+    task: GetTaskResponse;
+    endpoint: string;
+}>;
+/**
+ * Create and validate Meshy client
+ */
+export declare function createMeshyClient(): Promise<MeshyClient>;

package/dist/services/meshy-client.js

@@ -0,0 +1,172 @@
+/**
+ * Meshy API client with authentication and error handling
+ */
+import axios from "axios";
+import { API_BASE_URL, API_TIMEOUT, RETRY_DELAYS, MAX_RETRIES } from "../constants.js";
+import { isRetryableError, isRateLimitError } from "./error-handler.js";
+export class MeshyClient {
+    client;
+    apiKey;
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+        this.client = axios.create({
+            baseURL: API_BASE_URL,
+            timeout: API_TIMEOUT,
+            headers: {
+                "Content-Type": "application/json",
+                "Accept": "application/json"
+            }
+        });
+        // Add request interceptor to inject auth token
+        this.client.interceptors.request.use((config) => {
+            config.headers.Authorization = `Bearer ${this.apiKey}`;
+            return config;
+        });
+    }
+    /**
+     * Make a GET request with retry logic
+     */
+    async get(endpoint, params) {
+        return this.requestWithRetry({
+            method: "GET",
+            url: endpoint,
+            params
+        });
+    }
+    /**
+     * Make a POST request with retry logic
+     */
+    async post(endpoint, data) {
+        return this.requestWithRetry({
+            method: "POST",
+            url: endpoint,
+            data
+        });
+    }
+    /**
+     * Make a DELETE request with retry logic
+     */
+    async delete(endpoint) {
+        return this.requestWithRetry({
+            method: "DELETE",
+            url: endpoint
+        });
+    }
+    /**
+     * Make a request with exponential backoff retry logic
+     */
+    async requestWithRetry(config, retryCount = 0) {
+        try {
+            const response = await this.client.request(config);
+            return response.data;
+        }
+        catch (error) {
+            // Check if we should retry
+            const shouldRetry = retryCount < MAX_RETRIES &&
+                (isRetryableError(error) || isRateLimitError(error));
+            if (shouldRetry) {
+                const delay = RETRY_DELAYS[retryCount] || RETRY_DELAYS[RETRY_DELAYS.length - 1];
+                // Log retry attempt to stderr (not stdout for stdio transport)
+                console.error(`Request failed, retrying in ${delay}ms (attempt ${retryCount + 1}/${MAX_RETRIES})...`);
+                await this.sleep(delay);
+                return this.requestWithRetry(config, retryCount + 1);
+            }
+            // No more retries, throw the error
+            throw error;
+        }
+    }
+    /**
+     * Sleep for specified milliseconds
+     */
+    sleep(ms) {
+        return new Promise(resolve => setTimeout(resolve, ms));
+    }
+    /**
+     * Validate API key by making a test request
+     */
+    async validateApiKey() {
+        try {
+            // Make a simple request to check if API key is valid
+            // Use the text-to-3d endpoint which returns a list of tasks
+            await this.get("/openapi/v2/text-to-3d");
+            return true;
+        }
+        catch (error) {
+            return false;
+        }
+    }
+}
+/**
+ * Try to fetch a task by ID from all known API endpoints.
+ * Tries endpoints in priority order until one succeeds.
+ * Useful when the task type is unknown.
+ */
+export async function fetchTaskByIdFromKnownEndpoints(client, taskId) {
+    const endpoints = [
+        "/openapi/v2/text-to-3d",
+        "/openapi/v1/image-to-3d",
+        "/openapi/v1/multi-image-to-3d",
+        "/openapi/v1/remesh",
+        "/openapi/v1/retexture",
+        "/openapi/v1/rigging",
+        "/openapi/v1/animations",
+        "/openapi/v1/text-to-image",
+        "/openapi/v1/image-to-image",
+        "/openapi/v1/print/multi-color"
+    ];
+    for (const endpoint of endpoints) {
+        try {
+            const task = await client.get(`${endpoint}/${taskId}`);
+            if (task && task.id) {
+                return { task, endpoint };
+            }
+        }
+        catch {
+            // Not found on this endpoint, try next
+            continue;
+        }
+    }
+    return null;
+}
+/**
+ * Fetch a task, trying the given endpoint first, then falling back to auto-inference.
+ * Returns the task data and the resolved endpoint.
+ */
+export async function getTaskWithAutoInference(client, taskId, preferredEndpoint) {
+    // Try preferred endpoint first
+    try {
+        const task = await client.get(`${preferredEndpoint}/${taskId}`);
+        if (task && task.id) {
+            return { task, endpoint: preferredEndpoint };
+        }
+    }
+    catch {
+        // Fall through to auto-inference
+    }
+    // Auto-infer from all endpoints
+    const result = await fetchTaskByIdFromKnownEndpoints(client, taskId);
+    if (result) {
+        return result;
+    }
+    throw new Error(`Task ${taskId} not found on any endpoint. Verify the task_id is correct.`);
+}
+/**
+ * Create and validate Meshy client
+ */
+export async function createMeshyClient() {
+    const apiKey = process.env.MESHY_API_KEY;
+    if (!apiKey) {
+        throw new Error("MESHY_API_KEY environment variable is required. " +
+            "Get your API key from https://www.meshy.ai/settings/api");
+    }
+    const client = new MeshyClient(apiKey);
+    // Validate API key on startup
+    console.error("Validating Meshy API key...");
+    const isValid = await client.validateApiKey();
+    if (!isValid) {
+        throw new Error("Invalid MESHY_API_KEY. Please check your API key is correct. " +
+            "Get your API key from https://www.meshy.ai/settings/api");
+    }
+    console.error("✓ Meshy API key validated successfully");
+    return client;
+}

package/dist/services/output-manager.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Output directory manager for Meshy generation tasks.
+ *
+ * Organizes all downloaded files under {cwd}/meshy_output/ with:
+ *   - Per-project folders: {YYYYMMDD_HHmmss}_{prompt_slug}_{task_id_prefix}/
+ *   - Auto-downloaded thumbnails
+ *   - Per-project metadata.json tracking task chains
+ *   - Global history.json index
+ */
+export interface TaskRecord {
+    task_id: string;
+    task_type: string;
+    stage: string;
+    prompt?: string;
+    status: string;
+    files: string[];
+    created_at: string;
+}
+/**
+ * Infer a human-readable stage name from task type and API response type field.
+ */
+export declare function inferStage(taskType: string, apiType?: string): string;
+/**
+ * Resolve (or create) the project directory for a task.
+ *
+ * For chained tasks (refine → preview, rig → source), pass parentTaskId
+ * to place the output in the same project folder as the parent.
+ */
+export declare function resolveProjectDir(taskId: string, taskType: string, prompt?: string, parentTaskId?: string, createdAt?: string | number): string;
+/**
+ * Generate the file path for a model download within a project directory.
+ * Returns: /path/to/project/stage.ext (e.g., preview.glb, refined.glb)
+ */
+export declare function getFilePath(projectDir: string, stage: string, format: string): string;
+/**
+ * Generate texture file path within a project directory.
+ * Returns: /path/to/project/stage_texType.ext (e.g., refined_base_color.png)
+ */
+export declare function getTextureFilePath(projectDir: string, stage: string, textureType: string, url: string): string;
+/**
+ * Record a completed task into the project's metadata.json.
+ */
+export declare function recordTask(projectDir: string, record: TaskRecord): void;
+/**
+ * Download and save thumbnail to the project directory.
+ * Silently skips on failure.
+ */
+export declare function saveThumbnail(projectDir: string, thumbnailUrl: string): Promise<string | null>;
+/**
+ * Get the output root path (for display purposes).
+ */
+export declare function getOutputRootPath(): string;