Enterprise 에디션

MCP — 심층 참조

한눈에 보기

NextPDF\Enterprise\Mcp 네임스페이스는 NextPDF MCP 도구 카탈로그의 Enterprise 등급을 제공합니다. 그 공개 표면은 열한 개의 도구 클래스, 하나의 클라이언트 팩토리, 하나의 타입 지정 예외입니다. 모든 도구는 nextpdf/server 런타임의 NextPDF\Server\Tools\ToolInterface 계약을 구현하며 ToolTier::Enterprise를 선언합니다. 여섯 개의 도구는 단일 PDF를 프로세스 내에서 분석합니다. 네 개의 도구는 NextPDF\Enterprise\Mcp\SpectrumClientFactory를 통해 배치 및 RAG 워크로드를 Spectrum 사이드카에 위임합니다. 한 개의 도구는 PDF 바이트 대신 생성자 주입된 AST 변형 감사 추적을 읽습니다. 각 도구는 자신의 MCP 이름, JSON Schema 입력, 클라이언트 주석, RiskLevel, 카테고리를 자체 기술합니다.

가용성 및 라이선스

이 기능은 NextPDF Enterprise(nextpdf/enterprise)에 제공되며 Enterprise 등급 라이선스 봉투로 활성화됩니다. 해당 권한이 없는 배포에서는 이 기능의 클래스가 로드되지 않습니다. 에디션 비교 및 라이선스 받기.

공개 API 표면

심볼	매개변수	기본 동작	반환	예외 또는 실패	참고
`ForensicAnalyzeTool::execute`	`array $arguments, InMemoryDocumentStore $store`; 인자: `document_id` 또는 `source`	포렌식 분석 실행: 리비전, 증분 업데이트, 서명	`ToolResult` (JSON 리포트)	오류 `ToolResult`; 예외는 포착되며 다시 던지지 않음	도구 `forensic_analyze`; `RiskLevel::Safe`; 읽기 전용, 멱등; 카테고리 `document`; since 2.0.0
`BatchForensicAnalyzeTool::execute`	인자: `workspace_token`, `documents[]` (각각 `id` + `path`)	Spectrum 사이드카를 통한 배치 포렌식 분석	문서별 `status`, 성공 및 실패 카운트를 포함한 `ToolResult`	오류 `ToolResult` (누락된 인자, 사이드카 실패)	도구 `batch_forensic_analyze`; `RiskLevel::Safe`; 카테고리 `document`; since 2.1.0
`ComplianceCheckTool::execute`	인자: `policy` (12개 값 열거형), `document_id` 또는 `source`	PDF를 하나의 명명된 컴플라이언스 정책에 대해 평가	findings, pass/fail, `duration_ms`, `disclaimer` 필드를 포함한 `ToolResult`	오류 `ToolResult`; 알 수 없는 정책은 지원되는 키를 나열하는 오류를 반환	도구 `compliance_check`; `RiskLevel::Review`; 카테고리 `document`; since 2.0.0
`BatchComplianceCheckTool::execute`	인자: `workspace_token`, `documents[]`, `policies` (`pdfa`, `pades`, `zugferd`; 기본 `["pdfa"]`)	Spectrum 사이드카를 통한 배치 컴플라이언스 검사	준수 / 비준수 카운트를 포함한 `ToolResult`	오류 `ToolResult`; 각 `documents[]` 요소는 비어 있지 않은 `id`와 `path`에 대해 검증됨	도구 `batch_compliance_check`; `RiskLevel::Safe`; 카테고리 `document`; since 2.1.0
`LtvHealthCheckTool::execute`	인자: `document_id` 또는 `source`	서명된 PDF에 대해 LTV 상태 정책 실행	findings와 pass/fail을 포함한 `ToolResult`	오류 `ToolResult`	도구 `ltv_health_check`; `RiskLevel::Safe`; 카테고리 `document`; since 2.0.0
`AiReadyCertifyTool::execute`	인자: `document_id` 또는 `source`	네 가지 기준에 대한 읽기 전용 AI 준비도 평가	`certification_level` (`certified`, `partial`, `not_certified`)과 기준별 불리언을 포함한 `ToolResult`	오류 `ToolResult`	도구 `ai_ready_certify`; `RiskLevel::Review`; 읽기 전용; 카테고리 `document`; since 2.0.0
`CertifyAiReadyTool::execute`	인자: `document_id` 또는 `source`, `return_stamped_pdf` (기본 `true`)	세 가지 기준을 평가하고 XMP 출처 스탬프를 추가	`ToolResult`; 비활성화되었거나 `not_certified`가 아닌 한 `stamped_pdf_base64` 포함	오류 `ToolResult`	도구 `certify_ai_ready`; `RiskLevel::Review`; 읽기 전용 아님; 카테고리 `document`; since 3.0.0
`AstAwareChunkTool::execute`	인자: `document_id` 또는 `source`, `max_chunk_chars` (기본 1500), `overlap_chars` (기본 150)	AST를 구축하고 출처가 포함된 인용 앵커 청크를 방출	`chunk_count`와 청크별 노드 ID, 페이지 인덱스, bbox, 노드 유형을 포함한 `ToolResult`	오류 `ToolResult`	도구 `ast_aware_chunk`; `RiskLevel::Review`; 카테고리 `extraction`; since 3.0.0
`AuditAstMutationsTool::__construct`	`AstAuditTrailInterface $auditTrail`	감사 추적 백엔드를 주입	인스턴스	—	생성자 주입 의존성; since 3.0.0
`AuditAstMutationsTool::execute`	인자: `document_source_hash` (SHA-256 16진수, 필수)	해당 문서에 대해 기록된 모든 AST 변형 이벤트를 반환	`entries[]`와 `count`를 포함한 `ToolResult`	인자가 누락되거나 비어 있을 때 오류 `ToolResult`	도구 `audit_ast_mutations`; `RiskLevel::Review`; 카테고리 `document`; since 3.0.0
`EmbedDocumentsTool::execute`	인자: `collection_id`, `workspace_token`, `documents[]` (모두 필수)	Spectrum 사이드카를 통해 PDF를 RAG 컬렉션에 수집	성공 / 전체 / 실패 카운트를 포함한 `ToolResult`	오류 `ToolResult`	도구 `embed_documents`; `RiskLevel::Caution`; 읽기 전용 아님, 멱등 아님; 카테고리 `extraction`; since 2.1.0
`SearchDocumentsTool::execute`	인자: `collection_id`, `query` (필수), `top_k` (기본 10, 1–100으로 클램프), `mode` (`hybrid`, `bm25`, `semantic`)	수집된 컬렉션에 대한 하이브리드 검색	순위가 매겨진 청크와 관련성 점수를 포함한 `ToolResult`	오류 `ToolResult`; 허용 목록 밖의 `mode`는 거부됨	도구 `search_documents`; `RiskLevel::Safe`; 카테고리 `extraction`; since 2.1.0
`SpectrumClientFactory::create`	없음 (`SPECTRUM_URL`, `SPECTRUM_TIMEOUT`, `SPECTRUM_AUTH_TOKEN`, `SPECTRUM_APP_SECRET`를 읽음)	프로세스 전역 사이드카 클라이언트 하나를 구축하고 캐시	`SpectrumClient`	`SPECTRUM_URL`이 잘못된 형식이거나 차단된 주소를 대상으로 할 때 `InvalidArgumentException`	기본 엔드포인트 `http://127.0.0.1:7800`; 타임아웃 30.0초; since 2.1.0
`SpectrumClientFactory::reset`	없음	캐시된 클라이언트 인스턴스를 지움	`void`	—	테스트용
`SpectrumClientFactory::createRequest`	`string $method, $uri` (`string` 또는 `UriInterface`)	Core HTTP 클래스로부터 PSR-7 요청을 구축	`RequestInterface`	—	PSR-17 `RequestFactoryInterface` 구현
`SpectrumClientFactory::createStream`	`string $content = ''`	인메모리 PSR-7 스트림을 구축	`StreamInterface`	—	PSR-17 `StreamFactoryInterface` 구현
`SpectrumClientFactory::createStreamFromFile`	`string $filename, string $mode = 'r'`	파일을 열고 스트림으로 래핑	`StreamInterface`	파일을 열 수 없을 때 `McpStreamException`	`McpStreamException`은 `RuntimeException`을 확장
`SpectrumClientFactory::createStreamFromResource`	`$resource` (PHP 리소스)	기존 리소스를 스트림으로 래핑	`StreamInterface`	—	PSR-17 `StreamFactoryInterface` 구현
`McpStreamException`	—	타입 지정 스트림 획득 실패	—	—	`final class`, `RuntimeException` 확장; 소스는 PSR-17 §1.5 호환성을 문서화; 소스는 `@since 3.2.0`으로 주석 처리(현재 3.1.0 별칭 dev 라인에 존재)

모든 도구는 ToolInterface 자체 기술 메서드도 노출합니다: name, description, inputSchema, annotations, riskLevel, tier, category. 도구별 값은 위 참고 열에 나타납니다.

진입점 시그니처, 소스 그대로:

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function __construct(private readonly AstAuditTrailInterface $auditTrail)
public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

public function execute(array $arguments, InMemoryDocumentStore $store): ToolResult

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

동작 계약

모든 도구는 NextPDF\Server\Tools\ToolInterface를 구현하고 ToolTier::Enterprise를 명시적으로 선언합니다. 등급은 네임스페이스나 패키징으로부터 절대 추론되지 않습니다.
execute는 예외를 던지지 않습니다. 모든 실패는 포착되어 실패 메시지를 담은 오류 ToolResult로 반환됩니다.
단일 문서 도구는 고정된 우선순위로 PDF 바이트를 해석합니다. document_id는 먼저 InMemoryDocumentStore에서 조회됩니다. 그 외의 경우 source는 data: URI로, 그다음 원시 base64(256자 초과)로, 그다음 파일 경로로 해석됩니다.
파일시스템 source 경로는 기본적으로 비활성화됩니다. NEXTPDF_MCP_INPUT_DIR 환경 변수가 제한된 입력 디렉터리를 지정할 때에만 활성화됩니다. 해석된 실제 경로는 그 디렉터리 안에 머물러야 합니다. 그 외 모든 것은 fail-closed 됩니다.
스트림 래퍼 스킴(phar://, php://, file:// 및 그 밖의 모든 스킴)과 파일 경로 source 내의 널 바이트는 어떤 파일시스템 호출 이전에 거부됩니다. 순회 및 심볼릭 링크 탈출은 실제 경로 제한 검사에 대해 실패합니다.
사이드카 기반 도구(embed_documents, search_documents, batch_compliance_check, batch_forensic_analyze)는 SpectrumClientFactory::create로부터 클라이언트를 얻습니다. 팩토리는 사용 전에 non-localhost SPECTRUM_URL을 사설 및 예약된 주소 범위에 대해 검증합니다. 명시적 localhost는 로컬 사이드카 모드에 대해 허용됩니다.
ai_ready_certify는 네 가지 기준으로부터 레벨을 도출합니다: 포렌식 무결성, 서명 존재, LTV 유효성, 암호화 부재. 네 가지 모두 통과하면 certified; 하나에서 셋 통과하면 partial; 없으면 not_certified를 산출합니다. 포렌식 무결성은 리비전 체인에 대한 구조적 휴리스틱이며 암호학적 바이트 무결성 검증이 아닙니다. 암호화 검사는 트레일러 영역만 검사합니다.
certify_ai_ready는 세 가지 기준을 평가하고 XMP 출처 스탬프를 추가합니다. 스탬프된 바이트는 return_stamped_pdf가 false이거나 레벨이 not_certified가 아닌 한 base64로 인코딩되어 반환됩니다.
compliance_check는 정확히 열두 개의 정책 키를 허용합니다: pdfa4, pdfa4e, pdfa4f, pades-baseline, ltv-health, eidas-qualified, zugferd, fda-part11, sec-17a4, sec-17a4-compatible, sec-17a4-structural, sec-17a4-pre-sign. 알 수 없는 키는 지원되는 집합을 명명하는 오류 결과를 반환합니다.
audit_ast_mutations는 주입된 AstAuditTrailInterface만 읽습니다. 자체적으로는 아무것도 기록하지 않습니다.

예외 상황 및 실패 모드

document_id도 source도 제공되지 않음: 호출자에게 둘 중 하나를 제공하라고 지시하는 오류 결과.
알 수 없는 document_id: 해당 ID를 명명하고 create_pdf를 가리키는 오류 결과.
NEXTPDF_MCP_INPUT_DIR이 설정되지 않은 상태의 파일시스템 source: 지원되는 채널을 명명하는 메시지와 함께 거부됨.
구성된 입력 디렉터리 밖으로 해석되는 source 경로(심볼릭 링크를 통한 경우 포함): 거부됨. 비교는 디렉터리 구분자 경계에서 이루어지므로, 이름 접두사를 공유하는 형제 디렉터리는 통과할 수 없습니다.
쉼표 구분자가 없는 data: URI 또는 유효하지 않은 base64 페이로드: 오류 결과.
search_documents의 top_k가 1–100 밖: 거부가 아니라 클램프됨. 정수가 아닌 top_k는 구성된 파이프라인 기본값으로 폴백됩니다.
search_documents의 mode가 hybrid, bm25, semantic 밖: 파이프라인 허용 목록으로부터의 오류 결과.
batch_compliance_check의 documents[] 요소에 id 또는 path가 누락되었거나 빈 문자열을 지님: 문제가 되는 인덱스를 명명하는 오류 결과. batch_forensic_analyze는 외부 배열 형태만 검증하며, 요소 결함은 배치 계층에서 드러납니다.
잘못된 형식의 SPECTRUM_URL 또는 사설, 링크 로컬, 메타데이터 주소를 대상으로 하는 SpectrumClientFactory::create: InvalidArgumentException. 도구 execute 내부에서 이는 오류 결과로 드러납니다.
읽을 수 없는 경로에 대한 SpectrumClientFactory::createStreamFromFile: McpStreamException.
빈 환경 변수는 설정되지 않은 것으로 취급되어 기본값으로 폴백됩니다.

적합성

NextPDF는 어떤 인증도 보유하지 않으며 어떤 인증도 부여하지 않습니다. MCP 도구는 기능 수준의 평가를 보고합니다. 지원은 적합성이 아니며, 적합성은 인증이 아닙니다. ai_ready_certify와 certify_ai_ready가 반환하는 certification_level 값은 도구 자체가 보고하는 어휘입니다. 이는 제3자 증명을 구성하지 않습니다. compliance_check 응답에는 동일한 이유로 기저 리포트가 생성한 disclaimer 필드가 포함됩니다. 제품 소스가 ISO 32000-2:2020 §12.8.4.3으로 명시하는 LTV 정책 근거와 같은 정책 조항 참조는 도구 설명과 finding별 clause 필드에 담겨 있으며, 이 페이지는 독립적인 표준 주장을 추가하지 않습니다. 검사된 문서가 규정을 충족하는지 여부는 운영자와 그 평가자가 결정할 사항입니다.

개발 노트

SpectrumClientFactory::create는 프로세스당 클라이언트 하나를 캐시합니다. 새로운 클라이언트를 강제하려면 테스트 셋업에서 SpectrumClientFactory::reset을 호출하세요.
환경 변수 읽기는 $_ENV, 그다음 $_SERVER, 그다음 getenv를 참조하며, 빈 문자열은 부재로 취급합니다.
RiskLevel은 server 런타임의 호스트 측 처리를 좌우합니다: Safe는 자동 실행되고, Caution 이상은 감사 로깅되며, ApprovalRequired는 사람의 확인을 요구합니다. 어떤 Enterprise MCP 도구도 ApprovalRequired를 선언하지 않습니다. 운영자 재정의는 선언된 레벨을 높일 수는 있어도 낮출 수는 없습니다.
annotations 값(readOnlyHint, idempotentHint)은 MCP 클라이언트 힌트이며 강제가 아닙니다. 제한과 검증은 힌트와 무관하게 서버 측에서 이루어집니다.
도구는 tools/list 필터링을 위해 category 값 document 또는 extraction을 보고합니다.
AuditAstMutationsTool은 생성자 주입을 요구하는 유일한 도구입니다. 구체적인 AstAuditTrailInterface 구현과 함께 등록하세요.

게시 범위

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