NextPDF Connect 부팅과 검색

한눈에 보기

각 전송 방식에는 고유한 진입점과 부팅 시퀀스가 있습니다. 전송 방식들은 레지스트리, 구성, 게이트를 개념적으로 공유합니다. 각 전송 방식은 독립 프로세스로 실행되므로, 하나를 시작해도 다른 전송 방식이 시작되지는 않습니다.

설치

composer require nextpdf/server

개념 개요

MCP 부팅 시퀀스

McpServer::create()는 정해진 순서로 MCP 서버를 연결합니다. 먼저 구성을 로드하고, 그 구성에서 보안 정책을 빌드하며, 도구 레지스트리를 구성하고, 계층 검색을 실행합니다. 이어서 구성된 TTL과 용량을 바탕으로 인메모리 문서 저장소를 빌드하고, stdio 전송을 생성한 뒤, 확인 게이트 및 감사 로거와 함께 JSON-RPC 프로토콜 핸들러를 조립합니다. 이 준비가 끝나면 서버는 읽기-처리-쓰기 루프에 진입하고, 표준 입력이 파일 끝에 도달할 때까지 실행됩니다.

REST 부팅 시퀀스

HttpServer::create()는 환경에서 HttpConfig를 읽고 CLI 재정의를 적용합니다. 그런 다음 API 키 저장소를 다음 우선순위로 해석합니다. 핫 리로딩 파일 저장소가 먼저이고, 그다음이 정적 파일, 그다음이 환경입니다. 이어서 속도 제한 및 멱등성 저장소를 해석하며, Redis가 구성되어 있고 연결 가능한 경우 Redis를 사용하고 그렇지 않으면 인메모리 저장소로 폴백합니다. 이후 공유 SQLite 작업 저장소를 열고, 애플리케이션 서비스를 빌드한 다음, 라우트 테이블을 구성합니다. 라우트 테이블은 감지된 계층을 바탕으로 빌드되므로, 설치된 패키지를 반영합니다. 그런 다음 RoadRunner가 워커 요청 루프를 구동합니다.

gRPC 부팅 시퀀스

GrpcServer::create()는 동일한 키 저장소를 해석하고, 동일한 애플리케이션 서비스를 빌드한 뒤, Spiral gRPC 워커와 함께 nextpdf.connect.v1 서비스를 등록합니다. 엔진 종속성을 사용할 수 없어도 gRPC 서버는 계속 시작되어 상태 및 기능 쿼리를 제공합니다. 이 상태에서도 프로세스는 부팅을 거부하지 않습니다. 대신 데이터를 전달하는 RPC는 명확한 오류로 실패합니다.

도구 검색

검색은 레지스트리의 기본 등록 단계입니다. 핵심 계층이 먼저 등록됩니다. Pro 및 Enterprise 공급자는 해당 클래스가 class_exists()를 통해 해석되면 그다음에 등록됩니다. 이어서 번들 AST 및 변이 공급자가 해당 환경 게이트에 따라 Pro 계층 아래에 등록됩니다. 모든 등록은 enabled_tools 보안 허용 목록을 통해 필터링되며, 그 결과 산출된 계층별 개수가 MCP initialize 응답에 보고됩니다. 자세한 내용은 /connect/tool-catalog/을 참조하세요.

전송 검색

“전송 방식을 활성화하는” 단일 구성 설정은 없습니다. 각 전송 방식은 별도의 진입점입니다. REST와 gRPC는 각각 별도의 RoadRunner 프로필을 가집니다. 배포는 실행하는 프로필에 따라 전송 방식을 선택합니다. REST의 경우 .rr.yaml, gRPC의 경우 .rr.grpc.yaml, 둘 다의 경우 .rr.full.yaml입니다. 전송 방식은 독립 프로세스로 실행됩니다. 누락된 MCP 클라이언트가 REST 서버를 차단하는 일은 결코 없으며, 누락된 REST 클라이언트가 MCP를 차단하는 일도 결코 없습니다. 자세한 내용은 /connect/deployment/을 참조하세요.

구성 해석 순서

MCP 서버는 다음 우선순위로 구성을 해석합니다. 환경(NEXTPDF_MCP_*)이 YAML 파일의 nextpdf_mcp 섹션보다 우선하며, 이는 다시 내장 기본값보다 우선합니다. REST 및 gRPC 서버는 HttpConfig를 안전한 기본값과 함께 NEXTPDF_* 환경 변수에서 읽습니다. 이 서버들은 MCP YAML 파일을 읽지 않습니다. 자세한 내용은 /connect/configuration/을 참조하세요.

컨테이너 바인딩

등록해야 할 종속성 주입 컨테이너나 서비스 공급자는 없습니다. 각 create() 팩토리는 자체 객체 그래프를 명시적이고 결정론적으로 구성합니다. 주입 가능한 지점은 두 개, 즉 전송과 워커 팩토리이며, 둘 다 애플리케이션 연결이 아니라 테스트를 위한 것입니다.

코드 샘플 — 빠른 시작

트래픽을 처리하지 않고 검색이 생성한 결과를 검사합니다:

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

코드 샘플 — 프로덕션

하나의 슈퍼바이저 아래에서 결합된 전송 방식을 부팅합니다:

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
./vendor/bin/rr serve -c .rr.full.yaml

에지 케이스 및 함정

누락된 계층 때문에 부팅이 실패하지는 않습니다. 계층 검색은 없는 Pro 또는 Enterprise 패키지를 조용히 건너뜁니다. 서버는 핵심 카탈로그로 부팅됩니다.
다운그레이드 재정의는 부팅 실패를 유발합니다. risk_level_overrides 항목이 approval_required 도구를 약화시키면 구성 로드 시 예외가 발생하며, 서버는 시작을 거부합니다. 이는 의도적입니다.
Redis 장애는 성능을 저하시킬 뿐, 충돌하지 않습니다. Redis가 구성되어 있지만 부팅 시 연결할 수 없는 경우, REST 서버는 인메모리 저장소로 폴백합니다. Redis가 사용 중이라고 가정하지 말고 Redis 상태를 확인하세요.

성능

부팅 비용은 구성 파싱, 레지스트리 스캔, 계층 감지 비용을 합한 것입니다. 페이지의 performance_budget이 이 비용을 제한합니다. 이 비용은 요청마다가 아니라 프로세스 시작마다 한 번 지불됩니다.

보안 참고 사항

보안 정책은 레지스트리보다 먼저 빌드되므로, enabled_tools 허용 목록은 첫 등록 단계부터 검색 범위를 제한합니다. API 키는 MCP YAML 파일에서 결코 읽지 않으며, 네트워크 전송 방식은 비밀 파일 또는 환경에서 키를 해석합니다. 자세한 내용은 /connect/security-and-operations/을 참조하세요.

적합성

이 페이지는 부팅 메커니즘을 설명합니다. 프로토콜 및 보안 인용은 /transports/mcp/, /transports/rest/, /transports/grpc/, 그리고 /connect/security-and-operations/.에 고정되어 있습니다.

상업적 맥락

부팅 시 계층 감지는 서버와 함께 nextpdf/premium이 설치되어 있을 때, nextpdf/premium이 Pro 및 Enterprise 도구를 카탈로그에 기여하는 단일 지점입니다.