大家好我是专注于技术实战分享的博主。今天我们来开启一个全新的系列教程——CodexSketchUp 实时建模 MCP 插件开发。如果你是一名建筑、室内设计或游戏场景的开发者厌倦了在建模软件和代码编辑器之间反复切换或者想通过AI辅助实现更智能的参数化设计那么这个系列正是为你准备的。我们将手把手教你如何搭建一个连接AI大脑Codex与3D建模工具SketchUp的实时交互桥梁。通过本系列第一课你将能独立完成从零开始的环境搭建包括SketchUp的安装、Ruby开发环境的配置、以及初步理解MCPModel 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)这是本系列的核心创新点。你可以将其理解为一套通信协议或中间件。它的职责是翻译接收来自CodexAI的自然语言指令。转换将这些指令“翻译”成SketchUp Ruby API能够理解和执行的代码。执行与反馈在SketchUp中执行生成的代码并将操作结果成功、失败、生成的实体信息反馈给用户或AI形成一个闭环。1.2 解决的问题与工作流程传统的建模工作流是线性的思考 - 手动操作软件 - 查看结果 - 修正。而我们的“Codex SketchUp MCP”架构旨在创建一个实时、交互式的建模环境。理想的工作流程如下用户输入用户在插件界面或聊天窗口中输入自然语言描述例如“在场景中央创建一个半径为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)。MCP桥接MCP插件捕获这段生成的代码。在SketchUp中执行MCP插件在SketchUp的Ruby环境中安全地执行这段代码。实时呈现结果SketchUp界面中立刻出现创建的球体。用户可以看到实时反馈并可以继续输入下一指令如“将它向上移动3米”。这个流程极大地降低了复杂参数化建模或批量操作的门槛将创意快速可视化。2. 环境准备与安装清单工欲善其事必先利其器。下面列出完成本课所需的所有软件和工具。请务必根据你的操作系统Windows/macOS选择对应的版本。组件推荐版本下载/安装说明必备性SketchUpSketchUp Pro 2022 或 SketchUp 2023从官网下载试用版或使用正版。本教程以SketchUp Pro为例。必需Ruby 解释器与 SketchUp 捆绑的 Ruby (如 2.7.x)SketchUp 已内置无需单独安装。我们主要用它。必需代码编辑器Visual Studio Code (VSCode)官网下载安装。轻量且插件生态丰富适合编辑Ruby等脚本。强烈推荐VSCode 插件Ruby, SketchUp Extension 等在VSCode扩展商店搜索安装用于代码高亮和提示。推荐文本编辑器任意如 Notepad, Sublime Text备用用于快速查看和编辑.rb文件。可选重要版本说明 SketchUp 不同版本内置的 Ruby 版本不同例如 SU 2021 用 Ruby 2.5 SU 2023 用 Ruby 2.7。这会导致一些语法和库的兼容性差异。本系列教程的代码将尽量保证在 Ruby 2.5 上运行。建议初学者使用较新的 SketchUp 版本如2022/2023以获得更好的兼容性和更现代的API支持。3. 第一步安装与配置 SketchUp这是我们的主战场所有建模和插件运行都发生在这里。3.1 下载与安装 SketchUp访问 SketchUp 官方网站。根据你的操作系统选择“下载”版本。对于学习和开发可以选择“SketchUp Pro”的试用版通常有30天试用期。运行下载的安装程序按照向导完成安装。安装路径建议使用默认路径避免不必要的权限问题。3.2 验证 Ruby 环境安装完成后我们需要确认 SketchUp 自带的 Ruby 环境。打开 SketchUp。在顶部菜单栏找到扩展程序-Ruby 控制台。如果找不到可以尝试窗口-Ruby 控制台。会弹出一个命令行窗口。在这里输入puts RUBY_VERSION然后按回车。控制台会输出当前 Ruby 的版本号例如2.7.0。请记下这个版本号后续编写代码时需要注意语法兼容性。恭喜至此SketchUp 和其 Ruby 引擎已就绪。这个 Ruby 控制台是我们测试代码片段、调试插件的关键工具。4. 第二步配置代码编辑器与开发环境虽然可以直接在 Ruby 控制台写代码但效率太低。我们需要一个强大的编辑器来管理我们的插件项目。4.1 安装与配置 Visual Studio Code安装 VSCode从官网下载并安装。安装 Ruby 相关扩展打开 VSCode点击左侧活动栏的“扩展”图标或按CtrlShiftX。搜索并安装Ruby扩展由 Peng Lv 开发。这个扩展提供了语法高亮、代码片段、linting 等基础功能。搜索并安装Ruby Solargraph扩展可选但推荐。它能提供更智能的代码补全和文档提示但需要额外配置初学者可先跳过。可选配置工作区为你未来的插件项目创建一个单独的文件夹例如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 编写插件入口文件在你的插件目录例如C:\Users\YourName\AppData\Roaming\SketchUp\SketchUp 2023\SketchUp\Plugins\下创建一个新文件夹命名为mcp_bridge。在该文件夹内用 VSCode 或任何文本编辑器创建一个新文件命名为mcp_bridge.rb。这个文件将是插件的入口。将以下代码复制到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 MCPBridge5.2 代码解析与运行测试保存文件。重启 SketchUp。这是加载新插件或修改后插件的最可靠方式。重启后你应该会立即看到一个弹出窗口显示“MCP Bridge 插件加载成功”和 Ruby 版本号。同时SketchUp 界面中应该会出现一个名为 “MCP Bridge” 的新工具栏上面有一个按钮。点击这个“测试MCP”按钮插件会在坐标原点 (0,0,0) 创建一个边长为1米的立方体并弹出提示框。打开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) end6.2 测试本地代码执行保存mcp_bridge.rb文件。在 SketchUp 中点击扩展程序-Reload Extensions重新加载所有插件。这样就不需要重启 SketchUp。你的 “MCP Bridge” 工具栏上现在应该有两个按钮。点击新加的“执行代码”按钮。在弹出的输入框中已经有一行示例代码Sketchup.active_model.entities.add_circle([0,0,0], [0,0,1], 500.mm)。这行代码的作用是在原点创建一个半径为500毫米的圆。直接点击“确定”。如果一切正常你会在场景原点看到一个圆并弹出“执行成功”的提示。你可以尝试修改代码例如将500.mm改为1000.mm或者将[0,0,1]法向量改为[1,0,0]看看创建出的圆有何不同。这个模拟实验的意义在于我们成功构建了一个最小化的MCP执行引擎。它的输入是一段文本Ruby代码输出是在SketchUp中执行这段代码的结果。未来我们只需要将输入源从手动输入替换为从AI服务如Codex API获取的代码即可。7. 常见问题与排查思路在环境配置和初步开发中你可能会遇到以下问题问题现象可能原因排查与解决思路插件加载无任何反应1. 插件文件未放在正确的Plugins目录。2. 文件扩展名不是.rb。3. Ruby 代码存在语法错误导致加载失败。1. 双击检查插件文件完整路径。2. 确保文件是纯文本并以.rb结尾。3. 打开 Ruby 控制台重启 SketchUp查看控制台是否有红色错误信息。Ruby 控制台不显示菜单位置因版本不同而变化。尝试扩展程序-Ruby 控制台或窗口-Ruby 控制台。也可以在窗口-偏好设置-扩展程序中检查相关设置。eval执行代码时报安全错误SketchUp 的安全限制或代码试图访问危险操作。这是正常限制。我们目前的模拟环境在 SketchUp 内部运行eval是受限可用的。未来与外部服务通信时需要更严格的安全沙箱机制这属于进阶内容。创建的几何体看不到1. 创建在了远离原点的地方。2. 创建的实体尺寸太小或太大。3. 视图被移动了。1. 使用Zoom Extents工具快捷键ShiftZ显示全部模型。2. 检查代码中的坐标和尺寸单位如.m,.mm,.cm。修改插件代码后变化未生效SketchUp 缓存了已加载的插件。最可靠的方法是重启 SketchUp。也可以尝试扩展程序-Reload Extensions但并非所有修改都能热重载。工具栏按钮是灰色的命令UI::Command在创建时未正确添加到工具栏或工具栏未显示。检查代码中toolbar.add_item(cmd)是否执行以及toolbar.show是否被调用。确保代码在模块加载时运行。8. 最佳实践与下一步学习路线8.1 环境配置最佳实践版本管理记录下你使用的 SketchUp 和 Ruby 版本。当分享代码或查找解决方案时版本信息至关重要。项目目录分离在Plugins目录下为每个插件创建独立的子文件夹便于管理资源文件如图标、HTML对话框等。使用版本控制立即为你的mcp_bridge插件文件夹初始化一个 Git 仓库。这是管理代码变更、回溯历史和协作的基础。备份Plugins目录在对插件进行重大修改前备份整个Plugins目录以防 SketchUp 无法启动。8.2 代码编写建议模块化将不同功能的代码放在不同的模块module或类class中避免所有代码堆在一个文件里。我们的MCPBridge模块就是一个好的开始。错误处理始终使用begin-rescue块包裹可能出错的代码尤其是执行外部输入或网络操作时并向用户提供友好的错误信息就像我们在“执行代码”命令中做的那样。日志输出善用puts向 Ruby 控制台输出调试信息这是最直接的调试手段。可以为不同模块的信息加上前缀如[MCP Network],[MCP Parser]。尊重 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 插件的核心工作原理。