NextPDF Connect — MCP-Transport

Auf einen Blick

Der MCP-Transport startet bin/nextpdf-mcp als lokalen Subprozess. Er spricht JSON-RPC 2.0 über Standardeingabe und Standardausgabe. Der Server implementiert die datumsbasierte MCP-Revision 2025-06-18.

Installation

composer require nextpdf/server

Konzeptioneller Überblick

Im stdio-Modell von MCP startet der Client den Server als Subprozess. Client und Server tauschen zeilengetrennte JSON-RPC-Nachrichten aus: eine Nachricht pro Zeile, ohne eingebettete Zeilenumbrüche, in UTF-8. Der Server schreibt ausschließlich gültige MCP-Nachrichten auf die Standardausgabe und nutzt die Standardfehlerausgabe für das Logging. Die Implementierung leitet ihren Audit-Logger deshalb gezielt auf die Standardfehlerausgabe um, damit Log-Zeilen den Protokollstrom niemals beschädigen. Dieses Framing ist in der offiziellen MCP-Spezifikation, Revision 2025-06-18, definiert. Diese Spezifikation ist nicht Teil des zugangsbeschränkten Standards-Korpus und wird daher per URL zitiert: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports.

NextPDF Connect implementiert den stdio-Transport. Die MCP-Spezifikation definiert außerdem einen Streamable-HTTP-Transport. Sie legt fest, dass Clients stdio nach Möglichkeit unterstützen sollten und ein Server auch ausschließlich stdio implementieren darf. Für den Netzwerkzugriff auf dieselben Tools verwenden Sie stattdessen den REST- oder gRPC-Transport — siehe /transports/rest/ und /transports/grpc/.

API-Oberfläche

Methoden

Methode	Verhalten
`initialize`	Gibt Protokollversion, Capabilities und Serverinfo zurück
`notifications/initialized`	Notification ohne `id`; wird ohne Antwort bestätigt
`tools/list`	Listet registrierte Tools auf; optionaler `params.category`-Filter
`tools/call`	Führt ein Tool aus, das durch `params.name` bestimmt wird, mit `params.arguments`

Jede andere Methode führt zu method-not-found (-32601). Eine Nachricht, die kein gültiges JSON-RPC 2.0 ist, führt zu invalid-request (-32600); nicht parsebare Eingaben führen zu parse-error (-32700). Bei einer doppelten Request-id wird die zwischengespeicherte vorherige Antwort aus einem Puffer mit 64 Einträgen zurückgegeben, ohne den Request erneut auszuführen.

Die initialize-Antwort

Das initialize-Ergebnis meldet protocolVersion 2025-06-18, serverInfo.name: NextPDF Connect sowie ein capabilities-Objekt. Zusätzlich zur Standard-tools-Capability ergänzt der Server einen capabilities.nextpdf-Block:

tiers — die zur Laufzeit ermittelten Zahlen registrierter Tools pro Stufe (core / pro / enterprise).
tool_count — die zur Laufzeit berechnete Gesamtzahl der registrierten Tools.
risk_model_version — die Version des vom Server durchgesetzten Risikomodells.
hitl_enabled — true; das Bestätigungs-Gate ist aktiviert.

tool_count ist für dieses Deployment maßgeblich. Es ist ein Laufzeitwert, keine dokumentierte Konstante; siehe /connect/tool-catalog/.

Codebeispiel — Schnellstart

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

Codebeispiel — Produktion

Eine nach Kategorie gefilterte Auflistung beschränkt den Katalog auf eine Domäne:

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

Die Kategoriewerte stammen aus der deklarierten Kategorie jedes Tools (zum Beispiel document, diagnostic).

Randfälle und Stolperfallen

Kein API-Schlüssel. Der stdio-Transport hat keinen Netzwerk-Listener und kein Bearer-Token. Die Vertrauensgrenze ist gemäß dem stdio-Modell von MCP die Prozessgrenze des Betriebssystems. Machen Sie ihn nicht über ein Netzwerk zugänglich.
Bestätigungs-Challenges laufen in-band. Ein ApprovalRequired-Tool gibt eine erfolgreiche JSON-RPC-Antwort zurück. Deren Inhalt besteht aus dem Challenge-Text und einem Einmal-Token, nicht aus einem Fehler. Siehe /connect/hitl-risk-tiers/.
Notifications bleiben stumm. Eine Nachricht ohne id erzeugt keine Antwort. Der Handshake besteht aus initialize (mit id), danach der initialized-Notification und anschließend Aufrufen, die eine id tragen.

Performance

Der MCP-Server läuft als einzelner Prozess und verarbeitet über Pipes eine Anfrage nach der anderen. Es gibt keinen Netzwerk-Roundtrip; die Latenz wird von der zugrunde liegenden Engine-Operation dominiert.

Sicherheitshinweise

Der Transport übernimmt das Vertrauen des startenden Clients. Halten Sie den Subprozess lokal. Hochriskante Tools bleiben durch eine menschliche Bestätigung abgesichert, auch ohne API-Schlüssel. Siehe /connect/security-and-operations/.

Konformität

Das stdio-Framing und das Verhalten von initialize/lifecycle entsprechen der offiziellen Spezifikation des Model Context Protocol, Revision 2025-06-18:

Transports: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports
Lifecycle: https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle

Die MCP-Spezifikation ist nicht im zugangsbeschränkten Standards-Korpus enthalten und trägt daher keine reference_id; die offiziellen URLs oben sind die maßgebliche Zitation.

Kommerzieller Kontext

tools/list gibt Pro- und Enterprise-Tools nur dann zurück, wenn nextpdf/premium neben dem Server installiert ist. Der Transport selbst bleibt unabhängig von den installierten Stufen identisch.

Siehe auch

/connect/quickstart/ — der ausführbare Handshake
/connect/tool-catalog/ — was tools/list zurückgibt und warum die Zahl variiert
/connect/hitl-risk-tiers/ — das Format der Bestätigungs-Challenge
/transports/rest/ · /transports/grpc/ — Netzwerkalternativen
/connect/migrating-to-multi-transport/ — eine MCP-only-Integration auf REST/gRPC umstellen