Metadata-Version: 2.4
Name: kl-mcp-client
Version: 2.1.18
Summary: MCP Client for Python
Author-email: Kyle <hngan.it@gmail.com>
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.32.5
Requires-Dist: httpx>=0.28.1

# 📦 kl-mcp-client

**kl-mcp-client** là SDK Python giúp giao tiếp với **MCP (Model Context Protocol) Browser Server** — một server trung gian điều khiển Chrome/Chromium qua CDP.

Thư viện này được thiết kế để:

- Điều khiển Chrome tự động: click, nhập liệu, screenshot, đọc DOM…
- Kết nối trình duyệt Chrome Remote qua CDP (Chrome DevTools Protocol)
- Tích hợp làm Web Automation Agent trong **Google ADK**
- Hoạt động độc lập như một browser automation SDK

---

# 🚀 Cài đặt

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

---

# 🧩 Thành phần của thư viện

Package gồm 2 module chính:

| File        | Vai trò                                                            |
| ----------- | ------------------------------------------------------------------ |
| `client.py` | JSON-RPC HTTP Client giao tiếp với MCP Server                      |
| `tools.py`  | Wrapper cấp cao, cung cấp API tiện dụng cho các Agent & automation |

---

## 🔌 API / Các tools (MCPTools)

`MCPTools` là wrapper cấp cao giúp gọi các tool trên MCP Server. Dưới đây là các nhóm method chính (tên method theo `tools.py`):

- **Kết nối / Khởi tạo**
    - `connect_mcp(mcpUrl)` — khởi tạo client tới MCP server.

- **Quản lý session**
    - `create_session(cdpUrl)`, `close_session(sessionId)`, `list_sessions()`

- **Quản lý tab**
    - `new_tab(sessionId, url)`, `switch_tab(sessionId, targetId)`, `close_tab(sessionId, tabId)`, `current_tab(sessionId)`

- **Navigation / DOM**
    - `open_page(sessionId, url)`, `get_html(sessionId)`, `evaluate(sessionId, expression)`, `screenshot(sessionId)`, `wait_for_selector(sessionId, selector, timeoutMs=None)`

- **Element utilities**
    - `find_element(sessionId, selector)`, `find_all(sessionId, selector)`, `get_bounding_box(sessionId, selector)`, `click_bounding_box(sessionId, selector)`

- **Hành động cơ bản**
    - `click(sessionId, selector)`, `type(sessionId, selector, text)`

- **Tìm / click nâng cao**
    - `click_to_text(sessionId, text)`, `find_element_xpath(sessionId, xpath)`, `find_element_by_text(sessionId, text)`, `find_element_by_prompt(sessionId, prompt)`, `click_by_node_id(sessionId, nodeId)`

- **File / Cookie**
    - `upload_file(sessionId, selector, file_path)`, `import_cookies(sessionId, cookies)`, `cookies(sessionId)`

- **AI / Parsing**
    - `parse_html_by_prompt(html, prompt)`

- **Stream**
    - `evaluate_stream(sessionId, expression, chunkSize=100)`, `stream_pull(stream_id, offset=0, limit=100)`, `evaluate_stream_all(...)`

- **Keyboard / Mouse / Perform**
    - `send_keys(sessionId, key, interval=100)`, `perform(...)`, `drag_and_drop(...)`, `hover(...)`, `scroll(...)`

- **Browser runtime (không cần session)**
    - `create_browser(payload)`, `release_browser(pop_name)`

- **Viewport**
    - `get_viewport(sessionId)`, `current_url(sessionId)`, `set_viewport(...)`

Mẹo nhanh — ví dụ khởi chạy và dùng `MCPTools`:

```python
from kl_mcp_client.tools import MCPTools

tools = MCPTools()
tools.connect_mcp("http://localhost:3000/mcp")
sid = tools.create_session("http://localhost:9222/json/version")["sessionId"]
tools.open_page(sid, "https://example.com")
html = tools.get_html(sid)
```

Lưu ý: hầu hết method yêu cầu đã gọi `connect_mcp` trước (decorator `_ensure_client`).


# ✨ Tính năng chính

### ✔ Điều khiển trình duyệt
- Mở tab, load URL  
- Click CSS selector, click bằng text, click bằng nodeId  
- Nhập text vào input  
- Screenshot (chuẩn ADK hiển thị được)

### ✔ DOM Tools nâng cao
- Find element by selector / text / XPath  
- Lấy bounding box  
- Lấy toàn bộ DOM Tree  
- Lấy danh sách clickable elements  
- Highlight elements (nếu server hỗ trợ)

### ✔ Tương tác hệ thống
- Upload file bằng base64  
- Import cookies  
- Evaluate JavaScript  

### ✔ Chrome Remote Debugging
- Tạo session từ địa chỉ:  
  `http://localhost:9222/json/version`

---

# 🧭 Cách sử dụng

## 1. Import client & tools

```python
from kl_mcp_client.client import MCPClient
from kl_mcp_client.tools import MCPTools
```

---

## 2. Tạo kết nối tới MCP Server

```python
mcp = MCPClient(
    base_url="http://localhost:3000/mcp",
    timeout=30,
    retries=2
)
tools = MCPTools(mcp)
```

---

## 3. Tạo session (Chrome Remote)

```python
session = tools.create_session("http://localhost:9222/json/version")
sid = session["sessionId"]
```

---

## 4. Mở URL

```python
tools.open_page(sid, "https://google.com")
```

---

## 5. Screenshot (hiển thị được trong ADK Web)

```python
img = tools.screenshot(sid)
print(img)
```

Trả về:

```json
{
  "type": "image",
  "mimeType": "image/png",
  "data": "<base64>"
}
```

---

## 6. Click & Type

```python
tools.click(sid, "#login")
tools.type(sid, "input[name=q]", "Hello world")
```

---

## 7. Find Elements

```python
tools.find_element(sid, "#content")
tools.find_element_by_text(sid, "Đăng nhập")
tools.find_element_xpath(sid, "//input[@type='email']")
```

---

## 8. Upload File

```python
import base64
data = base64.b64encode(open("test.pdf", "rb").read()).decode()

tools.upload_file(
    sid,
    selector="input[type=file]",
    filename="test.pdf",
    base64Data=data
)
```

---

## 9. Import Cookies

```python
tools.import_cookies(sid, [
    {"name": "token", "value": "abc", "domain": "example.com", "path": "/"}
])
```

---

## 10. Đóng session

```python
tools.close_session(sid)
```

---

# 🧪 Ví dụ đầy đủ

```python
from kl_mcp_client.client import MCPClient
from kl_mcp_client.tools import MCPTools
import base64

mcp = MCPClient("http://localhost:3000/mcp")
tools = MCPTools(mcp)

# Create session
sid = tools.create_session("http://localhost:9222/json/version")["sessionId"]

# Navigate
tools.open_page(sid, "https://google.com")

# Screenshot
img = tools.screenshot(sid)
print("Screenshot returned:", img["mimeType"])

# Search
tools.type(sid, "input[name=q]", "Hello MCP")
tools.click_to_text(sid, "Google Search")

# Close
tools.close_session(sid)
```

---

# 🏗 Kiến trúc

```
Python App / ADK Agent
          ↓
      kl-mcp-client
          ↓
   MCP Browser Server
          ↓
      Chrome / CDP
```

---

# 📘 Yêu cầu

- Python ≥ 3.8  
- MCP Server chạy sẵn (Chromedp backend)
- Chrome/Chromium với cờ:

```
chrome.exe --remote-debugging-port=9222
```

---

# 📝 License

MIT License.

---

# 📚 Liên hệ

Nếu bạn cần:

- MCP Server đầy đủ  
- Hỗ trợ tích hợp ADK Web Agent  
- Thêm tool: DOM Tree, highlight, selector map…  
