Circuitarium MCP

Circuitarium MCP

面向支持 MCP 的助手的本地电子电路工具，支持 CRUMB 存档文件和 Logisim-evolution 项目。

Circuitarium 可让 MCP 主机检查电路文件，而不会把静态分析误当作正在运行的模拟器。它可以追踪 CRUMB 网络、生成物料清单、运行电气规则检查、分析 Logisim 项目，还可选择让 Logisim-evolution 生成真值表或运行测试向量。

0.3.1 版包含 22 个工具、9 个只读资源和 4 个工作流提示词。此服务与模型无关：Codex、Claude Code/Desktop、VS Code、LM Studio、Jan 或其他本地 MCP 主机负责提供模型，并通过 stdio 启动 Circuitarium。Circuitarium 本身无需 OpenAI、Anthropic 或本地模型 API 密钥。

快速开始

你需要：

• Node.js 22 或更高版本；
• 能够启动本地 stdio 服务的 MCP 客户端；以及
• 一个专用文件夹，其中仅包含你希望客户端访问的电路文件。

CI 覆盖 Windows、macOS 和 Linux。CRUMB 分析和静态 Logisim 工具均不需要模拟器或 Java。

要在终端中安装并启动本地 stdio 服务：

npx -y [email protected]

在交互式终端中，这会显示简短的状态面板。在日常使用中，MCP 客户端会运行同一条命令，并通过 stdio 保持与服务的连接。

1. 将 Circuitarium 添加到 MCP 客户端

大多数客户端需要相同的命令、参数和环境变量：

Command: npx
Arguments: -y [email protected]
Environment:
  CIRCUITARIUM_MCP_ROOT=/absolute/path/to/circuit-workspace

首次启动时，npm 下载软件包可能需要较长时间。之后通常会使用 npm 的缓存。

将路径替换为最小的文件夹，其中应包含可供模型使用的 .cru、.circ、.vec 和 .txt 文件。不要将路径指向主目录或驱动器根目录。

可复制的配置如下：

• Codex
• Claude Code
• VS Code
• LM Studio
• Jan

请参阅客户端设置指南，了解针对不同平台的示例和本地模型使用指南。入门工作区方案会将一个合成 CRUMB 示例文件和完整的 Logisim 全加器项目复制到隔离文件夹，因此首次测试无需访问源代码检出目录中的其他内容。添加服务后，请重启或重新加载客户端。

Claude Desktop 用户也可以直接下载 circuitarium-mcp-0.3.1.mcpb 并将其作为本地捆绑包打开。安装程序会要求指定电路工作区，并提供可选的 Logisim JAR 和 Java 设置。发布页面 还包含校验和及对应的 npm tarball。

2. 在未安装模拟器的情况下尝试一个电路

将以下内容粘贴到已连接的客户端中：

使用 Circuitarium。调用 electronics_capabilities。将内置的 breadboard-led fixture 创建为 demo/first-led.cru，不要覆盖 任何内容，然后分析它并运行 crumb_check_design。说明哪些发现 是静态推断，而非模拟结果。

客户端可能会要求你批准创建合成文件。工具会拒绝覆盖已有路径；重复运行时，请分析已有文件或选择新文件名。

连接正常时，会创建一个小型合成文件，识别其中的面包板和 LED，并报告两条浮空端子警告。该 fixture 独立创作，可安全再分发；它不是 CRUMB 资源。

3. 在终端中检查启动器

这些命令会验证已发布的启动器，而不会打开服务会话：

npx -y [email protected] --help
npx -y [email protected] --version
npx -y [email protected] doctor --smoke

如果单独运行 npx -y [email protected] 后似乎一直在等待，这是服务的预期行为：它正在等待 MCP 主机通过 stdin 连接。按 Ctrl+C，然后让主机自行启动该命令。

观看终端演示，了解源码检出目录中的命令运行器如何检查合成 fixture、构建其 BOM 并导出其网表。公开软件包提供上文所示的 MCP 服务、帮助、版本和 doctor 命令。

观看 MCP Inspector 演示，了解该服务如何在独立的 MCP 客户端中运行；或者阅读可复现的 22 工具主机验证及其脱敏证据报告。

你可以做什么

领域	当前能力
通用电子技术	发现可用后端，验证可移植的实验描述，并规划验证电路主张所需的证据
CRUMBLE / CRUMB	发现、检查、验证和比较 Unity 时代的 .cru 存档；构建 BOM 和网表；追踪导电网络；查询受支持 IC 的引脚排列；并运行静态电气检查
Logisim-evolution	发现并检查 .circ 项目，导出明确不完整的中立网表，并可选择运行元件统计、真值表和测试向量
跨模型工作	保留相对于工作区的项目引用和原始字节 SHA-256 摘要，以便其他模型确认读取的是同一工件

CRUMBLE（Circuit Representation & Universal Model Bridge for Laboratory Electronics）是 Circuitarium 内针对 CRUMB 的非官方集成。 与模拟器无关的工具可避免将针对 CRUMB 的假设带入未来的适配器。

当前功能由三个中立的 electronics_* 工具、十三个 crumb_* 工具和六个 logisim_* 工具组成。所有工具结果都使用 electronics.mcp/0.2 结果契约，与软件包版本无关。

静态分析与运行时执行的区别

操作	是否需要模拟器或 Java？	可证实的内容
所有 crumb_* 工具	否	从 Unity 时代的已保存 .cru 文件推断出的事实；绝不代表 CRUMB 的实时行为
logisim_list_projects、logisim_analyze_design、logisim_export_netlist	否	已保存的 .circ 结构，以及明确不完整的中立表示
logisim_component_stats	需要 Java 21 和用户提供的 Logisim 4.1.0 all-JAR	所选项目和电路已在一个有界子进程中加载
logisim_truth_table、logisim_run_test_vector	需要 Java 21 和用户提供的 Logisim 4.1.0 all-JAR	针对确切项目摘要的有界行为证据；并非实时 GUI 会话
资源和提示词	否	仅提供指导和工作流模板；不会读取项目或运行模拟器

兼容性与明确的限制

目标	状态	范围
CRUMB 1.3.5，Unity 时代的 .cru 格式	实验性支持	在 crumb.unity/1.3.5 下进行静态、版本固定的文件分析
Godot 时代的 CRUMB 2.x	不支持	需要单独的证据配置文件和受控保存文件语料库
实时控制或模拟 CRUMB	尚未实现	不支持运行、暂停、单步执行、信号读取或 GUI 桥接
任意编辑 CRUMB	尚未实现	唯一公开的写入工具只能创建五种固定的合成测试文件之一
Logisim-evolution 4.1.0 静态分析	实验性支持	在隔离环境中解析 .circ 文件；中性网表仍明确属于部分支持
Logisim-evolution 4.1.0 执行	可选	有界、单次运行的 JAR 子进程；不支持实时 GUI 会话

CRUMB 电气规则检查基于推断出的网络连通性和保存的元件值。它可以检测电源短路、直接跨接在一个已识别电源两端的 LED、保存的阻值表明功耗过高的直接连接电阻，以及选定的悬空端子或 IC 电源引脚。它不会追踪串联路径、验证极性、计算一般电路行为，也不会为实物搭建提供认证。

警告

Circuitarium 是用于教育的实验性软件，不是安全认证工具。对于市电、电池充电、医疗、汽车、生命安全、高能量或法规相关工作，请勿仅凭其输出做判断。凡是后果重大的场景，都应查阅权威元件文档，进行适当测量，并由合格的工程人员审核。

文件解析在本地进行，但 MCP 主机可能会将返回的数据发送给云端模型。默认情况下不会包含嵌入式固件源码，也不会返回二进制 EEPROM 内容，但你仍应使用不含机密信息的精简工作区。请阅读安全策略，了解完整的信任模型。

可选的 Logisim 运行环境

三种静态 Logisim 工具无需 Java 即可使用。若要启用元件统计、真值表和测试向量：

1. 安装 Java 21 或更高版本。
2. 下载官方的 logisim-evolution-4.1.0-all.jar。
3. 将 JAR 路径添加到 MCP 主机配置中。

CIRCUITARIUM_LOGISIM_JAR=/absolute/path/to/logisim-evolution-4.1.0-all.jar
CIRCUITARIUM_JAVA=java

如果 java 已解析为 Java 21 或更高版本，则无需设置 CIRCUITARIUM_JAVA。在无头 Linux 机器上，执行测试向量还需要可用的 X11 显示；Xvfb 即可满足要求。

仅使用可信的 JAR。Circuitarium 会验证其自报版本为 4.1.0，但该响应无法验证文件或发布者的身份。运行时工具可能会更新 Logisim 的每用户 Java 首选项，且不属于操作系统沙箱。

代码库包含一个由独立作者编写的全加器项目和向量，可用于首次运行时测试。Circuitarium 不会捆绑或下载 Logisim-evolution。有关设置、Linux 说明、证据级别和子进程安全措施，请参阅 Logisim 适配器指南。

典型工作流

检查 CRUMB 保存文件

1. 调用 electronics_capabilities。
2. 如果路径未知，调用 crumb_list_projects。在请求摘要且文件及总量未超过文档规定的限值时，项目会附带摘要；否则结果会说明省略摘要的原因。
3. 使用 view: "summary" 调用 crumb_analyze_design。
4. 根据问题需要，使用 crumb_export_netlist、crumb_trace_net、crumb_check_design 或 crumb_bom。

静态分析结果仍属于基于文件格式的推断。Circuitarium 无法观察 CRUMB 是否正在运行，也无法判断电路的运行情况。

验证 Logisim 项目

1. 调用 logisim_list_projects，然后调用 logisim_analyze_design。
2. 将 logisim_export_netlist 视为部分静态证据，并检查其转换损失标记。
3. 如果可选运行时可用，请选择一个精确电路，并调用 logisim_truth_table 或 logisim_run_test_vector。
4. 当某项声明需要多种证据或需要明确列出剩余差距时，使用 electronics_plan_verification。

将工作交接给另一个模型

交接时保留 projectRef、projectDigest、backendId、adapterVersion 和 compatibilityProfile。接收模型应在首次读取时，将记录的摘要作为 expectedProjectDigest 传入。如果字节内容已更改，Circuitarium 会返回 PROJECT_STATE_CONFLICT，而不会悄悄沿用过时的结论。

请参阅跨模型交接示例。

工具参考

全部 22 个工具

通用电子工具

工具	用途
electronics_capabilities	报告可调用的后端、限制和推荐工作流
electronics_validate_experiment	验证可移植的实验描述，但不声称实验已运行
electronics_plan_verification	为明确的电路声明制定证据计划

CRUMBLE 工具

工具	用途
crumb_component_catalog	返回固定版本的 CRUMB 元件目录
crumb_analyze_design	读取 .cru 存档的有限语义视图
crumb_compare_designs	比较两个受摘要保护的存档，不修改其中任何一个
crumb_inspect_design	返回简明的格式级清单
crumb_validate_design	检查 XML 结构和已知不变量
crumb_generate_fixture	创建一个固定的合成测试样例，不覆盖现有内容
crumb_list_projects	发现工作区中的 .cru 文件和有限的制品元数据
crumb_get_component	获取一个元件和可选的有限源代码窗口
crumb_bom	将已识别元件归类并生成物料清单
crumb_ic_reference	查询固定版本的 IC 包和引脚注册表
crumb_export_netlist	导出静态的、已折叠跳线的推断网络
crumb_trace_net	为一个端子生成分页的导电路径证据
crumb_check_design	执行范围限定的静态电气规则检查

Logisim-evolution 工具

工具	用途
logisim_list_projects	发现工作区中的 .circ 文件
logisim_analyze_design	检查项目、电路、元件、Pin、Clock 和连线的静态结构
logisim_export_netlist	导出明确不完整、基于坐标的通用网表
logisim_component_stats	请求已配置的 JAR 加载并统计电路
logisim_truth_table	计算范围受限的组合逻辑真值表
logisim_run_test_vector	运行工作区内的测试向量并返回结构化故障

九个资源提供能力元数据、兼容性配置文件、合成示例元数据、电气审查和数字测试指南、通用元件配置文件架构，以及固定版本的元件目录。四个由用户调用的提示词为：

• review-circuit-design
• compare-crumb-designs
• verify-logisim-design
• handoff-circuit-project

资源和提示词本身不会读取项目或运行模拟器。不提供这些 MCP 功能的客户端仍可使用全部 22 个工具。契约参考记录了精确的资源 URI、提示词参数、结果封装、错误、输出限制和工具架构。

贡献

Circuitarium 仍处于早期阶段，细小且有充分依据的改进也很有价值。 适合入手的工作包括修复客户端设置问题、编写合成测试电路、 提供附有来源引用的组件资料、处理解析器边界情况、记录受控的兼容性 观察结果，以及开展范围明确的 路线图 工作。

在修改适配器或公开契约之前，请阅读 贡献指南、 架构说明和 溯源政策。问题和初步设计想法请在 讨论区中提出； 可复现的缺陷、范围明确的功能请求和受控的互操作性证据，请提交到 问题跟踪器。

git clone https://github.com/Craftiee/circuitarium-mcp.git
cd circuitarium-mcp
npm ci
npm run lint
npm run check

行为变更请使用 npm run test:coverage，程序包或启动器变更请使用 npm run package:check，Logisim 运行时变更请使用 npm run logisim:e2e。Logisim 端到端测试 需要 Java 21 和单独提供的 4.1.0 all-JAR。

测试固件必须小巧、合成、独立编写，并且可以安全地再分发。请勿提交 私人电路、固件、模拟器二进制文件、提取的资源或第三方电路设计。请改为 构建最精简的合成复现用例。请通过 GitHub 私密漏洞报告报告漏洞，而不要发布公开问题。 所有贡献者都必须遵守行为准则。

文档

文档	用途
客户端设置	特定宿主的安装、订阅/API 和本地模型
CRUMBLE 指南	当前 CRUMB 范围和证据资料
Logisim 指南	JAR 设置、运行时证据、安全事项和 Linux 说明
MCP 契约	工具、Resources、Prompts、信封和限制的具体内容
架构说明	适配器边界和与模拟器无关的设计
溯源	证据类别和再分发规则
路线图	已发布的里程碑和计划中的工作
变更日志	发布历史

隐私政策

Circuitarium 在本地通过 stdio 运行，不收集遥测数据，也不会将电路文件发送到 由维护者控制的服务。你选择的 MCP 宿主和模型提供商仍可能根据 各自的条款处理工具参数和结果。在允许宿主访问工作区之前，请阅读完整的 隐私政策。

项目状态和许可证

Circuitarium MCP 是实验性的社区软件，依据 Apache License 2.0发布。版本 0.3.1 可在 npm 上获取，也可作为 GitHub 发布版本获取， 其元数据也已列入 官方 MCP Registry。 如需帮助，请参阅 SUPPORT.md。研究和教学用户可以通过 CITATION.cff引用本项目。

Circuitarium MCP、CRUMBLE 和 Logisim-evolution 适配器是独立的非官方互操作性 项目。它们与 CRUMB、Logisim-evolution 及其开发者无关，也未获得其认可或赞助。本仓库 不包含 CRUMB 或 Logisim-evolution 的模拟器代码、二进制文件、提取的 资源、徽标或捆绑的第三方电路设计。产品名称和标志归各自所有者所有。