AI导哈

IoT平台服务器

AIRIOT MCP Server是基于Model Context Protocol的IoT平台服务器，为AI助手提供完整的AIRIOT平台访问能力，包括数据表管理、记录操作、时序数据查询、设备控制等功能。

  • by sshwsfc
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 sshwsfc/mcp-server

使用说明

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！

相关 MCP