@meshy-ai/meshy-mcp-server 0.2.0

package/dist/tools/workspace.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Workspace tools (list models)
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { MeshyClient } from "../services/meshy-client.js";
+/**
+ * Register workspace tools with the MCP server
+ */
+export declare function registerWorkspaceTools(server: McpServer, client: MeshyClient): void;

package/dist/tools/workspace.js

@@ -0,0 +1,161 @@
+/**
+ * Workspace tools (list models)
+ */
+import { handleMeshyError } from "../services/error-handler.js";
+import { ListModelsInputSchema } from "../schemas/tasks.js";
+import { ResponseFormat, TaskStatus, CHARACTER_LIMIT } from "../constants.js";
+/**
+ * Register workspace tools with the MCP server
+ */
+export function registerWorkspaceTools(server, client) {
+    // List models tool
+    server.registerTool("meshy_list_models", {
+        title: "List Workspace Models",
+        description: `Browse 3D models in your workspace with filtering and pagination.
+
+This tool lists all completed models in your workspace. Only shows models with status SUCCEEDED.
+
+Args:
+  - workspace_id (string, optional): Workspace ID (uses default workspace if omitted)
+  - filter (enum): Filter by visibility - "all", "published", or "private" (default: "all")
+  - limit (number): Results per page, 1-100 (default: 20)
+  - offset (number): Skip N results for pagination (default: 0)
+  - response_format (enum): Output format - "markdown" or "json" (default: "markdown")
+
+Returns:
+  {
+    "page_count": 20,
+    "offset": 0,
+    "models": [
+      {
+        "id": "abc-123",
+        "name": "Dragon model",
+        "thumbnail_url": "https://...",
+        "created_at": "2026-03-02T10:00:00Z",
+        "vertex_count": 45231,
+        "face_count": 89456,
+        "is_published": false
+      }
+    ],
+    "has_more": true,
+    "next_offset": 20
+  }
+
+Use Cases:
+  - Browse your generated models
+  - Find models by creation date
+  - Filter published vs private models
+
+Examples:
+  - List recent models: { limit: 10 }
+  - List published models: { filter: "published" }
+  - Get second page: { limit: 20, offset: 20 }
+
+Error Handling:
+  - Automatically truncates if response exceeds size limit`,
+        inputSchema: ListModelsInputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true
+        }
+    }, async (params) => {
+        try {
+            const pageSize = params.limit;
+            const pageNum = Math.floor(params.offset / pageSize) + 1;
+            const queryParams = {
+                status: TaskStatus.SUCCEEDED,
+                page_size: pageSize,
+                page_num: pageNum
+            };
+            // API returns Task[] directly
+            const response = await client.get("/openapi/v2/text-to-3d", queryParams);
+            const tasks = Array.isArray(response) ? response : [];
+            let filteredTasks = tasks;
+            if (params.filter === "published") {
+                filteredTasks = filteredTasks.filter(task => task.model_urls && task.is_published);
+            }
+            else if (params.filter === "private") {
+                filteredTasks = filteredTasks.filter(task => task.model_urls && !task.is_published);
+            }
+            const models = filteredTasks
+                .filter(task => task.model_urls)
+                .map(task => ({
+                id: task.id,
+                name: task.name || task.prompt || "Untitled Model",
+                thumbnail_url: task.thumbnail_url || "",
+                created_at: task.created_at,
+                vertex_count: task.vertex_count,
+                face_count: task.face_count,
+                is_published: task.is_published || false
+            }));
+            const output = {
+                page_count: models.length,
+                offset: params.offset,
+                models,
+                has_more: tasks.length >= pageSize,
+                next_offset: tasks.length >= pageSize
+                    ? params.offset + tasks.length
+                    : undefined
+            };
+            // Helper to render models as markdown
+            const renderModelsMarkdown = (modelList, totalCount, truncated = false) => {
+                const lines = [`# Workspace Models`, ""];
+                lines.push(`**Showing**: ${totalCount} models on this page (offset: ${output.offset})`);
+                if (truncated)
+                    lines.push(`*(truncated from ${models.length} results)*`);
+                lines.push("");
+                for (const model of modelList) {
+                    lines.push(`## ${model.name}`);
+                    lines.push(`- **ID**: ${model.id}`);
+                    lines.push(`- **Created**: ${new Date(model.created_at).toLocaleString()}`);
+                    if (model.vertex_count && model.face_count) {
+                        lines.push(`- **Geometry**: ${model.vertex_count.toLocaleString()} vertices, ${model.face_count.toLocaleString()} faces`);
+                    }
+                    lines.push(`- **Published**: ${model.is_published ? 'Yes' : 'No'}`);
+                    lines.push(`- **Thumbnail**: ${model.thumbnail_url}`);
+                    lines.push("");
+                }
+                if (output.has_more) {
+                    lines.push(`**More results available**. Use offset=${output.next_offset} to see next page.`);
+                }
+                return lines.join("\n");
+            };
+            let textContent;
+            if (params.response_format === ResponseFormat.MARKDOWN) {
+                textContent = renderModelsMarkdown(output.models, output.page_count);
+            }
+            else {
+                textContent = JSON.stringify(output, null, 2);
+            }
+            // Check character limit — re-render in same format with fewer models
+            if (textContent.length > CHARACTER_LIMIT) {
+                const truncatedModels = output.models.slice(0, Math.max(1, Math.floor(output.models.length / 2)));
+                output.models = truncatedModels;
+                output.page_count = truncatedModels.length;
+                if (params.response_format === ResponseFormat.MARKDOWN) {
+                    textContent = renderModelsMarkdown(truncatedModels, truncatedModels.length, true) +
+                        `\n\n[Response truncated. Use smaller limit to see more results.]`;
+                }
+                else {
+                    textContent = JSON.stringify(output, null, 2) +
+                        `\n\n[Response truncated. Use smaller limit to see more results.]`;
+                }
+            }
+            return {
+                content: [{ type: "text", text: textContent }],
+                structuredContent: output
+            };
+        }
+        catch (error) {
+            return {
+                isError: true,
+                content: [{
+                        type: "text",
+                        text: handleMeshyError(error)
+                    }]
+            };
+        }
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,261 @@
+/**
+ * TypeScript type definitions for Meshy API
+ */
+import { TaskStatus, TaskPhase, Topology, AIModel, ModelType, SymmetryMode, PoseMode } from "./constants.js";
+export interface TextureUrlsObject {
+    base_color?: string;
+    metallic?: string;
+    roughness?: string;
+    normal?: string;
+    ao?: string;
+}
+export interface TaskError {
+    code?: string;
+    message: string;
+}
+export interface CreateTaskApiResponse {
+    result: string;
+}
+export interface TextTo3DApiRequest {
+    mode: string;
+    prompt: string;
+    ai_model: string;
+    moderation: boolean;
+    model_type?: string;
+    target_polycount?: number;
+    topology?: string;
+    symmetry_mode?: string;
+    should_remesh?: boolean;
+    pose_mode?: string;
+    target_formats?: string[];
+    auto_size?: boolean;
+    origin_at?: string;
+}
+export interface ImageTo3DApiRequest {
+    image_url: string;
+    enable_pbr: boolean;
+    moderation: boolean;
+    ai_model?: string;
+    model_type?: string;
+    pose_mode?: string;
+    topology?: string;
+    target_polycount?: number;
+    should_remesh?: boolean;
+    symmetry_mode?: string;
+    should_texture?: boolean;
+    texture_prompt?: string;
+    texture_image_url?: string;
+    image_enhancement?: boolean;
+    remove_lighting?: boolean;
+    save_pre_remeshed_model?: boolean;
+    target_formats?: string[];
+    auto_size?: boolean;
+    origin_at?: string;
+}
+export interface TextTo3DRefineApiRequest {
+    mode: string;
+    preview_task_id: string;
+    enable_pbr: boolean;
+    ai_model: string;
+    texture_prompt?: string;
+    texture_image_url?: string;
+    remove_lighting?: boolean;
+    target_formats?: string[];
+    auto_size?: boolean;
+    origin_at?: string;
+}
+export interface MultiImageTo3DApiRequest {
+    image_urls: string[];
+    enable_pbr: boolean;
+    moderation: boolean;
+    ai_model?: string;
+    model_type?: string;
+    pose_mode?: string;
+    topology?: string;
+    target_polycount?: number;
+    should_remesh?: boolean;
+    symmetry_mode?: string;
+    should_texture?: boolean;
+    texture_prompt?: string;
+    texture_image_url?: string;
+    image_enhancement?: boolean;
+    remove_lighting?: boolean;
+    save_pre_remeshed_model?: boolean;
+    target_formats?: string[];
+    auto_size?: boolean;
+    origin_at?: string;
+}
+export interface RemeshApiRequest {
+    target_formats: string[];
+    resize_height: number;
+    convert_format_only: boolean;
+    input_task_id?: string;
+    model_url?: string;
+    topology?: string;
+    target_polycount?: number;
+    auto_size?: boolean;
+    origin_at?: string;
+}
+export interface RetextureApiRequest {
+    enable_original_uv: boolean;
+    enable_pbr: boolean;
+    input_task_id?: string;
+    model_url?: string;
+    text_style_prompt?: string;
+    image_style_url?: string;
+    ai_model?: string;
+    remove_lighting?: boolean;
+    target_formats?: string[];
+}
+export interface RigApiRequest {
+    height_meters: number;
+    input_task_id?: string;
+    model_url?: string;
+    texture_image_url?: string;
+}
+export interface AnimateApiRequest {
+    rig_task_id: string;
+    action_id: number;
+    post_process?: {
+        operation_type: string;
+        fps?: number;
+    };
+}
+export interface MultiColorPrintApiRequest {
+    input_task_id: string;
+    max_colors?: number;
+    max_depth?: number;
+}
+export interface TextToImageApiRequest {
+    ai_model: string;
+    prompt: string;
+    generate_multi_view: boolean;
+    aspect_ratio: string;
+    pose_mode?: string;
+}
+export interface ImageToImageApiRequest {
+    ai_model: string;
+    prompt: string;
+    reference_image_urls: string[];
+    generate_multi_view: boolean;
+}
+export interface Task {
+    id: string;
+    name?: string;
+    type?: string;
+    status: TaskStatus;
+    phase: TaskPhase;
+    progress: number;
+    created_at: string | number;
+    started_at?: string | number;
+    updated_at?: string;
+    finished_at?: string | number;
+    model_urls?: {
+        glb?: string;
+        fbx?: string;
+        usdz?: string;
+        obj?: string;
+        mtl?: string;
+        blend?: string;
+        stl?: string;
+        "3mf"?: string;
+    };
+    thumbnail_url?: string;
+    texture_urls?: TextureUrlsObject[] | TextureUrlsObject;
+    video_url?: string;
+    vertex_count?: number;
+    face_count?: number;
+    aabb?: {
+        min: [number, number, number];
+        max: [number, number, number];
+    };
+    prompt?: string;
+    preceding_tasks?: number;
+    task_error?: TaskError;
+    is_published?: boolean;
+    result?: {
+        rigged_character_glb_url?: string;
+        rigged_character_fbx_url?: string;
+        basic_animations?: {
+            walking_glb_url?: string;
+            walking_fbx_url?: string;
+            walking_armature_glb_url?: string;
+            running_glb_url?: string;
+            running_fbx_url?: string;
+            running_armature_glb_url?: string;
+        };
+        animation_glb_url?: string;
+        animation_fbx_url?: string;
+        processed_usdz_url?: string;
+        processed_armature_fbx_url?: string;
+        processed_animation_fps_fbx_url?: string;
+    };
+}
+export interface TextTo3DArgs {
+    prompt: string;
+    ai_model: AIModel;
+    model_type?: ModelType;
+    topology?: Topology;
+    target_polycount?: number;
+    symmetry_mode?: SymmetryMode;
+    should_remesh?: boolean;
+    pose_mode?: PoseMode;
+}
+export interface ImageTo3DArgs {
+    image_url: string;
+    ai_model?: AIModel;
+    model_type?: ModelType;
+    pose_mode?: PoseMode;
+    enable_pbr: boolean;
+    topology?: Topology;
+    target_polycount?: number;
+    should_remesh?: boolean;
+    symmetry_mode?: SymmetryMode;
+    should_texture?: boolean;
+    texture_prompt?: string;
+    texture_image_url?: string;
+    image_enhancement?: boolean;
+    remove_lighting?: boolean;
+    save_pre_remeshed_model?: boolean;
+}
+export interface CreateTaskRequest {
+    mode: string;
+    args: TextTo3DArgs | ImageTo3DArgs;
+}
+export interface CreateTaskResponse {
+    id: string;
+    status: TaskStatus;
+    created_at: string;
+}
+export interface GetTaskResponse extends Task {
+}
+export interface ListTasksResponse {
+    tasks: Task[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+export interface PaginationParams {
+    limit: number;
+    offset: number;
+}
+export interface BalanceResponse {
+    balance: number;
+}
+export interface PaginatedResponse<T> {
+    total: number;
+    count: number;
+    offset: number;
+    items: T[];
+    has_more: boolean;
+    next_offset?: number;
+}
+export interface ModelSummary {
+    id: string;
+    name: string;
+    thumbnail_url: string;
+    created_at: string | number;
+    vertex_count?: number;
+    face_count?: number;
+    is_published: boolean;
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * TypeScript type definitions for Meshy API
+ */
+export {};

package/dist/utils/endpoints.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Shared task endpoint mapping
+ */
+import { TaskType } from "../constants.js";
+/**
+ * All endpoint base paths in priority order for auto-inference
+ */
+export declare const ALL_TASK_ENDPOINTS: string[];
+/**
+ * Task types that have list endpoints (excludes rigging and animation which have no list API)
+ */
+export declare const LIST_CAPABLE_TASK_TYPES: TaskType[];
+/**
+ * Map task type to its API endpoint base path
+ */
+export declare function getTaskEndpoint(taskType: TaskType): string;

package/dist/utils/endpoints.js

@@ -0,0 +1,38 @@
+/**
+ * Shared task endpoint mapping
+ */
+import { TaskType } from "../constants.js";
+const TASK_ENDPOINTS = {
+    [TaskType.TEXT_TO_3D]: "/openapi/v2/text-to-3d",
+    [TaskType.IMAGE_TO_3D]: "/openapi/v1/image-to-3d",
+    [TaskType.MULTI_IMAGE_TO_3D]: "/openapi/v1/multi-image-to-3d",
+    [TaskType.REMESH]: "/openapi/v1/remesh",
+    [TaskType.RETEXTURE]: "/openapi/v1/retexture",
+    [TaskType.RIGGING]: "/openapi/v1/rigging",
+    [TaskType.ANIMATION]: "/openapi/v1/animations",
+    [TaskType.TEXT_TO_IMAGE]: "/openapi/v1/text-to-image",
+    [TaskType.IMAGE_TO_IMAGE]: "/openapi/v1/image-to-image",
+    [TaskType.MULTI_COLOR_PRINT]: "/openapi/v1/print/multi-color"
+};
+/**
+ * All endpoint base paths in priority order for auto-inference
+ */
+export const ALL_TASK_ENDPOINTS = Object.values(TASK_ENDPOINTS);
+/**
+ * Task types that have list endpoints (excludes rigging and animation which have no list API)
+ */
+export const LIST_CAPABLE_TASK_TYPES = [
+    TaskType.TEXT_TO_3D,
+    TaskType.IMAGE_TO_3D,
+    TaskType.MULTI_IMAGE_TO_3D,
+    TaskType.REMESH,
+    TaskType.RETEXTURE,
+    TaskType.TEXT_TO_IMAGE,
+    TaskType.IMAGE_TO_IMAGE
+];
+/**
+ * Map task type to its API endpoint base path
+ */
+export function getTaskEndpoint(taskType) {
+    return TASK_ENDPOINTS[taskType];
+}

package/dist/utils/request-builder.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared API request body builder.
+ * Constructs a request object from required fields and optional parameters,
+ * omitting undefined values automatically.
+ */
+/**
+ * Build an API request body by merging required fields with optional parameters.
+ * Undefined values in optionalParams are automatically excluded.
+ *
+ * @param requiredFields - Fields that are always included in the request
+ * @param optionalParams - Fields that are included only if defined
+ * @param excludeKeys - Keys to exclude from optionalParams (e.g., "response_format")
+ * @returns A flat record suitable for passing to client.post()
+ */
+export declare function buildApiRequest(requiredFields: Record<string, unknown>, optionalParams: Record<string, unknown>, excludeKeys?: string[]): Record<string, unknown>;

package/dist/utils/request-builder.js

@@ -0,0 +1,24 @@
+/**
+ * Shared API request body builder.
+ * Constructs a request object from required fields and optional parameters,
+ * omitting undefined values automatically.
+ */
+/**
+ * Build an API request body by merging required fields with optional parameters.
+ * Undefined values in optionalParams are automatically excluded.
+ *
+ * @param requiredFields - Fields that are always included in the request
+ * @param optionalParams - Fields that are included only if defined
+ * @param excludeKeys - Keys to exclude from optionalParams (e.g., "response_format")
+ * @returns A flat record suitable for passing to client.post()
+ */
+export function buildApiRequest(requiredFields, optionalParams, excludeKeys = ["response_format"]) {
+    const request = { ...requiredFields };
+    const excludeSet = new Set(excludeKeys);
+    for (const [key, value] of Object.entries(optionalParams)) {
+        if (value !== undefined && !excludeSet.has(key)) {
+            request[key] = value;
+        }
+    }
+    return request;
+}

package/dist/utils/response-formatter.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared response formatting for task creation tools.
+ */
+import { ResponseFormat } from "../constants.js";
+export interface TaskCreatedOutput {
+    [x: string]: unknown;
+    task_id: string;
+    status: string;
+    message: string;
+    estimated_time: string;
+}
+/**
+ * Format a task creation response with consistent structure across all tools.
+ *
+ * @param output - Structured output data
+ * @param responseFormat - Desired response format (markdown or json)
+ * @param title - Markdown title (e.g., "3D Generation Task Created")
+ * @param body - Additional markdown body text (e.g., "Your 3D model is being generated...")
+ * @param nextStepHint - Optional hint for the task_type parameter in next steps
+ */
+export declare function formatTaskCreatedResponse(output: TaskCreatedOutput, responseFormat: ResponseFormat, title: string, body: string, nextStepHint?: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: TaskCreatedOutput;
+};

package/dist/utils/response-formatter.js

@@ -0,0 +1,37 @@
+/**
+ * Shared response formatting for task creation tools.
+ */
+import { ResponseFormat } from "../constants.js";
+/**
+ * Format a task creation response with consistent structure across all tools.
+ *
+ * @param output - Structured output data
+ * @param responseFormat - Desired response format (markdown or json)
+ * @param title - Markdown title (e.g., "3D Generation Task Created")
+ * @param body - Additional markdown body text (e.g., "Your 3D model is being generated...")
+ * @param nextStepHint - Optional hint for the task_type parameter in next steps
+ */
+export function formatTaskCreatedResponse(output, responseFormat, title, body, nextStepHint) {
+    let textContent;
+    if (responseFormat === ResponseFormat.MARKDOWN) {
+        const taskTypeParam = nextStepHint ? ` and task_type "${nextStepHint}"` : "";
+        textContent = `# ${title}
+
+**Task ID**: ${output.task_id}
+**Status**: ${output.status}
+**Estimated Time**: ${output.estimated_time}
+
+${body}
+
+**Next Steps**:
+1. **Recommended**: Use \`meshy_get_task_status\` with task_id "${output.task_id}"${taskTypeParam} to automatically wait for completion.
+2. **Alternative**: Use \`meshy_get_task_status\` with wait=false to check once.`;
+    }
+    else {
+        textContent = JSON.stringify(output, null, 2);
+    }
+    return {
+        content: [{ type: "text", text: textContent }],
+        structuredContent: output
+    };
+}

package/dist/utils/slicer-detector.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Cross-platform slicer detection utilities.
+ * Detects installed 3D printing slicer software and returns launch commands.
+ * Does NOT execute launches — returns commands for the agent to run.
+ */
+import { SlicerType } from "../constants.js";
+export interface DetectedSlicer {
+    type: SlicerType;
+    displayName: string;
+    supportsMulticolor: boolean;
+    path: string;
+    launchCommand: string;
+    urlScheme?: string;
+}
+/**
+ * Detect all installed slicer software on the current system.
+ * Returns an array sorted with multicolor-capable slicers first.
+ */
+export declare function detectInstalledSlicers(): DetectedSlicer[];
+/**
+ * Detect a specific slicer by type.
+ * Returns null if not installed.
+ */
+export declare function detectSlicer(type: SlicerType): DetectedSlicer | null;
+/**
+ * Get the best slicer for multicolor printing from a list of installed slicers.
+ * Returns null if no multicolor-capable slicer is installed.
+ */
+export declare function getBestMulticolorSlicer(installed: DetectedSlicer[]): DetectedSlicer | null;