# maya-mcp

用 AI agent（ZCode / Codex / OpenCode / Claude Code / Cursor 等）控制 Autodesk Maya 的 MCP 服务器。

- **架构**：Maya 内 Python 插件（TCP 客户端，常驻）↔ 独立 MCP 服务器（FastMCP 4.x）↔ AI 客户端
- **工具面**：混合式——语义工具（场景/对象/材质/动画/渲染）+ `execute_python`/`execute_mel` 逃生舱 + 只读 resources
- **兼容**：Maya 2022-2025（插件按 Py3.7 语法上限编写，实测 Maya 2023/Py3.9 通过）；服务器端 Python 3.10+
- **transport**：默认 stdio，可选 Streamable HTTP

> 完整技术选型与搭建流程见 [Maya-MCP搭建计划书.md](Maya-MCP搭建计划书.md)；
> **用户手册见 [docs/user-guide.md](docs/user-guide.md)**；
> 协议规格见 [protocol/PROTOCOL.md](protocol/PROTOCOL.md)；
> 设计决策见 [docs/设计规约.md](docs/设计规约.md)；
> 开发环境部署见 [docs/环境部署说明.md](docs/环境部署说明.md)。

## 快速开始（用户）

```bash
pip install maya-mcp
maya-mcp install-maya        # 安装 Maya 侧插件（重启 Maya 生效）
maya-mcp install-clients     # 配置 AI 客户端
maya-mcp doctor              # 自检整条链路
```

详见 [docs/user-guide.md](docs/user-guide.md)。

## 快速开始（开发）

```bash
# 1) 准备服务器端环境（Python 3.10+）
conda create -n maya-mcp python=3.12 -y
conda activate maya-mcp
python -m pip install -r requirements.txt -r requirements-dev.txt

# 2) 验证
python -m pytest -q          # 含 Py3.7 语法门禁 + 协议契约测试
ruff check maya_mcp tests
mypy

# 3) 运行服务器
python -m maya_mcp            # stdio（默认）
python -m maya_mcp --http     # Streamable HTTP，绑 127.0.0.1
```

Maya 插件端无需 pip 环境（仅标准库 + Maya 自带 PySide2/6），由 Maya 解释器加载；
开发期可在 **Maya Script Editor 的 Python 标签页**执行（务必带 `encoding="utf-8"`，中文 Windows 下否则会报 GBK 解码错误）：

```python
MAYA_MCP_REPO = r"D:/project/maya-MCP"
exec(open(MAYA_MCP_REPO + "/maya_mcp_plugin/dev_load.py", encoding="utf-8").read())
```

## 目录

| 路径 | 说明 |
|---|---|
| `maya_mcp/` | MCP 服务器（Python 3.10+，FastMCP 4.x） |
| `maya_mcp_plugin/` | Maya 插件（Python 3.7+，PySide2/PySide6） |
| `protocol/` | 协议规格唯一真源 + JSON Schema |
| `tests/` | unit（含 Py3.7 门禁）/ contract / integration |
| `docs/` | 计划书、环境部署、设计规约、审查报告 |

## 状态

**M0 + M1 + M2 + M3 全部完成**（2026-09-11），并在真实 Maya 2023（Python 3.9.7）上端到端验证通过。

**35 个工具**，按组渐进暴露（默认只显示 core 的 22 个，用 `manage_tools` 开启其余）：

| 组 | 数量 | 工具 |
|---|---|---|
| core（默认） | 22 | `maya_ping`、`list_sessions`、`set_active_instance`、`execute_python`、`execute_mel`、`scene_new/open/save`、`get_scene_info`、`get_selection`、`select_objects`、`create_primitive`、`list_objects`、`get_attributes`、`set_attributes`、`delete_objects`、`parent_object`、`duplicate_object`、`rename_object`、`manage_tools`、`capture_viewport`、`view_image` |
| authoring | 5 | `create_material`、`assign_material`、`list_materials`、`set_material_color`、`import_reference_image` |
| animation | 4 | `set_keyframe`、`get_keyframes`、`set_timeline`、`playblast` |
| rendering | 4 | `start_render`、`get_job_status`、`cancel_job`、`list_jobs` |

其他能力：
- **视觉能力**：`capture_viewport` 截图视口返回给 agent（可看图迭代建模）、`view_image` 查看本地参考图、`import_reference_image` 把参考图作为 imagePlane 导入场景
- **MCP resources**：`maya://sessions`、`maya://scene/info`、`maya://editor/selection`、`maya://node/{path}/attributes`（只读增强，均有等价工具）
- **多 Maya 实例**：首个连接自动成为活动实例，`set_active_instance` 切换，`session_key` 精确路由；同 PID 重连自动替换僵尸会话
- **渲染 job**：`start_render` 提交后立即返回 job_id，`get_job_status` 轮询；Maya 端逐帧在主线程推进，不阻塞其他调用
- **安装与诊断**：`install-maya`（.mod + 托管 userSetup 块）、`install-clients`（六客户端，最小改键/幂等/原子写/备份）、`doctor`（分层自检）
- 测试：**219 项通过**（unit + contract + integration），ruff / mypy strict 全绿

**真机验证**：工具分组开关、材质创建与指定、关键帧读写、playblast、渲染 job 轮询到 `done` 且期间其他调用不阻塞、插件自动重连、僵尸会话清理——全部实测通过。

**下一步**：可选项——提交 git 存档、发布 PyPI、补充更多领域工具。

## 安全要点

- 本地 TCP 通道自带随机令牌认证（`~/.maya-mcp/token`）。
- HTTP transport 默认只绑 `127.0.0.1`；绑非 loopback 必须显式 `--allow-remote` 且启用认证。
- `execute_python` 逃生舱：危险模式需显式开启、变更默认包 undo、可整体 `--no-execute-python` 禁用。
- 详见 `protocol/PROTOCOL.md` §8 与 `docs/设计规约.md`。

## 许可

MIT（待补 LICENSE 文件）。