The hy3d-mcp server turns concept images into game-ready textured 3D models (GLB) locally on Apple Silicon, wrapping the Hunyuan3D-MLX pipeline. It offers the following tools:
generate_model: Creates a textured 3D GLB from an image. Options include skipping texturing (shape-only, ~20s), automatic background cutout, a game-look finishing pass, texture resolution (512/1024/2048), and a random seed. Generation jobs are serialized to prevent memory exhaustion.
prepare_concept: Standalone background‑keying tool that converts a plain‑background image into a centered square RGBA PNG.
finish_model: Applies a tunable game‑look texture pass (toned albedo, emissive accents, panel seams) to an existing GLB without changing geometry.
render_preview: Renders offscreen PNG previews of a GLB from multiple angles (isometric, front, back, top, side) with no external engine.
server_status: Full health check and diagnostic – validates binaries, metallib, weights, worker environment, reports queue depth and last job, with exact fix instructions for any failures.
setup_engine: Runs the engine installer (dry‑run by default; executes with confirmation).
Models are returned as local file paths, and all processing happens offline without cloud dependencies.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@hy3d-mcp Generate a textured 3D model from this concept image."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that turns a single concept image into a game-ready textured 3D model (GLB), fully locally on Apple Silicon, by wrapping the Hunyuan3D-MLX pipeline (Swift + MLX). One tool call: background cutout → shape → PBR paint → optional game-look finishing pass. Proven in production on a real game fleet.
Models land as file paths, never blobs — importing them into your
engine is the caller's job (for Godot: copy into the project and run
godot --headless --import).
Apple Silicon Mac with ~48GB unified memory (texture paint peaks ~25–33GB)
Xcode or the Command Line Tools (for swift), and
uv
~15GB free disk: 12GB of weights, 1.3GB of build output
A built Hunyuan3D-MLX
checkout and a worker Python environment — ./install.sh
builds both for you; see that section before doing any of it by hand.
The server itself carries no ML dependencies; it shells out to the Swift binary and the worker venv.
Related MCP server: trident-mcp
The repo is also a Claude Code plugin that bundles the MCP server plus a
create-3d-model skill (prompt → concept image → GLB, with all the
input doctrine baked in):
/plugin marketplace add JimCline/hy3d-mcp
/plugin install hy3d-gen@hy3d-mcpOnce installed, ask for a 3D model in plain language or invoke
/hy3d-gen:create-3d-model. The server starts via
uv run --project <plugin-root> hy3d-mcp — uv resolves the venv on first
run.
git clone https://github.com/JimCline/hy3d-mcp ~/git/repos/hy3d-mcpRegister with your MCP client (e.g. in .mcp.json or Claude Code's
claude mcp add):
"hy3d-gen": {
"command": "uv",
"args": ["run", "--project", "~/git/repos/hy3d-mcp", "hy3d-mcp"],
"env": {
"HY3D_REPO": "~/git/repos/hunyuan3d-mlx",
"HY3D_PY": "~/.hy3d/worker-venv/bin/python",
"HY3D_OUT": "~/hy3d-output"
}
}All three env vars are optional; the values above are the defaults.
HY3D_PY is any python interpreter with the worker packages installed.
The server is a thin wrapper — the actual pipeline is a separate Swift checkout that has to be cloned, built, and fed 12GB of weights. Either let the installer do it or follow the manual sequence below; both end at the same place.
./install.sh --plan # print exactly what it would do, change nothing
./install.sh # do it, confirming the build and the downloadSeven phases — preflight, clone, swift build, metallib, weights,
paint-large relayout, worker venv. Every phase inspects before it
acts, so it is safe to re-run: finished work is skipped and a failed
run resumes where it stopped. The cheap and idempotent phases run
unattended; the two expensive ones (a ~4 minute build, a ~12GB download)
stop and ask first. --yes runs unattended, --only N runs one phase,
and --repo / --worker-venv relocate the targets.
From inside an MCP client, the setup_engine tool is the same script.
It defaults to a dry run and returns the plan; it only executes when
called again with confirm=true, so the agent has to show you the cost
before spending it.
When it finishes it prints the HY3D_REPO and HY3D_PY values to put in
your MCP config, and server_status should then come back all green.
The engine's own README covers steps 2–4; steps 5–7 are the parts it does not mention.
# 1. clone
git clone https://github.com/ZimengXiong/Hunyuan3D-MLX.git ~/git/repos/hunyuan3d-mlx
cd ~/git/repos/hunyuan3d-mlx
# 2. build (~4 min)
swift build -c release
# 3-4. weights (~12GB)
uvx --from huggingface_hub hf download \
zimengxiong/hunyuan3d-mlx-shape-small --local-dir weights/shape-small
uvx --from huggingface_hub hf download \
zimengxiong/hunyuan3d-mlx-paint-large --local-dir weights/paint-large
# 5. metallib — swift build never emits it; harvest it from the pip mlx wheel.
# NOTE: mlx-swift and pip mlx are separate version series. Package.resolved
# pins mlx-swift 0.31.4, but no such pip release exists — take the newest
# pip mlx in the matching 0.31.x series (0.31.2 at time of writing).
uv venv /tmp/mlxharvest
uv pip install --python /tmp/mlxharvest/bin/python mlx==0.31.2
SRC=$(find /tmp/mlxharvest -name mlx.metallib | head -1)
for d in metallib .build/arm64-apple-macosx/release; do
mkdir -p "$d" && cp "$SRC" "$d/mlx.metallib" && cp "$SRC" "$d/default.metallib"
done
# 6. paint-large ships flat, the binary wants it nested
cd weights/paint-large
mkdir -p hunyuan3d-paint-v2-0 hunyuan3d-paintpbr-v2-1
ln -s ../vae ../unet hunyuan3d-paint-v2-0/
ln -s ../vae ../unet hunyuan3d-paintpbr-v2-1/
ln -s dinov2 dinov2-giant
cd ../..
# 7. worker venv — uv, not pip: uv-created venvs have no pip in them
uv venv ~/.hy3d/worker-venv
uv pip install --python ~/.hy3d/worker-venv/bin/python \
opencv-python numpy trimesh pillow scipy pyrender pygltflibThen set HY3D_REPO=~/git/repos/hunyuan3d-mlx and
HY3D_PY=~/.hy3d/worker-venv/bin/python.
Either way, verify with the server_status tool. It re-checks every
requirement and each failing check carries its own fix.
install.sh handles all three; they are documented here because they are
what a by-the-book install of the upstream repo gets wrong, and what
server_status is looking for when it fails.
Metallib — swift build never emits the MLX metallib (mlx-swift
SwiftPM limitation). Harvest mlx.metallib from the pip mlx wheel —
not the version string in Package.resolved, which is mlx-swift's
own series and has no pip counterpart (there is no pip mlx 0.31.4).
Take the newest pip mlx sharing its major.minor, and copy it as both
mlx.metallib and default.metallib into metallib/ and into
.build/arm64-apple-macosx/release/ (the real dir — .build/release
is a symlink).
Weight layout — the paint-large HF repo ships flat, the binary
expects nested: symlink hunyuan3d-paint-v2-0/{vae,unet} and
hunyuan3d-paintpbr-v2-1/{vae,unet} → ../vae, ../unet, and
dinov2-giant → dinov2, inside weights/paint-large.
Paint model flag — the server always passes --paint-model pbr;
the rgb default targets a weight set that isn't installed.
Tool | What it does | Typical time |
| image → textured GLB (auto cutout, optional finish) | ~3–4 min (shape only: ~20s) |
| texture a mesh you already have, from a concept image | ~3 min |
| plain-background image → centered square RGBA | seconds |
| game-look texture pass: toned albedo + accent/seam emissive | seconds |
| offscreen PNG renders, falling back to the generator's own sheets | seconds |
| full setup diagnostic, queue depth, last job | instant |
| runs | instant (plan) / up to an hour (apply) |
| kill the running engine and free the queue | instant |
Generation is serialized — one job at a time; concurrent calls queue
rather than OOM the machine. generate_model streams MCP progress
notifications the whole way through, so a slow job stays distinguishable
from a hung one, and cancelling the call kills the engine process rather
than leaving it holding the queue.
Outputs carry vertex normals. The engine writes only POSITION and
TEXCOORD_0; Godot does not synthesise the rest, and lights the whole
mesh off one constant vector when NORMAL is missing — which presents
as a bad material, not a missing attribute, and is expensive to
diagnose. generate_model and finish_model inject it by default
(normals=false opts out). Injected, not re-exported: a round trip
through a mesh library rebuilds the material block and destroys the
emissive map the finish pass writes.
Previews degrade rather than fail. pyrender wants a window-server
connection despite the "offscreen" name, and a daemonised MCP server
usually has none. When rasterising fails, render_preview returns the
<name>.glb.views.png and .rendercheck.png contact sheets the paint
pass writes beside every GLB, and marks source: "generator_sheets" so
you know they're fixed views, not the ones you asked for. Shape-only
output has no sheets to fall back on.
octree costs scale with concept detail, not just the number. A
smooth-hulled subject at octree=384 finished in ~6 minutes; a
lattice/greeble-heavy one ran 16.5 minutes and pushed the machine deep
into swap — and at defaults that same subject resolved its truss braces
fine in 790s. Reach for octree when thin struts fuse together, not
as a general quality dial.
Vertex counts vary ~4.5× across subjects at identical settings (82k for a gun housing, 367k for a trussed deck). There is no knob that trades detail back down; budget for the heavy case, or simplify the concept.
accent_coverage_pct near 0 is usually the extractor's range, not
your concept. It keys on saturated red-dominant regions and is tuned
for broad accent panels; thin indicator strips score near zero.
Long jobs and client timeouts. A detailed concept can legitimately
paint for 13+ minutes, which exceeds some clients' idle-abort defaults.
The progress stream is what keeps those timers alive; if your client
still gives up, raise its tool timeout (Claude Code:
CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT, or a per-server timeout in MCP
settings). If a job is ever abandoned mid-flight, cancel_job frees
the queue without hunting for a pid.
Feed naturally lit concept art — the model de-lights internally. Pre-flattened "albedo-style" input bakes pale and featureless.
No drop shadows in the source image — they reconstruct as literal geometry under the model.
Single object, plain background, roughly centered; ¾ view works best.
prepare_concept / auto_cutout handle the background keying.
No cloud fallback.
No mesh post-processing (decimation/repair proved destructive on generated meshes; LODs belong to your engine's importer).
No batch tool — loop generate_model; the queue serializes.
No multiview input yet — the pipeline is single-image at every entry point. Investigated and specced, not built; see below.
docs/multiview-routes-2026-08-02.md
— multi-image → 3D. Three routes costed (native MLX port, ComfyUI hybrid,
upstream PR), six open questions, and a Phase 0 A/B that settles whether
multiview earns its keep before anything is built. Tabled, decision open.
docs/multiview-findings-2026-08-02.md
— the investigation behind it. Read this for why contact sheets must never
be fed back in, why generator sheets must never be used to judge geometry,
and the measurement showing +31% geometry from input quality alone.
MIT — but that covers this wrapper code only. This repo distributes no model weights and no Tencent code.
The pipeline runs on Tencent's Hunyuan3D weights, which you download yourself and which are governed by the Tencent Hunyuan 3D 2.0 / 2.1 Community License Agreements (2.0, 2.1) — the paint stage uses both generations, so both apply. Highlights, not legal advice; read the licenses:
Territory: the license does not apply in the European Union, the United Kingdom, or South Korea. If you're there, you may not use the weights at all.
Scale: products/services exceeding 1M monthly active users require written permission from Tencent.
Attribution: distributing or productizing anything built on the weights requires the Tencent license notice; 2.1 asks for a "Powered by Tencent Hunyuan" mark.
Acceptable use: no training competing models on it, no undisclosed synthetic-media deception, no military use, among others.
Your outputs are yours: Tencent claims no rights to generated 3D models; you own them and are responsible for how you use them.
The Hunyuan3D-MLX Swift port this server shells out to is itself MIT-licensed.
Apply the game-look texture pass to a generated GLB. Geometry untouched.
Tones the albedo (gamma/contrast/saturation), extracts saturated accents and blackhat panel seams into a dedicated glTF emissive texture. Separated from generation so it can be re-run with new knobs without regenerating. seam_pinstripes 0-1 (0 disables); defaults are the values proven on the AEGIS fleet.
| Name | Required | Description | Default |
|---|---|---|---|
| contrast | No | ||
| glb_path | Yes | ||
| seam_halo | No | ||
| saturation | No | ||
| tone_gamma | No | ||
| output_path | No | ||
| accent_emissive | No | ||
| seam_pinstripes | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It explicitly discloses that geometry is untouched, that the tool alters albedo and creates an emissive texture, and that it is designed for re-runs. This is strong, though it does not clarify whether the input GLB is overwritten or how output_path influences file handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded, with four sentences covering the primary action, texture mechanisms, pipeline separation, and a key parameter. Every sentence adds functional value, and there is no redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 8 parameters and no annotations, the description provides a solid overview of the tool's behavior, safety, and re-runnability. It stops short of specifying output_path semantics and explicit sibling-tool alternatives, but the presence of an output schema and the sibling names help fill remaining context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It explains the purpose of key params: tone_gamma/contrast/saturation for albedo tuning, accent_emissive for saturated accents, and seam_pinstripes with a 0-1 range and disable behavior. It does not explain seam_halo or explicitly define glb_path/output_path, but those are partially inferable from names.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description delivers a specific verb and resource: 'Apply the game-look texture pass to a generated GLB.' It clearly distinguishes the tool from siblings like generate_model by noting it is 'Separated from generation' and re-runnable without regenerating, making the tool's role in the pipeline unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description establishes when to use the tool: after a GLB has been generated, and notes it can be reused with new tuning knobs. It implies this is the texturing step rather than generation/rendering, but it does not explicitly name sibling tools as alternatives or list exclusion cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Turn a concept image into a textured 3D model (GLB).
paint=False skips texturing (shape only, ~20s vs ~3-4 min). auto_cutout keys out a plain background first unless the input already carries real transparency. finish=True applies the game-look texture pass (see finish_model) after generation. texture_size: 512|1024|2048. Blocks while an earlier generation is running (single-job queue).
| Name | Required | Description | Default |
|---|---|---|---|
| seed | No | ||
| paint | No | ||
| finish | No | ||
| image_path | Yes | ||
| auto_cutout | No | ||
| output_path | No | ||
| texture_size | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully carries the behavioral disclosure burden. It reveals timing differences (~20s vs 3-4 min), the effect of auto_cutout on transparency, the meaning of finish=True, and the blocking queue behavior. This is exceptionally transparent for an AI agent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is tightly packed into a few sentences with no filler. It front-loads the core purpose, then concisely explains options and side effects. Every sentence adds value, and the structure is logical (purpose → options → behavior).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 params, output schema exists), the description covers the main workflow flags, timing, queue behavior, and references finish_model. It does not mention prepare_concept as a prerequisite or explain output_path, but these are minor gaps. The presence of an output schema means return value details are not required, so the description is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must add meaning. It does for paint, auto_cutout, finish, and texture_size (including allowed values 512|1024|2048). It omits seed and output_path, but these are self-explanatory from their names and defaults. The description compensates for most key parameters, though not all.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Turn a concept image into a textured 3D model (GLB).' It clearly distinguishes this tool from siblings by focusing on generation, while finish_model is referenced as a separate follow-up step. The GLB format specification adds precision.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage contexts: paint=False for shape-only, finish=True for game-look pass with a pointer to finish_model, and auto_cutout for background removal. It also mentions the single-job queue, which tells the agent when to expect blocking. These are clear when/when-not scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Key a plain-background concept image out to a centered square RGBA PNG.
Standalone version of generate_model's auto_cutout, for callers that want the intermediate. Refuses inputs whose corners disagree (busy background). Warns when the opaque fraction looks like a bad key.
| Name | Required | Description | Default |
|---|---|---|---|
| image_path | Yes | ||
| output_path | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of disclosing behavior. It does so effectively by stating refusal conditions ('Refuses inputs whose corners disagree (busy background)') and warning behavior ('Warns when the opaque fraction looks like a bad key'). These are meaningful beyond what the schema reveals.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, front-loaded with the core action, and every sentence adds unique value: the operation, the relationship to generate_model, and two behavioral constraints. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose, usage context, behavioral edge cases, and output format. An output schema exists, so return details are not needed. The only gap is the lack of parameter-level explanation, but overall the description is sufficiently complete for a moderately complex tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate by explaining the parameters. It mentions the concept image as input and RGBA PNG as output, but it never maps these to the actual parameter names (image_path, output_path) or clarifies output_path's null default behavior. The parameter semantics are under-specified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb-resource statement: 'Key a plain-background concept image out to a centered square RGBA PNG.' It also explicitly distinguishes itself from a sibling tool ('Standalone version of generate_model's auto_cutout'), making its unique role clear.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description names the alternative (generate_model) and specifies the intended use case ('for callers that want the intermediate'). It implies when this tool should be chosen over the sibling but does not explicitly say when NOT to use it in favor of other alternatives, so it stops short of full guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Offscreen renders of a GLB, no engine needed.
views: subset of iso/front/back/top/side (default [iso]). Needs pyrender in the worker venv; the error message says how to add it if missing.
| Name | Required | Description | Default |
|---|---|---|---|
| size | No | ||
| views | No | ||
| glb_path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses offscreen rendering, no engine requirement, a pyrender dependency, and the allowed views values/default. While it doesn't mention side effects or return format, an output schema exists, so those omissions are less critical.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences: the first states the core purpose, and the second packs parameter semantics and a dependency note. No fluff, well front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple render tool with an output schema and a clear parameter schema, the description covers purpose, dependency, and views options. It doesn't elaborate on return behavior (handled by output schema) or pipeline timing, but overall it is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description adds meaning to the 'views' parameter by listing the allowed values (iso/front/back/top/side) and default ([iso]). It does not explain 'size' or 'glb_path' beyond what the schema already provides, so compensation is partial.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool performs 'Offscreen renders of a GLB', specifying the verb 'renders' and the resource type 'GLB'. This distinguishes it from sibling tools like generate_model or server_status by the render-specific action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit 'when to use' or 'when not to use' guidance. The phrase 'no engine needed' hints at lighter usage compared to a full engine, but it does not mention alternatives or pipeline stage. The dependency note is operational, not usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Health check and first-run diagnostic.
Validates every setup requirement (binary, metallib, weights, weight layout, worker venv); each failing check carries the exact fix. Also reports queue depth and the last job.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that checks report exact fixes and that queue depth and last job are included, which is useful. However, it does not explicitly state whether the operation is read-only, requires specific permissions, or has side effects, which is a gap for a tool with no annotation safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the tool's role, followed by a concise list of checks and reports. Every word earns its place without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter diagnostic tool with an output schema, the description covers the main functionality and clearly states what will be checked and reported. It does not need to describe return values due to the output schema. A minor gap is the lack of explicit read-only behavior, but it is largely implied.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the input schema is empty. The description adds context about what is validated and reported, which is relevant but not parameter-level detail. With zero parameters, the baseline is 4 per the rubric.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool as a health check and first-run diagnostic, listing specific validation targets (binary, metallib, weights, weight layout, worker venv) and additional reporting (queue depth, last job). This distinguishes it from sibling tools like generate_model or render_preview, which focus on generation/rendering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for setup validation and diagnostics but does not explicitly state when to prefer this over siblings or provide exclusions. It mentions 'first-run diagnostic' which suggests a specific use case, but no clear when-not-to-use guidance is included.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0finish_modelgenerate_modelprepare_conceptrender_previewserver_statusScored across 5 tools
Each tool addresses a distinct stage: concept preparation, model generation, texturing/finishing, preview rendering, and server diagnostics. There is no functional overlap or ambiguity between them.
Four of five tools follow a clear verb_noun pattern (prepare_concept, generate_model, finish_model, render_preview). server_status breaks the pattern slightly but remains readable and predictable within the set.
Five tools are well-scoped for the server's purpose, covering the essential pipeline without redundancy or bloat. Each tool has a clear role and earns its place.
The full lifecycle from concept image to finished model preview is covered: prepare concept, generate model, optionally finish texturing, and render preview. server_status adds operational coverage. No critical gaps are apparent.
Turn text or an image into an animation-ready 3D model (GLB): generate, rig, animate, retexture.
Free text/image → 3D: generate, rig, avatar-ify, and refine GLB models. No auth, no payment.
3D avatar/asset foundry: text/image -> rigged, validated, engine-ready GLB via x402.
Turn any LLM multimodal; generate images, voices, videos, 3D models, music, and more.
