디지털 스레드 커넥터
디지털 스레드는 MES · ERP · PLM 같은 고객 시스템을 커넥터로 붙여 «무엇이 언제 일어났고 무엇과 이어졌나» 를 잇습니다. 이 쪽은 커넥터를 가족별로 정리합니다 — 가족마다 어떤 도구를 내야 하는지, 디지털 스레드가 그것을 어디에 쓰는지, 무엇을 조심해야 하는지. 화면에서 등록 · 적합성 · 켜기를 하는 법은 디지털 스레드 에 있습니다.
재릴리즈(2026-10-20) 부터 디지털 스레드는 아래 최소 판보다 낮은 커넥터를 쓰지 않습니다. 그 전의 판으로 붙인 커넥터는 올려야 합니다 → 판 올리기
한눈에 — 가족 열하나
| 가족 | 화면 이름 | 스펙 · 최소 판 | 필수 도구 | 행동 도구(🔒) | 신선도 상한 · 동기화 | 주로 쓰이는 곳 |
|---|---|---|---|---|---|---|
mes | MES | mes-mcp/0.7 | 7 | 셋 | 2시간 · 1시간 | 작업 준비도 · 오늘 작업 · 회복안 · 타임라인 — 기본 바탕 |
scm | SCM | mes-mcp/0.7 | 5 | 둘 | 24시간 · 12시간 | 자재 준비도 · PO 스레드 · 공급 회복 |
sched | 일정 계획(APS) | mes-mcp/0.7 | 2 | 하나 | 2시간 · 1시간 | 회복안의 기준 계획 |
erp | ERP | erp-mcp/0.4 | 2 | 없음 | 24시간 · 12시간 | 사람 · 자격, PO · 입고, 고객 주문, 제조 BOM |
plm | PLM | plm-mcp/0.2 | 3 | 없음 | 24시간 · 12시간 | 설계 변경 · 판 확인 · BOM 대조 |
qm | 품질 | qm-mcp/0.2 | 3 | 없음 | 24시간 · 12시간 | 품질 준비도 · 부적합 지연 |
cmms | 정비(CMMS) | cmms-mcp/0.2 | 2 | 없음 | 4시간 · 2시간 | 설비 준비도 · 정비 창 회복 |
tool | 공구 관리 | tool-mcp/0.2 | 2 + 기능 | 없음 | 24시간 · 12시간 | 공구 점검 · 공구 준비도 |
wms | 창고(WMS) | wms-mcp/0.2 | 3 | 없음 | 2시간 · 1시간 | 늦은 부품의 재고 |
lims | 시험실(LIMS) | lims-mcp/0.2 | 2 | 없음 | 12시간 · 6시간 | 로트 시험 성적 · 불합격 사건 |
ehs | 안전(EHS) | ehs-mcp/0.3 | 2 + 기능 | 없음 | 1시간 · 30분 | 작업 허가 준비도 · 격리 창 |
scm·sched는 MES 와 같은 스펙 줄기(mes-mcp)의 다른 가족입니다. 나머지는 가족마다 스펙이 따로 있습니다.- MES 가 바탕입니다. MES 가 없으면 작업 준비도 판정 전체가 «붙지 않음» 이고, 다른 가족만으로는 답이 나오지 않습니다.
- 행동 도구는
mes-mcp줄기(MES · SCM · 일정 계획)에만 있습니다. 나머지 여덟 가족은 읽기 전용입니다.
모든 커넥터에 공통인 규칙
거울에는 «키» 만 싣습니다
디지털 스레드는 커넥터에서 읽은 것을 공장 그래프 거울에 키와 연결만 싣습니다 — 「작업지시 WO-1 이 설비 M-3 에서 돈다」. 이름 · 수량 · 날짜 · 상태 같은 값은 저장하지 않고, 질문이 올 때 커넥터의 읽기 도구로 다시 읽습니다. 그래서 커넥터가 꺼지면 답에 값이 비고, 원천 시스템의 값이 바뀌면 다음 질문부터 바로 바뀐 값이 나옵니다.
도구 응답 규칙(규격 0.2)
| 규칙 | 값 |
|---|---|
| 응답 하나의 크기 | 16,000자 이하 |
| 쪽 크기 | limit 1 ~ 200(기본 50), 다음 쪽은 cursor |
| 기간 창 | 최대 31일. 예외 — 협력사 납기 실적 · 설비 정비 이력 · 교정 기록은 366일 |
| 오류 코드 | invalid_argument · not_found · unauthorized · rate_limited · unavailable · conflict |
| «모름» 표시 | 행의 unknown_fields, 응답의 partial(일부만 읽힘) · unreadable(읽지 못한 행). 모르는 값은 짐작하지 말고 null 로 냅니다 |
| 시각 | 시간대 오프셋이 있는 ISO 8601. 오프셋 없는 시각은 «모름» 으로 읽습니다 |
- 조건 없이 «전부 다오» 를 부르면
invalid_argument로 거절해야 합니다 — 적합성 시험이 봅니다. - 모르는 설비 ID 로 물으면 빈 목록이 아니라
not_found여야 합니다.
동기화와 신선도
- 디지털 스레드가 커넥터마다 가족 신선도 상한의 절반 간격으로 동기화합니다(최소 5분, 위 표).
DT_CONNECTOR_SYNC_INTERVAL_S를 주면 모든 커넥터가 그 간격입니다. 기동하고 2분 뒤에 첫 동기화가 돕니다. - 한 번에 지금 ±15일 창을 읽습니다. 이번 창에 나오지 않은 연결은 지우지 않고 닫습니다(연결 이력에 남습니다, 기본 180일). 실적 · 계보 · 검사 같은 기록 연결은 닫지 않습니다.
- 응답이 잘렸거나(
truncated) 일부만 읽혔으면(partial) 그 회차는 아무 연결도 닫지 않습니다. - 마지막 동기화가 신선도 상한보다 오래되면 회복안이 그 자료로 숫자를 내지 않고 «낡은 입력» 으로 밝힙니다. 상한은
DT_CONNECTOR_MAX_AGE로 가족마다 바꿀 수 있습니다. - 사건 도구가 있는 가족은 동기화 뒤 사건을 타임라인 참조로 싣습니다(본문 없이). 같은 사건을 다시 읽어도 두 벌이 되지 않고, 한 회차 5,000건까지입니다.
호출 한도
커넥터가 capabilities.limits.rate_limit_per_min 을 선언하면 디지털 스레드가 그 안에서만 부릅니다.
동기화 · 적합성 같은 무인 호출은 한도의 80% 까지만 쓰고(최대 10분 기다림), 채팅 같은 대화형 호출은 20초까지만 기다립니다.
커넥터가 Retry-After 를 주면 한 시간까지 지킵니다. 선언이 없으면 줄을 세우지 않습니다.
현장(사이트)을 MES 와 맞추십시오
커넥터는 현장 하나에 등록합니다. 현장이 그 공장 MES 와 다른 가족은 판정에서 빠지고 답에 site_mismatch:<가족> 이 남습니다(PLM 만 예외 — 설계 자료는 공장을 가리지 않습니다).
🔴 전사 ERP 를 본사 현장으로 등록하면 그 공장의 판정에서 ERP 가 빠집니다. 공장마다 그 공장 MES 와 같은 현장으로 등록하십시오.
원천 화면으로 바로 가기(딥 링크)
커넥터마다 링크 틀(links — base_url · label · allow_http · templates)을 두면 연결 · 타임라인 · 영향 범위 · 노드 상세 답의 객체에
open_url · open_label 이 붙고, 코파일럿 근거 패널에 「SAP 에서 열기」 같은 버튼이 생깁니다. 버튼 글은 label(비우면 커넥터 이름)입니다.
틀의 자리표는 {base} · {key} · {key.1} ~ {key.9} 셋뿐이고, 기본은 https 만(allow_http: true 면 http 도), 결과 호스트가 base_url 의 호스트와 같아야 합니다. 링크 틀은 바꿔도 적합성 · 켜짐 상태가 그대로입니다. 틀이 없으면 링크 칸 자체가 없습니다.
콘솔에서 넣는 법(연동 지도 › 커넥터 옆 창 › 외부 링크)은 디지털 스레드 — 외부 링크에 있습니다.
노드 상세 — 누를 때마다 부르는 읽기 도구
코파일럿 근거 패널에서 노드를 누르면(원 시스템의 지금 값) 디지털 스레드가 그 종류의 정본 가족 커넥터에서 아래 도구를 한 번 부릅니다. 값은 거울에도 서비스에도 저장하지 않고, 종류마다 정해 둔 칸만 옮깁니다(사람 이름 · 사번 · 연락처는 옮기지 않습니다). 한 번에 15초를 넘으면 «원 시스템 응답 없음» 입니다.
| 종류 | 가족 | 부르는 도구 |
|---|---|---|
| PO 줄 | ERP | erp_list_purchase_orders |
| 고객 주문 줄 | ERP | erp_list_sales_orders |
| 작업지시 · 공정 | MES | mes_get_work_order(공정은 부모 작업지시로) |
| 품번 | PLM | plm_get_bom |
| 협력사 | SCM | scm_get_supplier_delivery_performance(최근 90일) |
- 검사 · 부적합(QM)과 정비 작업지시(CMMS)는 규격에 한 건 읽기가 없어 «모름» 입니다 — 목록 도구는 기간 창만 받고 번호로 거르지 못하기 때문입니다.
- 커넥터 고르는 순서는 링크와 같습니다 — 켜지고 판이 맞는 정본 가족 커넥터 중 노드와 같은 현장(PLM 은 현장 대조 면제) → 대표 → 먼저 등록된 것.
판 올리기 — 최소 판보다 낮으면 쓰이지 않습니다
- 위 표의 최소 판보다 낮은 판을 선언한 커넥터는 동기화가 거절되고(409
connector_outdated) 판정 · 회복안에서 «붙지 않음» 이 됩니다. 답의 «빠진 것» 에connector_outdated:<가족>이 오르고, 등록부에spec_status: outdated와 올릴 판(upgrade_to)이 보입니다. - 커넥터를 새 판으로 올린 뒤에는 도구 발견 → 적합성 시험 → 켜기 → 동기화를 다시 밟습니다. 판이 바뀌면 도구 발견에서 커넥터가 꺼지고 적합성 결과가 지워지기 때문입니다.
- 커넥터가 여럿이면
bin/reregister-connectors.sh가 이 걸음을 커넥터마다 대신 밟습니다(MES 먼저, 그다음 SCM · 일정 계획 · ERP).--dry-run으로 먼저 보십시오.
적합성 시험을 밖에서 돌리기
커넥터를 만드는 쪽은 디지털 스레드 없이도 같은 시험을 돌릴 수 있습니다.
python -m app.connectors.conformance_cli <커넥터 MCP 주소> --family <가족>
한 번 시험은 15분 안에 끝나야 합니다(호출 한도 때문에 기다린 시간은 빼고 셉니다). 일시적인 끊김은 기록을 바꾸지 않고, 확정된 실패만 기록하고 커넥터를 끕니다.
MES — 작업지시 · 공정 · 실적
스펙 mes-mcp 0.7 · 가족 mes · 신선도 상한 2시간(동기화 1시간마다) · 디지털 스레드의 바탕
| 도구 | 필수 | 하는 일 | 주요 입력 |
|---|---|---|---|
mes_capabilities | ✅ | 판 · 사이트 · 한도 선언 | — |
mes_list_equipment | ✅ | MES 설비 ↔ 플랫폼 자산(asset_id) 대응표, 설비 계층 | asset_id · equipment_id |
mes_list_work_orders | ✅ | 설비별 · 기간별 작업지시 — 상태 · 품목 · 수량 · 계획/실제 시각 · 납기 · 마일스톤 · 수주 프로젝트(0.4) · 고객 주문 줄(0.7) | asset_id 또는 from · to, status, due_before |
mes_get_work_order | ✅ | 작업지시 하나의 공정과 BOM 줄 | work_order_id |
mes_list_production_results | ✅ | 생산 실적 — 양품 · 불량 · 폐기, 로트 · 일련번호 | from · to |
mes_list_downtime_events | ✅ | 비가동과 사유 | from · to |
mes_events | ✅ | 사건 봉투 — 타임라인에 실립니다 | from · to, types |
mes_get_genealogy | 선택 | 로트 · 일련번호 계보(앞뒤 3단까지) | direction |
mes_get_precedence | 선택 | 공정 선후행 그래프와 여유 | direction, depth 1~5 |
mes_list_maintenance_history · mes_list_nonconformances · mes_list_personnel | 선택 | 정비 이력 · 부적합 · 사람과 자격 — CMMS · QM · ERP 가 없을 때의 대체 원천 | 기간 |
mes_get_operation_requirements | 선택 | 공정마다 쓸 수 있는 설비 · 필요한 자격 · 셋업 묶음 | work_order_id |
mes_list_calendars · mes_list_maintenance_windows · mes_get_power_limit | 선택 | 설비 · 사람 달력(셋업 전환 포함), 계획 정비 창, 현장 동시 전력 상한 — 회복안의 자원 제약 | 기간 |
mes_get_mbom | 선택 | 제조 BOM — MES/MPM 이 정본일 때(0.6) | material_id |
🔒 행동 도구 — 사람이 코파일럿 제안 카드에서 승인해야만 불립니다. 원천 시스템에 «초안 · 요청» 을 만들 뿐이고, 확정은 그 시스템 안에서 사람이 합니다.
| 도구 | 만드는 것 |
|---|---|
mes_create_work_order_draft | 작업지시 초안(품목 · 수량 · 설비 · 시작 · 납기) |
mes_create_hold_request | 작업지시 · 로트 · 일련번호의 보류 / 해제 요청 |
mes_create_maintenance_request | 정비 요청(설비 · 우선순위 · 고장 코드 · 근거 링크) |
- 거울에 싣는 것 — 설비 → 플랫폼 설비 · 상위 설비, 작업지시 → 설비 · 마일스톤 · 프로젝트 · 고객 주문 줄, 공정 → 작업지시 · 설비 · 필요 자격, BOM 줄 → 품번, 선후행, 실적 로트 → 설비 · 작업지시, 계보, 제조 BOM. 수량 · 시각 · 달력 · 정비 창 · 전력 · 정지 사유는 물을 때 읽습니다.
어디에 쓰이나
| 기능 | 쓰는 방식 |
|---|---|
| 작업 준비도 | 작업지시 · 공정이 판정의 뼈대입니다. 없으면 판정 전체가 «붙지 않음». 공정 요구가 없으면 인원 항목이 «모름» |
오늘 작업(thread_today_work) | 오늘 계획된 공정과 설비 상태 |
회복안(thread_explain_recovery) | 작업지시 · 선후행 · 자원(달력 · 정비 창 · 전력) · 제조 BOM |
| 타임라인 · 영향 범위 | mes_events 와 계보 |
설비 부모 사슬에 고리가 있으면 떨어집니다. 작업지시에 wbs_parent_id 를 내면 project 도 내야 합니다. 필수 읽기 도구는 p95 2초 미만이어야 합니다.
SCM — 구매 · 입고 · 협력사
스펙 mes-mcp 0.7 · 가족 scm · 신선도 상한 24시간(동기화 12시간마다)
| 도구 | 필수 | 하는 일 | 주요 입력 |
|---|---|---|---|
scm_capabilities | ✅ | 판 · 사이트 · 한도 선언 | — |
scm_list_supply_lines | ✅ | 미결 구매 · 공급 라인 — 주문 · 입고 · 미결 수량, 요청 · 약속 · 확정일, 걸린 작업지시 · 고객 주문 | 품번 · 작업지시 · 협력사 중 하나 |
scm_list_inbound_shipments | ✅ | 출하 통지(ASN) — 도착 예정 · 운송 상태 | from · to |
scm_list_goods_receipts | ✅ | 입고와 검사 상태 | from · to |
scm_get_work_order_shortage | ✅ | 작업지시 하나의 결품 — 품번마다 필요 · 가용 · 입고 예정 · 부족, 다음 도착일 | work_order_id |
scm_events | 선택 | 사건 봉투 | from · to |
scm_get_supplier_delivery_performance | 선택 | 협력사 납기 준수율 · 평균 / p90 지연(최대 366일) | supplier_id |
scm_list_alternates | 선택 | 대체 부품 · 대체 협력사 | material_id |
scm_list_incoming_inspections · scm_list_supplier_nonconformances | 선택 | 수입 검사 결과 · 협력사 부품 부적합 | 기간 |
scm_list_supplier_capacity | 선택 | 협력사 공급 능력(운송 일수 · 기간별 능력) | 협력사 또는 품번 |
🔒 행동 도구
| 도구 | 만드는 것 |
|---|---|
scm_create_expedite_request_draft | 납기 당김 요청 초안(PO 줄 · 필요일) — 구매 담당이 원천에서 보냅니다 |
scm_create_supplier_inquiry_draft | 협력사 문의 초안(납기 · 품질, 1,000자까지) |
- 거울에 싣는 것 — PO 줄 → 협력사 · 품번 · 걸린 작업지시 · 고객 주문 줄, 입고 로트 → 협력사. 공급 라인은 출하 · 입고에 나온 협력사로 좁혀 읽습니다(SCM 스펙이 대량 조회를 막으므로).
어디에 쓰이나 — 자재 준비도(결품), PO 스레드, 회복안(결품 · 출하 · 공급 능력 — 공급 능력이 없으면 공급 쪽은 «영향만» 답합니다), 오늘 작업의 PO 칸.
일정 계획(APS) — 발행된 계획
스펙 mes-mcp 0.7 · 가족 sched · 신선도 상한 2시간(동기화 1시간마다)
| 도구 | 필수 | 하는 일 | 주요 입력 |
|---|---|---|---|
sched_capabilities | ✅ | 판 · 사이트 선언 | — |
sched_events | ✅ | 마일스톤 · 계획 날짜 변경 사건 | from · to |
sched_list_planned_operations | 선택 | 발행된 계획의 공정 일정 — 계획 판 · 설비 · 계획 시각 · 셋업 · 동결 · 순서 | from · to |
sched_get_resource_calendars | 선택 | 설비별 근무조와 계획 정지 | from · to |
sched_list_scenarios | 선택 | 시나리오(what-if 계획) 목록과 KPI | status |
🔒 행동 도구 — sched_create_scenario_draft: 회복안의 공정 이동(최대 200개)을 APS 에 시나리오 초안으로 만듭니다. 계획을 발행하지 않습니다 — 평가 · 발행은 APS 안에서 사람이 합니다.
회복안의 기준 계획으로 쓰입니다. 어제부터 앞으로 15일의 발행 계획을 읽어, 선후행의 계획 시각을 APS 의 것으로 덮습니다. 끝났거나 진행 중인 공정은 덮지 않습니다(실적이 계획을 이깁니다). 동결 공정은 그 시각에 고정하되, 선행이 늦어 그 시각에 시작할 수 없으면 고정하지 않고 «가정» 에 적습니다. APS 가 없으면 기준은 MES 의 작업 배정이고, 답의 «고려하지 않은 것» 에 «APS 계획 모름» 이 오릅니다.
ERP — 사람 · 구매 · 고객 주문 · 제조 BOM
스펙 erp-mcp 0.4 · 가족 erp · 신선도 상한 24시간(동기화 12시간마다) · 읽기 전용
| 도구 | 필수 | 하는 일 | 주요 입력 |
|---|---|---|---|
erp_capabilities | ✅ | 판 · 사이트 선언 | — |
erp_list_personnel | ✅ | 사람(가명 ID) · 자격 · 배정 | on_date, qualification_code |
erp_list_availability | 선택 | 사람의 가용 창 — 근무 · 휴가 · 잔업 | from · to |
erp_get_mbom | 선택 | 제조 BOM — ERP 가 정본일 때 | material_id |
erp_list_purchase_orders | 선택 | 자재 구매오더 줄(미결 기본) — 걸린 공정 · 고객 주문 줄 | 비우면 미결 줄 전부 |
erp_list_goods_receipts | 선택 | 입고 | from · to |
erp_list_sales_orders | 선택 | 고객 주문 줄 — 고객 · 고객 PO · 계약 납기 · 확정일 · 지체상금 · 이어진 프로젝트 · 마일스톤 · 작업지시 | 비우면 미결 줄 전부 |
- 사람은 가명 ID 로만 거울에 들어갑니다. 이름 · 자격 유효기한은 물을 때 읽습니다.
- 거울에 싣는 것 — 사람 → 자격 · 배정된 작업지시 · 공정, PO 줄 → 협력사 · 품번 · 작업지시 · 고객 주문 줄, 고객 주문 줄 → 고객, 프로젝트 · 마일스톤 · 작업지시 → 고객 주문 줄, 제조 BOM. ERP 와 SCM 이 같은 PO 줄 번호를 말하면 거울에서 같은 줄입니다.
ERP 와 SCM 이 함께 있을 때 — 납기는 SCM 에 협력사 확정일이 있으면 SCM 것, 없으면 ERP 것을 씁니다. 상태 · 미결 수량은 ERP 가 정본이고, 걸린 작업지시는 두 쪽을 합칩니다. 값이 다르면 답의 «어긋남» 에 둘 다 싣습니다.
어디에 쓰이나
| 기능 | 쓰는 방식 |
|---|---|
| 작업 준비도 — 인원 · 자재 | 인원은 ERP 를 먼저(없으면 MES). SCM 이 없는 고객도 ERP 구매오더의 미결 · 걸린 줄로 자재를 판정합니다 |
| 수주 맥락 | 공정마다 이행하는 고객 주문과 여유일 |
| 회복안 | 사람 자원 · PO · 고객 주문 여유일 |
| BOM 대조 | ERP 제조 BOM 을 먼저 봅니다(없으면 MES) |
고객 주문 줄이 프로젝트 · 마일스톤 · 작업지시 키를 하나도 내지 않는 것은 실패가 아니라 정보입니다(공장 일과 이어지지 않을 뿐). 주문 줄 번호가 겹치면 실패입니다.
PLM — 설계 변경과 BOM
스펙 plm-mcp 0.2 · 가족 plm · 신선도 상한 24시간(동기화 12시간마다) · 모두 읽기 전용
| 도구 | 필수 | 하는 일 | 주요 입력 |
|---|---|---|---|
plm_capabilities | ✅ | 판 · 사이트 · 기능 선언 | — |
plm_list_change_orders | ✅ | 설계 변경 지시(ECO · ECN) — 상태 · 바뀌는 품번과 판 · 재고 처리 · 효력 · 새 판을 쓸 수 있는 시각 | from · to(바뀐 시각 기준, 필수), material_id, status[] |
plm_get_bom | ✅ | 품번 한 판의 설계 BOM — 자품번(lines)과 그 품번이 들어가는 곳(where_used) | material_id(필수), revision(비우면 지금 released 판). 0.2 부터 쪽 나눔(limit 최대 200) |
plm_list_documents | 선택 | 품번에 묶인 문서 · 도면 메타데이터(이름 · 종류 · 판 · 상태 · 여는 링크). 파일 내용은 내지 않습니다 | material_id(필수), revision |
- 변경 지시 상태는
draft·in_review·approved·released·design_released(0.2) ·implemented·cancelled, 재고 처리는pending·use_as_is·rework·scrap·none, 효력은immediate·date·unit·serial입니다. - 거울에 싣는 것 — 변경 지시 · 품번 · 문서의 키와 연결(지시 → 품번, 자품번 → 모품번, 문서 → 품번)만. BOM 은 바뀌는 품번에서 위로 4단까지 걷습니다. 상태 · 날짜 · 문서 이름 · 링크는 싣지 않고 물을 때 읽습니다.
- 타임라인 사건 — 변경 지시가 바뀜 · 릴리즈됨 · 상태가 바뀜(0.2). 영향받는 품번에 붙습니다.
어디에 쓰이나
| 기능 | 쓰는 방식 |
|---|---|
회복안(thread_explain_recovery) | 지난 30일 ~ 내일의 변경 지시 가운데 승인 · 릴리즈된 것만 제약이 됩니다. 재고 처리가 use_as_is 면 막지 않고, rework · scrap · none 이면 «새 판을 쓸 수 있는 시각» 까지 그 부품을 막습니다. design_released 는 보이기만 하고 막지 않습니다 |
| 작업 준비도 — 도면 항목 | 변경 지시를 못 읽으면 이 항목은 «모름», BOM 이 없으면 판정 범위가 좁아집니다 |
판 확인(thread_part_revision_status) | 지금 released 판과 열린 변경(93일)을 보고 current · outdated · change_open · unknown 으로 답합니다 |
| BOM 대조 · 영향 범위 | 설계 BOM 을 제조 BOM · 실적과 견줍니다 → 위 제조 BOM |
truncated: true 인 BOM 응답에 next_cursor 를 함께 내면 떨어집니다. 문서의 open_url 은 http(s) 링크여야 합니다(data: 금지).
QM — 검사와 부적합
스펙 qm-mcp 0.2 · 가족 qm · 신선도 상한 24시간(동기화 12시간마다) · 모두 읽기 전용
| 도구 | 필수 | 하는 일 | 주요 입력 |
|---|---|---|---|
qm_capabilities | ✅ | 판 · 사이트 선언 | — |
qm_list_inspections | ✅ | 검사 로트 — 수입 · 공정 · 최종 검사, 결과(passed · failed · conditional · pending), 이어진 부적합 번호 | from · to(필수), material_id · lot_id · work_order_id |
qm_list_nonconformances | ✅ | 부적합(NCR) — 결함 · 수량 · 처리(재작업 · 폐기 · 반품 …) · 재작업 계획 · 대체품 예정 시각 | from · to(발견 시각, 필수), 품번 · 로트 · 작업지시 · 협력사 · status[] |
- 거울에 싣는 것 — NCR · 검사의 키와 연결: NCR → 품번 · 로트 · 일련번호, NCR → 막는 작업지시 · 공정, 로트 → 검사, 로트 → 협력사.
- 타임라인 사건 — 부적합 발생 · 재작업 끝남, 검사 합격 · 불합격 · 조건부(
pending은 사건이 아닙니다).
어디에 쓰이나
| 기능 | 쓰는 방식 |
|---|---|
| 회복안 | 처리가 재작업 · 수리면 재작업 계획의 끝까지, 폐기 · 반품이면 대체품 예정 시각까지 막습니다. 시각이 없으면 숫자를 내지 않고 «모름» 으로 남깁니다 |
| 작업 준비도 — 품질 항목 | QM 을 먼저 보고, 없으면 MES 의 부적합(mes_list_nonconformances)을 봅니다 |
공구 점검(thread_check_tooling) | 부적합의 원인 후보를 찾을 때 함께 읽습니다 |
CMMS — 정비
스펙 cmms-mcp 0.2 · 가족 cmms · 신선도 상한 4시간(동기화 2시간마다) · 모두 읽기 전용
| 도구 | 필수 | 하는 일 | 주요 입력 |
|---|---|---|---|
cmms_capabilities | ✅ | 판 · 사이트 선언 | — |
cmms_list_work_orders | ✅ | 정비 작업지시 — 종류(예방 · 고장 수리 · 예지 · 점검 · 교정) · 상태 7단계 · 계획/실제 시각 · 설비 정지 여부 · 쓰는 예비품 · 기다리는 생산 작업지시 | from · to(필수), equipment_id · asset_id · type[] · status[] · open_only |
cmms_list_pm_schedules | 선택 | 예방정비가 설비를 세우는 창 — 길이 · 가장 이른 시작 · 가장 늦은 끝 · 옮길 수 있는지(movable) | from · to(필수), 설비 |
cmms_get_asset_history | 선택 | 설비 한 대의 정비 이력 요약(건수 · 고장 수 · MTBF · MTTR · 정지 시간) | from · to(최대 366일), 설비 |
- 거울에 싣는 것 — 정비 작업지시 번호와 연결: 정비 → 설비(플랫폼 자산 ID 가 있으면 플랫폼 설비에 바로), 정비 → 예비품, 정비 → 기다리는 생산 작업지시. 창 안의 작업지시에 더해, 창 밖에서 시작해 아직 열린 것도 읽습니다.
- 타임라인 사건 — 정비 요청 · 시작 · 끝, 예방정비 계획. 시각이 하나도 없는 작업지시는 사건 없이 «시각 없음» 으로 남습니다.
어디에 쓰이나
| 기능 | 쓰는 방식 |
|---|---|
| 회복안 | 어제부터 앞으로 15일의 예방정비 창과 열린 작업지시를 읽습니다. 끝나지 않은 고장 수리는 예상 끝까지 설비를 막고, 옮길 수 없는 예방정비도 막습니다. 옮길 수 있는 예방정비는 최적화가 일정 안에서 옮깁니다. CMMS 가 없으면 답의 «고려하지 않은 것» 에 정비 일정이 오릅니다 |
| 작업 준비도 — 설비 항목 | 예방정비 창과 작업지시가 둘 다 없으면 «모름» |
| 안전(EHS) 대조 | 정비 작업지시와 작업 허가 · 격리를 견줍니다 |
| 이상 사례 라벨 | 끝난 고장 수리 작업지시로 이상 사례에 라벨을 붙입니다(DT_WO_LABELS_ENABLED) |
- 같은 정비 창이 MES 에도 있으면 CMMS 쪽이 이깁니다.
TOOL — 공구 · 지그 · 계측기
스펙 tool-mcp 0.2 · 가족 tool · 신선도 상한 24시간(동기화 12시간마다) · 모두 읽기 전용
공구 관리 시스템은 하는 일이 제각각이라, 커넥터가 기능을 선언하고 그 기능의 도구만 냅니다. 교정만 하는 시스템은 calibration 하나만 선언해도 됩니다.
| 기능 | 내는 도구 | 대장에서 채우는 칸 |
|---|---|---|
inventory | (대장만) | 수량 |
issue_return | tool_list_issues — 불출 · 반납(누가 · 어느 작업지시 · 공정 · 검사 · 로트에) | — |
calibration | tool_list_calibrations — 교정 기록(교정 전 · 후 판정, 최대 오차, 다음 기한). 최대 366일 | 교정 |
tool_life | tool_list_life_events — 재연마 · 교체 · 수명 끝 · 수명 경고 | 수명 |
presetting | tool_list_requirements — 작업지시 · 공정에 필요한 공구 목록 | 프리셋 |
- 늘 내는 도구는
tool_capabilities와tool_list_tools(공구 · 지그 · 계측기 대장 — 상태available·issued·in_calibration·out_of_tolerance·quarantined·worn_out·retired)입니다. 사건 도구tool_events는 기능과 상관없는 선택입니다. - 🔴 선언한 기능의 도구는 다 내야 하고, 선언하지 않은 기능의 도구는 내면 안 되며, 그 대장 칸은 비워야 합니다 — 적합성 시험이 이것을 봅니다.
- 거울에 싣는 것 — 공구 키와 연결: 공구 → 놓인 설비, 작업지시 · 공정 · 검사 · 로트 · 일련번호 → 실제로 쓴 공구. 수명 · 교정 · 수량 값은 싣지 않습니다.
- 타임라인 사건 — 불출 · 반납 · 교정 합격/불합격 · 수명 끝 · 교체.
tool_events가 없으면 교정 기록에서 교정 사건만 만듭니다.
어디에 쓰이나
| 기능 | 쓰는 방식 |
|---|---|
공구 점검(thread_check_tooling) | 세 가지를 답합니다 — 의심 측정(교정 기한이 지난 계측기로 쟀거나, 쓴 뒤 교정에서 불합격), 실제로 쓴 공구, 부적합의 원인 후보(수명 · 불출 · QM 부적합). 조회 기간 1~31일(기본 30일), 교정 기록은 1년 전까지 봅니다 |
| 작업 준비도 — 공구 항목 | 필요 공구 목록과 대장 중 하나라도 없으면 «모름» |
WMS — 창고 재고와 이동
스펙 wms-mcp 0.2 · 가족 wms · 신선도 상한 2시간(동기화 1시간마다) · 읽기 전용
| 도구 | 필수 | 하는 일 | 주요 입력 |
|---|---|---|---|
wms_capabilities | ✅ | 판 · 사이트 선언 | — |
wms_list_stock | ✅ | 재고 — 품번 · 위치 · 로트마다 보유 · 예약 · 가용, 재고 상태(시점 as_of 기준) | material_id · location_id(조건 없는 전부는 거절) |
wms_list_movements | ✅ | 재고 이동 — 입고 · 출고 · 이전 · 조정 · 반품 | from · to(필수), 품번 · 작업지시 |
- 거울에 싣지 않습니다. 재고는 시간마다 바뀌는 값이라 물을 때 읽습니다.
- 타임라인 사건 — 이동마다 입고 · 출고 · 이전 · 조정 · 반품 사건.
- 어디에 쓰이나 — 회복안이 늦은 부품마다 창고 재고(가용 · 보유 · 예약 · 보류 · 검사 중)를 함께 보여 줍니다. 일부만 읽혔으면 행이 없는 품번도 0 이 아니라 «모름» 입니다. WMS 가 없으면 답의 «고려하지 않은 것» 에 재고가 오릅니다.
LIMS — 시료와 시험 결과
스펙 lims-mcp 0.2 · 가족 lims · 신선도 상한 12시간(동기화 6시간마다) · 읽기 전용
| 도구 | 필수 | 하는 일 | 주요 입력 |
|---|---|---|---|
lims_capabilities | ✅ | 판 · 사이트 선언 | — |
lims_list_samples | ✅ | 시료와 시험 결과 — 품번 · 로트 · 일련번호 · 협력사 · 작업지시 · 검사, 상태(registered · in_testing · completed · cancelled), 종합 판정 | from · to(채취 시각, 필수), 품번 · 로트 · 상태 |
- 거울에 싣는 것 — 시료 → 로트 · 일련번호(없으면 품번) · 작업지시 · 검사, 로트 → 협력사. 시험 값 · 규격 · 판정은 싣지 않습니다.
- 타임라인 사건 — 판정된 시료마다 합격 · 불합격. 판정 전 시료는 사건이 아닙니다.
- 어디에 쓰이나 — 로트에 시험 성적을 붙이고, 영향 범위를 시료에서부터 따라갑니다. LIMS 불합격을 QM 부적합으로 올리지는 않습니다 — 부적합은 QM 이 정본입니다.
EHS — 작업 허가 · 격리 · 안전
스펙 ehs-mcp 0.3 · 가족 ehs · 신선도 상한 1시간(동기화 30분마다 — 가족 가운데 가장 짧습니다) · 읽기 전용
늘 내는 도구는 ehs_capabilities 와 ehs_events(허가 승인 · 시작 · 중지 · 종료, 격리 설치 · 해제, 사고 보고, 점검 완료, 위험성평가 만료) 둘이고,
나머지는 공구 관리처럼 기능을 선언하고 그 도구를 냅니다.
| 기능 | 도구 | 하는 일 |
|---|---|---|
permits | ehs_list_permits | 작업 허가 — 종류 · 상태 · 설비 · 구역 · 작업지시 · 정비 작업지시 · 공정, 유효 기간, 격리가 필요한지 |
isolations | ehs_list_isolations | 격리(LOTO) — 격리 지점 · 허가 · 계획/설치/확인/해제 시각 |
incidents | ehs_list_incidents | 사고 참조 — 사고 · 아차사고 · 불안전 상태 · 환경 누출, 심각도 등급 |
inspections | ehs_list_inspections | 안전 점검 — 발견 수 · 열린 조치 |
risk_assessments | ehs_list_risk_assessments | 위험성평가 — 승인일 · 재검토 기한 |
training | ehs_list_training | 역할 자격(교육) — 가명 ID · 유효 기간 |
- 🔴 0.3 이 최소 판인 이유 — 0.3 부터 정비 작업지시를 따로 받습니다(
maintenance_order_ids).work_order_*는 MES 작업지시만 뜻합니다. 0.2 커넥터가 정비 번호를 작업지시 칸에 넣으면 거울에 없는 작업지시가 생겼기 때문에, 0.3 미만은 동기화하지 않습니다. - 🔴 개인정보를 받지 않습니다. 사고의 서술 · 부상 · 인적 사항 칸이 없고, 칸을 더 내면 적합성 시험에서 떨어집니다. 사람은 가명 ID 뿐입니다.
- 거울에 싣는 것 — 허가 → 설비 · 구역 · 작업지시 · 정비 작업지시 · 공정, 격리 → 설비 · 허가, 사고 → 설비 · 구역 · 작업지시 · 정비. 점검 · 위험성평가 · 자격은 물을 때 읽습니다.
어디에 쓰이나
| 기능 | 쓰는 방식 |
|---|---|
| 작업 준비도 — 허가 항목 | 허가가 없음 · 공정을 덮는 허가가 없음 · 필요한 격리가 없음을 사유로 냅니다 |
| 허가 덮임 점검 | 정해진 기간(기본 7일, 최대 31일)의 작업 · 정비에 허가 · 격리의 빈틈이 있는지, 위험성평가 재검토가 늦었는지 |
| 회복안 | 격리 기간을 그 설비를 못 쓰는 창으로 넣습니다. 승인 전 · 중지된 허가는 «참고» 로만 밝힙니다 |
- 역할 자격(
training)은 읽지만 아직 판정에 쓰지 않습니다. 채팅 도구는 없습니다.
상용 제품 어댑터 — 사전 검증 단계
자주 쓰이는 상용 제품에 맞춘 어댑터 넷을 준비했습니다. 넷 다 모의 서버를 상대로 적합성 시험을 통과한 단계이고, 실제 제품에 붙여 검증하지는 않았습니다 — 도입 때 고객 환경에서 함께 검증합니다. 모두 읽기 전용입니다.
| 제품 | 가족 · 판 | 내는 도구 | 제품 쪽 인터페이스 | 인증 |
|---|---|---|---|---|
| SAP S/4HANA | ERP erp-mcp/0.4 · 정비 cmms-mcp/0.2(가족마다 따로 등록) | ERP: 사람 · 구매오더 · 입고 · 고객 주문(가용 창 · 제조 BOM 은 아직 없음). 정비: 넷 다 | OData V2 표준 API(구매오더 · 자재 문서 · 판매오더 · 정비오더 · 정비계획 · 설비 등) | OAuth2 client credentials 또는 basic |
| IBM Maximo(Manage · 7.6) | 정비 cmms-mcp/0.2 | 넷 다 | REST(OSLC JSON) — 작업지시 · 예방정비 · 자산 | API 키(MAS) · maxauth(7.6) · basic |
| Siemens Teamcenter | PLM plm-mcp/0.2 | 넷 다(문서 포함) | SOA JSON — 저장된 질의 · BOM 창 · where-used | 세션 로그인(사용자 · 비밀번호) |
| Dassault 3DEXPERIENCE | PLM plm-mcp/0.2 | 넷 다(문서 포함) | 3DPassport 로그인 → 3DSpace 변경 · 엔지니어링 · 문서 API | 사용자 · 비밀번호 + 보안 문맥 |
- 어댑터는 디지털 스레드와 별개의 컨테이너로 고객 쪽에 띄우고, 디지털 스레드에는 보통 커넥터처럼 끝점 · 토큰으로 등록합니다. 토큰이 비어 있으면 어댑터가 기동을 거부합니다.
- 원천 시스템 주소는 https 만 받습니다. 비밀은 값 대신 파일(
…_FILE)로 줄 수 있습니다. - 어댑터마다 분당 호출 한도를 선언합니다(예: Teamcenter 분당 40, 3DEXPERIENCE 분당 25). 원천 시스템이 자격을 거절하면 5분에서 60분까지 쉬었다가 다시 시도합니다.
- MES · 품질 · 공구 · 창고 · 시험실 · 안전 가족의 상용 어댑터는 아직 없습니다. 그 가족은 위 스펙을 따르는 커넥터를 세워 붙입니다.
커넥터를 만드는 쪽에게
- 스펙 원문은 디지털 스레드 소스의
app/connectors/spec/<스펙>-<판>/에 도구마다 JSON 으로 있습니다. 새 판은 앞 판 위에 더한 것만 담습니다. - 내지 않는 기능의 도구는 목록에서 빼십시오. 빈 응답을 내는 도구는 «기능 있음, 자료 없음» 으로 읽힙니다.
- 모르는 값은
null과unknown_fields로 밝히십시오. 0 이나 빈 문자열로 채우면 «측정된 0» 으로 읽혀 판정이 틀립니다. - 읽기 도구에는
readOnlyHint: true를, 시간 창이 있는 도구에는 31일 상한을 지키십시오. - 사건 ID 는 다시 읽어도 같아야 합니다 — 타임라인이 그것으로 중복을 거릅니다.
관련 문서
- 디지털 스레드 — 등록 화면 · 바인딩 · 동기화 · 그래프 거울 · 채팅 도구
- MCP 도구 지도 — 채팅이 부르는
thread_도구 - 비밀번호 · API 키 변경 — 커넥터 자격증명을 암호화하는
PI_DT_SECRET_KEY