schematic-mcp

MCP를 통한 AI 에이전트용 하드웨어 회로도 컨텍스트.

schematic-mcp는 MCP 호환 에이전트가 하드웨어 회로도를 스크린샷이나 긴 텍스트 블롭으로 취급하는 대신 구조화된 전기 데이터로 검사할 수 있게 해줍니다.

상태: V0.1 / 알파. 첫 번째 어댑터는 최신 KiCad .kicad_sch 파일을 대상으로 합니다.

이 프로젝트가 존재하는 이유

펌웨어를 작성하는 AI 코딩 에이전트는 종종 다음과 같은 질문에 대한 답이 필요합니다:

• 어떤 ESP32 핀이 SENSOR_OUT에 연결되어 있나요?

• U4.GPIO12에는 무엇이 연결되어 있나요?

• 이 I2C 넷을 공유하는 장치는 무엇인가요?

• MCU의 모든 핀과 해석된 넷은 무엇인가요?

• 펌웨어가 가정하는 GPIO 맵이 실제로 회로도와 일치하나요?

이 서버는 EDA 파일을 결정론적으로 파싱하고, 표준 컴포넌트/핀/넷 모델을 구축하며, 해당 모델을 MCP 도구와 리소스를 통해 노출합니다.

설계 원칙은 보수적입니다. 연결성이 확실하게 해석될 수 없는 경우 전기적 연결을 임의로 만들지 않고 경고를 표시합니다.

설계 초점

schematic-mcp는 의도적으로 파일 기반 하드웨어 컨텍스트 계층이며 범용 EDA GUI 자동화 서버가 아닙니다. 일반적인 KiCad 읽기/쿼리 워크플로우에는 실행 중인 KiCad 애플리케이션이 필요하지 않습니다. EDA별 어댑터는 표준 전기 그래프를 생성하는 반면, 에이전트용 MCP 계약은 형식 중립적으로 유지됩니다.

이를 통해 이 프로젝트는 편집기/IPC 자동화를 보완합니다. 편집기 도구는 대화형 설계 변경에 유용하지만, schematic-mcp는 코딩 에이전트, CI 시스템 및 향후 크로스 EDA 어댑터가 사용할 수 있는 결정론적 하드웨어 사실에 중점을 둡니다. 펌웨어 ↔ 회로도 검증이 첫 번째 구체적인 사용 사례입니다.

프로젝트 경계와 에코시스템 관점은 docs/project-positioning.md를 참조하세요.

Related MCP server: mcp-kicad-sch-api

V0.1 기능

• 최신 KiCad .kicad_sch S-표현식 파일 파싱

• 컴포넌트, 참조자, 값 및 라이브러리 ID 읽기

• 라이브러리 핀 지오메트리를 회로도 좌표로 해석

• 다중 유닛 심볼에 대해 활성 KiCad 유닛으로 핀 선택

• 와이어, 레이블 및 접점에서 연결성 구축

• 명명된 넷과 익명 넷 해석

• 단일 컴포넌트 또는 핀 검사

• 동일한 전기 넷의 모든 엔드포인트로 핀 추적

• 간결한 MCU 핀 맵 생성

• 펌웨어 핀 기대치를 실제 핀 번호 또는 기호 핀 이름으로 회로도 넷과 비교

• 현재 표준 모델을 MCP 리소스로 노출

• SCHEMATIC_MCP_ROOT 또는 --root로 파일시스템 액세스 제한

• stdio 또는 Streamable HTTP를 통한 로컬 실행

• GitHub Actions에서 자동화된 파서, 그래프 및 파일시스템 경계 테스트

MCP 도구

리소스:

• schematic://current/summary

• schematic://current/model

GitHub에서 설치

Python 3.10+이 필요합니다. 첫 번째 패키지 레지스트리 릴리스가 게시될 때까지 현재 main 브랜치를 GitHub에서 직접 설치할 수 있습니다:

python -m pip install "git+https://github.com/vonpanda/schematic-mcp.git"
schematic-mcp --help

재현 가능한 프로덕션 사용을 위해 고정되지 않은 개발 브랜치를 추적하는 대신 릴리스 태그나 커밋을 고정하세요. 첫 번째 패키지 릴리스는 이슈 #8에서 추적됩니다.

개발용 설치

git clone https://github.com/vonpanda/schematic-mcp.git
cd schematic-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

이 프로젝트는 공식 MCP Python SDK의 안정적인 v2 라인을 사용합니다.

실행

로컬 stdio

schematic-mcp

또는:

python -m schematic_mcp

환경 변수를 설정하지 않고도 읽기 가능한 파일을 제한할 수 있습니다:

schematic-mcp --root /absolute/path/to/your/hardware-projects

포함된 픽스처 사용해 보기

이 저장소에는 데모 및 테스트에 안전한 소규모 합성 KiCad 회로도가 포함되어 있습니다:

schematic-mcp --root "$PWD/examples"

그런 다음 MCP 호환 클라이언트가 다음을 호출할 수 있습니다:

open_schematic("minimal.kicad_sch")
schematic_summary()
list_components()
trace_signal("U1", "1")

이 예제는 U1.1을 SENSOR_OUT으로 해석하고 U2.1을 다른 엔드포인트로 표시해야 합니다. examples/README.md를 참조하세요.

펌웨어 ↔ 회로도 검증 데모

두 번째 합성 예제는 코딩 에이전트가 소스 코드만으로는 안전하게 감지할 수 없는 하드웨어 버그를 보여줍니다. 펌웨어는 회로도가 올바른 전기 매핑을 유지하는 동안 의도적으로 SENSOR_INT 및 LED_STATUS GPIO 할당을 바꿉니다.

결정론적 로컬 데모 실행:

python examples/demo_firmware_validation.py

examples/firmware_with_pin_bug.c에서 간단한 GPIO 계약을 추출하고 examples/esp32_firmware_validation.kicad_sch를 파싱하여 두 개의 일치와 두 개의 불일치를 보고합니다.

MCP를 통한 동일한 비교:

open_schematic("esp32_firmware_validation.kicad_sch")
validate_pinmap(
  "U1",
  {
    "GPIO8": "I2C_SDA",
    "GPIO9": "I2C_SCL",
    "GPIO12": "LED_STATUS",
    "GPIO13": "SENSOR_INT"
  }
)

전체 에이전트 워크플로우와 예상 결과는 docs/firmware-validation-demo.md를 참조하세요.

Streamable HTTP

schematic-mcp --transport streamable-http --host 127.0.0.1 --port 8000

MCP 엔드포인트는 http://127.0.0.1:8000/mcp에서 사용할 수 있습니다. 기본 호스트는 루프백 전용입니다. 인증되지 않은 개발 서버를 공개 인터넷에 직접 노출하지 마세요.

MCP Inspector의 경우:

mcp dev src/schematic_mcp/server.py

MCP 클라이언트 구성 예시

{
  "mcpServers": {
    "schematic": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/schematic-mcp", "run", "schematic-mcp"],
      "env": {"SCHEMATIC_MCP_ROOT": "/absolute/path/to/your/hardware-projects"}
    }
  }
}

그런 다음 에이전트가 다음을 호출할 수 있습니다:

open_schematic("board/main.kicad_sch")
get_component("U4")
get_mcu_pinmap("U4")
trace_signal("U4", "12")

파일시스템 보안

기본적으로 로컬 서버는 해당 프로세스가 액세스할 수 있는 경로를 열 수 있습니다. 완전히 신뢰할 수 없는 에이전트의 경우 SCHEMATIC_MCP_ROOT를 설정하거나 허용된 프로젝트 디렉토리로 --root를 전달하세요. 허용된 루트 외부로 해석되는 경로를 포함하여 외부 파일을 열려는 시도는 거부됩니다.

취약점 보고 및 배포 지침은 SECURITY.md를 참조하세요.

현재 제한 사항

V0.1은 의도적으로 작습니다. 계층적 하위 시트는 발견되지만 아직 단일 시트 간 그래프로 재귀적으로 병합되지는 않습니다. 특이한 다중 유닛/라이브러리 구조와 타사 KiCad 내보내기는 여전히 더 광범위한 호환성 픽스처가 필요합니다. 버스 의미 체계는 아직 재구성되지 않았습니다. PDF, Altium 및 EasyEDA는 아직 구현되지 않았습니다.

trace_signal은 해석된 넷 연결성만 따릅니다. IC 내부의 개별 핀이 전기적으로 연결되어 있다고 가정하지 않습니다. validate_pinmap은 명시적 예상 매핑을 비교합니다. 임의의 펌웨어 프레임워크에서 자동 추출하는 것은 아직 핵심 파서의 일부가 아닙니다.

로드맵

• V0.2 — 계층적 KiCad 프로젝트 그래프 및 더 풍부한 버스/넷 의미 체계

• V0.3 — 신뢰도 메타데이터가 포함된 PDF/벡터 회로도 어댑터

• V0.4 — Altium 및 EasyEDA 어댑터

• V0.5 — 데이터시트 컨텍스트 및 전기 규칙 추론

• V0.6 — 프레임워크별 펌웨어 추출(ESP-IDF/Arduino/Zephyr) 및 CI 핀 계약 검사

• 이후 — PCB, BOM, Gerber 및 제조 컨텍스트

장기 목표는 공급업체 중립적인 AI 에이전트용 하드웨어 컨텍스트 서버입니다.

기여

하드웨어 엔지니어, 임베디드 개발자 및 EDA 사용자는 최소한의 호환성 픽스처, 파서 엣지 케이스, 테스트 및 실제 에이전트 워크플로우를 기여함으로써 가장 큰 도움을 줄 수 있습니다.

CONTRIBUTING.md부터 시작하세요. 코딩 에이전트와 유지관리자는 아키텍처 불변성, 안전 제약 조건 및 예상 개발 루프에 대해 AGENTS.md도 읽어야 합니다. 명시적 허가 없이 독점 고객 회로도를 기여하지 마세요.

유용한 유지관리자/프로젝트 문서:

• AGENTS.md — 코딩 에이전트 및 유지관리자 규칙

• docs/project-positioning.md — 프로젝트 경계 및 에코시스템 가치

• docs/architecture.md — 파서/모델/MCP 아키텍처

• docs/firmware-validation-demo.md — 펌웨어 ↔ 회로도 불일치 데모

• examples/README.md — 실행 가능한 합성 픽스처

• CHANGELOG.md — 릴리스 기록

• SECURITY.md — 보안 정책

• docs/oss-readiness.md — 공개 채택 및 OSS 프로그램 준비 체크리스트

라이선스 및 저작자 표시

Apache License 2.0에 따라 라이선스가 부여됩니다. 상업적 사용, 수정 및 재배포는 라이선스 조건에 따라 허용됩니다. 재배포는 Apache-2.0에서 요구하는 대로 해당 저작권, 라이선스 및 NOTICE 정보를 보존해야 합니다.

LICENSE 및 NOTICE를 참조하세요.

원래 SYANKOR에서 개발되었습니다.