GraphQL

1. Роль протокола в проекте

GraphQL поддерживается как отдельный тип интеграции, но на слое MCP намеренно ограничивается. Цель платформы не в том, чтобы дать LLM универсальный доступ ко всему GraphQL endpoint, а в том, чтобы превратить конкретный GraphQL-запрос в узкий и предсказуемый MCP tool.

2. Что поддерживается в MVP

query
mutation
один GraphQL endpoint на operation
фиксированный query_template
фиксированный selection set
загрузка примера выходного JSON
схема переменных
variables mapping
response extraction из data
разбор errors
auth и headers
автогенерация чернового mapping
ручная донастройка через JSONPath
тестовый вызов перед публикацией

3. Что не входит в MVP

subscription
универсальный GraphQL explorer для LLM
передача произвольного GraphQL-документа от LLM
визуальный конструктор сложных selection set
обязательная зависимость от introspection
автоматическое построение любого запроса по полной GraphQL schema

subscription допускается только как future scope после появления отдельного websocket/subscription adapter и controlled streaming lifecycle.

4. Ключевое архитектурное ограничение

Платформа не должна публиковать в MCP общий GraphQL tool, который умеет получать любые поля и принимать любые параметры в зависимости от намерения LLM.

Правильная модель только одна:

один tool;
один конкретный query или mutation;
один заранее зафиксированный selection set;
фиксированный набор входных параметров;
один предсказуемый формат ответа.

Иными словами, на MCP-слое GraphQL сознательно сужается до модели, близкой к RPC или REST operation. Это делается потому, что LLM должен работать с понятным контрактом, а не конструировать произвольный GraphQL-запрос на лету.

5. Внутренняя модель GraphQL operation

GraphQL operation должна включать:

endpoint
operation_type
operation_name
query_template
variables_schema
input_mapping
response_path
error_policy
headers
auth_profile

6. Как оператор настраивает GraphQL operation

Указывает GraphQL endpoint.
Выбирает query или mutation.
Задает имя операции.
Вставляет готовый шаблон запроса.
Описывает переменные, которые разрешено передавать в эту операцию.
При необходимости загружает пример JSON-ответа.
Система строит черновую схему ответа и стартовый mapping.
Настраивает маппинг MCP input -> GraphQL variables.
Указывает response_path, по которому извлекается полезный результат из data.
При необходимости уточняет mapping через JSONPath.
Выполняет тест.
Публикует operation как MCP tool.

7. Поведение runtime

При выполнении GraphQL operation runtime должен:

Валидировать вход по фиксированной схеме переменных.
Применить input mapping.
Собрать GraphQL payload вида query + variables.
Выполнить HTTP request.
Отдельно разобрать data и errors.
Применить output mapping или response_path.
Вернуть нормализованный результат.

8. Критические нюансы

HTTP 200 OK не означает успешное выполнение, если в теле присутствует errors.
структура ответа зависит от selection set, значит она должна быть фиксирована заранее;
GraphQL endpoint обычно один, поэтому операция определяется не URL, а телом запроса;
variables должны быть строго ограничены, иначе один tool станет слишком широким и плохо управляемым;
subscription не входит в текущий scope, потому что требует отдельной lifecycle-модели, близкой к session mode, и отдельного transport adapter.
JSONPath используется для точечного извлечения вложенных данных из data и для управления структурой итогового ответа.

9. Почему GraphQL не считается "почти REST"

GraphQL похож на REST только тем, что часто передается по HTTP. Но с точки зрения платформы это другой тип контракта:

смысл операции задается не endpoint, а запросом;
ответ зависит от selection set;
ошибки живут в теле ответа, а не только в HTTP status;
одна и та же точка входа может обслуживать много операций.

Поэтому GraphQL в системе должен иметь отдельный адаптер и отдельную конфигурационную модель.

6.3 KiB Raw Blame History Unescape Escape