Subscribes to IoT device MQTT topics for status, telemetry, logs, faults, and heartbeats, and enables diagnosis of MQTT connectivity issues such as unreachable brokers, authentication failures, and keep-alive timeouts.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@IoT Diagnosis MCP Server diagnose why device ESP32_05 keeps disconnecting from MQTT"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
小yi 的 IoT 能力层，包含两个相互独立的 Streamable HTTP MCP 服务：
IoT Diagnosis MCP：汇集设备状态、遥测、日志、知识文档和历史案例，完成检索与故障诊断。
IoT Control MCP：按风险等级执行修复动作、管理人工审批，并验证设备是否恢复。
两者通过 MQTT Topic 契约协作，不直接调用彼此。修复成功后，Control MCP 发布完成事件，Diagnosis MCP 将结果沉淀为可检索的已验证案例，形成“诊断 → 决策 → 执行 → 验证 → 学习”的闭环。
MCP Python SDK 2.x + Streamable HTTP 传输。
15 个诊断/知识工具和 6 个设备控制工具。
结构感知分块以及 Dense + BM25 + RRF + Reranker 混合检索。
无网络、无模型下载的确定性检索，以及可选的 Qwen3 GPU 检索服务。
SQLite 事实源、MySQL 镜像、Qdrant 向量索引和持久化 outbox。
低风险动作自动执行，高风险动作必须经人工批准。
设备命令回执、恢复窗口验证和自动案例沉淀。
SQLite schema 迁移、数据保留、外部存储重建、健康检查和离线模型缓存校验。
单设备模拟器及包含 12 台 ESP32 的可配置模拟机群。
Related MCP server: IT-HelpDesk-MCP
flowchart LR
Agent[小yi 主后端 / MCP Client]
Agent -->|MCP :9001| Diagnosis[IoT Diagnosis MCP]
Agent -->|MCP :9002| Control[IoT Control MCP]
Diagnosis --> SQLiteD[(Diagnosis SQLite)]
Diagnosis --> MySQL[(MySQL 镜像)]
Diagnosis --> Qdrant[(Qdrant)]
Diagnosis -. GPU 档位 .-> Models[Qwen3 Models :9010]
Diagnosis <--> MQTT[MQTT Broker]
Control --> SQLiteC[(Control SQLite)]
Control <--> MQTT
Fleet[ESP32 设备 / 模拟机群] <--> MQTT服务 | MCP 端点 | 健康检查 | 就绪检查 |
Diagnosis MCP |
|
|
|
Control MCP |
|
|
|
Retrieval Models（可选） | Embeddings |
|
|
主项目负责 MySQL、Qdrant、MQTT、两个 MCP 服务和模拟机群的完整编排：
git clone https://github.com/fireworksfade/xiaoyi.git
cd xiaoyi
git clone https://github.com/fireworksfade/xiaoyi-mcp-services.git mcp-services
docker compose up -d --build
docker compose ps首次启动或重建数据卷后，在主项目中注册 MCP 服务与工具策略：
docker compose exec backend python scripts/bootstrap_local_mcp.pyCompose 会在服务启动前自动执行数据库迁移。默认使用 Portable 检索，无需 GPU 或模型下载。
需要 Python >= 3.12。先创建环境并安装依赖：
git clone https://github.com/fireworksfade/xiaoyi-mcp-services.git
cd xiaoyi-mcp-services
python -m venv .venv
.venv\Scripts\python -m pip install -e ".[dev]"
.venv\Scripts\python -m scripts.migrate upgrade --service diagnosis
.venv\Scripts\python -m scripts.migrate upgrade --service control分别在两个终端中启动服务：
# Terminal 1
.venv\Scripts\python -m iot_diagnosis.server
# Terminal 2
.venv\Scripts\python -m iot_control.server独立运行时 Diagnosis MCP 默认使用本地 SQLite、hash embedding 和 weighted reranker。Control MCP 要真正下发命令并通过 /ready 检查，需要启动 MQTT Broker 并设置 MQTT_ENABLED=true。.env.example 是配置参考；服务读取进程环境变量，不会自动加载 .env 文件。
类别 | 工具 | 用途 |
诊断 |
| 聚合实时状态、日志和检索证据，返回结构化诊断 |
诊断 |
| 查询路由、最终上下文、耗时、Token 与错误快照 |
设备 |
| 查询单设备或发现设备，可按类型和在线状态过滤 |
日志 |
| 获取设备近期日志，可按级别过滤 |
知识 |
| 检索知识或分页查看知识目录 |
案例 |
| 检索或分页查看已验证案例 |
历史 |
| 按设备、故障类型和执行状态查看诊断记录 |
写入 |
| 写入人工确认且包含确认人的故障案例 |
写入 |
| 摄取文本/Markdown 并执行结构感知分块 |
删除 |
| 同步删除 SQLite、MySQL 镜像和 Qdrant 数据 |
维护 |
| 以 SQLite 为准批量重建 Qdrant 索引 |
所有列表工具均支持 limit/offset 分页。写入和删除工具应由 MCP Client 按风险策略显式授权，不应默认暴露给 Agent。
工具 | 用途 |
| 返回动作目录、风险级别、参数和适用故障类型 |
| 直接执行低风险动作；高风险动作会被拒绝 |
| 为高风险动作创建待审批提案 |
| 按命令 ID 或提案 ID 查询执行和验证状态 |
| 按状态分页查看修复提案 |
| 批准或拒绝提案，仅供已授权后端调用 |
内置动作：
风险 | 动作 | 参数 |
低 |
| 无 |
低 |
| 无 |
低 |
| 无 |
低 |
|
|
高 |
| 无，必须审批 |
高 |
|
|
修复命令必须携带本轮 diagnosis_id。Control MCP 会向 Diagnosis MCP 验证该诊断存在、成功且属于同一设备；恢复成功后，Diagnosis MCP 会按这个精确 ID 把闭环结果保存为已验证案例，不再按设备和时间窗口猜测关联。
默认检索链路：
结构感知分块
→ Dense 召回 + SQLite FTS5/BM25 召回
→ RRF 融合与去重
→ Reranker 重排
→ Top-K 证据分块保留 Markdown 标题层级、代码块、日志行、排查步骤和表格边界。
默认块大小为 512 token、重叠 64 token，可用 RAG_CHUNK_SIZE 和 RAG_CHUNK_OVERLAP 调整。
BM25 对下划线技术词与 CJK 二元组做展开，可检索 ERR_CONNECTION_RESET、mosquitto.conf 和中文短语。
RAG_RETRIEVAL_STRATEGY 支持 dense、sparse、hybrid，默认 hybrid。
RAG_ENABLE_SPARSE、RAG_ENABLE_RRF 和 RAG_ENABLE_RERANKER 可独立关闭组件，用于评测或回退。
RAG_RETRIEVAL_DEBUG=true 时返回候选的 dense/sparse rank、RRF 和 reranker 调试信息。
实时 RSSI、温度、在线状态、WiFi/MQTT 状态问题由 Rule Router 直接回答，不调用诊断 LLM。
档位 | Embedding / Reranker | 向量维度 | 要求 |
Portable（默认 Compose） | hash / weighted | 384 | 无 GPU、无模型下载 |
GPU | Qwen3-Embedding-0.6B / Qwen3-Reranker-0.6B | 1024 | NVIDIA runtime，建议至少 4 GiB 空闲显存 |
GPU offline | 已缓存的 Qwen3 模型 | 1024 | 完整模型缓存，禁止联网下载 |
在主项目目录中切换档位：
# GPU
docker compose -f compose.yaml -f compose.retrieval-gpu.yaml up -d --build
# GPU + offline
docker compose -f compose.yaml -f compose.retrieval-gpu.yaml -f compose.retrieval-offline.yaml up -d --buildPortable 和 GPU 档位应使用不同的 Qdrant collection，主项目默认分别为 iot_diagnosis_portable 和 iot_diagnosis_qwen3，避免 384/1024 维向量混写。GPU 档位首次下载约 2.5 GiB 模型，典型冷启动时间为 5–20 分钟。
模型缓存模式由 MODEL_CACHE_MODE=download|offline 控制。发布离线部署前可检查缓存：
.venv\Scripts\python -m scripts.check_model_cache --models-dir C:\path\to\model-cache缓存完整时退出码为 0；否则退出码为 1。offline 模式缓存不完整时 /ready 返回 503 和 MODEL_CACHE_INCOMPLETE，不会联网下载。
Diagnosis MCP 以 SQLite 为本地事实源。配置 MySQL 或 Qdrant 后，外部写入失败会持久化到 SQLite outbox，并由后台任务按 DIAGNOSIS_SYNC_RETRY_SECONDS 重试。
数据 | SQLite | MySQL | Qdrant |
设备状态、日志、诊断记录 | 事实源 | 镜像 | — |
知识文档与分块 | 事实源 | 镜像 | 向量索引 |
已验证故障案例 | 事实源 | 镜像 | 向量索引 |
修复命令与提案 | Control SQLite 事实源 | — | — |
Repository 初始化不会执行全库外部同步。需要重建 MySQL 镜像时使用显式、可恢复的分页任务：
.venv\Scripts\python -m scripts.rebuild_external --list
.venv\Scripts\python -m scripts.rebuild_external --entity device_log --batch-size 500
.venv\Scripts\python -m scripts.rebuild_external --entity knowledge_document --dry-runQdrant 向量索引应通过 MCP 工具 rebuild_vector_index 以 SQLite 为准重建。
支持 .txt、.md、.markdown 和 .pdf。相同 document-id 会原子替换已有分块：
.venv\Scripts\python -m scripts.ingest_documents .\docs\mqtt.md --source mqtt_docs --document-id mqtt-guide --title "MQTT Guide"仓库在 knowledge/ 中附带 32 份 ESP32、ESP-IDF、MQTT 和 Mosquitto 诊断资料，可重复摄取：
.venv\Scripts\python -m scripts.ingest_recommended_documents稳定的文档 ID 保证重复执行会替换原有分块，而不是生成重复文档。
设置 MQTT_ENABLED=true 后，Diagnosis MCP 订阅：
iot/{device_id}/status
iot/{device_id}/telemetry
iot/{device_id}/logs
iot/{device_id}/fault
iot/{device_id}/heartbeat
iot/{device_id}/remediationControl MCP 使用以下控制主题：
iot/{device_id}/cmd
iot/{device_id}/cmd_ack
iot/{device_id}/remediation
iot/{device_id}/remediation_case运行单设备模拟器：
$env:MQTT_ENABLED = "true"
.venv\Scripts\python -m iot_diagnosis.simulator --device-id ESP32_05 --scenario mqtt_timeout运行 iot_diagnosis/fleet.json 定义的 12 台设备机群：
.venv\Scripts\python -m iot_diagnosis.simulator --host 127.0.0.1 --fleet iot_diagnosis/fleet.json内置场景包括 normal、mqtt_timeout、wifi_weak、sensor_error、unstable、memory_leak 和 watchdog_reset。模拟器还支持 inject_fault 下行动作，可动态注入或清除故障。
在 Compose 的 Diagnosis 容器中可批量生成真实闭环案例：
docker compose exec iot-diagnosis-mcp python scripts/generate_fault_cases.py --rounds 2
docker compose exec iot-diagnosis-mcp python scripts/purge_fault_cases.py查看、预演、应用迁移或备份 SQLite：
.venv\Scripts\python -m scripts.migrate status --service diagnosis
.venv\Scripts\python -m scripts.migrate upgrade --service diagnosis --dry-run
.venv\Scripts\python -m scripts.migrate upgrade --service diagnosis
.venv\Scripts\python -m scripts.migrate backup --service diagnosis --target .\data\diagnosis-backup.db
.venv\Scripts\python -m scripts.migrate status --service control
.venv\Scripts\python -m scripts.migrate upgrade --service control数据保留默认只统计、不删除：
.venv\Scripts\python -m scripts.retention --dry-run确认备份与候选数量后，设置 DIAGNOSIS_RETENTION_DELETE_ENABLED=true，再显式执行：
$env:DIAGNOSIS_RETENTION_DELETE_ENABLED = "true"
.venv\Scripts\python -m scripts.retention --execute默认保留期：遥测和 INFO 日志 14 天、ERROR 日志 90 天、诊断记录 180 天、已完成 outbox 7 天。可通过 .env.example 中的 DIAGNOSIS_*_RETENTION_* 变量调整。
运行确定性 RAG、Router 和 Diagnosis 评测：
.venv\Scripts\python -m scripts.evaluate_rag --database .\data\iot_diagnosis_eval.db报告包含 Recall@K、Precision@K、MRR、Hit Rate、Router/Source/Diagnosis Accuracy、延迟和 Token 使用。可用 --strategy dense|sparse|hybrid 对比检索策略。
对比 384/512/768/1024 chunk size：
.venv\Scripts\python -m scripts.evaluate_chunk_sizes在主项目 GPU Compose 档位中运行真实 Qwen3 检索评测：
docker compose -f compose.yaml -f compose.retrieval-gpu.yaml exec iot-diagnosis-mcp python /app/scripts/evaluate_rag.py --profile live-retrieval --database /app/data/iot_diagnosis.db对已运行的 Diagnosis MCP 做在线协议验收：
.venv\Scripts\python scripts\smoke_diagnosis_server.py
.venv\Scripts\python scripts\smoke_diagnosis_server.py --timeout 180常用配置分组：
分组 | 关键变量 |
Diagnosis 服务 |
|
外部存储 |
|
诊断 LLM |
|
Embedding |
|
Reranker |
|
Control 服务 |
|
MQTT |
|
配置 DIAGNOSIS_LLM_API_KEY 和 DIAGNOSIS_LLM_MODEL 后，复杂问题会调用兼容 Chat Completions 的 Router 与 Diagnosis；未配置或调用失败时使用启发式回退，并在结果中记录回退原因。
生产环境可分别设置 DIAGNOSIS_MCP_BEARER_TOKEN 和 CONTROL_MCP_BEARER_TOKEN。同时把对应的 *_MCP_PUBLIC_URL 设置为客户端可访问的服务 URL。认证只保护 /mcp；健康端点仍可供探针访问。
.venv\Scripts\python -m ruff check common iot_diagnosis iot_control model_service scripts tests
.venv\Scripts\python -m ruff format --check common iot_diagnosis iot_control model_service scripts tests
.venv\Scripts\python -m mypy common iot_diagnosis iot_control model_service
.venv\Scripts\python -m pytest -q tests路径 | 职责 |
| 共享结果结构与 SQLite 迁移基础设施 |
| 诊断 MCP、Repository、RAG、MQTT 消费和模拟器 |
| 控制 MCP、动作策略、提案、命令回执与恢复验证 |
| Qwen3 Embedding/Reranker HTTP 服务及缓存检查 |
| 可摄取的 ESP32/MQTT/Mosquitto 资料 |
| 检索、路由与诊断评测数据 |
| 迁移、摄取、评测、重建、保留与案例维护脚本 |
| 单元、集成、迁移与可靠性测试 |
本地 MQTT 匿名连接只适合开发环境。生产环境必须启用身份认证、TLS 和 Topic ACL，并通过已授权的主后端限制写入、删除、审批和设备控制工具。
This server cannot be deployed
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
MCP-Native LLM Orchestration Agent
AI-powered incident management and server monitoring via MCP.
Tenant-scoped evidence intake and controlled AI context over MCP.
