kl-mcp-client 1.0.0__py3-none-any.whl → 1.0.1__py3-none-any.whl

kl_mcp_client-1.0.1.dist-info/METADATA

@@ -0,0 +1,251 @@
+Metadata-Version: 2.4
+Name: kl-mcp-client
+Version: 1.0.1
+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.1.dist-info/RECORD

@@ -0,0 +1,4 @@
+kl_mcp_client-1.0.1.dist-info/METADATA,sha256=7_9H-uKTIcEAJXtOlYhIqGkYOOhhtT3e4h-Ep2Wv71g,4432
+kl_mcp_client-1.0.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+kl_mcp_client-1.0.1.dist-info/top_level.txt,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+kl_mcp_client-1.0.1.dist-info/RECORD,,

kl_mcp_client-1.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+

kl_mcp_client-1.0.0.dist-info/METADATA

@@ -1,8 +0,0 @@
-Metadata-Version: 2.4
-Name: kl-mcp-client
-Version: 1.0.0
-Summary: MCP Client
-Author-email: Kyle <hngan.it@gmail.com>
-License: MIT
-Requires-Python: >=3.7
-Description-Content-Type: text/markdown

kl_mcp_client-1.0.0.dist-info/RECORD

@@ -1,7 +0,0 @@
-mcp_client/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-mcp_client/client.py,sha256=0kkC1oGS4lMbQmsNtKa7fp_2aZdcqVZLssTmsVKmai0,4668
-mcp_client/tools.py,sha256=GC5IRYnWH35wBNCMrFGYE8VQx4bhj5uiJNDPBjDfdvQ,6615
-kl_mcp_client-1.0.0.dist-info/METADATA,sha256=3NUizw9TxUkbninPSWsL0jSiy9FxWNnSB3J6ZMVpls8,193
-kl_mcp_client-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-kl_mcp_client-1.0.0.dist-info/top_level.txt,sha256=ZSWRi9Sxwn8pf9wHQny6lLfmYSfG4JpbzGdVrwvQoxM,11
-kl_mcp_client-1.0.0.dist-info/RECORD,,

kl_mcp_client-1.0.0.dist-info/top_level.txt

@@ -1 +0,0 @@
-mcp_client

mcp_client/client.py

@@ -1,136 +0,0 @@
-# mcp_client.py
-import time
-import uuid
-from typing import Any, Dict, List, Optional
-
-import requests
-
-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, int(retries))
-        # local cache of sessions -> can be used to reuse session ids
-        self._sessions: Dict[str, Dict[str, Any]] = {}
-
-    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 = requests.post(
-                    self.base_url,
-                    json=payload,
-                    headers=self.headers,
-                    timeout=self.timeout,
-                )
-                r.raise_for_status()
-            except requests.RequestException as e:
-                last_exc = e
-                time.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 "error" in data and data["error"] is not None:
-                err = data["error"]
-                raise MCPError(
-                    {
-                        "code": err.get("code"),
-                        "message": err.get("message"),
-                        "data": err.get("data"),
-                    }
-                )
-            return data.get("result", {})
-
-        # all retries failed
-        raise MCPError(f"Request failed after {self.retries} attempts: {last_exc}")
-
-    # ----- Generic callTool wrapper -----
-    def call_tool_structured(
-        self, tool: str, arguments: Optional[Dict[str, Any]] = None
-    ) -> Dict[str, Any]:
-        args = {"tool": tool, "arguments": arguments or {}}
-        res = self._rpc("callTool", args)
-        # return structuredContent when possible
-        if isinstance(res, dict) and "structuredContent" in res:
-            return res["structuredContent"]
-        # fallback: maybe top-level result
-        return res
-
-    # ----- Generic callTool wrapper -----
-    def call_tool(
-        self, tool: str, arguments: Optional[Dict[str, Any]] = None
-    ) -> Dict[str, Any]:
-        args = {"tool": tool, "arguments": arguments or {}}
-        res = self._rpc("callTool", args)
-        # # return structuredContent when possible
-        # if isinstance(res, dict) and "structuredContent" in res:
-        #     return res["structuredContent"]
-        # # fallback: maybe top-level result
-        return res
-
-    # ----- Session helpers -----
-    def create_session(self, cdpUrl: str) -> str:
-        result = self.call_tool_structured("createSession", {"cdpUrl": cdpUrl})
-        # Many MCP servers put sessionId in structuredContent.sessionId or result.sessionId
-        session_id = None
-        if isinstance(result, dict):
-            session_id = (
-                result.get("sessionId") or result.get("session_id") or result.get("id")
-            )
-        if not session_id:
-            # fallback: try raw result text or content
-            raise MCPError("createSession did not return sessionId")
-        # store meta
-        self._sessions[session_id] = {"created_at": time.time()}
-        return session_id
-
-    def close_session(self, session_id: str) -> bool:
-        try:
-            self.call_tool_structured("closeSession", {"sessionId": session_id})
-            if session_id in self._sessions:
-                del self._sessions[session_id]
-            return True
-        except MCPError:
-            # still remove local record if present
-            self._sessions.pop(session_id, None)
-            raise
-
-    def list_local_sessions(self) -> List[str]:
-        return list(self._sessions.keys())

mcp_client/tools.py

@@ -1,173 +0,0 @@
-from typing import Any, Dict, Optional
-
-from .client import MCPClient
-
-
-class MCPTools:
-    """
-    Wrapper chuẩn cho Google ADK + MCP Server.
-    - Tool nào trả text/html/... → dùng structuredContent
-    - Tool screenshot → trả đúng content để ADK Web hiển thị image
-    """
-
-    def __init__(self, client: MCPClient):
-        self.client = client
-
-    # ======================================================
-    # SESSION MANAGEMENT
-    # ======================================================
-
-    def create_session(self, cdpUrl: str) -> Dict[str, Any]:
-        sid = self.client.create_session(cdpUrl)
-        return {"sessionId": sid}
-
-    def close_session(self, sessionId: str) -> Dict[str, Any]:
-        ok = self.client.close_session(sessionId)
-        return {"ok": bool(ok)}
-
-    def list_sessions(self) -> Dict[str, Any]:
-        return {"sessions": self.client.list_local_sessions()}
-
-    # ======================================================
-    # NAVIGATION & DOM
-    # ======================================================
-
-    def open_page(self, sessionId: str, url: str) -> Dict[str, Any]:
-        return self.client.call_tool(
-            "openPage", {"sessionId": sessionId, "url": url}
-        ).get("structuredContent", {})
-
-    def get_html(self, sessionId: str) -> Dict[str, Any]:
-        return self.client.call_tool("getHTML", {"sessionId": sessionId}).get(
-            "structuredContent", {}
-        )
-
-    def screenshot(self, sessionId: str) -> Dict[str, Any]:
-        """
-        Trả về đúng phần IMAGE content:
-        {
-          "type": "image",
-          "mimeType": "image/png",
-          "data": "<base64>"
-        }
-        """
-        full = self.client.call_tool("screenshot", {"sessionId": sessionId})
-        return full["content"][0]
-
-    def click(self, sessionId: str, selector: str) -> Dict[str, Any]:
-        return self.client.call_tool(
-            "click", {"sessionId": sessionId, "selector": selector}
-        ).get("structuredContent", {})
-
-    def type(self, sessionId: str, selector: str, text: str) -> Dict[str, Any]:
-        return self.client.call_tool(
-            "type", {"sessionId": sessionId, "selector": selector, "text": text}
-        ).get("structuredContent", {})
-
-    def evaluate(self, sessionId: str, expression: str) -> Dict[str, Any]:
-        return self.client.call_tool(
-            "evaluate", {"sessionId": sessionId, "expression": expression}
-        ).get("structuredContent", {})
-
-    # ======================================================
-    # ELEMENT UTILITIES
-    # ======================================================
-
-    def find_element(self, sessionId: str, selector: str) -> Dict[str, Any]:
-        return self.client.call_tool(
-            "findElement", {"sessionId": sessionId, "selector": selector}
-        ).get("structuredContent", {})
-
-    def find_all(self, sessionId: str, selector: str) -> Dict[str, Any]:
-        return self.client.call_tool(
-            "findAll", {"sessionId": sessionId, "selector": selector}
-        ).get("structuredContent", {})
-
-    def get_bounding_box(self, sessionId: str, selector: str) -> Dict[str, Any]:
-        return self.client.call_tool(
-            "getBoundingBox", {"sessionId": sessionId, "selector": selector}
-        ).get("structuredContent", {})
-
-    def click_bounding_box(self, sessionId: str, selector: str) -> Dict[str, Any]:
-        return self.client.call_tool(
-            "clickBoundingBox", {"sessionId": sessionId, "selector": selector}
-        ).get("structuredContent", {})
-
-    def upload_file(
-        self, sessionId: str, selector: str, filename: str, base64data: str
-    ) -> Dict[str, Any]:
-        """
-        Upload file vào input[type=file]
-        Args:
-            sessionId: MCP browser session
-            selector: CSS selector, ví dụ 'input[type=file]'
-            filename: tên file trên browser side
-            base64data: dữ liệu base64 (không kèm header)
-        Returns:
-            structured result từ server
-        """
-        return self.client.call_tool(
-            "uploadFile",
-            {
-                "sessionId": sessionId,
-                "selector": selector,
-                "filename": filename,
-                "data": base64data,
-            },
-        ).get("structuredContent", {})
-
-    def wait_for_selector(
-        self, sessionId: str, selector: str, timeoutMs: Optional[int] = None
-    ) -> Dict[str, Any]:
-        args = {"sessionId": sessionId, "selector": selector}
-        if timeoutMs is not None:
-            args["timeoutMs"] = int(timeoutMs)
-
-        return self.client.call_tool("waitForSelector", args).get(
-            "structuredContent", {}
-        )
-
-    # ======================================================
-    # TAB MANAGEMENT
-    # ======================================================
-
-    def new_tab(
-        self, sessionId: str, url: Optional[str] = "about:blank"
-    ) -> Dict[str, Any]:
-        return self.client.call_tool(
-            "newTab", {"sessionId": sessionId, "url": url}
-        ).get("structuredContent", {})
-
-    def switch_tab(self, sessionId: str, targetId: str) -> Dict[str, Any]:
-        return self.client.call_tool(
-            "switchTab", {"sessionId": sessionId, "targetId": targetId}
-        ).get("structuredContent", {})
-
-    # ======================================================
-    # ADVANCED ACTIONS
-    # ======================================================
-
-    def click_to_text(self, sessionId: str, text: str) -> dict:
-        return self.client.call_tool(
-            "clickToText", {"sessionId": sessionId, "text": text}
-        ).get("structuredContent", {})
-
-    def find_element_xpath(self, sessionId: str, xpath: str) -> Dict[str, Any]:
-        return self.client.call_tool(
-            "findElementByXPath", {"sessionId": sessionId, "xpath": xpath}
-        ).get("structuredContent", {})
-
-    def find_element_by_text(self, sessionId: str, text: str) -> Dict[str, Any]:
-        return self.client.call_tool(
-            "findElementByText", {"sessionId": sessionId, "text": text}
-        ).get("structuredContent", {})
-
-    def click_by_node_id(self, sessionId: str, nodeId: int) -> Dict[str, Any]:
-        return self.client.call_tool(
-            "clickByNodeId", {"sessionId": sessionId, "nodeId": nodeId}
-        ).get("structuredContent", {})
-
-    def import_cookies(self, sessionId: str, cookies: dict) -> Dict[str, Any]:
-        return self.client.call_tool(
-            "importCookies", {"sessionId": sessionId, "cookies": cookies}
-        ).get("structuredContent", {})