> ## 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

> 通过 Model Context Protocol 在 Claude、Claude Code、Cursor、VS Code 和 ChatGPT 中使用 Avala

[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 是一个开放标准，允许 AI 助手与外部工具和数据源进行交互。Avala 的 MCP Server 将您的数据集、项目和导出公开为工具，任何 MCP 兼容的客户端都可以调用，让您无需切换上下文即可通过自然语言管理标注工作流。

这意味着您可以让 Claude「列出我所有的数据集」，在 Cursor 中创建导出，或使用 VS Code 查看项目状态——所有这些都由您已在使用的 Avala API 提供支持。

## 前提条件

* 您的机器上已安装 **Node.js** 18 或更高版本
* 一个 **Avala API 密钥**（在 [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"
      }
    }
  }
}
```

确保您已安装启用了 MCP 支持的 [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) 扩展。重启 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>
  ChatGPT 的 MCP 支持仍在发展中。有关最新的设置说明以及在您所在的套餐和地区的可用性，请参阅 [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) — 数据集所有者的用户名或邮箱

### 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) — 接收 Webhook 投递的 URL
* `events` (string\[], required) — 要订阅的事件类型列表

### delete\_webhook

按 UID 删除 Webhook 订阅。

**参数：**

* `uid` (string, required) — 要删除的 Webhook 的唯一标识符（UUID）

### 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 访问密钥 ID（在服务器端安全存储）
* `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) — GCS 服务账户 JSON 凭据（在服务器端安全存储）

### 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) — 组织的 slug 标识符

### list\_slices

列出所有者（用户或组织）的切片。

**参数：**

* `owner` (string, required) — 所有者名称（用户或组织的 slug）
* `limit` (number, optional) — 返回的最大切片数量
* `cursor` (string, optional) — 来自上一次请求的分页游标

### get\_slice

获取特定切片的详细信息。

**参数：**

* `owner` (string, required) — 所有者名称（用户或组织的 slug）
* `slug` (string, required) — 切片的 slug

### 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) — 数据集的 slug
* `sequenceUid` (string, optional) — 按序列 UUID 筛选

### get\_annotation\_issue\_metrics

获取数据集中标注问题的聚合指标（状态/优先级/严重程度计数、关闭时间）。

**参数：**

* `owner` (string, required) — 数据集所有者的用户名
* `datasetSlug` (string, required) — 数据集的 slug
* `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` 查找与「Urban Driving Q1」匹配的项目 UID。

**步骤 2** — 助手使用项目 UID 调用 `create_export`。

```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 MB）。在此处下载：`https://api.avala.ai/exports/.../download`

### 示例 3：跨项目质量审计

向助手提问：*「评估我所有项目的质量目标，标记未通过的项目。」*

**步骤 1** — 助手调用 `list_projects` 获取所有项目。

**步骤 2** — 对于每个项目，助手使用项目 UID 调用 `evaluate_quality`。

**步骤 3** — 助手汇总结果并突出显示未通过的项目：

> 7 个项目中有 5 个通过了所有质量目标。两个需要关注：
>
> * **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 小时」（自 3 月 18 日起）
>
> **Warning（2 条）**
>
> * Forklift Sensor Unit 12 — 「设备温度超过阈值（72C）」（自 3 月 19 日起）
> * Rooftop LiDAR 1 — 「磁盘空间不足（\< 5%）」（自 3 月 19 日起）

**步骤 3** — 您可以继续提问：*「确认所有 warning 级别的警报。」* 助手将为每个 warning 警报的 UID 调用 `fleet_acknowledge_alert`。

### 示例 5：标注问题分类

向助手提问：*「获取 urban-driving-q1 数据集的标注问题指标，显示详细分类。」*

**步骤 1** — 助手使用所有者和数据集 slug 调用 `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 助手将调用相应的 Avala MCP 工具，处理响应，并以易读的格式呈现结果。您可以在一次对话中连续发出请求——例如，列出数据集，选择一个，然后查看导出状态。

## 故障排除

### `AVALA_API_KEY` 未设置

如果 `AVALA_API_KEY` 环境变量缺失，MCP Server 会立即以错误代码 1 退出。请确保在 MCP 配置的 `env` 块中设置了密钥，或在启动服务器之前在 shell 中导出了该变量。

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

### 变更类工具未显示

如果 `create_export`、`create_agent` 或 `fleet_register_device` 等工具未出现在工具列表中，您需要在服务器环境中设置 `AVALA_MCP_ENABLE_MUTATIONS=true`。将其添加到 MCP 配置文件的 `env` 块中：

```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>