本地 MCP 与调试（Maya + Cursor / Claude）

在完成 开发链接（just maya-dev-build-link-core-win / just maya-link-win）后，用 MCP 宿主连接本机 Maya；也可选地把 Python 调试器 附加到 Maya 进程。

1. 启动 Maya 与 MCP HTTP 服务

启动 Maya（或从仓库运行 just maya-dev-debug-win）。
在 Windows → Settings/Preferences → Plug-in Manager 中加载 dcc_mcp_maya（需要时可设为自动加载）。
在脚本编辑器 / 标准输出中确认 gateway URL（插件 sidecar 模式通常是 http://127.0.0.1:9765/mcp）。

如果明确启动直连 Python server，请使用 start_server().mcp_url() 返回的实际 URL；默认实例端口由操作系统分配。

2. 连接 Cursor（Streamable HTTP MCP）

打开 Cursor 设置 → MCP（或按你使用的 Cursor 版本编辑工作区 / 用户 MCP JSON）。
添加使用 HTTP / Streamable HTTP 传输、指向上述 Maya URL 的服务器。

可将 examples/mcp/cursor-maya-streamable-http.json 中的 JSON 片段复制到 MCP 配置，或合并为：

json

{
  "mcpServers": {
    "maya-local": {
      "url": "http://127.0.0.1:9765/mcp"
    }
  }
}

若宿主未加载配置，请重启 MCP / 重载窗口。
在对话中使用 Maya 工具（如 search_tools、load_skill、execute_python）操作当前会话。

若连接失败：确认 Maya 已运行、插件已加载、端口未被占用，且本机防火墙未拦截 localhost。

3. 连接 Claude Desktop（参考）

在 claude_desktop_config.json 中加入（详见 docs/integrations/claude.md）：

json

{
  "mcpServers": {
    "maya": {
      "url": "http://127.0.0.1:9765/mcp"
    }
  }
}

4. Python 调试（debugpy + Cursor / VS Code）

Maya 内嵌 CPython；debugpy 是用于 IDE 断点调试的可选增强能力。不安装时 maya-dev 的其它工具仍可使用，maya_dev__start_debugpy 会返回 debugpy_missing 并提示安装方式。

向该 Maya 环境安装 debugpy（一次性）：

text

"C:\Program Files\Autodesk\Maya2025\bin\mayapy.exe" -m pip install debugpy

加载 maya-dev skill，并通过 MCP 启动监听器：

json

{
  "tool": "load_skill",
  "arguments": {"skill_name": "maya-dev"}
}

json

{
  "tool": "maya_dev__start_debugpy",
  "arguments": {
    "host": "127.0.0.1",
    "port": 5678,
    "configure_python": true,
    "log_dir": "C:/temp/maya-debugpy"
  }
}

返回结果包含 debug_session 元数据、client_connected、log_uri，以及已 attach project 的建议 path_mappings。只有在你明确希望 Maya 阻塞等待 IDE 附加时才设置 wait_for_client=true。

在 Cursor / VS Code 中使用 Run and Debug → Python: Remote Attach，主机 127.0.0.1、端口 5678。
在 src/dcc_mcp_maya/**/*.py（或技能脚本）设断点，再从 MCP 触发工具；仅当代码在 Maya 主线程执行时 断点才会命中（与 Maya 脚本规则一致）。

Rust（dcc_mcp_core） 在 Maya 内调试成本较高（原生扩展）；可优先用日志，或在 Maya 外用小型 mayapy 复现导入 dcc_mcp_core 以加快原生调试。

5. 区分启动画面、Home 与编辑器就绪

MCP 就绪表示 dispatcher 能处理场景请求，不代表编辑器视口已经可见。 Home 覆盖编辑器时，Maya 仍可能正常提供工具。应分别报告这两项观察；不要仅因 Home 打开就让 /v1/readyz 拒绝一个可工作的会话。

应用界面的观察和输入使用项目 dcc-cua / DCC-MCP ui-control 路由。首次观察前报告运行时版本及精确 PID/HWND。用户截图可以帮助判断状态，但实际动作必须使用绑定到当前进程和窗口的最新观察。

界面状态	证据	下一步
启动画面	Maya splash 显示当前加载阶段	间隔观察，对比阶段、时间和进程活动。
首次欢迎页	Home 导航及新手/有经验用户选项	完成本地欢迎选项，再使用进入 Maya 的控件。
Home	最近文件、项目导航及进入编辑器的控件	进入现有编辑器，不新建或替换场景。
编辑器	可见视口及 Outliner、Channel Box 等编辑器控件	对同一实例执行 typed 场景查询。
阻塞对话框或未知	模态提示、归属不明或证据不足	报告具体阻塞，不猜测点击。

结合控件角色、结构、归属和最新像素识别，不能只依赖 Experienced、 Go to Maya 等英文标签。悬浮覆盖物不能作为 Maya 自身状态的证据。

动作返回成功或按钮获得焦点，不代表界面转换成功。进入编辑器后重新发现窗口：Home 与编辑器可能属于同一进程的不同 HWND。重新绑定 DCC-CUA，取得新观察并确认视口后，才能宣布 GUI 验收通过。若守卫因目标不在前台而拒绝输入，停止输入，只请求必要的人工聚焦或导航；不得改用通用界面自动化或注入 Maya 界面代码。

启动画面暂时无响应不足以证明死锁。关联同一进程的重复观察、bootstrap 阶段、sidecar 注册和只读线程诊断，并明确缺失证据。仅凭 splash 上的插件名，不能确定启动耗时实际发生在哪个调用中。

6. 快速检查表

现象	处理
MCP 404 / 连接被拒绝	插件是否加载？使用 gateway `9765`，或启动时报告的实际直连 URL。
看不到工具	极简模式：先调用 `load_skill("…")`（见 AGENTS.md）。
`debugpy_missing`	可选：将 debugpy 安装到对应的 `mayapy`，然后重启 Maya，即可获得更强的 IDE attach 调试能力。
`port_in_use`	换一个端口，或停止已经占用该端口的进程。
断点不命中	代码路径须在 Maya 内执行；确认通过 `maya_dev__start_debugpy` 附加到了正确的 Maya 进程。

本地 MCP 与调试（Maya + Cursor / Claude） ​

1. 启动 Maya 与 MCP HTTP 服务 ​

2. 连接 Cursor（Streamable HTTP MCP） ​

3. 连接 Claude Desktop（参考） ​

4. Python 调试（debugpy + Cursor / VS Code） ​

5. 区分启动画面、Home 与编辑器就绪 ​

6. 快速检查表 ​

相关 ​

本地 MCP 与调试（Maya + Cursor / Claude）

1. 启动 Maya 与 MCP HTTP 服务

2. 连接 Cursor（Streamable HTTP MCP）

3. 连接 Claude Desktop（参考）

4. Python 调试（debugpy + Cursor / VS Code）

5. 区分启动画面、Home 与编辑器就绪

6. 快速检查表

相关