Pro 에디션

MCP 도구

한눈에 보기

NextPDF Pro는 AI 에이전트가 NextPDF Server를 통해 고급 PDF 작업을 실행할 수 있도록 여덟 개의 Model Context Protocol(MCP) 도구를 추가합니다. 이 도구들은 nextpdf/pro와 nextpdf/server가 모두 설치되면 자동으로 노출됩니다 — 별도의 등록 단계가 필요하지 않습니다.

가용성 및 라이선스

이 기능은 NextPDF Pro(nextpdf/pro)에 포함되며 Pro 계층 라이선스 봉투로 활성화됩니다. 그 자격이 없는 배포 환경은 이 기능의 클래스를 로드하지 않습니다. 에디션 비교 및 라이선스 받기.

기본 MCP 표면 — 문서 생성, 텍스트, 표, 진단 — 은 오픈 소스 NextPDF Server와 함께 제공되며 라이선스가 필요하지 않습니다. 이 페이지의 여덟 개 도구에는 Pro 라이선스가 필요하며, 부팅 시 nextpdf/pro 패키지가 해석될 때만 등록됩니다. pro 도구 계층이 전체 세트를 게이트합니다. 각 도구는 자체 계층을 명시적으로 선언하며, 도구별 플래그는 없습니다 — nextpdf/pro를 nextpdf/server와 함께 설치하면 세트가 활성화됩니다.

동작 계약

여덟 개의 Pro MCP 도구는 부팅 시 nextpdf/pro와 nextpdf/server가 모두 해석되면 pro 계층 아래에서 표준 MCP tools/list 및 tools/call 흐름을 통해 자동으로 등록됩니다. 도구별 플래그가 없으며, 소비하는 애플리케이션의 코드 변경이 필요하지 않습니다.
각 도구는 이전 create_pdf 호출의 document_id, 인라인 source(파일 경로, base64, 또는 data: URI), 또는 — compare_pdfs의 경우 — 그러한 소스 두 개를 통해 PDF를 받습니다. 도구는 구조화된 JSON을 반환합니다.
모든 도구는 서버가 적용하는 HITL 위험 등급을 선언합니다. 즉, 안전(자동 실행, 읽기 전용), 검토(오용될 수 있는 출력), 그리고 승인 필요입니다. sign_pdf는 승인 필요이며 사람이 확인할 때까지 보류됩니다. 운영자는 도구의 위험 등급을 강화할 수만 있고, 결코 완화할 수 없습니다.
sign_pdf는 PAdES B-B(기준) 서명만 생성합니다 — 신뢰된 타임스탬프도, 장기 검증 자료도 없습니다. 장기(B-LT / B-LTA) 프로필, 하드웨어 키 보관, 감사 추적 서명은 Enterprise 계층이며 이 도구들에서 제공되지 않습니다. B-T(타임스탬프된 서명)는 타임스탬프 공급자가 구성된 경우 Core 엔진에서 제공됩니다.
redact_pii는 시각적 수정(redaction)이 아니라 텍스트 레이어 패턴 감지 및 마스킹을 수행합니다. check_accessibility는 PDF/UA나 WCAG 적합성 판정이 아니라 구조적 휴리스틱입니다. 권위 있는 입력/출력 스키마는 이 페이지가 아니라 서버의 라이브 tools/list 응답입니다.

개념 개요

NextPDF Server는 NextPDF를 위한 결정적 MCP 실행 계층입니다. 부팅 시 클래스 존재 프로브를 사용해 도구 공급자를 발견하므로, Pro 패키지가 서버의 의존성에 나열될 필요가 없습니다. Pro 패키지가 존재하면 서버는 pro 계층 아래에 여덟 개 도구를 등록하고, 구성한 어떤 전송 방식에서든 표준 MCP tools/list 및 tools/call 흐름을 통해 노출합니다.

각 Pro 도구는 세 가지 소스 중 하나로부터 PDF를 받습니다. 이전 create_pdf 호출이 반환한 document_id, 인라인 source(파일 경로, base64 문자열, 또는 data: URI), 또는 — 비교 도구의 경우 — 그러한 소스 두 개입니다. 도구는 구조화된 JSON 결과를 반환합니다. 즉, 추출된 텍스트, diff 영역, 마스킹된 텍스트, 세그먼트 트리, 접근성 결과, 또는 서명된 PDF입니다.

모든 Pro 도구는 서버가 인간 개입(human-in-the-loop, HITL) 적용에 사용하는 위험 분류를 담고 있습니다. 읽기 전용 분석 도구는 안전으로 분류되어 자동 실행됩니다. 호출자가 오용할 수 있는 출력을 생성하는 도구는 검토 등급입니다. 서명 도구는 승인 필요로 분류되므로, 서버는 사람이 확인할 때까지 보류합니다. 도구 자체가 이 분류를 선언합니다. 운영자는 런타임에 이를 강화할 수만 있고 — 결코 완화할 수 없습니다.

MCP 도구 표면은 의도적으로 Pro PDF 엔진과 분리되어 있습니다. 도구는 얇은 어댑터입니다. 즉, 입력을 검증하고, PDF를 해석하고, Pro 엔진 구성 요소에 위임하고, 결과를 직렬화합니다. 이들은 엔진의 두 번째 API가 아니며 Pro 공개 PHP API의 일부가 아닙니다 — 지원되는 통합 지점은 NextPDF Server가 노출하는 MCP 프로토콜입니다.

도구 카탈로그 (여덟 개 Pro 도구)

MCP 프로토콜 이름별 여덟 개의 Pro MCP 도구입니다. 위험 수준은 서버의 HITL 모델을 따릅니다. safe(자동 실행, 읽기 전용), review(오용될 수 있는 출력을 생성하며 에이전트 지침에서 경고됨), 그리고 approval-required(사람이 확인해야 함)입니다.

`extract_text`

목적: 텍스트 추출. PDF의 텍스트 레이어를 추출하며, 선택적으로 1부터 시작하는 페이지 범위로 제한합니다.
입력: PDF(document_id 또는 source), 선택적 page_start 및 page_end.
출력: 추출된 텍스트와 총 페이지 수.
위험: Safe. 읽기 전용이며 멱등적입니다.
경계: 기존 텍스트 레이어를 추출합니다. 스캔된 페이지나 이미지 전용 페이지에 OCR을 수행하지 않습니다.

`segment_document`

목적: 구조적 세분화. PDF를 논리적 섹션으로 분할합니다 — 제목, 헤딩, 본문, 표, 그림.
입력: PDF(document_id 또는 source).
출력: 세그먼트 수와 구조화된 세그먼트 목록.
위험: Safe. 읽기 전용이며 멱등적입니다.
경계: 레이아웃 분석 기반의 구조적 세분화입니다. 시맨틱 개요나 태그된 PDF 구조 트리가 아닙니다.

`compare_pdfs`

목적: 구조적 diff. 두 PDF를 비교하고 텍스트 콘텐츠의 구조화된 diff를 반환합니다.
입력: 두 개의 PDF(source_a 및 source_b, 각각 경로, base64, 데이터 URI, 또는 document_id).
출력: identical 플래그, 총 변경 수, 문서별 페이지 수, 그리고 페이지 및 라인 인덱스가 포함된 변경 영역 목록.
위험: Safe. 읽기 전용이며 멱등적입니다.
경계: 텍스트 콘텐츠 diff입니다. 시각적 렌더링, 포함된 글꼴, 또는 바이너리 구조를 diff하지 않습니다.

`redact_pii`

목적: PII 감지 및 마스킹. PDF의 텍스트 레이어에서 개인 식별 정보를 감지하고 마스킹된 텍스트 뷰를 반환합니다.
입력: PDF(document_id 또는 source), 선택적 types 필터(email, phone, ssn, credit_card).
출력: has-PII 플래그, 감지된 수, 마스킹된 텍스트, 그리고 스캔된 유형 목록.
위험: Review. 마스킹된 출력은 정화된 문서로 취급될 경우 오용될 수 있습니다.
경계: 이것은 시각적 수정(redaction)이 아니라 텍스트 레이어 패턴 감지 및 마스킹입니다. 렌더링된 PDF에서 글리프를 제거하거나 덮어쓰지 않으며, 패턴 매칭이 민감 데이터의 모든 인스턴스를 찾는다고 보장하지 않습니다. 그 출력을 완전한 PII 제거의 보장으로 취급하지 마십시오. 기반 콘텐츠를 파괴하는 문서 수준 수정(redaction)에는 오픈 소스 서버 도구나 Enterprise 에디션의 전용 수정 표면을 사용하십시오.

`fill_form`

목적: AcroForm 채우기 데이터. 필드 이름-값 맵으로부터 PDF AcroForm 필드를 채우는 XFDF(ISO 19444-1) 데이터를 생성합니다.
입력: 필드 이름-문자열 값의 fields 맵, 선택적으로 XFDF 참조로 포함되는 pdf_filename.
출력: 생성된 XFDF 문서와 필드 수.
위험: Review. 문서에 적용될 의도의 폼 데이터를 생성합니다.
경계: 표준을 준수하는 XFDF를 생성합니다. 그 자체로는 값을 PDF에 다시 기록하지 않습니다. 표준을 준수하는 리더나 처리 도구로 XFDF를 적용하십시오.

`extract_form_data`

목적: AcroForm 읽기. PDF에 포함된 XFDF에서 AcroForm 필드 이름과 값을 추출합니다.
입력: PDF(document_id 또는 source).
출력: 필드 수와 필드 이름-값 맵, 포함된 폼 데이터가 없을 때의 명시적 안내.
위험: Safe. 읽기 전용이며 멱등적입니다.
경계: 포함된 XFDF(ISO 19444-1) 스트림을 읽습니다. 포함된 XFDF 없이 AcroForm 객체에만 폼 값을 보유한 PDF는 빈 결과를 반환합니다.

`check_accessibility`

목적: 구조적 접근성 분석. PDF의 구조적 접근성 — 헤딩, 단락, 표, 이미지 —을 분석하고 WCAG 참조와 함께 발생 가능한 문제를 보고합니다.
입력: PDF(document_id 또는 source).
출력: 구조적 점수(0–100), 문제 목록, 세그먼트 요약.
위험: Safe. 읽기 전용이며 멱등적입니다.
경계: 이것은 적합성 판정이 아니라 구조적 휴리스틱입니다. 전체 PDF/UA 및 WCAG 적합성 테스트 — 태그 트리, 읽기 순서, 색상 대비 —에는 전용 접근성 엔진이 필요합니다. 높은 점수가 PDF/UA 적합성에 대한 진술은 아닙니다.

`sign_pdf`

목적: PAdES B-B 디지털 서명. 로컬 X.509 인증서와 개인 키를 사용해 PDF에 PAdES B-B(기준) 디지털 서명을 적용합니다.
입력: PDF(document_id 또는 source), PEM 인증서와 PKCS#8 개인 키, 선택적 알고리즘(RSA-SHA256 기본값, RSA + SHA-3 256/384/512, 또는 Ed25519), 선택적 서명자 이름과 사유, 개인 키 페이로드를 감싸는 선택적 AES-GCM 전송 봉투.
출력: 서명된 PDF, 서명 수, 완료 플래그, 그리고 사용된 알고리즘, OID, 다이제스트.
위험: Approval-required. 서명은 법적으로 중요한 파괴적 작업입니다. 서버는 실행 전에 명시적인 사람의 확인을 요구합니다.
경계: 이 도구는 PAdES B-B(기준) 서명을 생성합니다 — 신뢰된 타임스탬프나 장기 검증 자료를 포함하지 않습니다. 장기(B-LT / B-LTA) 프로필, 하드웨어 기반 키 보관, 감사 추적 서명은 Enterprise 에디션의 일부입니다. B-T(타임스탬프된 서명)는 타임스탬프 공급자가 구성된 경우 Core 엔진에서 제공됩니다. Pro 패키지의 더 넓은 서명 기능과 B-LT/B-LTA에 대한 Enterprise 에디션은 Pro 서명 표면을 참조하십시오.

도구가 노출되는 방식

composer require nextpdf/pro
composer require nextpdf/server

두 패키지가 모두 설치된 상태에서 선택한 전송 방식으로 NextPDF Server를 시작하십시오. 서버는 부팅 시 Pro 계층을 발견하며, 여덟 개 도구가 오픈 소스 Core 도구와 함께 pro 계층 아래의 MCP tools/list 응답에 나타납니다. 애플리케이션에는 코드 변경이 필요하지 않습니다 — 발견이 자동으로 실행되며, 누락된 계층이 다른 계층의 로드를 막는 일은 결코 없습니다.

모든 도구의 권위 있는 입력 및 출력 스키마는 서버가 tools/list 응답에 발행하는 스키마입니다. 이 페이지가 아니라 해당 응답을 계약으로 취급하십시오. 이 카탈로그는 의도와 경계를 설명하고, 라이브 스키마는 정확한 필드 이름과 타입을 설명합니다.

코드 샘플 — 빠른 시작

Pro 도구는 Pro PHP API가 아니라 MCP 프로토콜을 통해 소비됩니다. 호스트 측 통합은 NextPDF Server를 부팅하는 것입니다. nextpdf/pro가 존재하면 여덟 개 도구가 런타임 발견을 통해 등록되며 — 도구별 배선이 없습니다 — 호스트는 이후 이를 에이전트에 제공합니다.

<?php

declare(strict_types=1);

use NextPDF\Server\Mcp\McpServer;

require __DIR__ . '/vendor/autoload.php';

// Runtime discovery registers the Pro tier when nextpdf/pro is installed
// alongside nextpdf/server. The consuming application changes no code.
$server = McpServer::create();

// A Pro tool name resolves only when the Pro package is present.
$signTool = $server->getToolRegistry()->get('sign_pdf');

\fwrite(\STDERR, $signTool !== null
    ? "Pro MCP tools active.\n"
    : "Pro MCP tools unavailable; install nextpdf/pro.\n");

// Serve the MCP protocol over stdio (Claude Desktop, Cursor, local agents).
$server->run();

코드 샘플 — 프로덕션

부팅 경로를 강화하십시오. 명시적 정책 파일을 로드하고, 잘못된 위험 수준 재정의에서 시작을 거부하며, 제공하기 전에 Pro 계층이 노출되었는지 확인하십시오. McpServer::create()의 배선은 risk_level_overrides 블록이 sign_pdf 같은 승인 필요 도구를 약화하려 할 때 InvalidArgumentException을 던지므로, 잘못 구성된 정책은 제공 루프 이전에 실패-차단됩니다.

<?php

declare(strict_types=1);

use NextPDF\Server\Mcp\McpServer;
use NextPDF\Server\Tools\ToolInterface;

require __DIR__ . '/vendor/autoload.php';

// A downgrade of an approval-required tool's HITL gate is rejected at boot,
// never silently applied — the server refuses to start on such a policy.
try {
    $server = McpServer::create(__DIR__ . '/nextpdf-mcp.yaml');
} catch (\InvalidArgumentException $e) {
    \fwrite(\STDERR, 'Refusing to start: invalid MCP policy. ' . $e->getMessage() . "\n");
    exit(1);
}

// Confirm the Pro tier surfaced before advertising it to agents.
$signTool = $server->getToolRegistry()->get('sign_pdf');

if (!$signTool instanceof ToolInterface) {
    \fwrite(\STDERR, "nextpdf/pro is not resolving; Pro MCP tools are unavailable.\n");
    exit(1);
}

// sign_pdf is approval-required; the server holds it for human confirmation.
$risk = $signTool->riskLevel()->label();
\fwrite(\STDERR, "Pro MCP tools ready. sign_pdf risk: {$risk}.\n");

$server->run();

프로덕션 지침

HITL 게이팅. sign_pdf를 사람의 확인 뒤에 두십시오. 서버는 도구가 선언한 위험 수준으로부터 이를 적용합니다. 에이전트가 이를 우회하도록 구성하지 마십시오. 운영자는 도구의 위험 수준을 강화할 수만 있고, 결코 완화할 수 없습니다.
소스 처리. 이미 세션에 있는 문서에는 document_id를 선호하십시오. 인라인 데이터의 경우 도구는 base64와 data: URI를 받습니다. 매우 큰 인라인 페이로드는 참조된 문서보다 느리게 실행됩니다.
PII 기대치. 호출자의 기대치를 명시적으로 설정하십시오. redact_pii는 정화 보장이 아니라 감지 및 마스킹 보조 도구입니다. 되돌릴 수 없는 제거에는 전용 수정(redaction) 표면으로 라우팅하십시오.
서명 키. 전송이 종단 간 기밀이 아닐 때는 전송 암호화 봉투를 통해 키를 제공하십시오. 에이전트의 도구 호출 로깅 정책에서 개인 키 자료를 비밀로 취급하십시오.
감사 로깅. safe 수준을 넘는 도구는 서버에 의해 감사 로깅됩니다. 규정 준수 요구 사항에 따라 배포 환경이 해당 로그를 보존하도록 하십시오.

엣지 케이스

extract_text 페이지 범위는 1부터 시작하며 문서의 실제 페이지 수로 클램핑됩니다. 범위를 벗어난 끝값은 오류가 아닙니다.
compare_pdfs는 두 소스를 모두 요구합니다. 하나만 전달하면 부분 diff가 아니라 명확한 검증 오류를 반환합니다.
extract_form_data는 포함된 XFDF가 없는 PDF에 대해 오류가 아니라 채워진 명시적 “포함된 폼 데이터 없음” 결과를 반환합니다.
sign_pdf는 지원되지 않는 알고리즘 식별자를 지원되는 값 목록과 함께 거부합니다. Ed25519는 libsodium 확장이 필요하고 SHA-3 변형은 SHA-3 지원이 포함된 OpenSSL 빌드가 필요합니다.
check_accessibility는 설계상 이미지 전용 PDF에 낮은 점수를 매깁니다 — 실패하는 대신 읽을 수 있는 텍스트 레이어의 부재를 표시합니다.

보안 참고

서명 도구는 유일한 승인 필요 도구입니다. 서버는 이를 자동 실행하지 않습니다.
개인 키를 감싸는 선택적 AES-GCM 봉투는 페이로드를 인증합니다. 태그 불일치는 복호화 오류로 실패-차단되며, 결코 암호문 사용으로 폴백하지 않습니다.
redact_pii는 소스 PDF를 변경하지 않습니다. 마스킹된 텍스트 표현을 반환합니다. 콘텐츠 파괴를 대체하지 않습니다.
도구는 어떤 엔진 작업 이전에 입력을 검증합니다. 잘못된 형식의 소스, 데이터 URI, base64 페이로드를 명시적 오류와 함께 거부합니다.

적합성

폼 도구는 ISO 19444-1:2019(XML Forms Data Format)에 따라 XFDF를 생성하고 소비합니다.
sign_pdf는 ETSI EN 319 142 PAdES 패밀리에 부합하는 PAdES 기준(B-B) 서명을 생성합니다. 장기 프로필은 Enterprise 기능이며, B-T는 타임스탬프 공급자가 구성된 경우 Core 엔진에서 제공됩니다.
check_accessibility는 적합성 증명이 아니라 휴리스틱 지침으로서 WCAG 성공 기준 참조(예: 1.1.1, 1.3.1, 2.4.6)와 함께 결과를 보고합니다.

에디션 경계

NextPDF Pro는 정확히 여덟 개의 MCP 도구를 기여하며, 모두 pro 계층에 있습니다. Enterprise 에디션은 enterprise 계층에 자체적인 별도의 MCP 도구 세트를 제공합니다 — 규정 준수 검사, 포렌식 분석, 장기 검증 상태, AI 준비 인증, 문서 검색 및 임베딩을 다룹니다. 그 도구들, 그 입력, 그 내부는 이 페이지의 범위 밖입니다. Enterprise MCP 도구를 참조하십시오. 서버 자체의 문서는 함께 제공되는 Core(오픈 소스) 도구를 다룹니다. 서버는 세 계층을 독립적으로 발견하며, 누락된 계층이 다른 계층을 비활성화하는 일은 결코 없습니다.

Enterprise 경계 참고

Pro는 정확히 여덟 개의 MCP 도구를 pro 계층에 기여합니다. Enterprise 에디션은 enterprise 계층에 별도의 MCP 도구 세트(규정 준수 검사, 포렌식 분석, 장기 검증 상태, AI 준비 인증, 문서 검색 및 임베딩)와 타임스탬프된/장기 서명 프로필을 제공합니다. 이는 Pro 계층에서 제공되지 않습니다. 전체 계층 분류는 위의 에디션 경계 섹션을 참조하십시오.

Core 폴백 / 대안

오픈 소스 NextPDF Server는 모든 AI 에이전트에 라이선스 없이 결정적 Core PDF 도구 세트(문서 생성, 텍스트, 표, 진단)를 제공합니다. 이 페이지의 여덟 개 고급 도구는 Pro 추가 기능입니다. /connect/tools/를 참조하십시오.

게시 경계

이 페이지는 외부에서 관찰 가능한 동작과 지원되는 공개 API 표면만 문서화합니다. 내부 네임스페이스 경로, 헬퍼 클래스, 메커니즘 표, 런북 파일 이름, 티켓 접두사는 범위 밖입니다.