Spine JSON MCP

这是一个 TypeScript MCP 服务器，用于受控地读取、校验和修改 Spine 4.1.24 导出的 JSON 文件。第一版聚焦动画时间线，不直接修改 setup pose、骨骼结构、插槽结构或皮肤资源结构。

安装与构建

npm install
npm run build
npm test

运行

npm run build
node dist/server.js

服务器使用 MCP stdio 传输。默认情况下，所有文件工具只能访问当前工作目录内的文件。可以通过 SPINE_MCP_WORKSPACE 指定工作区根目录。

浏览器预览

项目提供一个独立浏览器预览层，用本地安装的官方 Spine Web runtime 加载工作区内的 JSON、atlas 和贴图资源。预览层只负责显示动画，不负责写入 JSON。

npm run build
npm run preview

默认访问：

http://127.0.0.1:5177

当前预览默认使用 example-json/skeleton-4.1.json、preview/xiaoren.atlas 和 preview/xiaoren.png。预览系统说明见 docs/浏览器预览系统.md。

WinForms 观察平台

项目提供一个最小 WinForms 观察壳，路径为 apps/winforms-observer。它读取 /api/session，展示 Agent 设置的当前上下文和操作日志，会话变化时调用 /api/validation-pipeline 展示验证结果，通过 /api/agent-connection 展示 Codex、Claude Code、opencode 等 Agent 的连接状态，并用 WebView2 嵌入预览 URL。

推荐用一键脚本启动，它会自动构建、选择空闲端口、启动预览服务并打开 WinForms：

npm run observer

脚本会写入运行态状态文件 .spine-mcp/observer-runtime.json，记录本次启动的 preview server 端口、URL、PID、WinForms PID 和日志路径。该文件只用于观察平台运行管理，不写 Spine JSON。

WinForms 会读取这个运行态状态文件，在左侧显示 preview server URL/PID、WinForms PID、启动时间、日志路径和停止命令，并提供“复制停止命令”“打开日志”两个辅助按钮。

停止由脚本启动的观察平台：

npm run observer:stop

停止前预览将要停止的进程：

powershell -ExecutionPolicy Bypass -File scripts/stop-observer.ps1 -DryRun

也可以直接运行：

powershell -ExecutionPolicy Bypass -File scripts/start-observer.ps1

如果只想检查端口和路径，不启动进程：

powershell -ExecutionPolicy Bypass -File scripts/start-observer.ps1 -CheckOnly

dotnet run --project apps/winforms-observer/SpineMcp.WinFormsObserver.csproj

WinForms 只观察和预览，不直接编辑 JSON。设计说明见 docs/WinForms观察平台设计.md。

在 Codex 中使用

本项目可作为 Codex MCP server 使用。配置示例：

[mcp_servers.spine_json_mcp]
command = 'C:\Program Files\nodejs\node.exe'
args = ['D:\AI_cc\spine-mcp\dist\server.js']
startup_timeout_sec = 30

[mcp_servers.spine_json_mcp.env]
SPINE_MCP_WORKSPACE = 'D:\AI_cc\spine-mcp'

修改 Codex 配置后，需要重启 Codex 或开启新会话，让 MCP 工具列表重新加载。加载成功后，可以让 Codex 调用 spine_get_document_summary、spine_get_animations、spine_validate_json 等工具。

连接成功后，建议让 Agent 调用一次握手工具：

{
  "tool": "spine_agent_ping",
  "arguments": {
    "clientType": "codex",
    "agentName": "Codex"
  }
}

WinForms 观察平台会根据握手状态显示 Agent 连接绿灯。未握手但检测到项目规则时显示黄灯；未检测到连接时显示红灯。

完整 MCP 操作列表见 docs/MCP操作清单.md。

官方 JSON 规范审查说明见 docs/官方JSON规范审查.md。自然语言验证用例见 docs/自然语言验证用例.md。安全提交流程见 docs/安全提交流程.md。浏览器预览说明见 docs/浏览器预览系统.md。WinForms 观察平台设计见 docs/WinForms观察平台设计.md。

V1 范围

• 读取 Spine JSON 摘要、骨骼层级、插槽、皮肤、动画列表、动画时间线和关键帧表格。
• 校验 Spine JSON 结构、引用关系、附件时间线、绘制顺序偏移和关键帧排序。
• 按 Spine 官方 JSON 导出格式和 4.1.24 样本适配规则审查当前可写 timeline 子集。
• 管理动画：创建、复制、删除动画。
• 批量编辑动画：平移关键帧、缩放时间、删除范围、复制片段、批量写入姿态、一次性写入多姿态动画序列、偏移骨骼数值、闭合循环。
• 从自然语言制作新动画时，优先使用 spine_apply_pose_sequence 把多个姿态时间点放进一次事务，减少多次写入、多次备份和多次审查调用。
• 只写入动画时间线数据：
  • 骨骼 rotate、translate、scale、shear
  • 插槽 attachment
  • 动画 drawOrder / draworder
• 写入工具默认 dryRun: true，只返回差异，不修改文件。
• 写入工具返回去重后的 affectedPaths、完整 diff、中文 summary、diff 白名单结果和官方规范审查结果，便于 Agent 判断修改范围和下一步操作。
• 提交写入时会在 backups/ 中生成备份。
• 可通过 spine_list_backups 查看备份，通过 spine_restore_backup 执行带 dryRun、confirm、expectedHash 和二次备份保护的恢复流程。
• 浏览器预览层通过官方 Spine Web runtime 动态加载修改后的 JSON；runtime 的 major.minor 必须匹配 skeleton.spine。
• 预览辅助工具可以检查资源并生成带参数的浏览器预览 URL，但不写入 JSON。
• spine_runtime_validate 可以用本地官方 spine-core@4.1.56 读取 JSON、atlas 和附件数据，确认文件不只是结构校验通过，也能被当前 4.1 runtime 加载。
• spine_run_validation_pipeline 可以在真实写入后一次性执行结构校验、官方 runtime 加载验证和预览 URL 生成，作为推荐复查入口。
• spine_preview_set_session / spine_preview_get_session / spine_preview_clear_session 提供 Agent 驱动的预览会话状态，供浏览器预览层和未来 WinForms 观察平台同步当前 JSON、atlas、动画和操作说明。
• spine_agent_ping / spine_agent_get_connection_status 提供 Agent 连接握手和配置片段查询，供 WinForms 连接向导显示红/黄/绿状态。
• V1 有意不修改 setup pose、bones、slots、skins、mesh/deform、constraints 和 events。

版本策略

写入操作锁定 skeleton.spine === "4.1.24"。如果文件版本不是 4.1.24，默认只允许读取和校验；除非工具调用显式传入 allowUnsupportedVersion: true，否则拒绝写入。

项目规则

项目规则记录在 AGENTS.md。后续所有新增文档、注释性说明、工具说明和面向 Agent 的描述都应优先使用中文。