MCP — 詳細リファレンス

概要

NextPDF\Enterprise\Mcp 名前空間は、NextPDF MCP ツールカタログの Enterprise ティアを提供します。その公開サーフェスは、11 個のツールクラス、1 個のクライアントファクトリ、1 個の型付き例外です。すべてのツールは nextpdf/server ランタイムの NextPDF\Server\Tools\ToolInterface コントラクトを実装し、ToolTier::Enterprise を宣言します。6 個のツールは 1 つの PDF をインプロセスで分析します。4 個のツールは、NextPDF\Enterprise\Mcp\SpectrumClientFactory を通じてバッチおよび RAG ワークロードを Spectrum サイドカーへ委譲します。1 個のツールは 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	名前付きコンプライアンスポリシー 1 つに対して PDF を評価	検出結果、合否、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 ヘルスポリシーを実行	検出結果と合否を含む ToolResult	エラー ToolResult	ツール ltv_health_check；RiskLevel::Safe；カテゴリ document；since 2.0.0
AiReadyCertifyTool::execute	引数：document_id または source	4 つの基準に対する読み取り専用の 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）	3 つの基準を評価し、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 hex、必須）	そのドキュメントに記録されたすべての 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 を読む）	プロセス全体で 1 つのサイドカークライアントを構築・キャッシュ	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 エイリアス開発ラインに存在）

すべてのツールは、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 環境変数が制限付き入力ディレクトリを指定した場合にのみ有効になります。解決された実パスはそのディレクトリ内に留まる必要があります。それ以外はすべてフェイルクローズします。
• ストリームラッパースキーム（phar://、php://、file://、およびその他のスキーム）およびファイルパス source 内のヌルバイトは、いかなるファイルシステム呼び出しの前にも拒否されます。トラバーサルおよびシンボリックリンクエスケープは、実パス制限チェックに対して失敗します。
• サイドカー基盤ツール（embed_documents、search_documents、batch_compliance_check、batch_forensic_analyze）は、SpectrumClientFactory::create からクライアントを取得します。ファクトリは、使用前に非ローカルホストの SPECTRUM_URL をプライベートおよび予約済みアドレス範囲に対して検証します。ローカルサイドカーモードでは、明示的なローカルホストが許可されます。
• ai_ready_certify は、4 つの基準からレベルを導きます：フォレンジック整合性、署名の存在、LTV 有効性、暗号化の不在。4 つすべての合格で certified、1〜3 で partial、0 で not_certified となります。フォレンジック整合性はリビジョンチェーンに対する構造的ヒューリスティックであり、暗号的なバイト整合性検証ではありません。暗号化チェックはトレーラー領域のみを検査します。
• certify_ai_ready は 3 つの基準を評価し、XMP プロビナンススタンプを追記します。return_stamped_pdf が false の場合、またはレベルが not_certified の場合を除き、スタンプ済みバイトは base64 エンコードされて返されます。
• compliance_check は正確に 12 個のポリシーキーを受け付けます：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 は外側の配列形状のみを検証します。要素の欠陥はバッチレイヤーから表面化します。
• SpectrumClientFactory::create に不正な SPECTRUM_URL、またはプライベート、リンクローカル、メタデータアドレスを指すものを渡した場合：InvalidArgumentException。ツールの execute 内では、これはエラー結果として表面化します。
• 読み取り不可能なパスに対する SpectrumClientFactory::createStreamFromFile：McpStreamException。
• 空の環境変数は未設定として扱われ、デフォルトにフォールバックします。

適合性

NextPDF はいかなる認証も保持せず、いかなる認証も付与しません。MCP ツールは能力レベルの評価を報告します。サポートは適合性ではなく、適合性は認証ではありません。ai_ready_certify および certify_ai_ready が返す certification_level 値は、ツール自身の報告用語彙です。それらは第三者による証明を構成しません。compliance_check のレスポンスに含まれる disclaimer フィールドは、同じ理由で基盤レポートによって生成されます。製品ソースが ISO 32000-2:2020 §12.8.4.3 と述べる LTV ポリシーの根拠のようなポリシー条項参照は、ツールの説明および検出結果ごとの clause フィールドに保持されます。本ページは独立した規格上の主張を追加しません。チェック対象のドキュメントが規制を満たすかどうかは、オペレータおよびその評価者による判断です。

開発ノート

• SpectrumClientFactory::create は、プロセスごとに 1 つのクライアントをキャッシュします。新しいクライアントを強制するには、テストセットアップで SpectrumClientFactory::reset を呼び出してください。
• 環境の読み取りは $_ENV、次に $_SERVER、次に getenv を参照し、空文字列を不在として扱います。
• RiskLevel はサーバーランタイムでのホスト側の処理を駆動します：Safe は自動実行、Caution 以上は監査ログ記録、ApprovalRequired は人間による確認を要求します。Enterprise MCP ツールで ApprovalRequired を宣言するものはありません。オペレータのオーバーライドは、宣言されたレベルを引き上げることはできますが、引き下げることはできません。
• annotations の値（readOnlyHint、idempotentHint）は MCP クライアントのヒントであり、強制ではありません。制限と検証は、ヒントに関わらずサーバー側で行われます。
• ツールは、tools/list フィルタリング用に category 値 document または extraction を報告します。
• AuditAstMutationsTool は、コンストラクタ注入を必要とする唯一のツールです。具体的な AstAuditTrailInterface 実装で登録してください。

関連項目

• MCP（能力ページ）
• Accelerator — 詳細リファレンス — Spectrum サイドカークライアントサーフェス。
• Forensics — 詳細リファレンス — forensic_analyze の背後にあるアナライザ。
• Compliance — 詳細リファレンス — compliance_check の背後にあるポリシー。
• AST — 詳細リファレンス — チャンク化とミューテーション監査証跡。
• Validation — 詳細リファレンス

公開範囲

本ページは、外部から観測可能な挙動とサポートされるパブリック API サーフェスのみを文書化します。内部名前空間パス、ヘルパークラス、メカニズムテーブル、ランブックファイル名、チケットプレフィックスは対象外です。