> ## Documentation Index
> Fetch the complete documentation index at: https://avala.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Server

> Используйте Avala с Claude, Claude Code, Cursor, VS Code и ChatGPT через Model Context Protocol

[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) — это открытый стандарт, который позволяет AI-ассистентам взаимодействовать с внешними инструментами и источниками данных. MCP Server от Avala предоставляет ваши датасеты, проекты и экспорты в виде инструментов, которые может вызывать любой MCP-совместимый клиент, позволяя управлять рабочим процессом аннотирования на естественном языке без переключения контекста.

Это значит, что вы можете попросить Claude «показать все мои датасеты», создать экспорт в Cursor или проверить статус проекта в VS Code — всё это работает на том же Avala API, который вы уже используете.

## Предварительные требования

* **Node.js** версии 18 или новее, установленный на вашем компьютере
* **API-ключ Avala** (создайте его в [Mission Control](https://avala.ai/settings?section=security) в разделе **Settings > Security**)

## Настройка

### Claude Desktop

Откройте файл конфигурации Claude Desktop:

* **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

Добавьте Avala MCP Server:

<Warning>
  Никогда не коммитьте файлы конфигурации с настоящими API-ключами в систему контроля версий. Установите `AVALA_API_KEY` как системную переменную окружения или замените `"your-api-key"` на ваш реальный ключ локально и убедитесь, что файл конфигурации добавлен в `.gitignore`.
</Warning>

```json theme={null}
{
  "mcpServers": {
    "avala": {
      "command": "npx",
      "args": ["-y", "@avala-ai/mcp-server"],
      "env": {
        "AVALA_API_KEY": "your-api-key"
      }
    }
  }
}
```

Перезапустите Claude Desktop. Инструменты Avala появятся в списке доступных инструментов.

### Cursor

Создайте или отредактируйте файл `.cursor/mcp.json` в корне вашего проекта (или в глобальной директории конфигурации):

<Warning>
  Файл `.cursor/mcp.json` находится в корне проекта и может быть закоммичен в git. Добавьте его в `.gitignore` или установите `AVALA_API_KEY` как системную переменную окружения вместо указания ключа непосредственно в файле конфигурации.
</Warning>

```json theme={null}
{
  "mcpServers": {
    "avala": {
      "command": "npx",
      "args": ["-y", "@avala-ai/mcp-server"],
      "env": {
        "AVALA_API_KEY": "your-api-key"
      }
    }
  }
}
```

Перезапустите Cursor или перезагрузите окно. Инструменты Avala появятся в режиме агента Cursor.

### VS Code

Создайте или отредактируйте файл `.vscode/mcp.json` в вашем рабочем пространстве:

<Warning>
  Файл `.vscode/mcp.json` находится в вашем рабочем пространстве и может быть закоммичен в git. Добавьте его в `.gitignore` или установите `AVALA_API_KEY` как системную переменную окружения вместо указания ключа непосредственно в файле конфигурации.
</Warning>

```json theme={null}
{
  "mcpServers": {
    "avala": {
      "command": "npx",
      "args": ["-y", "@avala-ai/mcp-server"],
      "env": {
        "AVALA_API_KEY": "your-api-key"
      }
    }
  }
}
```

Убедитесь, что у вас установлено расширение [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) с включённой поддержкой MCP. Перезапустите VS Code для подключения нового сервера.

### Claude Code

Добавьте Avala MCP Server в Claude Code одной командой:

```bash theme={null}
claude mcp add avala -- npx -y @avala-ai/mcp-server
```

Установите API-ключ как переменную окружения:

```bash theme={null}
export AVALA_API_KEY="your-api-key"
```

Перезапустите Claude Code. Инструменты Avala будут доступны в вашей сессии.

### ChatGPT

<Info>
  Поддержка MCP в ChatGPT находится в процессе развития. Актуальные инструкции по настройке и доступность для вашего тарифного плана и региона смотрите в [документации OpenAI](https://platform.openai.com/docs).
</Info>

## Режим безопасности MCP

В целях безопасности MCP Server по умолчанию работает в режиме «только чтение». Инструменты, изменяющие данные, не регистрируются, если вы не включите их явно:

```bash theme={null}
AVALA_MCP_ENABLE_MUTATIONS=true
```

Эта переменная окружения может быть установлена в среде процесса MCP Server перед его запуском.

По умолчанию следующие операции записи и удаления заблокированы:

* `create_dataset`
* `create_agent`, `delete_agent`
* `create_annotation_issue`, `update_annotation_issue`, `delete_annotation_issue`
* `create_storage_config`, `test_storage_config`, `delete_storage_config`
* `create_webhook`, `delete_webhook`
* `create_export`
* `evaluate_quality`
* `compute_consensus`
* `fleet_register_device`, `fleet_acknowledge_alert`

## Доступные MCP-инструменты

После подключения AI-ассистенту доступны следующие инструменты:

| Инструмент                           | Описание                                                                                                          |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `list_datasets`                      | Список всех датасетов в рабочем пространстве.                                                                     |
| `get_dataset`                        | Получение подробной информации о конкретном датасете.                                                             |
| `create_dataset`                     | Создание нового датасета для аннотирования. <span className="text-orange-500 text-xs font-medium">mutation</span> |
| `list_projects`                      | Список всех проектов аннотирования.                                                                               |
| `get_project`                        | Получение полной информации о проекте.                                                                            |
| `create_export`                      | Запуск нового экспорта для датасета или проекта. *(требуется `AVALA_MCP_ENABLE_MUTATIONS=true`)*                  |
| `get_export_status`                  | Проверка статуса экспорта.                                                                                        |
| `list_exports`                       | Список всех экспортов.                                                                                            |
| `get_workspace_stats`                | Получение сводки по использованию рабочего пространства.                                                          |
| `list_tasks`                         | Список задач с опциональной фильтрацией.                                                                          |
| `get_task`                           | Получение информации о задаче.                                                                                    |
| `list_agents`                        | Список агентов автоматизации.                                                                                     |
| `get_agent`                          | Получение информации об агенте.                                                                                   |
| `create_agent`                       | Создание нового агента автоматизации. *(требуется `AVALA_MCP_ENABLE_MUTATIONS=true`)*                             |
| `delete_agent`                       | Удаление агента. *(требуется `AVALA_MCP_ENABLE_MUTATIONS=true`)*                                                  |
| `list_webhooks`                      | Список подписок на Webhook.                                                                                       |
| `create_webhook`                     | Создание подписки на Webhook. *(требуется `AVALA_MCP_ENABLE_MUTATIONS=true`)*                                     |
| `delete_webhook`                     | Удаление Webhook. *(требуется `AVALA_MCP_ENABLE_MUTATIONS=true`)*                                                 |
| `list_storage_configs`               | Список конфигураций хранилища.                                                                                    |
| `create_storage_config`              | Создание конфигурации хранилища. *(требуется `AVALA_MCP_ENABLE_MUTATIONS=true`)*                                  |
| `test_storage_config`                | Тестирование подключения к хранилищу. *(требуется `AVALA_MCP_ENABLE_MUTATIONS=true`)*                             |
| `delete_storage_config`              | Удаление конфигурации хранилища. *(требуется `AVALA_MCP_ENABLE_MUTATIONS=true`)*                                  |
| `list_quality_targets`               | Список целей качества для проекта.                                                                                |
| `evaluate_quality`                   | Оценка целей качества. *(требуется `AVALA_MCP_ENABLE_MUTATIONS=true`)*                                            |
| `get_consensus_summary`              | Получение сводки по консенсусу для проекта.                                                                       |
| `compute_consensus`                  | Запуск вычисления консенсуса. *(требуется `AVALA_MCP_ENABLE_MUTATIONS=true`)*                                     |
| `list_organizations`                 | Список организаций.                                                                                               |
| `get_organization`                   | Получение информации об организации.                                                                              |
| `list_slices`                        | Список срезов для владельца.                                                                                      |
| `get_slice`                          | Получение информации о срезе.                                                                                     |
| `list_annotation_issues_by_sequence` | Список проблем аннотирования для последовательности.                                                              |
| `create_annotation_issue`            | Создание новой проблемы аннотирования. *(требуется `AVALA_MCP_ENABLE_MUTATIONS=true`)*                            |
| `update_annotation_issue`            | Обновление проблемы аннотирования. *(требуется `AVALA_MCP_ENABLE_MUTATIONS=true`)*                                |
| `delete_annotation_issue`            | Удаление проблемы аннотирования. *(требуется `AVALA_MCP_ENABLE_MUTATIONS=true`)*                                  |
| `list_annotation_issues_by_dataset`  | Список проблем аннотирования для датасета.                                                                        |
| `get_annotation_issue_metrics`       | Получение метрик проблем для датасета.                                                                            |
| `list_qc_tools`                      | Список доступных инструментов QC.                                                                                 |

### Fleet (предварительная версия)

<Info>
  Инструменты Fleet находятся в предварительной версии и могут измениться. Они предоставляют доступ на чтение и запись к устройствам, записям, событиям, оповещениям и правилам автопарка.
</Info>

| Инструмент                | Описание                                                                                                       |
| ------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `fleet_list_devices`      | Список устройств автопарка с опциональными фильтрами.                                                          |
| `fleet_get_device`        | Получение подробной информации об устройстве автопарка.                                                        |
| `fleet_list_recordings`   | Список записей автопарка с опциональными фильтрами.                                                            |
| `fleet_get_recording`     | Получение подробной информации о записи.                                                                       |
| `fleet_list_events`       | Список событий автопарка с опциональными фильтрами.                                                            |
| `fleet_list_alerts`       | Список оповещений автопарка с опциональными фильтрами.                                                         |
| `fleet_list_rules`        | Список правил автопарка с опциональными фильтрами.                                                             |
| `fleet_register_device`   | Регистрация нового устройства автопарка. <span className="text-orange-500 text-xs font-medium">mutation</span> |
| `fleet_acknowledge_alert` | Подтверждение оповещения автопарка. <span className="text-orange-500 text-xs font-medium">mutation</span>      |

## Определения инструментов

Подробные схемы для каждого MCP-инструмента. Все инструменты возвращают JSON в виде текстового содержимого.

### list\_datasets

Список всех датасетов в рабочем пространстве.

**Параметры:**

* `dataType` (string, optional) — Фильтр по типу данных (`image`, `video`, `lidar`, `mcap`, `splat`)
* `name` (string, optional) — Фильтр по названию датасета (частичное совпадение)
* `status` (string, optional) — Фильтр по статусу датасета
* `visibility` (string, optional) — Фильтр по видимости (`private` или `public`)
* `limit` (number, optional) — Максимальное количество возвращаемых датасетов
* `cursor` (string, optional) — Курсор пагинации из предыдущего запроса

**Пример ответа:**

```json theme={null}
{
  "datasets": [
    {
      "uid": "d8f2e1a4-3b7c-4e9f-a1d6-5c8b9e0f2a3d",
      "name": "Urban Driving Q1",
      "slug": "urban-driving-q1",
      "dataType": "lidar",
      "itemCount": 12450,
      "visibility": "private",
      "status": "active",
      "createdAt": "2026-01-15T08:30:00Z"
    },
    {
      "uid": "a1b2c3d4-5e6f-7a8b-9c0d-e1f2a3b4c5d6",
      "name": "Warehouse Cameras",
      "slug": "warehouse-cameras",
      "dataType": "image",
      "itemCount": 34200,
      "visibility": "private",
      "status": "active",
      "createdAt": "2026-02-20T14:15:00Z"
    }
  ],
  "cursor": "eyJpZCI6MTAwfQ=="
}
```

### get\_dataset

Получение подробной информации о конкретном датасете.

**Параметры:**

* `uid` (string, required) — Уникальный идентификатор (UUID) датасета

**Пример ответа:**

```json theme={null}
{
  "uid": "d8f2e1a4-3b7c-4e9f-a1d6-5c8b9e0f2a3d",
  "name": "Urban Driving Q1",
  "slug": "urban-driving-q1",
  "dataType": "lidar",
  "itemCount": 12450,
  "sequenceCount": 85,
  "visibility": "private",
  "status": "active",
  "owner": "acme-robotics",
  "createdAt": "2026-01-15T08:30:00Z",
  "updatedAt": "2026-03-10T11:45:00Z"
}
```

**Ответ с ошибкой (недопустимый UID):**

```json theme={null}
{
  "error": "not_found",
  "message": "Dataset with UID 'invalid-uid-here' was not found.",
  "status": 404
}
```

### list\_projects

Список всех проектов аннотирования.

**Параметры:**

* `limit` (number, optional) — Максимальное количество возвращаемых проектов
* `cursor` (string, optional) — Курсор пагинации из предыдущего запроса

### get\_project

Получение подробной информации о конкретном проекте.

**Параметры:**

* `uid` (string, required) — Уникальный идентификатор (UUID) проекта

### create\_dataset

Создание нового датасета для аннотирования.

**Параметры:**

* `name` (string, required) — Отображаемое имя датасета
* `slug` (string, required) — URL-совместимый идентификатор датасета
* `dataType` (string, required) — Тип данных: `image`, `video`, `lidar` или `mcap`
* `visibility` (string, optional) — Видимость датасета: `private` или `public` (по умолчанию: `private`)
* `createMetadata` (boolean, optional) — Создавать ли метаданные датасета (по умолчанию: true)
* `providerConfig` (object, optional) — Конфигурация облачного провайдера хранилища
* `ownerName` (string, optional) — Имя пользователя или email владельца датасета

### create\_export

Запуск нового экспорта для датасета или проекта.

**Параметры:**

* `project` (string, optional) — UID проекта для экспорта
* `dataset` (string, optional) — UID датасета для экспорта

**Пример ответа:**

```json theme={null}
{
  "uid": "e3a1b2c4-9d8f-4e7a-b6c5-d4e3f2a1b0c9",
  "status": "pending",
  "project": "770a9600-a40d-63f6-c938-668877660000",
  "createdAt": "2026-03-19T10:00:00Z"
}
```

### get\_export\_status

Проверка статуса экспорта.

**Параметры:**

* `uid` (string, required) — Уникальный идентификатор (UUID) экспорта

**Пример ответа:**

```json theme={null}
{
  "uid": "e3a1b2c4-9d8f-4e7a-b6c5-d4e3f2a1b0c9",
  "status": "completed",
  "project": "770a9600-a40d-63f6-c938-668877660000",
  "downloadUrl": "https://api.avala.ai/exports/e3a1b2c4-9d8f-4e7a-b6c5-d4e3f2a1b0c9/download",
  "fileSize": 52428800,
  "createdAt": "2026-03-19T10:00:00Z",
  "completedAt": "2026-03-19T10:02:34Z"
}
```

### list\_exports

Список всех экспортов в рабочем пространстве.

**Параметры:**

* `limit` (number, optional) — Максимальное количество возвращаемых экспортов
* `cursor` (string, optional) — Курсор пагинации из предыдущего запроса

### get\_workspace\_stats

Быстрая проверка содержимого рабочего пространства (датасеты, проекты, экспорты).

**Параметры:** нет

**Пример ответа:**

```json theme={null}
{
  "datasets": 14,
  "projects": 7,
  "exports": 23,
  "tasks": {
    "total": 8420,
    "pending": 312,
    "completed": 7856,
    "inProgress": 252
  },
  "members": 18
}
```

### list\_tasks

Список задач с опциональной фильтрацией по проекту или статусу.

**Параметры:**

* `project` (string, optional) — Фильтр по UID проекта
* `status` (string, optional) — Фильтр по статусу задачи
* `limit` (number, optional) — Максимальное количество возвращаемых задач
* `cursor` (string, optional) — Курсор пагинации из предыдущего запроса

**Пример ответа:**

```json theme={null}
{
  "tasks": [
    {
      "uid": "t1a2b3c4-d5e6-f7a8-b9c0-d1e2f3a4b5c6",
      "status": "completed",
      "project": "770a9600-a40d-63f6-c938-668877660000",
      "assignee": "jane.doe@acme.com",
      "completedAt": "2026-03-18T16:30:00Z"
    },
    {
      "uid": "t7e8f9a0-b1c2-d3e4-f5a6-b7c8d9e0f1a2",
      "status": "pending",
      "project": "770a9600-a40d-63f6-c938-668877660000",
      "assignee": null,
      "completedAt": null
    }
  ],
  "cursor": "eyJ0YXNrSWQiOjUwfQ=="
}
```

### get\_task

Получение подробной информации о конкретной задаче.

**Параметры:**

* `uid` (string, required) — Уникальный идентификатор (UUID) задачи

### list\_agents

Список всех агентов автоматизации, настроенных в вашем рабочем пространстве.

**Параметры:**

* `limit` (number, optional) — Максимальное количество возвращаемых агентов
* `cursor` (string, optional) — Курсор пагинации из предыдущего запроса

### get\_agent

Получение подробной информации о конкретном агенте автоматизации.

**Параметры:**

* `uid` (string, required) — Уникальный идентификатор (UUID) агента

### create\_agent

Создание нового агента автоматизации с подписками на события и URL обратного вызова.

**Параметры:**

* `name` (string, required) — Имя агента
* `events` (string\[], required) — Список типов событий, на которые подписывается агент
* `callbackUrl` (string, optional) — URL для получения обратных вызовов по событиям
* `description` (string, optional) — Описание агента
* `project` (string, optional) — UID проекта для ограничения области агента
* `taskTypes` (string\[], optional) — Типы задач, обрабатываемые агентом

### delete\_agent

Удаление агента автоматизации по его UID.

**Параметры:**

* `uid` (string, required) — Уникальный идентификатор (UUID) удаляемого агента

### list\_webhooks

Список всех подписок на Webhook в вашем рабочем пространстве.

**Параметры:**

* `limit` (number, optional) — Максимальное количество возвращаемых Webhook
* `cursor` (string, optional) — Курсор пагинации из предыдущего запроса

### create\_webhook

Создание новой подписки на Webhook для определённых событий.

**Параметры:**

* `targetUrl` (string, required) — URL для получения Webhook-доставок
* `events` (string\[], required) — Список типов событий для подписки

### delete\_webhook

Удаление подписки на Webhook по её UID.

**Параметры:**

* `uid` (string, required) — Уникальный идентификатор (UUID) удаляемого Webhook

### list\_storage\_configs

Список всех конфигураций хранилища в вашем рабочем пространстве.

**Параметры:**

* `limit` (number, optional) — Максимальное количество возвращаемых конфигураций
* `cursor` (string, optional) — Курсор пагинации из предыдущего запроса

### create\_storage\_config

Создание новой конфигурации хранилища (S3 или Google Cloud Storage).

**Параметры:**

* `name` (string, required) — Имя конфигурации хранилища
* `provider` (string, required) — Тип провайдера хранилища (`s3` или `gcs`)
* `s3BucketName` (string, optional) — Имя S3-бакета
* `s3BucketRegion` (string, optional) — Регион S3-бакета
* `s3BucketPrefix` (string, optional) — Префикс ключа S3
* `s3AccessKeyId` (string, optional) — Идентификатор ключа доступа S3 (надёжно хранится на стороне сервера)
* `s3SecretAccessKey` (string, optional) — Секретный ключ доступа S3 (надёжно хранится на стороне сервера)
* `s3IsAccelerated` (boolean, optional) — Включить S3 Transfer Acceleration
* `gcStorageBucketName` (string, optional) — Имя бакета Google Cloud Storage
* `gcStoragePrefix` (string, optional) — Префикс Google Cloud Storage
* `gcStorageAuthJsonContent` (string, optional) — JSON-учётные данные сервисного аккаунта GCS (надёжно хранятся на стороне сервера)

### test\_storage\_config

Тестирование подключения к конфигурации хранилища.

**Параметры:**

* `uid` (string, required) — Уникальный идентификатор (UUID) конфигурации хранилища для тестирования

### delete\_storage\_config

Удаление конфигурации хранилища по её UID.

**Параметры:**

* `uid` (string, required) — Уникальный идентификатор (UUID) удаляемой конфигурации хранилища

### list\_quality\_targets

Список целей качества, настроенных для конкретного проекта.

**Параметры:**

* `projectUid` (string, required) — Уникальный идентификатор (UUID) проекта
* `limit` (number, optional) — Максимальное количество возвращаемых целей качества
* `cursor` (string, optional) — Курсор пагинации из предыдущего запроса

### evaluate\_quality

Оценка всех целей качества для проекта и возврат их текущего статуса.

**Параметры:**

* `projectUid` (string, required) — Уникальный идентификатор (UUID) оцениваемого проекта

### get\_consensus\_summary

Получение сводки по консенсусу для проекта, включая средние/медианные оценки и распределение.

**Параметры:**

* `projectUid` (string, required) — Уникальный идентификатор (UUID) проекта

### compute\_consensus

Запуск вычисления консенсуса для проекта.

**Параметры:**

* `projectUid` (string, required) — Уникальный идентификатор (UUID) проекта

### list\_organizations

Список всех организаций, членом которых вы являетесь.

**Параметры:**

* `limit` (number, optional) — Максимальное количество возвращаемых организаций
* `cursor` (string, optional) — Курсор пагинации из предыдущего запроса

### get\_organization

Получение подробной информации о конкретной организации.

**Параметры:**

* `slug` (string, required) — Слаг-идентификатор организации

### list\_slices

Список срезов для владельца (пользователя или организации).

**Параметры:**

* `owner` (string, required) — Имя владельца (слаг пользователя или организации)
* `limit` (number, optional) — Максимальное количество возвращаемых срезов
* `cursor` (string, optional) — Курсор пагинации из предыдущего запроса

### get\_slice

Получение подробной информации о конкретном срезе.

**Параметры:**

* `owner` (string, required) — Имя владельца (слаг пользователя или организации)
* `slug` (string, required) — Слаг среза

### list\_annotation\_issues\_by\_sequence

Список всех проблем аннотирования для конкретной последовательности.

**Параметры:**

* `sequenceUid` (string, required) — UUID последовательности
* `datasetItemUid` (string, optional) — Фильтр по UUID элемента датасета
* `projectUid` (string, optional) — Фильтр по UUID проекта

### create\_annotation\_issue

Создание новой проблемы аннотирования для последовательности.

**Параметры:**

* `sequenceUid` (string, required) — UUID последовательности
* `toolUid` (string, required) — UUID инструмента аннотирования
* `problemUid` (string, required) — UUID типа проблемы
* `datasetItemUid` (string, optional) — UUID элемента датасета
* `projectUid` (string, optional) — UUID проекта
* `priority` (string, optional) — Уровень приоритета: `lowest`, `low`, `medium`, `high`, `highest`
* `severity` (string, optional) — Уровень серьёзности: `critical`, `moderate`
* `description` (string, optional) — Описание проблемы
* `wrongClass` (string, optional) — Неверная метка класса
* `correctClass` (string, optional) — Верная метка класса
* `objectUid` (string, optional) — UUID объекта аннотации
* `shouldReAnnotate` (boolean, optional) — Требуется ли повторное аннотирование
* `shouldDelete` (boolean, optional) — Требуется ли удаление аннотации
* `framesAffected` (string, optional) — Затронутые кадры

### update\_annotation\_issue

Обновление существующей проблемы аннотирования (статус, приоритет и т. д.).

**Параметры:**

* `sequenceUid` (string, required) — UUID последовательности
* `issueUid` (string, required) — UUID проблемы аннотирования
* `status` (string, optional) — Статус: `open`, `relabeling`, `in_review`, `completed`, `cant_reproduce`, `awaiting_feedback`, `no_action_taken`
* `priority` (string, optional) — Уровень приоритета: `lowest`, `low`, `medium`, `high`, `highest`
* `severity` (string, optional) — Уровень серьёзности: `critical`, `moderate`
* `description` (string, optional) — Обновлённое описание
* `toolUid` (string, optional) — UUID инструмента аннотирования
* `problemUid` (string, optional) — UUID типа проблемы
* `wrongClass` (string, optional) — Неверная метка класса
* `framesAffected` (string, optional) — Затронутые кадры

### delete\_annotation\_issue

Удаление проблемы аннотирования.

**Параметры:**

* `sequenceUid` (string, required) — UUID последовательности
* `issueUid` (string, required) — UUID удаляемой проблемы аннотирования

### list\_annotation\_issues\_by\_dataset

Список всех проблем аннотирования для датасета.

**Параметры:**

* `owner` (string, required) — Имя пользователя владельца датасета
* `datasetSlug` (string, required) — Слаг датасета
* `sequenceUid` (string, optional) — Фильтр по UUID последовательности

### get\_annotation\_issue\_metrics

Получение агрегированных метрик проблем аннотирования для датасета (количество по статусу/приоритету/серьёзности, время закрытия).

**Параметры:**

* `owner` (string, required) — Имя пользователя владельца датасета
* `datasetSlug` (string, required) — Слаг датасета
* `sequenceUid` (string, optional) — Фильтр по UUID последовательности

### list\_qc\_tools

Список доступных инструментов QC-аннотирования для заданного типа датасета.

**Параметры:**

* `datasetType` (string, required) — Тип датасета (например, `lidar`, `image`, `video`)

### fleet\_list\_devices

Список устройств автопарка с опциональными фильтрами.

**Параметры:**

* `status` (string, optional) — Фильтр по статусу устройства (`online`, `offline`, `maintenance`)
* `type` (string, optional) — Фильтр по типу устройства
* `limit` (number, optional) — Максимальное количество возвращаемых устройств
* `cursor` (string, optional) — Курсор пагинации

**Пример ответа:**

```json theme={null}
{
  "devices": [
    {
      "uid": "dev-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Forklift Sensor Unit 12",
      "type": "lidar-sensor",
      "status": "online",
      "firmwareVersion": "2.4.1",
      "lastSeenAt": "2026-03-19T09:55:00Z",
      "tags": ["warehouse-a", "forklift"]
    },
    {
      "uid": "dev-b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "name": "Dock Camera 3",
      "type": "camera",
      "status": "offline",
      "firmwareVersion": "1.8.0",
      "lastSeenAt": "2026-03-18T23:10:00Z",
      "tags": ["dock", "exterior"]
    }
  ],
  "cursor": "eyJkZXZpY2VJZCI6MjB9"
}
```

### fleet\_get\_device

Получение подробной информации о конкретном устройстве автопарка.

**Параметры:**

* `uid` (string, required) — Уникальный идентификатор устройства

### fleet\_list\_recordings

Список записей автопарка с опциональными фильтрами.

**Параметры:**

* `device` (string, optional) — Фильтр по UID устройства
* `status` (string, optional) — Фильтр по статусу записи
* `limit` (number, optional) — Максимальное количество возвращаемых записей
* `cursor` (string, optional) — Курсор пагинации

### fleet\_get\_recording

Получение подробной информации о конкретной записи.

**Параметры:**

* `uid` (string, required) — Уникальный идентификатор записи

### fleet\_list\_events

Список событий автопарка с опциональными фильтрами.

**Параметры:**

* `recording` (string, optional) — Фильтр по UID записи
* `device` (string, optional) — Фильтр по UID устройства
* `type` (string, optional) — Фильтр по типу события
* `severity` (string, optional) — Фильтр по серьёзности
* `limit` (number, optional) — Максимальное количество возвращаемых событий
* `cursor` (string, optional) — Курсор пагинации

### fleet\_list\_alerts

Список оповещений автопарка с опциональными фильтрами.

**Параметры:**

* `status` (string, optional) — Фильтр по статусу оповещения (`open`, `acknowledged`, `resolved`)
* `severity` (string, optional) — Фильтр по серьёзности (`info`, `warning`, `error`, `critical`)
* `device` (string, optional) — Фильтр по UID устройства
* `rule` (string, optional) — Фильтр по UID правила
* `limit` (number, optional) — Максимальное количество возвращаемых оповещений
* `cursor` (string, optional) — Курсор пагинации

**Пример ответа:**

```json theme={null}
{
  "alerts": [
    {
      "uid": "alert-c3d4e5f6-a7b8-9012-cdef-123456789012",
      "status": "open",
      "severity": "warning",
      "device": "dev-a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "rule": "rule-d4e5f6a7-b8c9-0123-defa-234567890123",
      "message": "Device temperature exceeded threshold (72C)",
      "createdAt": "2026-03-19T08:45:00Z"
    },
    {
      "uid": "alert-e5f6a7b8-c9d0-1234-efab-345678901234",
      "status": "acknowledged",
      "severity": "critical",
      "device": "dev-b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "rule": "rule-f6a7b8c9-d0e1-2345-fabc-456789012345",
      "message": "Device offline for more than 24 hours",
      "createdAt": "2026-03-18T09:00:00Z",
      "acknowledgedAt": "2026-03-18T10:30:00Z"
    }
  ],
  "cursor": "eyJhbGVydElkIjoxMH0="
}
```

### fleet\_list\_rules

Список правил автопарка с опциональными фильтрами.

**Параметры:**

* `enabled` (boolean, optional) — Фильтр по статусу включения
* `limit` (number, optional) — Максимальное количество возвращаемых правил
* `cursor` (string, optional) — Курсор пагинации

### fleet\_register\_device

Регистрация нового устройства автопарка.

**Параметры:**

* `name` (string, required) — Имя устройства
* `type` (string, required) — Тип устройства
* `firmwareVersion` (string, optional) — Версия прошивки
* `tags` (string\[], optional) — Теги устройства

### fleet\_acknowledge\_alert

Подтверждение оповещения автопарка.

**Параметры:**

* `uid` (string, required) — Уникальный идентификатор подтверждаемого оповещения

## Рецепты

Многошаговые рабочие процессы, которые можно выполнять на естественном языке. Каждый рецепт показывает вызовы инструментов, которые ассистент выполняет за кулисами.

### Рецепт 1: Проверка состояния датасетов

Попросите ассистента: *«Проведи проверку состояния моего рабочего пространства — сколько у меня датасетов и в каких больше всего элементов?»*

**Шаг 1** — Ассистент вызывает `get_workspace_stats` для получения обзора.

```json theme={null}
{
  "datasets": 14,
  "projects": 7,
  "exports": 23,
  "tasks": { "total": 8420, "pending": 312, "completed": 7856, "inProgress": 252 },
  "members": 18
}
```

**Шаг 2** — Ассистент вызывает `list_datasets` с `limit: 50` для получения всех датасетов.

**Шаг 3** — Ассистент сортирует результаты по `itemCount` и представляет ранжированную сводку:

> У вас 14 датасетов. Три самых больших:
>
> 1. **Warehouse Cameras** — 34 200 элементов (image)
> 2. **Urban Driving Q1** — 12 450 элементов (lidar)
> 3. **Parking Lot Footage** — 8 900 элементов (video)

### Рецепт 2: Экспорт и скачивание

Попросите ассистента: *«Экспортируй проект Urban Driving Q1 и сообщи, когда будет готово.»*

**Шаг 1** — Ассистент вызывает `list_projects` для поиска UID проекта, соответствующего «Urban Driving Q1».

**Шаг 2** — Ассистент вызывает `create_export` с UID проекта.

```json theme={null}
{
  "uid": "e3a1b2c4-9d8f-4e7a-b6c5-d4e3f2a1b0c9",
  "status": "pending",
  "project": "770a9600-a40d-63f6-c938-668877660000",
  "createdAt": "2026-03-19T10:00:00Z"
}
```

**Шаг 3** — Ассистент опрашивает `get_export_status` до тех пор, пока статус не изменится на `completed`.

```json theme={null}
{
  "uid": "e3a1b2c4-9d8f-4e7a-b6c5-d4e3f2a1b0c9",
  "status": "completed",
  "downloadUrl": "https://api.avala.ai/exports/e3a1b2c4-9d8f-4e7a-b6c5-d4e3f2a1b0c9/download",
  "fileSize": 52428800,
  "completedAt": "2026-03-19T10:02:34Z"
}
```

**Шаг 4** — Ассистент предоставляет ссылку на скачивание и размер файла.

> Ваш экспорт готов (50 МБ). Скачайте его здесь: `https://api.avala.ai/exports/.../download`

### Рецепт 3: Аудит качества по всем проектам

Попросите ассистента: *«Оцени цели качества для всех моих проектов и отметь те, которые не проходят.»*

**Шаг 1** — Ассистент вызывает `list_projects` для получения всех проектов.

**Шаг 2** — Для каждого проекта ассистент вызывает `evaluate_quality` с UID проекта.

**Шаг 3** — Ассистент агрегирует результаты и выделяет несоответствия:

> 5 из 7 проектов проходят все цели качества. Два требуют внимания:
>
> * **Sidewalk Segmentation** — цель «Точность меток» на 88% (порог: 95%)
> * **Fleet Camera Review** — цель «Оценка консенсуса» на 0,72 (порог: 0,85)

### Рецепт 4: Мониторинг устройств автопарка

Попросите ассистента: *«Покажи все неподтверждённые оповещения автопарка, сгруппированные по серьёзности.»*

**Шаг 1** — Ассистент вызывает `fleet_list_alerts` с `status: "open"`.

**Шаг 2** — Ассистент группирует и форматирует ответ:

> **Critical (1)**
>
> * Dock Camera 3 — «Устройство офлайн более 24 часов» (с 18 марта)
>
> **Warning (2)**
>
> * Forklift Sensor Unit 12 — «Температура устройства превысила пороговое значение (72C)» (с 19 марта)
> * Rooftop LiDAR 1 — «Мало места на диске (\< 5%)» (с 19 марта)

**Шаг 3** — Вы можете продолжить: *«Подтверди все оповещения уровня warning.»* Ассистент вызовет `fleet_acknowledge_alert` для каждого UID оповещения уровня warning.

### Рецепт 5: Сортировка проблем аннотирования

Попросите ассистента: *«Получи метрики проблем аннотирования для датасета urban-driving-q1 и покажи разбивку.»*

**Шаг 1** — Ассистент вызывает `get_annotation_issue_metrics` с владельцем и слагом датасета.

**Шаг 2** — Ассистент представляет форматированную сводку:

> **Urban Driving Q1 — Метрики проблем**
>
> По статусу: 12 open, 5 in review, 3 relabeling, 45 completed
> По серьёзности: 8 critical, 57 moderate
> По приоритету: 2 highest, 6 high, 18 medium, 25 low, 14 lowest
> Среднее время закрытия: 4,2 часа

**Шаг 3** — Вы продолжаете: *«Покажи открытые critical проблемы.»* Ассистент вызывает `list_annotation_issues_by_dataset` с фильтрами и показывает результаты.

## Примеры промптов

Вот несколько примеров промптов на естественном языке, которые можно использовать с любым MCP-совместимым клиентом:

```
List all my datasets
```

```
Show me the details of dataset "autonomous-driving-v3"
```

```
What's the status of the "Lidar QA" project?
```

```
Create an export for project 770a9600-a40d-63f6-c938-668877660000
```

```
How many exports do I have?
```

```
Show my workspace stats
```

```
List all my automation agents
```

```
Create a webhook for task.completed events pointing to https://my-server.com/hooks
```

```
Show me the quality targets for project proj_abc123
```

```
What's the consensus score summary for my annotation project?
```

```
List all organizations I belong to
```

```
Show workspace storage config list
```

```
List all online fleet devices
```

```
Show me open critical alerts across the fleet
```

```
Register a new lidar-sensor device called "Rooftop Unit 5"
```

AI-ассистент вызовет соответствующий MCP-инструмент Avala, обработает ответ и представит результаты в удобочитаемом формате. Вы можете выполнять запросы последовательно в одном разговоре — например, показать список датасетов, выбрать один из них, а затем проверить статус экспорта.

## Устранение неполадок

### `AVALA_API_KEY` не установлен

Если переменная окружения `AVALA_API_KEY` отсутствует, MCP Server немедленно завершается с кодом ошибки 1. Убедитесь, что ключ задан в блоке `env` конфигурации MCP или экспортирован в вашей оболочке перед запуском сервера.

```
Error: AVALA_API_KEY environment variable is required
```

### Мутирующие инструменты не отображаются

Если такие инструменты, как `create_export`, `create_agent` или `fleet_register_device`, отсутствуют в списке инструментов, необходимо установить `AVALA_MCP_ENABLE_MUTATIONS=true` в среде сервера. Добавьте это в блок `env` файла конфигурации MCP:

```json theme={null}
{
  "env": {
    "AVALA_API_KEY": "your-api-key",
    "AVALA_MCP_ENABLE_MUTATIONS": "true"
  }
}
```

### `npx` не найден или неправильная версия Node.js

MCP Server требует Node.js 18 или новее. Если вы видите `npx: command not found` или ошибки синтаксиса модулей, проверьте версию Node.js:

```bash theme={null}
node --version  # Must be v18.0.0 or later
```

### Устаревший кэш MCP Server

Если вы недавно обновили пакет `@avala-ai/mcp-server`, но по-прежнему наблюдаете старое поведение или отсутствие инструментов, npx может использовать кэшированную версию. Принудительно выполните свежую установку:

```bash theme={null}
npx --yes @avala-ai/mcp-server@latest
```

Затем перезапустите MCP-клиент.

### API-ключ недействителен или просрочен

Если вызовы инструментов возвращают `401 Unauthorized`, ваш API-ключ может быть недействительным, просроченным или отозванным. Создайте новый ключ в [Mission Control](https://avala.ai/settings?section=security) в разделе **Settings > Security** и обновите конфигурацию MCP.

<Info>
  Avala MCP Server является открытым исходным кодом. Посетите [репозиторий GitHub](https://github.com/avala-ai/avala-sdk-ts), чтобы просмотреть исходный код или внести свой вклад.
</Info>