instrument-mcp: Instructions file for Claude Code

Instrument MCP Server - Project Rules

Project Overview

계측기(오실로스코프, 로직 분석기, 멀티미터, 파워서플라이)를 MCP(Model Context Protocol)를 통해 AI에 연결하는 오픈소스 Python 서버.

Tech Stack

• Language: Python 3.12+
• MCP Framework: FastMCP (fastmcp)
• Instrument Communication: PyVISA + pyvisa-py (SCPI/VISA), saleae (Saleae API), pyserial
• Testing: pytest + pytest-asyncio
• Packaging: pyproject.toml (PEP 621)
• Linting: ruff

Directory Structure

src/
├── server.py              # MCP 서버 진입점, FastMCP 인스턴스 생성
├── config.py              # 설정 관리 (safety limits, connection defaults)
├── safety.py              # 안전 계층: 쓰기 동작 승인, 범위 제한
├── drivers/
│   ├── __init__.py
│   ├── base.py            # InstrumentDriver 추상 베이스 클래스
│   ├── visa_driver.py     # SCPI/VISA 공통 드라이버
│   ├── saleae_driver.py   # Saleae 전용 드라이버
│   └── serial_driver.py   # 시리얼 통신 드라이버
├── tools/
│   ├── __init__.py
│   ├── oscilloscope.py    # scope_* Tool 정의
│   ├── logic_analyzer.py  # logic_* Tool 정의
│   ├── multimeter.py      # dmm_* Tool 정의
│   └── power_supply.py    # psu_* Tool 정의
├── mock/
│   ├── __init__.py
│   ├── mock_scope.py      # 가상 오실로스코프
│   ├── mock_logic.py      # 가상 로직 분석기
│   ├── mock_dmm.py        # 가상 멀티미터
│   ├── mock_psu.py        # 가상 파워서플라이
│   └── sample_data/       # 샘플 파형/프로토콜 JSON
├── resources/             # MCP Resource 정의 (데이터시트 스펙 등)
└── utils/
    ├── __init__.py
    ├── waveform.py        # 파형 분석 유틸리티
    └── protocol.py        # 프로토콜 디코드 유틸리티
tests/
├── unit/                  # Mock 기반 단위 테스트
└── integration/           # 실장비 연동 테스트 (CI에서 skip)

Architecture Rules

3-Layer Architecture

1. Tool Layer (src/tools/) - MCP Tool 정의. AI에게 노출되는 인터페이스. 비즈니스 로직 없음.
2. Driver Layer (src/drivers/) - 장비 통신 추상화. SCPI 명령 조합, 응답 파싱.
3. Safety Layer (src/safety.py) - 모든 쓰기 동작을 가로채서 범위 검증. Driver를 직접 호출하지 않고 Safety를 거침.

Tool → Safety → Driver 호출 흐름

Tool 함수 → safety.validate_write() → Driver.send_command()
Tool 함수 → Driver.query() (읽기는 Safety 불필요)