a.tolmachev
110 lines
6.3 KiB
Markdown
110 lines
6.3 KiB
Markdown
# GraphQL
|
||
|
||
## 1. Роль протокола в проекте
|
||
|
||
GraphQL поддерживается как отдельный тип интеграции, но на слое MCP намеренно ограничивается. Цель платформы не в том, чтобы дать LLM универсальный доступ ко всему GraphQL endpoint, а в том, чтобы превратить конкретный GraphQL-запрос в узкий и предсказуемый MCP tool.
|
||
|
||
## 2. Что поддерживается в целевом продукте
|
||
|
||
- `query`
|
||
- `mutation`
|
||
- один GraphQL endpoint на operation
|
||
- фиксированный `query_template`
|
||
- фиксированный `selection set`
|
||
- загрузка примера выходного `JSON`
|
||
- схема переменных
|
||
- variables mapping
|
||
- response extraction из `data`
|
||
- разбор `errors`
|
||
- auth и headers
|
||
- автогенерация чернового mapping
|
||
- ручная донастройка через `JSONPath`
|
||
- тестовый вызов перед публикацией
|
||
|
||
## 3. Что отложено
|
||
|
||
- `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
|
||
|
||
1. Указывает GraphQL endpoint.
|
||
2. Выбирает `query` или `mutation`.
|
||
3. Задает имя операции.
|
||
4. Вставляет готовый шаблон запроса.
|
||
5. Описывает переменные, которые разрешено передавать в эту операцию.
|
||
6. При необходимости загружает пример JSON-ответа.
|
||
7. Система строит черновую схему ответа и стартовый mapping.
|
||
8. Настраивает маппинг `MCP input -> GraphQL variables`.
|
||
9. Указывает `response_path`, по которому извлекается полезный результат из `data`.
|
||
10. При необходимости уточняет mapping через `JSONPath`.
|
||
11. Выполняет тест.
|
||
12. Публикует operation как MCP tool.
|
||
|
||
## 7. Поведение runtime
|
||
|
||
При выполнении GraphQL operation runtime должен:
|
||
|
||
1. Валидировать вход по фиксированной схеме переменных.
|
||
2. Применить input mapping.
|
||
3. Собрать GraphQL payload вида `query + variables`.
|
||
4. Выполнить HTTP request.
|
||
5. Отдельно разобрать `data` и `errors`.
|
||
6. Применить output mapping или `response_path`.
|
||
7. Вернуть нормализованный результат.
|
||
|
||
## 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 в системе должен иметь отдельный адаптер и отдельную конфигурационную модель.
|