싸인딜 개발자

MCP 도구 참조

MCP 서버 주소는 https://mcp.signdeal.kr/mcp예요. 도구 12개, 별칭 14개가 열려 있어요. 이 표는 코드(app/src/mcp/tools.ts)에서 자동으로 만들었어요. *는 필수예요.

목차

도구

generate_contract_from_text · 계약 초안 생성(법률고지 동반)

자연어 요구사항을 한국어 계약서 초안(draft_markdown)으로 생성하고, 금액을 추출해 후속 단계상향 판단의 입력으로 넘긴다. 입력: contract_type(표준 7종 enum) + instruction(자유서술) + parties[](선택). 출력: { draft_markdown, slots, field_anchors[], review_payload(detected_amount_krw·amount_confidence·disclaimer·review_required·next), risk_warnings[] }. 다음 단계: create_draft 로 저장하거나 본문을 직접 수정하세요.

필요한 스코프: contract:draft · 분류: contract_authoring · readOnlyHint=false · destructiveHint=false · idempotentHint=false

입력

이름타입·제약설명
contract_type *string
enum: loan_iou | lease_residential | lease_commercial | sale_real_estate | service | p2p_used_goods | p2p_general | employment
계약유형(DB CHECK 표준 7종). 전자 불가 예외 유형은 create_draft 단계에서 거부됨.
instruction *string
minLength: 1 · maxLength: 50000
계약 요구사항 자유서술(예: "친구에게 500만원 빌려주고 6개월 뒤 상환, 이자 연 5%").
partiesarray<object>당사자 역할·이름 목록(선택, 예: 채권자/채무자). 본문의 역할 앵커 생성 힌트.
parties[].role *string
minLength: 1
역할명(예: 채권자).
parties[].name *string
minLength: 1
당사자 이름.
languagestring
enum: ko · default: "ko"
초안 언어(MVP: ko 고정).
type_keystring|null
default: null
카탈로그 양식 키(list_templates의 type_key, 예: residential_lease_jeonse_wolse). 지정 시 해당 표준 양식(spec) 기반으로 본문을 구성하고 특약을 주입한다.

출력

이름타입·제약설명
draft_markdownstring생성된 계약서 초안(Markdown).
field_anchorsarray탐지된 역할/필드 앵커.
review_payloadobjectdetected_amount_krw·amount_confidence·review_required 등.
risk_warningsarray리스크 경고 목록.

별칭

create_draft · 계약 초안 저장

계약 리소스를 draft 상태로 생성한다. amount_krw·contract_type 기준으로 required_auth_level 을 정책 평가(§4)하고, 전자 불가 예외 유형(유언·혼인신고·물권변동 등기 등)은 validation_error(type_not_allowed)로 거부한다. 출력: { contract_id, status:"draft", created_at, expires_at, edit_url, required_auth_level, auth_level_reason, next }. 표준(spec) 양식(template_id)은 get_template 의 필수 값을 var_values 로 모두 채워야 한다 — 비면 missing_required(빠진 key 목록 동봉). signers[] 를 함께 보내면 서명자 추가·서명필드 배치까지 이 호출 하나로 끝나고 바로 send_for_signature(dry_run)로 갈 수 있다(없으면 add_signer 로 추가).

필요한 스코프: contract:draft · 분류: contract_authoring · readOnlyHint=false · destructiveHint=false · idempotentHint=false

입력

이름타입·제약설명
title *string
minLength: 1 · maxLength: 200
계약 제목(예: "차용증(홍길동→김철수)").
body_markdownstring
minLength: 1 · maxLength: 50000
계약 본문(Markdown). ≤50,000자. spec 양식(template_id+var_values)으로 생성할 경우 생략 가능(서버가 권위 렌더).
contract_type *string
enum: loan_iou | lease_residential | lease_commercial | sale_real_estate | service | p2p_used_goods | p2p_general | employment
계약유형(표준 7종). 전자 불가 예외 유형이면 거부.
amount_krwinteger|null
minimum: 0 · default: null
계약 본질가액(원). 단계상향 임계(1천만원) 평가 입력. 미상이면 null.
expires_in_daysinteger
minimum: 1 · maximum: 30 · default: 7
서명 만료일(일). 1~30, 기본 7. 경과 시 expired 전이.
template_idstring|null
default: null
기반 템플릿 id(list_templates 결과). 시스템 spec·내 조직 spec(저장 본문)·내 조직 업로드 PDF 모두 지원. PDF 업로드 양식이면 signer(수신자)를 함께 보내면 초안+수신자까지 생성되고 바로 send_for_signature 로 발송. 자유서식이면 null.
signerobject업로드 PDF 양식(template_id=PDF) 발송 시 수신자. { name, phone, email? }. PDF 양식은 생성 시 수신자가 필요하다.
signer.namestring수신자 이름.
signer.phonestring수신자 휴대폰(본인확인용).
signer.emailstring수신자 이메일(선택).
signersarray<object>
maxItems: 10
서명자 일괄 추가(선택, ≤10, PDF 업로드 양식에는 사용 불가 — 그쪽은 signer). 초안 생성 직후 add_signer 와 서명필드 자동배치까지 한 번에 수행한다. role 은 get_template roles[].id(없으면 본문 역할명). { name, role, phone, auth_level?, order?, required_fields? }.
signers[].name *string
signers[].role *string
signers[].phone *string
signers[].auth_levelstring
enum: none | phone | id_card | bank
signers[].orderinteger
minimum: 1
signers[].required_fieldsarray<string>
field_valuesobjectPDF 업로드 양식(template_id=PDF) 데이터머지 값. key=양식 라벨 key(list_templates.fields[].key) 또는 한글 표시명, value=채울 텍스트. 예: {"대표자명":"홍길동","일사용료":"55,000","보증금":"300,000"}. 각 라벨 좌표에 값이 채워진 계약서가 생성된다. fillBy=recipient/system 필드 지정 시 검증 거부.
var_valuesobjectspec 양식의 변동 변수값(key=양식 변수 key, 예: deposit·lease_start_date·lessor_name). 서버가 양식에 채워 권위 렌더한다.
special_termsarray<object>특약사항 목록. 본문 특약 구역(특약사항)에 번호목록으로 주입되고 별도 저장된다(source 격리).
special_terms[].body *string
minLength: 1
특약 내용.
special_terms[].titlestring특약 제목(선택).
special_terms[].sourcestring
enum: user | ai | template_suggested · default: "user"
특약 출처(AI 작성=ai).

출력

이름타입·제약설명
contract_idstring
statusstringdraft|ready.
required_auth_levelstring
auth_level_reasonstring|null
expires_atstring

list_templates · 템플릿 조회

계약 템플릿(정부 표준양식 기반 디폴트 + 테넌트 커스텀)을 조회한다. category·query 모두 선택. 출력: { templates:[{ template_id, name, category, fields[], source }] }. 빈 결과는 에러가 아니며 next 힌트로 generate_contract_from_text 자유서식 경로를 안내한다. 표준(spec) 양식의 fields 는 비어 있다 — 채울 값 목록·역할은 get_template 으로 확인한다.

필요한 스코프: contract:read · 분류: templates · readOnlyHint=true · destructiveHint=false · idempotentHint=true

입력

이름타입·제약설명
categorystring
maxLength: 100
카테고리 필터(예: "loan"). 선택.
querystring
maxLength: 200
이름·내용 검색어(예: "차용증"). 선택.

출력

이름타입·제약설명
templatesarray{template_id,name,category,contract_type,is_system}.

별칭

get_template · 양식 값 목록 조회

양식 하나의 채울 값 목록·서명 역할을 조회한다(readOnly). create_draft 전에 반드시 호출해 필수 값을 모두 모은다 — 표준(spec) 양식은 필수 값이 비면 create_draft 가 missing_required 로 거부한다. 출력: { template_id, name, engine(spec|pdf|legacy), electronic_ok, values[{key,label,data_type,required,options?}], required_keys[], roles[{id,label}], next }. spec → create_draft.var_values, pdf → create_draft.field_values(fill_by=sender 만), legacy → generate_contract_from_text 로 본문 먼저. add_signer 의 role 은 roles[].id 를 그대로 쓴다.

필요한 스코프: contract:read · 분류: templates · readOnlyHint=true · destructiveHint=false · idempotentHint=true

입력

이름타입·제약설명
template_id *string
minLength: 1
list_templates 결과의 template_id.

출력

이름타입·제약설명
template_idstring
enginestringspec|pdf|legacy.
valuesarray{key,label,data_type,required,options?}.
required_keysarray
rolesarray{id,label} — add_signer.role 에 그대로.

별칭

add_signer · 서명자 추가(단계상향 평가)

계약에 서명자를 추가한다. 기본 휴대폰 번호인증(phone), 고액(≥1천만원)·유형 트리거 시 서버가 identity_provider 로 강제 상향(요청값 무시). phone 은 E.164 로 정규화 저장. 동일 phone 중복 추가·서명자 수 한계(2~10) 초과는 validation_error. required_fields 로 서명 시 수신자에게 받을 정보(name·phone 필수 + birthdate·address 옵션)를 계약별로 지정한다 — 명시되지 않았으면 사용자에게 "상대방에게 이름·연락처만 받을까요, 생년월일·주소까지 받을까요?"라고 먼저 확인한 뒤 호출하라. 주민등록번호 전체·신분증 이미지는 수집 불가. 출력: { signer_id, status:"added", auth_level_requested, auth_level_effective, auth_level_reason, required_fields }.

필요한 스코프: contract:draft · 분류: contract_authoring · readOnlyHint=false · destructiveHint=false · idempotentHint=false

입력

이름타입·제약설명
contract_id *string
minLength: 1
대상 계약 id(create_draft 결과).
signer *object추가할 서명자.
signer.name *string
minLength: 1
서명자 이름.
signer.role *string
minLength: 1
역할(예: 채무자). 본문 앵커와 매칭.
signer.phone *string
pattern: ^01[016789]-?\d{3,4}-?\d{4}$
한국 휴대폰 번호. 알림톡/SMS·번호인증용. E.164 정규화 저장.
signer.auth_levelstring
enum: phone | identity_provider | simple_cert · default: "phone"
요청 본인확인 레벨. 정책이 상향하면 무시되고 서버가 격상(다운레벨 금지).
signer.orderinteger
minimum: 1 · maximum: 10
서명 순서. 중복/누락 시 서버가 입력 순서로 정규화.
signer.required_fieldsarray<string>
maxItems: 4
서명 시 수신자에게 수집할 항목. name·phone 은 항상 포함(번호인증 필수). birthdate(생년월일)·address(주소)는 사용자가 원할 때만 추가. 미지정 = 이름·연락처만.

출력

이름타입·제약설명
signer_idstring
statusstring
auth_level_effectivestring
required_fieldsarray

별칭

set_signature_fields_auto · 서명필드 자동배치

create_draft 때 본문의 역할 앵커("(채권자) 서명:", 양식의 {{sig:role}} 등)로 계산해 둔 서명필드를 현재 버전에 확정 저장한다(멱등, 좌표 아님). 출력: { contract_id, version_id, field_count, fields[{field, anchor, role}], next }. fields[].role 이 add_signer 의 role 과 같아야 서명칸이 그 사람에게 붙는다. 서명칸이 없는 서명자가 있으면 send_for_signature 가 missing_signature_field 로 거부한다. 위치를 직접 지정·이동하는 기능은 아직 없다(본문의 역할 줄 위치가 곧 서명칸 위치). strategy·field_types 는 예약 입력(현재 무시).

필요한 스코프: contract:draft · 분류: contract_authoring · readOnlyHint=false · destructiveHint=false · idempotentHint=true

입력

이름타입·제약설명
contract_id *string
minLength: 1
대상 계약 id.
strategystring
enum: auto · default: "auto"
예약 입력(현재 무시). auto 고정.
assign_by_roleboolean
default: true
예약 입력(현재 무시). 필드는 항상 역할로 바인딩된다.
field_typesarray<string>예약 입력(현재 무시).

출력

이름타입·제약설명
contract_idstring
field_countinteger
fieldsarray

별칭

send_for_signature · 서명 요청 발송

계약서를 카카오 알림톡(폴백 SMS)으로 발송. channel 로 카톡/SMS 를 선택할 수 있다(기본 auto = 알림톡 우선). dry_run=true(기본)면 미리보기 카드 + 과금 안내(가입 시 무료 10건(1회성)/충전 잔여 → 0원, 모두 소진 시 충전 필요·건당 과금 없음) + confirmation_token(5분·1회·스냅샷 바인딩)만 반환. 실발송은 dry_run=false + 유효한 confirmation_token 필수(누락/만료/불일치 시 서버 무조건 거부, confirmation_required). 무료 10건(1회성)과 충전 잔여를 모두 소진하면 충전이 필요하다(건당 과금 없음). idempotency_key 로 중복 발송·중복 과금 차단. 단계상향 미충족·미배치 서명자 존재 시 발송 차단. 실발송 응답 status 는 "queued"(비동기 발송; 실제 채널은 check_status 로 확인).

필요한 스코프: contract:send · 분류: delivery · readOnlyHint=false · destructiveHint=true · idempotentHint=true

입력

이름타입·제약설명
contract_id *string
minLength: 1
대상 계약 id.
channelstring
enum: auto | kakao_alimtalk | sms | lms · default: "auto"
발송 채널(SSOT MessageChannel + auto). auto = 알림톡 우선 → 실패 시 SMS/LMS 폴백.
messagestring
maxLength: 1000
서명 요청 메시지(정보성). ≤1,000자. 선택.
dry_runboolean
default: true
기본 true(미리보기). false = 실발송(confirmation_token 필수).
confirmation_tokenstringdry_run 미리보기에서 받은 1회용 토큰. dry_run=false 일 때 필수.
idempotency_keystring실발송 멱등키(중복 발송 방지용, 필수). 이미 발송(sent)된 계약의 재발송은 상태전이로 거부된다 — 최초 결과 재반환(replay)은 미지원.

출력

이름타입·제약설명
would_sendbooleandry_run 미리보기 여부.
statusstring실발송 시 queued|sent.
confirmation_tokenstringdry_run 시 발급되는 1회용 토큰.
billingobjectfree_quota·free_remaining·amount_krw.
channel_usedstring|null

별칭

send_document · PDF 서명 요청 발송

내가 가진 PDF 그대로에 서명·도장·입력 칸(쪽 + 0~1 비율 좌표, 좌상단 기준)을 얹어 서명 요청을 보낸다(REST POST /contracts:send_document 의 mode "sign_pdf" 와 같은 엔진). 발송 전 확인: dry_run=true(기본)면 칸 검증 결과(checks)·layout_hash·confirmation_token(5분·1회·칸/문서/수신자 바인딩)만 반환하고 계약은 만들지 않는다. 실발송은 dry_run=false + confirmation_token + idempotency_key 필수 — 미리보기 뒤 칸·PDF·수신자가 바뀌면 거부된다. 사용자의 명시적 OK 없이 dry_run=false 를 호출하지 말 것. 칸 type: signature|seal|text|date|checkbox, side 는 roles[].side(sender=발신 회사가 값·직인으로 채움 / recipient=수신자가 서명). 크기 한도: MCP 요청 본문 상한이 약 1MB 라 pdf_base64 는 약 750KB 까지만 가능하다. 더 큰 PDF 는 REST(POST /contracts:send_document, 5MB)로 올린 뒤 응답의 document_ref("sha256:...")를 여기에 넘긴다. 양식(템플릿)으로 보낼 수 있으면 create_draft → send_for_signature 가 더 쉽다.

필요한 스코프: contract:send · 분류: delivery · readOnlyHint=false · destructiveHint=true · idempotentHint=true

입력

이름타입·제약설명
title *string
minLength: 1 · maxLength: 200
문서 제목(≤200자).
document_kindstring
enum: company_form | agreement | employment_contract | other · default: "other"
문서 종류. 근로계약이면 employment_contract.
pdf_base64stringPDF 원본 base64(약 750KB 이하 — MCP 본문 1MB 한도). document_ref 와 택일.
document_refstring이미 올린 PDF 의 "sha256:<64자 hex>". pdf_base64 와 택일.
roles *array<object>서명 역할 목록. 발신(sender) 역할은 회사가 자동 처리, 수신(recipient) 역할 수만큼 recipients 필요.
roles[].id *string역할 id(칸의 role 과 같은 값).
roles[].label *string화면에 보일 역할 이름(예: 회사, 직원).
roles[].side *string
enum: sender | recipient
발신/수신.
roles[].orderinteger
minimum: 1
서명 순서(선택).
recipients *array<object>받는 사람. recipients[].role 을 모두 넣으면 역할 id 로, 모두 빼면 수신 역할 순서대로 매핑.
recipients[].name *string
recipients[].phone *string휴대폰(본인확인·알림톡).
recipients[].emailstring
recipients[].rolestring수신 역할 id(선택).
fields *array<object>칸 목록. x·y·w·h 는 쪽 크기 대비 0~1 비율(좌상단 원점). 쪽 밖이면 field_out_of_page 로 거부된다.
fields[].type *string
enum: signature | seal | text | date | checkbox
fields[].role *string이 칸을 채울 역할 id(roles[].id).
fields[].page *integer
minimum: 1
1부터 시작하는 쪽 번호.
fields[].x *number
minimum: 0 · maximum: 1
fields[].y *number
minimum: 0 · maximum: 1
fields[].w *number
minimum: 0 · maximum: 1
fields[].h *number
minimum: 0 · maximum: 1
fields[].keystring값 칸 key(선택).
fields[].labelstring칸 이름(선택).
fields[].requiredboolean
fields[].valuestring발신 역할이 미리 채울 값(선택).
subjectobject문서 대상자(근로계약 등 1:1 문서에서 수신자와 대조). { name, phone }.
subject.namestring
subject.phonestring
employer_seal_imagestring회사 전자인감 PNG/JPEG data URL(선택). 없으면 싸인딜 기존 직인 규칙.
client_refstring호출자 멱등 참조(선택, 같은 값=같은 요청).
channelstring
enum: auto | kakao_alimtalk | sms | lms · default: "auto"
expires_in_daysinteger
minimum: 1 · maximum: 30 · default: 7
dry_runboolean
default: true
기본 true(미리보기). false = 실발송(confirmation_token·idempotency_key 필수).
confirmation_tokenstringdry_run 미리보기에서 받은 1회용 토큰. dry_run=false 일 때 필수.
idempotency_keystring실발송 멱등키(필수 — dry_run=false 일 때). 같은 키 재시도는 첫 결과를 재생한다.

출력

이름타입·제약설명
would_sendbooleandry_run 미리보기 여부.
layout_hashstring칸·역할·문서 해시(dry_run).
confirmation_tokenstringdry_run 시 발급되는 1회용 토큰.
contract_idstring실발송 시 생성된 계약 id.
statusstring실발송 시 sent|partially_signed.

별칭

check_status · 상태 조회

계약·서명 진행 상태를 조회한다(readOnly). 출력: { status, channel_used, signers[]{name,role,signed,signed_at,auth_verified,viewed_at,decline_reason}, expires_at, next_poll_after_sec }. next_poll_after_sec(기본 30) 로 폴링 백오프를 권고(과도 폴링 rate limit 방지).

필요한 스코프: contract:read · 분류: contract_read · readOnlyHint=true · destructiveHint=false · idempotentHint=true

입력

이름타입·제약설명
contract_id *string
minLength: 1
조회할 계약 id.

출력

이름타입·제약설명
statusstring
channel_usedstring|null
signersarray{name,role,signed,signed_at,auth_verified}.
next_poll_after_secinteger

별칭

get_signed_document · 완료 문서·보존본 조회

체결 완료(completed) 계약의 보존본 단기 presigned URL(기본 5분) + audit trail + 무결성 해시를 반환한다(readOnly). 미완료면 document_url 대신 available_after 또는 종료사유(declined/expired)를 반환(미완성 문서 유출 방지). 출력: { status, document_url, audit_trail_url, completed_at, hash_sha256, tsa_token_present, retention_until }. tsa_token_present=false 여도 계약은 유효(타임스탬프는 증거력 보강 옵션).

필요한 스코프: document:read · 분류: documents · readOnlyHint=true · destructiveHint=false · idempotentHint=true

입력

이름타입·제약설명
contract_id *string
minLength: 1
문서를 가져올 계약 id.
formatstring
enum: pdf · default: "pdf"
보존본 포맷(MVP: pdf 고정).

출력

이름타입·제약설명
availableboolean
document_urlstring|null단기 presigned URL(완료 시).
hash_sha256string|null
tsa_token_presentboolean

별칭

list_contracts · 계약 문서함 조회

내 계약 문서함을 조회한다(readOnly). status 필터로 보낸/진행/체결 문서함을 구분 — completed = 체결 완료 문서함(양 당사자 열람), sent·partially_signed = 진행 중, draft·ready = 임시저장. 출력: { contracts:[{ contract_id, title, contract_type, status, amount_krw, created_at, completed_at }], next_offset }. 체결 완료 문서는 수정 불가(불변)이며 보존본은 get_signed_document 로 받는다.

필요한 스코프: contract:read · 분류: contract_read · readOnlyHint=true · destructiveHint=false · idempotentHint=true

입력

이름타입·제약설명
statusstring
enum: draft | ready | sent | partially_signed | completed | archived | declined | expired | voided | deleted
상태 필터(선택). completed = 체결 문서함.
limitinteger
minimum: 1 · maximum: 100 · default: 20
페이지 크기(기본 20).
offsetinteger
minimum: 0 · default: 0
페이지 오프셋.

출력

이름타입·제약설명
contractsarray{contract_id,title,contract_type,status,amount_krw}.
next_offsetinteger|null

별칭

get_usage · 사용량·무료쿼터 조회

발송 사용량, 가입 시 무료 10건(1회성) 잔여, 구매한 충전권 잔여를 조회한다(readOnly). 발송 전 비용 안내에 사용 — 무료 잔여 또는 충전 잔여가 있으면 발송 무료(건당 과금 없음), 모두 소진 시 VAT 포함 가격으로 충전이 필요하다. 출력: { period, free_quota, free_used, free_remaining, credit_balance, paid_count, paid_amount_krw, next_send_price_krw, requires_purchase }. next_send_price_krw 는 건당 과금 폐지로 항상 0, requires_purchase=true 는 무료·충전을 모두 소진해 발송하려면 충전이 필요함을 뜻한다.

필요한 스코프: contract:read · 분류: billing · readOnlyHint=true · destructiveHint=false · idempotentHint=true

입력

입력 없음 (object)

출력

이름타입·제약설명
periodstring
free_quotainteger
free_remaininginteger
credit_balanceinteger
credit_usedinteger
next_send_price_krwinteger

별칭