OpenSCAD MCP 服务器

关键词

OpenSCAD渲染后端模型管理缓存策略依赖分析

使用说明

  • 项目简介
    • 该仓库实现了一个 OpenSCAD 的 MCP 服务器，核心功能包括托管与管理资源（Resources）、注册并执行工具（Tools，如渲染、导出、分析、模型 CRUD 等），以及执行与渲染 Prompt/模板相关的能力，使得 AI 助手可以通过 MCP 客户端以标准化方式访问 OpenSCAD 的能力。
    • 服务器通过 JSON-RPC 风格的请求/响应与客户端通信，支持会话管理、能力声明，以及多种传输协议的扩展，如 stdio、HTTP、SSE 等。
  • 主要功能点
    • 资源与数据访问：对模型、库、渲染结果等资源进行管理与查询（如渲染缓存、库检测、依赖解析、项目文件等）。
    • 工具（Tools）：提供大量 MCP 工具函数，用于渲染、对比渲染、分析 STL、导出模型、验证 SCAD、库发现、项目文件管理、以及缓存清理等。
    • 渲染与导出：支持单视图渲染、多视角渲染、批量对比渲染，以及 OpenSCAD 的导出（STL、3MF、AMF、OFF、DXF、SVG）。
    • 模型与项目管理：创建、读取、更新、列出、删除 .scad 文件，解析依赖关系、扫描项目文件、清理缓存等。
    • 安全与配置：对输入进行路径与大小等安全校验，支持包含路径的白名单、变量名校验，以及最大输入大小限制。
    • 缓存与性能：可缓存渲染输出，以减少重复渲染，提供缓存淘汰策略、基于大小的清理，以及将渲染结果自动切换为文件路径输出等策略。
    • 流程与集成：提供多种解析器工具（parse_list_param、parse_dict_param、parse_image_size_param、parse_camera_param 等），方便与 AI 客户端进行多格式参数对接，以及用于性能与边界测试的工具。
  • 安装步骤
    • 需要依赖 OpenSCAD、Python 环境与 FastMCP 框架。建议在开发机安装 OpenSCAD 并确保可访问。
    • 快速启动（参考仓库自述）：
      • 使用 uv 直接运行当前仓库的 MCP 服务器实现（需要安装 uv 工具）；
      • 也可将仓库作为 Git 包在 uv/ Claude/OpenAI 之类环境中作为 MCP 服务器端。
    • 常见环境变量及配置（自动从配置加载，未必需要逐条设置）：
      • MCP_TRANSPORT 指定传输类型（stdio、http、sse），默认 stdio
      • MCP_HOST/MCP_PORT 指定 HTTP/SSE 传输的主机与端口
      • OPENSCAD_PATH 指定 OpenSCAD 可执行文件路径
    • 本仓库也提供 YAML/ENV 配置和测试用例，便于开发与验证。
  • 服务器配置（给 MCP 客户端使用的配置信息，JSON 形式，非代码）
    • 服务器名称
    • 启动命令及参数（client 端用来连接服务器的启动信息）
    • 说明：客户端需要至少配置服务器名称、启动命令与参数以建立连接，但具体如何连接由客户端实现决定。以下为可直接参考的配置示例描述（以 JSON 表达，非代码块）：
    • server_name: "OpenSCAD MCP Server"
    • command: "uv"
    • args: ["run", "--with", "git+https://github.com/quellant/openscad-mcp.git", "openscad-mcp"] 注释说明：
    • server_name 对应 MCP 服务器的名称，与服务端展示的名称保持一致。
    • command 与 args 指定启动服务器所需的命令及参数，通常通过 uv 工具加载本仓库中的 MCP 服务实现来暴露给 MCP 客户端使用。
    • 客户端在接入时需要将上述信息与自身的 JSON-RPC 机制对接，形成请求-响应的通信。
  • 基本使用方法
    • 启动服务器
      • 使用 uv 启动本仓库中的 MCP 服务实现，默认传输为 stdio。若需要 HTTP/SSE，请启用相应配置并通过客户端连接。
    • 客户端交互
      • 客户端通过 JSON-RPC 向 MCP 服务器发起请求，例如读取资源、调用工具、获取模型信息、管理缓存等。服务器返回标准化的 JSON-RPC 响应。
    • 常用工具示例
      • render_single：按给定 OpenSCAD 代码或文件渲染单一视图，支持自定义相机、图片尺寸、变量覆盖、质量设定等。
      • render_perspectives：并行渲染多视角，返回每个视角的渲染结果。
      • analyze_model/export_model/validate_scad/get_libraries/get_model/list_models/delete_model、create_model、update_model 等工具实现了资源和模型的完整生命周期。
    • 调试与日志
      • 服务器内置日志与调试输出，异常会在返回结果中以 error 字段呈现，必要时可结合上下文对象（ctx）进行日志记录。

服务器信息

访问项目