Загрузка и обнаружение в NextPDF Connect

Кратко

У каждого транспорта есть своя точка входа и последовательность загрузки. Транспорты совместно используют реестр, конфигурацию и шлюз как концепции. Они работают как независимые процессы, поэтому запуск одного транспорта не запускает остальные.

Установка

composer require nextpdf/server

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

Последовательность загрузки MCP

McpServer::create() собирает сервер Model Context Protocol (MCP) в фиксированном порядке. Сначала он загружает конфигурацию, на её основе строит политику безопасности, создаёт реестр инструментов и выполняет обнаружение уровней. Затем создаёт хранилище документов в памяти с учётом заданных срока жизни (TTL) и ёмкости, создаёт транспорт stdio и собирает обработчик протокола JSON-RPC со шлюзом подтверждения и журналом аудита. После этого сервер входит в цикл «чтение — обработка — запись» и работает, пока стандартный ввод не достигнет конца файла.

Последовательность загрузки REST

HttpServer::create() читает HttpConfig из окружения и применяет переопределения интерфейса командной строки (CLI). Затем он выбирает хранилище ключей API в следующем порядке предпочтения: сначала файловое хранилище с горячей перезагрузкой, затем статический файл, затем окружение. Далее он выбирает хранилища для ограничения частоты запросов и идемпотентности. Они используют Redis, когда Redis настроен и доступен, а в противном случае переключаются на хранение в памяти. Затем сервер открывает общее хранилище заданий SQLite, создаёт службы приложения и формирует таблицу маршрутов. Поскольку таблица маршрутов строится на основе обнаруженных уровней, она отражает установленные пакеты. После этого RoadRunner управляет циклом обработки запросов рабочими процессами.

Последовательность загрузки gRPC

GrpcServer::create() использует то же хранилище ключей, создаёт те же службы приложения и регистрирует службу nextpdf.connect.v1 в рабочем процессе gRPC Spiral. Если зависимость от движка недоступна, сервер gRPC всё равно запускается и обслуживает запросы состояния и возможностей. В этом состоянии процесс не отказывается загружаться; вместо этого удалённые вызовы процедур (RPC), передающие данные, завершаются корректной ошибкой.

Обнаружение инструментов

Обнаружение — это этап заполнения реестра по умолчанию. Первым регистрируется уровень core. Затем регистрируются провайдеры Pro и Enterprise, если их классы доступны через class_exists(). Затем встроенные провайдеры абстрактного синтаксического дерева (AST) и мутаций регистрируются на уровне Pro, если они проходят свои шлюзы окружения. Каждая регистрация проходит через фильтр списка разрешений безопасности enabled_tools, а ответ MCP initialize сообщает итоговое количество по каждому уровню. См. /connect/tool-catalog/.

Обнаружение транспортов

Нет отдельного параметра конфигурации, который “включает транспорты”. Каждый транспорт — это отдельная точка входа. У REST и gRPC есть отдельные профили RoadRunner. Развёртывание выбирает транспорты по запускаемому профилю: .rr.yaml для REST, .rr.grpc.yaml для gRPC или .rr.full.yaml для обоих. Транспорты работают как независимые процессы. Отсутствие клиента MCP никогда не блокирует сервер REST, а отсутствие клиента REST никогда не блокирует MCP. См. /connect/deployment/.

Порядок разрешения конфигурации

Сервер MCP разрешает конфигурацию в следующем порядке приоритета: окружение (NEXTPDF_MCP_*) имеет приоритет над секцией nextpdf_mcp файла YAML, а она — над встроенными значениями по умолчанию. Серверы REST и gRPC строят HttpConfig из переменных окружения NEXTPDF_*, используя безопасные значения по умолчанию. Они не читают файл YAML MCP. См. /connect/configuration/.

Привязки контейнера

Здесь нет ни контейнера внедрения зависимостей, ни поставщика служб, которые нужно регистрировать. Каждая фабрика create() строит свой граф объектов явно и детерминированно. Есть две точки внедрения: транспорт и фабрика рабочих процессов. Обе предназначены для тестирования, а не для сборки приложения.

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

Проверьте результаты обнаружения без обработки трафика:

./vendor/bin/generate-skills --dry-run --list-tools

Пример кода — продакшен

Запустите объединённые транспорты под управлением одного супервизора:

export NEXTPDF_API_KEYS_FILE=/run/secrets/api-keys
./vendor/bin/rr serve -c .rr.full.yaml

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

• Отсутствующий уровень не приводит к сбою загрузки. Обнаружение уровней без ошибок пропускает отсутствующий пакет Pro или Enterprise. Сервер загружается с каталогом уровня core.

• Переопределение, понижающее уровень, приводит к сбою загрузки. Запись risk_level_overrides, которая ослабляет инструмент approval_required, вызывает исключение при загрузке конфигурации; сервер отказывается запускаться. Это сделано намеренно.

• Сбой Redis приводит к деградации, а не к аварийному завершению. Если Redis настроен, но недоступен при загрузке, сервер REST переключается на хранилища в памяти. Проверяйте состояние Redis, а не предполагайте, что Redis используется.

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

Затраты на загрузку складываются из разбора конфигурации, сканирования реестра и определения уровней. Параметр страницы performance_budget ограничивает эти затраты. Они возникают один раз при запуске процесса, а не на каждый запрос.

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

Политика безопасности строится до создания реестра, поэтому список разрешений enabled_tools ограничивает обнаружение начиная с первой регистрации. Ключи API никогда не читаются из файла YAML MCP; сетевые транспорты получают ключи из файла секрета или из окружения. См. /connect/security-and-operations/.

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

Эта страница описывает механику загрузки. Ссылки на протокол и безопасность приведены на /transports/mcp/, /transports/rest/, /transports/grpc/ и /connect/security-and-operations/.

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

Определение уровней при загрузке — единственная точка, в которой nextpdf/premium добавляет свои инструменты Pro и Enterprise в каталог, когда nextpdf/premium установлен вместе с сервером.

См. также

• /connect/tool-catalog/ — что регистрирует обнаружение и почему количество различается
• /connect/configuration/ — подробный порядок разрешения
• /connect/deployment/ — выбор транспортов через профили RoadRunner
• /transports/mcp/ · /transports/rest/ · /transports/grpc/ — подробности по каждому транспорту