헤드리스와 MCP

GUI 없이 PubSub over MQTT를 쓰려면 헤드리스 시뮬레이터 pdcomm-opcua-headless나 MCP 서버 pdcomm-opcua-mcp를 씁니다. 둘 다 시뮬레이터 패키지의 bin/에 있고, GUI와 같은 시뮬레이터 서비스를 실행합니다.

헤드리스 실행 방식

실행	동작
`bin/pdcomm-opcua-headless`	표준 입력에서 JSON 명령을 한 줄씩 읽고, 결과를 한 줄씩 표준 출력에 씁니다. 입력이 끝나거나 `shutdown`을 받으면 종료합니다.
`bin/pdcomm-opcua-headless --scenario <파일>`	시나리오 파일의 단계를 차례로 실행하고 단계마다 결과를 한 줄 출력합니다.

대화형 실행의 응답은 {"ok":true,"result":…}나 {"ok":false,"error":"…"}입니다. 실패한 명령이나 해석할 수 없는 줄이 하나라도 있었으면 종료 코드는 1, 아니면 0입니다. 명령 한 줄은 1 MiB를 넘을 수 없습니다.

시나리오 파일은 다음 형식의 배열입니다. 파일은 1 MiB, 단계는 10,000개까지입니다.

키	뜻
`command`	실행할 명령 객체. 대화형 명령과 같습니다.
`expect`	결과 객체에서 같은 이름의 값이 같아야 합니다. 생략할 수 있습니다.
`expect_error`	`true`이면 이 단계가 실패해야 통과합니다. 결과 줄에는 `{"error":"…"}`가 나옵니다.

출력은 {"step":1,"result":…} 형식입니다. 한 단계라도 기대와 다르면 Scenario step 2 failed: …처럼 표준 오류에 쓰고 종료 코드 1로 끝납니다. 잘못된 인수는 사용법을 출력하고 종료 코드 2로 끝납니다.

명령	인수	결과
`configure`	`config`: 전체 구성 객체	현재 상태(`state`와 같음)
`pubsub_start`	없음	PubSub 상태
`pubsub_publish`	`fields`: 형식이 붙은 값 배열(1~64개). 생략하면 Boolean `true`, Int32 `42`, Double `3.5`, String `pdcomm`	`sequence`, `bytes`, `fields`
`pubsub_status`	없음	PubSub 상태. 실행 중이 아니면 `{"running":false}`
`pubsub_received`	없음	`messages`: 받은 메시지 배열. 꺼낸 메시지는 대기열에서 지워집니다.
`pubsub_stop`	없음	`{"running":false}`
`state`	없음	구성과 서버, 클라이언트, PubSub 상태
`capabilities`	없음	지원 기능. `"pubsub":{"encoding":"uadp","mqtt":true,"udp":true}`
`trace`	없음	최근 동작 기록
`shutdown`	없음	모든 연결을 닫고 헤드리스 시뮬레이터를 끝냅니다(대화형 전용).

필드 형식 이름은 시뮬레이터 PubSub 화면의 DataSet fields와 같습니다.

키	뜻	기본값
`transport`	`mqtt` 또는 `udp`	`udp`
`role`	`both`, `publisher`, `subscriber`	`both`
`broker`	브로커의 `IP 주소:포트`	`127.0.0.1:1883`
`topic`	발행하고 구독할 토픽. 와일드카드 불가, 1~256바이트	`pdcomm/opcua/simulator`
`publisher_id`	NetworkMessage의 PublisherId(1~65535)	77
`writer_group_id`	WriterGroupId(1~65535)	1
`dataset_writer_id`	DataSetWriterId(1~65535)	17
`listen`, `destination`	UDP 전용

브로커 연결 제한 시간은 client.timeout_ms(기본 5000)입니다.

키	뜻
`running`	작업 스레드가 실행 중인지 여부. 브로커 연결이 끊기면 `false`가 됩니다.
`transport`, `role`	시작할 때의 전송과 역할
`broker`, `topic`	MQTT일 때 연결한 브로커와 토픽. UDP이면 `null`
`listen`, `destination`	UDP일 때의 주소. MQTT이면 `null`
`sent`	발행한 메시지 수
`acknowledged`	브로커가 PUBACK 성공으로 확인한 수
`received`	받아들인 메시지 수
`rejected`	받았지만 거부한 메시지 수
`queued`	`pubsub_received`로 아직 꺼내지 않은 메시지 수(최대 256)
`dropped`	대기열이 가득 차 버린 메시지 수
`error`	마지막 오류. 없으면 `null`

pdcomm-opcua-mcp는 표준 입출력으로 JSON-RPC를 주고받는 MCP(Model Context Protocol) 서버입니다. MCP 클라이언트 설정에 실행 파일을 등록합니다.

{
  "mcpServers": {
    "pdcomm-opcua": {
      "command": "<시뮬레이터 패키지 디렉터리>/bin/pdcomm-opcua-mcp"
    }
  }
}

서버 이름은 pdcomm-opcua이고, 프로토콜 버전 2025-11-25, 2025-06-18, 2024-11-05를 지원합니다.
도구 이름은 헤드리스 명령 앞에 opcua_를 붙인 것입니다. PubSub 도구는 opcua_pubsub_start, opcua_pubsub_publish, opcua_pubsub_status, opcua_pubsub_received, opcua_pubsub_stop입니다.
도구 인수는 헤드리스 명령에서 action을 뺀 객체입니다.
결과는 JSON 문자열 하나를 담은 텍스트 콘텐츠입니다. 실패하면 isError가 true이고 텍스트가 오류 문장입니다.

다음은 MCP로 PubSub over MQTT를 실행한 예입니다. 요청마다 응답의 텍스트 콘텐츠만 적었습니다.

도구 호출	결과 텍스트
`opcua_configure` `{"config":{"pubsub":{"transport":"mqtt","role":"both","broker":"127.0.0.1:1883","topic":"opcua/uadp/data/77/mcp"}}}`	현재 상태
`opcua_pubsub_start` `{}`	`{"acknowledged":0,"broker":"127.0.0.1:1883",…,"running":true,…,"topic":"opcua/uadp/data/77/mcp","transport":"mqtt"}`
`opcua_pubsub_publish` `{"fields":[{"type":"Int32","value":7}]}`	`{"bytes":38,"fields":1,"sequence":1}`
`opcua_pubsub_received` `{}`	`{"messages":[{"bytes":38,"datasets":[{"fields":[{"type":"Int32","value":7}],…}],"publisher_id":77,"source":"mqtt",…}]}`
`opcua_pubsub_stop` `{}`	`{"running":false}`
`opcua_pubsub_stop` `{}`(다시)	`isError: true`, `PubSub is not running`

AI 도구에서 PDComm 문서도 함께 찾게 하려면 AI 도구에서 PDComm 문서 사용하기를 참고합니다.