NextPDF Connect로 첫 PDF 생성하기

한눈에 보기

이 레시피는 빈 세션에서 시작해 NextPDF Connect를 통해 렌더링된 PDF에 이르는 가장 짧은 경로를 안내합니다. 한 페이지짜리 A4 문서를 생성하고, 제목과 부제목을 작성한 뒤, 파일을 base64로 반환합니다. 세 가지 Core 도구가 전체 작업을 처리합니다: create_pdf, add_text, output_pdf. 글꼴도, 이미지도, 라이선스 등급도 필요하지 않습니다.

Connect 전송 계층은 각 도구 호출을 요청으로 전달하고, 도구의 결과를 응답으로 반환합니다. 전송 계층은 도구가 보고하는 결과값에 의존하지 않습니다(PSR-18 §p2).

설치

NextPDF Server를 설치하고 전송 계층을 바인딩합니다:

composer require nextpdf/server

호스트가 기대하는 전송 방식으로 서버를 실행합니다 — stdio를 통한 Model Context Protocol, REST 또는 gRPC. 아래 전송 가용성을 참고하십시오. 이 레시피에서 사용하는 도구는 모두 Core 도구입니다. 이 도구들은 서버와 함께 제공되므로 Pro 또는 Enterprise 패키지가 필요하지 않습니다.

개념 개요

Connect 세션은 document_id로 식별되는 서버 측 문서 저장소입니다. create_pdf는 세션을 열고 그 id를 반환합니다. 이후 모든 도구 호출은 이 id를 참조합니다. 문서는 빈 페이지 하나로 시작합니다. 페이지 트리는 각 페이지에 접근하는 데 쓰이는 구조입니다(ISO 32000-2 §7.7.3). output_pdf는 세션을 PDF로 렌더링합니다. 기본적으로 렌더링 후 메모리를 해제하기 위해 세션을 파기합니다.

명시적인 x나 y 없이 add_text를 호출하면 텍스트가 흐름에 따라 배치됩니다. 즉, 현재 커서 위치에서 시작하며 호출할 때마다 커서가 이동합니다.

API 표면

서버가 부팅될 때 도구 레지스트리는 아래 도구들을 해석합니다. 이 이름들은 레지스트리의 프로토콜 이름입니다. 기준 카탈로그는 병합된 도구 카탈로그입니다. 설치된 등급에 따라 사용 가능한 도구가 달라질 수 있지만, 이 세 가지는 Core에 항상 포함됩니다.

도구	역할	위험 등급
`create_pdf`	문서 세션 열기	Safe
`add_text`	문서에 텍스트 작성	Caution
`output_pdf`	PDF 렌더링 및 반환	Approval Required(파일 모드) / Review(base64)

코드 샘플 — 빠른 시작

호스트는 세 번의 도구 호출을 수행합니다. 흐름은 다음과 같습니다:

create_pdf를 page_size: "A4", orientation: "portrait"와 문서 제목, 작성자와 함께 호출합니다. 서버는 document_id를 반환합니다.
add_text를 해당 document_id, 제목 텍스트, 큰 font_size, width: 0(전체 콘텐츠 너비), alignment: "center"와 함께 호출합니다.
output_pdf를 해당 document_id와 함께 호출합니다. file_path가 없으면 서버는 PDF를 base64로 반환하고 세션을 파기합니다.

다음은 최소한의 create_pdf 인수 객체입니다:

{
  "page_size": "A4",
  "orientation": "portrait",
  "title": "Hello World",
  "author": "NextPDF Cookbook"
}

응답에는 document_id, 페이지 수, 페이지 형상이 포함됩니다. id는 불투명한 값으로 취급하고, 그 안에서 의미를 해석하려 하지 마십시오.

코드 샘플 — 프로덕션

프로덕션 호출자는 다음 호출로 넘어가기 전에 모든 응답을 확인합니다. output_pdf가 세션을 파기한 후에는 document_id를 절대 재사용하지 않습니다.

create_pdf — 응답에 document_id가 포함되어 있는지 확인합니다. 서버가 세션 한도 오류를 반환하면 사용하지 않는 세션을 해제하고 다시 시도하십시오.
add_text(제목) — 응답이 position을 반환하는지 확인합니다.
add_text(부제목) — 더 작은 font_size를 사용합니다. 커서는 제목 아래에서 계속 이어집니다.
output_pdf — base64 필드를 읽고 바이트로 디코딩합니다. destroyed 플래그는 세션이 사라졌음을 확인해 줍니다.

파일이 인라인으로(base64 모드) 반환되므로 파일 시스템 부작용이 없고 사람 승인 게이트도 필요하지 않습니다 — HITL 위험 등급을 참고하십시오.

엣지 케이스 및 함정

파기된 세션. output_pdf가 기본값 destroy: true로 실행된 후에는 document_id가 더 이상 유효하지 않습니다. 그 id에 대한 이후의 모든 호출은 알 수 없는 문서 오류를 반환합니다. 대신 새 세션을 생성하십시오.
알 수 없는 페이지 크기. 서버는 인식하지 못하는 page_size를 거부하고 명확한 오류를 반환합니다. 문서화된 크기(A3, A4, A5, A6, Letter, Legal, Tabloid)를 사용하십시오.
빈 텍스트. 빈 text는 오류가 아니라 너비가 0인 항목을 생성합니다. 호출 전에 입력을 확인하십시오.
세션 한도. 인메모리 저장소는 동시에 실행되는 세션 수를 제한합니다. output_pdf로 세션을 즉시 해제하십시오.

성능

텍스트만 있는 단일 페이지는 페이지 예산 안에서 충분히 렌더링되며, 출력물은 보통 1–3 KB입니다. 이 레시피의 이중 렌더링 재현성 프로파일은 structural입니다. PDF에는 실행할 때마다 바뀌는 트레일러 /ID와 타임스탬프가 포함되므로, 구조적(정규화된) 비교가 가장 타당한 방식입니다.

보안 참고 사항

base64 경로에는 파일 시스템 부작용이 없습니다. 파일 출력 경로는 단일 파일 시스템 부작용을 만들며, 게이트로 통제됩니다 — HITL 섹션을 참고하십시오. 반환된 base64를 신뢰할 수 있는 채널이 아니라 문서 콘텐츠로 취급하십시오. 이는 도구가 생성한 바이트 그 자체입니다.

적합성

진술	사양	조항	reference_id
전송 계층은 결과와 무관하게 요청을 보내고 응답을 받습니다.	PSR-18	§p2
페이지는 문서 페이지 트리를 통해 접근됩니다.	ISO 32000-2	§7.7.3

이 레시피는 서버가 출력을 생성하는 방식을 설명합니다. 어떠한 프로파일 적합성도 주장하지 않습니다.

상업적 맥락

해당 없음 — 세 도구 모두 Core입니다.

전송 가용성

전송 방식	가용 여부	참고
MCP (stdio)	예	도구 호출은 MCP `tools/call`에 매핑됩니다.
REST	예	각 도구는 REST 작업이며, 결과는 응답 본문입니다.
gRPC	예	각 도구는 단항(unary) 호출입니다.

도구 결과는 모든 전송 방식에서 동일하고, 프레이밍만 다릅니다. 성공이 아닌 결과도 여전히 정상 응답이며, 전송 실패가 아닙니다(PSR-18 §p2).

HITL 위험 등급

서버는 각 도구 호출을 사람 개입(HITL) 위험 등급 체계에 배치합니다: Safe(0) → Caution(1) → Review(2) → Approval Required(3). create_pdf는 Safe이고 add_text는 Caution입니다. output_pdf는 Approval Required이지만, base64 모드(file_path 없음)에서는 Review로 낮아져 사람의 확인 없이 실행됩니다. 파일에 기록하면 Approval Required로 유지됩니다 — output-approval과 HITL 위험 등급 참조를 참고하십시오.

확인 게이트 JSON 봉투

이 레시피는 base64 모드를 유지하므로 확인 게이트는 허용 봉투를 반환합니다:

{ "allowed": true }

챌린지 봉투(allowed: false, challenge 문자열과 일회용 token 포함)는 output-approval에 문서화되어 있습니다.