NextPDF Connect — транспорт MCP

Коротко о главном

Транспорт Model Context Protocol (MCP) запускает bin/nextpdf-mcp как локальный подпроцесс. Он использует JSON-RPC 2.0 через стандартные ввод и вывод. Сервер реализует редакцию MCP от 2025-06-18.

Установка

composer require nextpdf/server

Концептуальный обзор

В модели stdio для протокола MCP клиент запускает сервер как подпроцесс. Клиент обменивается сообщениями JSON-RPC, разделёнными переводами строки: одно сообщение на строку, без встроенных переводов строки, в кодировке UTF-8. Сервер пишет в стандартный вывод только корректные сообщения MCP, а журналы направляет в стандартный поток ошибок. Эта реализация направляет журнал аудита в стандартный поток ошибок, поэтому строки журнала никогда не повреждают поток протокола. Такое кадрирование определяется официальной спецификацией MCP, редакция 2025-06-18. Эта спецификация не входит в контролируемый корпус стандартов, поэтому на неё ссылаются по URL: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports.

NextPDF Connect реализует транспорт stdio. Спецификация MCP также определяет транспорт Streamable HTTP. Спецификация указывает, что клиентам следует по возможности поддерживать stdio, а сервер может реализовывать только stdio. Для сетевого доступа к тем же инструментам используйте транспорт REST или gRPC; см. /transports/rest/ и /transports/grpc/.

Поверхность API

Методы

Метод	Поведение
`initialize`	Возвращает версию протокола, возможности и сведения о сервере
`notifications/initialized`	Уведомление (без `id`); принимается без ответа
`tools/list`	Перечисляет зарегистрированные инструменты; можно фильтровать по `params.category`
`tools/call`	Выполняет инструмент по `params.name`, передавая `params.arguments`

Любой другой метод возвращает ошибку “метод не найден” (-32601). Сообщение, не являющееся корректным JSON-RPC 2.0, возвращает ошибку “недопустимый запрос” (-32600); для данных, которые не удается разобрать, возвращается ошибка “ошибка разбора” (-32700). Повторный id запроса возвращает закешированный предыдущий ответ из буфера из 64 записей без повторного выполнения.

Ответ initialize

Результат initialize содержит protocolVersion 2025-06-18, serverInfo.name: NextPDF Connect и объект capabilities. Помимо стандартной возможности tools сервер добавляет блок capabilities.nextpdf:

tiers — актуальное количество зарегистрированных инструментов по уровням (core / pro / enterprise).
tool_count — общее количество зарегистрированных инструментов, вычисляемое во время выполнения.
risk_model_version — версия модели рисков, применяемая сервером.
hitl_enabled — true; барьер подтверждения человеком активен.

tool_count — достоверное число для этого развёртывания. Оно вычисляется во время выполнения и не является задокументированной константой; см. /connect/tool-catalog/.

Пример кода — быстрый старт

./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

Пример кода — рабочая среда

Фильтр по категории сужает каталог до одной области:

./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

Значения категорий берутся из объявленной категории каждого инструмента (например, document, diagnostic).

Граничные случаи и подводные камни

Нет ключа API. У транспорта stdio нет сетевого слушателя и нет bearer-токена. Считайте границу процесса в операционной системе границей доверия в соответствии с моделью stdio протокола MCP. Не выставляйте его в сеть.
Запросы на подтверждение передаются внутри канала. Инструмент ApprovalRequired возвращает успешный ответ JSON-RPC. Содержимое ответа — текст запроса и одноразовый токен, а не ошибка. См. /connect/hitl-risk-tiers/.
Уведомления не возвращают ответ. Сообщение без id не вызывает ответа. Рукопожатие: initialize (с id), затем уведомление initialized, затем вызовы с id.

Производительность

Сервер MCP работает как единый процесс и обрабатывает по одному запросу за раз через каналы. Сетевого обмена туда и обратно нет; задержка в основном зависит от операции нижележащего движка.

Замечания по безопасности

Транспорт наследует уровень доверия клиента, который его запускает. Держите подпроцесс локальным. Инструменты с высоким риском по-прежнему требуют подтверждения человеком, даже если ключа API нет. См. /connect/security-and-operations/.

Соответствие

Кадрирование stdio и поведение initialize/lifecycle соответствуют официальной спецификации Model Context Protocol, редакции 2025-06-18:

Транспорты: https://modelcontextprotocol.io/specification/2025-06-18/basic/transports
Жизненный цикл: https://modelcontextprotocol.io/specification/2025-06-18/basic/lifecycle

Спецификация MCP не входит в контролируемый корпус стандартов, поэтому у неё нет reference_id; официальные URL выше служат каноническими ссылками.

Коммерческий контекст

tools/list возвращает инструменты Pro и Enterprise только тогда, когда вместе с сервером установлен пакет nextpdf/premium. Сам транспорт одинаков независимо от установленных уровней.

См. также

/connect/quickstart/ — пример рукопожатия, который можно выполнить
/connect/tool-catalog/ — что возвращает tools/list и почему различается количество
/connect/hitl-risk-tiers/ — формат запроса на подтверждение
/transports/rest/ · /transports/grpc/ — сетевые альтернативы
/connect/migrating-to-multi-transport/ — перенос интеграции, использующей только MCP, на REST/gRPC