# Instrument MCP Server

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

자연어로 계측기를 제어하고, 측정 결과를 AI가 분석하여, 프로젝트 맥락에서 진단과 해결책을 제시합니다.

```
사용자: "3.3V LDO 출력에 리플이 많은 것 같아. 확인해줘"

Claude → scope_connect → scope_capture → scope_analyze_ripple

Claude: "Vpp 리플 210mV (6.4%), 주 주파수 180kHz.
        스위칭 레귤레이터 주파수와 일치하므로
        입력측 바이패스 캡 추가를 권장합니다."
```

## 요구사항

- Python 3.12+
- (실장비 모드) VISA 호환 계측기 + USB-TMC 또는 LAN 연결
- (Mock 모드) 장비 없이 가상 데이터로 모든 기능 테스트 가능

## 설치

```bash
git clone https://github.com/your-org/instrument-mcp-server.git
cd instrument-mcp-server
pip install -e ".[dev]"
```

## 적용 방법

### 1. Claude Desktop

`claude_desktop_config.json`에 추가:

**Mock 모드 (장비 없이 테스트):**
```json
{
  "mcpServers": {
    "instrument": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "D:\\seriouscode\\app_dev\\MCP",
      "env": {
        "INSTRUMENT_MCP_MOCK": "1"
      }
    }
  }
}
```

**실장비 모드:**
```json
{
  "mcpServers": {
    "instrument": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "D:\\seriouscode\\app_dev\\MCP"
    }
  }
}
```

> 설정 파일 위치:
> - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
> - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

### 2. Claude Code (CLI)

```bash
# Mock 모드
cd D:\seriouscode\app_dev\MCP
claude mcp add instrument -- python -m src.server
```

또는 `.claude/settings.local.json`에 직접 추가:
```json
{
  "mcpServers": {
    "instrument": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "D:\\seriouscode\\app_dev\\MCP",
      "env": {
        "INSTRUMENT_MCP_MOCK": "1"
      }
    }
  }
}
```

### 3. Cursor / VS Code (Copilot)

`.cursor/mcp.json` 또는 `.vscode/mcp.json`:
```json
{
  "servers": {
    "instrument": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "D:\\seriouscode\\app_dev\\MCP",
      "env": {
        "INSTRUMENT_MCP_MOCK": "1"
      }
    }
  }
}
```

### 4. Windsurf (Codeium)

`~/.codeium/windsurf/mcp_config.json`:
```json
{
  "mcpServers": {
    "instrument": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "D:\\seriouscode\\app_dev\\MCP",
      "env": {
        "INSTRUMENT_MCP_MOCK": "1"
      }
    }
  }
}
```

### 5. 범용 (FastMCP CLI)

```bash
# Mock 모드 직접 실행
INSTRUMENT_MCP_MOCK=1 python -m src.server

# Windows
set INSTRUMENT_MCP_MOCK=1 && python -m src.server

# pip install 후 entrypoint 사용
INSTRUMENT_MCP_MOCK=1 instrument-mcp
```

## MCP Tool 목록

### 오실로스코프 (6개)

| Tool | 설명 |
|------|------|
| `scope_connect` | VISA 주소로 오실로스코프 연결 |
| `scope_disconnect` | 연결 해제 |
| `scope_measure` | Vpp, 주파수, Vrms 등 측정값 반환 |
| `scope_capture` | 파형 캡처 실행 (자동/수동 타임베이스) |
| `scope_analyze_ripple` | 전원 레일 리플/노이즈 측정 |
| `scope_list_resources` | 연결 가능한 VISA 장비 목록 |

### 로직 분석기 (6개)

| Tool | 설명 |
|------|------|
| `logic_connect` | 로직 분석기 연결 |
| `logic_capture` | 디지털 신호 캡처 |
| `logic_decode_spi` | SPI 버스 디코딩 |
| `logic_decode_i2c` | I2C 버스 디코딩 (ACK/NACK 포함) |
| `logic_decode_uart` | UART 통신 디코딩 |
| `logic_check_timing` | 신호 타이밍 스펙 준수 검증 |

### 멀티미터 (2개)

| Tool | 설명 |
|------|------|
| `dmm_connect` | 멀티미터 연결 |
| `dmm_measure` | VDC/VAC/IDC/RES/FREQ 등 측정 |

### 파워서플라이 (5개)

| Tool | 설명 |
|------|------|
| `psu_connect` | 파워서플라이 연결 |
| `psu_set_output` | 출력 전압/전류 설정 (**Safety 검증**) |
| `psu_enable` | 출력 ON/OFF |
| `psu_read_actual` | 실제 출력 전압/전류 읽기 |
| `psu_status` | 채널 설정 상태 조회 |

### 유틸리티 (1개)

| Tool | 설명 |
|------|------|
| `instrument_status` | 전체 장비 연결 상태 확인 |

## 안전 제한 (Safety Layer)

파워서플라이 제어에는 하드웨어 보호를 위한 안전 제한이 적용됩니다:

| 항목 | 기본값 | 설명 |
|------|--------|------|
| 최대 전압 | 30V | 이 이상 설정 불가 |
| 최대 전류 | 3A | 이 이상 설정 불가 |
| 전압 스텝 | 5V | 한 번에 변경 가능한 최대 차이 |
| 전류 스텝 | 1A | 한 번에 변경 가능한 최대 차이 |
| 차단 명령 | `*RST`, `*CAL`, `SYST:PRES` | 위험 SCPI 명령 실행 불가 |

기본값 변경은 `~/.instrument-mcp/config.json`:
```json
{
  "safety": {
    "max_voltage": 12.0,
    "max_current": 1.0,
    "max_voltage_step": 3.0
  }
}
```

## 환경변수

| 변수 | 값 | 설명 |
|------|------|------|
| `INSTRUMENT_MCP_MOCK` | `1` / `true` | Mock 모드 활성화 |
| `INSTRUMENT_MCP_LOG_LEVEL` | `DEBUG` / `INFO` / `WARNING` | 로그 레벨 |

## 지원 장비 (Phase 1)

| 종류 | 제조사/모델 | 연결 |
|------|-------------|------|
| 오실로스코프 | Rigol DS1054Z, Siglent SDS1104 | USB-TMC / LAN (SCPI) |
| 로직 분석기 | Saleae Logic 8/Pro | USB (Saleae API) - Phase 2 |
| 멀티미터 | Rigol DM3058, Siglent SDM3045X | USB-TMC / LAN (SCPI) |
| 파워서플라이 | Rigol DP832, Siglent SPD3303X | USB-TMC / LAN (SCPI) |

SCPI 표준을 지원하는 다른 VISA 호환 장비도 대부분 동작합니다.

## 개발

```bash
# 테스트
python -m pytest tests/ -v

# 린트
ruff check src/ tests/

# Mock 모드 서버 실행
set INSTRUMENT_MCP_MOCK=1 && python -m src.server
```

## 프로젝트 구조

```
src/
├── server.py          # MCP 서버 진입점
├── config.py          # 설정 및 안전 제한값
├── safety.py          # Safety Layer (쓰기 동작 검증)
├── drivers/           # 장비 통신 드라이버
│   ├── base.py        # 추상 베이스 클래스
│   └── visa_driver.py # SCPI/VISA 드라이버
├── tools/             # MCP Tool 정의
│   ├── oscilloscope.py
│   ├── logic_analyzer.py
│   ├── multimeter.py
│   └── power_supply.py
├── mock/              # 가상 장비 드라이버 (테스트용)
│   ├── mock_scope.py
│   ├── mock_logic.py
│   ├── mock_dmm.py
│   └── mock_psu.py
└── utils/             # 파형/프로토콜 분석 유틸리티
```

## 라이선스

MIT License