内容
# wasp-mcp
克劳德（或任何MCP客户端）将 **Wasp** 离散聚合组件和一般的Grasshopper定义放置在实时的Grasshopper画布上，并提供基于证据的组件知识、易读的自动组织输出和视口捕获，以便模型可以查看其创建的内容。
```
克劳德 ── MCP (stdio) ── 服务器/ (Python FastMCP, uv)
│ TCP 127.0.0.1:8090 (JSON, 参见 PROTOCOL.md)
GH_MCP_Wasp.gha — "WaspMCP" 组件在 GH 画布上
│ GH_Document API, UI线程封送
Grasshopper 画布 ← Wasp .ghuser 组件
```
两个独立的部分，分别安装：一个 **Grasshopper 插件** （桥梁）和一个 **Python MCP 服务器** （克劳德对话）。下面将详细介绍这两个部分。
## 首先需要
| 需求 | 需要用于 | 如何获取 |
|---|---|---|
| Windows + **Rhino 8** | 画布（Grasshopper 包含在 Rhino 中） | [rhino3d.com](https://www.rhino3d.com/download/) — 90 天试用期有效 |
| **克劳德桌面版** | 驱动画布的 AI（任何 MCP 客户端都有效；以下说明假设克劳德桌面版） | [claude.ai/download](https://claude.ai/download) — 免费层级即可 |
| **uv** | 运行 Python 服务器 | 在 PowerShell 中：`irm https://astral.sh/uv/install.ps1 \| iex`（步骤 2 中的安装程序检查并打印该命令，如果缺少） |
| **Wasp** *(可选)* | 聚合工作流（`create_wasp_part`, `run_aggregation`, …）。一般 Grasshopper 控制和架构模板无需 Wasp 即可工作 | [Food4Rhino](https://www.food4rhino.com/en/app/wasp) （免费帐户）→ 下载 → 将安装程序拖放到 Rhino 中 |
## 步骤 1 — 安装桥梁插件（Grasshopper 端）
在 Rhino 8 中，输入 `_PackageManager`，搜索 **`wasp-mcp-bridge`**，点击 **安装**，重启 Rhino。完成。
<details>
<summary>手动替代（无软件包管理器）</summary>
从 [最新版本](https://github.com/liangjunglj-cpu/wasp-mcp/releases/latest) 下载 `GH_MCP_Wasp.gha`，复制到 `%APPDATA%\Grasshopper\Libraries\`，在资源管理器中右键单击 → 属性 → **取消阻止**，重启 Rhino。
</details>
## 步骤 2 — 安装 MCP 服务器（克劳德端）
服务器在 PyPI 上为 [`wasp-mcp-server`](https://pypi.org/project/wasp-mcp-server/) — 无需克隆。在 `%APPDATA%\Claude\claude_desktop_config.json` （克劳德桌面版）中，在 `mcpServers` 下添加以下内容，或者运行 `claude mcp add WaspMCP -- uvx wasp-mcp-server` （克劳德代码）：
```json
{
"mcpServers": {
"WaspMCP": {
"command": "uvx",
"args": ["wasp-mcp-server"]
}
}
}
```
### 开发者替代：从检出运行
克隆此仓库（或下载并提取发布源 zip），然后从仓库根目录在 PowerShell 中：
```powershell
powershell -ExecutionPolicy Bypass -File tools\install\install.ps1
```
安装程序是幂等的（安全地重新运行），并且：
- 验证 Rhino 8 / Grasshopper / uv / Wasp（警告，但从不阻止）
- 如果跳过步骤 1，则安装桥梁 `.gha`
- 在 `%APPDATA%\Claude\claude_desktop_config.json` 中添加 `WaspMCP` 条目，指向此仓库的位置 — 保留其他 MCP 服务器并首先备份配置
**安装后不要移动或删除仓库文件夹** — 服务器从中运行。
选项：`-Port <n>` / `-Token <secret>` （参见“端口和身份验证”），`-DryRun` （打印所有内容，写入无）。`tools\install\uninstall.ps1` 撤销所有操作。
最后，**重启克劳德桌面应用程序** （完全退出系统托盘 — 关闭窗口不够），使其获取新的服务器。
<details>
<summary>手动替代（手动编辑配置）</summary>
在 `%APPDATA%\Claude\claude_desktop_config.json` 中，在 `mcpServers` 下添加此条目，两个路径都扩展为实际绝对路径（克劳德桌面版不扩展环境变量）：
```json
"WaspMCP": {
"command": "C:\\Users\\<you>\\.local\\bin\\uv.exe",
"args": ["--directory", "C:\\path\\to\\wasp-mcp\\server", "run", "wasp-mcp-server"]
}
```
然后重启克劳德桌面应用程序。
</details>
## 步骤 3 — 将桥梁放在画布上并启用
桥梁仅在其组件位于 Grasshopper 画布上且 `Enabled` 设置为 true 时才运行：
1. 打开 **Rhino 8**，输入 `Grasshopper` 以打开画布。
2. 双击任意空白画布空间，输入 **`WaspMCP`**，然后单击 **Wasp MCP Bridge** 以放置它。（它也位于 **Params → Util** 下的组件面板中。）
3. 为其开关添加切换：再次双击空白画布，输入 **`toggle`**，选择 **Boolean Toggle** （Params → Input）并将其放置在桥梁组件的左侧。
4. 将切换的输出连接到桥梁的 **`Enabled`** 输入（从切换的右侧连接点拖动到输入的左侧连接点）。
5. 双击切换的 **False** 标签，使其翻转为 **True**。桥梁组件现在报告它正在 `127.0.0.1:8090` 上监听。
**验证端到端**：在克劳德桌面版中，询问 *"检查 wasp-mcp 画布状态"* — 您应该收到一个组件列表和一个版本字符串。如果安装了 Wasp，请尝试 *"列出此机器上的 wasp 组件"*，或直接进行 *"从简单盒子零件构建随机聚合"*。
## 之后的每个会话
Rhino 8 + Grasshopper 打开，WaspMCP 组件在画布上，切换为 True（将其保存在模板文件中，因此只需单击一次）。其他所有操作都是自动的。
## 端口和身份验证（PROTOCOL v0.5）
- 桥梁监听 **本地主机 TCP，默认端口 8090**。要更改它，请设置组件的 `Port` 输入 **和** 配置条目中的 `WASP_MCP_PORT` 环境变量为相同的值（`install.ps1 -Port <n>` 为您写入）。
- 可选的共享密钥身份验证：设置组件的 `Token` 输入和配置条目中的 `WASP_MCP_TOKEN` 环境变量为相同的值（`install.ps1 -Token <secret>`）。空/不存在令牌 = 开放访问（无论哪种方式，都仅限本地主机）
## 工具表面
- `list_wasp_components` / `refresh_registry` — 发现已安装的 Wasp 组件
- `gh_add_wasp_component`, `gh_add_component`, `gh_connect`, `gh_set_slider`, `gh_set_panel`, `gh_set_geometry_ref`, `gh_set_plane_values`, `gh_set_toggle`, `gh_get_output`, `gh_canvas_state`, `gh_expire`, `gh_wait_idle`, `gh_bake`, `gh_delete`, `gh_clear`, `gh_save`, `gh_group`, `gh_scribble`, `gh_set_nickname`, `gh_workflow_note`, `gh_list_component_types`, `gh_component_schema` — 画布控制和内省
- `create_wasp_part`, `define_rules`, `run_aggregation`, `get_aggregation`, `reset_aggregation` — 高级 Wasp 宏（一次调用 = 一个连接的子图）
- `list_templates`, `expand_template` — 基于证据的架构阶段模板（吸引子网格，桁架，轮廓，...）
- `gh_capture_viewport`, `gh_capture_canvas` — 让模型看到结果
## 文档
- [docs/architecture.md](docs/architecture.md) — 流程，线程，设计决策
- [docs/tool-reference.md](docs/tool-reference.md) — 每个工具：参数，返回形状，错误
- [docs/cookbook.md](docs/cookbook.md) — 复制粘贴 Wasp 工作流提示 + 规则语法入门
- [docs/troubleshooting.md](docs/troubleshooting.md) — 扩展修复（端口，超时，.gha 升级）
- [docs/development.md](docs/development.md) — 扩展系统；PROTOCOL.md 保持绑定规范
## 布局
| 路径 | 内容 |
|---|---|
| `PROTOCOL.md` | 绑定线规格 |
| `server/` | Python MCP 服务器 |
| `GH_MCP_Wasp/` | C# 桥梁源代码（net48） |
| `build/` | 编译的 `.gha` |
| `tools/install/` | install.ps1 / uninstall.ps1 |
| `tools/yak/` | Yak 包清单 + 构建脚本 |
## 重建桥梁
```powershell
cd GH_MCP_Wasp
dotnet build -c Release
```
（`tools\yak\build-yak.ps1` 从 `build\GH_MCP_Wasp.gha` 构建并构建 Yak 包 — 仅当您发布自己的构建时需要；已发布的包已经在 Rhino 包服务器上。）
## 故障排除
- `bridge_unreachable` — WaspMCP 组件不在画布上 / 切换为真 / Grasshopper 未打开。
- `_PackageManager` 搜索中无内容 — 软件包需要 Windows 上的 Rhino 8；如果您处于早期服务版本，请更新 Rhino。
- 端口冲突 — 为服务器和组件的端口输入设置匹配的值（默认 8090）。
- 安装新 Wasp 版本后注册表过时 — 调用 `refresh_registry`。
## 许可
代码为 [MIT](LICENSE)。`server/knowledge/` 下的知识库数据文件可免费与 wasp-mcp 一起使用，但不可重新分发 — 请参阅 [server/knowledge/LICENSE-KNOWLEDGE.md](server/knowledge/LICENSE-KNOWLEDGE.md)。第三方属性：[THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md)。
