{"_id":"@airiot/tools","name":"@airiot/tools","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@airiot/tools","version":"1.0.0","description":"MCP server and CLI for AIRIOT IoT platform","type":"module","main":"dist/index.js","bin":{"airiot-mcp-server":"dist/index.js","airiot":"dist/cli/index.js"},"scripts":{"build":"tsc","watch":"tsc --watch","start":"node dist/index.js","dev":"tsc --watch","cli":"node dist/cli/index.js","test":"vitest run","test:coverage":"vitest run --coverage"},"publishConfig":{"access":"public"},"keywords":["mcp","airiot","iot","model-context-protocol","cli"],"author":"","license":"MIT","dependencies":{"@modelcontextprotocol/sdk":"^1.0.4","axios":"^1.7.9","commander":"^14.0.3","dotenv":"^17.2.3"},"devDependencies":{"@types/node":"^22.0.0","typescript":"^5.6.0","vitest":"^2.0.0"},"gitHead":"5baba822a0cc3070a8836cb33f47b1c1d3a25283","types":"./dist/index.d.ts","_id":"@airiot/tools@1.0.0","_nodeVersion":"24.11.1","_npmVersion":"11.7.0","dist":{"integrity":"sha512-bEdkPsUXdYZj0v1wEPe0XhmlOUwpR245p4Tk4VUvHiRWbEFy9pFK66sa4lNCwozgBRWg7Lmyq637NhSI2Fs6ng==","shasum":"60d2498b42afd000a311c9faed7b5b402d2689c3","tarball":"https://registry.npmjs.org/@airiot/tools/-/tools-1.0.0.tgz","fileCount":146,"unpackedSize":491768,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHYX+qd0xxsXfWfKgrP3elGXDCoGJ76TONehN/WGLf0aAiAIueoB0i0TggF0svWzciwlk+ciU2SiVq5LKLO36E2ULQ=="}]},"_npmUser":{"name":"sshwsfc","email":"23025006@qq.com"},"directories":{},"maintainers":[{"name":"sshwsfc","email":"23025006@qq.com"},{"name":"airiot3308521255","email":"3308521255@qq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/tools_1.0.0_1773540585902_0.9554459021307495"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-15T02:09:45.802Z","1.0.0":"2026-03-15T02:09:46.067Z","modified":"2026-03-15T02:09:46.343Z"},"maintainers":[{"name":"sshwsfc","email":"23025006@qq.com"},{"name":"airiot3308521255","email":"3308521255@qq.com"}],"description":"MCP server and CLI for AIRIOT IoT platform","keywords":["mcp","airiot","iot","model-context-protocol","cli"],"license":"MIT","readme":"# AIRIOT MCP Server\n\n基于 Model Context Protocol (MCP) 的 AIRIOT IoT 平台服务器，为 AI 助手提供完整的 AIRIOT 平台访问能力。\n\n## 功能特性\n\n### 核心能力\n- 📊 **数据表管理**: 查询、创建、更新、删除数据表\n- 📝 **记录操作**: 对表记录进行 CRUD 操作（含批量）\n- 🏷️ **属性点查询**: 查询表和记录的属性点定义\n- 📈 **时序数据**: 查询设备最新数据和历史数据\n- 📊 **统计分析**: 设备在线状态统计\n\n### MCP 能力支持\n- 🔧 **Tools**: 30+ 工具接口\n- 📁 **Resources**: 10+ 资源端点，支持直接读取平台数据作为上下文\n- 💬 **Prompts**: 12+ 预定义提示词模板\n\n### 新增功能\n- 🚨 **告警管理**: 查询、确认、解除告警\n- 📁 **文件管理**: 上传、下载、删除文件\n- 🎮 **设备控制**: 发送控制命令\n- 📄 **报表管理**: 创建、执行、管理报表\n- 👤 **用户管理**: 查询用户信息\n\n### 开发体验\n- ⚙️ **配置文件**: 支持 `.airiotrc.json` 配置文件\n- 📝 **日志系统**: 分级日志，便于调试\n- 🛡️ **错误处理**: 完善的错误类型和错误恢复机制\n\n## 安装\n\n```bash\ncd airiot-mcp-server\nnpm install\nnpm run build\n```\n\n## 配置\n\n### 方式一：配置文件（推荐）\n\n在项目根目录创建 `.airiotrc.json` 文件：\n\n```json\n{\n  \"baseUrl\": \"https://your-airiot-server.com\",\n  \"projectId\": \"your-project-id\",\n  \"token\": \"your-api-token\",\n  \"timeout\": 30000,\n  \"logLevel\": \"info\",\n  \"retries\": 3\n}\n```\n\n可参考 [`.airiotrc.json.example`](.airiotrc.json.example) 文件。\n\n### 方式二：环境变量\n\n创建 `.env` 文件或设置以下环境变量：\n\n```bash\n# AIRIOT 服务器地址（必填）\nexport AIRIOT_BASE_URL=\"https://your-airiot-server.com\"\n\n# 项目ID（必填）\nexport AIRIOT_PROJECT_ID=\"your-project-id\"\n\n# 认证方式1: 使用Token（推荐）\nexport AIRIOT_TOKEN=\"your-api-token\"\n\n# 认证方式2: 使用用户名密码\nexport AIRIOT_USERNAME=\"your-username\"\nexport AIRIOT_PASSWORD=\"your-password\"\n\n# 日志级别（可选）\nexport AIRIOT_LOG_LEVEL=\"info\"\n```\n\n### MCP 配置\n\n在 Claude Desktop 配置文件中添加：\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"airiot\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"/path/to/airiot-mcp-server/dist/index.js\"\n      ],\n      \"env\": {\n        \"AIRIOT_BASE_URL\": \"https://your-airiot-server.com\",\n        \"AIRIOT_PROJECT_ID\": \"your-project-id\",\n        \"AIRIOT_TOKEN\": \"your-api-token\"\n      }\n    }\n  }\n}\n```\n\n## MCP 能力\n\n### Resources（资源）\n\nAI 可以直接读取以下资源作为上下文：\n\n| URI | 描述 |\n|-----|------|\n| `airiot://tables` | 数据表列表 |\n| `airiot://tables/{id}` | 数据表详情 |\n| `airiot://table/{tableName}/records` | 表记录列表 |\n| `airiot://devices` | 设备列表 |\n| `airiot://device/{id}` | 设备详情 |\n| `airiot://device/{deviceId}/tag/{tagId}/latest` | 最新数据 |\n| `airiot://stats/online` | 在线统计 |\n\n### Prompts（提示词模板）\n\n预定义的常用查询模板：\n\n| 模板名 | 描述 |\n|--------|------|\n| `list_tables` | 列出数据表 |\n| `describe_table` | 获取表结构 |\n| `query_devices` | 查询设备列表 |\n| `get_realtime_data` | 获取实时数据 |\n| `get_history_trend` | 获取历史趋势 |\n| `device_online_summary` | 设备在线摘要 |\n| `query_alarms` | 查询告警 |\n| `create_device` | 创建设备 |\n| `update_device_status` | 更新设备状态 |\n\n## 可用工具\n\n### 表管理\n\n| 工具名 | 描述 |\n|--------|------|\n| `get_tables` | 查询数据表列表 |\n| `get_table_by_id` | 根据ID查询单个表 |\n| `create_table` | 创建新数据表 |\n| `update_table` | 更新表信息 |\n| `delete_table` | 删除数据表 |\n\n### 记录管理\n\n| 工具名 | 描述 |\n|--------|------|\n| `get_table_records` | 查询表记录列表 |\n| `get_record_by_id` | 根据ID查询单条记录 |\n| `create_record` | 创建新记录 |\n| `update_record` | 更新记录 |\n| `delete_record` | 删除单条记录 |\n| `batch_delete_records` | 批量删除记录 |\n\n### 属性点查询\n\n| 工具名 | 描述 |\n|--------|------|\n| `get_table_tags` | 查询表的属性点定义 |\n| `get_record_tags` | 查询记录的属性点 |\n\n### 时序数据\n\n| 工具名 | 描述 |\n|--------|------|\n| `get_latest_data` | 查询最新数据 |\n| `get_history_data` | 查询历史时序数据 |\n\n### 告警管理\n\n| 工具名 | 描述 |\n|--------|------|\n| `get_alarms` | 查询告警列表 |\n| `get_alarm_by_id` | 查询告警详情 |\n| `acknowledge_alarm` | 确认告警 |\n| `resolve_alarm` | 解除告警 |\n\n### 文件管理\n\n| 工具名 | 描述 |\n|--------|------|\n| `upload_file` | 上传文件 |\n| `get_file_info` | 获取文件信息 |\n| `delete_file` | 删除文件 |\n\n### 设备控制\n\n| 工具名 | 描述 |\n|--------|------|\n| `send_control_command` | 发送控制命令 |\n| `send_batch_control_commands` | 批量发送控制命令 |\n\n### 报表管理\n\n| 工具名 | 描述 |\n|--------|------|\n| `get_reports` | 查询报表列表 |\n| `get_report_by_id` | 查询报表详情 |\n| `execute_report` | 执行报表生成 |\n| `create_report` | 创建报表 |\n| `update_report` | 更新报表 |\n| `delete_report` | 删除报表 |\n\n### 用户管理\n\n| 工具名 | 描述 |\n|--------|------|\n| `get_current_user` | 获取当前用户信息 |\n| `get_users` | 获取用户列表 |\n\n## 使用示例\n\n### 查询所有数据表\n\n```\n调用 get_tables 工具，参数：\n{\n  \"limit\": 50,\n  \"sort\": { \"createTime\": -1 }\n}\n```\n\n### 查询特定表的记录\n\n```\n调用 get_table_records 工具，参数：\n{\n  \"tableName\": \"device\",\n  \"filter\": { \"status\": \"online\" },\n  \"limit\": 100\n}\n```\n\n### 创建新表\n\n创建表需要提供完整的 schema 定义：\n\n```\n调用 create_table 工具，参数：\n{\n  \"id\": \"my_table\",\n  \"title\": \"我的数据表\",\n  \"showField\": \"name\",\n  \"schema\": {\n    \"form\": [\"name\", \"status\", \"createTime\"],\n    \"key\": \"myTable\",\n    \"listFields\": [\"name\", \"status\", \"createTime\"],\n    \"name\": \"myTable\",\n    \"properties\": {\n      \"name\": {\n        \"type\": \"string\",\n        \"key\": \"name\",\n        \"title\": \"名称\",\n        \"fieldType\": \"input\",\n        \"listFields\": true,\n        \"createShow\": true,\n        \"editShow\": true,\n        \"need\": true,\n        \"unique\": true\n      },\n      \"status\": {\n        \"type\": \"string\",\n        \"key\": \"status\",\n        \"title\": \"状态\",\n        \"fieldType\": \"input\",\n        \"listFields\": true,\n        \"createShow\": true,\n        \"editShow\": true,\n        \"need\": false\n      },\n      \"createTime\": {\n        \"type\": \"string\",\n        \"key\": \"createTime\",\n        \"title\": \"创建时间\",\n        \"fieldType\": \"datePicker\",\n        \"listFields\": true,\n        \"createShow\": false,\n        \"editShow\": false,\n        \"disabled\": true,\n        \"format\": \"datetime\"\n      }\n    },\n    \"required\": [\"name\"],\n    \"title\": \"我的表\",\n    \"type\": \"object\"\n  }\n}\n```\n\n### 查询告警\n\n```\n调用 get_alarms 工具，参数：\n{\n  \"level\": \"critical\",\n  \"status\": \"active\",\n  \"limit\": 50\n}\n```\n\n### 发送设备控制命令\n\n```\n调用 send_control_command 工具，参数：\n{\n  \"deviceId\": \"设备ID\",\n  \"tagName\": \"control_tag\",\n  \"value\": 1\n}\n```\n\n### 执行报表\n\n```\n调用 execute_report 工具，参数：\n{\n  \"id\": \"报表ID\",\n  \"parameters\": {\n    \"startDate\": \"2024-01-01\",\n    \"endDate\": \"2024-12-31\"\n  }\n}\n```\n\n## CLI 使用\n\n项目同时提供 CLI 工具 `airiot`，用于命令行操作 AIRIOT 平台。\n\n### 安装\n\n```bash\nnpm install -g .\n# 或使用 npx\nnpx @airiot/mcp-server\n```\n\n### 配置\n\n首次使用需要登录：\n\n```bash\nairiot login --url https://your-airiot-server.com --project your-project-id\n```\n\n或使用 Token：\n\n```bash\nairiot login --url https://your-airiot-server.com --project your-project-id --token your-token\n```\n\n### 常用命令\n\n```bash\n# 查看帮助\nairiot --help\n\n# 查询数据表\nairiot tables\nairiot table <table-id>\n\n# 查询记录\nairiot records <table-id>\nairiot record <table-id> <record-id>\n\n# 查询报警\nairiot warnings\nairiot warnings confirm <warning-id>\nairiot warnings resolve <warning-id>\n\n# 查询最新数据\nairiot data-latest --device <device-id> --tag <tag-id>\n\n# 查询历史数据\nairiot data-history --device <device-id> --tag <tag-id> --start <timestamp> --end <timestamp>\n\n# 设备控制\nairiot control-send --device <device-id> --tag <tag-name> --value <value>\n\n# 查看配置\nairiot config\n\n# 登出\nairiot logout\n```\n\n更多命令请查看 `airiot --help`。\n\n## 测试\n\n项目包含完整的测试套件，使用 Vitest 进行测试。\n\n```bash\n# 运行所有测试\nnpm test\n\n# 运行测试并监听文件变化\nnpm test -- --watch\n\n# 运行测试并生成覆盖率报告\nnpm run test:coverage\n\n# 运行测试一次（不监听）\nnpm run test:run\n```\n\n测试覆盖范围：\n- ✅ 所有 CLI 命令功能测试\n- ✅ 工具函数测试\n- ✅ 配置管理测试\n- ✅ API 客户端 mock 测试\n\n## 开发\n\n```bash\n# 安装依赖\nnpm install\n\n# 开发模式（自动编译）\nnpm run dev\n\n# 构建\nnpm run build\n\n# 运行 MCP 服务器\nnpm start\n\n# 运行 CLI\nnpm run cli\n```\n\n## 项目结构\n\n```\nmcp-server/\n├── src/\n│   ├── index.ts           # MCP 服务器入口\n│   ├── airiot-api.ts      # AIRIOT API 客户端\n│   ├── types.ts           # 类型定义\n│   ├── config.ts          # 配置管理\n│   ├── logger.ts          # 日志系统\n│   ├── errors.ts          # 错误处理\n│   ├── tools/             # MCP 工具\n│   ├── resources/         # MCP 资源\n│   ├── prompts/           # MCP 提示词\n│   └── cli/               # CLI 工具\n│       ├── index.ts       # CLI 入口\n│       ├── config.ts      # CLI 配置管理\n│       ├── formatter.ts   # 输出格式化\n│       ├── utils.ts       # CLI 工具函数\n│       ├── commands/      # CLI 命令模块\n│       │   ├── warning.ts # 报警管理命令\n│       │   ├── tables.ts  # 表管理命令\n│       │   ├── records.ts # 记录管理命令\n│       │   ├── tags.ts    # 属性点查询命令\n│       │   ├── data.ts    # 时序数据命令\n│       │   ├── stats.ts   # 统计命令\n│       │   ├── files.ts   # 文件管理命令\n│       │   ├── control.ts # 设备控制命令\n│       │   ├── reports.ts # 报表管理命令\n│       │   └── users.ts   # 用户管理命令\n│       └── tests/         # 测试工具\n├── dist/                  # 编译输出\n├── .airiotrc.json.example # 配置示例\n├── vitest.config.ts       # 测试配置\n└── package.json\n```\n\n## API 文档\n\n本服务器基于 [AIRIOT API 4.0](https://airiot.apifox.cn/llms.txt) 文档实现。\n\n主要接口包括：\n\n- **表管理**: `/core/t/schema/*`\n- **表记录管理**: `/core/t/{table}/d/*`\n- **属性点管理**: `/core/t/schema/tag/*`\n- **时序数据**: `/api/core/time-series/*`\n- **告警管理**: `/api/alarms/*`\n- **文件管理**: `/api/files/*`\n- **设备控制**: `/api/control/*`\n- **报表管理**: `/api/reports/*`\n\n## 错误处理\n\n服务器实现了完善的错误处理机制：\n\n- **NetworkError**: 网络连接错误\n- **AuthError**: 认证失败（401）\n- **NotFoundError**: 资源不存在（404）\n- **ApiError**: API 请求错误（4xx/5xx）\n- **ValidationError**: 参数验证错误\n\n所有错误都会返回详细的错误信息，包括错误代码和详情。\n\n## 许可证\n\nMIT\n\n## 贡献\n\n欢迎提交 Issue 和 Pull Request！\n","readmeFilename":"README.md","_rev":"1-29de75187a22c51c3d6e53b50b5ddcd5"}