MCP Incidentiq

IncidentIQ MCP服务器

IncidentIQ的模型上下文协议服务器-排名第一的K-12服务管理平台

 ](https://nodejs.org) 

概述

IncidentIQ MCP服务器使像Claude这样的人工智能助手能够与K-12学区的IncidentIQ实例进行交互，简化IT运营、资产管理和教育机构的支持工作流程。

IncidentIQ是排名第一的K-12服务管理平台，被美国2000多个学区使用。此MCP服务器提供与IncidentIQ全面的API的无缝集成，使人工智能助手能够：

• 🎫 管理IT帮助台工单 -搜索、查看、更新状态、设置优先级、管理分配（21个工作端点！）
• 💻 跟踪技术资产 -搜索和管理Chromebook、iPad和其他设备
• 👥 查找用户 -在学区系统中查找学生、教职员工和家长
• 🏫 导航位置 -访问建筑物和房间信息
• 📊 生成报告 -访问分析和运营指标
• 🔧 管理维修 -跟踪零件库存和设备维修工作流程

特性

📊 API全面覆盖

✅ 对所有13个API模块进行了分析和验证 随着 总体成功率83% 横跨 122个工作端点！

可用的MCP工具

🎫 票证管理（21个端点正常工作！）

搜索和列表操作

• ticket_search -使用过滤器和分页搜索门票
• ticket_get -通过ID获取详细的门票信息
• ticket_get_statuses -获取所有可用的票证状态
• ticket_get_priorities -获取所有可用的票优先级

门票详细信息

• ticket_get_assets -获取与票证关联的资产
• ticket_get_sla -获取票证的SLA信息

状态管理

• ticket_update_status -更新工单状态（等待/已响应）
• ticket_set_urgency -将票标记为紧急/不紧急
• ticket_set_sensitivity -将票标记为敏感/不敏感
• ticket_confirm_issue -确认或取消确认问题

票务操作

• ticket_cancel -取消机票
• ticket_unassign -从用户/团队/SLA取消分配
• ticket_mark_duplicate -标记为另一张票的副本

向导操作

• ticket_get_wizards -获取可用的票证创建向导
• ticket_get_wizards_by_site -获取特定站点的向导

💻 资产管理

• asset_search -使用筛选器搜索IT资产
• asset_get_by_tag -按标签号查找资产
• asset_get -获取详细的资产信息
• asset_get_counts -获取库存摘要

👥 用户管理

• user_search -搜索用户（学生/教职员工/家长）
• user_get -获取用户详细信息
• user_get_agents -列出IT支持代理

🏫 位置管理

• location_list_all -列出所有地区位置
• location_search -搜索特定位置
• location_get -获取位置详细信息

📈 SLA管理（新增！）

• sla_list -获取所有已配置的SLA
• sla_get_metrics -获取SLA性能指标
• sla_get_metric_types -获取度量类型（响应/分辨率/自定义）
• sla_get_ticket_status -检查票证的SLA合规性

👁️ 视图管理（新增！）

• view_list_all -获取所有可用视图
• view_list_user -获取用户特定的视图
• view_list_tickets -获取门票视图
• view_list_assets -获取资产视图
• view_list_users -获取用户目录视图

🔔 通知和电子邮件（新增！）

• notification_get_ticket_emails -获取门票电子邮件
• notification_query -使用过滤器搜索通知
• notification_get_unread -获取未读通知
• notification_get_unarchived -获取未存档的通知
• notification_mark_all_read -将所有内容标记为已读
• notification_mark_read -将特定通知标记为已读

安装

先决条件

• Node.js>=18.0.0
• 纱线包装经理
• 您所在地区的IncidentIQ API证书

快速开始

1. 克隆存储库：

git clone https://github.com/IIQ-Community/mcp-incidentiq.git
cd mcp-incidentiq

1. 安装依赖项：

yarn install

1. 配置您的环境：

cp .env.example .env

编辑 .env 持有您所在地区的IncidentIQ证书：

# Your district's IncidentIQ URL (e.g., https://mydistrict.incidentiq.com/api/v1.0)
IIQ_API_BASE_URL=https://your-district.incidentiq.com/api/v1.0

# API key from IncidentIQ Administration > Developer Tools
IIQ_API_KEY=your-api-key-here

# Optional: Request timeout in milliseconds (default: 30000)
IIQ_API_TIMEOUT=30000

配置

获取API证书

1. 以管理员身份登录您所在地区的IncidentIQ实例
2. 引导到 行政 > 开发工具
3. 生成或复制API密钥（JWT令牌）
4. 记下您所在地区的基本URL（格式： https://[district].incidentiq.com)

与AI助手集成

Claude代码集成

要将此MCP服务器添加到Claude Code中，请运行以下命令：

npx @anthropic/claude-code mcp add /path/to/mcp-incidentiq

这将自动配置Claude Code以使用IncidentIQ MCP服务器。

Claude桌面集成

要将此MCP服务器与Claude Desktop一起使用，请参阅我们的综合 Claude桌面设置指南.

快速配置示例：

1. 打开克劳德桌面设置
2. 导航到“开发人员”>“MCP设置”
3. 添加以下配置：

{
  "mcpServers": {
    "incidentiq": {
      "command": "node",
      "args": ["/path/to/mcp-incidentiq/dist/index.js"],
      "env": {
        "IIQ_API_BASE_URL": "https://your-district.incidentiq.com/api/v1.0",
        "IIQ_API_KEY": "your-api-key-here"
      }
    }
  }
}

替换 /path/to/mcp-incidentiq 与这个项目的实际路径。

用法

发展模式

yarn dev

这将启动服务器，并启用热重新加载以进行开发。

生产模式

yarn build
yarn start

测试连接

连接到Claude后，您可以测试您的连接：

Claude: "Test the IncidentIQ connection"

这将验证：

• API密钥有效性
• 与您所在地区实例的网络连接
• 正确配置

交互示例

# Search and view tickets
Claude: "Search for all urgent tickets"
Claude: "Show me details for ticket 9771c9fb-ed68-f011-8dca-000d3a0dbd19"
Claude: "Get all ticket priorities and statuses"

# Update ticket status
Claude: "Mark ticket [id] as waiting on requestor"
Claude: "Set ticket [id] as urgent and sensitive"
Claude: "Confirm the issue in ticket [id]"

# Manage ticket assignments
Claude: "Cancel ticket [id]"
Claude: "Unassign ticket [id] from the current team"
Claude: "Mark ticket [id] as duplicate of [other-id]"

# Look up assets
Claude: "Find Chromebook with tag CHR-12345"
Claude: "Show assets linked to ticket [id]"

# Get user information
Claude: "Look up user John Smith"

# Check SLA status
Claude: "Show SLA information for ticket [id]"

K-12教育重点

此MCP服务器是专门为K-12教育环境设计的：

关键用例

• 1:1设备程序：高效管理学生Chromebook和iPad
• 课堂支持：针对课堂技术问题快速创建工单
• 资产跟踪：为学生和教职员工分配跟踪设备
• 建筑管理：组织学校和教室的支持
• 夏日清新：支持设备收集和部署工作流
• 家长沟通：访问家长可见的门票信息

FERPA和隐私合规

此工具的设计考虑到了学生的隐私：

• MCP服务器不存储学生数据
• 所有API调用都直接转到您所在地区的IncidentIQ实例
• 遵循您所在地区的数据治理政策
• API访问由您的IncidentIQ权限控制

发展

项目结构

mcp-incidentiq/
├── src/
│   ├── index.ts          # Main MCP server entry point
│   ├── api/
│   │   └── client.ts     # IncidentIQ API client
│   ├── tools/            # MCP tool implementations
│   │   ├── tickets.ts    # Ticket management tools
│   │   ├── assets.ts     # Asset management tools
│   │   ├── users.ts      # User management tools
│   │   └── locations.ts  # Location management tools
│   └── types/            # TypeScript type definitions
│       └── common.ts     # Shared type definitions
└── dist/                 # Compiled JavaScript output

可用脚本

• yarn dev -使用热重新加载启动开发服务器
• yarn build -将TypeScript构建为JavaScript
• yarn start -运行生产服务器
• yarn type-check -无建筑类型检查
• yarn clean -清理构建目录

API集成

支持的IncidentIQ模块

此MCP服务器与IncidentIQ的核心模块集成：

• ✅ IT帮助台 -完整的票证生命周期管理
• ✅ 资产管理 -设备跟踪和库存
• ✅ 用户目录 -学生、教职员工和家长查询
• ✅ 位置 -建筑和房间管理
• 🚧 分析 -基本报告（即将推出）
• 🚧 零件库存 -维修零件跟踪（即将推出）
• 🚧 自定义字段 -地区特定数据（即将发布）

API速率限制

服务器实现负责任的API使用：

• 尊重偶发事件IQ率限制
• 实现请求超时处理
• 提供详细的错误消息
• 记录所有API交互以进行调试

贡献

我们欢迎K-12 IT社区的贡献！请查看我们的 贡献指南 了解详情。

如何做出贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

贡献理念

• 其他工具实现
• 与更多IncidentIQ模块集成
• 改进了错误处理
• 文档改进
• Bug修复和优化

故障排除

常见问题

连接失败

• 验证您的API密钥是否正确
• 检查基本URL格式（应以结尾 /api/v1.0)
• 确保您的IncidentIQ实例可访问
• 验证您的帐户是否已启用API访问

未找到工具

• 跑 yarn build 编译TypeScript代码
• 配置更改后重新启动Claude Desktop
• 检查MCP服务器日志是否有错误

权限错误

• 确保您的API密钥具有适当的权限
• 某些操作可能需要管理员权限
• 请与您的IncidentIQ管理员联系

支持

• 问题:
• 讨论:
• 安全：参见 安全.md 用于报告漏洞
• IncidentIQ支持：联系您所在地区的IncidentIQ管理员

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

免责声明

这是一个社区项目，与IncidentIQ没有正式联系或认可。IncidentIQ是IncidentIQneneneba公司的注册商标。

致谢

• IIQ社区提供合作和支持
• 为该项目做出贡献的K-12 IT专业人员
• IncidentIQ提供全面的API文档
• 模型上下文协议SDK的拟人化