K-12服务管理协议服务器

IncidentIQ MCP服务器

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

概述

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

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

• 🎫 管理IT帮助台工单 -搜索、查看、更新状态、设置紧急/敏感度、管理任务
• 💻 跟踪技术资产 -搜索和管理Chromebook、iPad和其他设备
• 👥 查找用户 -在学区系统中查找学生、教职员工和家长
• 🏫 导航位置 -访问建筑物和房间信息
• 👪 协调团队 -查看IT支持团队、成员和工作负载
• 🔧 管理维修 -跟踪零件库存、采购订单和设备维修工作流程

特征

📊 API全面覆盖

12个注册域模块中的158个MCP工具，所有这些都连接到服务器，并针对生产K-12地区实例进行验证。

可用的MCP工具

🎫 票务管理（15个工具）

搜索和列表操作

• ticket_search -使用文本、分页和方面过滤器搜索票证： statusIds, agentIds, agentEmails （任何域）， teamIds, locationIds一个方面内的多个值匹配ANY（OR）；不同的方面与AND相结合。状态筛选扫描有限数量的页面（设置 IIQ_TICKET_FILTER_MAX_PAGES，默认值5，范围1-50；超过上限的结果被标记为截断）。
• 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 -获取特定站点的向导

💻 资产管理（15种工具）

• asset_search_advanced -使用过滤器和分页搜索IT资产
• asset_find_by_tag / asset_search_by_tag -按标签号查找资产
• asset_find_by_serial / asset_search_by_serial -按序列号查找资产
• asset_get_history -获取资产的活动历史记录
• asset_get_user_devices -列出分配给用户的设备
• asset_get_inventory_counts -获取库存汇总计数
• asset_get_status_types / asset_get_funding_types -参考数据
• …以及更多（备件、收藏夹、按房间、按存储）

👥 用户管理（15个工具）

• user_search_advanced / user_quick_search -搜索用户（学生/教职员工/家长）
• user_get_details -按ID获取用户详细信息
• user_get_students / user_get_staff / user_get_parents -筛选目录查找
• user_get_all_agents / user_search_agents -列出IT支持代理
• user_get_by_location -某个位置的用户
• user_statistics_grades / user_statistics_locations -人口统计
• …以及更多（组、权限、当前用户）

🏫 位置管理（17个工具）

• location_get_all -列出所有地区位置
• location_search_advanced -搜索特定位置
• location_get_details -按ID获取位置详细信息
• location_get_buildings / location_get_campuses -建筑层次结构
• location_get_building_rooms / location_find_special_rooms -房间查询
• location_get_assets / location_get_users / location_get_tickets -交叉引用
• …以及更多（层次结构、儿童、可用房间）

👪 团队管理（9个工具）

• team_get_all / team_search -列出或搜索IT支持团队
• team_get / team_get_members / team_get_agents -团队详细信息和名单
• team_get_tickets / team_get_locations / team_get_categories / team_get_stats -团队背景

🔧 零件和维修（20个工具）

• parts_get_all / parts_search / parts_find_by_number -库存查询
• parts_check_stock / parts_get_low_stock / parts_get_by_location -库存跟踪
• parts_get_chromebook_parts / parts_get_ipad_parts / parts_get_compatible -设备部件
• parts_get_suppliers / parts_get_supplier_details -供应商
• parts_record_usage / parts_transfer / parts_get_repair_costs -维修工作流程
• …以及更多（订单、常见维修、票务零件）

🧾 采购订单（14个工具）

• purchaseorder_get_all / purchaseorder_search / purchaseorder_get -PO查询
• purchaseorder_get_pending / purchaseorder_get_approved / purchaseorder_get_completed -按状态
• purchaseorder_get_items / purchaseorder_get_parts / purchaseorder_get_attachments -PO内容
• purchaseorder_get_history / purchaseorder_get_summary / purchaseorder_get_supplier -PO上下文

🐞 问题类型（20个工具）

• issues_get_types / issues_search_types / issues_get_type_details -问题类型目录
• issues_get_categories / issues_get_category_hierarchy -类别结构
• issues_get_chromebook_issues / issues_get_network_issues / issues_get_classroom_tech -常见的K-12问题
• issues_get_priorities / issues_get_priority_sla -优先级和SLA映射
• …以及更多（模板、定期、季节性、父门户）

🏷️ 自定义字段（18个工具）

• customfield_get_all / customfield_search / customfield_find_by_name -现场目录
• customfield_get_by_entity / customfield_get_types / customfield_get_type_details -字段定义
• customfield_get_asset_values / customfield_get_ticket_values / customfield_get_user_values / customfield_get_location_values -字段值
• customfield_validate_value / customfield_get_required / customfield_get_options -验证

📈 SLA管理（4个工具）

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

👁️ 视图管理（5个工具）

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

🔔 通知和电子邮件（6个工具）

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

安装

先决条件

• Node.js >=22（升）
• 您所在地区的IncidentIQ API证书

注： 此服务器运行在Node.js上，由MCP客户端通过以下方式启动 node （或 npx), 符合标准MCP服务器惯例。开发工具链使用npm+Vitest。

安装（已发布的软件包）

发布的版本发布到 GitHub 包 作为 @iiq-community/mcp-incidentiq 每个包装上都附有皮球 GitHub 发布两条安装路径：

A——GitHub Packages注册表（需要一个令牌）。 GitHub软件包甚至需要身份验证 公共 包，所以创建一个 .npmrc GitHub令牌具有 read:packages 范围：

可见性注释： GitHub Packages仅在包的可见性为 公共.直到维护者将其设置为公共（组织→ 包裹→ mcp-incidentiq → 软件包设置→ 更改可见性→ 公共），只有IIQ社区成员可以通过注册表安装——其他人都应该使用 路径B 下面，它是公开的，不需要令牌。

# .npmrc
@iiq-community:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

npm install @iiq-community/mcp-incidentiq

B——GitHub发布tarball（无令牌）。 下载 iiq-community-mcp-incidentiq-<version>.tgz 从 最新版本，然后直接安装它——不需要注册表身份验证：

npm install ./iiq-community-mcp-incidentiq-<version>.tgz

两者都暴露了 mcp-incidentiq 二元的；将您的MCP客户端指向它（例如。 npx @iiq-community/mcp-incidentiq 一旦 .npmrc 已设置，或 node .../dist/index.js).请参阅下面的集成示例。要在服务器本身上工作，请使用源代码设置：

快速入门（来源）

1. 克隆存储库：

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

2. 安装依赖项：

npm install

3. 配置您的环境：

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代码集成

首先构建服务器(npm run build)，然后在Claude Code CLI中注册它：

claude mcp add incidentiq \
  -e IIQ_API_BASE_URL=https://your-district.incidentiq.com/api/v1.0 \
  -e IIQ_API_KEY=your-api-key-here \
  -- node /path/to/mcp-incidentiq/dist/index.js

替换 /path/to/mcp-incidentiq 与这个项目的实际路径。验证它是否已添加 claude mcp list.

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 与这个项目的实际路径。

用法

开发模式

npm run dev

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

生产模式

npm run build
npm run start

测试连接

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

Claude: "Test the IncidentIQ connection"

这将验证：

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

交互示例

# Search and view tickets
Claude: "Search for all urgent tickets"
Claude: "Show me details for ticket 00000000-0000-0000-0000-000000000000"
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 Jane User"

# 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 (registers all tool modules)
│   ├── api/
│   │   └── client.ts        # IncidentIQ API client
│   ├── tools/               # MCP tool implementations (one module per domain)
│   │   ├── tickets.ts       # Ticket management tools
│   │   ├── assets.ts        # Asset management tools
│   │   ├── users.ts         # User management tools
│   │   ├── locations.ts     # Location management tools
│   │   ├── teams.ts         # Team management tools
│   │   ├── parts.ts         # Parts & repair tools
│   │   ├── purchaseorders.ts# Purchase order tools
│   │   ├── issues.ts        # Issue type tools
│   │   ├── customfields.ts  # Custom field tools
│   │   ├── slas.ts          # SLA tools
│   │   ├── views.ts         # View tools
│   │   ├── notifications.ts # Notification & email tools
│   │   └── analytics.ts     # Analytics tools (defined, not yet registered)
│   └── types/               # TypeScript type definitions
│       └── common.ts        # Shared type definitions
└── dist/                    # Compiled JavaScript output

可用脚本

• npm run dev -使用热重新加载启动开发服务器
• npm run build -将TypeScript构建为JavaScript
• npm run start -运行生产服务器
• npm run type-check -无建筑类型检查
• npm run clean -清理构建目录
• npm run test / npm run test:unit -运行单元测试套件
• npm run test:coverage -使用覆盖率报告运行单元测试

API集成

支持的IncidentIQ模块

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

• ✅ IT帮助台 -完整的票证生命周期管理
• ✅ 资产管理 -设备跟踪和库存
• ✅ 用户目录 -学生、教职员工和家长查询
• ✅ 位置 -建筑和房间管理
• ✅ 团队 -IT支持团队名册和工作量
• ✅ 零件库存 -维修零件跟踪和供应商管理
• ✅ 采购订单 -按状态、项目和历史记录跟踪采购订单
• ✅ 问题类型 -问题/类别目录和K-12问题模板
• ✅ 自定义字段 -所有实体的地区特定数据
• ✅ SLA/视图/通知 -合规性指标、保存的视图和电子邮件/通知访问
• 🚧 分析 -已实施但尚未在服务器中注册的报告工具

API速率限制

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

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

贡献

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

治理： main 受保护——贡献通过拉取请求获得，只需1次批准+代码所有者审查，所有CI检查通过，对话解决，合并提交。看 存储库治理 用于完整的工作流程和安全设置。

如何做出贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feat/amazing-feature)
3. 使用提交 约定式提交 --例如。 git commit -m 'feat: add amazing feature'.一个共产党员 commit-msg 钩子（通过预提交框架强制执行）在本地拒绝不符合要求的消息；看见 贡献.md.
4. 推到分支(git push origin feat/amazing-feature)
5. 打开拉取请求

贡献理念

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

故障排除

常见问题

连接失败

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

未找到工具

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

权限错误

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

支持

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

版本控制和发布

该项目如下 语义版本控制 并使用 语义释放 用于全自动发布。每一次推动 main 分析 常规承诺 历史，计算 下一个版本，将包发布到 GitHub 包 以及GitHub版本（ npm pack 附带tarball，可免费安装）和更新 CHANGELOG.md / CITATION.cff / package.json --没有手动版本颠簸。该项目正在进行中 0.x 线，所以a 突破性的改变会产生轻微的冲击（不是 1.0.0).看 贡献.md 详情及 更改日志.md 版本历史。

许可证

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

免责声明

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

致谢

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