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

kl_mcp_client/__init__.py

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

kl_mcp_client/__version__.py

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

kl_mcp_client/async/__init__.py

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

kl_mcp_client/async/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()

kl_mcp_client/async/tools.py

@@ -0,0 +1,179 @@
+# async_tools.py
+from typing import Any, Dict, Optional
+
+from .client import MCPClient
+
+
+class MCPTools:
+    """
+    Async wrapper cho Google ADK + MCP Server.
+    - Dùng MCPClientAsync (httpx async)
+    - Tất cả method đều async
+    - Screenshot trả về đúng format ADK Web yêu cầu
+    """
+
+    def __init__(self, client: MCPClient):
+        self.client = client
+
+    # ======================================================
+    # SESSION MANAGEMENT
+    # ======================================================
+
+    async def create_session(self, cdpUrl: str) -> Dict[str, Any]:
+        sid = await self.client.create_session(cdpUrl)
+        return {"sessionId": sid}
+
+    async def close_session(self, sessionId: str) -> Dict[str, Any]:
+        ok = await self.client.close_session(sessionId)
+        return {"ok": bool(ok)}
+
+    async def list_sessions(self) -> Dict[str, Any]:
+        return {"sessions": self.client.list_local_sessions()}
+
+    # ======================================================
+    # NAVIGATION & DOM
+    # ======================================================
+
+    async def open_page(self, sessionId: str, url: str) -> Dict[str, Any]:
+        res = await self.client.call_tool(
+            "openPage", {"sessionId": sessionId, "url": url}
+        )
+        return res.get("structuredContent", {})
+
+    async def get_html(self, sessionId: str) -> Dict[str, Any]:
+        res = await self.client.call_tool("getHTML", {"sessionId": sessionId})
+        return res.get("structuredContent", {})
+
+    async def screenshot(self, sessionId: str) -> Dict[str, Any]:
+        """
+        ADK Web expects this structure:
+        {
+            "type": "image",
+            "mimeType": "image/png",
+            "data": "<base64>"
+        }
+        """
+        res = await self.client.call_tool("screenshot", {"sessionId": sessionId})
+        return res["content"][0]
+
+    async def click(self, sessionId: str, selector: str) -> Dict[str, Any]:
+        res = await self.client.call_tool(
+            "click", {"sessionId": sessionId, "selector": selector}
+        )
+        return res.get("structuredContent", {})
+
+    async def type(self, sessionId: str, selector: str, text: str) -> Dict[str, Any]:
+        res = await self.client.call_tool(
+            "type", {"sessionId": sessionId, "selector": selector, "text": text}
+        )
+        return res.get("structuredContent", {})
+
+    async def evaluate(self, sessionId: str, expression: str) -> Dict[str, Any]:
+        res = await self.client.call_tool(
+            "evaluate", {"sessionId": sessionId, "expression": expression}
+        )
+        return res.get("structuredContent", {})
+
+    # ======================================================
+    # ELEMENT UTILITIES
+    # ======================================================
+
+    async def find_element(self, sessionId: str, selector: str) -> Dict[str, Any]:
+        res = await self.client.call_tool(
+            "findElement", {"sessionId": sessionId, "selector": selector}
+        )
+        return res.get("structuredContent", {})
+
+    async def find_all(self, sessionId: str, selector: str) -> Dict[str, Any]:
+        res = await self.client.call_tool(
+            "findAll", {"sessionId": sessionId, "selector": selector}
+        )
+        return res.get("structuredContent", {})
+
+    async def get_bounding_box(self, sessionId: str, selector: str) -> Dict[str, Any]:
+        res = await self.client.call_tool(
+            "getBoundingBox", {"sessionId": sessionId, "selector": selector}
+        )
+        return res.get("structuredContent", {})
+
+    async def click_bounding_box(self, sessionId: str, selector: str) -> Dict[str, Any]:
+        res = await self.client.call_tool(
+            "clickBoundingBox", {"sessionId": sessionId, "selector": selector}
+        )
+        return res.get("structuredContent", {})
+
+    async def upload_file(
+        self, sessionId: str, selector: str, filename: str, base64data: str
+    ) -> Dict[str, Any]:
+        res = await self.client.call_tool(
+            "uploadFile",
+            {
+                "sessionId": sessionId,
+                "selector": selector,
+                "filename": filename,
+                "data": base64data,
+            },
+        )
+        return res.get("structuredContent", {})
+
+    async 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"] = timeoutMs
+
+        res = await self.client.call_tool("waitForSelector", args)
+        return res.get("structuredContent", {})
+
+    # ======================================================
+    # TAB MANAGEMENT
+    # ======================================================
+
+    async def new_tab(
+        self, sessionId: str, url: Optional[str] = "about:blank"
+    ) -> Dict[str, Any]:
+        res = await self.client.call_tool(
+            "newTab", {"sessionId": sessionId, "url": url}
+        )
+        return res.get("structuredContent", {})
+
+    async def switch_tab(self, sessionId: str, targetId: str) -> Dict[str, Any]:
+        res = await self.client.call_tool(
+            "switchTab", {"sessionId": sessionId, "targetId": targetId}
+        )
+        return res.get("structuredContent", {})
+
+    # ======================================================
+    # ADVANCED
+    # ======================================================
+
+    async def click_to_text(self, sessionId: str, text: str) -> dict:
+        res = await self.client.call_tool(
+            "clickToText", {"sessionId": sessionId, "text": text}
+        )
+        return res.get("structuredContent", {})
+
+    async def find_element_xpath(self, sessionId: str, xpath: str) -> Dict[str, Any]:
+        res = await self.client.call_tool(
+            "findElementByXPath", {"sessionId": sessionId, "xpath": xpath}
+        )
+        return res.get("structuredContent", {})
+
+    async def find_element_by_text(self, sessionId: str, text: str) -> Dict[str, Any]:
+        res = await self.client.call_tool(
+            "findElementByText", {"sessionId": sessionId, "text": text}
+        )
+        return res.get("structuredContent", {})
+
+    async def click_by_node_id(self, sessionId: str, nodeId: int) -> Dict[str, Any]:
+        res = await self.client.call_tool(
+            "clickByNodeId", {"sessionId": sessionId, "nodeId": nodeId}
+        )
+        return res.get("structuredContent", {})
+
+    async def import_cookies(self, sessionId: str, cookies: dict) -> Dict[str, Any]:
+        res = await self.client.call_tool(
+            "importCookies", {"sessionId": sessionId, "cookies": cookies}
+        )
+        return res.get("structuredContent", {})

kl_mcp_client-1.0.2.dist-info/METADATA

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

@@ -0,0 +1,11 @@
+kl_mcp_client/__init__.py,sha256=pdJdBcEH5HaRuHSe2B7VUyRgH5ad3u1dDc4euZMDRMY,106
+kl_mcp_client/__version__.py,sha256=CCYQUt19bi0kfo0Q8q8snnwgw_c9F3s6FFxTMsX1yDE,22
+kl_mcp_client/client.py,sha256=0kkC1oGS4lMbQmsNtKa7fp_2aZdcqVZLssTmsVKmai0,4668
+kl_mcp_client/tools.py,sha256=GC5IRYnWH35wBNCMrFGYE8VQx4bhj5uiJNDPBjDfdvQ,6615
+kl_mcp_client/async/__init__.py,sha256=pdJdBcEH5HaRuHSe2B7VUyRgH5ad3u1dDc4euZMDRMY,106
+kl_mcp_client/async/client.py,sha256=bRpDmDU4FhehKWfQ1ftVPSQ7tSioR4GrpD3NX_msRqc,4131
+kl_mcp_client/async/tools.py,sha256=98L9JM5QM1jST-ICFACNc5Uwekaj6Y60ZU51-fRfaaY,6785
+kl_mcp_client-1.0.2.dist-info/METADATA,sha256=lsT9pIjx9cFaKJ3cB3p2-M8HeMao8eYoPBudVj4xl0k,4432
+kl_mcp_client-1.0.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+kl_mcp_client-1.0.2.dist-info/top_level.txt,sha256=wd_HFFyGjiKavwACuj8Ny0svtVyNsrxCSVU48EkoQ7c,14
+kl_mcp_client-1.0.2.dist-info/RECORD,,

kl_mcp_client-1.0.2.dist-info/top_level.txt

@@ -0,0 +1 @@
+kl_mcp_client

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