physics-lint-mcp

📖 문서 사이트 — 포트폴리오 서사, 개념, 전체 워크스루, 그리고 이 모든 것이 증명하는 것(과 증명하지 못하는 것).

당신의 AI 에이전트가 말로 얼버무릴 수 없는 물리학 오라클.

LLM은 물리적으로 불가능한 S-파라미터 행렬과 그럴듯한 행렬을 구별할 방법이 없다 — 둘 다 그저 숫자일 뿐이다. 에이전트에게 조작된 모델을 건네면, 에이전트는 그것에 대해 자신 있게 추론하고, 인용하고, 그 위에 무언가를 구축할 것이다. 루프 안에서 이의를 제기하는 것은 아무것도 없다.

이 MCP 도구들은 에이전트에게 자체 판단이 아닌 선형대수학에서 나온 근거 자료(ground truth)를 제공한다.

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를 통해 광고하는 스키마가 해당 표의 권위 있는 버전이며, 테스트가 둘이 일치함을 검증한다.

실제 사례: 스스로를 속일 수 없는 에이전트

이것이 방지하는 실패는 구체적이다. 에이전트가 공급업체의 .s2p 파일을 받고, 링크가 닫힐지 질문을 받으며, 존재할 수 없는 네트워크를 설명하는 숫자에 대해 유창하게 추론한다. 루프 안에서 이의를 제기하는 것은 아무것도 없다. LLM은 불가능한 S-행렬과 그럴듯한 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에 없기 때문이며, 이는 클라이언트가 다른 셸로 서버를 실행할 때 흔하다. mcp.json에서 절대 경로를 사용하라: {"command": "/full/path/to/venv/bin/physics-lint-mcp"}.

클라이언트가 서버 시작 실패로 표시함 — 퀵스타트의 stdio 스모크 테스트를 먼저 직접 실행하라. 클라이언트의 감독 없이 동일한 코드 경로이므로 트레이스백이 보인다.

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

범위, 솔직하게

이 도구들은 물리적 허용 가능성(physical admissibility)을 검증하지 정확성(accuracy)을 검증하지 않는다. 완전히 잘못된 구조의 수동 모델도 모든 검사를 통과한다. 이것들은 바닥(floor)이지, 필드 솔루션이나 측정에 대한 검증을 대체하지 않는다.

나머지 도구 모음

한 가지 질문에 다른 위치에서 답하는 여덟 개의 산출물: 이 모델이 물리적으로 가능한가? 각각은 채점자(grader)이다 — 모델이 틀렸다고 말할 수는 있지만, 맞다고 말할 수는 없다.

이 도구들은 모델을 채점한다. 구조적으로 수동인 — 즉 매개변수가 무엇이든 이 법칙들을 위반할 수 없는 — 모델을 생성하고, 다체 영역에서 빠르게 정확하며, 보정된 기권과 실패 시 폐쇄(fail-closed) 서명 인증서를 갖추는 것이 상업적 핵심이다: ChipletOS.

라이선스

Apache-2.0. LICENSE 참조. 저작권은 NOTICE에 있음.

이 도구들과 함께 작성된 서명 인증서와 구조적 수동 합성은 ChipletOS 폐쇄 코어이다.

기여

여기서 양보할 수 없는 규칙 하나: 모든 도구는 읽기 전용을 유지한다 — 실패한 모델을 조용히 패치할 수 있는 에이전트는 오라클을 두는 의미를 무너뜨릴 것이다. CONTRIBUTING.md에 자세한 내용이 있다. 각 형제 저장소는 자체 규칙을 명시하며, 그것들은 서로 다르다 — 그것은 의도적이며, 각각이 자기 조건에서 신뢰할 수 있는 이유이다.

인용

CITATION.cff는 기계가 읽을 수 있다. GitHub는 그것으로 "이 저장소 인용" 버튼을 렌더링한다.