┌──────────────┐   stdio (JSON-RPC)   ┌───────────────────┐   HTTP (127.0.0.1:9876)   ┌──────────────────┐
│ MCP 客户端    │ ──────────────────▶ │ MCP Server        │ ───────────────────────▶ │ Blender 插件      │
│ WorkBuddy /  │                     │ mcp_server/       │                          │ blender_addon/    │
│ Claude 等     │ ◀────────────────── │ server.py         │ ◀─────────────────────── │ subhuti_..._mcp.py│
└──────────────┘                     └───────────────────┘                          └──────────────────┘
      工具调用                             转发请求/结果                             主线程执行 bpy 代码

subhuti-blender-mcp/
├── src/subhuti_blender_mcp/        # 主包（可安装、可导入）
│   ├── __main__.py                 # 入口：python -m subhuti_blender_mcp
│   ├── config.py                   # 配置模块（环境变量统一管理）
│   ├── core/                       # 核心应用服务
│   │   └── mcp_server.py           #   MCP Server 定义 + 4 个工具
│   └── utils/                      # 基础工具
│       └── http_client.py          #   与 Blender 桥通信的 HTTP 封装
├── blender_addon/                  # 部署物：Blender 插件（独立于 Python 包）
│   └── subhuti_blender_mcp.py
├── scripts/                        # 辅助启动脚本
│   ├── start_blender_gui.py
│   └── start_blender_headless.py
├── tests/                          # 测试
│   ├── test_client.py              #   stdio 端到端测试
│   └── debug_client.py             #   HTTP 模式调试客户端
├── pyproject.toml                  # 构建配置（src 布局）
├── requirements.txt
└── README.md

.venv/bin/python -m pip install -e .

# 复制插件到 Blender 用户级 addons 目录
mkdir -p "$HOME/Library/Application Support/Blender/4.3/scripts/addons"
cp blender_addon/subhuti_blender_mcp.py \
   "$HOME/Library/Application Support/Blender/4.3/scripts/addons/"

# 启用并保存为用户偏好（只需一次，之后 Blender 启动自动加载）
/Applications/Blender.app/Contents/MacOS/Blender -b -y --python-expr "
import bpy, addon_utils
addon_utils.enable('subhuti_blender_mcp', default_set=True, persistent=True)
bpy.ops.wm.save_userpref()
"

make package   # 生成 dist/subhuti_blender_mcp.zip

curl --noproxy '*' http://127.0.0.1:9876/health
# {"status": "ok", "blender": "4.3.2", "background": false, ...}

.venv/bin/python tests/test_client.py

.venv/bin/python scripts/start_blender_headless.py /Users/hezenghui/Public/blender/cli_test.blend

make run-logs          # ★ 前台日志模式：启动 + 日志实时滚动，Ctrl+C 统一关闭（推荐日常）
make start             # 后台启动 Blender(GUI) + MCP Server(HTTP)，启动前自动清理残留实例
make start-headless    # 同上，但 Blender 无头模式（自动化/CI）
make stop              # 彻底关闭所有相关进程（SIGTERM + 兜底 SIGKILL）
make status            # 查看各组件运行状态
make logs              # 查看当前会话日志
make clean             # stop + 删除日志/运行时文件

# 终端 1：以 HTTP 模式启动 server（默认 127.0.0.1:8100/mcp）
BLENDER_MCP_TRANSPORT=http .venv/bin/python -m subhuti_blender_mcp

# 终端 2 / PyCharm 调试：触发调用（server 端断点会命中）
.venv/bin/python tests/debug_client.py

# 安装全局命令 subhuti-blender-mcp（依赖自动装进独立环境，不污染项目 venv）
uv tool install .

# 把 ~/.local/bin 加入 PATH（或 uv tool update-shell），之后可直接使用该命令

{
  "mcpServers": {
    "blender-mcp": {
      "command": "/Users/hezenghui/.local/bin/subhuti-blender-mcp",
      "args": [],
      "env": {
        "BLENDER_MCP_HOST": "127.0.0.1",
        "BLENDER_MCP_PORT": "9876"
      }
    }
  }
}

检测 subhuti-blender-mcp 命令 → 已装：打印 "MCP Server 已就绪"
                              → 未装 + 自动安装开启：后台 uv tool install（不阻塞 Blender）
                              → 未装 + 未找到 uv：打印手动安装指引