NextPDF Connect 도구 카탈로그

한눈에 보기

NextPDF Connect 배포가 노출하는 도구 수는 고정된 상수가 아닙니다. 서버는 설치된 패키지, 구성의 허용 목록, 일련의 환경 게이트를 바탕으로 런타임에 이 값을 계산합니다. 이 페이지에서는 검증된 핵심 집합과 전체 수를 결정하는 방식을 문서화합니다.

설치

composer require nextpdf/server

개념 개요

NextPDF\Server\ToolRegistry는 부팅 시 다음 순서로 카탈로그를 구성합니다.

핵심 계층. 고정된 핵심 도구 집합은 항상 등록됩니다. 추가 도구 두 개는 사전 조건이 충족될 때만 등록됩니다.
Pro 계층. Pro 도구는 Pro 공급자 클래스가 확인될 때 등록되며, 이는 nextpdf/premium이 설치되어 있을 때 발생합니다. 클래스가 확인되지 않으면 서버는 이 단계를 조용히 건너뜁니다.
Enterprise 계층. Enterprise 공급자는 Pro 공급자와 동일한 패턴을 따릅니다.
번들로 제공되는 확장 계층. AST 및 뮤테이션 도구 공급자는 서버 패키지와 함께 제공되며 Pro 계층 아래에 등록됩니다. 환경 게이트는 각 공급자를 제어하고, 각 공급자는 기반 핵심 지원이 없을 때 정상적으로 기능을 축소합니다.
보안 정책 필터. 서버는 모든 등록 항목을 enabled_tools 허용 목록과 대조합니다. 비어 있지 않은 허용 목록은 목록에 없는 모든 도구를 제외합니다. 계층 카운터는 정책에서 허용한 도구만 계산합니다.

MCP initialize 응답은 실행 중인 서버의 결과 tool_count와 계층별 개수를 보고합니다. 이 값이 권위 있는 숫자입니다. 본문에 적힌 고정된 전체 수치는 모두 오래된 것으로 간주하십시오.

API 표면

검증된 상시 사용 가능 핵심 도구

이 열두 개의 도구는 핵심 계층에 항상 등록됩니다. 서버는 각 위험 등급과 MCP 동작 힌트를 도구 구현에서 읽습니다.

도구 이름	범주	설명	위험
`create_pdf`	document	새 PDF 문서를 생성하고 `document_id`를 반환합니다	caution
`add_text`	document	PDF 문서에 텍스트 콘텐츠를 추가합니다	caution
`add_image`	document	파일 경로 또는 base64 데이터에서 이미지를 추가합니다	caution
`add_table`	document	PDF 문서에 HTML 표를 추가합니다	caution
`set_font`	document	이후 텍스트 작업에 사용할 글꼴을 설정합니다	caution
`add_page`	document	PDF 문서에 새 페이지를 추가합니다	caution
`output_pdf`	document	PDF를 파일 또는 base64로 완성합니다	approval_required
`preview_layout`	document	렌더링 없이 레이아웃의 JSON 요약을 제공합니다	safe
`diagnostic.doctor`	diagnostic	상태 점검을 실행하고 구조화된 환경 진단을 제공합니다	safe
`diagnostic.capabilities`	diagnostic	계층 및 상태와 함께 기능을 나열합니다	safe
`diagnostic.inspect`	diagnostic	PDF를 검사하고 구조적 메타데이터를 반환합니다	safe
`diagnostic.verify`	diagnostic	PDF 무결성을 검증하며, 선택적으로 PDF/A 또는 PDF/UA 검사를 수행합니다	caution

조건부로 등록되는 핵심 도구

도구 이름	조건
`generate_barcode`	설치된 패키지 `nextpdf/core`에 핵심 바코드 인코더 레지스트리가 있을 때 등록됩니다
`parse_pdf`	`NEXTPDF_MCP_TOOL_PARSE_PDF_ENABLED`이 `true` 또는 `1`일 때만 등록됩니다

output_pdf는 approval_required 위험 수준에 있는 유일한 핵심 도구입니다. 파일 쓰기에는 휴먼 인 더 루프 게이트가 적용되지만, base64 출력 모드에는 적용되지 않습니다. /connect/hitl-risk-tiers/ 항목을 참조하십시오.

추가 패키지가 설치된 경우에만 추가되는 도구

서버는 class_exists()로 공급자 클래스를 탐지합니다.

Pro 도구는 nextpdf/premium이 설치되고 Pro 공급자가 확인될 때 등록됩니다.
Enterprise 도구는 nextpdf/premium이 설치되고 Enterprise 공급자가 확인될 때 등록됩니다. 개인정보 보호 도구(편집, 비식별화, 영역 편집)는 Enterprise 클래스를 래핑합니다. 이러한 도구는 해당 클래스를 자동 로드할 수 있을 때만 Enterprise 계층 아래에 등록됩니다.
AST 및 뮤테이션 도구는 서버와 함께 제공되며 Pro 계층 아래에 등록됩니다. NEXTPDF_AST_TOOLS_ENABLED 및 NEXTPDF_MUTATION_TOOLS_ENABLED 게이트가 이를 제어하며, 두 게이트는 모두 기본적으로 활성화되어 있습니다.

정확한 Pro 및 Enterprise 도구 목록은 서버가 아니라 Premium 패키지가 정의하며, 해당 패키지와 함께 문서화됩니다. 서버의 계약은 고정된 Premium 목록이 아니라 등록 메커니즘입니다.

코드 예제 — 빠른 시작

서버를 시작하지 않고 현재 설치가 노출하는 도구를 출력합니다.

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

코드 예제 — 프로덕션

MCP를 통해 실행 중인 서버의 권위 있는 개수를 쿼리합니다.

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

서버는 실행 중인 프로세스를 기준으로 initialize 결과의 capabilities.nextpdf.tool_count와 tiers를 계산합니다. REST를 통해서는 GET /api/v1/capabilities가 동등한 인트로스펙션을 반환합니다.

예외 상황 및 주의 사항

고정된 “33 개 도구”는 없으며, 어떤 고정된 전체 수치도 없습니다. 오래된 자료에서는 단일 숫자를 인용하지만, 이는 계약이 아닙니다. 개수는 설치된 패키지, enabled_tools 허용 목록, parse_pdf, AST, 뮤테이션 환경 게이트에 따라 달라집니다. 항상 실행 중인 서버에서 읽으십시오.
허용 목록은 제거할 뿐, 결코 추가하지 않습니다. enabled_tools에 Pro 도구를 나열해도 nextpdf/premium이 없으면 등록되지 않습니다.
없는 계층은 조용히 처리되며, 이는 예상된 동작입니다. 오픈 소스 전용 설치는 핵심 집합을 제공하며 Pro 도구 0 개와 Enterprise 도구 0 개를 보고합니다. 그 결과는 오류가 아니라 올바른 동작입니다.
카탈로그의 계층은 선언된 불변값입니다. 각 도구는 코드에서 자체 계층과 위험을 선언합니다. 레지스트리는 네임스페이스나 패키징에서 계층을 추론하지 않습니다.

성능

레지스트리 스캔과 계층 감지는 부팅 시 한 번 실행됩니다. 이 페이지의 performance_budget가 이를 제한합니다. 도구별 비용은 카탈로그 조회가 아니라 기반 엔진 작업에서 발생하며, 카탈로그 조회는 도구 이름 기준으로 O(1)입니다.

보안 참고 사항

최소 권한 제어 수단으로 enabled_tools를 사용하십시오. 통합에 필요한 도구만 노출하십시오. 카탈로그에는 보안 정책이 거부한 도구가 절대 포함되지 않으며, 계층 카운터는 허용된 도구만 반영합니다. 고위험 도구는 카탈로그 포함 여부와 관계없이 계속 사람의 확인 게이트를 거칩니다. /connect/security-and-operations/ 항목을 참조하십시오.

적합성

이 페이지는 레지스트리 메커니즘을 설명합니다. tools/list 및 initialize 표면에 대한 프로토콜 인용은 /transports/mcp/에 고정되어 있습니다. 위험 모델은 /connect/hitl-risk-tiers/에 명세되어 있습니다.

상업적 맥락

핵심 카탈로그만으로도 생성, 검사, 진단에는 충분합니다. 서명, 편집, 규정 준수, 포렌식 도구는 nextpdf/premium이 서버와 함께 설치된 경우에만 나타납니다. 이는 런타임 프롬프트가 아니라 composer require 시점에 적용되는 패키징 경계입니다.

함께 보기

/connect/hitl-risk-tiers/ — 위험 열의 의미와 적용 방식
/connect/boot-and-discovery/ — 전체 부팅 및 검색 시퀀스
/connect/configuration/ — enabled_tools 및 환경 게이트
/transports/mcp/ — tools/list 및 initialize 와이어 형식
/connect/overview/ — 카탈로그가 설계상 런타임에 의존하는 이유