MCP로 가상 시리얼 제어하기

pdcomm-vserial-mcp는 MCP(Model Context Protocol) 서버입니다. Claude Code, Cursor 같은 AI 도구가 이 서버로 가상 시리얼 랩을 만들고 결함을 넣고 멈춥니다. 시리얼 통신 코드를 AI와 함께 시험할 때 사용합니다.

서버는 표준 입출력(stdio)으로 줄 단위 JSON-RPC 메시지를 주고받습니다. 프로토콜 버전 2025-11-25, 2025-06-18, 2024-11-05를 지원합니다. 한 서버는 랩을 하나만 실행합니다. AI 도구가 연결을 끊어 입력이 닫히면 실행 중인 랩도 멈춥니다.

도구

도구	인수	결과
`vserial_validate`	`config`: 랩 JSON 객체	`{"valid":true}`
`vserial_start`	`config`: 랩 JSON 객체	`{"ports":[…]}`. 포트마다 응용 프로그램이 열 경로나 주소가 있습니다.
`vserial_ports`	없음	실행 중인 랩의 `{"ports":[…]}`
`vserial_inject`	`node`, `fault`	`{"injected":true}`
`vserial_attach`	`node`, `attached`	`{"attached":false}` 또는 `{"attached":true}`
`vserial_stop`	없음	`{"stopped":true}`

config는 랩 파일과 같은 형식입니다. fault는 "drop", {"xor": n}, {"error": "parity"}처럼 명령줄의 inject와 같습니다. trace의 상대 경로는 MCP 서버의 작업 폴더를 기준으로 합니다.

도구 실행이 실패하면 결과의 isError가 true이고 본문에 원인이 있습니다. 예를 들어 랩이 이미 실행 중이면 a lab is already running; stop it first, 실행 중인 랩이 없으면 no lab is running을 돌려줍니다. 없는 도구를 부르면 JSON-RPC 오류 -32602(Unknown tool: <이름>)로 응답합니다.

AI 도구에 연결하기

이 예시는 서버가 /opt/pdcomm-vserial/bin/pdcomm-vserial-mcp에 있다고 가정합니다. 실제 경로로 바꿉니다.

Claude Code
다른 MCP 클라이언트

claude mcp add --transport stdio pdcomm-vserial -- /opt/pdcomm-vserial/bin/pdcomm-vserial-mcp

claude mcp list를 실행하거나 세션에서 /mcp를 입력해 연결을 확인합니다.

stdio 전송을 지원하는 클라이언트의 설정 파일에 다음을 추가합니다.

{
  "mcpServers": {
    "pdcomm-vserial": {
      "command": "/opt/pdcomm-vserial/bin/pdcomm-vserial-mcp",
      "args": []
    }
  }
}

사용 예

AI 도구에 다음처럼 요청합니다.

19200bps 짝수 패리티 널 모뎀 쌍을 /tmp/pdcomm-plc, /tmp/pdcomm-hmi 링크로 시작해 줘. 그다음 hmi 포트에 프레이밍 오류를 한 번 넣어 줘.

AI 도구는 vserial_start와 vserial_inject를 차례로 부릅니다. vserial_start의 결과는 다음과 같습니다.

{"ports":[{"backend":"pty","link":"/tmp/pdcomm-plc","node":"plc","path":"/dev/ttys011"},{"backend":"pty","link":"/tmp/pdcomm-hmi","node":"hmi","path":"/dev/ttys016"}]}

의사 터미널 포트는 MCP 서버가 실행 중인 컴퓨터에 생깁니다. 응용 프로그램도 같은 컴퓨터에서 실행합니다. 시험이 끝나면 AI 도구에 랩을 멈추라고 요청합니다(vserial_stop).