NextPDF Connect 통합

한눈에 보기

NextPDF Connect는 서버로 실행해 통합합니다. 라이브러리를 호스트 애플리케이션에 연결하는 방식이 아닙니다. 전송 방식을 선택한 다음, 선택한 전송 방식이 네트워크 전송 방식인 경우 인증을 구성합니다. 엔진 도구는 확인 게이트 뒤에 배치됩니다.

설치

composer require nextpdf/server

Composer 제약 조건은 nextpdf/core: ^3.0이며 php: >=8.4 <9.0도 함께 요구합니다. 선택 사항인 ext-redis와 nextpdf/premium에 대해서는 /connect/install/.을 참조하세요.

개념 개요

이 패키지는 독립 실행형 서비스입니다. 호스트 프레임워크에 등록할 서비스 프로바이더, 번들 또는 컨테이너 모듈은 없습니다. 통합 지점은 사용자가 실행하는 프로세스입니다. 각 전송 방식에는 자체 진입점이 있으며 독립적으로 부팅됩니다. /connect/boot-and-discovery/.을 참조하세요.

API 표면

진입점	전송 방식	프로필
`bin/nextpdf-mcp`	stdio 기반 MCP	(없음 — 직접 하위 프로세스)
`bin/nextpdf-server`	RoadRunner HTTP 기반 REST	`.rr.yaml`
`bin/nextpdf-grpc`	RoadRunner gRPC 기반 gRPC	`.rr.grpc.yaml`
두 네트워크 전송 방식 모두	REST + gRPC	`.rr.full.yaml`

부팅 및 자동 검색

레지스트리는 코어 계층을 항상 검색합니다. 그런 다음 해당 클래스가 확인되면 Pro 및 Enterprise 프로바이더를 추가하고, 이어서 환경 게이트 아래에서 번들 제공 AST 및 뮤테이션 프로바이더를 추가합니다. enabled_tools 보안 허용 목록이 이 모든 항목을 필터링하므로, 노출되는 카탈로그는 해당 배포에 고유합니다. /connect/tool-catalog/ 및 /connect/boot-and-discovery/.을 참조하세요.

컨테이너 바인딩

없습니다. 각 서버 팩토리는 자체 객체 그래프를 명시적으로 구성합니다. 주입 가능한 접점은 애플리케이션 통합용이 아니라 테스트용입니다.

구성 게시

MCP 서버는 선택적 YAML 파일(--config=PATH, nextpdf_mcp 섹션)과 NEXTPDF_MCP_* 환경 변수 재정의를 허용합니다. REST 및 gRPC 서버는 NEXTPDF_* 환경 변수를 읽습니다. 자세한 내용은 /connect/configuration/.을 참조하세요.

전송 방식 가용성 (MCP / REST / gRPC)

세 가지 전송 방식은 모두 동일한 레지스트리를 제공합니다.

MCP — 로컬 하위 프로세스, stdio 기반 JSON-RPC 2.0, API 키 없음, MCP 리비전 2025-06-18. /transports/mcp/.을 참조하세요.
REST — RoadRunner HTTP 워커 풀, OpenAPI 3.1 계약, bearer API 키, 계층별 게이트 경로. /transports/rest/.을 참조하세요.
gRPC — RoadRunner gRPC 워커 풀, nextpdf.connect.v1 Protobuf 서비스, 서버 스트리밍 RPC, 메타데이터의 bearer 인증, 결합 프로필에서의 상호 TLS. /transports/grpc/.을 참조하세요.

해당 진입점 또는 RoadRunner 프로필이 실행 중이면 전송 방식은 “사용 가능” 상태입니다. 전송 방식이 서로를 자동으로 시작하지는 않습니다.

HITL 위험 계층

모든 도구는 네 가지 위험 수준(safe, caution, review, approval_required) 중 하나를 선언합니다. approval_required 수준의 도구는 첫 번째 호출에서 실행되지 않습니다. 확인 게이트는 사람이 승인해야 하는 일회용 챌린지 토큰을 발급합니다. 구성 재정의는 도구의 위험 수준을 높일 수만 있으며, approval_required 도구를 낮출 수는 절대 없습니다. 이 모델은 도구를 구동하는 모든 전송 방식에 동일하게 적용됩니다. /connect/hitl-risk-tiers/.을 참조하세요.

확인 게이트 JSON 봉투

게이트 검사는 두 가지 JSON 형태 중 하나를 반환합니다. 허용되는 경우:

{ "allowed": true }

챌린지:

{
  "allowed": false,
  "challenge": "<human-readable text naming the operation, its description, an overwrite warning when applicable, and the re-invocation instruction>",
  "token": "confirm_<nonce>"
}

토큰은 도구 이름, 무작위 논스, 300 초 TTL을 바인딩하며, 인수는 바인딩하지 않습니다. 진행하려면 호출자는 _confirmation_token 인수를 발급된 토큰으로 설정해 동일한 도구를 다시 호출합니다. 챌린지는 일반 안내 텍스트와 토큰으로 구성되며, 암호학적으로 서명된 봉투가 아닙니다. /connect/hitl-risk-tiers/.을 참조하세요.

서비스 스모크 테스트

./vendor/bin/generate-skills --dry-run --list-tools

이 명령은 레지스트리와 계층 감지를 부팅한 다음, 트래픽을 처리하지 않고 노출된 도구를 출력합니다. 통합이 제대로 연결되었는지 확인하고, 이 설치가 생성하는 카탈로그를 점검하는 빠른 방법입니다.

엣지 케이스 및 주의 사항

프레임워크 후크 없음. 서비스 프로바이더나 번들을 찾지 마세요. 통합은 실행 중인 프로세스 자체입니다.
누락된 계층은 오류가 아닙니다. 코어 전용 설치는 부팅되고 코어 카탈로그를 제공합니다.
네트워크 전송 방식에는 키가 필요합니다. /healthz 및 /readyz(REST)와 헬스 RPC(gRPC)만 익명입니다.

성능

부팅 비용은 레지스트리 스캔과 계층 감지이며, 프로세스당 한 번 발생합니다. 요청당 비용은 엔진 작업에서 발생합니다. 관측된 렌더링 지연 시간에 맞춰 RoadRunner 워커 풀 크기를 조정하세요. /connect/production-usage/.을 참조하세요.

보안 참고 사항

네트워크 전송 방식은 상수 시간으로 검증되는 npk_live_ bearer 키로 인증합니다. 게이트는 전송 방식과 관계없이 파괴적 작업에 대해 사람의 확인을 강제합니다. 신뢰할 수 없는 네트워크에서는 REST 앞단에서 TLS를 종료하고 gRPC에는 상호 TLS를 사용하세요. /connect/security-and-operations/.을 참조하세요.

적합성

프로토콜과 보안 관련 인용은 /transports/mcp/, /transports/rest/, /transports/grpc/, /connect/security-and-operations/.에 고정되어 있습니다.

상업적 맥락

서버와 함께 nextpdf/premium을 설치하면 추가 Pro 및 Enterprise 도구가 실행 중인 동일한 서버에 등록됩니다. 별도 프로세스는 관여하지 않습니다.