Pro 에디션

MCP Tools — 심층 참조

가용성 및 라이선싱

이 기능은 NextPDF Pro(nextpdf/pro)에 포함되어 제공되며 Pro 등급 라이선스 봉투로 활성화됩니다. 해당 권한이 없는 배포는 이 기능의 클래스를 로드하지 않습니다. 에디션 비교 및 라이선스 받기.

기능별 라이선스 플래그는 없습니다. 코드는 Pro 에디션과 함께 제공되며, 부팅 시 Pro 패키지가 nextpdf/server와 함께 해석되면 여덟 개의 도구가 pro 등급으로 등록됩니다.

동작 계약

NextPDF Server는 부팅 시 Pro 도구 공급자 클래스를 탐지하여 등급을 발견합니다. 해당 클래스가 해석되면, 서버는 여덟 개의 도구를 pro 등급으로 등록합니다. Pro 패키지는 서버의 하드 의존성이 아니므로, Pro 도구는 동시 설치를 통해서만 엄격하게 옵트인됩니다. 등급 등록은 독립적입니다. 누락되었거나 정책으로 제외된 등급이 다른 등급을 결코 차단하지 않습니다.
각 도구는 네 가지 위험 수준(safe, caution, review, approval-required) 중 하나를 선언합니다. 선택적 운영자 재정의는 도구의 수준을 올릴 수만 있고 결코 낮출 수 없습니다. 서버는 caution 이상에서의 모든 실행을 감사 로그에 기록합니다. sign_pdf는 approval-required입니다.
PDF 입력은 고정된 순서로 해석됩니다. 인메모리 저장소의 document_id, 그다음 source를 data: URI, 파일 시스템 경로, 또는 원시 base64로 해석합니다. 입력이 없으면 빈 문서를 처리하는 대신 검증 오류를 반환합니다.
sign_pdf는 PAdES B-B 기준선 서명만 생성합니다. 타임스탬프도, 장기 검증도 없습니다. 지원되는 알고리즘과 AES-GCM 키 전송 봉투는 아래에 자세히 설명됩니다. 복호화는 닫힌 상태로 실패하며, 도구는 암호문을 결코 키 자료로 사용하지 않습니다.
전체 발견, 위험, 소스 해석, 도구별, 서명 세부 사항은 아래 섹션을 참조하십시오. 이 페이지는 외부에서 관찰 가능한 동작과 공개된 도구 계약만을 설명합니다.

범위

이 페이지는 여덟 개의 Pro MCP 도구에 대한 운영자 및 통합자 참조입니다. 발견 모델, 서버가 적용하는 위험/HITL 의미론, 소스 해석 규칙, 서명 키 전송 봉투, 도구별 실패 동작을 다룹니다. 외부에서 관찰 가능한 동작과 공개된 도구 계약만을 설명합니다. 사용자 대상 카탈로그는 공개 MCP 페이지를 참조하십시오.

디스커버리 및 등록 모델

NextPDF Server는 부팅 시 등급 공급자를 발견합니다. Pro 도구 공급자 클래스를 탐지하여 Pro 등급을 감지하며, 클래스가 해석되면 서버는 공급자를 인스턴스화하고 공급자가 반환하는 각 도구를 pro 등급으로 등록합니다. Pro 패키지는 의도적으로 서버의 하드 의존성이 아닙니다. 이는 독점 패키지 없이도 오픈 소스 서버를 설치할 수 있게 하고, Pro 도구를 동시 설치를 통해서만 엄격하게 옵트인되도록 합니다.

서버는 등급별로 등록을 격리합니다. Pro 패키지가 없으면 Core 도구는 여전히 등록되며, 존재하는 등급 공급자가 다른 등급을 차단하지 않습니다. 도구 등록은 또한 서버의 보안 정책 허용 목록의 적용을 받습니다. 정책에 의해 제외된 도구는 조용히 등록되지 않으며 등급 요약에 집계되지 않습니다. 서버는 진단과 로깅을 위해 등급별 개수(core / pro / enterprise)를 노출합니다.

공급자는 여덟 개의 도구를 고정된 순서로 반환합니다. 텍스트 추출, 세분화, 비교, PII 마스킹, 양식 채우기, 양식 읽기, 접근성 분석, 서명. 순서는 안정적이지만 호출자는 이에 의존해서는 안 됩니다. 도구는 MCP 프로토콜 이름으로 해석하십시오.

위험 모델 및 HITL 의미 체계

각 도구는 네 가지 위험 수준 중 하나를 선언합니다. 서버는 선언된 수준을 사람 개입(human-in-the-loop) 강제에 사용합니다.

Safe — 읽기 전용, 부작용 없음. 자동 실행됩니다.
Caution — 인메모리 상태를 생성하거나 수정합니다. 감사 로그 항목과 함께 자동 실행됩니다.
Review — 오용될 수 있는 출력을 생성합니다. 자동 실행되지만, 에이전트 스킬 지침이 이를 표시하여 에이전트가 사용자에게 경고합니다.
Approval-required — 파괴적, 법적, 또는 개인 정보에 결정적입니다. 서버는 실행 전에 명시적인 사람의 확인을 요구합니다.

Pro 도구 분류: 다섯 개의 추출/분석 도구(extract_text, segment_document, compare_pdfs, extract_form_data, check_accessibility)는 safe이고, redact_pii와 fill_form은 review이며, sign_pdf는 approval-required입니다.

위험 수준은 정확히 두 가지 출처에서 나옵니다. 도구 자체의 선언, 그리고 런타임의 선택적 운영자 재정의입니다. 재정의는 도구의 위험 수준을 올릴(강제를 강화) 수만 있고, 결코 낮출 수 없습니다. 서버는 caution 수준 이상에서의 모든 실행을 감사 로그에 기록합니다. 위험 모델은 버전을 가지며, 서버는 초기화 응답에서 해당 버전을 광고하므로 클라이언트가 호환되지 않는 변경을 감지할 수 있습니다.

소스 해석 순서

PDF를 받는 모든 도구는 다음 순서로 해석되는 세 가지 입력 형태 중 하나를 통해 PDF를 받습니다.

document_id — 서버는 인메모리 문서 저장소에서 바이트를 가져옵니다. 알 수 없는 id는 호출자에게 먼저 문서를 생성하도록 안내하는 명시적 오류로 실패합니다.
data: URI로서의 source — 도구는 쉼표 뒤의 base64 본문을 디코딩합니다.
파일 시스템 경로로서의 source — 경로가 파일로 해석되면 도구는 디스크에서 읽습니다.
원시 base64 문자열로서의 source — 도구는 충분히 길고 base64 형태인 입력만 받아 디코딩합니다.

compare_pdfs는 동일한 해석을 source_a와 source_b에 독립적으로 적용하며, 추가로 두 소스 슬롯 중 어느 쪽에서든 document_id 값을 받습니다. document_id도 source도 제공되지 않으면, 도구는 빈 문서를 처리하는 대신 검증 오류를 반환합니다.

도구별 참조

Tool	Risk	Inputs	Result fields	Behavioral boundary
`extract_text`	safe	PDF; optional 1-indexed `page_start` / `page_end`	text, total page count	텍스트 레이어 전용. 범위는 실제 페이지 수로 클램핑됨. OCR 없음
`segment_document`	safe	PDF	segment count, segment list	레이아웃에서 도출된 세그먼트. 태그된 PDF 구조 트리가 아님
`compare_pdfs`	safe	two PDFs	identical flag, total changes, per-doc page counts, regions (type, text, page index, line index, optional counterpart text)	텍스트 콘텐츠 diff. 시각적이거나 바이너리가 아님
`redact_pii`	review	PDF; optional `types` (`email`, `phone`, `ssn`, `credit_card`)	has-PII flag, detected count, masked text, scanned types	텍스트 레이어 탐지/마스킹. 시각적 마스킹이 아님. 패턴 기반이며 완전하지 않음
`fill_form`	review	`fields` map; optional `pdf_filename`	XFDF document, field count	XFDF(ISO 19444-1)를 생성함. 값을 PDF에 쓰지 않음
`extract_form_data`	safe	PDF	field count, field map, explicit note when none	임베드된 XFDF만 읽음
`check_accessibility`	safe	PDF	structural score (0–100), issues, segment summary	WCAG 참조를 갖춘 구조적 휴리스틱. 적합성 판정이 아님
`sign_pdf`	approval-required	PDF; PEM cert + PKCS#8 key; optional algorithm, signer name, reason, transport envelope	signed PDF, signature count, completion flag, algorithm, OID, digest	PAdES B-B 기준선 전용. 타임스탬프 없음, LTV 없음

서명: 알고리즘 및 키 전송

sign_pdf는 PAdES B-B 기준선 서명을 생성합니다. 지원되는 알고리즘은 밑줄과 대시 표기 둘 다로 허용됩니다.

RSA with SHA-256 (기본값).
RSA with SHA-3 256 / 384 / 512 — SHA-3을 지원하는 OpenSSL 빌드가 필요합니다.
Ed25519 — libsodium 확장이 필요합니다. 키는 Ed25519 개인 키를 감싸는 PKCS#8 PEM이어야 합니다.

도구는 지원되지 않는 식별자를 거부하고 허용되는 값의 목록을 반환합니다.

선택적 전송 암호화 봉투는 호출자가 종단 간 기밀이 아닌 전송을 통해 개인 키를 터널링할 수 있게 합니다. 봉투는 AES-GCM 전용입니다.

대칭 키: 16, 24, 또는 32바이트(AES-128/192/256), base64로 인코딩됨.
논스: 정확히 12바이트, base64로 인코딩됨.
선택적 추가 인증 데이터, base64로 인코딩됨.
private_key 페이로드는 끝에 16바이트 GCM 인증 태그가 붙은 base64 암호문입니다.

복호화는 닫힌 상태로 실패합니다. 인증 태그 불일치나 잘못된 형식의 페이로드는 복호화 오류를 반환하며, 도구는 암호문을 결코 키 자료로 사용하지 않습니다. 도구는 어떠한 암호화 작업 전에도 잘못된 키나 논스 크기를 거부합니다.

엣지 케이스 및 FIPS 모드 동작

extract_text: 도구는 문서를 초과하는 페이지 범위 끝을 거부하는 대신 클램핑하고, 첫 페이지보다 낮은 시작을 첫 페이지로 정규화합니다.
compare_pdfs: source_a 또는 source_b가 없으면 검증 오류를 반환합니다. 동일한 문서는 변경이 0인 명시적 동일 결과를 반환합니다.
extract_form_data: 임베드된 XFDF 스트림이 없는 PDF는 오류가 아니라 설명 노트와 함께 필드 0개 결과를 반환합니다.
redact_pii: types의 인식되지 않는 항목은 무시됩니다. 전부 인식되지 않는 목록은 실패가 아니라 빈 스캔을 산출합니다.
sign_pdf: 인증서나 개인 키가 없으면 어떠한 서명 작업 전에도 실패합니다. 도구는 서명 시점에 알고리즘 요구 사항(SHA-3 OpenSSL 지원, Ed25519용 libsodium)을 확인하고 이를 명시적 오류로 표면화합니다.
FIPS 모드: 알고리즘 가용성은 호스트 OpenSSL/libsodium 빌드를 따릅니다. FIPS 제약 빌드에서는 승인되지 않은 알고리즘이 조용히 다운그레이드되지 않고 암호화 경계에서 명시적 오류로 실패합니다. MCP 계층은 암호화 정책을 추가하거나 완화하지 않습니다. 호스트 암호화 공급자의 결정을 표면화할 뿐입니다.

운영자 런북 노트

sign_pdf를 approval-required로 유지하십시오. safe 도구의 위험을 의도치 않게 올리는 운영자 재정의가 없는지 확인하십시오. 재정의는 강화만 하므로, 우발적 재정의는 안전성이 아니라 가용성을 저하시킵니다.
감사 보존: review 수준 이상에서의 모든 실행은 서버에 의해 감사 로그에 기록됩니다. redact_pii, fill_form, sign_pdf 호출량에 맞게 로그 보존을 설계하십시오.
전송 선택: 종단 간 기밀이 아닌 전송을 통해 실행할 때는, sign_pdf에 AES-GCM 키 전송 봉투를 요구하고 에이전트의 도구 호출 로깅 정책에서 개인 키 자료를 비밀로 취급하십시오.
등급 개수: 서버의 등급별 개수를 사용하여 배포 시점에 Pro 등급이 여덟 개의 도구를 등록했는지 확인하십시오. 개수가 0이면 Pro 패키지가 해석되지 않은 것입니다.

에디션 경계

Pro 등급은 정확히 여덟 개의 MCP 도구를 제공합니다. Enterprise 에디션은 자체 도구를 갖춘 별도의 MCP 등급을 제공합니다. 규정 준수, 포렌식, 장기 검증 상태, AI 준비 인증, 문서 검색/임베딩입니다. Enterprise 도구의 입력, 출력, 내부는 여기서 범위 밖이며 Enterprise 에디션과 함께 문서화됩니다. 서버는 등급을 독립적으로 발견합니다. 누락된 등급이 다른 등급을 비활성화하는 일은 결코 없습니다.

게시 경계

이 페이지는 외부에서 관찰 가능한 동작과 지원되는 공개 API 표면만을 문서화합니다. 내부 네임스페이스 경로, 헬퍼 클래스, 메커니즘 테이블, 런북 파일명, 티켓 접두사는 범위 밖입니다.