# kl-mcp-client (Python) 🚀

Thư viện Python Client thế hệ mới (Agentic v1.6.1) dùng để điều khiển trình duyệt Web thông qua Model Context Protocol (MCP). Đây là giải pháp tối ưu cho việc xây dựng các Agent có khả năng tự động hóa trình duyệt một cách thông minh, linh hoạt và chính xác cao.

## ✨ Các Tính năng Đột phá (v1.6.1)

-   🤖 **AI Semantic Search**: Tìm kiếm phần tử bằng ngôn ngữ tự nhiên.
-   🧠 **Context Analysis**: Phân tích toàn bộ ngữ cảnh trang web (DOM Context).
-   ⚡ **AI-Driven Action**: `click_by_prompt` giúp AI tự tìm và nhấp chuột trực tiếp.
-   📊 **Smart Extraction**: Trích xuất dữ liệu thô sang cấu trúc JSON thông minh.
-   🌊 **Memory-Safe Streaming**: `evaluate_stream_all` hỗ trợ lấy dữ liệu mảng lớn.
-   📂 **Unified File Handling**: Quy trình tải lên tệp gộp thông minh.

## 📦 Cài đặt

```bash
pip install kl-mcp-client
```

---

## 🚀 Hướng dẫn Bắt đầu Nhanh

Thư viện hỗ trợ đồng thời hai chế độ lập trình:

### ⏱️ Chế độ Đồng bộ (Synchronous)
```python
from kl_mcp_client.tools import MCPTools
tools = MCPTools()
tools.connect_mcp("http://localhost:8080")
sid = tools.create_session("ws://localhost:9222")["sessionId"]
tools.open_page(sid, "https://google.com")
tools.close_session(sid)
```

### ⚡ Chế độ Bất đồng bộ (Asynchronous)
```python
import asyncio
from kl_mcp_client.asyncio.tools import MCPTools
async def main():
    tools = MCPTools()
    tools.connect_mcp("http://localhost:8080")
    res = await tools.create_session("ws://localhost:9222")
    sid = res["sessionId"]
    await tools.open_page(sid, "https://github.com")
    await tools.close_session(sid)
asyncio.run(main())
```

---

## 📘 Tài liệu Hướng dẫn Chi tiết (Full Documentation)

### 1. Quản lý Phiên & Điều hướng (Session & Navigation)

| Công cụ | Mô tả | 🚀 **MCP Server** |
| :--- | :--- | :--- |
| `connect_mcp(url)` | Kết nối tới máy chủ MCP | v1.0.0+ |
| `create_session(cdpUrl)` | Khởi tạo phiên điều khiển trình duyệt | v1.0.0+ |
| `open_page(sid, url)` | Di chuyển đến địa chỉ URL | v1.0.0+ |
| `get_html(sid)` | Lấy mã nguồn HTML | v1.0.0+ |
| `get_clean_text(sid)` | Lấy văn bản đã lọc bỏ tag | v1.0.0+ |
| `screenshot(sid)` | Chụp ảnh màn hình (Base64) | v1.0.0+ |
| `get_cookies(sid)` | Lấy danh sách Cookies | v1.0.0+ |
| `import_cookies(sid, cookies)` | Nạp Cookies vào phiên | v1.0.0+ |

---

### 2. AI & Tương tác Thông minh (AI Interaction)

Bộ công cụ mạnh mẽ nhất giúp Agent hiểu và tác động lên trang web qua ngôn ngữ tự nhiên.

*   **`find_element_by_prompt(sid, prompt)`** (🚀 **v1.5.0+**): Tìm 1 phần tử qua mô tả.
*   **`find_elements_by_prompt(sid, prompt)`** (🚀 **v1.6.1+**): Tìm danh sách phần tử qua mô tả.
*   **`find_element_context(sid, prompt)`** (🚀 **v1.6.1+**): Tìm phần tử bằng phân tích ngữ cảnh (Context Mode).
*   **`click_by_prompt(sid, prompt)`** (🚀 **v1.6.1+**): AI tự tìm và Nhấp chuột vào mục tiêu.
*   **`extract_structured(sid, prompt)`** (🚀 **v1.6.1+**): Trích xuất nội dung trang web thành JSON.

---

### 3. Tự động hóa & Luồng dữ liệu (Automation & Data Streaming)

Hỗ trợ trích xuất dữ liệu lớn mà không gây treo hệ thống.

*   **`evaluate_stream_all(sid, expression, chunkSize, max_items)`** (🚀 **v1.6.0+**): 
    - Tự động kéo toàn bộ dữ liệu từ trình duyệt theo từng đoạn (chunk).
*   **`wait_for_selector(sid, selector, timeout)`** (🚀 **v1.0.0+**): Chờ đợi phần tử xuất hiện mới thực hiện lệnh tiếp theo.
*   **`scroll(sid, x, y, selector, position)`** (🚀 **v1.0.0+**): Cuộn trang linh hoạt.

---

### 4. Điều khiển & Nhập liệu (Input & Controls)

*   **`click(sid, selector)`** / **`click_to_text(sid, text)`**: Các hành động nhấp chuột cơ bản.
*   **`type(sid, selector, text)`**: Nhập liệu vào ô input.
*   **`send_text(sid, text, interval)`**: Mô phỏng gõ phím với khoảng nghỉ tự nhiên (Stealthy mode).
*   **`send_combo(sid, text)`**: Gửi tổ hợp phím như `Control+A`, `Command+C`.
*   **`drag_and_drop(sid, from_x, from_y, to_x, to_y)`**: Kéo thả giữa 2 tọa độ.

---

### 5. Quản lý Tệp & Tải lên (File & Upload)

*   **`upload_file(sid, selector, file_path)`** (v1.0.0) ⭐: 
    - Cách dễ nhất để tải tệp lên. 
    - Tự động gửi tệp lên server và gắn vào ô `<input type="file">` trên web.

---

## 🛠️ Ví dụ Thực tế (Examples)

Kiểm tra thư mục [`kl_mcp_client/examples/`](./kl_mcp_client/examples/) để xem các kịch bản mẫu:
- `ai_extraction.py`: Trích xuất AI chuyên sâu.
- `data_streaming.py`: Trích xuất Big Data.
- `async_example.py`: Tự động hóa bất đồng bộ tốc độ cao.

## 📄 Bản quyền
Dự án được phát hành dưới giấy phép mã nguồn mở.
