Repository avatar
Developer Tools
v0.2.1
active

spine-pipeline-mcp

io.github.RainLib/spine-pipeline-mcp

Local Spine JSON, mesh, weight and animation tools with isolated staging.

Documentation

Spine2d-mcp: a local bridge between Spine and coding agents

Spine2d-mcp

English | 简体中文 | 日本語 | 한국어

Original Spine2d-mcp icon

License: MIT

A local, staging-first MCP foundation for Spine asset pipelines.

The repository/display name is Spine2d-mcp; the Python package and executable remain spine-pipeline-mcp for existing client compatibility. The project icon is unchanged. The banner uses the official, unmodified Spine mark only to identify compatibility; Codex and Claude Code are plain-text labels, not official logos or endorsements. See third-party notices.

Install / marketplaces · Connect Codex / Claude · Authoring skills · Architecture · Security · Contributing

Early prototype, project version 0.2.1. This repository uses the official Python MCP SDK 2.3.0. That SDK version is not a claim of “MCP protocol 2.0”, FastMCP 2.x, or project version 2.0. The fifteen tools below are implemented. Output remains staging-only; there is no publication tool.

Install MCP + Skills

The MCP executes tools; the Skills guide the agent's workflow. Use both for asset preparation → Spine rigging/animation → runtime integration. All paths and game-specific conventions come from the user.

All three Skills use English for instructions, references, and interface metadata. The repository plugin is version 0.2.2; the MCP server and published Registry bundle are version 0.2.1.

Discovery and downloads: three Skills on skills.sh · official MCP Registry entry · version 0.2.1 MCPB release. In the Registry search, enter io.github.RainLib/spine-pipeline-mcp. The repository plugins below combine all fifteen MCP tools and the three skills.

Option A: install the combined plugin

With a recent Codex CLI supporting codex plugin, register the repository marketplace and install its plugin:

codex plugin marketplace add RainLib/Spine2d-mcp
codex plugin add spine-pipeline@rainlib-spine

The equivalent Claude Code commands are:

claude plugin marketplace add RainLib/Spine2d-mcp
claude plugin install spine-pipeline@rainlib-spine

Both bundle the MCP and all three skills. Install Git, uv and Python 3.11+, then complete the one-time directory setup: Codex forwards the two SPINE_MCP_*_ROOT environment variables; Claude prompts for source and staging directories. Installing the plugin alone does not select your assets. JSON operations need no Spine license; native export requires your own installed, licensed Spine.

Option B: install Skills and MCP separately

For clients without plugin support, use the skills.sh CLI (Node.js 22.20+) to install the three skills for Codex:

npx skills add RainLib/Spine2d-mcp \
  --skill spine-asset-prep spine-rig-animation spine-game-integration \
  --agent codex --global

Replace codex with claude-code, or list both. Omit --global for a project installation. Skills installation does not register an MCP server. Add the MCP to Codex without manually cloning or creating a Python environment:

uvx --from git+https://github.com/RainLib/Spine2d-mcp.git@main python -c 'import spine_pipeline_mcp'
codex mcp add spine-pipeline \
  --env SPINE_MCP_SOURCE_ROOT=/absolute/path/to/test-assets \
  --env SPINE_MCP_STAGING_ROOT=/absolute/path/to/separate-staging \
  -- uvx --from git+https://github.com/RainLib/Spine2d-mcp.git@main spine-pipeline-mcp

The first command downloads/builds the server before the client's startup timeout applies. Replace both paths; source must exist and neither directory may contain the other. uvx installs from Git, so this command does not depend on a PyPI release. For repeatable setups, replace main with v0.2.1 or a full commit. See Claude's equivalent command, timeout setup, updates and registry details. Choose one installation route per client to avoid duplicate tools and skills.

Option C: install the Registry MCPB bundle

The official Registry name is io.github.RainLib/spine-pipeline-mcp. Its package points to the MCPB download, with a SHA-256 checksum in server.json. Import this file in a client supporting MCPB 0.4 and the UV runtime, then supply the source and staging directories when prompted. This bundle targets macOS/Linux and installs Python dependencies on first launch; it contains the MCP server. Install Skills separately with Option B.

The Registry provides discovery metadata; installation support depends on the client. Codex/Claude Code users can use Option A or B. See the bundle requirements and verification steps.

Use it

Start a new client session and first ask it to call skeleton_inspect on a JSON file relative to your configured source root. Then invoke a skill:

SkillExample request
spine-asset-prepPrepare these AI assets for Spine; use a connected PhotoCraft/Photoshop MCP for layers and previews when available.
spine-rig-animationAdjust this rig's mesh and weights, then validate the requested animation and secondary motion.
spine-game-integrationIntegrate the character into the target I specify, including slots, attachments, skins and events.

In Codex, use $spine-rig-animation for a standalone skill or $spine-pipeline:spine-rig-animation for the plugin. In Claude, use /spine-rig-animation or /spine-pipeline:spine-rig-animation, respectively. Photo editors are optional integrations discovered at use time. Skills do not add missing editor APIs; see capabilities and local extensions.

What works today

ToolBehavior
skeleton_inspectRead source JSON version, bones, animations and SHA-256
skeleton_validateStatic source bone/reference/mesh/weight/timeline checks
stage_json_copyByte-for-byte JSON-only copy to a new job
stage_asset_bundleIsolated JSON + referenced images; rebases image paths
job_validateStatic validation of an existing staged skeleton
mesh_inspectSource/job mesh inventory, edge connectivity, boundary/fan defects and influence statistics
mesh_weights_getPaged named influences and bone-local bind coordinates from a staged mesh
mesh_weights_setReplace selected vertices' existing weights, normalize and sort in a new job
mesh_replaceReplace explicit geometry in a new job, retaining the attachment's texture metadata
mesh_policy_validateCaller-defined continuity/budget/rigidity/direct-weight/ancestor-isolation rules
animation_copyCopy an animation under a new name in a new job
animation_retimeScale times by 1/speed in a new job; linear/stepped only
bone_keys_setSet rotate/translate/scale keys in a new job; Spine 4.3 rotate uses value
spine_exportExplicitly configured licensed CLI imports a copied JSON and exports project/JSON/atlas/PNG
godot_validateExplicitly configured native Spine-enabled Godot loads and briefly samples animations in an isolated minimal project

All transformations create a new job, preserving their input job and the original source. Animation copying refuses existing target names. Setting keys replaces only the selected timeline in the new copy. Retiming/setting keys rejects numeric Bezier curves rather than silently distorting them.

Static validation checks bone references/cycles, slot references, mesh UV/triangles, packed weighted vertices, bone indices, weight sums and timeline times. Multiple meshes are reported, not automatically rejected: attachment count alone cannot prove that the body mesh is continuous or that a rig follows an art policy.

Mesh edits currently require Spine 4.3.x and reject documents containing linked meshes, image sequences or deform/FFD/attachment animation timelines. Weight edits retain existing bone-local bind coordinates; changing weights can change the pose. Explicit mesh replacement supports locally generated geometry and new bindings with supplied coordinates. See mesh operations and local extensions for schemas, limits and the ProjectAdapter Python API.

Verified scope

Local copy-only smoke testing exercised the real MCP stdio tools: stage a weighted-mesh rig, copy/retime/edit an animation, export with Spine 4.3.26, then import/load/initialize/briefly sample using a Spine-enabled Godot 4.7.1 custom build. This is one locally tested combination, not a cross-version compatibility guarantee. Local test assets and paths are not distributed.

Not implemented

  • Spine editor GUI control or live timeline/weight-paint editing
  • Automatic alpha-contour meshing, rig creation, interactive weight painting or constraint authoring
  • GIF/rendered preview, full-timeline deformation/foot-drift/face-rigidity quality checks
  • Publishing back into a game, automatic retention/quota, remote HTTP hosting
  • Audio assets, image sequences or complete linked-mesh semantics

No Spine executable, game-specific engine binary, commercial assets, proprietary project files or game scripts are included. The example fixture is synthetic schema-shaped test data, not a production rendering rig.

Local development quick start

Requirements: Git, Python 3.11+, uv, and an MCP client supporting stdio. You do not need Spine installed to use the current JSON-only tools.

git clone https://github.com/RainLib/Spine2d-mcp.git
cd Spine2d-mcp
uv sync --locked
uv run --locked pytest -q

SPINE_MCP_SOURCE_ROOT="$PWD/examples/source" \
SPINE_MCP_STAGING_ROOT="$PWD/.staging" \
uv run --locked spine-pipeline-mcp

The last command starts a stdio MCP server waiting for a client; it is not an interactive CLI. Stop it with Ctrl-C. Start with the synthetic sample or your own test copies, not a production asset root.

Codex configuration (TOML)

Codex uses a named TOML table, not a mcpServers JSON object. Review the Codex template and merge it into the intended config without replacing existing settings:

[mcp_servers.spine-pipeline]
command = "uv"
args = ["--directory", "/path/to/Spine2d-mcp", "run", "--locked", "spine-pipeline-mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 300

[mcp_servers.spine-pipeline.env]
SPINE_MCP_SOURCE_ROOT = "/path/to/test-assets"
SPINE_MCP_STAGING_ROOT = "/path/to/separate-staging"

A separate CODEX_HOME (for example an API-account wrapper) does not inherit this entry automatically. An actual read-only Codex MCP tool invocation has been verified, not merely config parsing.

Claude Code configuration (JSON)

Claude Code uses mcpServers JSON. This format is not Codex TOML. Adapt the following or use the Claude Code template. Replace every placeholder with an actual absolute path. If the client cannot find uv, use its absolute executable path.

{
  "mcpServers": {
    "spine-pipeline": {
      "type": "stdio",
      "timeout": 300000,
      "command": "uv",
      "args": ["--directory", "/path/to/Spine2d-mcp", "run", "--locked", "spine-pipeline-mcp"],
      "env": {
        "SPINE_MCP_SOURCE_ROOT": "/path/to/Spine2d-mcp/examples/source",
        "SPINE_MCP_STAGING_ROOT": "/path/to/Spine2d-mcp/.staging"
      }
    }
  }
}

For a session-only Claude connection, use claude --mcp-config /path/to/private-spine.mcp.json --strict-mcp-config. Claude Code's isolated health check has been verified as Connected; a Claude model-driven call has not been claimed. The client guide explains scopes, verification and the licensed Spine CLI chain.

Example calls for source-reading tools:

{"relative_path": "minimal.json"}

Both root variables are required. Source must already exist. Source and staging must be separate and neither may contain the other. Tools fail closed if the configuration is absent or invalid. Source paths must be relative to the configured source root.

Optional native tools

The JSON tools need no installed editor. To enable CLI export, explicitly configure:

export SPINE_MCP_CLI=/path/to/Spine
export SPINE_MCP_CLI_VERSION=4.3.26
export SPINE_MCP_GODOT_EXECUTABLE=/path/to/spine-enabled-godot

The skeleton's version must exactly match the configured CLI version. Spine must already be installed/licensed; the server does not acquire a license. Stock Godot does not necessarily contain the native SpineSprite class; godot_validate reports failure when it is absent. Run native tools only on assets you trust.

Example sequence:

stage_asset_bundle(relative_path="rig.json") -> job A
animation_copy(job_id=A, source="idle", target="idle_preview") -> job B
animation_retime(job_id=B, animation="idle_preview", speed=1.2) -> job C
job_validate(job_id=C) -> static report
spine_export(job_id=C) -> export job D
godot_validate(job_id=D) -> independent validation job E

There is no automatic last step publishing D into a game. Inspect the outputs and reports before deciding how to use them.

Architecture

MCP client → stdio server
  ├─ inspect / validate → source JSON (read only)
  └─ stage bundle → immutable job A (JSON + images)
      └─ animation transforms → new job B
          └─ pinned Spine CLI → new export job C
              └─ isolated Godot project → new check job D

core.py handles source boundaries; validation.py, animation.py, mesh.py and mesh_policy.py provide JSON operations; pipeline.py handles staging and fixed CLI calls; godot_check.py builds a minimal standalone verification project. adapter.py composes explicit local transforms/validators with staging. Per-game paths and art policies belong in a local adapter outside this repository. See architecture.

Why Python rather than Go? Python can reuse image processing, NumPy/Pillow mesh work, JSON transforms and validation scripts in existing art pipelines. Go has attractive binary distribution, but requiring a Python worker for those operations would add another boundary before it adds value.

Safety model

  • Explicit source root, JSON-only reads, 16 MiB per JSON.
  • Reject requested absolute paths, parent traversal, symlinks and non-regular files.
  • Bundled images must resolve below the configured source; max 256 images / 128 MiB.
  • New UUID jobs; no overwrite/delete/publish tools or arbitrary shell text.
  • Native executable paths are administrator configuration, not tool-call arguments; commands use fixed argument arrays and timeouts.
  • Godot runs a generated minimal project with no game autoloads and isolated HOME/XDG.
  • Spine outputs are isolated, but the licensed editor can access its normal license/cache/settings. This is not an OS sandbox.
  • Log sizes are checked after each native command; they are not a hard live disk quota.

Use trusted directories/assets/executables. A hostile local process concurrently changing files/mounts is outside the threat model. Asset metadata and tool output are untrusted data, not instructions. Staging has no automatic retention/quota policy. See SECURITY.md.

Testing and CI

uv sync --locked
uv run --locked pytest -q
uv build

Unit tests use synthetic copies and mocked native executables. The stdio integration test invokes a real MCP subprocess. Licensed Spine/Godot tests are local, opt-in manual checks, not public CI fixtures.

An inactive CI template is provided for Linux Python 3.11/3.12 and a package build. Hosted CI is not enabled or verified yet: the publishing credential lacks workflow-write scope. A maintainer with appropriate access can place the template at .github/workflows/ci.yml and inspect the run.

License and third-party software

Project code and synthetic examples: MIT. Third-party trademarks and the official Spine mark are excluded from that license; see THIRD_PARTY_NOTICES.md. Dependencies retain their own licenses. Spine is commercial software by Esoteric Software and is not bundled or licensed by this project. Future CLI integrations require a separately installed, appropriately licensed copy and compliance with the applicable Spine terms. This is an independent community project, not an official Spine integration.

References

MCPB
https://github.com/RainLib/Spine2d-mcp/releases/download/v0.2.1/spine-pipeline-mcp-0.2.1.mcpb
Install Command
# mcpb: https://github.com/RainLib/Spine2d-mcp/releases/download/v0.2.1/spine-pipeline-mcp-0.2.1.mcpb