Рецепт для модели
Вызовы MCP
Вызовы MCP
Рецепт говорит агенту, как вызывать ComplexQA через MCP (Model Context Protocol) ключом одного проекта. Человеку, который нажимает кнопки в профиле, нужна Выпуск ключа MCP, не эта страница.
Имя вызова в протоколе - поле tool. В тексте ниже это имя в моноширинном шрифте. Список tools у всех ключей одинаковый. Разрешение проверяется в момент вызова.
Вход
Ключ ACTIVE, секрет в Authorization: Bearer, адрес из Подключения агента.
Поиск принимает объект:
| Поле | Смысл |
|---|---|
filters | Массив условий, те же фильтры, что у веб-клиента |
options.limit | Размер страницы. Выше потолка сервер не отдаёт. Если поле пустое, сервер подставляет потолок |
options.order | Порядок: attribute и направление ASC или DESC. Без него порядок строк не зафиксирован. Исключение: шаги автотеста идут по sort_order |
options.add | Какие вложения добрать. Для значений кастомных свойств передайте custom_properties |
response | Необязательный объект ответа, как у веб-клиента |
Одно условие фильтра:
{
"object": { "element": "bug", "attribute": "bug_id" },
"operator": "EQUAL",
"value": 446
}element и attribute - технические имена сущности и поля. operator - слово, не знак. Допустимы LIKE, NOT_LIKE, EQUAL, NOT_EQUAL, GT, GTE, LT, LTE, IN, NOT_IN, IS_NULL, IS_NOT_NULL. Знак = сервер не принимает. У IN и NOT_IN значение - массив.
options.offset схема не принимает: вызов отказывается до main backend. Ответ, в котором строк столько же, сколько потолок страницы, дополняется полем hint: это не весь набор, следующей страницы нет. Сузьте фильтры.
Создание, клон, set, add, add_test_cases, save_json и create_from_test_case требуют idempotency_key длиной от 1 до 191 символа и объект body. Правка одного поля требует body с идентификатором, key и value, без ключа идемпотентности.
Создание на канале MCP не отбрасывает незнакомое поле молча. Чужое имя - отказ, api_code -102, в теле списки unknown_fields и accepted_fields. Браузерный /web_api эту сверку не проходит. project_id, team_id, user_id и mcp_key_id канал ставит сам. Успешное создание записало каждое присланное поле.
Успешный ответ ComplexQA имеет api_code 200. Иначе вызов для клиента - отказ, и текст ответа приходит целиком.
Ограничения
Не выдумывайте поля, шаги и связи, которых нет в ответе. Не вызывайте удаление: такого вызова нет. Не подменяйте project_id ключа. Не ждите окончания запуска автотестов внутри одного вызова: создайте запуск и прочитайте результат следующим вызовом.
Ключ не шире человека. Оба контура должны пропустить вызов: разрешение на ключе и роль этого человека в ComplexQA.
Имена людей приходят объектом, не отдельным справочником состава команды. Поля assigned_to, reporter_id, created_by_user_id и actor_id при actor_type = USER (или если типа нет) имеют вид:
{ "user_id": 21, "first_name": "Alina", "last_name": "QA" }Почты в объекте нет. Неизвестный идентификатор остаётся числом. actor_type = SERVICE не подменяется. В field_changes то же правило для old_value и new_value, если field - одно из этих полей. Состава команды, ролей и доменов в вызовах нет.
Значения кастомных свойств не приходят сами. Их просит поиск: options.add содержит custom_properties. Отдельного чтения custom_property_value нет. Запись значения - custom_property_value_set и custom_property_value_add.
Журнал event_search режется проектом ключа. Автор действия - человек ключа. Если издатель записал канал, в строке есть actor_interface: UI или MCP. При MCP есть mcp_key_id. У старых строк канала может не быть.
Тестовый аккаунт не отдаётся: пароли стенда в контекст модели не попадают. Утилиты (url.inspect, скриншот страницы, мониторинг) в каталог не входят.
Не зарегистрированы, даже если ячейка есть в таблице профиля: delete, update_property_mass, delete_file, отмена запуска autotest_run_cancel.
Повтор создания с тем же idempotency_key после успеха возвращает первый ответ и не увеличивает месячный счётчик. После неуспеха тот же ключ можно выполнить снова. Свежая запись в ходе PENDING просит подождать 60 секунд. Запись PENDING старше 60 секунд выполняется заново.
Выход
Имя вызова - {сущность}_{хвост маршрута}. Разрешение на ключе - заглавный код действия, не хвост.
| Хвост | Код разрешения |
|---|---|
search, summary, деревья проекта, load_body, read_content, check_syntax, get_current_user_tasks | READ |
create | CREATE |
update_property | UPDATE |
| другой изменяющий хвост | тот же хвост заглавными: save_json → SAVE_JSON |
Проект
| Вызов | Разрешение |
|---|---|
project_search | project READ |
project_get_test_structure | project READ |
project_get_autotest_structure | project READ |
project_get_text_document_structure | project READ |
Ресурсы, тот же READ:
| URI | Что это |
|---|---|
complexqa://bug/{bug_id} | Одна карточка дефекта |
complexqa://test_case/{test_case_id} | Одна карточка тест-кейса |
complexqa://autotest_case/{autotest_case_id} | Одна карточка автотеста |
complexqa://project/{project_id}/test_structure | Дерево наборов тестов и тест-кейсов |
complexqa://project/{project_id}/autotest_structure | Дерево автотестов |
complexqa://project/{project_id}/text_document_structure | Дерево текстовых документов |
project_id в URI обязан совпасть с проектом ключа.
Дефект и журнал
| Вызов | Разрешение |
|---|---|
bug_search, bug_summary | bug READ |
bug_create | bug CREATE |
bug_update_property | bug UPDATE |
bug_relation_search | bug_relation READ |
bug_relation_create | bug_relation CREATE |
bug_relation_update_property | bug_relation UPDATE |
event_search | event READ |
Для журнала options.add может содержать subjects, actors, projects, field_changes. Имена людей на actor_id приходят и без actors.
Тестовая документация
| Вызов | Разрешение |
|---|---|
test_suite_search | test_suite READ |
test_suite_create | test_suite CREATE |
test_suite_update_property | test_suite UPDATE |
test_suite_clone_element | test_suite CLONE_ELEMENT |
test_case_search | test_case READ |
test_case_create | test_case CREATE |
test_case_update_property | test_case UPDATE |
test_case_step_search | test_case_step READ |
test_case_step_create | test_case_step CREATE |
test_case_step_update_property | test_case_step UPDATE |
test_run_search | test_run READ |
test_run_create | test_run CREATE |
test_run_update_property | test_run UPDATE |
test_run_add_test_cases | test_run ADD_TEST_CASES |
test_run_result_search | test_run_result READ |
test_run_result_create | test_run_result CREATE |
test_run_result_update_property | test_run_result UPDATE |
Автотесты
| Вызов | Разрешение |
|---|---|
autotest_suite_search | autotest_suite READ |
autotest_suite_create | autotest_suite CREATE |
autotest_suite_update_property | autotest_suite UPDATE |
autotest_suite_clone_element | autotest_suite CLONE_ELEMENT |
autotest_case_search | autotest_case READ |
autotest_case_create | autotest_case CREATE |
autotest_case_create_from_test_case | autotest_case CREATE_FROM_TEST_CASE |
autotest_case_update_property | autotest_case UPDATE |
autotest_case_check_syntax | autotest_case READ |
autotest_step_search | autotest_step READ |
autotest_step_create | autotest_step CREATE |
autotest_step_save_json | autotest_step SAVE_JSON |
autotest_step_update_property | autotest_step UPDATE |
autotest_run_search | autotest_run READ |
autotest_run_create | autotest_run CREATE |
autotest_run_update_property | autotest_run UPDATE |
autotest_result_search | autotest_result READ |
autotest_step_save_json обновляет уже существующие шаги одного autotest_case_id. У каждого элемента steps нужен autotest_step_id. Пропущенные шаги остаются. Новые шаги этот вызов не создаёт: для нового шага нужен autotest_step_create.
Локатор шага передавайте ключом target как объект {kind, value, name}, не строкой с экранированием HTML. Колонка в базе - target_json. kind: ROLE, LABEL, PLACEHOLDER, TESTID, TEXT, TITLE, ALT, CSS, ID, NAME, XPATH, SELECTOR. value_source_type со значением INLINE хранится как null: это и есть встроенный value_text. Второй тип - TEST_ACCOUNT.
autotest_case_status: PENDING, READY или DISABLED. Новый запуск берёт только READY. DISABLED не попадает в новые запуски. Статусов DRAFT и DEPRECATED нет.
autotest_suite_clone_element копирует этот набор и автотесты, которые лежат прямо в нём, вместе с их шагами. Вложенные наборы не копируются. Ответ содержит идентификатор новой копии.
Шаги автотеста - данные ComplexQA (autotest_step, save_json). Код Playwright в репозиторий заказчика этот сервер не пишет.
Репозиторий объектов, документы, прочее
| Вызов | Разрешение |
|---|---|
object_repository_folder_search / create / update_property / clone_element | object_repository_folder и код хвоста |
object_repository_page_search / create / update_property / clone_element | object_repository_page и код хвоста |
object_repository_element_search / create / update_property / clone_element | object_repository_element и код хвоста |
text_document_search, text_document_load_body | text_document READ |
text_document_create | text_document CREATE |
text_document_update_property | text_document UPDATE |
text_document_folder_search | text_document_folder READ |
text_document_folder_create | text_document_folder CREATE |
text_document_folder_update_property | text_document_folder UPDATE |
tag_search | tag READ |
tag_create | tag CREATE |
tag_update_property | tag UPDATE |
tag_clone_element | tag CLONE_ELEMENT |
tag_clone_from_templates | tag CLONE_FROM_TEMPLATES |
tag_relation_search | tag_relation READ |
tag_relation_create | tag_relation CREATE |
tag_relation_update_property | tag_relation UPDATE |
attachment_search, attachment_read_content | attachment READ |
attachment_create | attachment CREATE |
attachment_update_property | attachment UPDATE |
execution_context_search | execution_context READ |
execution_context_create | execution_context CREATE |
execution_context_update_property | execution_context UPDATE |
execution_context_clone_element | execution_context CLONE_ELEMENT |
custom_property_search | custom_property READ |
custom_property_create | custom_property CREATE |
custom_property_update_property | custom_property UPDATE |
custom_property_clone_element | custom_property CLONE_ELEMENT |
custom_property_clone_from_templates | custom_property CLONE_FROM_TEMPLATES |
custom_property_option_search | custom_property_option READ |
custom_property_option_create | custom_property_option CREATE |
custom_property_option_update_property | custom_property_option UPDATE |
custom_property_value_set | custom_property_value SET |
custom_property_value_add | custom_property_value ADD |
task_get_current_user_tasks | task READ |
attachment_read_content отдаёт текст и картинку, пока файл внутри потолка байт. Для большего файла в ответе короткая access_url. Число потолка в этой странице не фиксируется.
task_get_current_user_tasks возвращает задачи человека, которому выдан ключ, не всей команды.
Каталог кастомных свойств и варианты принадлежат команде. У слота нет поля project_id. Запись каталога доступна администратору команды.
Связь дефекта, связь тега и результат автотеста ищутся в команде и дополнительно режутся родителем в проекте ключа.
Сценарии
Сервер регистрирует четыре сценария. Аргумент - строка.
| Имя | Аргумент | Смысл |
|---|---|---|
bug_to_test_case | bug_id | Из дефекта собрать тест-кейс и шаги |
test_case_to_autotest | test_case_id | Из тест-кейса собрать автотест как данные шагов ComplexQA |
autotest_run_and_result | autotest_case_id | Создать запуск автотестов и прочитать результат позже |
failure_to_bug | autotest_result_id | Из неуспеха результата автотеста создать дефект |
Сценарий не обходит разрешения ключа. Удаление внутри сценария не вызывается.
Проверка
Ответ пригоден, если api_code равен 200, идентификаторы принадлежат проекту ключа, а люди в карточках - объекты user_id / first_name / last_name либо число, когда имени нет.
Отказ This key cannot … значит, что пары нет на ключе. HTTP 401 - секрет не принят. HTTP 429 - частота или месячный потолок команды. Повтор создания без нового idempotency_key после успеха не создаёт вторую строку.
Страница не помогла?