🚀 SketchupMCP - Sketchup 模型上下文协议（MCP）整合

SketchupMCP 通过模型上下文协议（MCP）将 Sketchup 连接到 Claude AI，使 Claude 能够直接与 Sketchup 进行交互和控制。这项整合允许使用提示辅助 3D 建模、场景创建和操作 Sketchup。

特别感谢 mhyrr/sketchup-mcp 提供的架构。我们对其原生版本（mhyrr/sketchup-mcp）进行了简体中文化及部分功能优化与调整。

🚀 快速开始

SketchupMCP 借助模型上下文协议（MCP），实现了 Sketchup 与 Claude AI 的连接，让 Claude 可直接与 Sketchup 交互和控制。下面为你介绍如何快速开启使用之旅。

连线设置

1. 启动服务器：在终端执行以下命令：

python -m sketchupmcp.server --host localhost --port 8000

2. 启用扩展并连线：
   • 打开 Sketchup。
   • 启用 SketchupMCP 插件，选择服务器 IP 和端口连接服务器。

✨ 主要特性

• 双向通信：通过 TCP 套接字连接 Claude AI 与 Sketchup。
• 组件操作：在 Sketchup 中创建、修改、删除和变换组件。
• 材质控制：应用和修改材质与颜色。
• 场景检查：获取当前 Sketchup 场景的详细信息。
• 选取处理：获取并操作选定的组件。
• Ruby 代码执行：使用 Ruby 语言进行复杂的建模操作。

📦 安装指南

Sketchup 扩展安装

1. 下载并安装 Sketchup：官网下载地址：Sketchup 官方网站。
2. 启动软件并安装扩展：
   • 打开 Sketchup。
   • 进入 “编辑” 菜单，选择 “扩展库”。
   • 在可用的扩展中找到并安装 SketchupMCP。
3. 启用插件：
   • 安装完成后，在工具栏中找到 SketchupMCP 图标。
   • 点击图标以启动插件，并按照提示连接至 MCP 服务器。

Python 套件安装

1. 安装 Python 环境：推荐使用 Anaconda 或 Pyenv 管理多版本环境。
2. 安装依赖库：开启终端，执行命令：

pip install sketchupmcp

3. 启动服务器：使用以下命令启动 MCP 服务器：

python -m sketchupmcp.server --host <IP> --port <PORT>

调整 <IP> 和 <PORT> 确保与 Sketchup 扩展连线正常。

💻 使用示例

基础用法

以下是一些常见的操作指令示例：

基本命令

{
    "type": "create_house",
    "params": {
        "roof_type": "gabled",
        "window_count": 4
    }
}

选取操作

{
    "type": "select_components"
}

颜色修改

{
    "type": "change_color",
    "params": {
        "color": "#FF0000"
    }
}

📚 详细文档

系统结构

概述

SketchupMCP 系统包含以下主要部分：

1. Sketchup 扩展：
   • 功能：提供 Sketchup 平台与外部服务器之间的通信桥接。
   • 作用：接收用户指令并通过 TCP 套接字传送至服务器，同时将服务器回应传送回客户端。
2. MCP 服务器：
   • 功能：负责处理来自 Sketchup 扩展的请求，并执行相应的操作。
   • 作用：解析指令、执行建模或操作，然后将结果反馈给客户端。

具体结构

• Sketchup 扩展：
  • 安装步骤：
    1. 下载并安装 Sketchup。
    2. 启动软件后，在扩展库中安装 SketchupMCP 插件。
    3. 开启插件后，根据提示连接至 MCP 服务器。
• MCP 服务器：
  • 安装步骤：
    1. 安装 Python 环境（建议使用最新版本）。
    2. 使用 Git 克隆 SketchupMCP 专案仓库。
    3. 启动服务器后，设定 IP 和端口等待客户端连线。

疑难排解

连线问题

1. 服务器未启动：检查服务器端是否已正确启动，并显示待机讯息。
2. 防火墙干扰：确保服务器端的防火墙允许 TCP 端口连线。
3. 网络问题：使用 ping 命令测试服务器和客户端之间的网络连通性。

操作失败

1. 检查错误讯息：查看 Sketchup 的 Ruby 控制台，捕获并分析错误讯息。
2. 重启服务：有时简单地重新启动服务器和客户端可以解决瞬间异常。

高级调试

• 日志记录：

python -m sketchupmcp.server --log-level DEBUG

• 错误回溯：确保所有第三方库已更新至最新版本，以避免潜在的兼容性问题。

安全考量

认证机制

1. 用户身份验证：采用令牌认证方式，确保只有授权用户能连线服务器。
2. 数据加密：使用 SSL/TLS 加密通讯频道，防止敏感数据被窃取。

常见攻击防范

1. 防止 DDoS 攻击：配置限流策略，限制同时连线数量。
2. 注入攻击防护：在处理外部指令时，进行充分的输入过滤和验证。

常见问题解答

Q1: 如何安装 SketchupMCP 插件？

A: 按以下步骤操作：

1. 开启 Sketchup。
2. 进入 “编辑” > “扩展库”。
3. 安装 SketchupMCP 插件。

Q2: 服务器无法启动，应该怎么办？

A:

1. 确保安装了最新版本的 Python 和依赖库。
2. 检查是否有其他程序占用相同的端口。
3. 查看服务器启动日志，寻找错误讯息。

Q3: 如何更改服务器端口号？

A: 在启动命令中指定新的端口：

python -m sketchupmcp.server --host localhost --port 8001

Q4: 插件无法连线服务器，原因有哪些？

A:

1. 服务器未正确启动。
2. 确保客户端和服务器在同一个网络下。
3. 检查端口是否通畅。

Q5: 如何保护服务器免受未授权存取？

A:

1. 启用用户身份验证。
2. 使用 SSL 加密连线。
3. 定期更新软件版本，堵塞安全漏洞。

常见错误与解决方案

错误讯息	解决方法
服务器无法启动	确保依赖库已安装，端口未被占用
插件无法连线	检查网络设定，确保防火墙允许连线
延迟过长	优化服务器配置，或移除不必要的模块

高级主题

群集架构

1. 负载均衡：使用 Nginx 或 HAProxy 分散请求至多台服务器。
2. 自动扩展：配置弹性云服务，根据负载自动增减实例数量。
3. 会话管理：使用 Redis 等中间件来管理和同步客户端会话状态。

性能优化

1. Opcode 缓存：使用 OpCode 缓存（如 Redis 或 Memcached）来加速重复操作。
2. 平行处理：利用多线程或多进程模型提升服务器的处理能力。
3. 数据库优化：确保数据库索引最优，避免全表扫描。

安全加固

1. 最小权限原则：每个帐户只授予完成其工作所需的最低级别权限。
2. 定期安全审查：进行常规的安全审计以识别和缓解漏洞。
3. 入侵检测系统：部署 IDS/IPS 系统来监控并阻挡可疑活动。

进阶配置

认证方式

1. JWT 认证：使用 JSON Web Token 进行轻量级的用户身份验证。
2. OAuth2 整合：将服务器与第三方授权服务（如 Google、Facebook）整合，提供联合登入功能。

日志管理

1. 日志数据存储：使用专业的日志库（如 ELK Stack（Elasticsearch、Logstash、Kibana））进行日志收集、处理和可视化。
2. 日志监控：配置日志仪表盘，实时监控服务器运行状况，快速定位问题。

监控与告警

1. 性能监控：使用 Prometheus + Grafana 来监控服务器性能指标。
2. 异常检测：配置基于机器学习的异常检测系统来检测流量中的异常模式。
3. 即时通知：确保在发生问题时能通过多种通讯管道（如电子邮件、SMS）收到即时通知。

常见错误码

错误代号	说明
500 Internal Server Error	服务器内部错误，例如程式错误或资源不足
401 Unauthorized	欠缺适当的认证信息
403 Forbidden	访问被禁止或拒绝
404 Not Found	所请求的资源未找到
502 Bad Gateway	下游服务器回应错误
503 Service Unavailable	服务临时不可用，通常因为负载过高或维护中

插件用户手册

安装与配置

安装步骤

1. 下载最新版本的 SketchupMCP 插件。
2. 打开 SketchUp 检查是否有可用更新，然后安装插件。
3. 开启 SketchUp，进入 编辑 > 扩展库 确认插件已正确安装。

环境依赖

• 操作系统：Windows 7 及以上版本、MacOS X 10.10 及以上版本。
• SketchUp 版本：支持 SketchUp 2018 及以上版本。
• Python 环境：确保安装了 Python 3.6 或更高版本。

设定初始化

1. 打开 SketchUp，进入 编辑 > 扩展库。
2. 选择 SketchupMCP 插件并打开。
3. 根据向导完成初始设置，包括选择工作目录和配置基本选项。

基本使用方法

插件功能概述

SketchupMCP 提供多种功能模块，包括建筑建模、结构分析、能耗计算等，适合专业建筑师和设计师使用。

快捷键与操作指南

• 按钮：在 SketchUp 的工具栏中找到 SketchupMCP 按钮，点击即可启动插件。
• 快捷键：设置自定义快捷键以提高工作效率。

常用命令参考

# 示例命令
mcp new_project [project_name]  # 新建项目
mcp open [project_path]         # 开启已存在项目
mcp save                        # 保存当前项目

进阶配置

群集架构

• 配置多台服务器：在 SketchupMCP 中设置群集模式，分散计算负载。
• 通信协议：选择合适的通讯协议（如 HTTP/HTTPS）以确保数据传输安全。

负载均衡设置

• 配置反向代理：使用 Nginx 或 Apache 等服务器软件实现负载均衡。
• 健康检查机制：配置健康检查机制，确保每台服务器状态正常。

安全加固措施

• SSL 证书：采用 SSL 加密通信，保护数据安全。
• 认证授权：配置多级用户权限管理，限制未经授权的访问。

错误排查与解决方案

常见错误码

错误代号	说明
500 Internal Server Error	服务器内部错误，例如程式错误或资源不足
401 Unauthorized	欠缺适当的认证信息
403 Forbidden	访问被禁止或拒绝

错误诊断步骤

1. 检查日志文件，查找错误代号。
2. 根据错误代号对应的原因进行相应的设置调整。

日志分析方法

• 日志仪表盘：使用 Grafana 等工具来可视化日志数据，快速定位问题。

附录

安装依赖库

pip install -r requirements.txt

认证机制详细介绍

• 基本认证：使用 $username:$password 格式进行认证。
• 令牌认证：采用令牌方式，增加安全性。

常用命令与脚本示例

# 示例脚本
#!/bin/bash
mcp batch_process /path/to/projects/

🔧 技术细节

系统结构

概述

SketchupMCP 系统包含 Sketchup 扩展和 MCP 服务器两大部分。Sketchup 扩展作为 Sketchup 平台与外部服务器的通信桥梁，接收用户指令并通过 TCP 套接字传送至服务器，同时将服务器回应传送回客户端。MCP 服务器则负责处理来自 Sketchup 扩展的请求，解析指令、执行建模或操作，然后将结果反馈给客户端。

具体结构

Sketchup 扩展的安装涉及下载并安装 Sketchup，在扩展库中安装 SketchupMCP 插件，开启插件后连接至 MCP 服务器。MCP 服务器的安装需要安装 Python 环境，克隆 SketchupMCP 专案仓库，启动服务器后设定 IP 和端口等待客户端连线。

高级主题

群集架构

通过使用 Nginx 或 HAProxy 实现负载均衡，将请求分散至多台服务器。配置弹性云服务实现自动扩展，根据负载自动增减实例数量。利用 Redis 等中间件管理和同步客户端会话状态。

性能优化

使用 OpCode 缓存（如 Redis 或 Memcached）加速重复操作，利用多线程或多进程模型提升服务器处理能力，确保数据库索引最优避免全表扫描。

安全加固

遵循最小权限原则，为每个帐户授予完成工作所需的最低级别权限。进行定期安全审查，识别和缓解漏洞。部署 IDS/IPS 系统监控并阻挡可疑活动。

进阶配置

认证方式

采用 JWT 认证进行轻量级的用户身份验证，将服务器与第三方授权服务（如 Google、Facebook）整合实现 OAuth2 整合。

日志管理

使用专业的日志库（如 ELK Stack）进行日志收集、处理和可视化，配置日志仪表盘实时监控服务器运行状况。

监控与告警

使用 Prometheus + Grafana 监控服务器性能指标，配置基于机器学习的异常检测系统检测流量异常模式，确保在发生问题时能通过多种通讯管道收到即时通知。

📄 许可证

文档中未提及相关许可证信息。

结论

SketchupMCP 是一款功能强大的插件，能帮助您在 SketchUp 中实现各种复杂的建筑设计和模拟。通过合理的配置和最佳实践，可以充分发挥其潜力，提升工作效率。希望本指南能助您一臂之力，祝您的建模过程顺利！

附录：

• 附录A: 安装依赖库
• 附录B: 认证机制
• 附录C: 常用命令与脚本

参考文献：

1. SketchUp 官方文件
2. 相关技术白皮书
3. 开发团队内部纪录

注释： 此指南为示范性质，具体内容可能因版本不同而有所变动。建议使用时参照官方最新文档。