rhino-gh-mcp

# rhino-gh-mcp > 一个MCP服务器和Rhino/Grasshopper插件，让大型语言模型（LLM）可以读取和驱动实时的Rhino 8建模会话，用于参数化设计、建筑研究和教学。 **📖 新手？从 [示例工作流指南](https://xunliudesign.github.io/rhino-gh-mcp/) 开始 —— 涵盖从首次连接到底层研究的可行工作流。** **状态**: v0.2.6 —— Rhino 8 `gh_write_script` 修复（`IScriptComponent.Text`），新的 `facade-design` 技能（七种类型学配方，附带参考 `.gh` 文件）和 `rhino-gh-bridge-basics` 技能，以及来自 v0.2.x 的五种场景画布曲面（检查 / 调整 / 指导 / 执行 / 作者）。通过 [`.mcpb` 桌面扩展](https://github.com/modelcontextprotocol/mcpb) 进行双击安装，适用于克劳德桌面和 [Yak 包](https://developer.rhino3d.com/guides/yak/)，适用于Rhino包管理器。详见下面的快速入门。 --- ## 功能 您需要安装三个组件 —— 一个Python MCP服务器、一个Grasshopper插件和一个Rhino插件 —— 将您喜欢的MCP客户端（克劳德桌面、克劳德代码、光标等）连接到服务器，然后您可以用自然语言与LLM交流您的模型： *"添加一个名为radius的滑块，范围为0-50，然后用该半径创建一个圆圈，然后将其烘焙到当前图层"*. LLM使用以下工具读取您的画布、放置和连接Grasshopper组件、更改参数、捕获视口并运行Rhino命令。 v0.2 通过画布组件上的单个 **场景** 下拉菜单控制AI可以触及的内容： **检查** （只读）→ **调整** （仅限参数）→ **指导** （默认 - 精选编辑，每次更改均突出显示）→ **执行** （仅限活动技能声明）→ **作者** （完全控制）。 [示例工作流指南](https://xunliudesign.github.io/rhino-gh-mcp/) 有每个模式的章节，附有真实的转录提示和截图。您可以在对话中切换场景；它会在约3秒内传播。（v0.1组件保留在功能区中，作为 `rhino-gh-mcp 服务器（v1）`，适用于已使用的 `.gh` 文件。） 参见 [docs/architecture.md](docs/architecture.md) 以了解完整情况， [docs/v0.2-redesign.md](docs/v0.2-redesign.md) 以了解场景设计， [docs/handoff.md](docs/handoff.md) 以了解当前状态。 --- ## 快速入门 — 软件包管理器 + 一次下载 > 适用于设计师和建筑学生。无需 `git clone`，无需 `uv`，无需 `dotnet`。您需要：**Rhino 8** 已安装，**克劳德桌面** 已安装，**Python 3.11+** 在您的PATH上。大约5分钟。 ### 步骤 0 — 下载克劳德桌面扩展 前往 [最新的GitHub发布](https://github.com/xunliuDesign/rhino-gh-mcp/releases/latest) 并下载： | 文件 | 它是什么 | 它去哪里 | |---|---|---| | `rhino-gh-mcp-X.Y.Z.mcpb` | 克劳德桌面扩展（Python MCP服务器捆绑） | 克劳德桌面 | 两个Rhino插件（`.yak`文件）从步骤1中的Rhino内部通过软件包管理器安装 - 您不需要下载它们。（它们也在发布页面上，如果您需要离线/拖放备份。） ### 步骤 1 — 安装Rhino + Grasshopper插件 启动Rhino 8，运行 `_PackageManager` 在命令行中，搜索 **rhino-gh-mcp**。安装两个软件包： - `rhinogh-mcp-grasshopper` — Grasshopper画布桥（`.gha`） - `rhinogh-mcp-rhino` — Rhino文档桥（`.rhp`） 重启Rhino。插件位于Grasshopper的 **MCP** 功能区选项卡中。 *离线/防火墙/旧Rhino？* 跳过软件包管理器：将每个 `.yak` 文件从最新的GitHub发布拖放到打开的Rhino 8窗口中 - 相同的安装对话框，无需网络连接。 ### 步骤 2 — 在克劳德桌面上安装Python MCP服务器 双击下载的 `.mcpb`。克劳德桌面打开扩展面板并提示安装。确认。首次启动时，pip安装约5个Python依赖项（约30秒，一次性）。 扩展程序显示四个设置：控制级别预设（`parameter` / `curated` / `full`），Grasshopper桥接端口（默认9999），Rhino桥接端口（默认9876），日志级别。 ### 步骤 3 — 在Rhino中启动两个桥接器 1. 在Rhino的命令行中运行 `_ToggleMcpService`。您应该看到 *"rhino-gh-mcp: MCP服务在127.0.0.1:9876上运行"*。 2. 打开Grasshopper（ `_Grasshopper` ）。 3. 找到 **MCP** 功能区选项卡 → **服务器** 组 → 将 **rhino-gh-mcp 服务器（v2）** 组件放到空白画布上。 4. 一个 **布尔切换** （运行，关闭）和一个 **值列表** （场景，指导已选中）自动连接到左侧 - 将切换按钮切换到 **真**，`状态` 应该显示 `服务器开启 127.0.0.1:9999 | 场景：指导 | 技能：（无）`。 ### 步骤 4 — 重启克劳德桌面并尝试提示 重启克劳德桌面，使其拾取扩展程序。在一个新的聊天中： > 调用 `gh_status` 和 `rhino_status` 以确认两个桥接器都存活，然后调用 `gh_canvas_summary` 和 `rhino_get_scene_info` 以查看那里有什么。然后添加一个名为 `radius` 的滑块，范围为0-50，默认值为10，放置一个读取该滑块的 `Circle` 组件，重新计算并捕获视口，以便我可以看到结果。 如果两个状态检查都成功，并且圆圈出现在画布上，则完成。从这里开始， [示例工作流指南](https://xunliudesign.github.io/rhino-gh-mcp/) 演练所有五个场景 - 从 **指导** 开始，这是默认的。 --- ## 替代快速入门 — 让AI从源代码安装 如果上述 `.mcpb` / Yak路径不适合您的设置 - 例如，您想修改桥接代码，或者您正在使用Rhino的构建版本，没有设置软件包管理器 - 您仍然可以让AI助手完成完整的源代码安装。您安装一个助手应用程序，将存储库放到磁盘上，并要求AI完成其余的操作。 **1. 安装MCP功能的助手。** [克劳德桌面](https://claude.ai/download) （Mac或Windows）是最简单的。克劳德代码（在VS Code内部）和ChatGPT桌面应用程序的MCP支持也有效。 **2. 确保Rhino 8已经安装。** 该项目仅支持Rhino 8 - Rhino 7不受支持。 **3. 将此存储库下载到稳定位置** （例如 `Documents/rhino-gh-mcp`）。无需Git：前往 [GitHub页面](https://github.com/xunliuDesign/rhino-gh-mcp) → 绿色 **代码** 按钮 → **下载ZIP** → 解压。 **4. 将助手指向解压的文件夹。** - *克劳德桌面：* 打开文件夹选择器/“添加项目”面板并选择解压的存储库。助手可以从中读取文件。 - *克劳德代码：* 在该文件夹内打开一个会话（`claude` 从终端进入文件夹，或在VS Code中打开文件夹并安装克劳德扩展）。 **5. 粘贴下面的安装提示。** 填写您指定的操作系统。 > 请阅读此项目中的 `README.md` 和 `docs/handoff.md`，然后在我的机器上安装rhino-gh-mcp。我是 **macOS** *(或：Windows)*。 做任何你能做的，不需要我参与：使用 `uv` 安装Python依赖项，构建Grasshopper `.gha` 和Rhino `.rhp` 源代码，将 `.gha` 复制到我的Grasshopper库文件夹，将 `.rhp` 注册到Rhino，并将此MCP服务器添加到我的克劳德桌面配置中，以便它作为工具源出现。 当你完成后，告诉我你需要手动在Rhino中执行哪些步骤（例如启动监听器，放置画布组件，重启助手）。 助手将运行 `uv sync`，使用 `dotnet build` 构建两个插件，将每个插件复制到其OS特定的安装路径，注册Rhino插件并编辑您的MCP配置。然后，它将告诉您需要手动执行的小部分操作 - 与上面的两个点击快速启动相同。 如果出现任何问题，请将助手的错误消息反馈给它，并指向 **故障排除** 和 **安装** 部分。 --- ## 先决条件 - **Rhino 8** （Mac或Windows）。 Rhino 7 **不支持** - 我们依赖Rhino 8 .NET 7运行时。 - **Python 3.11 或 3.12**。 - **`uv`](https://docs.astral.sh/uv/) 用于Python环境 + 运行。 - Windows： `winget install --id=astral-sh.uv` - Mac： `brew install uv` （或 `curl -LsSf https://astral.sh/uv/install.sh | sh` ） - **.NET 7+ SDK** （用于从源代码构建C#插件）。 - Windows： `winget install Microsoft.DotNet.SDK.8` - Mac： `brew install --cask dotnet-sdk` - **Git** 用于克隆。 - **MCP客户端。** 克劳德桌面、克劳德代码或光标都有效。 --- ## 安装 — 5分钟（如果您有前提条件） ### 1. 克隆 ```bash git clone https://github.com/xunliuDesign/rhino-gh-mcp.git cd rhino-gh-mcp ``` ### 2. 设置Python服务器 ```bash cd server uv sync # 创建.venv，安装依赖 + 开发依赖 uv run pytest -q # 27个测试应该通过 - 健康检查 cd .. ``` ### 3. 构建 + 安装Grasshopper插件 **Windows：** ```powershell cd plugins\grasshopper .\reinstall.ps1 ``` **Mac：** ```bash cd plugins/grasshopper ./reinstall.sh ``` 两个脚本：强制退出Rhino（如果正在运行）→ `dotnet build -c Release` → 将生成的 `.gha` 复制到您的Grasshopper `Libraries` 文件夹。首次使用PowerShell的用户可能需要运行 `Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned` 一次。 ### 4. 构建 + 安装Rhino插件 ```powershell # Windows cd plugins\rhino .\reinstall.ps1 ``` ```bash # Mac cd plugins/rhino ./reinstall.sh ``` **仅限首次：** Rhino需要显式注册后 `_ToggleMcpService` 成为识别命令。 - **Windows：** 将构建的 `.rhp` （脚本打印绝对路径）拖放到Rhino的主窗口 - Rhino将提示加载和信任插件。第一次注册后，随后重建 **自动更新** 。 - **Mac：** 拖放路径在macOS Rhino 8上不可靠 - 将 `.rhp` 放在 `~/Library/Application Support/McNeel/Rhinoceros/8.0/Plug-ins/RhinoGhMcpRhino (3f88bb55-3368-4204-9d0a-55911c9349ee)/RhinoGhMcpRhino.rhp` 并在 `<child key="PlugInRegistry"><child key="6">` 块的 `~/Library/Application Support/McNeel/Rhinoceros/8.0/settings/settings-Scheme__Default.xml` 中添加注册条目（`LoadMode=1`，`IsDotNETPlugIn=True`，`FileName`指向绝对路径）。AI安装路径上述快速启动执行这两个操作。 ### 5. 连接客户端 **克劳德代码** - 存储库范围内的 `.mcp.json` 已支持。启动克劳德代码会话并批准信任提示。 `rhino-gh` 服务器将在该会话中可用。 **克劳德桌面** - 在您的配置文件中添加一个 `mcpServers` 块： ```json { "mcpServers": { "rhino-gh": { "command": "uv", "args": [ "--directory", "/absolute/path/to/rhino-gh-mcp/server", "run", "rhino-gh-mcp", "--policy", "curated" ] } } ``` Mac上的 `uv` 应该是绝对路径（ `/Users/<you>/.local/bin/uv` 或类似）- GUI应用程序不总是继承您的shell的 `PATH` 配置文件位置取决于克劳德构建版本： | 构建版本 | Mac | Windows | |---|---|---| | 克劳德桌面（经典） | `~/Library/Application Support/Claude/claude_desktop_config.json` | `%APPDATA%\Claude\claude_desktop_config.json` | | 统一Anthropic克劳德应用（带有Cowork / 克劳德代码集成） | `~/Library/Application Support/Claude-3p/claude_desktop_config.json` | `%APPDATA%\Claude-3p\claude_desktop_config.json` | 如果您同时拥有两个目录，请使用 `Claude-3p` 目录 - 配置文件内的纯 `Claude/` 文件会被应用并剥夺未知键。重启助手后编辑。 **Cursor / 其他客户端** - 将它们指向与上述克劳德桌面块相同的命令和参数。 ### 6. 在Rhino中启动两个桥接器 1. 启动Rhino 8。 2. **在Rhino的命令行中，键入 `_ToggleMcpService` 并按Enter。您应该看到 *"rhino-gh-mcp: MCP服务在127.0.0.1:9876上运行"*。 3. 打开Grasshopper（ `_Grasshopper` ）。 4. 在Grasshopper功能区中找到 **MCP** 选项卡 → **服务器** 组 → 将 **rhino-gh-mcp 服务器（v1）** 组件放到空白画布上。 5. 右键单击组件的 `Run` 输入 → 将持久数据设置为 `True` （或连接布尔值切换器 = True）。`状态` 输出应显示 `服务器开启 127.0.0.1:9999`。 ### 7. 从终端进行烟雾测试（可选但推荐） ```bash cd server uv run python ../examples/smoke_test_bridge.py # GH 桥接 uv run python ../examples/smoke_test_rhino.py # Rhino 桥接 uv run python ../examples/verify_capability_gate.py # 画布标志 ``` 如果这些测试通过，则您的MCP客户端应该也能与桥接器通信。 --- ## 使用它 在一个新的聊天中与您的MCP客户端进行一次预热： ``` 您可以通过rhino-gh MCP服务器访问Rhino 8 + Grasshopper会话。在执行任何操作之前，请调用 gh_status 和 rhino_status 以验证两个桥接器是否正常运行，然后调用 gh_canvas_summary 和 rhino_get_scene_info 以查看那里有什么。分步骤操作；每次进行有意义的更改后，请重新计算并捕获视口。 ``` 然后用自然语言描述您想要的内容 - LLM会选择合适的工具。 [示例工作流指南](https://xunliudesign.github.io/rhino-gh-mcp/) 有八个工作会话（带有提示，截图和观察到的运行时间）可供参考。 有关引导工作流（技能），请参阅 [skills/README.md](skills/README.md)。第一方技能： - **`landform`** - 通过捆绑的MCP景观用户对象进行参数化地形。 - **`ladybug-environmental`** - 使用Ladybug工具（日照路径，日照小时，风向玫瑰）进行环境分析。需要安装Ladybug Grasshopper插件。 - **`facade-design`** - 基于配方生成立面：七种类型学配方（百叶窗，网格，折叠，动态，板面，穿孔吸引子，Voronoi）附带参考 `.gh` 文件。 - **`rhino-gh-bridge-basics`** - 桥接怪癖和主机几何体导入模式的基础知识。 --- ## 仓库布局 ``` rhino-gh-mcp/ ├── server/ # Python MCP服务器（uv项目） │ ├── src/rhino_gh_mcp/ │ │ ├── server.py # FastMCP应用程序 + 生命周期 │ │ ├── config.py # CLI + 策略预设 │ │ ├── capabilities.py # 软能力门控（v0.1.5+） │ │ ├── bridges/ # HTTP→GH，TCP→Rhino │ │ ├── policies/ # 旧版兼容性（后备兼容） │ │ └── tools/ # 工具实现 │ ├── tests/ # pytest（无需Rhino） │ └── pyproject.toml ├── plugins/ │ ├── grasshopper/ # .gha（C# / net7.0 + net7.0-windows） │ └── rhino/ # .rhp（C# / net7.0） ├── examples/ # 桥接级别的烟雾 + 验证脚本 ├── skills/ # Anthropic Agent Skills包 │ ├── landform/ │ ├── ladybug-environmental/ │ ├── facade-design/ │ └── rhino-gh-bridge-basics/ ├── mcpb/ # .mcpb / .dxt 桌面扩展源代码 │ ├── manifest.json # MCPB v0.3 清单 │ ├── bootstrap.py # 首次启动依赖项安装程序 │ └── requirements.txt # 服务器运行时依赖项 ├── scripts/ │ ├── build-mcpb.sh # → dist/rhino-gh-mcp-<v>.mcpb │ ├── build-yak.sh # → dist/rhinogh-mcp-*-<v>-*.yak │ └── sync.{sh,ps1} # 一次性开发同步后 ├── dist/ # 构建安装包（.mcpb + .yak） ├── docs/ │ ├── architecture.md │ ├── handoff.md # 状态 + 会话日志 │ ├── packaging-status.md # .mcpb + Yak 发布状态 / 下一步 │ ├── performance-notes.md │ └── generalization.md └── .mcp.json # 项目范围的克劳德代码MCP配置 ``` --- ## 故障排除 **“Grasshopper 桥接器在 http://127.0.0.1:9999 处不可达”** MCP 服务器组件未在 GH 画布上运行（无打开的画布，或 `Run` 为假）。在空白画布上放置一个并将 `Run` 设置为真。 **"Rhino 桥接器在 127.0.0.1:9876 处不可达"** 您尚未在启动 Rhino 后运行 `_ToggleMcpService`，或者您运行了两次并关闭了监听器。 **"画布能力被拒绝：请设置 `AllowScripting` 输入..."** 工作正常 - LLM 正在请求您画布上关闭的能力。或者在组件上启用该切换开关，或告诉 LLM 使用较不特权的路径。 **工具返回无值/挂起** 检查相关组件上的 `gh_get_runtime_messages`。大多数故障是由于线路问题（错误的输入名称），这些问题在运行时错误中显示，但不显示异常。 **Windows 上的 PowerShell “脚本无法加载”** 一次性修复： `Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned`。 **`uv sync` 未安装 pytest** 确保您使用的是 `uv ≥ 0.5` 以便 `[dependency-groups]` 表被遵守。旧版本需要 `uv sync --extra dev`。 --- ## 路线图 | 阶段 | 状态 | 范围 | |-------|--------|-------| | **P0** | ✅ | 清洁骨架，FastMCP 服务器，所有 15 个 GH 命令已移植，`.gha` 在 Mac + Windows 上构建 | | **P1** | ✅ | Rhino `.rhp` 清洁分离，视口捕获，Windows + Mac 上的烟雾测试通过 | | **P2** | ✅ | 软能力门控，画布端控件，第一技能（`landform`） | | **P3** | ⏳ | Rhino 8 脚本组件注入（Python 3 + C# 进入现代脚本组件） | | **P4** | 🟡 | 曲面扩展 - 已完成：list_toggles/value_lists，canvas_summary，find_components，set_toggle，select_value_list，list_blocks，set_view。 剩余：bake_to_rhino，group_components，measure_distance | | **P5** | 🟡 | 技能库 - 已完成：landform，ladybug-environmental（草案），facade-design，rhino-gh-bridge-basics。 计划中：massing，structural grid，daylighting | | **P6** | ⏳ | 可流式 HTTP 传输 + 一个薄的 web 前端 | | **P7** | ✅ | `.mcpb` 桌面扩展 + Yak 包 - 参见 `scripts/build-mcpb.sh`， `scripts/build-yak.sh`， [docs/packaging-status.md](docs/packaging-status.md) | | **P8** | ⏳ | 面向学生的教学包 | --- ## 许可 MIT - 参见 [LICENSE](./LICENSE). --- ## 贡献 欢迎提交拉取请求，尤其是： - 新的建筑工作流技能（参见 [skills/README.md](skills/README.md) 了解格式）。 - 特定Rhino 8版本下的错误报告（粘贴 `rhino_version` 信息）。 - 您期望存在的命令形状的桥接处理程序。