NextPDF Connect 구성

한눈에 보기

NextPDF Connect에는 두 개의 구성 영역이 있습니다. MCP 서버는 YAML 파일과 NEXTPDF_MCP_* 변수를 읽습니다. REST 및 gRPC 서버는 NEXTPDF_* 환경 변수를 읽습니다. 서버가 부팅된 뒤에는 구성을 변경할 수 없습니다.

설치

composer require nextpdf/server

개념 개요

MCP 서버는 고정된 우선순위에 따라 구성을 해석합니다. 우선순위가 가장 높은 소스가 적용됩니다.

1. 환경 변수(NEXTPDF_MCP_*).
2. YAML 구성 파일의 nextpdf_mcp 섹션.
3. 내장 기본값.

YAML 파일은 --config=PATH로 전달합니다. 이 파일이 없으면 서버는 기본값과 환경 변수만 사용합니다. 그 결과 생성되는 McpConfig는 readonly 값 객체입니다. 부팅 후에는 어떤 설정도 바뀌지 않습니다.

REST 및 gRPC 서버는 부팅 시 환경에서 HttpConfig를 읽습니다. 지원되는 환경 재정의는 NEXTPDF_BIND, NEXTPDF_WORKER_COUNT, NEXTPDF_SESSIONS_ENABLED, 그리고 NEXTPDF_CORS_ENABLED입니다. 나머지 상한값에는 안전한 기본값이 적용됩니다.

API 표면

MCP 구성(nextpdf-mcp)

YAML 파일의 nextpdf_mcp 섹션:

nextpdf_mcp:
  enabled_tools: []          # empty/absent = all available tools allowed
  temp_directory: /tmp/nextpdf-mcp
  max_documents: 50
  document_ttl: 1800
  max_file_size_bytes: 104857600
  allow_file_output: true
  compress: true
  risk_level_overrides:
    fill_form: 3             # raise fill_form to ApprovalRequired (see below)

MCP 서버용 환경 재정의:

변수	구성 키	기본값
NEXTPDF_MCP_ENABLED_TOOLS	enabled_tools	모든 도구 허용
NEXTPDF_MCP_TEMP_DIR	temp_directory	시스템 임시 디렉터리 + /nextpdf-mcp
NEXTPDF_MCP_MAX_FILE_SIZE	max_file_size_bytes	104857600 (100 MB)
NEXTPDF_MCP_MAX_DOCUMENTS	max_documents	50
NEXTPDF_MCP_DOCUMENT_TTL	document_ttl	1800초
NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED	(parse_pdf 게이트)	설정 안 됨(비활성화됨)
NEXTPDF_AST_TOOLS_ENABLED	(AST 도구 게이트)	활성화됨
NEXTPDF_MUTATION_TOOLS_ENABLED	(AST 변형 도구 게이트)	설정 안 됨(비활성화됨)

REST 및 gRPC 구성

변수	기본값	효과
NEXTPDF_BIND	0.0.0.0:8080	REST 수신 대기 주소
NEXTPDF_WORKER_COUNT	4	RoadRunner PHP 워커 수
NEXTPDF_SESSIONS_ENABLED	false	상태 저장 세션 엔드포인트 활성화
NEXTPDF_CORS_ENABLED	false	CORS 응답 헤더 활성화
NEXTPDF_API_KEYS	설정 안 됨	인라인 API 키 정의
NEXTPDF_API_KEYS_FILE	설정 안 됨	API 키 파일 경로
NEXTPDF_JOB_STORE_PATH	시스템 임시 디렉터리	SQLite 작업 저장소 경로
NEXTPDF_REDIS_HOST	설정 안 됨	설정 시 Redis 기반 저장소를 활성화함

Redis(NEXTPDF_REDIS_HOST가 설정되고 ext-redis가 로드된 경우 REST 서버에서 사용):

변수	기본값
NEXTPDF_REDIS_PORT	6379
NEXTPDF_REDIS_PASSWORD	비어 있음
NEXTPDF_REDIS_DATABASE	0
NEXTPDF_REDIS_PREFIX	nextpdf:
NEXTPDF_REDIS_CONNECT_TIMEOUT	2.0초
NEXTPDF_REDIS_READ_TIMEOUT	2.0초

코드 예제 — 빠른 시작

명시적으로 지정한 구성 파일로 MCP 서버를 실행합니다:

./vendor/bin/nextpdf-mcp --config=/etc/nextpdf/nextpdf-mcp.yaml

코드 예제 — 프로덕션

MCP 카탈로그를 명시적으로 지정한 허용 목록으로 제한하고, 도구의 위험 수준을 상향합니다:

/etc/nextpdf/nextpdf-mcp.yaml

nextpdf_mcp:
  enabled_tools:
    - create_pdf
    - add_text
    - output_pdf
    - diagnostic.doctor
  temp_directory: /var/lib/nextpdf/tmp
  max_file_size_bytes: 26214400
  risk_level_overrides:
    add_text: 2          # upgrade add_text from caution to review

비어 있지 않은 enabled_tools가 있으면 보안 정책은 나열된 도구 이름만 허용합니다. 그 외의 모든 도구는 레지스트리에서 자동으로 제거됩니다. 목록이 비어 있거나 없으면 사용 가능한 모든 도구를 허용합니다.

예외 사례 및 주의 사항

• 두 개의 중요한 도구는 하향 조정할 수 없습니다. output_pdf와 sign_pdf는 설계상 승인 게이트가 적용됩니다. risk_level_overrides 항목이 둘 중 하나를 ApprovalRequired 미만으로 낮추도록 설정하면 로드 시 InvalidArgumentException을 발생시키며, 서버는 부팅을 거부합니다. 그 외 모든 도구의 위험 수준은 상향 또는 하향할 수 있으므로, 하향 조정은 반드시 자체 위협 모델에 비추어 검토하십시오. /connect/hitl-risk-tiers/. 항목을 참조하십시오.

• enabled_tools는 필터링할 뿐, 추가하지 않습니다. nextpdf/premium 패키지가 없는 상태에서 Pro 도구 이름을 나열해도 해당 도구가 나타나지는 않습니다. 허용 목록은 레지스트리가 실제로 발견한 도구와의 교집합으로 적용됩니다.

• MCP 서버에서는 환경이 YAML보다 우선합니다. NEXTPDF_MCP_* 변수는 YAML 파일의 동일한 키를 재정의합니다. REST 및 gRPC 서버는 MCP YAML 파일을 전혀 읽지 않습니다.

• parse_pdf는 옵트인 방식입니다. parse_pdf 도구는 NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED가 true 또는 1일 때만 등록됩니다. 기본적으로는 core 카탈로그에도 포함되지 않습니다.

성능

구성은 부팅 시 한 번만 구문 분석됩니다. max_documents 및 document_ttl 설정은 인메모리 문서 저장소의 한도를 정합니다. 이 값을 낮추면 문서 수명이 짧아지는 대신 최대 메모리 사용량이 줄어듭니다. 워커 수와 계층별 페이로드 상한값은 배포 튜닝 수단이며, /connect/deployment/.에서 다룹니다.

보안 참고 사항

• 최소 권한 배포에서는 enabled_tools를 기본 거부 제어 수단으로 취급하십시오. 즉, 해당 통합에 필요한 도구만 나열하십시오.
• API 키를 YAML 파일에 절대로 저장하지 마십시오. NEXTPDF_API_KEYS_FILE을 사용하여 Docker 또는 Kubernetes 시크릿으로 마운트된 파일을 지정하십시오. 서버는 핫 리로딩 파일 저장소를 우선하므로 재시작 없이 키를 교체할 수 있습니다. /connect/security-and-operations/. 항목을 참조하십시오.
• 파일 출력 시 temp_directory는 강제 기준 디렉터리로 사용됩니다. 서버는 출력 경로를 정규화하며, 이 디렉터리 밖으로 해석되는 모든 경로를 거부합니다.

적합성

이 페이지는 구성 메커니즘을 설명합니다. 인증 및 전송 보안 적합성 인용은 /connect/security-and-operations/.에 고정되어 있습니다.

상업적 맥락

계층별 페이로드 및 타임아웃 상한값(corePayloadLimit, proPayloadLimit, enterprisePayloadLimit 및 이에 대응하는 타임아웃)은 인증된 API 키의 계층에 따라 REST 전송에 적용됩니다. 이 상한값은 Pro 또는 Enterprise 도구가 설치되어 있고 키에 해당 도구에 대한 권한이 부여된 경우에만 적용됩니다.

참고 항목

• /connect/install/ — 설치 및 선택적 패키지
• /connect/boot-and-discovery/ — 구성이 부팅 시퀀스에 반영되는 방식
• /connect/hitl-risk-tiers/ — 위험 모델과 상향 전용 재정의
• /connect/security-and-operations/ — API 키 구성 및 전송 보안
• /connect/deployment/ — 프로덕션 환경의 워커 수, Redis 및 계층 상한값