kl-mcp-client 1.0.3__tar.gz

kl_mcp_client-1.0.3/PKG-INFO

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: kl-mcp-client
+Version: 1.0.3
+Summary: MCP Client
+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 |
+
+---
+
+# ✨ 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…  

kl_mcp_client-1.0.3/README.md

@@ -0,0 +1,240 @@
+# 📦 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 |
+
+---
+
+# ✨ 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…  

kl_mcp_client-1.0.3/kl_mcp_client/__init__.py

@@ -0,0 +1,7 @@
+from .client import MCPClient
+from .tools import MCPTools
+
+__all__ = [
+    "MCPClient",
+    "MCPTools",
+]

kl_mcp_client-1.0.3/kl_mcp_client/__version__.py

@@ -0,0 +1 @@
+__VERSION__ = "1.0.0"

kl_mcp_client-1.0.3/kl_mcp_client/asyncio/__init__.py

@@ -0,0 +1,7 @@
+from .client import MCPClient
+from .tools import MCPTools
+
+__all__ = [
+    "MCPClient",
+    "MCPTools",
+]

kl_mcp_client-1.0.3/kl_mcp_client/asyncio/client.py

@@ -0,0 +1,141 @@
+# mcp_client_async.py
+import uuid
+import time
+from typing import Any, Dict, List, Optional
+
+import httpx
+import asyncio
+
+
+DEFAULT_HEADERS = {
+    "Content-Type": "application/json",
+    "Accept": "application/json, text/event-stream",
+}
+
+
+class MCPError(Exception):
+    pass
+
+
+class MCPClient:
+    def __init__(
+        self,
+        base_url: str,
+        headers: Optional[Dict[str, str]] = None,
+        timeout: int = 30,
+        retries: int = 1,
+    ):
+        """
+        base_url: full MCP HTTP endpoint e.g. http://localhost:3000/mcp
+        headers: extra headers (e.g. {"Authorization": "Bearer ..."})
+        timeout: request timeout seconds
+        retries: number of attempts for network errors
+        """
+        self.base_url = base_url.rstrip("/")
+        self.headers = DEFAULT_HEADERS.copy()
+        if headers:
+            self.headers.update(headers)
+
+        self.timeout = timeout
+        self.retries = max(1, retries)
+
+        self._client = httpx.AsyncClient(
+            timeout=self.timeout,
+            headers=self.headers,
+        )
+
+        # local session cache
+        self._sessions: Dict[str, Dict[str, Any]] = {}
+
+    async def _rpc(self, method: str, params: Dict[str, Any]) -> Dict[str, Any]:
+        payload = {
+            "jsonrpc": "2.0",
+            "id": str(uuid.uuid4()),
+            "method": method,
+            "params": params,
+        }
+
+        last_exc = None
+        for attempt in range(self.retries):
+            try:
+                r = await self._client.post(
+                    self.base_url,
+                    json=payload,
+                )
+                r.raise_for_status()
+            except Exception as e:
+                last_exc = e
+                await asyncio.sleep(0.2 * (attempt + 1))
+                continue
+
+            try:
+                data = r.json()
+            except ValueError:
+                raise MCPError(
+                    f"Invalid JSON response (status {r.status_code}): {r.text}"
+                )
+
+            if err := data.get("error"):
+                raise MCPError(
+                    {
+                        "code": err.get("code"),
+                        "message": err.get("message"),
+                        "data": err.get("data"),
+                    }
+                )
+
+            return data.get("result", {})
+
+        raise MCPError(f"Request failed after {self.retries} attempts: {last_exc}")
+
+    # -------------------------
+    # Generic tool wrappers
+    # -------------------------
+
+    async def call_tool_structured(
+        self, tool: str, arguments: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        res = await self._rpc("callTool", {"tool": tool, "arguments": arguments or {}})
+
+        if isinstance(res, dict) and "structuredContent" in res:
+            return res["structuredContent"]
+
+        return res
+
+    async def call_tool(
+        self, tool: str, arguments: Optional[Dict[str, Any]] = None
+    ) -> Dict[str, Any]:
+        return await self._rpc("callTool", {"tool": tool, "arguments": arguments or {}})
+
+    # -------------------------
+    # Session helpers
+    # -------------------------
+
+    async def create_session(self, cdpUrl: str) -> str:
+        result = await self.call_tool_structured("createSession", {"cdpUrl": cdpUrl})
+
+        session_id = (
+            result.get("sessionId") or result.get("session_id") or result.get("id")
+        )
+
+        if not session_id:
+            raise MCPError("createSession did not return sessionId")
+
+        self._sessions[session_id] = {"created_at": time.time()}
+        return session_id
+
+    async def close_session(self, session_id: str) -> bool:
+        try:
+            await self.call_tool_structured("closeSession", {"sessionId": session_id})
+            self._sessions.pop(session_id, None)
+            return True
+        except MCPError:
+            self._sessions.pop(session_id, None)
+            raise
+
+    def list_local_sessions(self) -> List[str]:
+        return list(self._sessions.keys())
+
+    async def aclose(self):
+        """Close the httpx async client"""
+        await self._client.aclose()