physics-lint-mcp

📖 文档站点 — 作品集叙事、概念、完整演练，以及这一切证明了什么（以及不能证明什么）。

一个你的 AI 智能体无法用言语绕过去的物理预言机。

LLM 无法区分一个物理上不可能的 S 参数矩阵和一个看似合理的矩阵——两者都只是数字。把一个人为构造的模型交给智能体，它会自信地推理、引用并在此基础上构建。整个回路中没有任何东西提出异议。

这些 MCP 工具为智能体提供来自线性代数的地面真相，而不是来自它自己的判断。

30 秒快速上手

git clone https://github.com/nickharris808/physics-lint-mcp.git
cd physics-lint-mcp

pip install git+https://github.com/nickharris808/sparam-lint.git@main \
            git+https://github.com/nickharris808/maxwell-lint.git@main \
            .

两个检查器是独立的包，从各自的仓库拉取；服务器是末尾的 .。在接入客户端之前，先确认服务器能通过 stdio 应答：

$ printf '%s\n%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | physics-lint-mcp | tail -1 | python3 -m json.tool | grep '"name"'
                "name": "check_touchstone",
                "name": "self_test",
                "name": "check_screening",
                "name": "pairwise_error",

尚未发布到 PyPI。 pip install physics-lint-mcp 是发布后的预期安装方式；在此之前，上面那条三包命令是可行的方式。

Related MCP server: mcp-openems

配置

Claude Desktop / Cursor / 任何 MCP 客户端：

{
  "mcpServers": {
    "physics-lint": {
      "command": "physics-lint-mcp"
    }
  }
}

随包附带一份现成的 mcp.json。

工具

服务器通过 tools/list 通告的 schema 是该表格的权威版本，并且有一个测试断言两者一致。

一个实际示例：一个无法自欺的智能体

这里所防止的失败是具体的。一个智能体拿到一份供应商的 .s2p，被问及链路是否会闭合，然后流畅地推理那些描述一个不可能存在的网络的数字。整个回路中没有任何东西提出异议，因为 LLM 无法区分不可能的 S 矩阵和看似合理的矩阵。

接入服务器后，会话中最值得做的第一件事就是让检查器证明自己：

你： 在我们看模型之前，运行 self_test。

智能体： (调用 self_test) 测试组能区分——五个各自违反一条定律而构造的网络全部被拒绝。

现在看模型：

你： 检查 vendor/lna_stage.s2p。

智能体： (以 path="vendor/lna_stage.s2p" 调用 check_touchstone) 这个网络作为无源器件在物理上不可实现：它不满足无源性和能量守恒。我不会基于它的数值进行推理。

最后那句话不是智能体在谨慎行事——那是结果中返回的 interpretation 字段，是为模型阅读而写的。一个只拿到 {"passed": false} 的智能体往往会继续下去。

设计禁止的两件事，看起来比实际更重要：智能体无法修复模型，因为每个工具都是只读的；它无法把失败误认为崩溃，因为物理失败是以结果而非传输错误的形式返回的。接下来的三节就是这两个属性的详细说明，而第三节是你会最先遇到的情况。

故障排查

physics-lint-mcp: command not found — 控制台脚本没有安装。检查 pip show physics-lint-mcp；如果它存在，说明环境的 bin 目录不在 PATH 上，这在客户端用不同的 shell 启动服务器时很常见。在 mcp.json 中使用绝对路径： {"command": "/full/path/to/venv/bin/physics-lint-mcp"}。

客户端显示服务器启动失败 — 先手动运行快速上手里的 stdio 冒烟测试。它走的是相同的代码路径，但没有客户端的监督，因此可以看到 traceback。

No module named 'sparam_lint' — 两个检查器是独立的包，不会自动拉入。按快速上手所示，安装全部三个。

工具调用返回 isError: true 且智能体停止 — 这是物理判定，不是故障。结果携带失败的定律和一段解释；你的智能体应该阅读它们，而不是把调用视为失败。

完全没有返回 — 服务器通过 stdio 说 JSON-RPC，每行一个对象。客户端如果把多个对象合并到一行，或者写入时没有结尾换行符，就会挂起。initialize 请求必须最先发出。

工具列表比上表短 — 你运行的是旧版本。tools/list 是从与表格测试所用的相同定义生成的，因此它们在同一版本内不可能不一致。

智能体看到的内容

每个结果都携带一个 interpretation 字段，为模型阅读而写，因为智能体依据文字行动，而不是依据布尔值：

{
  "physically_admissible": false,
  "failed_laws": ["passivity", "energy_conservation"],
  "interpretation": "This network is not physically realizable as a passive
    device. Do not use it as a reference and do not reason from its values.
    One legitimate exception: a non-reciprocal device such as a ferrite
    isolator will correctly fail the reciprocity law by design."
}

最后那句话很重要。一个只被告知"互易性失败"的智能体会好心"修复"一个完全正常的隔离器。

而在干净的结果上，解释会说明该判定不意味着什么：

五条定律全部成立；该网络在物理上可接受。请注意这并不表示它是准确的——一个结构完全错误的无源模型在这里能通过每一条定律。

每个工具都是只读的

这里没有任何东西写入、伪造或修复模型。一个能静默修补失败网络的智能体会使预言机的存在失去意义，因此没有 I/O 这一点由测试强制执行。

物理失败是结果，不是错误

一个未通过定律的文件返回正常结果，带有 isError: true 和完整判定，而不是传输级错误。智能体需要看到失败才能推理；一个不透明的协议错误教不了它任何东西。

不用智能体试试

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | physics-lint-mcp

诚实地说明范围

这些工具验证的是物理可接受性，而非准确性。一个结构完全错误的无源模型能通过所有检查。它们是一个下限，不能替代针对场求解或测量的验证。

工具包的其他部分

八个工件在不同位置回答同一个问题：这个模型在物理上可能吗？ 每个都是评分器——它能告诉你一个模型是错的；没有一个能告诉你一个是对的。

这些工具评分一个模型。构造一个按构造就是无源的模型——因此无论参数如何都不会违反这些定律——并在多体体制下快速准确，同时具备校准的弃权和故障关闭的签署证书，这才是商业核心： ChipletOS。

许可证

Apache-2.0。参见 LICENSE；版权见 NOTICE。

这些工具在编写时伴随的签署证书和按构造无源的综合，是 ChipletOS 的闭源核心。

贡献

这里有一条不可协商的规则：每个工具保持只读——一个能静默修补失败模型的智能体会使预言机的存在失去意义。CONTRIBUTING.md 有详细说明。每个兄弟仓库都有自己的规则，而且各不相同——这是有意为之，也是每个仓库在自身条件下都可信的原因。

引用

CITATION.cff 是机器可读的；GitHub 会据此渲染一个"引用此仓库"按钮。