kl-mcp-client 2.1.26

MCP Client for Python

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

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)

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)

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/ để 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ở.