NextPDF Connect 빠른 시작

한눈에 보기

이 페이지에서는 MCP와 REST 두 전송 방식 모두에서 최소한이면서도 유용한 메시지 교환을 실행합니다. 각 요청은 서버가 구현한 정확한 와이어 형식을 따릅니다. 소프트웨어 개발 키트(SDK)는 사용하지 않습니다.

설치

composer require nextpdf/server

개념 개요

MCP 전송은 표준 입력과 출력을 통해 JSON-RPC 2.0으로 통신합니다. 이 순서는 필수이며 반드시 지켜야 합니다. 먼저 initialize를 보내고, 이어서 notifications/initialized 확인을 보냅니다. 그런 다음 tools/list와 tools/call을 보냅니다. 서버는 줄마다 하나의 JSON 메시지를 읽으며, 각 줄은 줄바꿈 문자로 끝나야 합니다. 서버는 줄마다 하나의 응답을 출력합니다.

REST 전송은 동일한 엔진 기능을 HTTP 작업으로 제공합니다. 단일 무상태 렌더는 정렬된 operations 배열을 포함한 하나의 POST /api/v1/render 요청입니다. 응답 본문은 PDF입니다.

코드 예제 — 빠른 시작 (stdio를 통한 MCP)

서버를 시작한 뒤 핸드셰이크를 서버로 파이프합니다. 아래 세 가지 요청은 프로토콜 핸들러가 라우팅하는 검증된 메서드 이름을 사용합니다.

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"quickstart","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
EOF

이 initialize 응답은 프로토콜 버전 2025-06-18, 서버 이름 NextPDF Connect, capabilities.nextpdf 블록을 보고합니다. 이 블록에는 실시간 계층 개수, 런타임 tool_count, 위험 모델 버전, 그리고 hitl_enabled: true가 포함됩니다. tools/list 응답은 이 설치에 등록된 도구를 정확히 나열합니다. 알림 줄은 설계상 응답을 생성하지 않습니다.

이제 안전한 도구를 호출합니다. diagnostic.doctor 도구는 읽기 전용 환경 점검을 실행합니다. 문서나 확인 절차는 필요하지 않습니다.

./vendor/bin/nextpdf-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"quickstart","version":"1.0.0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"diagnostic.doctor","arguments":{}}}
EOF

코드 예제 — 빠른 시작 (REST)

REST 서버를 시작한 다음, 한 줄짜리 PDF를 렌더링합니다. 서버는 상태 점검 엔드포인트를 제외한 모든 엔드포인트에서 API 키를 요구하므로, 먼저 키를 정의합니다.

export NEXTPDF_API_KEYS='npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef:demo:core:default'
./vendor/bin/rr serve -c .rr.yaml

두 번째 셸에서 렌더 요청을 전송합니다. 본문은 RenderRequest입니다. 이 요청에는 형식이 지정된 작업으로 구성된 정렬된 operations 배열이 포함됩니다.

curl -sS -X POST http://localhost:8080/api/v1/render \
  -H 'Authorization: Bearer npk_live_k8a3b2c1_0123456789abcdef0123456789abcdef' \
  -H 'Content-Type: application/json' \
  -d '{
        "page_size": "A4",
        "orientation": "portrait",
        "operations": [
          { "type": "add_text", "text": "Hello from NextPDF Connect" }
        ]
      }' \
  --output hello.pdf

이 200 응답의 본문은 PDF이며(Content-Type: application/pdf), hello.pdf에 기록됩니다. 상태 점검 프로브에는 키가 필요하지 않습니다.

curl -sS http://localhost:8080/healthz

예외 상황과 주의사항

핸드셰이크 순서가 중요합니다. 프로토콜 핸들러는 id가 없는 메시지를 알림으로 처리하며 아무것도 반환하지 않습니다. 먼저 id와 함께 initialize를 보내고, 그다음 initialized 알림을 보낸 뒤, 마지막으로 id를 포함한 요청을 보냅니다.
반복된 요청 id는 중복 제거됩니다. 핸들러는 최근 응답을 64개 항목으로 이루어진 순환 버퍼에 캐시합니다. 중복된 id에는 도구를 다시 실행하지 않고 캐시된 응답을 반환합니다. 새로운 id를 사용합니다.
고위험 도구는 결과 대신 챌린지로 응답합니다. output_pdf를 file_path와 함께 호출하면 실행하지 않고 확인 챌린지를 반환합니다. 발급된 _confirmation_token으로 다시 호출합니다. base64 출력 모드(file_path 없음)에는 확인이 필요하지 않습니다. /connect/hitl-risk-tiers/. 참조합니다.
인증되지 않은 REST 요청은 401을 받습니다. Authorization: Bearer 헤더가 누락되었거나 형식이 잘못된 경우 WWW-Authenticate: Bearer 헤더와 함께 problem-details 본문을 반환합니다. 익명 엔드포인트는 /healthz와 /readyz 프로브뿐입니다.

성능

두 가지 빠른 시작 경로는 모두 단일 요청입니다. REST 경로에서는 또한 rr serve 이후 첫 요청에서 RoadRunner 워커 풀의 콜드 스타트 비용이 발생합니다. 이후 요청은 예열된 워커를 재사용합니다.

보안 참고 사항

위의 npk_live_ 키는 일회용 데모 값입니다. 충분한 엔트로피를 사용해 실제 키를 생성하고, 소스 관리 외부에 저장하며, 키 교체에는 파일 기반 키 저장소를 우선 사용합니다. MCP stdio 전송은 MCP 전송 모델에 따라 이를 실행하는 클라이언트가 신뢰하는 로컬 하위 프로세스이므로 API 키를 사용하지 않습니다. /connect/security-and-operations/. 참조합니다.

적합성

이 페이지에 표시된 와이어 형식은 구현된 MCP 리비전 2025-06-18 및 OpenAPI 3.1 REST 계약과 일치합니다. 프로토콜 및 인증에 대한 규범적 인용은 /transports/mcp/, /transports/rest/, 그리고 /connect/security-and-operations/.에 고정되어 있습니다.

함께 보기

/transports/mcp/ — 전체 MCP 전송 참조
/transports/rest/ — 전체 REST 전송 참조와 OpenAPI 렌더링
/connect/tool-catalog/ — tools/list가 반환하는 도구와 그 이유
/connect/hitl-risk-tiers/ — 확인 챌린지의 형태
/connect/configuration/ — 카탈로그 제한과 서버 튜닝