MCP 빠른 시작 — 실제 도구 한 번으로 DSLText 확인
적용: 새 원문 DS2-SPEC-V2.0·ds2/v2, 기존 원문 DS2-SPEC-V1.1·ds2/v1, additive dsdx-mcp-entry/1.
1. 첫 호출
연결한 AI 클라이언트에서 실제로 다음 MCP 도구를 호출합니다.
{"name":"dsdx.start","arguments":{}}
짧은 목표를 함께 넘길 수도 있습니다: {"name":"dsdx.start","arguments":{"goal":"차체 조립 공정을 시작하고 싶어요"}}.
goal은 500자 이하 힌트입니다. 서버는 공식 ST 조건식 예제 examples/st-expression/st-conditions-v2.ds2 정본과 실제 컴파일 영수증을 돌려줍니다. 사용자 목표에 맞춘 공정 생성·반영·등록 결과가 아니며 goalGenerated=false, adopted=false, registration=NOT_PERFORMED, physicalExecution=NOT_RUN입니다.
현재 대화에 DSDX 도구가 보이지 않으면 MCP 연결 미확인으로 알리고 6탭 구성의 AI 연결 안내(/mcp-guide) (빠른 시작·도구, #product-download, #ide-mcp-guide, #vscode-guide, 사진·MC·Factory, 문서·FAQ · #tool-catalog)에서 클라이언트에 서버를 등록합니다. 브라우저의 서버 응답 진단만으로는 외부 AI 클라이언트의 연결이나 도구 노출을 입증할 수 없습니다.
2. 응답에서 확인할 항목
source:ds2 v2;로 시작하는 실제.ds2원문입니다. 응답의languageVersion(ds2/v2)과specVersion을 함께 확인합니다.document: 공식 문서 ID·버전·출처·본문 해시입니다.compileReceipt:dsdx.start에 포함된 공식 시작 예제의 서버 컴파일 영수증(원문/정규문 해시,sealDigest, 작업·관계 수, 진단 결과 —DS2-E001..E029·DS2-W002·DS2-I002포함)입니다. (ds2 v2;원문 최대 크기1 MiB/1,048,576바이트, UTF-8 무-BOM · LF 전용)buildCommit: 응답을 만든 실제 Host 빌드 커밋입니다. (dsdx.verify.run·dsdx.ai.probe는 정본 판정PASS | FAIL | NOT_RUN | UNSUPPORTED | INCONCLUSIVE와 주행 추적·3-round 기본 3라운드 증거·CALL-TOKEN-BOUNDARY-1토큰 격리/대여·FiredEdgeIndices인과 귀속을 반환하며, 미지원 Call·개루프 경로는GUARD-E422_UNSUPPORTED_OR_UNMEASURED/HOST-E422_CALL_EXECUTION_UNSUPPORTED로 거절하고 미복구 결함 시FAIL봉인 및 검증 실패 시 후속 내보내기/수정 제안을 생략합니다.)preflightAdvisories(dsdx.artifact.export전용): PLC·산출물 내보내기 시 사전점검 권고(PREFLIGHT-W001..W005)와 묶음 상태(CAPABILITY_UNSUPPORTED)를 반환합니다.serverSteps: 서버가 내부에서 실행한 조회 기록입니다. AI 클라이언트가 별도 MCP 호출을 했다는 뜻이 아닙니다.
HTML 회전 큐브, 임의 JSON/YAML, 파일에 적어 둔 READY/REGISTERED 문구는 DSLText나 서버 등록 증거가 아닙니다. 공개 Web MCP(/mcp, 읽기 전용 10개 도구)에서는 PRIVACY-E403 정책상 원격 컴파일·실행·생산 평가가 차단되며 zero-retention 정책에서는 영구 저장이 거부됩니다. 작성한 .ds2 초안은 UNVERIFIED_DRAFT로 표기해 /play#source(브라우저 로컬 WASM)에서 확인하고, 로컬 stdio MCP(Dsdx.Authoring --stdio) 또는 소유자 인증 환경에서만 dsdx.compile·dsdx.verify.run(논리 진단 MILS와 PC 제어·실생성 타깃을 실행하는 VENDOR_PLC · Virtual Kit SILS 구분)에 넣어 독립 검증합니다.
3. 3D로 이어 가기
nextCalls에 들어 있는 실제 도구 이름과 인자를 그대로 씁니다. 공개 Web MCP에서는 조회형 도구만 실행하고 작성 원문 검증은 /play#source를 사용하며, 로컬 stdio MCP(Dsdx.Authoring --stdio)에서는 반환된 원문을 그대로 dsdx.compile에 보내 확인하고 공식 작성 가이드의 G-01 절을 읽습니다. 목표(goal)에 3D·3차원·카탈로그·뷰어 요청이 적혀 있고 서버에 선택형 엔진이 설정되어 있을 때만 카탈로그·layout 조회가 다음 호출에 붙습니다. 엔진이 설정되지 않았으면 viewer.url은 null이며 설정 누락 사유를 돌려줍니다. 첫 카탈로그 조회는 작게 제한합니다.
{"name":"dsdx.scene.catalog","arguments":{"action":"search","query":"conveyor","limit":3}}
카탈로그에서 받은 실제 provider/version/hash만 사용합니다. 표시용 작업공간은 dsdx.scene.layout의 action=get으로 조회합니다. 3D 경로가 제공된 경우 viewer.url은 현재 활성 프로젝트의 공유 DISPLAY_PREVIEW 작업공간이며 공식 예제의 자동 생성 장면이 아닙니다. configured=true는 설정이 존재한다는 뜻일 뿐이며, 연결·실제 geometry·물리 제어 검증은 각각 실행 결과로 확인합니다. 엔진 미설정이나 통신 실패 시 해당 오류를 그대로 두고 임의 큐브로 대체하지 않습니다.
4. 실패 복구
도구 응답의 isError와 Host status/error.code를 확인합니다. dsdx.start 입력 오류의 error.nextCall은 바로 실행 가능한 시작 호출입니다. 컴파일 문법 오류나 알 수 없는 도구 호출에는 MCP _meta.recovery와 별도 text content로 정본 예제 조회용 nextCall을 안내합니다. 명령형 연산(publish_link, revoke_link, job.cancel, plan.invoke, run.create, run.command, job.resume)은 중복 실행 방지를 위해 ASCII idempotency_key가 필요합니다. job 상태나 버전 충돌 같은 다른 오류에는 입문 예제로 돌아가는 안내를 붙이지 않습니다.
초기화(initialize)의 protocolVersion은 문자열이어야 하며, 알려진 MCP 메서드의 params는 전달할 경우 객체여야 합니다. 자료형이 다르면 연결을 끊지 않고 -32602로 거절합니다.
tools/call의 name/arguments 형식이 틀리면 프로토콜 오류 -32602와 정확한 시작 인수를 돌려줍니다. resource 오류는 error.data.nextRequest의 resources/list로 허용 URI를 확인합니다. resources/read는 광고된 URI만 읽고 임의 로컬 경로는 열지 않습니다.
5. 호환 범위
기존 28개 Host 정규 연산과 호환 별칭은 그대로 유지합니다(정확한 목록은 런타임 tools/list 기준). 주요 도구로 시작 도구 dsdx.start(ds2/v2 기본 st-conditions-v2.ds2 및 ds2/v1 01_chain.ds2), 공식 예제 dsdx.examples.list·get, 계층별 구문 카드 dsdx.ai.probe, 공개 3D 라이브러리 dsdx.library.search·get·download(1,345종 설비 · .ds2 연결 1,258종 · 10대 라인 예제 · .aasx/.ds2/GLB 다운로드), 산출물 내보내기 dsdx.artifact.export(7탭 V3 쇼케이스 showcase-html · 수동 조그 MutexSafe/ZoneSafe를 적용한 7대 PLC 패키지 · 시스템 단위 SequenceControlData.Edges[Sources/Targets] 및 조건부 AID/AIMC .aasx 패키지)를 제공합니다. Client Zero-Exposure 정책에 따라 공개 Web MCP(/mcp, /mcp-exp)는 고객 .ds2 원문 보호를 위해 읽기 전용 10개 도구만 노출하며(호환 HTTP 및 DS Studio Desktop --local-agent는 73개, /healthz·/llms.txt·dsdx.ping 노출 수는 tools/list와 일치), 컴파일·검증·PLC/AASX 출력·DSD 진단 포함 전체 89개 도구는 소유자 인증 또는 내 PC의 로컬 MCP(Dsdx.Authoring --stdio)에서 실행합니다. MCP 프로토콜 2025-11-25·2025-06-18, --stdio 전송, resources/*, HTTP gzip을 지원하며, id 없는 notification은 stdio 무응답·HTTP 202로 처리합니다. Prompts·자동 프로젝트 변경·웹 API 키 등록은 포함하지 않습니다.
5.1 전용 AI IDE (Antigravity · Claude · Gemini · OpenAI Codex) 및 VS Code MCP 등록 요약
사용자 정보 보호 방침에 따라 공정 원문(.ds2)과 설계 데이터는 웹 /play의 API 키 입력 대신 웹 [DS2 코드 편집기] + 클립보드 브리지를 쓰거나, 로컬 제품(단일 dsdx-vscode-latest.vsix v2.2.3 · DS Studio Desktop --local-agent · 1클릭 로컬 Dsdx.Authoring --stdio 설치기)으로 내 PC 안에서 작성·검증하는 것을 원칙으로 합니다.
- VS Code 없이 전용 AI IDE 원클릭 자동 설치 (
Antigravity·Claude·Gemini·OpenAI Codex·Cursor·Windsurf): - Windows 원클릭:
/download/dsdx-mcp-setup.cmd?dl=1또는powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://dualsoft.ai/download/install-local-mcp.ps1 | iex"(단일dsdx-vscode-latest.vsix에서Dsdx.Authoring.exe만 추출해 7대 IDE 설정 파일에 자동 병합, 2중.zip없음) - Claude (
Claude Code/Claude Desktop): - 공개 읽기 전용 HTTP:
claude mcp add --transport http ds-studio https://dualsoft.ai/mcp - 로컬 무노출 전체 도구 stdio: 1클릭 설치기 실행(권장) 또는 수동 경로
"command": "C:/Users/<user>/AppData/Local/DualSoft/DSDX/mcp/Dsdx.Authoring.exe", "args": ["--stdio"](JSON 설정에서는%LOCALAPPDATA%가 확장되지 않으므로<user>를 실제 사용자명으로 바꾸고, VS Code.vscode/mcp.json만"${env:LOCALAPPDATA}/DualSoft/DSDX/mcp/Dsdx.Authoring.exe"사용 가능) - Gemini (
Google AntigravityIDE /Gemini CLI): - Antigravity
mcp_config.json· Gemini CLI~/.gemini/settings.json: 원클릭 설치기로 로컬"dsdx"(Dsdx.Authoring.exe --stdio) 자동 등록 또는 읽기 전용serverUrl/httpUrl(https://dualsoft.ai/mcp) - OpenAI (
Codex CLI/Codex IDE 확장/Codex 데스크톱 앱): - CLI 한 줄(읽기 전용):
codex mcp add ds-studio --url https://dualsoft.ai/mcp ~/.codex/config.toml로컬 무노출: 1클릭 설치기로 자동 병합(권장) 또는 수동[mcp_servers.dsdx]아래command = "C:/Users/<user>/AppData/Local/DualSoft/DSDX/mcp/Dsdx.Authoring.exe",args = ["--stdio"](<user>를 실제 Windows 사용자명으로 교체)- VS Code 에이전트 모드 (
.vscode/mcp.json): - VS Code
1.106+에서는 단일 패키지dsdx-vscode-latest.vsix설치 후 작업실(Flow·SCADA·3D·MILS·PLC)을 사용하면서 명령 팔레트의dsdx.registerLocalMcp한 번으로 외부 AI IDE에도 동일 로컬 MCP를 등록할 수 있습니다. - 6탭 비스크롤 구성의 전체 안내는 AI 연결 안내(
/mcp-guide) (빠른 시작·도구, 제품 다운로드, AI IDE 설정, VS Code 가이드,사진·MC·Factory, 도구 카탈로그)에서 확인할 수 있습니다.
6. 생성한 DSLText의 검증 증거
공식 예제를 읽은 뒤 새로 만들거나 고친 전체 원문을 실제 dsdx.compile에 보냅니다. 성공한 서버 응답의 sourceSha256이 그 원문의 UTF-8 SHA-256과 일치해야 컴파일을 통과한 초안으로 표시합니다. 한 글자라도 고치면 다시 컴파일합니다. 이전 예제의 영수증이나 AI가 임의로 적은 validation=true, READY 문구는 새 원문의 증거가 아닙니다.
도구를 호출할 수 없거나 컴파일이 실패하면 미검증 초안 (UNVERIFIED_DRAFT) 으로 표시하고 완료·반영·등록을 주장하지 않습니다. 컴파일 성공은 문법과 정적 규칙 확인이며, 요구사항 충족·실행 결과·물리 제어 인수는 별개입니다. 공식 HTTP 문서와 실제 컴파일러를 쓰는 경로도 같은 증거 원칙을 따릅니다.
PLAY의 AI 제안은 서버가 받은 원문을 직접 컴파일합니다(로컬 에이전트·호환 모드 기준; 원격 공개 Web에서는 브라우저 로컬 WASM만 사용). 오류가 있으면 HTTP 422와 실제 진단·거절한 원문을 돌려주고 성공 제안이나 3D 배치 생성으로 넘어가지 않습니다. 성공 응답의 compileReceipt는 서버가 만들며, AI의 summary는 제안 설명일 뿐 검증 근거가 아닙니다. 기존 프로젝트는 명시적 검토·반영 전까지 바뀌지 않습니다.
7. 복사해서 쓰는 DSL·3D 에이전트 지침
다음 지침은 실행 서버의 문서·도구 스키마와 함께 씁니다. 문서 접근, 컴파일, 3D 표시, 물리 인수는 각각 따로 확인합니다.
DualSoft DSLText 및 lib3D 작업에서 다음 순서를 지킨다.
>
1.
docs_search로 관련 문서를 찾고docs_read로 새 원문은AI-ST-KIT·ST-EXPR-SPEC·grammar/ds2-v2.ebnf(DS2-SPEC-V2.0,version생략 시 문서별 정본 프로필 자동 선택), 기존ds2 v1;원문과 공개 규격은SPEC-00·SPEC-04·MCP-START·MCP-GEN-GUIDE·grammar/ds2-v1.ebnf(DS2-SPEC-V1.1)와 관련 골든 예제를 읽거나dsdx.ai.probe의guidanceProfile("compact"·"standard"·"reasoning")로 계층별 핵심 구문 카드를 확인한다(SPEC-01..03,SPEC-05등 내부 정본은 소유자 인증 환경에서만 열람 가능). 실제 문서 버전·본문 해시와 실행 서버buildCommit을 기록한다. 도구 이름·필수 인수는 현재tools/list에서 확인한다.2. DSL의 편집 정본은
.ds2원문이다. 새 원문의 기본 골격은ds2 v2; project 이름 { active 이름; system 이름 { flow 이름 { work 이름 { duration 2000ms; } } } }이며 조건식은when (BOOL 식);·while (BOOL 식);·interlock (BOOL 식) "사유";에 ST 부분집합(= <> AND OR NOT MOD)으로 쓰고, 능동 제어기의 원점 복귀 절차는origin flow 이름 { ... }에 유한 DAG로 작성한다. 기존ds2 v1;파일의 뜻은 명시적 이전(dsdx.project.migrate) 없이 바꾸지 않는다.sys,F =,D =,P =,period =(sys/F/P,sys/F/D/P)를 이 언어의 문법이라고 생성하지 않는다. 봉인된 SDF·IR은 직접 고치지 않는다. MCP 요청 인자와 3D 표시 배치 JSON은 이 금지 대상과 구별한다.3. 관계는 읽은 규격대로 사용한다.
>는 시작,|>는 재준비,=>는 시작과 인계에 따른 선행 재준비,=|>는A => B; A |> B;의 매크로,<|>는 논리적 상호배제다. 외부 명령 1회당 1사이클 후 복귀하는 직렬 체인은 2-Work일 때A =|> B;, 3개 이상일 때A => B =|> C;를 사용하며, 반복 호출되는 Passive 장치는Lock <|> Unlock;또는Weld =|> Rearm; work Rearm;으로 재준비 경로를 명시한다.=>를 계층 진입,=|>를 비상정지 명령이라고 설명하지 않는다. 합류의 AND/OR·토큰·호출 의미는 공식 예제와 독립 기대값으로 확인한다.4. 생성·수정한 전체 원문을 실제
dsdx.compile에 보내고 그 원문의 해시와 응답을 대조한다(ds2 v2;에서 타입 있는input단독 사용 불가, 비-virtualWork미소비sensingDS2-W002경고, 부분 미선언token필드 Kleene 3치 논리DS2-I002확인). 실행을 주장하려면 실제dsdx.verify.run(기본verbosity:"summary"응답의traceSummary.workGoingEntries/workFinishEntries및CALL-TOKEN-BOUNDARY-1토큰 경계로 전체 스캔 회차 즉시 확인 가능, 미지원 Call·개루프 경로는GUARD-E422_UNSUPPORTED_OR_UNMEASURED/HOST-E422_CALL_EXECUTION_UNSUPPORTED로 거절)과 입력 시나리오의 기대 결과를 확인한다. 검증 후 원문이 바뀌면 다시 검증한다. 도구 호출이 불가능하면UNVERIFIED_DRAFT, 미실행은NOT_RUN, 근거 부족은INCONCLUSIVE로 표시한다. 임의로 성공 영수증을 작성하지 않는다.- PLC·산출물 내보내기 시에는
dsdx.artifact.export응답의preflightAdvisories(PREFLIGHT-W001..W005)와bundleStatus(CAPABILITY_UNSUPPORTED)를 별도로 확인한다.5. 3D는 기존 라이브러리를 먼저 검색한다. 공개 3D 라이브러리(
/ui/library/1,345종 ·.ds2연결1,258종 · DSL 프리뷰927종 [검증 궤적136+ 검토 대상756+ 정적 참조35] ·HUD_DRAFT_ONLY418종 · IDTA AASX Package Explorer UI ·/ui/library/line-workbench.html)는dsdx.library.search·dsdx.library.get·dsdx.library.download로 전체 개수(modelCount)와 최상위package_id/source_sha256/delivery_sha256해시 핀을 즉시 확인하고, 장면 배치 엔진 카탈로그는dsdx.scene.catalog의search→resolve/manifest로 실제 에셋과 공급자·릴리스·package ID·해시·허용 파라미터를 확인한다. 장비명이나 추측한 파일 경로만으로 모델이 존재한다고 주장하지 않는다. 일치 모델이 없으면 후보와 차이를 제시하고, 박스나 글자를 실제 라이브러리 모델로 대신 표시하지 않는다. (/mcp-guide에는 실사 조립 셀 사진과 HMI MC 타임차트 예제도 수록되어 있음)6.
dsdx.scene.layout의get으로 대상 프로젝트·작업공간·revision을 확인한 뒤, 실제로 resolve한 모델을 배치하고 현재 계약에서 허용한 위치·회전·표시 크기 등을 수정한다. 제공되지 않은 형상 파라미터는 지어내지 않는다. 새 형상이 필요하면 해당 SDK·모델 소스를 실제로 확인하고 별도 파생 에셋을 만들며 원본 라이브러리·공유 릴리스는 보존한다.make(ctx)등 함수 시그니처도 해당 파일을 읽고 확인한 경우에만 사용한다.7. 실제 장면을 다시 조회하고 렌더 화면을 확인한다. 모델 로딩 오류·빈 geometry·패키지 불일치를 성공으로 표시하지 않는다.
asset_type_id(종류),instance_id(배치), 실제 제어asset_id/Work 연결을 구별한다. Work 연결, 파트 소유권·인계·조인트·입출력 검증 없이DISPLAY_PREVIEW를 물리 디지털 트윈이나 제어 검증 완료라고 부르지 않는다.8. 도구를 사용할 수 없는 웹 AI는 공식 GET 문서 또는
/ai-start의 전체 본문을 읽고 초안을 제공한다. POST가 불가능하면 사용자가/play#source에서 전체DSLText를 명시적으로 컴파일하도록 안내한다. URL에 비공개 원문을 넣거나 GET으로 변경을 실행하지 않는다. 외부 AI의 권한·도구 제한을 서버가 없앴다고 주장하지 않는다.
현재 공개 서버에 키 없이 접근할 수 있다는 사실은 모든 외부 모델 호출·사설 공급자·물리 장치 접근 권한을 뜻하지 않습니다. 필요한 연결이나 권한이 없으면 해당 단계의 사유와 복구 방법을 알립니다.
8. 기존 샘플·라이브러리 수정 4단계
- 찾기:
examples/01_chain.ds2,examples/기본단어.ds2,examples/05_mutex.ds2,SPEC-04를docs_read또는/api/docs/read?document_id=…&raw=1로 실제로 읽고 현재 EBNF와 대조합니다. 읽지 못한 원문을 기억이나 추측으로 채우지 않습니다. - 고르기: 요청의 직렬·병렬·반복·공유 장치·합류 구조에 맞는 공식 패턴을 고릅니다. 3D 장비는
dsdx.scene.catalog에서 실제로 검색·resolve하며,dsdx.catalog.lookup의 현재 프로젝트 식별자 목록을 장비 라이브러리 검색과 혼동하지 않습니다. 유사 모델로 대체할 때는 원래 요청, 선택한 모델 ID, 차이점, 미검증 항목을 적습니다. - 수정하기: 기존 DSL의 선언과 모든 참조를 함께 고칩니다. 이름만 바꾸어 시간·조건·입출력·토큰·인계 요구를 만족했다고 주장하지 않습니다. 3D는 확인한 패키지의 허용 파라미터나 배치 속성으로만 수정하며, 임의 Three.js 박스나 장비명 텍스트를 라이브러리 로딩 성공 대신 쓰지 않습니다.
- 검증하기: 변경된 전체 DSL을 실제 컴파일하고, 원래 요구에서 정한 작업 수·순서·시간·인터록·인계 기대값을 실행 결과와 대조합니다.
lint와 컴파일은 정적 검사이며 실행 검증을 대신하지 않습니다. 3D도 실제 패키지·형상·배치 결과를 조회하고 화면을 캡처합니다.
공식 샘플을 가져온 뒤 그 내용을 sys/F/P나 sys/F/D/P 형태로 다시 적거나 =|>를 비상정지로 바꾸는 것은 샘플 보존이 아닙니다. 실제 project/system/flow/work 구조와 관계 의미를 그대로 따릅니다.