内容
# mcp-itop
MCP服务器用于 **iTop ITSM** — 分析，工单，评论，知识库，配置项。
提供给AI助手（opencode，Claude Desktop，Cursor） **19种工具** 用于处理iTop：
SLA分析，代理负载，服务质量，工单生命周期，知识库搜索，配置项影响分析。
## 功能
### 分析
| 工具 | 描述 |
|------------|----------|
| `itop_sla_report` | 指定服务在指定期间的SLA报告（TTO/TTR 已过/超时/不适用，中位数解决时间） |
| `itop_agent_workload` | 代理负载：已关闭/打开的工单，时间花费，待办事项 |
| `itop_idle_agents` | 搜索代理在N小时内无操作而处于空闲状态的工单 |
| `itop_service_quality` | 搜索被指派到不同服务的类似工单 |
| `itop_caller_quality` | 用户选择服务的质量 |
| `itop_agent_correction_rate` | 修正/未修正服务的代理 |
| `itop_ticket_summary` | 仪表盘：创建/解决/打开/SLA超时 |
### 评论
| 工具 | 描述 |
|------------|----------|
| `itop_add_comment` | 添加公开或私有的评论到工单 |
| `itop_get_log` | 读取评论历史（public_log，private_log） |
### 知识库
| 工具 | 描述 |
|------------|----------|
| `itop_search_kb` | 搜索知识库文章（支持KBEntry和FAQ） |
| `itop_get_kb_article` | 文章全文 |
| `itop_list_kb_categories` | 知识库分类列表 |
### CRUD + 生命周期
| 工具 | 描述 |
|------------|----------|
| `itop_get` | 搜索对象（OQL / ID / JSON条件） |
| `itop_create` | 创建对象 |
| `itop_update` | 更新对象字段 |
| `itop_delete` | 删除（模拟模式） |
| `itop_apply_stimulus` | 生命周期：ev_assign，ev_resolve，ev_close，ev_reopen |
| `itop_get_related` | 配置项影响分析（影响/依赖） |
| `itop_describe_class` | 通过现有对象探索类字段 |
## 快速开始
### 1. 安装
```bash
pip install mcp[fastmcp] httpx python-dotenv
```
### 2. 配置（全局配置）
```bash
mkdir -p ~/.config/mcp-itop
cat > ~/.config/mcp-itop/.env << 'CONFIG'
ITOP_URL=https://your-itop.example.com
# Token 或 登录密码：
ITOP_TOKEN=您的_token_在此
# ITOP_USER=admin
# ITOP_PASSWORD=secret
ITOP_VERSION=1.3
ITOP_VERIFY_SSL=true
ITOP_TIMEOUT=30
CONFIG
```
### 3. 启动
```bash
python server.py
```
## 集成
### opencode（全局配置）
在 `~/.config/opencode/opencode.json` 中添加：
```json
"itop": {
"type": "local",
"command": ["python", "/路径/到/mcp-itop/server.py"],
"enabled": true
}
```
### opencode（项目）
在项目 `opencode.json` 中添加：
```json
{
"mcpServers": {
"itop": {
"command": "python",
"args": ["/路径/到/mcp-itop/server.py"],
"env": {
"ITOP_URL": "https://your-itop.example.com",
"ITOP_TOKEN": "您的_token"
}
}
}
}
```
### Claude Desktop
在 `claude_desktop_config.json` 中添加：
```json
{
"mcpServers": {
"itop": {
"command": "python",
"args": ["/路径/到/mcp-itop/server.py"]
}
}
}
```
## 请求示例
```
显示本月“技术支持”服务的SLA情况
哪些代理超负荷工作？
哪些工单超过2小时未处理？
搜索不同服务下的类似工单
哪些用户经常选择错误的服务？
在工单RQ-123中添加评论
创建新工单：打印机无法工作
将工单RQ-456指派给Ivanov
搜索与服务器srv-web-01相关的配置项
在知识库中搜索VPN相关信息
```
## 兼容性
已在以下环境中测试：
- **iTop** 3.2.1-1-16749（PHP 8.1.2，MariaDB 10.6）
- 支持俄语本地化（是/否用于SLA）和英语本地化（true/false）
- 自动识别知识库模块：KBEntry → FAQ
## 要求
- Python ≥ 3.10
- `mcp[fastmcp]`
- `httpx`
- `python-dotenv`
## 测试
```bash
python -m pytest tests/ -v
```
## 架构
```
AI客户端 → MCP（stdio）→ server.py → iTop REST API
```
配置优先级：
1. `~/.config/mcp-itop/.env`（全局，最高优先级）
2. `.env`（项目本地）
3. 环境变量
## 许可证
MIT
