# zhoushengmin/spine-mcp-server architecture

> Architecture diagram of the GitHub repository zhoushengmin/spine-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zhoushengmin/spine-mcp-server
- Repository: https://github.com/zhoushengmin/spine-mcp-server

## Overview

Spine MCP Server exposes Spine 3.8.75 project inspection, editing, rendering, and production workflows as MCP tools for AI clients. The principal flow is an MCP request through tool dispatch to a domain tool and its Spine service; project changes use JSON editing and can round-trip through Spine’s CLI. A separate pipeline automates asset-to-animation production, while the documented Cocos extension provides a panel for service management and configuration. Some service wiring is unsampled, so unverified links are omitted.

Main entry points: [`src/spine/pipeline-service.ts`](https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/spine/pipeline-service.ts) (Production Pipeline), [`src/tools/registry.ts`](https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/tools/registry.ts) (Tool Registry), [`src/tools/render-preview.tool.ts`](https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/tools/render-preview.tool.ts) (Preview Tools), [`src/server.ts`](https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/server.ts) (MCP Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["MCP Entry"]
  node_server["MCP Server<br/>[server.ts]"]
  node_registry["Tool Registry<br/>[registry.ts]"]
  node_config["Configuration<br/>[config-manager.ts]"]
end

subgraph group_tools["Spine Tools"]
  node_base["Tool Base<br/>[base.tool.ts]"]
  node_inspect["Project Inspection<br/>[info.tool.ts]"]
  node_structure["Skeleton Editing"]
  node_animation["Animation Tools"]
  node_preview["Preview Tools"]
  node_pipeline_tool["Pipeline Tool<br/>[pipeline.tool.ts]"]
end

subgraph group_services["Spine Services"]
  node_cli["Spine CLI<br/>[cli-executor.ts]"]
  node_json["Spine JSON Editing<br/>[json-handler.ts]"]
  node_export["Project Export<br/>[export-service.ts]"]
  node_import["Project Import<br/>[import-service.ts]"]
  node_render["Animation Rendering<br/>[render-service.ts]"]
  node_runtime["JS Render Runtime<br/>[render-runtime.ts]"]
end

subgraph group_production["Asset Production"]
  node_pipeline["Production Pipeline"]
  node_cut["Atlas Part Cutting"]
  node_assemble["Skeleton Assembly"]
  node_mirror["Skeleton Mirroring<br/>[mirror-service.ts]"]
  node_generate["Animation Generation"]
  node_repack["Atlas Repacking"]
end

subgraph group_cocos["Cocos Extension"]
  node_extension["Cocos Panel<br/>[panel.js]"]
end

node_ai(("AI Client"))

node_ai -->|"sends MCP requests"| node_server
node_server -->|"dispatches tools"| node_registry
node_server -->|"loads configuration"| node_config
node_registry -->|"registers tools"| node_inspect
node_registry -->|"registers tools"| node_structure
node_registry -->|"registers tools"| node_animation
node_registry -->|"registers tools"| node_preview
node_registry -->|"registers tools"| node_pipeline_tool
node_inspect -.->|"reads project info"| node_cli
node_structure -->|"edits project JSON"| node_json
node_animation -->|"updates keyframes"| node_json
node_preview -->|"renders frames"| node_render
node_preview -->|"renders runtime frames"| node_runtime
node_preview -->|"exports project"| node_export
node_pipeline_tool -->|"runs workflow"| node_pipeline
node_pipeline -->|"cuts image parts"| node_cut
node_pipeline -->|"assembles skeleton"| node_assemble
node_pipeline -->|"mirrors skeleton"| node_mirror
node_pipeline -->|"generates animation"| node_generate
node_pipeline -->|"repacks atlas"| node_repack
node_pipeline -->|"renders frames"| node_render
node_extension -.->|"manages service"| node_server
node_export -->|"exports via CLI"| node_cli
node_import -->|"imports via CLI"| node_cli

click node_server "https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/server.ts"
click node_registry "https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/tools/registry.ts"
click node_config "https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/config-manager.ts"
click node_base "https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/tools/base.tool.ts"
click node_inspect "https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/tools/info.tool.ts"
click node_structure "https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/tools/bones-control.tool.ts"
click node_animation "https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/tools/animation-generate.tool.ts"
click node_preview "https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/tools/render-preview.tool.ts"
click node_pipeline_tool "https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/tools/pipeline.tool.ts"
click node_cli "https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/spine/cli-executor.ts"
click node_json "https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/spine/json-handler.ts"
click node_export "https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/spine/export-service.ts"
click node_import "https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/spine/import-service.ts"
click node_render "https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/spine/render-service.ts"
click node_runtime "https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/spine/render-runtime.ts"
click node_pipeline "https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/spine/pipeline-service.ts"
click node_cut "https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/spine/cut-parts-service.ts"
click node_assemble "https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/spine/assemble-service.ts"
click node_mirror "https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/spine/mirror-service.ts"
click node_generate "https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/spine/animation-generate-service.ts"
click node_repack "https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/spine/repack-atlas-service.ts"
click node_extension "https://github.com/zhoushengmin/spine-mcp-server/blob/master/cocos-extension/panel/panel.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_registry,node_config,node_ai toneBlue
class node_base,node_inspect,node_structure,node_animation,node_preview,node_pipeline_tool toneAmber
class node_cli,node_json,node_export,node_import,node_render,node_runtime toneMint
class node_pipeline,node_cut,node_assemble,node_mirror,node_generate,node_repack toneRose
class node_extension toneIndigo
```

## Components

### MCP Entry

- [MCP Server](https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/server.ts): `src/server.ts`
- [Tool Registry](https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/tools/registry.ts): `src/tools/registry.ts`
- [Configuration](https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/config-manager.ts): `src/config-manager.ts`

### Spine Tools

- [Tool Base](https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/tools/base.tool.ts): `src/tools/base.tool.ts`
- [Project Inspection](https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/tools/info.tool.ts): `src/tools/info.tool.ts`
- [Skeleton Editing](https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/tools/bones-control.tool.ts): `src/tools/bones-control.tool.ts`
- [Animation Tools](https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/tools/animation-generate.tool.ts): `src/tools/animation-generate.tool.ts`
- [Preview Tools](https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/tools/render-preview.tool.ts): `src/tools/render-preview.tool.ts`
- [Pipeline Tool](https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/tools/pipeline.tool.ts): `src/tools/pipeline.tool.ts`

### Spine Services

- [Spine CLI](https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/spine/cli-executor.ts): `src/spine/cli-executor.ts`
- [Spine JSON Editing](https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/spine/json-handler.ts): `src/spine/json-handler.ts`
- [Project Export](https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/spine/export-service.ts): `src/spine/export-service.ts`
- [Project Import](https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/spine/import-service.ts): `src/spine/import-service.ts`
- [Animation Rendering](https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/spine/render-service.ts): `src/spine/render-service.ts`
- [JS Render Runtime](https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/spine/render-runtime.ts): `src/spine/render-runtime.ts`

### Asset Production

- [Production Pipeline](https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/spine/pipeline-service.ts): `src/spine/pipeline-service.ts`
- [Atlas Part Cutting](https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/spine/cut-parts-service.ts): `src/spine/cut-parts-service.ts`
- [Skeleton Assembly](https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/spine/assemble-service.ts): `src/spine/assemble-service.ts`
- [Skeleton Mirroring](https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/spine/mirror-service.ts): `src/spine/mirror-service.ts`
- [Animation Generation](https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/spine/animation-generate-service.ts): `src/spine/animation-generate-service.ts`
- [Atlas Repacking](https://github.com/zhoushengmin/spine-mcp-server/blob/master/src/spine/repack-atlas-service.ts): `src/spine/repack-atlas-service.ts`

### Cocos Extension

- [Cocos Panel](https://github.com/zhoushengmin/spine-mcp-server/blob/master/cocos-extension/panel/panel.js): `cocos-extension/panel/panel.js`

### Other components

- **AI Client**

## Connections

- AI Client → MCP Server: sends MCP requests (evidence: `README.md`)
- MCP Server → Tool Registry: dispatches tools (evidence: `src/server.ts`)
- MCP Server → Configuration: loads configuration (evidence: `src/server.ts`)
- Tool Registry → Project Inspection: registers tools (evidence: `src/tools/registry.ts`)
- Tool Registry → Skeleton Editing: registers tools (evidence: `src/tools/registry.ts`)
- Tool Registry → Animation Tools: registers tools (evidence: `src/tools/registry.ts`)
- Tool Registry → Preview Tools: registers tools (evidence: `src/tools/registry.ts`)
- Tool Registry → Pipeline Tool: registers tools (evidence: `src/tools/registry.ts`)
- Project Inspection → Spine CLI: reads project info
- Skeleton Editing → Spine JSON Editing: edits project JSON (evidence: `src/tools/bones-control.tool.ts`)
- Animation Tools → Spine JSON Editing: updates keyframes (evidence: `src/tools/animation-generate.tool.ts`)
- Preview Tools → Animation Rendering: renders frames (evidence: `src/tools/render-preview.tool.ts`)
- Preview Tools → JS Render Runtime: renders runtime frames (evidence: `src/tools/render-preview.tool.ts`)
- Preview Tools → Project Export: exports project (evidence: `src/tools/render-preview.tool.ts`)
- Pipeline Tool → Production Pipeline: runs workflow (evidence: `src/tools/pipeline.tool.ts`)
- Production Pipeline → Atlas Part Cutting: cuts image parts (evidence: `src/spine/pipeline-service.ts`)
- Production Pipeline → Skeleton Assembly: assembles skeleton (evidence: `src/spine/pipeline-service.ts`)
- Production Pipeline → Skeleton Mirroring: mirrors skeleton (evidence: `src/spine/pipeline-service.ts`)
- Production Pipeline → Animation Generation: generates animation (evidence: `src/spine/pipeline-service.ts`)
- Production Pipeline → Atlas Repacking: repacks atlas (evidence: `src/spine/pipeline-service.ts`)
- Production Pipeline → Animation Rendering: renders frames (evidence: `src/spine/pipeline-service.ts`)
- Cocos Panel → MCP Server: manages service (evidence: `README.md`)
- Project Export → Spine CLI: exports via CLI (evidence: `src/spine/export-service.ts`)
- Project Import → Spine CLI: imports via CLI (evidence: `src/spine/import-service.ts`)
