内容
# IT 帮助台助理 MCP
一个准备好用于展示的 [模型上下文协议](https://modelcontextprotocol.io/) 服务器，为 AI 客户端提供只读帮助台上下文、受控的修复操作、一致的支持提示和可选的外部集成。
该项目在本地运行，无需 API 密钥。首次启动时，它会使用演示客户、设备、工单和库存创建 SQLite 数据库。本地手册通过 `documents/` 目录动态发现。
## 文档
首先查看 [文档索引](docs/index.md)，或者直接访问：
| 指南 | 内容 |
|---|---|
| [快速入门](docs/getting-started.md) | 安装、首次运行、检查器、客户端配置 |
| [配置](docs/configuration.md) | 路径、驱动程序 API、SMTP、超时和密钥 |
| [MCP 参考](docs/mcp-reference.md) | 每个资源、工具、提示、参数、输出和错误 |
| [数据模型](docs/data-model.md) | SQLite 表、关系、生命周期、编号和种子数据 |
| [工作流程](docs/workflows.md) | 诊断、工单生命周期、库存、电子邮件和报告 |
| [操作](docs/operations.md) | 传输、备份、恢复、知识文件和健康检查 |
| [开发](docs/development.md) | 模块、测试、打包和扩展程序 |
| [安全](docs/security.md) | 信任边界、密钥、数据保护和强化 |
| [故障排除](docs/troubleshooting.md) | 启动、MCP、数据库、PDF、搜索、API 和 SMTP 失败 |
| [架构](docs/architecture.md) | 组件、序列和数据模型图 |
## 包含内容
| 阶段 | 已交付能力 |
|---|---|
| 1. 基础 | 基于 stdio、SSE 或 Streamable HTTP 的 FastMCP 服务器 |
| 2. 文件 | 用于 `.pdf`、`.txt` 和 `.md` 的动态 `docs://` 资源 |
| 3. 数据库 | SQLite 客户、维修工单、设备、库存和时间线 |
| 4. 搜索 | 一个工具搜索手册和历史工单 |
| 5. 外部 API | 供应商支持、可配置驱动程序 API、SMTP、Open-Meteo 演示 |
| 6. 工具 | 客户、工单、库存、搜索和报告操作 |
| 7. 提示 | `helpdesk_assistant` 安全性和工作流程提示 |
| 8. 工作流程 | 搜索 → 诊断 → 检查零件 → 创建/更新/关闭 → 通知 |
| 9. 用户功能 | `HD-YYYYMM-NNNN` 编号、时间线、仪表板、Markdown 报告 |
| 10.润色 | 模块化代码、测试、架构文档、设置和客户端示例 |
## 快速开始
需要 Python 3.11 或更新版本。出于故意，依赖项约束停留在 MCP Python SDK v1，而 v2 处于预发布状态。
### Windows PowerShell
```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt
python server.py
```
### macOS 或 Linux
```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
python server.py
```
默认传输方式为 stdio。要使用本地 HTTP 端点：
```powershell
python server.py --transport streamable-http
```
端点为 `http://127.0.0.1:8000/mcp`。
## 在 MCP 检查器中打开
官方检查器通过 `npx` 运行。从此仓库：
```powershell
npx -y @modelcontextprotocol/inspector .\.venv\Scripts\python.exe server.py
```
在 macOS 或 Linux 上，将 Python 路径替换为 `.venv/bin/python`。在检查器中，验证“资源”、“工具”和“提示”选项卡。检查器还可以连接到 `http://127.0.0.1:8000/mcp`，当服务器使用 `--transport streamable-http` 运行。
## 连接 MCP 客户端
使用绝对路径，因为桌面客户端可能从另一个工作目录启动进程。
```json
{
"mcpServers": {
"it-helpdesk": {
"command": "D:\\absolute\\path\\to\\it-helpdesk\\.venv\\Scripts\\python.exe",
"args": ["D:\\absolute\\path\\to\\it-helpdesk\\server.py"]
}
}
}
```
在 macOS 或 Linux 上使用 `/absolute/path/to/.../.venv/bin/python`。
## MCP 接口
### 资源
| URI | 目的 |
|---|---|
| `docs://list` | 发现手册及其生成的 ID |
| `docs://{document_id}` | 读取发现的 PDF、文本或 Markdown 手册 |
| `db://customers` | 客户目录 |
| `db://tickets` | 工单队列 |
| `db://tickets/{ticket_number}` | 完整的工单、客户/设备上下文、时间线 |
| `db://devices` | 已注册的客户设备 |
| `db://inventory` | 零件和用品 |
| `db://dashboard` | 实时操作总数和最近的工单 |
### 工具
| 工具 | 效果 |
|---|---|
| `search_helpdesk` | 搜索手册和工单历史记录 |
| `add_customer` | 在验证后创建客户 |
| `create_ticket` | 打开编号的维修工单 |
| `update_ticket_status` | 添加时间线事件并更改活动状态 |
| `close_ticket` | 记录解决方案并关闭工单 |
| `search_inventory` | 匹配 SKU、零件、供应商、类别或兼容型号 |
| `generate_report` | 返回或保存摘要、工单或库存 Markdown |
| `lookup_manufacturer_support` | 返回官方供应商支持位置 |
| `lookup_driver` | 调用配置的目录或返回官方驱动程序页面 |
| `send_ticket_email` | 通过配置的 SMTP 发送状态更新 |
| `get_weather_demo` | 演示无密钥 Open-Meteo API 查询 |
变异、只读、破坏性和开放世界工具带有 MCP 工具注释，以便兼容的客户端可以呈现适当的确认 UI。
### 提示
`helpdesk_assistant(issue)` 提供基于证据的支持工作流程。核心行为相同的服务指令在 MCP 初始化期间提供：首先检查本地上下文，优先采用可逆操作，保护密钥，在变异前需要批准，并且永远不会伪造工具结果。
## 配置
使用 `mcp dev` 时，将 `.env.example` 复制到 `.env`，或者在启动客户端的环境中设置变量。
| 变量 | 目的 |
|---|---|
| `HELPDESK_DOCUMENTS_DIR` | 覆盖手册目录 |
| `HELPDESK_DATABASE_PATH` | 覆盖 SQLite 数据库路径 |
| `HELPDESK_REPORTS_DIR` | 覆盖保存的报告输出 |
| `HELPDESK_DRIVER_API_URL` | 可选的 JSON 驱动程序目录端点 |
| `HELPDESK_DRIVER_API_KEY` | 该端点的可选承载令牌 |
| `HELPDESK_SMTP_*` | SMTP 主机、端口、凭证和发件人地址 |
| `HELPDESK_EXTERNAL_TIMEOUT_SECONDS` | 网络超时；默认 `10` |
如果没有驱动程序 API，`lookup_driver` 返回官方制造商页面。如果没有 SMTP 配置，电子邮件会安全地失败，并带有设置指导。天气是唯一内置的实时 HTTP 调用，并使用 [Open-Meteo](https://open-meteo.com/en/docs)。
## 测试和验证
测试使用临时文件和真正的临时 SQLite 数据库来锻炼公共 FastMCP 接口。只有外部 HTTP/电子邮件适配器被替换。
```powershell
python -m unittest discover -s tests -v
python -m compileall -q it_helpdesk server.py
python -m mypy --check-untyped-defs it_helpdesk server.py
```
对于手动协议检查，请使用检查器：
1. 读取 `docs://list` 和 `db://dashboard`。
2. 使用 `printer` 调用 `search_helpdesk`。
3. 添加客户并使用返回的客户 ID 创建工单。
4. 读取 `db://tickets/{ticket_number}` 以检查其时间线。
5. 更新、报告和关闭工单。
## 架构
```mermaid
flowchart LR
Client["MCP 客户端 / 检查器"] -->|"stdio, SSE, or HTTP"| Server["FastMCP 服务器"]
Server --> Prompt["帮助台说明 + 提示"]
Server --> Resources["资源处理程序"]
Server --> Tools["工具处理程序"]
Resources --> Docs["文档存储"]
Docs --> Files["PDF / TXT / Markdown"]
Resources --> Repo["帮助台存储库"]
Tools --> Repo
Repo --> SQLite[("SQLite")]
Tools --> Reports["Markdown 报告"]
Tools --> Integrations["外部集成"]
Integrations --> Vendor["供应商 / 驱动程序 API"]
Integrations --> SMTP["SMTP"]
Integrations --> Weather["Open-Meteo"]
```
参见 [docs/architecture.md](docs/architecture.md) 以获取边界、工作流程和设计决策。
## 项目结构
```text
it-helpdesk/
├── documents/ # 自动发现的本地知识库
├── database/ # 运行时 SQLite 数据库（忽略）
├── reports/ # 可选生成的报告（忽略）
├── docs/ # 完整的项目和 API 文档
├── it_helpdesk/
│ ├── cli.py # 安装的命令入口
│ ├── config.py # 环境支持的设置
│ ├── database.py # 模式、种子数据、查询、工单生命周期
│ ├── documents.py # 文件发现、PDF 提取、搜索
│ ├── integrations.py # HTTP/供应商/天气和 SMTP 适配器
│ ├── mcp_server.py # 资源、工具、提示注册
│ └── reports.py # Markdown 报告生成
├── tests/test_mcp_server.py # 公共 MCP 集成测试
├── server.py # 简单的本地入口
├── pyproject.toml
└── requirements.txt
```
## 设计笔记
- SQL 使用绑定参数、外键、验证和原子月度序列以实现抗冲突的工单编号。
- 文档 ID 仅来自发现的文件；调用者不能使用资源模板进行任意路径访问。
- 数据库连接是短暂的，使服务器构造和测试在没有全局可变连接的情况下确定。
- 外部服务是明确的边界，带有超时和可操作的错误。
- 演示种子数据仅在客户表为空时插入。
