NextPDF Connect 서버 개요

한눈에 보기

NextPDF Connect는 nextpdf/server 패키지로 제공되는 장기 실행 서비스이며, NextPDF PDF 2.0 엔진을 AI 에이전트와 HTTP 클라이언트에 노출합니다. 이 작업은 stdio 기반 Model Context Protocol(MCP), REST API, gRPC라는 세 가지 전송 방식으로 수행됩니다. 세 전송 방식은 모두 하나의 도구 레지스트리와 하나의 사람 개입(HITL) 확인 게이트 뒤에서 동작합니다.

설치

composer require nextpdf/server

Composer 제약 조건은 nextpdf/core: ^3.0이며, PHP 버전은 php: >=8.4 <9.0입니다. 전체 절차는 /connect/install/을 참조하세요. 해당 페이지에서는 두 가지 선택적 추가 구성 요소인 ext-redis 확장과 nextpdf/premium 패키지도 다룹니다.

개념 개요

nextpdf/server는 프레임워크에 종속되지 않는 NextPDF 코어를 서비스 표면으로 변환합니다. PDF 생성을 다시 구현하지는 않습니다. 대신 각 엔진 기능을 자체 스키마가 있는 명명된 도구로 래핑한 다음, 그 카탈로그를 여러 와이어 프로토콜을 통해 제공합니다.

세 가지 개념이 전체 설계의 기반이 됩니다.

도구 레지스트리. NextPDF\Server\ToolRegistry는 부팅 시 도구를 찾아 등록합니다. 핵심 도구 집합은 패키지에 함께 제공되며, 이 핵심 집합은 항상 사용할 수 있습니다. Pro 및 Enterprise 제공자는 더 많은 도구를 등록하지만, 해당 패키지가 설치된 경우에 한해서만 등록합니다. 따라서 노출되는 도구의 개수는 고정된 상수가 아니라 배포 환경의 런타임 속성입니다. /connect/tool-catalog/을 참조하세요.
전송 방식. 동일한 레지스트리가 세 가지 방식으로 제공됩니다. MCP는 로컬 AI 클라이언트를 위해 stdio를 통해 동작합니다. REST는 네트워크 클라이언트를 위해 RoadRunner 워커 풀에서 PSR-15 미들웨어 파이프라인을 통해 동작합니다. gRPC는 타입 지정 또는 스트리밍 클라이언트를 위해 Spiral RoadRunner gRPC 워커를 통해 동작합니다. 각 전송 방식은 자체 진입점을 가진 별도의 프로세스입니다. /transports/mcp/, /transports/rest/, /transports/grpc/을 참조하세요.
확인 게이트. 모든 도구는 위험 수준을 선언합니다. 가장 높은 위험 수준의 도구는 실행되기 전에 명시적인 사람 확인을 요구합니다. 게이트는 일회용 챌린지 토큰을 발급합니다. 에이전트는 그 토큰을 사람에게 전달한 다음, 해당 토큰과 함께 도구를 다시 호출해야 합니다. /connect/hitl-risk-tiers/을 참조하세요.

아래 다이어그램은 하나의 레지스트리가 세 가지 전송 방식에 어떻게 연결되는지 보여줍니다. 또한 확인 게이트가 요청 경로에서 어디에 위치하는지도 보여줍니다.

NextPDF Connect component architecture

이 패키지는 Apache-2.0 라이선스를 따르며, 이는 nextpdf/core와 일치합니다. 구현된 MCP 프로토콜 버전은 날짜 기반 버전인 2025-06-18 개정판입니다. REST 표면은 OpenAPI 3.1 문서로 설명됩니다. gRPC 표면은 nextpdf.connect.v1 Protocol Buffers 패키지로 설명됩니다.

API 표면

공개 진입점은 세 개의 서버 클래스입니다. 각 클래스에는 명령줄 인터페이스(CLI) 래퍼가 함께 제공됩니다.

진입점	클래스	전송 방식
`bin/nextpdf-mcp`	`NextPDF\Server\Mcp\McpServer`	stdio 기반 MCP
`bin/nextpdf-server`	`NextPDF\Server\Http\HttpServer`	RoadRunner HTTP 기반 REST
`bin/nextpdf-grpc`	`NextPDF\Server\Grpc\GrpcServer`	RoadRunner gRPC 기반 gRPC
`bin/generate-skills`	`NextPDF\Server\Skills\SkillsDumper`	도구 카탈로그 내보내기

McpServer::create(), HttpServer::create(), GrpcServer::create()는 각각 환경 및 구성 입력값으로부터 완전히 구성된 서버를 빌드합니다. 레지스트리, 문서 저장소, 보안 정책, 확인 게이트는 세 서버에서 공유되는 개념입니다.

코드 예제 — 빠른 시작

가장 단순한 MCP 서버 실행은 명령 하나면 됩니다. PHP 글루 코드를 작성할 필요가 없습니다.

./vendor/bin/nextpdf-mcp

서버는 표준 입력에서 JSON-RPC 요청을 읽고 표준 출력에 응답을 씁니다. 실행 가능한 initialize 및 tools/list 교환과 그에 대응하는 REST 요청은 /connect/quickstart/을 참조하세요.

예외 상황과 주의 사항

도구 개수는 33 개도 아니고, 그 밖의 어떤 고정된 숫자도 아닙니다. 서버는 정책 필터링과 계층 감지를 거친 후 런타임에 count(ToolRegistry::all())로 도구 개수를 셉니다. 고정된 총개수를 인용하는 문서는 오래된 것입니다. 정확한 개수를 얻으려면 실행 중인 서버에 질의하세요. MCP initialize 응답이나 REST /api/v1/capabilities 엔드포인트를 사용하세요.

노출되는 도구의 개수는 설치된 패키지와 활성 정책에 따라 달라집니다. 런타임에 실행 중인 서버에서 해당 값을 읽으세요. 직접 작성한 코드나 문서에 복사해 넣은 고정된 숫자는 시간이 지나면 더 이상 유효하지 않게 됩니다.
Pro 또는 Enterprise 패키지가 없는 것은 오류가 아닙니다. 레지스트리는 class_exists()로 제공자 클래스를 확인한 다음, 존재하지 않는 계층은 조용히 건너뜁니다. 오픈 소스만으로 구성된 배포도 정상적으로 부팅되어 핵심 카탈로그를 제공합니다.
세 가지 전송 방식은 프로세스를 공유하지 않습니다. MCP 서버를 실행해도 REST 서버나 gRPC 서버가 시작되지 않습니다. 그 반대의 경우도 마찬가지입니다. 통합 배포에서는 두 워커 풀, 즉 HTTP 풀과 gRPC 풀을 모두 시작하는 구성으로 RoadRunner 수퍼바이저를 실행합니다. /connect/deployment/을 참조하세요.

성능

각 전송 방식은 워커 기반입니다. 워커는 한 번에 하나의 요청을 처리합니다. REST 서버와 gRPC 서버는 RoadRunner 워커 풀에서 실행되며, 풀 크기는 구성에서 설정합니다. 기본값은 HTTP 워커 4 개입니다. RoadRunner 수퍼바이저는 각 워커의 메모리를 제한합니다. 이 페이지의 performance_budget 프런트매터는 콜드 부팅 및 발견 단계의 범위를 설명합니다. 이는 요청별 목표가 아닙니다. 각 요청 비용의 대부분은 기반 엔진 작업에 의해 좌우됩니다.

보안 참고 사항

모든 네트워크 전송 방식은 애플리케이션 프로그래밍 인터페이스(API) 키 베어러 토큰으로 인증합니다. MCP stdio 전송 방식은 MCP 전송 모델에 따라 실행한 클라이언트가 신뢰하는 로컬 하위 프로세스로 동작합니다. 고위험 도구는 모든 전송 방식에서 사람 확인 게이트 뒤에 보호된 상태로 유지됩니다. 전체 위협 모델, 인증 모델, 전송 보안 구성은 /connect/security-and-operations/을 참조하세요.

적합성

이 페이지는 아키텍처 관련 주장만 제시합니다. 규범적 프로토콜 및 보안 인용은 해당 동작을 명시하는 페이지에 고정되어 있습니다. 해당 페이지는 /connect/security-and-operations/, /transports/mcp/, /transports/rest/, /transports/grpc/입니다. MCP 수명 주기 참조 자료는 modelcontextprotocol.io의 공식 명세(개정판 2025-06-18)입니다. MCP 명세는 게이트된 표준 코퍼스의 일부가 아니므로, 전송 방식 페이지에서는 해당 참조 자료를 그 URL과 함께 기록합니다.

상업적 맥락

핵심 카탈로그는 문서 생성, 검사, 진단 측면에서 완결적입니다. 서명, 편집 차단, 규정 준수 인증, 포렌식 분석을 위한 도구는 서버와 함께 nextpdf/premium이 설치된 경우에만 나타납니다. 이는 패키징 경계이며, 런타임에 나타나는 업셀 프롬프트가 아닙니다. 서버는 마케팅 콘텐츠를 결코 내보내지 않습니다.

함께 참조

/connect/install/ — 설치 및 선택적 패키지
/connect/quickstart/ — 처음 실행해 볼 수 있는 MCP 및 REST 교환
/connect/tool-catalog/ — 검증된 핵심 도구 집합과 개수가 런타임에 따라 달라지는 방식
/connect/hitl-risk-tiers/ — 확인 게이트와 위험 모델
/transports/mcp/, /transports/rest/, /transports/grpc/ — 전송 방식별 설정
/connect/security-and-operations/ — 인증, 전송 보안, 위협 모델
/connect/deployment/ — RoadRunner, Docker, 통합 전송 방식 배포