AIRIOT MCP Server

基于 Model Context Protocol (MCP) 的 AIRIOT IoT 平台服务器，为 AI 助手提供完整的 AIRIOT 平台访问能力。

功能特性

核心能力

• 📊 数据表管理: 查询、创建、更新、删除数据表
• 📝 记录操作: 对表记录进行 CRUD 操作（含批量）
• 🏷️ 属性点查询: 查询表和记录的属性点定义
• 📈 时序数据: 查询设备最新数据和历史数据
• 📊 统计分析: 设备在线状态统计

MCP 能力支持

• 🔧 Tools: 30+ 工具接口
• 📁 Resources: 10+ 资源端点，支持直接读取平台数据作为上下文
• 💬 Prompts: 12+ 预定义提示词模板

新增功能

• 🚨 告警管理: 查询、确认、解除告警
• 📁 文件管理: 上传、下载、删除文件
• 🎮 设备控制: 发送控制命令
• 📄 报表管理: 创建、执行、管理报表
• 👤 用户管理: 查询用户信息

开发体验

• ⚙️ 配置文件: 支持 .airiotrc.json 配置文件
• 📝 日志系统: 分级日志，便于调试
• 🛡️ 错误处理: 完善的错误类型和错误恢复机制

安装

cd airiot-mcp-server
npm install
npm run build

配置

方式一：配置文件（推荐）

在项目根目录创建 .airiotrc.json 文件：

{
  "baseUrl": "https://your-airiot-server.com",
  "projectId": "your-project-id",
  "token": "your-api-token",
  "timeout": 30000,
  "logLevel": "info",
  "retries": 3
}

可参考 .airiotrc.json.example 文件。

方式二：环境变量

创建 .env 文件或设置以下环境变量：

# AIRIOT 服务器地址（必填）
export AIRIOT_BASE_URL="https://your-airiot-server.com"

# 项目ID（必填）
export AIRIOT_PROJECT_ID="your-project-id"

# 认证方式1: 使用Token（推荐）
export AIRIOT_TOKEN="your-api-token"

# 认证方式2: 使用用户名密码
export AIRIOT_USERNAME="your-username"
export AIRIOT_PASSWORD="your-password"

# 日志级别（可选）
export AIRIOT_LOG_LEVEL="info"

MCP 配置

在 Claude Desktop 配置文件中添加：

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

{
  "mcpServers": {
    "airiot": {
      "command": "node",
      "args": [
        "/path/to/airiot-mcp-server/dist/index.js"
      ],
      "env": {
        "AIRIOT_BASE_URL": "https://your-airiot-server.com",
        "AIRIOT_PROJECT_ID": "your-project-id",
        "AIRIOT_TOKEN": "your-api-token"
      }
    }
  }
}

MCP 能力

Resources（资源）

AI 可以直接读取以下资源作为上下文：

URI	描述
airiot://tables	数据表列表
airiot://tables/{id}	数据表详情
airiot://table/{tableName}/records	表记录列表
airiot://devices	设备列表
airiot://device/{id}	设备详情
airiot://device/{deviceId}/tag/{tagId}/latest	最新数据
airiot://stats/online	在线统计

Prompts（提示词模板）

预定义的常用查询模板：

模板名	描述
list_tables	列出数据表
describe_table	获取表结构
query_devices	查询设备列表
get_realtime_data	获取实时数据
get_history_trend	获取历史趋势
device_online_summary	设备在线摘要
query_alarms	查询告警
create_device	创建设备
update_device_status	更新设备状态

可用工具

表管理

工具名	描述
get_tables	查询数据表列表
get_table_by_id	根据ID查询单个表
create_table	创建新数据表
update_table	更新表信息
delete_table	删除数据表

记录管理

工具名	描述
get_table_records	查询表记录列表
get_record_by_id	根据ID查询单条记录
create_record	创建新记录
update_record	更新记录
delete_record	删除单条记录
batch_delete_records	批量删除记录

属性点查询

工具名	描述
get_table_tags	查询表的属性点定义
get_record_tags	查询记录的属性点

时序数据

工具名	描述
get_latest_data	查询最新数据
get_history_data	查询历史时序数据

告警管理

工具名	描述
get_alarms	查询告警列表
get_alarm_by_id	查询告警详情
acknowledge_alarm	确认告警
resolve_alarm	解除告警

文件管理

工具名	描述
upload_file	上传文件
get_file_info	获取文件信息
delete_file	删除文件

设备控制

工具名	描述
send_control_command	发送控制命令
send_batch_control_commands	批量发送控制命令

报表管理

工具名	描述
get_reports	查询报表列表
get_report_by_id	查询报表详情
execute_report	执行报表生成
create_report	创建报表
update_report	更新报表
delete_report	删除报表

用户管理

工具名	描述
get_current_user	获取当前用户信息
get_users	获取用户列表

使用示例

查询所有数据表

调用 get_tables 工具，参数：
{
  "limit": 50,
  "sort": { "createTime": -1 }
}

查询特定表的记录

调用 get_table_records 工具，参数：
{
  "tableName": "device",
  "filter": { "status": "online" },
  "limit": 100
}

创建新表

创建表需要提供完整的 schema 定义：

调用 create_table 工具，参数：
{
  "id": "my_table",
  "title": "我的数据表",
  "showField": "name",
  "schema": {
    "form": ["name", "status", "createTime"],
    "key": "myTable",
    "listFields": ["name", "status", "createTime"],
    "name": "myTable",
    "properties": {
      "name": {
        "type": "string",
        "key": "name",
        "title": "名称",
        "fieldType": "input",
        "listFields": true,
        "createShow": true,
        "editShow": true,
        "need": true,
        "unique": true
      },
      "status": {
        "type": "string",
        "key": "status",
        "title": "状态",
        "fieldType": "input",
        "listFields": true,
        "createShow": true,
        "editShow": true,
        "need": false
      },
      "createTime": {
        "type": "string",
        "key": "createTime",
        "title": "创建时间",
        "fieldType": "datePicker",
        "listFields": true,
        "createShow": false,
        "editShow": false,
        "disabled": true,
        "format": "datetime"
      }
    },
    "required": ["name"],
    "title": "我的表",
    "type": "object"
  }
}

查询告警

调用 get_alarms 工具，参数：
{
  "level": "critical",
  "status": "active",
  "limit": 50
}

发送设备控制命令

调用 send_control_command 工具，参数：
{
  "deviceId": "设备ID",
  "tagName": "control_tag",
  "value": 1
}

执行报表

调用 execute_report 工具，参数：
{
  "id": "报表ID",
  "parameters": {
    "startDate": "2024-01-01",
    "endDate": "2024-12-31"
  }
}

CLI 使用

项目同时提供 CLI 工具 airiot，用于命令行操作 AIRIOT 平台。

安装

npm install -g .
# 或使用 npx
npx @airiot/mcp-server

配置

首次使用需要登录：

airiot login --url https://your-airiot-server.com --project your-project-id

或使用 Token：

airiot login --url https://your-airiot-server.com --project your-project-id --token your-token

常用命令

# 查看帮助
airiot --help

# 查询数据表
airiot tables
airiot table <table-id>

# 查询记录
airiot records <table-id>
airiot record <table-id> <record-id>

# 查询报警
airiot warnings
airiot warnings confirm <warning-id>
airiot warnings resolve <warning-id>

# 查询最新数据
airiot data-latest --device <device-id> --tag <tag-id>

# 查询历史数据
airiot data-history --device <device-id> --tag <tag-id> --start <timestamp> --end <timestamp>

# 设备控制
airiot control-send --device <device-id> --tag <tag-name> --value <value>

# 查看配置
airiot config

# 登出
airiot logout

更多命令请查看 airiot --help。

测试

项目包含完整的测试套件，使用 Vitest 进行测试。

# 运行所有测试
npm test

# 运行测试并监听文件变化
npm test -- --watch

# 运行测试并生成覆盖率报告
npm run test:coverage

# 运行测试一次（不监听）
npm run test:run

测试覆盖范围：

• ✅ 所有 CLI 命令功能测试
• ✅ 工具函数测试
• ✅ 配置管理测试
• ✅ API 客户端 mock 测试

开发

# 安装依赖
npm install

# 开发模式（自动编译）
npm run dev

# 构建
npm run build

# 运行 MCP 服务器
npm start

# 运行 CLI
npm run cli

项目结构

mcp-server/
├── src/
│   ├── index.ts           # MCP 服务器入口
│   ├── airiot-api.ts      # AIRIOT API 客户端
│   ├── types.ts           # 类型定义
│   ├── config.ts          # 配置管理
│   ├── logger.ts          # 日志系统
│   ├── errors.ts          # 错误处理
│   ├── tools/             # MCP 工具
│   ├── resources/         # MCP 资源
│   ├── prompts/           # MCP 提示词
│   └── cli/               # CLI 工具
│       ├── index.ts       # CLI 入口
│       ├── config.ts      # CLI 配置管理
│       ├── formatter.ts   # 输出格式化
│       ├── utils.ts       # CLI 工具函数
│       ├── commands/      # CLI 命令模块
│       │   ├── warning.ts # 报警管理命令
│       │   ├── tables.ts  # 表管理命令
│       │   ├── records.ts # 记录管理命令
│       │   ├── tags.ts    # 属性点查询命令
│       │   ├── data.ts    # 时序数据命令
│       │   ├── stats.ts   # 统计命令
│       │   ├── files.ts   # 文件管理命令
│       │   ├── control.ts # 设备控制命令
│       │   ├── reports.ts # 报表管理命令
│       │   └── users.ts   # 用户管理命令
│       └── tests/         # 测试工具
├── dist/                  # 编译输出
├── .airiotrc.json.example # 配置示例
├── vitest.config.ts       # 测试配置
└── package.json

API 文档

本服务器基于 AIRIOT API 4.0 文档实现。

主要接口包括：

• 表管理: /core/t/schema/*
• 表记录管理: /core/t/{table}/d/*
• 属性点管理: /core/t/schema/tag/*
• 时序数据: /api/core/time-series/*
• 告警管理: /api/alarms/*
• 文件管理: /api/files/*
• 设备控制: /api/control/*
• 报表管理: /api/reports/*

错误处理

服务器实现了完善的错误处理机制：

• NetworkError: 网络连接错误
• AuthError: 认证失败（401）
• NotFoundError: 资源不存在（404）
• ApiError: API 请求错误（4xx/5xx）
• ValidationError: 参数验证错误

所有错误都会返回详细的错误信息，包括错误代码和详情。

许可证

MIT

贡献

欢迎提交 Issue 和 Pull Request！