# Chatbot Lịch Sử XiaoZhi MCP

Đây là một **chatbot hỏi đáp về lịch sử** sử dụng **semantic search (tìm kiếm ngữ nghĩa)** trên cơ sở dữ liệu câu hỏi – trả lời.

Hệ thống kết nối với **XiaoZhi MCP Agent** thông qua WebSocket, sau đó truy vấn cơ sở dữ liệu bằng **embedding model** để tìm câu trả lời phù hợp nhất.

---

# Kiến trúc hệ thống

Người dùng / XiaoZhi Agent
↓
Kết nối MCP (WebSocket)
↓
`mcp_client.py`
↓
Tìm kiếm ngữ nghĩa (FastEmbed / SentenceTransformer)
↓
SQLite Database
↓
Trả lời cho Agent

---

# Cấu trúc project

```
xiaozhi-mcp/
│
├── data.csv              # Dữ liệu câu hỏi – trả lời lịch sử
├── data.txt              # Dữ liệu văn bản (tùy chọn)
├── knowledge.db          # Cơ sở dữ liệu SQLite
│
├── import.js             # Import dữ liệu CSV vào database
├── reset.js              # Reset database
│
├── server.js             # Script Node.js hỗ trợ
├── package.json          # Thông tin package Node.js
│
├── semantic_server.py    # API server tìm kiếm ngữ nghĩa
├── mcp_client.py         # Client kết nối MCP với XiaoZhi
│
├── node_modules
└── venv
```

---

# Yêu cầu hệ thống

## Python

Python 3.9 trở lên

Cài đặt thư viện:

```
pip install fastembed websockets numpy flask sentence-transformers
```

---

## Node.js

Node.js 18 trở lên

Cài đặt dependency:

```
npm install
```

---

# Định dạng dữ liệu

Dữ liệu chatbot được lưu trong file `data.csv`.

Ví dụ:

```
question,answer
Chiến thắng Điện Biên Phủ diễn ra năm nào?,1954
Ai là người lãnh đạo cách mạng Việt Nam?,Hồ Chí Minh
Chiến tranh thế giới thứ hai kết thúc năm nào?,1945
```

---

# Import dữ liệu vào database

Chạy lệnh:

```
node import.js
```

Script sẽ:

* đọc file `data.csv`
* tạo bảng `qa`
* import dữ liệu vào `knowledge.db`

Cấu trúc bảng:

```
qa(
  question TEXT,
  answer TEXT
)
```

---

# Reset database

Nếu muốn xóa toàn bộ dữ liệu và tạo lại database:

```
node reset.js
```

---

# Chạy Semantic Server

Server này dùng để tìm kiếm câu trả lời phù hợp nhất từ database.

Chạy:

```
python semantic_server.py
```

Server sẽ chạy tại:

```
http://localhost:3001
```

Kiểm tra server:

```
GET /mcp
```

Kết quả:

```
{
  "status": "MCP server running"
}
```

---

# Chạy MCP Client

Client này kết nối với XiaoZhi Agent thông qua WebSocket.

Chạy:

```
python mcp_client.py
```

Chức năng:

* nhận câu hỏi từ agent
* chuyển câu hỏi thành embedding
* so sánh với dữ liệu trong database
* trả về câu trả lời phù hợp nhất

Ví dụ log:

```
✅ Connected: agent_1
[agent_1] Query: Chiến tranh thế giới thứ hai kết thúc khi nào?
⭐ Best score: 0.91
```

---

# Semantic Search

Hệ thống sử dụng model:

```
sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2
```

Đây là model embedding đa ngôn ngữ hỗ trợ tiếng Việt.

Độ tương đồng được tính bằng **cosine similarity**.

Ngưỡng trả lời:

```
0.80
```

Nếu độ tương đồng thấp hơn ngưỡng này, chatbot sẽ không trả lời.

---

# MCP Tool

Agent sử dụng tool:

```
search_knowledge
```

Chức năng:

Tìm kiếm thông tin lịch sử trong cơ sở dữ liệu.

---

# Lưu ý


Trong `mcp_client.py`, thay `YOUR_TOKEN` bằng TOKEN trong console của Xiaozhi:

```
wss://api.xiaozhi.me/mcp/?token=YOUR_TOKEN
```

---

# Giấy phép

MIT License