kl-mcp-client 2.1.12__tar.gz → 2.1.13__tar.gz

{kl_mcp_client-2.1.12 → kl_mcp_client-2.1.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kl-mcp-client
-Version: 2.1.12
+Version: 2.1.13
 Summary: MCP Client for Python
 Author-email: Kyle <hngan.it@gmail.com>
 License: MIT

{kl_mcp_client-2.1.12 → kl_mcp_client-2.1.13}/kl_mcp_client/asyncio/tools.py

@@ -1,373 +1,300 @@
 # async_tools.py
+import logging
 from typing import Any, Dict, Optional
 
 from .client import MCPClient
 
+# ======================================================
+# LOGGER
+# ======================================================
+
+logger = logging.getLogger(__name__)
+
+# ======================================================
+# CLASS
+# ======================================================
+
 
 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
+    Async wrapper cho Google ADK + MCP Server
     """
 
+    # ======================================================
+    # INIT
+    # ======================================================
+
     def __init__(self, client: MCPClient):
         self.client = client
+        logger.info("MCPTools initialized")
+
+    # ======================================================
+    # BROWSER RUNTIME (NO SESSION)
+    # ======================================================
+
+    async def create_browser(self, payload: Optional[Dict[str, Any]] = None):
+        logger.info("create_browser")
+        res = await self.client.call_tool("createBrowser", payload or {})
+        return res.get("structuredContent", {})
+
+    async def release_browser(self, pop_name: str):
+        logger.info("release_browser | %s", pop_name)
+        res = await self.client.call_tool(
+            "releaseBrowser", {"pod_name": pop_name}
+        )
+        return res.get("structuredContent", {})
 
     # ======================================================
     # SESSION MANAGEMENT
     # ======================================================
 
     async def create_session(self, cdpUrl: str) -> Dict[str, Any]:
+        logger.info("create_session | %s", cdpUrl)
         sid = await self.client.create_session(cdpUrl)
         return {"sessionId": sid}
 
     async def close_session(self, sessionId: str) -> Dict[str, Any]:
+        logger.info("close_session | %s", sessionId)
         ok = await self.client.close_session(sessionId)
         return {"ok": bool(ok)}
 
     async def list_sessions(self) -> Dict[str, Any]:
+        logger.debug("list_sessions")
         return {"sessions": self.client.list_local_sessions()}
 
     # ======================================================
-    # NAVIGATION & DOM
+    # TAB MANAGEMENT
     # ======================================================
 
-    async def open_page(self, sessionId: str, url: str) -> Dict[str, Any]:
+    async def new_tab(self, sessionId: str, url: str = "about:blank"):
+        logger.info("new_tab | %s", url)
         res = await self.client.call_tool(
-            "openPage", {"sessionId": sessionId, "url": url}
+            "newTab", {"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})
+    async def close_tab(self, sessionId: str, tabId: str):
+        logger.info("close_tab | %s", tabId)
+        res = await self.client.call_tool(
+            "closeTab", {"sessionId": sessionId, "tabId": tabId}
+        )
         return res.get("structuredContent", {})
 
-    async def screenshot(self, sessionId: str) -> Dict[str, Any]:
-        """
-        ADK Web expects:
-        {
-            "type": "image",
-            "mimeType": "image/png",
-            "data": "<base64>"
-        }
-        """
-        res = await self.client.call_tool("screenshot", {"sessionId": sessionId})
-        return res["content"][0]
+    async def switch_tab(self, sessionId: str, targetId: str):
+        logger.info("switch_tab | %s", targetId)
+        res = await self.client.call_tool(
+            "switchTab", {"sessionId": sessionId, "targetId": targetId}
+        )
+        return res.get("structuredContent", {})
 
-    async def click(self, sessionId: str, selector: str) -> Dict[str, Any]:
+    async def current_tab(self, sessionId: str):
+        logger.debug("current_tab")
         res = await self.client.call_tool(
-            "click", {"sessionId": sessionId, "selector": selector}
+            "currentTab", {"sessionId": sessionId}
         )
         return res.get("structuredContent", {})
 
-    async def type(self, sessionId: str, selector: str, text: str) -> Dict[str, Any]:
+    # ======================================================
+    # NAVIGATION & DOM
+    # ======================================================
+
+    async def open_page(self, sessionId: str, url: str):
+        logger.info("open_page | %s", url)
         res = await self.client.call_tool(
-            "type", {"sessionId": sessionId,
-                     "selector": selector, "text": text}
+            "openPage", {"sessionId": sessionId, "url": url}
         )
         return res.get("structuredContent", {})
 
-    async def evaluate(self, sessionId: str, expression: str) -> Dict[str, Any]:
+    async def get_html(self, sessionId: str):
+        logger.debug("get_html")
+        res = await self.client.call_tool("getHTML", {"sessionId": sessionId})
+        return res.get("structuredContent", {})
+
+    async def evaluate(self, sessionId: str, expression: str):
+        logger.debug("evaluate")
         res = await self.client.call_tool(
             "evaluate", {"sessionId": sessionId, "expression": expression}
         )
         return res.get("structuredContent", {})
 
+    async def screenshot(self, sessionId: str):
+        logger.info("screenshot")
+        res = await self.client.call_tool("screenshot", {"sessionId": sessionId})
+        return res["content"][0]
+
+    async def wait_for_selector(
+        self, sessionId: str, selector: str, timeoutMs: Optional[int] = None
+    ):
+        logger.debug("wait_for_selector | %s", selector)
+        args = {"sessionId": sessionId, "selector": selector}
+        if timeoutMs:
+            args["timeoutMs"] = int(timeoutMs)
+
+        res = await self.client.call_tool("waitForSelector", args)
+        return res.get("structuredContent", {})
+
     # ======================================================
     # ELEMENT UTILITIES
     # ======================================================
 
-    async def find_element(self, sessionId: str, selector: str) -> Dict[str, Any]:
+    async def find_element(self, sessionId: str, selector: str):
+        logger.debug("find_element | %s", selector)
         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]:
+    async def find_all(self, sessionId: str, selector: str):
+        logger.debug("find_all | %s", selector)
         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]:
+    async def get_bounding_box(self, sessionId: str, selector: str):
+        logger.debug("get_bounding_box | %s", selector)
         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]:
+    async def click_bounding_box(self, sessionId: str, selector: str):
+        logger.debug("click_bounding_box | %s", selector)
         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"] = int(timeoutMs)
-
-        res = await self.client.call_tool("waitForSelector", args)
-        return res.get("structuredContent", {})
-
     # ======================================================
-    # TAB MANAGEMENT
+    # ADVANCED FIND / CLICK
     # ======================================================
 
-    async def new_tab(
-        self, sessionId: str, url: Optional[str] = "about:blank"
-    ) -> Dict[str, Any]:
+    async def click(self, sessionId: str, selector: str):
+        logger.debug("click | %s", selector)
         res = await self.client.call_tool(
-            "newTab", {"sessionId": sessionId, "url": url}
+            "click", {"sessionId": sessionId, "selector": selector}
         )
         return res.get("structuredContent", {})
 
-    async def switch_tab(self, sessionId: str, targetId: str) -> Dict[str, Any]:
+    async def type(self, sessionId: str, selector: str, text: str):
+        logger.debug("type | %s", selector)
         res = await self.client.call_tool(
-            "switchTab", {"sessionId": sessionId, "targetId": targetId}
+            "type",
+            {"sessionId": sessionId, "selector": selector, "text": text},
         )
         return res.get("structuredContent", {})
 
-    # ======================================================
-    # ADVANCED ACTIONS
-    # ======================================================
-
-    async def click_to_text(self, sessionId: str, text: str) -> Dict[str, Any]:
+    async def click_to_text(self, sessionId: str, text: str):
+        logger.debug("click_to_text | %s", text)
         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]:
+    async def find_element_xpath(self, sessionId: str, xpath: str):
+        logger.debug("find_element_xpath")
         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]:
+    async def find_element_by_text(self, sessionId: str, text: str):
+        logger.debug("find_element_by_text | %s", text)
         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]:
+    async def click_by_node_id(self, sessionId: str, nodeId: int):
+        logger.debug("click_by_node_id | %s", nodeId)
         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]:
+    async def upload_file(
+        self, sessionId: str, selector: str, filename: str, base64data: str
+    ):
+        logger.info("upload_file | %s", filename)
         res = await self.client.call_tool(
-            "importCookies", {"sessionId": sessionId, "cookies": cookies}
+            "uploadFile",
+            {
+                "sessionId": sessionId,
+                "selector": selector,
+                "filename": filename,
+                "data": base64data,
+            },
         )
         return res.get("structuredContent", {})
 
-    async def get_dom_tree(self, sessionId: str, args: Optional[dict] = None):
-        return await self.client.call_tool(
-            "getDomTree", {"sessionId": sessionId, "args": args or {}}
-        )
-
-    async def get_clickable(self, sessionId: str, args: Optional[dict] = None):
-        return await self.client.call_tool(
-            "getClickable", {"sessionId": sessionId, "args": args or {}}
-        )
-
-    async def selector_map(
-        self, sessionId: str, selector: str, args: Optional[dict] = None
-    ):
-        return await self.client.call_tool(
-            "selectorMap",
-            {"sessionId": sessionId, "selector": selector, "args": args or {}},
+    async def import_cookies(self, sessionId: str, cookies: dict):
+        logger.info("import_cookies")
+        res = await self.client.call_tool(
+            "importCookies", {"sessionId": sessionId, "cookies": cookies}
         )
+        return res.get("structuredContent", {})
 
     # ======================================================
-    # AI / CONTENT PARSING
+    # KEYBOARD
     # ======================================================
 
-    async def parse_html_by_prompt(self, html: str, prompt: str) -> Dict[str, Any]:
-        res = await self.client.call_tool(
-            "parseHTMLByPrompt",
-            {"html": html, "prompt": prompt},
+    async def send_key(self, sessionId: str, key: str):
+        logger.debug("send_key | %s", key)
+        return await self.client.call_tool(
+            "sendKey", {"sessionId": sessionId, "key": key}
         )
-        return res.get("structuredContent", {})
 
     # ======================================================
-    # MOUSE / PERFORM ACTIONS
+    # MOUSE / PERFORM
     # ======================================================
 
-    async def perform_click_xy(
-        self,
-        sessionId: str,
-        x: float,
-        y: float,
-    ) -> Dict[str, Any]:
-        """
-        Move mouse smoothly to (x, y) and left click.
-        """
-        res = await self.client.call_tool(
+    async def perform_click_xy(self, sessionId: str, x: float, y: float):
+        logger.debug("perform_click_xy | %s,%s", x, y)
+        return await self.client.call_tool(
             "perform",
-            {
-                "sessionId": sessionId,
-                "action": "click",
-                "x": float(x),
-                "y": float(y),
-            },
+            {"sessionId": sessionId, "action": "click", "x": x, "y": y},
         )
-        return res.get("structuredContent", {})
 
     async def perform_drag(
-        self,
-        sessionId: str,
-        from_x: float,
-        from_y: float,
-        to_x: float,
-        to_y: float,
-    ) -> Dict[str, Any]:
-        """
-        Drag mouse from (from_x, from_y) to (to_x, to_y).
-        """
-        res = await self.client.call_tool(
+        self, sessionId: str, from_x: float, from_y: float, to_x: float, to_y: float
+    ):
+        logger.debug("perform_drag")
+        return await self.client.call_tool(
             "perform",
             {
                 "sessionId": sessionId,
                 "action": "drag",
-                "from": {"x": float(from_x), "y": float(from_y)},
-                "to": {"x": float(to_x), "y": float(to_y)},
+                "from": {"x": from_x, "y": from_y},
+                "to": {"x": to_x, "y": to_y},
             },
         )
-        return res.get("structuredContent", {})
 
-    async def perform_hover(
-        self,
-        sessionId: str,
-        x: float,
-        y: float,
-    ) -> Dict[str, Any]:
-        """
-        Move mouse smoothly to (x, y) without clicking.
-        """
-        res = await self.client.call_tool(
+    async def perform_hover(self, sessionId: str, x: float, y: float):
+        logger.debug("perform_hover | %s,%s", x, y)
+        return await self.client.call_tool(
             "perform",
-            {
-                "sessionId": sessionId,
-                "action": "hover",
-                "x": float(x),
-                "y": float(y),
-            },
-        )
-        return res.get("structuredContent", {})
-
-    # CLEAN TEXT / READ MODE
-    # ======================================================
-    async def get_clean_text(self, sessionId: str) -> Dict[str, Any]:
-        """
-        Lấy toàn bộ visible text đã được clean trên trang hiện tại.
-        - Bỏ script/style/iframe/svg/canvas
-        - Chỉ text nhìn thấy (display/visibility/opacity)
-
-        Returns:
-            {
-              "text": "...",
-              "length": 12345
-            }
-        """
-        res = await self.client.call_tool(
-            "getCleanText",
-            {"sessionId": sessionId},
-        )
-        return res.get("structuredContent", {})
-
-    # ======================================================
-    # KEYBOARD (ASYNC)
-    # ======================================================
-    async def send_key(
-        self,
-        sessionId: str,
-        key: str,
-    ) -> Dict[str, Any]:
-        """
-        Send a keyboard key to the active page (async).
-
-        Args:
-            sessionId: MCP browser session
-            key: Keyboard key (e.g. "Enter", "Tab", "Escape", "ArrowDown",
-                 "Ctrl+a", "Ctrl+Enter")
-
-        Returns:
-            structuredContent from MCP server
-        """
-        return await self.call_tool_structured(
-            "sendKey",
-            {
-                "sessionId": sessionId,
-                "key": key,
-            },
+            {"sessionId": sessionId, "action": "hover", "x": x, "y": y},
         )
 
     # ======================================================
-    # BROWSER RUNTIME (NO SESSION)
+    # CLEAN TEXT
     # ======================================================
 
-    async def create_browser(
-        self,
-        payload: Optional[Dict[str, Any]] = None,
-    ) -> Dict[str, Any]:
-        """
-        Start browser runtime (idempotent).
-        - KHÔNG tạo session
-        - Dùng cho warm-up / admin / scheduler
-
-        payload: ThirdPartyOpenRequest (optional)
-        """
+    async def get_clean_text(self, sessionId: str):
+        logger.debug("get_clean_text")
         res = await self.client.call_tool(
-            "createBrowser",
-            payload or {},
+            "getCleanText", {"sessionId": sessionId}
         )
         return res.get("structuredContent", {})
 
-    async def release_browser(self, pop_name: str) -> Dict[str, Any]:
-        """
-        Release / stop browser runtime.
-        - KHÔNG cần payload
-        """
-        res = await self.client.call_tool(
-            "releaseBrowser",
-            {
-                "pod_name": pop_name
-            },
-        )
-        return res.get("structuredContent", {})
     # ======================================================
-    # VIEWPORT (Playwright-style, ASYNC)
+    # VIEWPORT
     # ======================================================
 
-    async def get_viewport(self, sessionId: str) -> Dict[str, Any]:
-        """
-        Get current browser viewport.
-        Equivalent to Playwright page.viewportSize().
-        """
+    async def get_viewport(self, sessionId: str):
+        logger.debug("get_viewport")
         res = await self.client.call_tool(
-            "viewport",
-            {
-                "sessionId": sessionId,
-            },
+            "viewport", {"sessionId": sessionId}
         )
         return res.get("structuredContent", {})
 
@@ -379,46 +306,30 @@ class MCPTools:
         height: int,
         deviceScaleFactor: float = 1.0,
         mobile: bool = False,
-    ) -> Dict[str, Any]:
-        """
-        Set browser viewport (Playwright-like).
-
-        Args:
-            width: viewport width
-            height: viewport height
-            deviceScaleFactor: default 1.0
-            mobile: mobile emulation flag
-        """
+    ):
+        logger.info("set_viewport | %sx%s", width, height)
         res = await self.client.call_tool(
             "viewport",
             {
                 "sessionId": sessionId,
                 "viewport": {
-                    "width": int(width),
-                    "height": int(height),
-                    "deviceScaleFactor": float(deviceScaleFactor),
-                    "mobile": bool(mobile),
+                    "width": width,
+                    "height": height,
+                    "deviceScaleFactor": deviceScaleFactor,
+                    "mobile": mobile,
                 },
             },
         )
         return res.get("structuredContent", {})
+
     # ======================================================
-    # CURRENT TAB
+    # AI / PARSING
     # ======================================================
 
-    async def current_tab(self, sessionId: str) -> Dict[str, Any]:
-        """
-        Get current active browser tab ID.
-
-        Returns:
-            {
-              "tabId": "<targetId>"
-            }
-        """
+    async def parse_html_by_prompt(self, html: str, prompt: str):
+        logger.info("parse_html_by_prompt")
         res = await self.client.call_tool(
-            "currentTab",
-            {
-                "sessionId": sessionId,
-            },
+            "parseHTMLByPrompt",
+            {"html": html, "prompt": prompt},
         )
         return res.get("structuredContent", {})