# Helpdesk MCP Server - AI IT Support Agent

基于 **LangGraph + MCP (Model Context Protocol) + ChromaDB RAG** 的 IT Helpdesk 智能客服系统，实现自然语言到 IT 运维工具的端到端智能交互。

---

## 核心功能

| 模块 | 说明 |
|------|------|
| **ReAct Agent** | 任务规划 → 工具调用 → 结果反馈的完整循环，支持多轮对话 |
| **MCP Server** | 4 个标准化 Tool 封装 IT 运维操作，JSON-RPC 2.0 协议 |
| **RAG 检索增强** | ChromaDB 向量数据库，IT 知识库文档召回率 80%+ |
| **三层防幻觉** | 硬规则拦截 → RAG 交叉验证 → Confidence 阈值兜底 |
| **记忆模块** | SQLite 长期记忆，完整对话历史，多轮上下文连贯 |
| **Flask 健康检查** | RESTful API 接口，支持服务状态监控 |

---

## 系统架构

```
用户输入自然语言（IT问题）
    │
    ▼
┌─────────────────────────────────────┐
│     LangGraph StateGraph            │
│  ┌─────────┐    ┌──────────────┐   │
│  │ Agent   │───→│ 条件判断      │   │
│  │ 节点    │    │ should_      │   │
│  │(LLM推理)│←───│  continue    │   │
│  └────┬────┘    └──────┬───────┘   │
│       │                │            │
│       │         ┌──────┘            │
│       │         ▼                   │
│       │    ┌──────────┐             │
│       │    │  Tools   │             │
│       │    │  节点     │             │
│       │    └────┬─────┘             │
│       │         │                   │
│       └─────────┘                   │
└─────────────────────────────────────┘
    │
    ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│  MCP Server  │  │   ChromaDB   │  │   SQLite     │
│  4个 Tool    │  │  向量检索     │  │  记忆存储     │
└──────┬───────┘  └──────────────┘  └──────────────┘
       │
    ┌──┴──┬──────────┬──────────┐
    ▼     ▼          ▼          ▼
 search_ query_   reset_     escalate_
 kb     ticket    password   human
```

---

## 4个 MCP Tool

| Tool | 功能 | 示例 |
|------|------|------|
| `search_kb` | IT知识库RAG检索 | "VPN连接失败怎么办？" → 返回5步排查方案 |
| `query_ticket` | 工单状态查询 | "查询工单 T-002" → 返回状态/处理人/优先级 |
| `reset_password` | 密码重置 | "重置邮箱密码 zhangsan" → 生成临时密码 |
| `escalate_human` | 转人工处理 | "转人工" → 队列号+预估等待时间 |

---

## 快速开始

### 环境要求
- Python 3.10+
- pip

### 安装

```bash
git clone https://github.com/xiaohe9/helpdesk-mcp-server.git
cd helpdesk-mcp-server

# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# .venv\Scripts\activate  # Windows

pip install -r requirements.txt
```

### 运行

```bash
# 启动 Flask 健康检查服务
python app.py

# 运行 AI Agent（交互模式）
python agent_with_memory.py
```

---

## 演示效果

```
用户: VPN连接失败怎么办？
→ [Agent] 调用 search_kb
→ [RAG] ChromaDB 检索 IT 知识库
→ [返回] 5步排查方案 ✅

用户: 查询工单 T-002
→ [Agent] 调用 query_ticket
→ [返回] 状态:处理中 / 处理人:李工程师 / 优先级:高 ✅

用户: 重置邮箱密码 zhangsan
→ [Agent] 调用 reset_password
→ [返回] 临时密码: Temp@789012 / 首次登录需修改 ✅

用户: 转人工
→ [Agent] 调用 escalate_human
→ [返回] 队列号: Q-15C1A3 / 预估等待: 3分钟 ✅

对话历史: 完整记录在 SQLite conversations.db ✅
```

---

## 技术栈

- **Agent 框架**: LangGraph (ReAct 模式)
- **工具协议**: MCP (Model Context Protocol)
- **向量数据库**: ChromaDB
- **记忆存储**: SQLite
- **Web 框架**: Flask
- **语言**: Python 3.10+

---

## 文件结构

```
helpdesk-mcp-server/
├── .cursorrules          # Cursor 项目约束定义
├── .gitignore            # Git 忽略规则
├── app.py                # Flask 健康检查接口
├── mcp_server.py         # 4 个 MCP Tool 实现
├── it_support_data.py    # 模拟 IT 知识库与工单数据
├── rag_engine.py         # ChromaDB 向量检索引擎
├── agent_with_memory.py  # LangGraph Agent + SQLite 记忆
├── requirements.txt      # Python 依赖
└── README.md             # 本文件
```

---

## 开发方式

本项目使用 **Cursor + Vibe Coding** 开发，基于 `.cursorrules` 约束文件驱动 AI 代码生成，完整对标 [flight-mcp-server](https://github.com/xiaohe9/flight-mcp-server) 架构，验证 AI Agent 系统的业务场景复用能力。