# WebAsk MCP Server — Документация

> **Model Context Protocol (MCP)** — стандарт, позволяющий ИИ-моделям (Claude, Cursor, Copilot и др.) подключаться к внешним сервисам и получать данные или выполнять действия напрямую через structured API.

---

## Подключение

### Получение API-ключа

1. Войдите в свой аккаунт WebAsk
2. Перейдите в раздел **Настройки** → **API / MCP**
3. Нажмите **«Создать API-ключ»** и скопируйте его — ключ показывается только один раз

### Эндпоинты

| Среда | URL |
|-------|-----|
| **Продакшн** | `https://mcp.webask.io/mcp/v1` |
| **Бета** | `https://mcp.novaww.com/mcp/v1` |

### Настройка клиента

Передайте API-ключ в заголовке `Authorization`:

```
Authorization: Bearer <ваш_api_ключ>
```

#### Пример конфигурации для Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "webask": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"],
      "env": {
        "MCP_URL": "https://mcp.webask.io/mcp/v1",
        "MCP_AUTH_HEADER": "Authorization",
        "MCP_AUTH_VALUE": "Bearer <ваш_api_ключ>"
      }
    }
  }
}
```

#### Пример конфигурации для Cursor / VS Code

```json
{
  "mcp.servers": {
    "webask": {
      "url": "https://mcp.webask.io/mcp/v1",
      "headers": {
        "Authorization": "Bearer <ваш_api_ключ>"
      }
    }
  }
}
```

### Лимиты

- **180 запросов в минуту** на пользователя (tools/call, resources/read и т.д.)
- Экспортные ссылки действуют **1 час**

---

## Ресурсы (Resources)

Ресурсы предназначены только для **чтения** данных. Для их вызова отправляется запрос `resources/read` с соответствующим URI.

### 👤 Пользователь и воркспейсы

#### `user://me`
Возвращает базовую информацию о текущем авторизованном пользователе.
**Структура ответа:**
| Поле | Тип | Описание |
|------|-----|----------|
| `id` | `integer` | ID пользователя |
| `email` | `string` | Почта пользователя |
| `language` | `string` | Язык интерфейса |
| `workspace` | `object` | Текущее рабочее пространство |

#### `workspace://list`
Возвращает список всех рабочих пространств (Workspaces), к которым имеет доступ пользователь.
**Структура ответа:** Общий объект с ключами:
| Поле | Тип | Описание |
|------|-----|----------|
| `total` | `integer` | Общее количество всех пространств |
| `owned` | `array` | Массив ваших пространств (`id`, `name`, `is_default`) |
| `shared` | `array` | Массив гостевых пространств (`id`, `name`, `owner_id`) |

---

### 📂 Папки и опросы

#### `folder://list`
Список всех папок пользователя, используемых для группировки опросов.
**Структура ответа:** 
| Поле | Тип | Описание |
|------|-----|----------|
| `total` | `integer` | Общее количество папок |
| `items` | `array` | Массив папок: `[{"id": 1, "name": "Название"}]` |

#### `quiz://list`
Список всех опросов, находящихся в доступе пользователя.
**Структура ответа:**
| Поле | Тип | Описание |
|------|-----|----------|
| `total` | `integer` | Общее количество опросов |
| `items` | `array` | Массив опросов: `[{"id": 1, "name": "Тест", "answer_count": 0, "url_shared": "..."}]` |

---

### 🧩 Структура и конфигурация опроса

#### `quiz://{id}/structure`
Полная структура элементов и виджетов опроса. Это главный ресурс для работы с содержимым форм.
**Параметры ресурса:**
| Параметр | Тип | Описание |
|----------|-----|----------|
| `id` | `integer` | (Обязательный) ID опроса |

**Структура ответа:**
| Поле | Тип | Описание |
|------|-----|----------|
| `ids` | `array` | Массив UUID виджетов, определяющий их порядок вывода |
| `entities` | `object` | Полная конфигурация и настройки каждого виджета (ключ - UUID) |
| `options` | `array` | Дополнительные внутренние опции |

#### `quiz://{id}/texts`
Пользовательские и стандартные надписи внутри опроса (например, текст "Далее", "Завершить").
**Параметры ресурса:**
| Параметр | Тип | Описание |
|----------|-----|----------|
| `id` | `integer` | (Обязательный) ID опроса |

**Структура ответа:** Массив объектов текста:
| Поле | Тип | Описание |
|------|-----|----------|
| `code` | `string` | Системный код надписи (`button_next`, `button_done` и др.) |
| `text` | `string` | Пользовательский текст надписи |

#### `quiz://{id}/variables`
Скрытые переменные опроса (extra fields).
**Параметры ресурса:**
| Параметр | Тип | Описание |
|----------|-----|----------|
| `id` | `integer` | (Обязательный) ID опроса |

**Структура ответа:** Массив объектов скрытых переменных:
| Поле | Тип | Описание |
|------|-----|----------|
| `field_id` | `string` | UUID скрытой переменной |
| `name` | `string` | Имя переменной |

#### `quiz://{id}/hidden_options`
Служебные конфигурационные опции всего опроса в целом.
**Параметры ресурса:**
| Параметр | Тип | Описание |
|----------|-----|----------|
| `id` | `integer` | (Обязательный) ID опроса |

**Структура ответа:** Массив активных скрытых опций:
| Поле | Тип | Описание |
|------|-----|----------|
| `id` | `integer` | Внутренний ID опции |
| `name` | `string` | Ключ опции (например, `redirect_url`) |
| `value` | `string` | Значение опции |

#### `quiz://{id}/widgets_hidden`
Скрытая мета-информация конкретных виджетов опроса.
**Параметры ресурса:**
| Параметр | Тип | Описание |
|----------|-----|----------|
| `id` | `integer` | (Обязательный) ID опроса |

**Структура ответа:** Массив опций, привязанных к виджетам:
| Поле | Тип | Описание |
|------|-----|----------|
| `id` | `integer` | Внутренний ID опции |
| `widget_uuid`| `string` | UUID виджета |
| `name` | `string` | Ключ опции |
| `value` | `string` | Значение опции |

---

### 📥 Ответы и сводная аналитика

#### `quiz://{id}/answers`
Список всех ответов респондентов (submissions). Каждая запись содержит уникальный `answer_id`.
**Параметры ресурса:**
| Параметр | Тип | Описание |
|----------|-----|----------|
| `id` | `integer` | (Обязательный) ID опроса |

**Query-параметры (пример: `?limit=50&is_complete=1`):**
| Параметр | Тип | Возможные значения | Описание |
|----------|-----|--------------------|----------|
| `limit` | `integer` | от `1` до `100` | Лимит записей (по умолчанию 20) |
| `offset` | `integer` | `любое число` | Сдвиг для пагинации (по умолчанию 0) |
| `date` | `string` | `Y-m-d` | Получить результаты только за конкретный день |
| `is_complete`| `boolean` | `1`/`0`, `true`/`false`| Фильтр по завершённости (true — завершённые) |
| `sort` | `string` | `date_end`, `date_start` | Поле сортировки (по дате старта или завершения) |
| `order` | `string` | `desc`, `asc` | Направление сортировки |

**Структура ответа:** Объект с данными пагинации:
| Поле | Тип | Описание |
|------|-----|----------|
| `total` | `integer` | Общее количество подходящих ответов |
| `offset` | `integer` | Текущий сдвиг |
| `items` | `array` | Массив детальных ответов респондента с `answer_id` |

#### `quiz://{id}/summary`
Сводная аналитика опроса (воронка конверсий, типы устройств, география).
**Параметры ресурса:**
| Параметр | Тип | Описание |
|----------|-----|----------|
| `id` | `integer` | (Обязательный) ID опроса |

---

### 📊 Развёрнутые отчёты (Reports)

#### `quiz://{id}/report`
Детальный отчёт по виджетам со статистикой. При наличии фильтров возвращает `report_uuid`.
**Параметры ресурса:**
| Параметр | Тип | Описание |
|----------|-----|----------|
| `id` | `integer` | (Обязательный) ID опроса |

**Query-параметры:**
| Параметр | Тип | Пример / Значения | Описание |
|----------|-----|-------------------|----------|
| `date_from` | `string` | `2024-01-01` | Начало периода (формат `Y-m-d`) |
| `date_to` | `string` | `2024-12-31` | Конец периода (формат `Y-m-d`) |
| `is_complete` | `boolean`| `1` или `0` | Учитывать только полные ответы |
| `widgets` | `array` | `widgets[]=uuid1...`| Фильтрация по определенным виджетам (UUID) |
| `tags` | `array` | `tags[]=тег1...` | Фильтрация по конкретным тегам |

#### `quiz://{id}/report_filters`
Возвращает сохранённые фильтры пользователя для отчётов этого опроса.
**Параметры ресурса:**
| Параметр | Тип | Описание |
|----------|-----|----------|
| `id` | `integer` | (Обязательный) ID опроса |

#### `quiz://{id}/report/{report_uuid}/inputs`
Текстовые ответы респондентов на input-виджеты (строка, email, телефон и т.д.).
**Параметры ресурса:**
| Параметр | Тип | Описание |
|----------|-----|----------|
| `id` | `integer` | (Обязательный) ID опроса |
| `report_uuid`| `string` | (Обязательный) UUID отчёта |

**Query-параметры:**
| Параметр | Тип | Описание |
|----------|-----|----------|
| `widget_id` | `string` | ID (UUID) виджета |
| `widget_hash`| `string` | Hash виджета (из структуры) |
| `limit` | `integer`| Лимит записей (по умолчанию 50) |
| `offset` | `integer`| Сдвиг (пагинация, начиная с 0) |

#### `quiz://{id}/report/{report_uuid}/files`
Загруженные пользователями файлы (ответы на виджет загрузки файла). 
**Параметры ресурса:**
| Параметр | Тип | Описание |
|----------|-----|----------|
| `id` | `integer` | (Обязательный) ID опроса |
| `report_uuid`| `string` | (Обязательный) UUID отчёта |

**Query-параметры:** Как у `inputs` (`widget_id`, `widget_hash`, `limit`, `offset`).

---

### 🎨 Темы оформления

#### `theme://list`
Список тем оформления (публичных и приватных из workspace).
**Структура ответа:** Массив объектов тем:
| Поле | Тип | Описание |
|------|-----|----------|
| `id` | `integer` | ID темы оформления (нужен для `apply_quiz_theme`) |
| `name` | `string` | Название темы |

#### `theme://{id}/details`
Детальные настройки указанной темы: цвета фона, шрифты, закругления кнопок и т.д.
**Параметры ресурса:**
| Параметр | Тип | Описание |
|----------|-----|----------|
| `id` | `integer` | (Обязательный) ID темы |

---

### 🎟️ Промокоды

#### `promocode://list`
Списки групп промокодов в рабочем пространстве.
**Query-параметры:**
| Параметр | Тип | Описание |
|----------|-----|----------|
| `workspace_id`| `integer` | (Обязательный) ID рабочего пространства |

#### `promocode://{id}/codes`
Коды в конкретном списке.
**Параметры ресурса:**
| Параметр | Тип | Описание |
|----------|-----|----------|
| `id` | `integer` | (Обязательный) ID списка промокодов |

**Query-параметры:**
| Параметр | Тип | Описание |
|----------|-----|----------|
| `workspace_id`| `integer` | (Обязательный) ID рабочего пространства |

---

## Инструменты (Tools)

Tools — действия, которые выполняются на стороне WebAsk по запросу ИИ-модели.

### Формат ответа инструментов

Каждый инструмент возвращает объект с полями:

| Поле | Тип | Описание |
|------|-----|----------|
| `content` | `array` | Массив блоков для отображения: `[{"type": "text", "text": "сообщение"}]`. Текст сообщения об успехе или об ошибке. |
| `isError` | `boolean` | `false` — успех, `true` — ошибка (валидация, доступ, сохранение и т.д.). |
| *(доп. ключи)* | — | При успехе добавляются поля с данными (например `quiz`, `quiz_id`, `url`, `updated`). При ошибке структуры виджетов может быть массив `errors`. |

В примерах ниже приведён **полный** успешный ответ (включая `content` и `isError` и все возвращаемые данные).

**Пример ответа с ошибкой:**
```json
{
  "content": [{"type": "text", "text": "Ошибка валидации: Поле quiz_id обязательно для заполнения."}],
  "isError": true
}
```

---

### 📁 Управление опросами

#### `create_quiz`
Создаёт новый опрос.
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Опрос успешно создан (ID: 1)."}],
  "isError": false,
  "quiz": {
    "id": 1,
    "workspace_id": 5,
    "answer_count": 0,
    "visits": {"visit": 0, "u_visit": 0},
    "ssid": "...",
    "shared": false,
    "isPublished": false,
    "is_archive": false,
    "is_template": false,
    "name": "Новый опрос",
    "virtual_id": null,
    "url_preview": "https://...",
    "url_shared": "https://...",
    "project": null,
    "quiz_data": {"ids": [], "entities": {}},
    "conditions": null,
    "settings": {"lang": "ru", "show_progressbar": true, "show_navigate": true, "numeration": false, "theme_id": 1, "..." : "..."},
    "info": {"info_title": "", "description": "", "og_image": null, "favicon": null},
    "integrations": {}
  }
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `folder_id` | `integer` | (Обязательный) ID папки, в которой будет создан опрос. |

#### `rename_quiz`
Переименовывает существующий опрос.
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Опрос #1 переименован в \"Новое название опроса\"."}],
  "isError": false,
  "quiz_id": 1,
  "name": "Новое название опроса"
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `quiz_id` | `integer` | (Обязательный) ID опроса. |
| `name` | `string` | (Обязательный) Новое название опроса (макс. 80 символов). |

#### `duplicate_quiz`
Создаёт копию опроса со всеми данными и версиями.
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Опрос #1 успешно дублирован (новый ID: 2)."}],
  "isError": false,
  "quiz": {
    "id": 2,
    "name": "Копия опроса",
    "url_shared": "https://...",
    "is_published": false,
    "created_at": "2024-01-15T12:00:00.000000Z",
    "updated_at": "2024-01-15T12:00:00.000000Z"
  }
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `quiz_id` | `integer` | (Обязательный) ID опроса для дублирования. |
| `name` | `string` | (Опционально) Новое название опроса (макс. 80 символов). |

#### `archive_quiz`
Архивирует или разархивирует опрос.
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Опрос архивирован."}],
  "isError": false,
  "quiz_id": 1,
  "archive_at": "2024-01-15 12:00:00",
  "is_archived": true
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `quiz_id` | `integer` | (Обязательный) ID опроса. |
| `archive` | `boolean` | (Обязательный) `true` — архивировать, `false` — разархивировать. |

#### `delete_quiz`
Удаляет опрос (мягкое удаление, с возможностью восстановления).
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Опрос #1 удален."}],
  "isError": false,
  "quiz_id": 1
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `quiz_id` | `integer` | (Обязательный) ID опроса. |

#### `publish_quiz`
Публикует опрос: текущая локальная версия становится публичной.
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Опрос #1 успешно опубликован."}],
  "isError": false,
  "quiz": {
    "id": 1,
    "workspace_id": 5,
    "answer_count": 0,
    "name": "Мой опрос",
    "url_shared": "https://...",
    "isPublished": true,
    "quiz_data": {"ids": ["uuid-1"], "entities": {"uuid-1": {"type": "question", "title": "Вопрос"}}},
    "conditions": {},
    "settings": {"lang": "ru", "theme_id": 1, "..." : "..."},
    "info": {},
    "integrations": {}
  }
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `quiz_id` | `integer` | (Обязательный) ID опроса. |

#### `move_quiz`
Перемещает опрос в другую папку пользователя.
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Опрос перемещен в папку #5."}],
  "isError": false,
  "quiz_id": 1,
  "folder_id": 5
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `quiz_id` | `integer` | (Обязательный) ID опроса. |
| `folder_id` | `integer` | (Обязательный) ID целевой папки (`folder://list`). |

#### `make_quiz_template`
Создаёт шаблон на основе текущего опроса.
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Шаблон успешно создан."}],
  "isError": false,
  "quiz_id": 1
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `quiz_id` | `integer` | (Обязательный) ID опроса. |

#### `create_folder`
Создаёт новую папку для группировки опросов.
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Папка успешно создана."}],
  "isError": false,
  "message": "OK"
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `workspace_id`| `integer` | (Обязательный) ID workspace (`workspace://list`). |
| `name` | `string` | (Обязательный) Название папки (макс. 255 символов). |

---

### 🎨 Содержимое и структура опроса

#### `update_quiz_widgets`
Сохраняет структуру виджетов опроса. Используется для изменения/добавления любых элементов формы.
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Структура виджетов опроса успешно обновлена."}],
  "isError": false,
  "quiz": {
    "id": 1,
    "workspace_id": 5,
    "answer_count": 0,
    "name": "Мой опрос",
    "url_shared": "https://...",
    "isPublished": false,
    "quiz_data": {
      "ids": ["a1b2c3d4-..."],
      "entities": {
        "a1b2c3d4-...": {"type": "question", "title": "Текст вопроса", "..." : "..."}
      }
    },
    "conditions": {},
    "settings": {"lang": "ru", "theme_id": 1, "show_progressbar": true, "..." : "..."},
    "info": {},
    "integrations": {}
  }
}
```
При ошибке структуры виджетов дополнительно возвращается массив `errors` (список строк с описанием несоответствий).
| Параметр | Тип | Описание |
|----------|-----|----------|
| `quiz_id` | `integer` | (Обязательный) ID опроса. |
| `ids` | `array` | (Обязательный) Массив UUID виджетов (порядок на странице). |
| `entities` | `object` | (Обязательный) Ключ-значение: `{"uuid": {настройки виджета}}`. |

#### `update_quiz_texts`
Сохраняет пользовательские тексты кнопок и интерфейсных элементов опроса. (**Требуется платный тариф**).
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Пользовательские тексты опроса успешно обновлены."}],
  "isError": false,
  "message": "OK"
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `quiz_id` | `integer` | (Обязательный) ID опроса. |
| `texts` | `array` | (Обязательный) Массив объектов `[{"code": "string", "text": "string"}]`. |

#### `update_quiz_settings`
Обновляет настройки опроса (название, язык, отображение, навигация, ограничения по времени и числу ответов, капча, тема, скрипты, QR-код, таймер заполнения, IP/устройства и др.). Передаются только те поля, которые нужно изменить.
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Настройки опроса обновлены."}],
  "isError": false,
  "updated": ["name", "lang"]
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `name` | `string` | Название опроса (макс. 255 символов). |
| `lang` | `string` | Язык интерфейса опроса: `ru`, `en`, `es` или `pt`. |
| `show_progressbar` | `boolean` | Показывать прогресс-бар прохождения опроса. |
| `show_navigate` | `boolean` | Показывать навигацию (кнопки назад/вперёд). |
| `numeration` | `boolean` | Включить нумерацию вопросов. |
| `auto_move_by_enter` | `boolean` | Переход к следующему вопросу по нажатию Enter. |
| `show_to_robots` | `boolean` | Доступность страницы опроса для поисковых роботов. |
| `show_by_one` | `boolean` | Показывать по одному вопросу на экране. |
| `allow_multiple_answer`| `boolean`| Разрешить повторную отправку ответа (несколько прохождений). |
| `show_copyright` | `boolean` | Показывать копирайт WebAsk в опросе. |
| `scripts_in_head` | `string` | Код скриптов в `<head>`. |
| `scripts_in_body` | `string` | Код скриптов в `<body>`. |
| `scripts_in_head_enabled` | `boolean` | Включить выполнение скриптов в head. |
| `scripts_in_body_enabled` | `boolean` | Включить выполнение скриптов в body. |
| `closed_quiz_message_enabled`| `boolean`| Включить сообщение о закрытии опроса. |
| `close_quiz_enabled` | `boolean` | Опрос закрыт (приём ответов отключён). |
| `limit_time_enabled`| `boolean` | Включить ограничение по времени доступности опроса. |
| `limit_time_value` | `string` | Дата/время окончания доступности. |
| `limit_time_value_tz`| `string` | Значение времени с таймзоной. |
| `limit_time_timezone`| `string` | Таймзона для ограничения по времени. |
| `limit_answer_count_enabled`| `boolean`| Включить ограничение максимального числа ответов. |
| `limit_answer_count_value` | `integer`| Максимальное число ответов. |
| `limit_message_title`| `string`| Заголовок сообщения при достижении лимита ответов. |
| `limit_message_body`| `string` | Текст сообщения при достижении лимита ответов. |
| `show_captcha` | `boolean` | Показывать капчу при отправке ответа. |
| `captcha_public_key` | `string` | Публичный ключ капчи. |
| `captcha_secret_key` | `string` | Секретный ключ капчи. |
| `multiple_ip` | `boolean` | Разрешить прохождение с нескольких IP. |
| `use_password` | `boolean` | Требовать пароль для доступа к опросу. |
| `session_check_method`| `array` | Методы проверки сессии: `ip`, `cookie`, `extra_params`. |
| `theme_id` | `integer` | ID темы оформления воркспейса. |
| `logo_show` | `boolean` | Показывать логотип воркспейса в опросе (применяется к воркспейсу). |
| `extra_fields` | `array` | Список скрытых переменных (extra fields). |
| `scoring_switcher` | `boolean` | Включить переключатель подсчёта баллов в опросе. |
| `block_jump_to_prev_widget`| `boolean`| Запретить переход к предыдущему вопросу (виджету). |
| `question_required_mode` | `string`| Режим обязательности вопросов: `individual`, `all_required`, `all_optional`. |
| `question_random_order`| `boolean`| Показывать вопросы в случайном порядке. |
| `disable_auto_redirect`| `boolean`| Отключить автоматический переход после ответа. |
| `filling_time_enabled`| `boolean`| Включить таймер времени на заполнение опроса. |
| `filling_time_seconds`| `integer`| Время на заполнение в секундах. |
| `ip_list_enabled` | `boolean` | Включить фильтрацию по спискам IP (белый/чёрный список). |
| `ip_whitelist` | `string` | Белый список IP. |
| `ip_blacklist` | `string` | Чёрный список IP. |
| `available_devices` | `array` | Доступные устройства: `desktop`, `mobile`, `tablet`. |
| `info_title` | `string` | Заголовок (мета). |
| `description` | `string` | Описание опроса (мета). |
| `qr_code_format` | `string` | Формат QR-кода. |
| `qr_code_size` | `integer` | Размер QR-кода в пикселях. |
| `qr_code_color` | `string` | Цвет QR-кода. |
| `qr_code_background_color`|`string`| Цвет фона QR-кода. |
| `qr_code_margin` | `integer` | Отступ QR-кода. |
| `is_change_theme` | `boolean` | Менять тему оформления по данным из QR-кода. |

#### `update_quiz_logic`
Сохраняет логические условия, переходы и скоринг (баллы). Формируется на основе UUID виджетов.
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Логика опроса успешно обновлена."}],
  "isError": false,
  "quiz": {
    "id": 1,
    "name": "Мой опрос",
    "quiz_data": {"ids": [], "entities": {}},
    "conditions": {"uuid-1": "uuid-2"},
    "settings": {},
    "info": {}
  }
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `quiz_id` | `integer` | (Обязательный) ID опроса. |
| `defaultConditions`| `object` | Переходы между экранами по умолчанию. Ключ — UUID виджета, значение — UUID целевого виджета. |
| `savedLogic` | `object` | Разветвлённая логика по ответам: `{"uuid": {"rules": [...]}}`. |
| `savedScoring` | `object` | Назначение баллов за варианты ответов. |
| `multiLogicFlags` | `object` | Флаги логики для конкретных виджетов. |

#### `update_quiz_note`
Добавляет или изменяет внутреннюю заметку опроса.
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Заметка опроса обновлена."}],
  "isError": false,
  "quiz_id": 1,
  "notes": "Текст внутренней заметки"
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `quiz_id` | `integer` | (Обязательный) ID опроса. |
| `notes` | `string` | (Обязательный) Текст заметки (видна только владельцу). |

#### `upload_quiz_media`
Загрузка медиа (изображение, видео, аудио) для блока multimedia. (**Требуется платный тариф**).
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Медиа загружено. url: https://storage.webask.io/... — подставьте в multimedia.imgUrl."}],
  "isError": false,
  "url": "https://storage.webask.io/..."
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `quiz_id` | `integer` | (Обязательный) ID опроса. |
| `type` | `string` | (Обязательный) Тип медиа: `image`, `video`, `audio`. |
| `url` | `string` | Ссылка (если загружается из сети). Укажите `url` или `file_base64`. |
| `file_base64` | `string` | Содержимое в base64. Укажите `url` или `file_base64`. |
| `filename` | `string` | Имя файла (опционально, для `file_base64`). |

#### `upload_quiz_widget_image`
Загрузка картинки для виджета "Выбор из списка" с медиа-вариантами.
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Изображение загружено. url: https://storage.webask.io/... — подставьте в choiceImageEntities[].link."}],
  "isError": false,
  "url": "https://storage.webask.io/..."
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `quiz_id` | `integer` | (Обязательный) ID опроса. |
| `url` | `string` | Ссылка (если загружается из сети). Укажите `url` или `file_base64`. |
| `file_base64` | `string` | Картинка в base64. Укажите `url` или `file_base64`. |
| `filename` | `string` | Имя файла (опционально). |

### 🎭 Темы оформления

#### `apply_quiz_theme`
Применяет указанную тему оформления к опросу.
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Тема #3 применена к опросу #1."}],
  "isError": false,
  "quiz": {
    "id": 1,
    "name": "Мой опрос",
    "url_shared": "https://...",
    "answer_count": 0,
    "quiz_data": {"ids": [], "entities": {}},
    "settings": {"theme_id": 3, "..." : "..."},
    "info": {}
  }
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `quiz_id` | `integer` | (Обязательный) ID опроса. |
| `theme_id` | `integer` | (Обязательный) ID темы (публичной или из вашего workspace). (`theme://list`). |

#### `create_theme`
Создаёт новую тему в workspace и применяет к опросу. (**Требуется платный тариф**).
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Тема создана и применена к опросу."}],
  "isError": false,
  "theme_id": 5,
  "name": "Тема 1"
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `workspace_id` | `integer` | (Обязательный) ID рабочего пространства. |
| `quiz_id` | `integer` | (Обязательный) ID опроса. |
| `name` | `string` | Название темы (макс. 255 символов). |
| `base_font_id` | `integer` | ID шрифта (`1`=Native, `2`=Roboto, `3`=Open Sans, `44`=Golos Text...). |
| `background_type_id` | `integer` | Тип фона: `1`=color_image, `2`=gradient. |
| `bg_gradient_vector` | `integer` | Направление градиента в градусах (0–360). |
| `bg_gradient_start` | `string` | Начальный цвет градиента в hex (напр. `#00d4ff`). |
| `bg_gradient_end` | `string` | Конечный цвет градиента в hex. |
| `buttons_type_id` | `integer` | Тип кнопок: `1`=background, `2`=border. |
| `header_color` | `string` | Цвет заголовка в формате `#RRGGBB`. |
| `buttons_color` | `string` | Цвет кнопок в формате `#RRGGBB`. |
| `buttons_text_color` | `string` | Цвет текста кнопок в формате `#RRGGBB`. |
| `buttons_radius` | `integer` | Радиус скругления кнопок (0–999 px). |
| `bg_color` | `string` | Цвет фона в формате `#RRGGBB` (для `background_type_id=1`). |
| `widget_active_color` | `string` | Цвет активного элемента виджета в формате `#RRGGBB`. |
| `bg_image_file_id` | `integer` | ID загруженного файла фонового изображения. |
| `background_position_id` | `integer` | Позиция фона (1–9). |
| `background_opacity` | `integer` | Прозрачность фона (0–100%). |
| `background_lightness` | `integer` | Яркость фона (-100 – +100). |
| `background_placement_id`| `integer` | Размещение фона: `1`=stretch, `2`=drawin, `3`=cover. |
| `background_saturate` | `integer` | Насыщенность фона (-100 – +100). |
| `background_contrast` | `integer` | Контраст фона (-100 – +100). |
| `bg_logo_file_id` | `integer` | ID загруженного файла логотипа поверх фона. |
| `bg_logo_position_id`| `integer` | Позиция логотипа на фоне (min: 1). |
| `bg_logo_size_id` | `integer` | Размер логотипа (min: 1). |
| `answer_options_radius`| `integer` | Скругление карточек вариантов ответа в px. |
| `answer_border` | `integer` | Толщина рамки вариантов ответа в px. |

#### `update_theme`
Обновляет существующую тему (настройки аналогичны `create_theme`).
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Тема успешно обновлена."}],
  "isError": false,
  "theme": {
    "id": 5,
    "workspace_id": 1,
    "name": "Тема 1",
    "base_font_id": 1,
    "background_type_id": 2,
    "bg_gradient_start": "#00d4ff",
    "bg_gradient_end": "#090979",
    "buttons_type_id": 1,
    "created_at": "...",
    "updated_at": "..."
  }
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `workspace_id` | `integer` | (Обязательный) ID рабочего пространства. |
| `theme_id` | `integer` | (Обязательный) ID темы (`theme://list`). |
| Остальные 25 параметров | | Аналогичны параметрам `create_theme` (начиная с `name` по `answer_border`). |

---

### 🔢 Переменные опроса

#### `create_quiz_variable`
Создаёт новую скрытую переменную (extra field) опроса.
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Скрытая переменная создана."}],
  "isError": false,
  "item": {
    "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Имя переменной"
  }
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `quiz_id` | `integer` | (Обязательный) ID опроса. |
| `name` | `string` | (Обязательный) Имя переменной. |
| `id` | `string` | (Опционально) Кастомный UUID переменной. |

#### `update_quiz_variable`
Обновляет имя скрытой переменной.
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Скрытая переменная обновлена."}],
  "isError": false,
  "item": {
    "field_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Новое имя переменной"
  }
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `quiz_id` | `integer` | (Обязательный) ID опроса. |
| `field_id` | `string` | (Обязательный) UUID переменной (`quiz://{id}/variables`). |
| `name` | `string` | (Обязательный) Новое имя. |

#### `delete_quiz_variable`
Удаляет скрытую переменную.
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Скрытая переменная удалена."}],
  "isError": false
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `quiz_id` | `integer` | (Обязательный) ID опроса. |
| `field_id` | `string` | (Обязательный) UUID переменной. |

---

### ⚙️ Скрытые опции

#### `create_hidden_option`
Создаёт скрытую служебную опцию всего опроса.
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Скрытая опция создана."}],
  "isError": false,
  "item": {
    "id": 10,
    "name": "redirect_url",
    "value": "https://example.com/thanks"
  }
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `quiz_id` | `integer` | (Обязательный) ID опроса. |
| `name` | `string` | (Обязательный) Ключ опции (напр. `redirect_url`). |
| `value` | `string` | (Обязательный) Значение. |

#### `update_hidden_option`
Обновляет скрытую служебную опцию опроса.
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Скрытая опция обновлена."}],
  "isError": false
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `quiz_id` | `integer` | (Обязательный) ID опроса. |
| `opt_id` | `integer` | (Обязательный) ID опции (`quiz://{id}/hidden_options`). |
| `name` | `string` | (Обязательный) Ключ опции. |
| `value` | `string` | (Обязательный) Значение. |

#### `delete_hidden_option`
Удаляет скрытую опцию опроса.
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Скрытая опция удалена."}],
  "isError": false
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `quiz_id` | `integer` | (Обязательный) ID опроса. |
| `opt_id` | `integer` | (Обязательный) ID опции (`quiz://{id}/hidden_options`). |

#### `create_widget_hidden_option`
Создаёт скрытую служебную опцию конкретного виджета.
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Скрытая опция виджета создана."}],
  "isError": false,
  "item": {
    "id": 11,
    "widget_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "custom_key",
    "value": "custom_value"
  }
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `quiz_id` | `integer` | (Обязательный) ID опроса. |
| `widget_uuid` | `string` | (Обязательный) UUID виджета. |
| `name` | `string` | (Обязательный) Ключ опции. |
| `value` | `string` | (Обязательный) Значение. |

#### `update_widget_hidden_option`
Обновляет опцию конкретного виджета.
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Скрытая опция виджета обновлена."}],
  "isError": false
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `quiz_id` | `integer` | (Обязательный) ID опроса. |
| `opt_id` | `integer` | (Обязательный) ID опции. |
| `name` | `string` | (Обязательный) Ключ опции. |
| `value` | `string` | (Обязательный) Значение. |

#### `delete_widget_hidden_option`
Удаляет опцию конкретного виджета.
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Скрытая опция виджета удалена."}],
  "isError": false
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `quiz_id` | `integer` | (Обязательный) ID опроса. |
| `opt_id` | `integer` | (Обязательный) ID опции. |

---

### 📊 Ответы и аналитика

#### `toggle_answer_visibility`
Скрывает или показывает конкретный ответ респондента.
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Видимость ответа обновлена."}],
  "isError": false,
  "answer_id": 100,
  "is_exclude": true
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `quiz_id` | `integer` | (Обязательный) ID опроса. |
| `answer_id` | `integer` | (Обязательный) ID ответа. |
| `is_hide` | `boolean` | (Обязательный) `true` (скрыть) или `false` (показать). |

#### `tag_answer`
Добавляет/синхронизирует теги для выбранного ответа.
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Теги ответа обновлены."}],
  "isError": false,
  "result": {
    "attached": [5],
    "detached": []
  }
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `quiz_id` | `integer` | (Обязательный) ID опроса. |
| `answer_id` | `integer` | (Обязательный) ID ответа. |
| `tags` | `array` | (Обязательный) Массив строк-тегов (заменяет старые). |

#### `generate_filtered_report`
Формирует отчёт по опросу с фильтрацией (даты, виджеты, теги). Возвращает `report_uuid`.
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Фильтрованный отчет сформирован."}],
  "isError": false,
  "data": {
    "report_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "total": 150
  }
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `quiz_id` | `integer` | (Обязательный) ID опроса. |
| `dateFrom` | `string` | Начало (формат `d.m.Y`, напр. `01.01.2024`). |
| `dateTo` | `string` | Конец (формат `d.m.Y`). |
| `is_complete` | `boolean` | Учитывать только полные ответы. |
| `widgets` | `array` | Массив UUID виджетов для отчёта. |
| `tags` | `array` | Массив тегов. |

---

### 🔗 Публичные ссылки

#### `share_summary_link` / `share_report_link` / `share_answers_link`
Создаёт публичные ссылки для шеринга аналитики с заказчиками (без авторизации).
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Публичная ссылка summary создана."}],
  "isError": false,
  "url": "https://webask.io/results/..."
}
```
Для `share_answers_link` также может возвращаться поле `shared_url`.
| Параметр | Тип | Описание |
|----------|-----|----------|
| `quiz_id` | `integer` | (Обязательный) ID опроса. |
| `date_from` / `date_to` | `string` | (Для summary и answers). Формат `Y-m-d`. |
| `type` | `string` | (Для answers) `full`, `in`, `not_in`, `answer`. |
| `answerIds` | `array` | (Для answers) ID ответов. |

---

### 📥 Экспорт списка ответов и отчёта

Инструменты экспорта: `export_answers_csv`, `export_answers_xlsx`, `export_answers_word`, `export_summary_pdf`, `export_filtered_report_pdf`, `export_filtered_report_word`.

**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Файл CSV готов. Скачать по ссылке (действует 1 час, после скачивания файл удаляется): https://storage.webask.io/..."}],
  "isError": false,
  "quiz_id": 1,
  "format": "csv",
  "download_url": "https://storage.webask.io/..."
}
```
Ссылка на скачивание действует 1 час. Для вызова любого из этих инструментов используется один обязательный параметр:
| Параметр | Тип | Описание |
|----------|-----|----------|
| `quiz_id` | `integer` | (Обязательный) ID опроса. |

---

### 🎟️ Промокоды (Доступно на платных тарифах)

#### `create_promocode_group`
Создаёт новый список промокодов для workspace.
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Список промокодов создан."}],
  "isError": false,
  "list_id": 10
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `quiz_id` | `integer` | (Обязательный) ID опроса в нужном workspace. |
| `name` | `string` | (Обязательный) Название списка. |
| `codes` | `array` | (Обязательный) Массив строковых кодов (до 1000). |

#### `add_promocodes`
Добавляет новые промокоды в существующий список.
**Структура ответа (успех):**
```json
{
  "content": [{"type": "text", "text": "Промокоды успешно добавлены."}],
  "isError": false,
  "added_count": 5
}
```
| Параметр | Тип | Описание |
|----------|-----|----------|
| `quiz_id` | `integer` | (Обязательный) ID опроса в нужном workspace. |
| `list_id` | `integer` | (Обязательный) ID списка промокодов (`promocode://list`). |
| `codes` | `array` | (Обязательный) Массив строковых кодов. |

---

## Технические детали

### Протокол

- **Версия протокола:** `2025-06-18`  
- **Транспорт:** HTTP POST (JSON-RPC 2.0)  
- **Метод подключения:** `POST /mcp/v1` (запросы)

### Стандартные JSON-RPC методы

| Метод | Описание |
|-------|----------|
| `initialize` | Инициализация сессии, получение capabilities сервера |
| `tools/list` | Получить список всех доступных инструментов |
| `tools/call` | Вызвать инструмент с параметрами |
| `resources/list` | Получить список всех доступных ресурсов |
| `resources/read` | Прочитать содержимое ресурса по URI |
| `prompts/list` | Получить список prompt-шаблонов |
| `prompts/get` | Получить конкретный prompt-шаблон |

### Пример запроса

```json
POST https://mcp.webask.io/mcp/v1
Authorization: Bearer <ваш_api_ключ>
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "rename_quiz",
    "arguments": {
      "quiz_id": 123,
      "name": "Новое название опроса"
    }
  }
}
```

### Формат ответа при ошибке

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params: quiz_id is required"
  }
}
```

---

## Типичные сценарии использования

### 1. Получить список опросов и структуру конкретного

```
1. Читаем ресурс: quiz://list → получаем список опросов с ID
2. Читаем ресурс: quiz://{id}/structure → получаем структуру виджетов
```

### 2. Работа с ответами

```
1. Читаем ресурс: quiz://{id}/answers → получаем ответы (с answer_id)
2. Вызываем tool: tag_answer (добавить теги) или toggle_answer_visibility (скрыть/показать)
```

### 3. Экспорт с фильтрацией

```
1. Вызываем tool: generate_filtered_report (quiz_id, dateFrom/dateTo в формате d.m.Y, фильтры)
   → получаем report_uuid фильтрованного отчёта
   ⚠ Формат дат здесь d.m.Y (например 01.01.2024), тогда как ресурс quiz://{id}/report использует Y-m-d
2. Читаем ресурс: quiz://{id}/report/{report_uuid}/files или /inputs → детальные ответы по виджетам
3. Вызываем tool: export_filtered_report_pdf (quiz_id) → получаем ссылку на PDF
   ⚠ Инструменты export_filtered_report_pdf и export_filtered_report_word принимают только quiz_id;
     report_uuid передавать не нужно — экспорт строится по последнему состоянию отчёта опроса
```

### 4. Добавление промокодов

```
1. Вызываем tool: create_promocode_group → создаём список с первыми кодами → получаем list_id
2. (при необходимости) Вызываем tool: add_promocodes → добавляем ещё коды в список
3. Читаем ресурс: promocode://{list_id}/codes → проверяем добавленные коды
```

### 5. Применить тему и сразу получить структуру опроса

```
1. Читаем ресурс: theme://list → получаем список доступных тем с ID
2. Вызываем tool: apply_quiz_theme (quiz_id, theme_id)
   → в ответе сразу доступно поле quiz с widgets, hidden_options и meta — дополнительный
     запрос quiz://{id}/structure не нужен
```