meshy-mcp: Instructions file for Claude Code

meshy-mcp — Claude Context

Read this before writing or editing anything in this repo.

---

What this project is

A Model Context Protocol (MCP) server that gives Claude the ability to generate 3D models and 3D environments using the Meshy AI API. When connected to Claude Desktop or any MCP-compatible client, Claude gains six new tools for 3D generation without leaving the conversation.

This is a pure Node.js TypeScript package — no frontend, no database, no auth layer. It runs as a child process communicating over stdio using the MCP protocol.

---

Architecture

src/
├── index.ts          ← entry point, calls startServer()
├── server.ts         ← MCP Server instance, tool registry, request routing
├── meshy/
│   ├── client.ts     ← HTTP wrapper around the Meshy REST API
│   ├── types.ts      ← TypeScript types for all Meshy request/response shapes
│   └── poller.ts     ← generic async task poller (polls until SUCCEEDED/FAILED)
├── tools/
│   ├── index.ts      ← re-exports all tools
│   ├── text-to-3d.ts ← generate_3d_model tool
│   ├── refine-3d.ts  ← refine_3d_model tool
│   ├── image-to-3d.ts← generate_3d_from_image tool
│   ├── texture.ts    ← add_texture tool
│   └── status.ts     ← check_task_status + list_3d_models tools
└── utils/
    └── format.ts     ← markdown formatters for tool output strings

---

MCP protocol basics

This server uses @modelcontextprotocol/sdk. Key patterns:

• ListToolsRequestSchema → returns all tool definitions (name, description, inputSchema)
• CallToolRequestSchema → receives { name, arguments }, dispatches to the right tool, returns { content: [{ type: "text", text: "..." }] }
• All communication is over stdio — stdout is the MCP wire protocol, stderr is for logs
• Never write to stdout directly — always use process.stderr for debug logging

---

Adding a new tool

1. Create src/tools/my-tool.ts — export a Zod schema, a typed input, and a tool object { name, description, inputSchema, execute }
2. Re-export from src/tools/index.ts
3. Add to ALL_TOOLS array in src/server.ts
4. Add a case in the switch in src/server.ts
5. Add to the tool reference in docs/tools.md