大家好，我是专注于技术实战分享的博主。今天我们来开启一个全新的系列教程——Codex+SketchUp 实时建模 MCP 插件开发。如果你是一名建筑、室内设计或游戏场景的开发者，厌倦了在建模软件和代码编辑器之间反复切换，或者想通过AI辅助实现更智能的参数化设计，那么这个系列正是为你准备的。我们将手把手教你如何搭建一个连接AI大脑（Codex）与3D建模工具（SketchUp）的实时交互桥梁。

通过本系列第一课，你将能独立完成从零开始的环境搭建，包括SketchUp的安装、Ruby开发环境的配置、以及初步理解MCP（Model Control Protocol）插件的基本结构。无论你是编程新手还是有一定经验的开发者，只要跟着步骤走，就能成功搭建起这个充满潜力的开发环境。

1. 核心概念与背景：为什么需要 Codex + SketchUp + MCP？

在深入安装步骤之前，我们有必要厘清这几个核心组件分别是什么，以及它们组合在一起能解决什么痛点。

1.1 组件拆解：各司其职的三驾马车

• SketchUp：这是一款广为人知的三维建模软件，以其直观易用的操作和强大的社区插件生态著称。它广泛应用于建筑设计、室内设计、城市规划、游戏场景搭建等领域。SketchUp支持通过Ruby语言进行二次开发，这为我们自定义功能提供了可能。
• Codex：这里通常指的是OpenAI的Codex模型，它是GPT-3的后代，特别擅长理解和生成编程代码。在本系列的语境中，我们将其泛指为能够理解自然语言并生成对应操作指令或代码的AI引擎。我们的目标是让用户用自然语言（如“在原点创建一个长5米、宽3米、高2.7米的盒子”）来控制SketchUp。
• MCP (Model Control Protocol)：这是本系列的核心创新点。你可以将其理解为一套通信协议或中间件。它的职责是：
  1. 翻译：接收来自Codex（AI）的自然语言指令。
  2. 转换：将这些指令“翻译”成SketchUp Ruby API能够理解和执行的代码。
  3. 执行与反馈：在SketchUp中执行生成的代码，并将操作结果（成功、失败、生成的实体信息）反馈给用户或AI，形成一个闭环。

1.2 解决的问题与工作流程

传统的建模工作流是线性的：思考 -> 手动操作软件 -> 查看结果 -> 修正。而我们的“Codex + SketchUp + MCP”架构旨在创建一个实时、交互式的建模环境。

理想的工作流程如下：

1. 用户输入：用户在插件界面或聊天窗口中输入自然语言描述，例如：“在场景中央创建一个半径为2米的球体。”
2. AI理解与生成：Codex（或类似AI）理解该描述，并生成一段符合SketchUp Ruby API规范的代码片段，例如：ents = Sketchup.active_model.entities; circle = ents.add_circle([0,0,0], [0,0,1], 2.m); face = ents.add_face(circle)。
3. MCP桥接：MCP插件捕获这段生成的代码。
4. 在SketchUp中执行：MCP插件在SketchUp的Ruby环境中安全地执行这段代码。
5. 实时呈现结果：SketchUp界面中立刻出现创建的球体。用户可以看到实时反馈，并可以继续输入下一指令，如“将它向上移动3米”。

这个流程极大地降低了复杂参数化建模或批量操作的门槛，将创意快速可视化。

2. 环境准备与安装清单

工欲善其事，必先利其器。下面列出完成本课所需的所有软件和工具。请务必根据你的操作系统（Windows/macOS）选择对应的版本。

重要版本说明： SketchUp 不同版本内置的 Ruby 版本不同（例如 SU 2021 用 Ruby 2.5， SU 2023 用 Ruby 2.7）。这会导致一些语法和库的兼容性差异。本系列教程的代码将尽量保证在 Ruby 2.5+ 上运行。建议初学者使用较新的 SketchUp 版本（如2022/2023），以获得更好的兼容性和更现代的API支持。

3. 第一步：安装与配置 SketchUp

这是我们的主战场，所有建模和插件运行都发生在这里。

3.1 下载与安装 SketchUp

1. 访问 SketchUp 官方网站。
2. 根据你的操作系统选择“下载”版本。对于学习和开发，可以选择“SketchUp Pro”的试用版（通常有30天试用期）。
3. 运行下载的安装程序，按照向导完成安装。安装路径建议使用默认路径，避免不必要的权限问题。

3.2 验证 Ruby 环境

安装完成后，我们需要确认 SketchUp 自带的 Ruby 环境。

1. 打开 SketchUp。
2. 在顶部菜单栏找到扩展程序->Ruby 控制台。如果找不到，可以尝试窗口->Ruby 控制台。
3. 会弹出一个命令行窗口。在这里输入puts RUBY_VERSION然后按回车。
4. 控制台会输出当前 Ruby 的版本号，例如2.7.0。请记下这个版本号，后续编写代码时需要注意语法兼容性。

恭喜！至此，SketchUp 和其 Ruby 引擎已就绪。这个 Ruby 控制台是我们测试代码片段、调试插件的关键工具。

4. 第二步：配置代码编辑器与开发环境

虽然可以直接在 Ruby 控制台写代码，但效率太低。我们需要一个强大的编辑器来管理我们的插件项目。

4.1 安装与配置 Visual Studio Code

1. 安装 VSCode：从官网下载并安装。
2. 安装 Ruby 相关扩展：
   • 打开 VSCode，点击左侧活动栏的“扩展”图标（或按Ctrl+Shift+X）。
   • 搜索并安装Ruby扩展（由 Peng Lv 开发）。这个扩展提供了语法高亮、代码片段、linting 等基础功能。
   • 搜索并安装Ruby Solargraph扩展（可选但推荐）。它能提供更智能的代码补全和文档提示，但需要额外配置，初学者可先跳过。
3. （可选）配置工作区：为你未来的插件项目创建一个单独的文件夹，例如D:\Dev\SketchUp_MCP_Plugin。在 VSCode 中打开这个文件夹，作为你的工作区。

4.2 理解 SketchUp 插件目录结构

SketchUp 插件通常存放在特定的用户目录下。了解这个结构对插件开发和部署至关重要。

• Windows:
  • C:\Users\[你的用户名]\AppData\Roaming\SketchUp\SketchUp 2023\SketchUp\Plugins\
  • AppData是隐藏文件夹，需要在文件管理器选项中设置“显示隐藏的文件、文件夹和驱动器”。
• macOS:
  • ~/Library/Application Support/SketchUp 2023/SketchUp/Plugins/

插件加载机制：SketchUp 启动时，会自动加载Plugins文件夹及其子文件夹下所有以.rb为扩展名的文件。一个插件可以是一个单独的.rb文件，也可以是一个包含多个文件的子文件夹（通常其中会有一个同名的.rb文件作为入口）。

5. 第三步：创建你的第一个 MCP 插件原型

现在，让我们动手创建第一个最简单的插件，它不涉及 AI，只验证我们的环境是否畅通，并理解插件的基本形式。

5.1 编写插件入口文件

1. 在你的插件目录（例如C:\Users\YourName\AppData\Roaming\SketchUp\SketchUp 2023\SketchUp\Plugins\）下，创建一个新文件夹，命名为mcp_bridge。
2. 在该文件夹内，用 VSCode 或任何文本编辑器创建一个新文件，命名为mcp_bridge.rb。这个文件将是插件的入口。
3. 将以下代码复制到mcp_bridge.rb中：

# mcp_bridge.rb - 第一个MCP插件原型 # 该文件位于 SketchUp 的 Plugins 目录下的 mcp_bridge 文件夹内 module MCPBridge # 定义一个模块，用于组织我们的功能 # 加载插件时显示欢迎信息 unless file_loaded?(__FILE__) UI.messagebox("🎉 MCP Bridge 插件加载成功！\nRuby 版本：#{RUBY_VERSION}") puts "[MCP Bridge] 初始化完成，环境正常。" file_loaded(__FILE__) end # 创建一个简单的工具栏（可选） toolbar = UI::Toolbar.new("MCP Bridge") # 创建一个命令，用于测试 cmd = UI::Command.new("测试MCP") { # 在场景原点创建一个立方体 model = Sketchup.active_model entities = model.entities # 定义立方体的一个角点 point1 = Geom::Point3d.new(0, 0, 0) point2 = Geom::Point3d.new(1.m, 1.m, 1.m) # 1米边长的立方体 # 添加一个长方体（实体） group = entities.add_group face = group.entities.add_face(point1, Geom::Point3d.new(1.m, 0, 0), Geom::Point3d.new(1.m, 1.m, 0), Geom::Point3d.new(0, 1.m, 0)) face.pushpull(1.m) if face model.selection.clear model.selection.add(group) UI.messagebox("已在原点创建了一个1x1x1米的立方体！") } cmd.small_icon = cmd.large_icon = File.join(__dir__, "icon.png") rescue nil cmd.tooltip = "MCP Bridge 测试命令" cmd.status_bar_text = "创建一个测试立方体" toolbar = toolbar.add_item(cmd) toolbar.show end # module MCPBridge

5.2 代码解析与运行测试

1. 保存文件。
2. 重启 SketchUp。这是加载新插件或修改后插件的最可靠方式。
3. 重启后，你应该会立即看到一个弹出窗口，显示“MCP Bridge 插件加载成功！”和 Ruby 版本号。同时，SketchUp 界面中应该会出现一个名为 “MCP Bridge” 的新工具栏，上面有一个按钮。
4. 点击这个“测试MCP”按钮，插件会在坐标原点 (0,0,0) 创建一个边长为1米的立方体，并弹出提示框。
5. 打开Ruby 控制台，你应该能看到输出的[MCP Bridge] 初始化完成，环境正常。信息。

这个简单的原型验证了：

• 你的插件目录位置正确。
• SketchUp 能成功加载并执行你的 Ruby 代码。
• 你能够通过代码操作 SketchUp 的模型实体（Entities）。
• 你可以创建用户界面元素（工具栏、按钮）。

6. 第四步：搭建本地“伪MCP”服务器（概念验证）

真正的 MCP 涉及与外部 AI 服务的网络通信。作为第一课，我们先在本地模拟一个最简单的“指令-执行”循环，理解其原理。

我们将创建一个简单的文本输入框，用户输入类Ruby代码，插件负责执行它。这模拟了AI生成代码 -> MCP执行的过程。

6.1 扩展插件代码

在刚才的mcp_bridge.rb文件中，我们添加新的功能。为了清晰，我们可以在模块内添加新的方法。以下是更新后的部分代码（你可以接在原有代码后面）：

module MCPBridge # ... 之前的初始化代码和工具栏创建代码 ... # 新增：创建第二个命令，用于打开代码执行面板 cmd_exec = UI::Command.new("执行代码") { # 显示一个输入对话框，让用户输入Ruby代码 prompts = ["输入要执行的SketchUp Ruby代码:"] defaults = ["Sketchup.active_model.entities.add_circle([0,0,0], [0,0,1], 500.mm)"] input = UI.inputbox(prompts, defaults, "MCP 代码执行器") if input code_to_exec = input[0] begin # 关键步骤：使用 eval 在 SketchUp 的上下文中执行字符串代码 result = eval(code_to_exec) UI.messagebox("执行成功！\n返回结果：#{result.inspect}") puts "[MCP Exec] 执行代码：#{code_to_exec}" puts "[MCP Exec] 返回结果：#{result}" rescue StandardError => e UI.messagebox("执行出错！\n错误信息：#{e.message}\n回溯：#{e.backtrace.join("\n")}") puts "[MCP Exec ERROR] #{e.message}" end end } cmd_exec.tooltip = "执行输入的Ruby代码" toolbar.add_item(cmd_exec) end

6.2 测试本地代码执行

1. 保存mcp_bridge.rb文件。
2. 在 SketchUp 中，点击扩展程序->Reload Extensions重新加载所有插件。这样就不需要重启 SketchUp。
3. 你的 “MCP Bridge” 工具栏上现在应该有两个按钮。
4. 点击新加的“执行代码”按钮。
5. 在弹出的输入框中，已经有一行示例代码：Sketchup.active_model.entities.add_circle([0,0,0], [0,0,1], 500.mm)。这行代码的作用是在原点创建一个半径为500毫米的圆。
6. 直接点击“确定”。如果一切正常，你会在场景原点看到一个圆，并弹出“执行成功”的提示。
7. 你可以尝试修改代码，例如将500.mm改为1000.mm，或者将[0,0,1]（法向量）改为[1,0,0]，看看创建出的圆有何不同。

这个模拟实验的意义在于：我们成功构建了一个最小化的MCP执行引擎。它的输入是一段文本（Ruby代码），输出是在SketchUp中执行这段代码的结果。未来，我们只需要将输入源从手动输入替换为从AI服务（如Codex API）获取的代码即可。

7. 常见问题与排查思路

在环境配置和初步开发中，你可能会遇到以下问题：

8. 最佳实践与下一步学习路线

8.1 环境配置最佳实践

1. 版本管理：记录下你使用的 SketchUp 和 Ruby 版本。当分享代码或查找解决方案时，版本信息至关重要。
2. 项目目录分离：在Plugins目录下为每个插件创建独立的子文件夹，便于管理资源文件（如图标、HTML对话框等）。
3. 使用版本控制：立即为你的mcp_bridge插件文件夹初始化一个 Git 仓库。这是管理代码变更、回溯历史和协作的基础。
4. 备份Plugins目录：在对插件进行重大修改前，备份整个Plugins目录，以防 SketchUp 无法启动。

8.2 代码编写建议

1. 模块化：将不同功能的代码放在不同的模块（module）或类（class）中，避免所有代码堆在一个文件里。我们的MCPBridge模块就是一个好的开始。
2. 错误处理：始终使用begin-rescue块包裹可能出错的代码（尤其是执行外部输入或网络操作时），并向用户提供友好的错误信息，就像我们在“执行代码”命令中做的那样。
3. 日志输出：善用puts向 Ruby 控制台输出调试信息，这是最直接的调试手段。可以为不同模块的信息加上前缀，如[MCP Network],[MCP Parser]。
4. 尊重 SketchUp API：仔细阅读 SketchUp Ruby API 文档，了解如何正确创建、选择和修改实体。错误的 API 使用可能导致模型损坏。

8.3 系列课后续展望

第一课我们成功搭建了地基。在接下来的课程中，我们将逐步深入：

• 第二课：深入 SketchUp Ruby API- 学习如何创建、编辑、查询各种几何图形和组件，这是 MCP 能执行哪些操作的基础。
• 第三课：构建 MCP 通信层- 使用 Ruby 的net/http或websocket库，让我们的插件能与本地或远程的 AI 服务（模拟 Codex）进行 HTTP/WebSocket 通信，接收自然语言指令。
• 第四课：自然语言到代码的转换器- 设计一个简单的解析器或规则引擎，初步实现将固定的自然语言命令（如“创建长方体”）映射为 Ruby 代码。这是连接 AI 与 API 的关键。
• 第五课：集成真实 AI 服务- 探索如何安全地调用 OpenAI API 或其他大语言模型 API，将用户的自然语言描述转换为 SketchUp Ruby 代码，并通过 MCP 层执行。
• 第六课：插件 UI 优化与打包发布- 设计更友好的用户界面，并将插件打包成可分发的.rbz文件。

环境配置是万里长征的第一步，也是最容易踩坑的一步。如果你成功完成了本课的所有操作，看到了弹出的欢迎框和创建的立方体，那么恭喜你，你已经拥有了一个功能完备的 SketchUp 插件开发环境，并理解了 MCP 插件的核心工作原理。