altium-designer-mcp

altium-designer-mcp 是一个 MCP（Model Context Protocol）服务器，用于 AI 辅助管理 Altium Designer 元件库。它让 AI 助手（如 Claude Code、Claude Desktop、Cursor、Antigravity、VS Code Copilot 等任何 MCP 客户端）获得对 .PcbLib（封装）和 .SchLib（符号）库文件的文件 I/O 和图元放置工具，从而能够创建和维护任意元件，而不仅是预先编程的封装类型。该工具的核心思路是：AI 负责工程智能（数据手册 → 尺寸 → 风格），工具负责文件 I/O。这是因为 Altium 的二进制 .PcbLib / .SchLib 文件采用未公开的 OLE 复合格式，容易损坏，且 Altium 会静默拒绝打开格式错误的文件，AI 无法直接写入。谁适合使用：任何构建或维护 Altium 元件库并使用支持 MCP 的 AI 助手的人。客户端配置已在 Claude Code、Claude Desktop、Google Antigravity、Cursor、VS Code、GitHub Copilot CLI、Windsurf、Cline、Roo Code、Kiro、JetBrains、Zed、Gemini CLI、Codex CLI、Continue、Goose、OpenCode 等 stdio MCP 客户端上验证，支持 Windows、Linux 和 macOS。服务器提供 34 项工具，同时适用于 .PcbLib 和 .SchLib。工具按类别包括：检查与可视化、管理元件、库操作、备份与安全。完整参数和示例见 docs/TOOLS.md。封装图元（PcbLib）：焊盘上的 shape 属性控制铜形状，可用于标记引脚 1，遵循 IPC-7351 惯例（引脚 1 使用矩形或方形角，其他焊盘使用圆角）。符号图元（SchLib）：支持标准 Altium 层，如 Top Overlay、Mechanical 13 等，层名可用 Altium 拼写或驼峰式，大小写不敏感，每个工具接受相同拼写。预构建二进制文件（Linux x86_64、macOS aarch64、Windows x86_64）在 Releases 页面提供，每个归档包含安装 README 和 docs/CLIENT_SETUP.md，覆盖已知所有 MCP 客户端。Linux 二进制需要 glibc 2.34 或更新版本（Ubuntu 22.04、Debian 12、RHEL 9 及后续版本）。Claude Desktop 用户无需归档：可从同一页面安装一键扩展 altium-designer-mcp.mcpb（旧版本为 altium-designer-mcp.dxt），路径为 Settings → Extensions → Advanced settings → Install Extension。代码签名策略：Windows 二进制将通过 SignPath Foundation 签名，在批准前未签名，每个发布版本带有签名的构建来源证明。在容器中使用：仓库的 Dockerfile 生成与发布二进制相同的 --locked release 构建。挂载的 /libraries 文件夹是容器的全部允许列表。客户端配置为 "command": "docker" 和 "args": ["run", "-i", "--rm", "-v", "/path/to/libraries:/libraries", "altium-designer-mcp"]。从源码构建：见 CONTRIBUTING.md，优化二进制来自 cargo build --release，位于 target/release/altium-designer-mcp。验证下载的发布版本：发布归档由 GitHub Actions 构建，带有签名的 SLSA 构建来源证明，可追踪到工作流运行和提交。二进制未代码签名，Windows SmartScreen 和 macOS Gatekeeper 首次运行时会警告（macOS 上右键 → 打开）。证明是更强的检查。命令行用法：每个 MCP 客户端需要相同的两个绝对路径——二进制文件和配置文件——仅写入位置不同。使用绝对路径，客户端不搜索 PATH 或展开 ~。服务器读取一个 JSON 文件，或没有：altium-designer-mcp --allow <DIR> 在命令行授予文件夹并默认运行其他内容，Claude Desktop 扩展就是这样启动的。配置位置：Linux/macOS 为 ~/.altium-designer-mcp/config.json，Windows 为 %USERPROFILE%.altium-designer-mcp\config.json。STEP 模型集成：STEP 模型是附加的，不是生成的。工具将现有 STEP 文件链接到封装。Altium 支持两种引用 3D 模型的方式：嵌入和外置。复制或合并元件时：嵌入模型随元件移动——copy_component_cross_library 和 merge_libraries 都会将引用的模型流复制到目标（多个封装共享的模型只复制一次），因此移动后主体仍能解析。外置模型引用：copy_component_cross_library 默认移除它们并警告，因为相对于源库的路径很少能在别处解析——传递 preserve_external_paths=true 可保留。merge_libraries 原样保留。在源库中嵌入模型是任何复制中保留 3D 数据的可靠方式。提取嵌入模型：使用 extract_step_model 从库中提取嵌入的 STEP 数据。参数化 3D 模型生成计划作为未来项目，使用专门的机械 MCP 服务器。自动备份：在任何破坏性操作（删除、更新、合并、批量更新）之前，服务器自动创建目标文件的时间戳备份。备份格式：保留每个文件最近 5 个备份，较旧的自动移除。创建备份的操作包括：delete_component、update_component、update_primitive、rename_component、copy_component_cross_library（目标文件）、merge_libraries（目标文件）、reorder_components、manage_schlib_parameters、manage_schlib_footprints、write_pcblib / write_schlib（覆盖时）、import_library（覆盖时）、restore_backup（当前文件在被选定备份替换前）。管理备份：使用 list_backups 查看可用备份，restore_backup 恢复先前版本。干运行支持：这些操作支持 dry_run=true 预览更改而不修改文件。非西文 Windows 的库：Altium 将大多数名称存储为写入机器的 Windows 代码页中的纯字节，无记录。在中文、日文、韩文、中欧、西里尔、希腊、土耳其、波罗的海、希伯来、阿拉伯、越南或泰文 Windows 上编写的库，在假定 Windows-1252 的工具中会显示为乱码（如 £¨0402 代替 （0402）。本服务器通过真实名称记录两次的封装（一次为字节，一次为 Unicode）推断库的代码页，通过它读取每个名称，并原样写回，重写保持字节相同。读取或编辑此类库无需配置。两种情况值得了解：1. Altium 必须显示的名称。Altium Designer 21 及更早版本从这些字节显示封装名称，通过运行机器的代码页解码，从不读取 Unicode 副本。因此新或重命名的封装以服务器自己的代码页写入——Windows 上为系统代码页。当服务器运行的机器区域设置与打开库的 Altium 不同时，请在配置文件中用 ansi_code_page 或命令行 --ansi-code-page 指定该页（874、932、936、949、950、1250 到 1258，或 65001）。2. 页面无法容纳的字符。Altium 写入 ? 代替，本服务器也如此；完整名称仍保留在元件参数中，如 Altium 保留的那样，下次读取时完整返回。长元件名称：支持超过 31 个字符的元件名称。OLE 复合文件格式限制存储名称为 31 个字符，因此较长的名称在内部自动截断，完整名称保留在元件参数中。透明处理，读写往返中保留任何长度的元件名称。数据收集：无。服务器无遥测和分析，从不联系任何服务，包括本项目。使用 --http 时监听给定地址上的 MCP 客户端，仍不发送任何内容。使用和存储：只读写授予文件夹（allowed_paths 或 --allow）内的库文件，以及在更改前在旁边创建的时间戳 .bak 副本。可选审计日志（logging.audit_log_path）是您选择的本地文件，保存工具名称、文件名和结果——从不保存库内容。第三方共享：无。数据保留：文件和备份保留到您删除；备份每个库最多保留最近 5 个。联系方式：matejg03@gmail.com，或 GitHub issue。贡献欢迎，见 CONTRIBUTING.md。遵循 STYLE.md 风格指南。安全问题见 SECURITY.md。写路径测试以编程方式生成自己的数据；读取测试解析提交的 Altium 编写的黄金夹具。临时文件创建在 .tmp/（git 忽略）并自动清理。完整构建、格式化和 lint 命令在 CONTRIBUTING.md 中。版权 (C) 2026 The Embedded Society。GNU General Public License v3.0，见 LICENCE。MCP 规范。Altium 编写的示例库作为黄金夹具提交在 scripts/samples/ 下：读取测试（tests/samples_pcblib.rs、tests/samples_schlib.rs）在 CI 中解析它们作为基准真值。重新生成它们的 PowerShell/DelphiScript 工具需要真实的 Altium 安装，仅手动。见 scripts/README.md。先前艺术与致谢：AltiumSharp (MIT) —— 最完整的开源 Altium 读写器，用作权威参考（其 DTO、二进制序列化代码和黄金 TestData）验证二进制格式。pyAltiumLib —— 独立的 Python 读取器，用作 CI 可读性 oracle 检查生成文件实际解析。python-altium —— 早期 Altium 格式文档。coffeenmusic/altium-mcp (MIT) —— 驱动实时 Altium 应用程序的 MCP 服务器，是本项目的补充（我们离线生成和编辑库文件；它控制运行会话）。我们改编了其 RunScript 启动 + 基于文件的桥接模式用于现场 Altium 自动化（scripts/altium/）。