Enterprise 에디션

MCP 도구

한눈에 보기

NextPDF Enterprise는 NextPDF Connect 서버에 열한 개의 MCP 도구를 추가합니다. 이 도구들은 AI 어시스턴트와 에이전트 프레임워크에 Enterprise 엔진에 대한 직접적이고 타입이 지정된 접근을 제공합니다: 컴플라이언스 정책 검사, PDF 포렌식, LTV 상태 점검, AI 준비도 스탬핑, AST 인식 청킹, RAG 수집 및 검색. 모든 도구는 자체 위험 수준과 읽기 전용 태세를 선언하므로, MCP 호스트는 에이전트 활동을 자신 있게 게이팅하고 로깅하고 감사할 수 있습니다. 실패는 결코 예외로 표출되지 않으며, 에이전트는 항상 구조화되어 파싱 가능한 결과를 받습니다.

사용 가능 여부 및 라이선스

이 기능은 NextPDF Enterprise(nextpdf/enterprise)에 포함되며 Enterprise 등급 라이선스 봉투로 활성화됩니다. 해당 엔타이틀먼트가 없는 배포는 이 기능의 클래스를 로드하지 않습니다. 에디션 비교 및 라이선스 받기.

설치

composer require nextpdf/enterprise:^3

MCP 호스트 자체는 nextpdf/server 패키지로 제공되는 NextPDF Connect입니다. Connect 설치를 참조하세요. 두 패키지가 모두 존재하면 서버의 도구 레지스트리가 NextPDF\Enterprise\McpToolProvider를 자동으로 발견하고 열한 개의 Enterprise 도구를 등록합니다. 연결 코드는 필요하지 않습니다. nextpdf/server가 없으면 프로바이더 파일이 조기에 반환되어 아무것도 로드되지 않습니다.

batch 및 RAG 도구는 추가로 Spectrum 사이드카가 필요합니다. NextPDF\Enterprise\Mcp\SpectrumClientFactory가 읽는 환경 변수를 통해 구성하세요: SPECTRUM_URL(기본값 http://127.0.0.1:7800), SPECTRUM_TIMEOUT(기본값 30.0초), SPECTRUM_AUTH_TOKEN, SPECTRUM_APP_SECRET.

개념 개요

Model Context Protocol(MCP)은 AI 어시스턴트와 에이전트 프레임워크가 서버에서 노출한 타입이 지정된 도구를 호출할 수 있게 하는 개방형 프로토콜입니다. PDF 바이트를 프롬프트에 붙여넣고 요행을 바라는 대신, 에이전트는 JSON 스키마로 검증된 페이로드로 명명된 도구를 호출하고 결정론적이고 구조화된 결과를 받습니다. NextPDF Connect가 PDF를 위한 그 서버이며, Enterprise 패키지는 아래 도구들로 그 카탈로그를 확장합니다. 각 도구는 여러분의 PHP 코드가 직접 호출하는 동일한 Enterprise API에 대한 얇은 래퍼이므로, 에이전트가 실행한 검사와 코드가 실행한 검사는 동일한 판정을 생성합니다.

도구 카탈로그

MCP 도구	클래스	하는 일	위험	읽기 전용
`compliance_check`	`ComplianceCheckTool`	하나의 PDF를 명명된 정책에 대해 검증합니다: `pdfa4`, `pdfa4e`, `pdfa4f`, `pades-baseline`, `ltv-health`, `eidas-qualified`, `zugferd`, `fda-part11`, 그리고 네 개의 `sec-17a4` 변형.	Review	예
`batch_compliance_check`	`BatchComplianceCheckTool`	하나의 Spectrum 사이드카 배치로 여러 PDF를 `pdfa`, `pades`, 또는 `zugferd` 정책에 대해 검사합니다.	Safe	예
`forensic_analyze`	`ForensicAnalyzeTool`	변조 탐지를 위해 개정 이력, 증분 업데이트, 수정 이벤트를 보고합니다.	Safe	예
`batch_forensic_analyze`	`BatchForensicAnalyzeTool`	하나의 사이드카 배치로 여러 PDF에 대해 포렌식 분석을 실행합니다.	Safe	예
`ltv_health_check`	`LtvHealthCheckTool`	서명된 PDF에서 장기 검증 자료를 검사합니다: DSS 딕셔너리, OCSP 응답, CRL 항목, VRI 항목, 인증서 저장소.	Safe	예
`ai_ready_certify`	`AiReadyCertifyTool`	네 가지 기준에 대한 읽기 전용 제품 정의 AI 준비도 판정: 포렌식 무결성, 서명 존재, LTV 유효성, 암호화 없음.	Review	예
`certify_ai_ready`	`CertifyAiReadyTool`	세 가지 기준에 대한 제품 정의 준비도 판정(읽기 전용 도구의 네 가지에서 포렌식 무결성을 뺀 것 - 이 도구는 스탬핑하는 파일을 다시 쓰므로 설계상 그렇습니다)을 내리고 XMP 출처 스탬프를 추가합니다. 스탬핑된 PDF를 base64로 반환합니다.	Review	아니요
`ast_aware_chunk`	`AstAwareChunkTool`	청크마다 노드 ID, 페이지 인덱스, 경계 상자를 포함하여 제목 경계를 따라 PDF를 인용 앵커 청크로 분할합니다.	Review	예
`audit_ast_mutations`	`AuditAstMutationsTool`	SHA-256 소스 해시로 문서의 AST 변형 감사 추적을 조회합니다.	Review	예
`embed_documents`	`EmbedDocumentsTool`	PDF를 RAG 컬렉션에 수집합니다: 파싱, 청킹, 임베딩, 인덱싱. 컬렉션 상태를 수정합니다.	Caution	아니요
`search_documents`	`SearchDocumentsTool`	수집된 컬렉션에 대한 하이브리드 검색(BM25 키워드 + 시맨틱)으로, 순위가 매겨지고 점수가 부여된 청크를 반환합니다.	Safe	예

“certify” 도구는 제품 정의 준비도 판정(certified, partial, 또는 not_certified)을 발급합니다. 그 판정은 기술적 검사 결과이지, 어떤 인증 기관에 의한 인증이 아닙니다.

승인 게이팅 및 감사 태세

모든 도구는 4단계 Connect 모델에서 위험 수준을 선언합니다. Safe 도구는 자동 실행됩니다. Caution 도구는 감사 로그 항목과 함께 자동 실행됩니다. Review 도구는 호출하는 에이전트의 지침에 경고를 실어줍니다. ApprovalRequired 도구는 사람의 확인을 요구합니다. 현재 어떤 Enterprise MCP 도구도 이 수준을 선언하지 않는데, 파괴적인 것이 없기 때문입니다. 런타임 구성은 도구의 위험 수준을 올릴 수만 있고 결코 낮출 수 없습니다. 도구는 또한 MCP 동작 어노테이션(readOnlyHint, idempotentHint)을 게시하므로, 규격을 준수하는 클라이언트는 그 위에 자체 게이팅을 적용할 수 있습니다. 전체 모델은 HITL 위험 등급을 참조하세요.

이렇게 작동하는 이유

핵심을 지탱하는 결정은 도구가 자체 선언 거버넌스를 갖춘 얇고 결정론적인 래퍼라는 점입니다: 각 도구는 자체 위험 수준과 등급을 도메인 불변식으로 진술하며, 네임스페이스나 패키징에서 추론하지 않습니다. 이는 전송 계층을 신뢰하지 않고도 게이팅 결정을 호스트에서 감사 가능하게 유지합니다. 도구는 자체적인 문서 지능을 담지 않고, 여러분의 코드가 호출하는 동일한 Enterprise API에 위임하므로, 테스트할 동작은 정확히 하나이고 신뢰할 판정도 하나입니다. 오류는 예외로 탈출하는 대신 MCP 오류 채널로 반환되는데, 에이전트는 PHP 예외를 잡을 수 없지만 isError로는 항상 분기할 수 있기 때문입니다. 파일 시스템에 닿을 수 있는 입력은 기본적으로 페일클로즈드인데, MCP 인자는 정의상 공격자가 도달할 수 있기 때문입니다.

설계 배경: 추측을 거부하는 API.

API 표면

열한 개의 도구 모두 nextpdf/server의 NextPDF\Server\Tools\ToolInterface 계약을 구현하며 동일한 공개 표면을 공유합니다. 아래 시그니처는 대표로 NextPDF\Enterprise\Mcp\ComplianceCheckTool에서 한 번 보여줍니다:

public function name(): string
public function description(): string
public function inputSchema(): array
public function annotations(): array
public function riskLevel(): RiskLevel
public function tier(): ToolTier
public function category(): string
public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

던지거나 실패하는 경우: execute()는 결코 던지지 않습니다. 내부적으로 Throwable을 잡아 isError = true인 ToolResult::error()를 반환합니다. 잘못된 인자(누락된 workspace_token, 형식이 잘못된 documents 항목, 알 수 없는 document_id, 안전하지 않은 source)는 그 오류 채널에서 InvalidArgumentException 메시지로 표출됩니다.

감사 추적 도구는 저장소 백엔드를 생성자 주입으로 받습니다:

public function __construct(private readonly AstAuditTrailInterface $auditTrail)

카탈로그를 등록하는 프로바이더:

public function getTier(): string
public function getTools(): array

getTier()는 'enterprise'를 반환합니다. getTools()는 열한 개의 도구 인스턴스를 반환하며, audit_ast_mutations는 기본적으로 NextPDF\Enterprise\Ast\InMemoryAstAuditTrail로 연결됩니다.

PSR-17 요청 및 스트림 팩토리이기도 한 Spectrum 사이드카 클라이언트 팩토리:

public static function create(): SpectrumClient
public static function reset(): void
public function createRequest(string $method, $uri): RequestInterface
public function createStream(string $content = ''): StreamInterface
public function createStreamFromFile(string $filename, string $mode = 'r'): StreamInterface
public function createStreamFromResource($resource): StreamInterface

던지거나 실패하는 경우: create()는 SPECTRUM_URL이 형식에 맞지 않거나 구성된 엔드포인트가 알려진 사설 또는 예약 주소(localhost 제외)를 대상으로 할 때 InvalidArgumentException을 던집니다. 이는 구성 시점의 게이트이지 네트워크 계층 제어가 아닙니다: 호스트 환경에서 이그레스 정책, 리다이렉트 처리, DNS 피닝을 여전히 시행하세요. createStreamFromFile()은 파일을 열 수 없을 때 NextPDF\Enterprise\Mcp\McpStreamException(PSR-17 계약에 따른 RuntimeException 서브클래스)을 던집니다.

코드 샘플 — 빠른 시작

인메모리 data: URI 채널을 사용하여 에이전트가 하는 것과 똑같이 PDF/A-4 컴플라이언스 검사를 실행합니다:

<?php

declare(strict_types=1);

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

use NextPDF\Enterprise\Mcp\ComplianceCheckTool;
use NextPDF\Enterprise\Mcp\McpStreamException;
use NextPDF\Enterprise\Mcp\SpectrumClientFactory;
use NextPDF\Server\Document\InMemoryDocumentStore;

$streams = new SpectrumClientFactory(); // PSR-17 stream factory from this module

try {
    $pdfBytes = (string) $streams->createStreamFromFile(__DIR__ . '/invoice.pdf');
} catch (McpStreamException $e) {
    fwrite(STDERR, 'Cannot read PDF: ' . $e->getMessage() . PHP_EOL);
    exit(1);
}

$tool   = new ComplianceCheckTool();
$result = $tool->execute(
    [
        'source' => 'data:application/pdf;base64,' . base64_encode($pdfBytes),
        'policy' => 'pdfa4',
    ],
    new InMemoryDocumentStore(),
);

// Tool failures arrive on the MCP error channel, never as exceptions.
if ($result->isError) {
    fwrite(STDERR, $result->content[0]['text'] . PHP_EOL);
    exit(1);
}

echo $result->content[0]['text'] . PHP_EOL;

적합한 파일에 대한 예상 출력 (발견 개수는 문서마다 다릅니다):

Compliance check (PDF/A-4): PASS — 0 finding(s)

발견별 심각도, 규칙 ID, 절, 제안을 포함한 전체 기계 판독 가능 보고서는 $result->structured에서 이용할 수 있습니다.

코드 샘플 — 프로덕션

사이드카를 프리플라이트하고, 선언된 위험 태세를 시행한 다음, 배치 컴플라이언스 검사를 실행합니다:

<?php

declare(strict_types=1);

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

use NextPDF\Enterprise\Mcp\BatchComplianceCheckTool;
use NextPDF\Enterprise\Mcp\SpectrumClientFactory;
use NextPDF\Server\Document\InMemoryDocumentStore;

// 1. Fail fast on sidecar misconfiguration before accepting agent traffic.
//    The factory validates SPECTRUM_URL and rejects private/reserved targets.
try {
    SpectrumClientFactory::create();
} catch (InvalidArgumentException $e) {
    fwrite(STDERR, 'Spectrum sidecar rejected: ' . $e->getMessage() . PHP_EOL);
    exit(1);
}

$tool = new BatchComplianceCheckTool();
$risk = $tool->riskLevel();

// 2. Enforce the declared risk posture before execution.
if ($risk->requiresHumanConfirmation()) {
    // Route to your approval queue instead of executing.
    exit(0);
}

if ($risk->requiresAuditLog()) {
    error_log(sprintf('[mcp-audit] tool=%s risk=%s', $tool->name(), $risk->label()));
}

// 3. Execute the batch.
$result = $tool->execute(
    [
        'workspace_token' => (string) getenv('SPECTRUM_WORKSPACE_TOKEN'),
        'documents'       => [
            ['id' => 'contract-001', 'path' => '/var/pdf-inbox/contract-001.pdf'],
            ['id' => 'contract-002', 'path' => '/var/pdf-inbox/contract-002.pdf'],
        ],
        'policies'        => ['pdfa', 'pades'],
    ],
    new InMemoryDocumentStore(),
);

echo $result->content[0]['text'] . PHP_EOL;

예상 출력 (개수는 여러분의 문서를 반영합니다):

Batch compliance check complete: 1 compliant, 1 non-compliant

엣지 케이스 및 함정

파일 시스템 source 경로는 기본적으로 비활성화됩니다. NEXTPDF_MCP_INPUT_DIR 환경 변수가 없으면 경로 형태의 source는 오류 결과로 거부됩니다. 대신 document_id, data: URI, 또는 원시 base64를 사용하세요.
원시 base64는 256자를 초과할 때만 인식됩니다. 더 짧은 base64 블롭은 파일 경로로 취급되어 거부됩니다. 작은 페이로드는 data:application/pdf;base64, URI로 감싸세요.
알 수 없는 document_id 값은 안내와 함께 실패합니다. 오류 텍스트는 Unknown document_id: ... Call create_pdf first.입니다. 인메모리 저장소의 문서도 저장소의 TTL에 따라 만료되므로, 오래된 ID도 같은 방식으로 실패합니다.
compliance_check는 알 수 없는 정책 키를 거부하고 오류 메시지에 지원되는 집합을 나열합니다.
batch 및 RAG 도구는 사이드카가 필요합니다. batch_compliance_check, batch_forensic_analyze, embed_documents, search_documents는 도달 가능한 Spectrum 엔드포인트와 workspace_token이 필요합니다. 팩토리는 프로세스당 하나의 클라이언트를 캐시합니다. 테스트에서는 SpectrumClientFactory::reset()을 호출하세요.
search_documents는 top_k를 1–100으로 클램프합니다. 정수가 아닌 값은 서버 기본값 10으로 폴백됩니다.
ast_aware_chunk 기본값은 청크당 1500자에 150자 겹침입니다.
certify_ai_ready는 return_stamped_pdf가 false이거나 판정이 not_certified일 때 스탬핑된 바이트를 생략합니다. 존재할 경우, base64 페이로드는 PDF 자체보다 약 3분의 1 더 큽니다.
기본 AST 감사 추적은 인메모리입니다. 기본 프로바이더 연결을 통해 기록된 항목은 프로세스 간에 지속되지 않습니다. 내구성 있는 감사 추적을 위해서는 지속적인 AstAuditTrailInterface 구현을 주입하세요.

보안 참고

페일클로즈드 소스 해석. MCP 호출자는 도구 인자를 완전히 제어하므로, 리졸버는 이를 적대적인 것으로 취급합니다. 스트림 래퍼(phar://, php://, file://, 그리고 모든 스킴)와 널 바이트는 어떤 파일 시스템 호출보다 먼저 거부됩니다. 경로 순회는 거부됩니다. 원시 파일 경로는 NEXTPDF_MCP_INPUT_DIR이 설정된 경우에만 작동하며, realpath로 정규화된 대상은 접두사 혼동 탈출을 차단하기 위해 구분자 경계에서 비교되어 반드시 그 디렉터리 안에 엄격히 해석되어야 합니다.
사이드카 엔드포인트의 SSRF 가드. SpectrumClientFactory는 로컬 사이드카 모드를 위해 localhost를 허용하고, 다른 모든 SPECTRUM_URL을 사설, 예약, 링크 로컬, 클라우드 메타데이터 범위에 대해 검증하여, 차단된 주소에서 InvalidArgumentException을 던집니다. 이는 구성된 엔드포인트에 대한 구성 시점의 게이트이지 네트워크 계층 제어가 아닙니다 - 호스트 환경에서 이그레스 정책, 리다이렉트 처리, DNS 피닝을 유지하세요.
비밀은 환경에 머뭅니다. 사이드카 베어러 토큰(SPECTRUM_AUTH_TOKEN)과 HMAC 서명 비밀(SPECTRUM_APP_SECRET)은 환경 변수에서 읽히며 도구 페이로드나 결과에 결코 나타나지 않습니다.
비반영 오류. 경로 거부 메시지는 설계상 일반적이므로(Source path is not permitted.), 탐침하는 호출자는 호스트 파일 시스템에 대해 아무것도 알 수 없습니다.
위험 재정의는 오직 위로만 갑니다. 운영자 구성은 도구의 선언된 위험 수준을 올릴 수 있지만 도구 자체의 선언 아래로는 결코 낮출 수 없습니다.

적합성

지원은 적합성이 아니며, 적합성은 인증이 아닙니다. NextPDF는 어떤 인증도 보유하지 않으며 어떤 인증도 부여하지 않습니다. 컴플라이언스 도구는 명명된 정책 프로파일에 대해 문서 구조를 검사하고 절 참조와 함께 발견을 보고합니다. compliance_check 보고서는 추가로 그것이 참고용 기술적 구조 검사이며 법률 자문이나 컴플라이언스 보증이 아니라는 엔진 자체의 면책 조항을 실어줍니다. ai_ready_certify와 certify_ai_ready 판정은 제품 정의 준비도 수준이지 어떤 표준 기구에 의한 증명이 아닙니다. MCP는 그 벤더 스튜어드가 게시한 개방형 프로토콜이지 SDO 표준이 아닙니다. 이 페이지는 NextPDF의 구현 동작을 문서화하며 독립적인 프로토콜 적합성이나 인증 주장을 하지 않습니다.

동작 계약

도구 실패는 오류 결과(isError = true와 메시지)로 반환됩니다. 예외는 MCP 경계를 결코 넘지 않습니다.
성공 결과는 한 줄의 사람 판독 가능 요약과 도구별로 안정적이고 문서화된 필드 집합을 갖춘 구조화된 JSON 페이로드를 실어줍니다.
모든 도구는 tier() = ToolTier::Enterprise와 선언된 RiskLevel을 보고합니다. 위험은 런타임에 낮출 수 없습니다.
읽기 전용 도구는 readOnlyHint: true를 선언하며 문서 저장소, 소스 PDF, 또는 어떤 컬렉션도 수정하지 않습니다.
certify_ai_ready는 입력 문서를 제자리에서 결코 변경하지 않습니다. 스탬프는 반환된 복사본에 적용됩니다.
컴플라이언스 및 LTV 보고서는 검증 타임스탬프와 심각도별 발견 개수를 포함합니다. compliance_check 페이로드는 추가로 엔진의 법적 면책 조항 문자열을 포함합니다.

Core 폴백

MCP 호스트 자체는 Enterprise를 요구하지 않습니다. NextPDF Connect(nextpdf/server, Apache-2.0)는 개방형 Core 엔진으로 실행되며 core 등급 도구 카탈로그를 제공합니다: 문서 생성, 텍스트 및 콘텐츠 작업, 추출. 도구 카탈로그를 참조하세요. Core만으로는 컴플라이언스 정책 검사, 포렌식 분석, LTV 상태 점검, AI 준비도 스탬핑, AST 인식 청킹, 변형 감사 추적, 또는 batch 및 RAG 도구를 제공하지 않습니다. 그 열한 개의 도구는 nextpdf/enterprise가 설치되고 라이선스된 경우에만 등록됩니다.

공개 경계

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