TailorKit automation API v1

TailorKit 0.3.0 has one local command interface for Blender Python, JSON batch jobs and MCP clients. It runs the same operators used by the sidebar. No AI subscription, API key, network listener or cloud upload is required. The client supplies the AI; TailorKit supplies deterministic tools and reports.

In an open Blender scene

Enable TailorKit, then use Blender's Python Console or an existing trusted Blender automation connection. Call on Blender's main thread:

from weftsmith import api
schema = api.execute({'api_version': 1, 'action': 'discover'})
state = api.execute({'api_version': 1, 'action': 'inspect'})
result = api.execute({
    'api_version': 1, 'action': 'configure',
    'settings': {'body': 'My Body', 'outfit_workflow': 'CONFORM', 'conform_slot': 'Top'}
})

Every response has api_version and ok. Success has result; failure has error.code and error.message. Discover first: it returns the installed add-on version, writable input types, numeric bounds, enum IDs, and all registered TailorKit operators with parameter schemas. Use exact datablock names returned by inspect. Do not guess enum IDs from display labels.

Pointer settings accept a datablock name or JSON null. Flag enums accept an array of IDs. Numeric inputs reject NaN, infinity and out-of-range values instead of relying on Blender to clamp them. Read-only queries work while a UI job runs; mutations report BUSY. Use weftsmith.cancel to request cancellation of a UI job.

Read inspect.result.settings before configuring a scene: pointers use exact datablock names or null, enum flags are sorted arrays, and numeric arrays are ordinary JSON arrays. active_object and frame identify the current review state. Inspection does not change settings or selection. The legacy current_shape_fit_approved flag covers its stored current-shape review only; read outfit and recorded-range reports separately.

On this development workstation, use the official Blender Lab MCP for all Blender work, including isolated jobs. Its guarded client is documented in wardrobe production (see the included source reference). The standalone product adapters below describe customer integration options and do not replace that local rule.

End-to-end request

This needs no downloaded body or third-party assets. Save the following as practice.json. It makes a small original torso/shirt, checks sources, fits working copies, checks the current shape, and returns the actual report:

[
  {"api_version":1,"action":"run","command":"weftsmith.create_demo"},
  {"api_version":1,"action":"run","command":"weftsmith.artist_check"},
  {"api_version":1,"action":"run","command":"weftsmith.artist_adopt"},
  {"api_version":1,"action":"run","command":"weftsmith.check"},
  {"api_version":1,"action":"read_report","name":"TailorKit Fit Report"}
]

Run it from PowerShell with a source checkout:

& 'C:/Program Files/Blender Foundation/Blender 5.2/blender.exe' `
  --background --factory-startup --disable-autoexec --python-exit-code 1 `
  --python E:/BlenderTools/TailorKit/tools/automation.py -- `
  --request E:/BlenderTools/TailorKit/output/practice.json `
  --response E:/BlenderTools/TailorKit/output/practice-response.json `
  --save-as E:/BlenderTools/TailorKit/output/practice.blend

The output directory must already exist. To work on an existing scene, put its absolute .blend path before --python-exit-code. --save-as must name a new file, never the input file. Commands run in order; a failure stops the batch, writes the response and exits nonzero without saving the scene. Successful commands may still have written explicit exports. There is no automatic rollback of an entire batch. A batch without --save-as does not persist scene changes.

The installed ZIP also contains weftsmith/tools/automation.py and weftsmith/tools/mcp_server.py. They work without a second source checkout. Locate the installed directory with weftsmith.__file__ in Blender's Console.

Connect an MCP client

Use any client supporting local stdio MCP tools. Python 3.10+ and a local Blender executable are required. Example configuration (adjust executable paths):

{
  "mcpServers": {
    "tailorkit": {
      "command": "python",
      "args": [
        "E:/BlenderTools/TailorKit/tools/mcp_server.py",
        "--blender", "C:/Program Files/Blender Foundation/Blender 5.2/blender.exe"
      ]
    }
  }
}

The server exposes tailorkit_batch with requests, optional blend_file, and optional save_as. Start by calling it with the discover request. Each call starts an isolated Blender process; it does not attach to an open artist window. Save a new copy and use that file as blend_file on the next call. Default timeout is 900 seconds; --timeout accepts 1–7200 seconds. A timeout terminates that batch process. Already written exports may remain.

Example natural-language instruction for your AI client:

Discover TailorKit's commands. Open my saved scene as a separate working copy. Inspect its body and garments, conform the selected shirt, create a recorded body range, run it, and summarize the failed cases from the actual report. Preserve originals. Save a new scene; do not describe completion as fit approval.

Long checks and inspection tools

The API adapts slider sweeps, adaptive range checks and rig/morph baking to blocking execution without UI timers. These calls may take minutes. They reuse the existing restoration and report paths. Pose review operators already have synchronous execution paths. For live UI interaction, use the sidebar's modal tools to retain responsive cancellation.

Source highlighting and fit-issue selection can enter Edit Mode. Call set_mode with OBJECT before the next operation. Review/comparison commands retain their existing context and binding requirements; read their errors rather than forcing invalid scenes through.

Trust and result interpretation

ok: true means a command completed. A fit report may still contain passed: false. Read blocking_issues, per-case blockers, restoration status, and the report's scope. Current-shape approval is checked against the current geometry fingerprint; range approval remains tied to the recorded inputs. Never set approval flags, suppress crossings or delete the hidden body to turn a failure into a pass.

The bridge disables automatic scene scripts. Scenes requiring custom executable driver expressions or external rig scripts may fail; use a trusted, separately configured authoring session for those scenes. This interface executes registered TailorKit commands only, but commands can write the explicit file paths supplied to export/import operators. It is a local tool, not an isolation boundary for untrusted users. Reports can contain proprietary object names or asset metadata; review them before sharing. The dedicated Support Report omits geometry and file paths and is never uploaded automatically.