콘텐츠로 이동
무료 평가 시작

MCP 서버

pdcomm-opcua-mcp는 OPC UA 시뮬레이터를 MCP(Model Context Protocol) 서버로 제공합니다. Claude Code, Cursor 같은 AI 도구가 시뮬레이터 서버를 시작하고, 접속하고, 노드를 읽고 쓰고, 구독과 알람을 다룰 수 있습니다. 동작과 인자는 헤드리스 시뮬레이터와 같습니다. apps 패키지의 bin/에 있습니다.

도구

섹션 제목: “도구”

시뮬레이터 동작마다 opcua_ 접두사를 붙인 도구가 하나씩 있어 모두 37개입니다. cancel은 도구가 아니며, MCP 취소 알림으로 대신합니다.

작업 공간 도구
connection opcua_capabilities, opcua_state, opcua_configure, opcua_server_start, opcua_server_stop, opcua_server_status, opcua_discover, opcua_connect, opcua_disconnect, opcua_project_export, opcua_project_import
address_space opcua_browse, opcua_server_nodes
read_write_methods opcua_read, opcua_write, opcua_call, opcua_server_write
subscriptions opcua_subscribe, opcua_publish, opcua_notifications, opcua_notifications_clear, opcua_unsubscribe
events opcua_event_subscribe, opcua_alarm_set, opcua_condition, opcua_condition_refresh
history opcua_history_read
pubsub opcua_pubsub_start, opcua_pubsub_publish, opcua_pubsub_status, opcua_pubsub_received, opcua_pubsub_stop
trace opcua_trace, opcua_trace_clear, opcua_logging_configure, opcua_logging_status, opcua_logging_flush

도구의 입력은 헤드리스 동작의 인자 객체입니다. 예를 들어 opcua_read는 {"node":"ns=2;s=Simulator.Double"}을 받습니다. 도구 정의에는 닫힌 입력 스키마(JSON Schema 2020-12)가 있고, 헤드리스 시뮬레이터의 동작 목록과 같은 인자마다 형식, 범위, 설명을 담습니다. 서버는 동작을 실행하기 전에 인자를 이 스키마로 검사하므로, 모르는 인자, 틀린 형식, 범위 밖의 값은 시뮬레이터에 전달되지 않습니다.

MCP 서버 프로세스 하나가 시뮬레이터 하나를 소유합니다. 서버, 세션, 구독은 AI 도구가 프로세스를 끝낼 때까지 유지됩니다.

AI 도구에 연결하기

섹션 제목: “AI 도구에 연결하기”

터미널에서 서버를 등록합니다. 경로는 apps 패키지를 푼 위치로 바꿉니다.

터미널 창
claude mcp add --transport stdio pdcomm-opcua -- /opt/pdcomm/pdcomm-opcua-apps-darwin-arm64/bin/pdcomm-opcua-mcp

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

연결한 뒤 AI 도구에 다음처럼 요청합니다.

  • “OPC UA 시뮬레이터 서버를 시작하고 Simulator.Double을 읽어 줘.”
  • “Simulator 객체를 탐색해서 메서드 목록을 보여 주고, Simulator.Add로 1.5와 2를 더해 줘.”
  • “알람을 활성화하고 이벤트를 받은 뒤 인지해 줘.”

메시지 흐름

섹션 제목: “메시지 흐름”

MCP 클라이언트가 보내는 메시지와 서버의 응답 예입니다. 서버는 initialize를 받은 뒤에 도구 요청을 처리합니다.

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"docs","version":"1"}}}
{"id":1,"jsonrpc":"2.0","result":{"capabilities":{"tools":{"listChanged":false}},"protocolVersion":"2025-06-18","serverInfo":{"name":"pdcomm-opcua","version":"0.1.0"}}}

tools/list의 opcua_read 도구는 다음과 같습니다.

{"description":"Read an attribute of nodes; give node or nodes.","inputSchema":{"$schema":"https://json-schema.org/draft/2020-12/schema","additionalProperties":false,"anyOf":[{"required":["node"]},{"required":["nodes"]}],"properties":{"attribute":{"description":"AttributeId (default 13, Value).","maximum":27,"minimum":1,"type":"integer"},"node":{"description":"Node. NodeId text such as ns=2;s=Simulator.Double or i=85.","maxLength":512,"minLength":1,"type":"string"},"nodes":{"description":"Up to 100 NodeIds; use instead of node.","items":{"description":"Node. NodeId text such as ns=2;s=Simulator.Double or i=85.","maxLength":512,"minLength":1,"type":"string"},"maxItems":100,"minItems":1,"type":"array"}},"required":[],"type":"object"},"name":"opcua_read","title":"Read"}

도구 호출의 결과는 동작 결과 JSON을 담은 텍스트 콘텐츠입니다.

{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"opcua_read","arguments":{"node":"ns=2;s=Simulator.Double"}}}
{"id":5,"jsonrpc":"2.0","result":{"content":[{"text":"{\"values\":[{\"good\":true,\"node\":\"ns=2;s=Simulator.Double\",\"server_time\":1791998196809,\"source_time\":1791998196683,\"status\":\"Good (0x00000000)\",\"type\":\"Double\",\"value\":0.0}]}","type":"text"}],"isError":false}}

동작이 실패하면 isError가 true이고 텍스트가 오류 문장입니다.

{"id":6,"jsonrpc":"2.0","result":{"content":[{"text":"NodeId must use i= or s= identifiers","type":"text"}],"isError":true}}

입력 스키마에 맞지 않는 인자는 Invalid arguments:로 시작하는 메시지로 거부합니다. 거부 방식은 MCP 사양에 따라 협상한 프로토콜 버전마다 다릅니다. 2025-06-18과 2024-11-05에서는 JSON-RPC 오류 -32602입니다.

{"jsonrpc":"2.0","id":7,"method":"tools/call","params":{"name":"opcua_read","arguments":{"nodes":"ns=2;s=Simulator.Double"}}}
{"error":{"code":-32602,"message":"Invalid arguments: nodes must be an array"},"id":7,"jsonrpc":"2.0"}

2025-11-25에서는 isError가 true인 도구 결과입니다. AI 도구는 이 메시지를 보고 호출을 고칠 수 있습니다.

{"id":7,"jsonrpc":"2.0","result":{"content":[{"text":"Invalid arguments: nodes must be an array","type":"text"}],"isError":true}}

프로토콜 오류

섹션 제목: “프로토콜 오류”
오류 의미
-32601 Unknown method or server is not initialized initialize 전에 요청했거나 지원하지 않는 메서드입니다.
-32602 Unknown tool: <이름> 없는 도구 이름입니다. 예를 들어 opcua_shutdown은 도구가 아닙니다.
-32602 Invalid arguments: <이유> 프로토콜 2025-06-18이나 2024-11-05에서 인자가 도구의 입력 스키마에 맞지 않습니다.
-32602 Arguments must be an object arguments가 객체가 아닙니다.
-32700 JSON으로 해석할 수 없는 줄입니다.

notifications/cancelled로 실행 중인 요청을 취소하면 그 요청은 중단되고 응답을 보내지 않습니다. 표준 입력이 닫히면 서버는 시뮬레이터를 정리하고 끝납니다.

보안 주의

섹션 제목: “보안 주의”
  • MCP 서버는 AI 도구가 시킨 대로 이 컴퓨터에서 서버를 열고 네트워크에 접속합니다. 신뢰하는 AI 도구에만 연결합니다.
  • 암호는 opcua_server_start, opcua_connect의 password 인자로 넘깁니다. 시뮬레이터는 암호를 응답과 로그에 남기지 않지만, AI 도구의 대화 기록에는 남을 수 있습니다. 시험용 암호를 씁니다.

다음 단계

섹션 제목: “다음 단계”

개인정보 처리방침