Stickman Character MCP Server

将您的 Red Hat 工程师风格的火柴人参考图变成一个 可摆姿势、可绑定的角色，任何兼容 MCP 的编程代理（Claude Code、Claude Desktop、Cursor 等）都能直接控制——设置关节角度、选择面部表情，并渲染单帧或完整动画（GIF/MP4）。由于每一帧都来自同一个参数化 SVG 骨架，角色在整段视频中都能保持与参考形象完美一致，不会像逐帧图像生成那样发生偏移。

保持形象一致

该骨架直接对齐参考表测量，而非近似取值，因此渲染结果与原始参考图几乎逐像素对应：

• 比例取自正面参考图（1024px 源图，头部外半径 121px）并按 0.546 缩放到 400x520 画布——脊柱 215px、上臂/前臂 108/120、大腿/小腿 126/127、四肢描边约 19px、头部中心位于肩叉上方 133px。

• 这顶软呢帽是参考帽子的矢量路径描摹，而非手工近似的模型。它以标准化的 SVG 路径（位于 rig.py 中的 HAT_PATHS）封装，使用头部半径单位表示，并通过 translate(head) scale(head_radius) 绘制。因此它可随头部倾角调节，同时保持原始帽沿弧线、帽冠凹陷和帽带的精确形态。

• 调色板源自角色：#D51918 亮红、#A01513 中间色、#7E1212 阴影、#C2C3C5 面部阴影、#D2D3D5 地面阴影。

• 脸部表现与参考一致——中性表情是两个实心黑色椭圆，并且没有嘴巴。白眼球加瞳孔的眼睛仅在 happy/excited/surprised 时使用，angry 表情使用斜向竖的楔形片并配以咬紧的牙齿，与参考表情统一。

hat_color 仍然是完全参数化的：传入任意十六进制颜色，中间色调和阴影色调都会据此推导，并沿参考色带的 1.0 / 0.742 / 0.592 比例自动生成。

内含方案

stickman_mcp/
  rig.py       - the skeleton: joints, forward kinematics, SVG renderer,
                 traced fedora paths, facial expressions, pose presets
  animate.py   - keyframe interpolation + export to PNG sequence / GIF / MP4
  server.py    - the MCP server itself (tools below)
pyproject.toml

安装

cd stickman_mcp
python3 -m venv venv
source venv/bin/activate
pip install -e .

这会引入 mcm、cairosvg（SVG→PNG 渲染）和 pillow（GIF 导出）。GIF/PNG 序列导出不需要额外的系统依赖；MP4 导出要求系统已安装 ffmpeg 并已加入您的 PATH。

将其注册为 MCP 服务器

Claude Desktop / Claude Code —— 在 MCP 配置中添加（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json，或 Claude Code 对应的配置）：

{
  "mcpServers": {
    "stickman": {
      "command": "/absolute/path/to/stickman_mcp/venv/bin/python",
      "args": ["-m", "stickman_mcp.server"],
      "cwd": "/absolute/path/to/stickman_mcp"
    }
  }
}

或通过 stdio 单独运行，以便测试：

python -m stickman_mcp.server

对外开放的操作

关节（所有角度单位为度，0 = 垂直向下，+ = 顺时针）

l_shoulder、l_elbow、r_shoulder、r_elbow、l_hip、l_knee、r_hip、r_knee、neck（头部倾斜）、spine（躯干倾斜）、hip_shift（像素，水平）、body_lift（像素，垂直，负值 = 更高）。

l_ 代表角色的左侧，也就是观看者的右侧。镜像对称姿势需要符号相反的膝盖角度（l_knee=86，r_knee=-86），以让双小腿同向弯曲。

样式 （每项在姿势切换时不会插值，而是在关键帧处直接 快照`）

• hands — "blob"（默认）、"open" 或 "fist"。也接收字典来进行单侧控制：{"r": "open"} 则另一只保持 bloblob。

• front_arm — "l"、"r" 或 "both"，表示将该侧手臂 置于头部之上。当手掌必须落在脸颊位置上（如 facepalm、thinking_pose）时需要使用，因为帽沿大约为头部宽度的 1.5 倍，否则会遮住手部。

• prop — 目前支持 "chair"，在 sit 时显示在角色后方。

动作列表

idle、wave_right、wave_left、point_right、point_left、explain_hands、explain_left_hand、thinking_pose、arms_up_happy、arms_crossed、hands_on_hips、fists_up、walk_1、walk_2、run_1、run_2、jump、crouch、sit、shrug、facepalm、bow、look_up、look_down、celebrate、typing.

表情

neutral、happy、excited、sad、angry、surprised、thinking、wink、talking、calm.

示例：一个编码代理制作一段简短短片

render_animation(
  keyframes=[
    {"pose": "idle",          "expression": "neutral", "hold": 0.5},
    {"pose": "wave_right",    "expression": "happy",   "hold": 1.0, "transition": 0.3},
    {"pose": "explain_hands", "expression": "excited", "hold": 1.5, "transition": 0.3},
    {"pose": "idle",          "expression": "happy",   "hold": 0.5, "transition": 0.3},
  ],
  fps=12,
  out_format="mp4",
)

代理也可以完全不使用预设，直接手工编写一个姿态：

render_pose(
  joints={"r_shoulder": -90, "r_elbow": 20, "neck": -10},
  expression="excited",
)

过渡使用 smoothstep缓动函数，因此动作在各动画之间会柔和地进行出/入缓动，而不是在关键帧之间直线滑动。

说明 / 更陡度的方向

• 当前骨架仅支持正面 2D 动作（涵盖参考表中绝大多数动作）。构建左/右或多面的侧面变体——并兼容侧身和向镜头走近的参考——是下一个自然的扩展方向：骨架本身已经支持此规模，但头部、面部以及绘制帽子仍然需要各自的侧身版本。

• 该确定了采用 prop="chair" 来绘制一把简单的木椅。其他道具可以按照 _chair_svg 的模式放入 rig.py。

• 如果希望实现“角色从屏幕前走”的镜头，可以手工生成 render_animation 的关键帧：在 walk_1 / walk_2 之间切换时，同时跨屏移动 hip_shift。