NextPDF Connect로 여러 페이지 문서 만들기

한눈에 보기

NextPDF Connect로 여러 페이지 문서를 만듭니다. add_page는 문서의 기본 지오메트리를 상속하거나 방향을 재정의한 페이지를 추가합니다. 각 add_page 호출 후 커서는 새 페이지의 왼쪽 위 여백으로 재설정됩니다. 네 가지 도구를 사용하며, 모두 Core입니다: create_pdf, add_text, add_page, output_pdf.

설치

composer require nextpdf/server

전송 방식을 바인딩합니다: MCP stdio, REST 또는 gRPC. 라이선스 등급이 필요하지 않습니다.

개념 개요

문서는 페이지 트리로 구성됩니다. 각 페이지는 해당 트리를 통해 접근되는 노드입니다(ISO 32000-2 §7.7.3). 페이지에는 가시 영역을 정의하는 미디어 박스 등 자체 지오메트리 속성이 있습니다(ISO 32000-2 §7.7.3.3). create_pdf는 첫 페이지를 자동으로 만들고, add_page는 그 뒤에 각 페이지를 추가합니다. page_size/orientation을 생략하면 문서의 기본값을 상속합니다. orientation: "landscape"를 설정하면 A4 페이지를 297×210 mm로 회전합니다.

API 표면

도구	역할	위험 등급
`create_pdf`	세션 열기 및 첫 페이지 생성	Safe
`add_text`	커서 위치에 텍스트 쓰기	Caution
`add_page`	페이지 추가(상속 또는 재정의)	Caution
`output_pdf`	PDF 렌더링 후 반환	Approval Required / Review(base64)

도구 이름은 레지스트리 프로토콜에 정의된 이름입니다. 기준 카탈로그는 도구 카탈로그입니다. 사용할 수 있는 도구는 설치된 등급에 따라 달라집니다.

코드 샘플 — 빠른 시작

흐름을 정리하면 다음과 같습니다:

create_pdf(A4 세로, 제목, 작성자) → document_id.
add_text(제목, 큰 글꼴, 가운데 정렬), 이어서 add_text(소개 단락, 본문 글꼴).
add_page에 document_id만 전달 → A4 세로를 상속합니다. 새 page_number가 반환되고 커서가 재설정됩니다.
2페이지의 섹션 제목과 본문에 add_text.
add_page에 orientation: "landscape" 지정 → 넓은 A4 페이지를 만듭니다.
넓은 콘텐츠에 add_text.
output_pdf → base64.

코드 샘플 — 프로덕션

각 응답을 검증합니다. add_page 후에는 콘텐츠가 새 페이지 맨 위에서 시작된다고 가정하십시오. 커서 재설정은 의도된 동작이며 결함이 아닙니다. add_text 응답의 position.page를 추적하여 콘텐츠가 뒤쪽 페이지로 넘어갔는지 감지하십시오. output_pdf를 정확히 한 번만 호출한 다음 document_id를 폐기하십시오.

예외 상황 및 함정

커서 재설정. add_page 후에 커서는 새 페이지의 왼쪽 위 여백에 위치합니다. 이전 페이지에서 계속 이어진다고 예상하는 것이 가장 흔한 실수입니다.
필수 document_id. create_pdf를 제외한 모든 도구는 document_id가 필요합니다. 이를 생략하면 오류입니다.
잘못된 방향. "portrait"와 "landscape"만 유효합니다.
출력 후 편집. output_pdf를 destroy: true와 함께 호출한 뒤 콘텐츠를 추가하면 세션이 사라졌기 때문에 실패합니다.

성능

여러 페이지 텍스트 문서는 페이지 예산 내에 머물며 출력은 수 KB입니다. 프로파일은 structural입니다: 트레일러 /ID와 타임스탬프는 실행 간 안정적이지 않습니다.

보안 참고 사항

base64 모드에는 부작용이 없습니다. 파일 출력은 게이트로 보호됩니다(HITL 섹션). document_id는 불투명 핸들입니다. 동시 요청 간에 이를 공유하지 마십시오.

적합성

진술	사양	조항	reference_id
페이지는 페이지 트리를 통해 접근됩니다.	ISO 32000-2	§7.7.3
페이지 객체는 자체 지오메트리 속성을 정의합니다.	ISO 32000-2	§7.7.3.3

상업적 맥락

해당 없음 — 모든 도구가 Core입니다.

전송 방식 가용성

전송 방식	사용 가능	참고
MCP (stdio)	예	도구마다 `tools/call`.
REST	예	도구마다 작업 하나.
gRPC	예	도구마다 단항 호출.

HITL 위험 등급

create_pdf는 Safe이고, add_text와 add_page는 Caution이며, output_pdf는 Approval Required이고 base64 모드에서는 Review로 강등됩니다. 파일 출력은 Approval Required를 유지합니다. output-approval과 HITL risk tiers를 참고하십시오.

확인 게이트 JSON 봉투

여기서는 base64 출력입니다:

{ "allowed": true }

챌린지 양식은 output-approval에서 확인할 수 있습니다.