chore: publish clean community baseline

docs/protocols/rest.md

@@ -0,0 +1,112 @@
+# REST
+
+## 1. Роль протокола в проекте
+
+REST - базовый и первый по очередности реализации протокол платформы. На нем должна быть обкатана общая модель `Operation`, схема входа и выхода, маппинг, тестовый запуск и публикация MCP tool.
+
+## 2. Что поддерживается в целевом продукте
+
+- HTTP methods: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`
+- загрузка примера входного `JSON`
+- загрузка примера выходного `JSON`
+- path parameters
+- query parameters
+- headers
+- JSON request body
+- JSON response body
+- auth: `Bearer`, `Basic`, API key
+- timeout и базовые transport settings
+- request mapping
+- response mapping
+- автогенерация чернового mapping
+- ручная донастройка через `JSONPath`
+- тестовый вызов перед публикацией
+
+## 3. Что отложено
+
+- multipart/form-data
+- file upload/download как отдельный сценарий
+- XML payload как основной формат
+- OpenAPI import с автоматическим созданием mappings
+- webhooks
+- long polling как специальный режим
+- `HEAD` и `OPTIONS` как отдельные пользовательские сценарии
+
+## 4. Внутренняя модель REST operation
+
+REST operation в системе описывается следующими основными частями:
+
+- `base_url`
+- `method`
+- `path_template`
+- `headers`
+- `auth_profile`
+- `input_schema`
+- `input_mapping`
+- `output_schema`
+- `output_mapping`
+- `tool_description`
+
+На слое MCP REST operation всегда выглядит как вызов `запрос -> ответ` с фиксированной схемой входа и выхода.
+
+## 5. Как оператор настраивает REST operation
+
+1. Указывает `base_url`.
+2. Выбирает HTTP method.
+3. Указывает `path_template`.
+4. При необходимости загружает пример входного и выходного `JSON`.
+5. Система строит черновую схему и стартовый mapping.
+6. Описывает или уточняет входные MCP-параметры.
+7. Сопоставляет параметры с `path`, `query`, `headers` и `body`.
+8. Указывает, откуда извлекать полезные данные в ответе.
+9. При необходимости уточняет mapping через `JSONPath`.
+10. Запускает тест.
+11. Публикует operation как MCP tool.
+
+## 6. Требования к маппингу
+
+Input mapping должен поддерживать:
+
+- `$.mcp.* -> $.request.path.*`
+- `$.mcp.* -> $.request.query.*`
+- `$.mcp.* -> $.request.headers.*`
+- `$.mcp.* -> $.request.body.*`
+- константы
+- значения по умолчанию
+
+Output mapping должен поддерживать:
+
+- `$.response.body.* -> $.output.*`
+- извлечение вложенных полей
+- нормализацию отсутствующих значений
+
+`JSONPath` является основным способом адресации конкретных параметров при работе со вложенными объектами и массивами.
+
+## 7. Поведение runtime
+
+При выполнении REST operation runtime должен:
+
+1. Валидировать вход по нормализованной схеме.
+2. Применить input mapping.
+3. Собрать HTTP request.
+4. Выполнить вызов через `reqwest`.
+5. Преобразовать ответ в нормализованный JSON.
+6. Применить output mapping.
+7. Вернуть итоговый результат MCP server.
+
+## 8. Нюансы и ограничения
+
+- `DELETE` допускается, но body для него не считается обязательным сценарием совместимости.
+- `PATCH` требует аккуратной работы с частичными payload, поэтому mapping должен позволять заполнять только выбранные поля.
+- Успешный HTTP status сам по себе не гарантирует корректность бизнес-ответа, если response mapping не может извлечь ожидаемые данные.
+- REST adapter не должен содержать бизнес-логику маппинга, только transport-логику.
+- Загруженные JSON-примеры используются для генерации черновика, но не заменяют явную конфигурацию operation.
+
+## 9. Почему REST выделен как основной сценарий Community
+
+REST выбран как основной сценарий Community, потому что:
+
+- контракт определяется URL, методом и payload;
+- semantics HTTP methods важны;
+- поведение интеграции часто завязано на headers и auth;
+- REST легко проверять через простой test run до публикации MCP tool.