kl-mcp-client 2.1.12__py3-none-any.whl → 2.1.14__py3-none-any.whl

kl_mcp_client/tools.py

@@ -1,8 +1,19 @@
+import logging
 from functools import wraps
 from typing import Any, Dict, Optional
 
 from .client import MCPClient
 
+# ======================================================
+# LOGGER
+# ======================================================
+
+logger = logging.getLogger(__name__)
+
+# ======================================================
+# DECORATOR
+# ======================================================
+
 
 def _ensure_client(func):
     """Decorator kiểm tra self.client != None trước khi gọi tool."""
@@ -10,6 +21,7 @@ def _ensure_client(func):
     @wraps(func)
     def wrapper(self, *args, **kwargs):
         if self.client is None:
+            logger.error("MCP client not connected")
             return {
                 "ok": False,
                 "error": "MCP client not connected. Call connect mcp server first.",
@@ -19,361 +31,320 @@ def _ensure_client(func):
     return wrapper
 
 
+# ======================================================
+# CLASS
+# ======================================================
+
 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
     """
 
+    # ======================================================
+    # INIT / CONNECT
+    # ======================================================
+
     def __init__(self):
         self.client = None
+        logger.info("MCPTools initialized")
 
-    # ======================================================
-    # SESSION MANAGEMENT
-    # ======================================================
     def connect_mcp(self, mcpUrl: str) -> Dict[str, Any]:
-        # sid = self.client.create_session(mcpUrl)
+        logger.info("connect_mcp | %s", mcpUrl)
+
         self.client = MCPClient(
-            base_url=mcpUrl, headers=None, timeout=30, retries=2)
+            base_url=mcpUrl,
+            headers=None,
+            timeout=30,
+            retries=2
+        )
         return {"ok": True, "cdpUrl": "http://localhost:9222"}
 
+    # ======================================================
+    # SESSION MANAGEMENT
+    # ======================================================
+
     @_ensure_client
-    def create_session(self, cdpUrl: str) -> Dict[str, Any]:
+    def create_session(self, cdpUrl: str):
+        logger.info("create_session | %s", cdpUrl)
         sid = self.client.create_session(cdpUrl)
         return {"sessionId": sid}
 
     @_ensure_client
-    def close_session(self, sessionId: str) -> Dict[str, Any]:
+    def close_session(self, sessionId: str):
+        logger.info("close_session | %s", sessionId)
         ok = self.client.close_session(sessionId)
         return {"ok": bool(ok)}
 
     @_ensure_client
-    def list_sessions(self) -> Dict[str, Any]:
+    def list_sessions(self):
+        logger.debug("list_sessions")
         return {"sessions": self.client.list_local_sessions()}
 
     # ======================================================
-    # NAVIGATION & DOM
+    # TAB MANAGEMENT
     # ======================================================
+
     @_ensure_client
-    def open_page(self, sessionId: str, url: str) -> Dict[str, Any]:
+    def new_tab(self, sessionId: str, url: Optional[str] = "about:blank"):
+        logger.info("new_tab | %s", url)
         return self.client.call_tool(
-            "openPage", {"sessionId": sessionId, "url": url}
+            "newTab", {"sessionId": sessionId, "url": url}
         ).get("structuredContent", {})
 
     @_ensure_client
-    def get_html(self, sessionId: str) -> Dict[str, Any]:
-        return self.client.call_tool("getHTML", {"sessionId": sessionId}).get(
-            "structuredContent", {}
-        )
-
-    @_ensure_client
-    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]
-
-    @_ensure_client
-    def click(self, sessionId: str, selector: str) -> Dict[str, Any]:
+    def switch_tab(self, sessionId: str, targetId: str):
+        logger.info("switch_tab | %s", targetId)
         return self.client.call_tool(
-            "click", {"sessionId": sessionId, "selector": selector}
+            "switchTab", {"sessionId": sessionId, "targetId": targetId}
         ).get("structuredContent", {})
 
     @_ensure_client
-    def type(self, sessionId: str, selector: str, text: str) -> Dict[str, Any]:
+    def close_tab(self, sessionId: str, tabId: str):
+        logger.info("close_tab | %s", tabId)
         return self.client.call_tool(
-            "type", {"sessionId": sessionId,
-                     "selector": selector, "text": text}
+            "closeTab", {"sessionId": sessionId, "tabId": tabId}
         ).get("structuredContent", {})
 
     @_ensure_client
-    def evaluate(self, sessionId: str, expression: str) -> Dict[str, Any]:
+    def current_tab(self, sessionId: str):
+        logger.debug("current_tab")
         return self.client.call_tool(
-            "evaluate", {"sessionId": sessionId, "expression": expression}
+            "currentTab", {"sessionId": sessionId}
         ).get("structuredContent", {})
 
     # ======================================================
-    # ELEMENT UTILITIES
+    # NAVIGATION / DOM
     # ======================================================
-    @_ensure_client
-    def find_element(self, sessionId: str, selector: str) -> Dict[str, Any]:
-        return self.client.call_tool(
-            "findElement", {"sessionId": sessionId, "selector": selector}
-        ).get("structuredContent", {})
 
     @_ensure_client
-    def find_all(self, sessionId: str, selector: str) -> Dict[str, Any]:
+    def open_page(self, sessionId: str, url: str):
+        logger.info("open_page | %s", url)
         return self.client.call_tool(
-            "findAll", {"sessionId": sessionId, "selector": selector}
+            "openPage", {"sessionId": sessionId, "url": url}
         ).get("structuredContent", {})
 
     @_ensure_client
-    def get_bounding_box(self, sessionId: str, selector: str) -> Dict[str, Any]:
+    def get_html(self, sessionId: str):
+        logger.debug("get_html")
         return self.client.call_tool(
-            "getBoundingBox", {"sessionId": sessionId, "selector": selector}
+            "getHTML", {"sessionId": sessionId}
         ).get("structuredContent", {})
 
     @_ensure_client
-    def click_bounding_box(self, sessionId: str, selector: str) -> Dict[str, Any]:
+    def evaluate(self, sessionId: str, expression: str):
+        logger.debug("evaluate")
         return self.client.call_tool(
-            "clickBoundingBox", {"sessionId": sessionId, "selector": selector}
+            "evaluate", {"sessionId": sessionId, "expression": expression}
         ).get("structuredContent", {})
 
     @_ensure_client
-    def upload_file(
-        self,
-        sessionId: str,
-        selector: str,
-        file_path: str,
-    ) -> Dict[str, Any]:
-        """
-        Upload file (kể cả video lớn) vào input[type=file] theo luồng mới:
-        1. Multipart upload file lên MCP server
-        2. Nhận uploadId
-        3. Gọi MCP tool uploadFile với uploadId
-
-        Args:
-            sessionId: MCP browser session
-            selector: CSS selector, ví dụ 'input[type=file]'
-            file_path: đường dẫn file local (video, pdf, doc, ...)
-        """
-
-        if not file_path:
-            return {"ok": False, "error": "file_path is required"}
-
-        # --------------------------------------------------
-        # 1️⃣ Multipart upload file lên MCP server
-        # --------------------------------------------------
-        try:
-            with open(file_path, "rb") as f:
-                resp = self.client.http.post(
-                    "/upload",
-                    files={"file": f},
-                    timeout=300,  # upload file lớn
-                )
-        except Exception as e:
-            return {"ok": False, "error": f"upload http failed: {e}"}
-
-        if resp.status_code != 200:
-            return {
-                "ok": False,
-                "error": f"upload http error {resp.status_code}: {resp.text}",
-            }
-
-        data = resp.json()
-        upload_id = data.get("uploadId")
-        if not upload_id:
-            return {"ok": False, "error": "uploadId not returned from server"}
-
-        # --------------------------------------------------
-        # 2️⃣ Gọi MCP tool uploadFile (PATH MODE)
-        # --------------------------------------------------
-        result = self.client.call_tool(
-            "uploadFile",
-            {
-                "sessionId": sessionId,
-                "selector": selector,
-                "uploadId": upload_id,
-            },
+    def screenshot(self, sessionId: str):
+        logger.info("screenshot")
+        full = self.client.call_tool(
+            "screenshot", {"sessionId": sessionId}
         )
-
-        return result.get("structuredContent", {})
+        return full["content"][0]
 
     @_ensure_client
     def wait_for_selector(
         self, sessionId: str, selector: str, timeoutMs: Optional[int] = None
-    ) -> Dict[str, Any]:
+    ):
+        logger.debug("wait_for_selector | %s", selector)
         args = {"sessionId": sessionId, "selector": selector}
         if timeoutMs is not None:
-            args["timeoutMs"] = int(timeoutMs)
+            args["timeout"] = int(timeoutMs)
 
-        return self.client.call_tool("waitForSelector", args).get(
-            "structuredContent", {}
-        )
+        return self.client.call_tool(
+            "waitForSelector", args
+        ).get("structuredContent", {})
 
     # ======================================================
-    # TAB MANAGEMENT
+    # ELEMENT UTILITIES
     # ======================================================
+
     @_ensure_client
-    def new_tab(
-        self, sessionId: str, url: Optional[str] = "about:blank"
-    ) -> Dict[str, Any]:
+    def find_element(self, sessionId: str, selector: str):
+        logger.debug("find_element | %s", selector)
         return self.client.call_tool(
-            "newTab", {"sessionId": sessionId, "url": url}
+            "findElement", {"sessionId": sessionId, "selector": selector}
         ).get("structuredContent", {})
 
     @_ensure_client
-    def switch_tab(self, sessionId: str, targetId: str) -> Dict[str, Any]:
+    def find_all(self, sessionId: str, selector: str):
+        logger.debug("find_all | %s", selector)
         return self.client.call_tool(
-            "switchTab", {"sessionId": sessionId, "targetId": targetId}
+            "findAll", {"sessionId": sessionId, "selector": selector}
         ).get("structuredContent", {})
 
-    # ======================================================
-    # ADVANCED ACTIONS
-    # ======================================================
     @_ensure_client
-    def click_to_text(self, sessionId: str, text: str) -> dict:
+    def get_bounding_box(self, sessionId: str, selector: str):
+        logger.debug("get_bounding_box | %s", selector)
         return self.client.call_tool(
-            "clickToText", {"sessionId": sessionId, "text": text}
+            "getBoundingBox", {"sessionId": sessionId, "selector": selector}
         ).get("structuredContent", {})
 
     @_ensure_client
-    def find_element_xpath(self, sessionId: str, xpath: str) -> Dict[str, Any]:
+    def click_bounding_box(self, sessionId: str, selector: str):
+        logger.debug("click_bounding_box | %s", selector)
         return self.client.call_tool(
-            "findElementByXPath", {"sessionId": sessionId, "xpath": xpath}
+            "clickBoundingBox", {"sessionId": sessionId, "selector": selector}
         ).get("structuredContent", {})
 
+    # ======================================================
+    # BASIC ACTIONS
+    # ======================================================
+
     @_ensure_client
-    def find_element_by_text(self, sessionId: str, text: str) -> Dict[str, Any]:
+    def click(self, sessionId: str, selector: str):
+        logger.debug("click | %s", selector)
         return self.client.call_tool(
-            "findElementByText", {"sessionId": sessionId, "text": text}
+            "click", {"sessionId": sessionId, "selector": selector}
         ).get("structuredContent", {})
 
     @_ensure_client
-    def click_by_node_id(self, sessionId: str, nodeId: int) -> Dict[str, Any]:
+    def type(self, sessionId: str, selector: str, text: str):
+        logger.debug("type | %s", selector)
         return self.client.call_tool(
-            "clickByNodeId", {"sessionId": sessionId, "nodeId": nodeId}
+            "type", {"sessionId": sessionId,
+                     "selector": selector, "text": text}
         ).get("structuredContent", {})
 
+    # ======================================================
+    # ADVANCED FIND / CLICK
+    # ======================================================
+
     @_ensure_client
-    def import_cookies(self, sessionId: str, cookies: dict) -> Dict[str, Any]:
+    def click_to_text(self, sessionId: str, text: str):
+        logger.debug("click_to_text | %s", text)
         return self.client.call_tool(
-            "importCookies", {"sessionId": sessionId, "cookies": cookies}
+            "clickToText", {"sessionId": sessionId, "text": text}
         ).get("structuredContent", {})
 
     @_ensure_client
-    def get_dom_tree(self, sessionId, args=None):
+    def find_element_xpath(self, sessionId: str, xpath: str):
+        logger.debug("find_element_xpath")
         return self.client.call_tool(
-            "getDomTree", {"sessionId": sessionId, "args": args or {}}
-        )
+            "findElementByXPath", {"sessionId": sessionId, "xpath": xpath}
+        ).get("structuredContent", {})
 
     @_ensure_client
-    def get_clickable(self, sessionId, args=None):
+    def find_element_by_text(self, sessionId: str, text: str):
+        logger.debug("find_element_by_text | %s", text)
         return self.client.call_tool(
-            "getClickable", {"sessionId": sessionId, "args": args or {}}
-        )
+            "findElementByText", {"sessionId": sessionId, "text": text}
+        ).get("structuredContent", {})
 
     @_ensure_client
-    def selector_map(self, sessionId, selector, args=None):
+    def click_by_node_id(self, sessionId: str, nodeId: int):
+        logger.debug("click_by_node_id | %s", nodeId)
         return self.client.call_tool(
-            "selectorMap",
-            {"sessionId": sessionId, "selector": selector, "args": args or {}},
-        )
+            "clickByNodeId", {"sessionId": sessionId, "nodeId": nodeId}
+        ).get("structuredContent", {})
 
     @_ensure_client
-    def find_element_by_prompt(self, sessionId: str, prompt: str) -> Dict[str, Any]:
-        """
-        Gọi tool findElementByPrompt trên MCP server.
-        Trả về structuredContent gồm: html, nodeId.
-        """
+    def find_element_by_prompt(self, sessionId: str, prompt: str):
+        logger.info("find_element_by_prompt")
         return self.client.call_tool(
             "findElementByPrompt", {"sessionId": sessionId, "prompt": prompt}
         ).get("structuredContent", {})
 
     # ======================================================
-    # AI / CONTENT PARSING
+    # FILE / COOKIE
     # ======================================================
+
     @_ensure_client
-    def parse_html_by_prompt(self, html: str, prompt: str) -> Dict[str, Any]:
-        """
-        Parse HTML content using AI with dynamic prompt-defined structure.
+    def upload_file(self, sessionId: str, selector: str, file_path: str):
+        logger.info("upload_file | %s", file_path)
 
-        Args:
-            html: Raw HTML string (client-provided)
-            prompt: Instruction that defines what to extract and output structure
-                    Example:
-                      - "Hãy lấy nội dung bài viết, struct trả về { content }"
-                      - "Hãy lấy số lượng like, share, comment, trả JSON { like, share, comment }"
+        if not file_path:
+            return {"ok": False, "error": "file_path is required"}
+
+        try:
+            with open(file_path, "rb") as f:
+                resp = self.client.http.post(
+                    "/upload",
+                    files={"file": f},
+                    timeout=300,
+                )
+        except Exception as e:
+            logger.exception("upload http failed")
+            return {"ok": False, "error": f"upload http failed: {e}"}
+
+        if resp.status_code != 200:
+            return {
+                "ok": False,
+                "error": f"http {resp.status_code}: {resp.text}",
+            }
+
+        upload_id = resp.json().get("uploadId")
+        if not upload_id:
+            return {"ok": False, "error": "uploadId not returned"}
 
-        Returns:
-            structuredContent (dynamic JSON defined by prompt)
-        """
         return self.client.call_tool(
-            "parseHTMLByPrompt",
+            "uploadFile",
             {
-                "html": html,
-                "prompt": prompt,
+                "sessionId": sessionId,
+                "selector": selector,
+                "uploadId": upload_id,
             },
         ).get("structuredContent", {})
 
+    @_ensure_client
+    def import_cookies(self, sessionId: str, cookies: dict):
+        logger.info("import_cookies")
+        return self.client.call_tool(
+            "importCookies", {"sessionId": sessionId, "cookies": cookies}
+        ).get("structuredContent", {})
+
     # ======================================================
-    # CLEAN TEXT / READ MODE
+    # AI / PARSING
     # ======================================================
+
     @_ensure_client
-    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)
+    def parse_html_by_prompt(self, html: str, prompt: str):
+        logger.info("parse_html_by_prompt")
+        return self.client.call_tool(
+            "parseHTMLByPrompt",
+            {"html": html, "prompt": prompt}
+        ).get("structuredContent", {})
 
-        Returns:
-            {
-              "text": "...",
-              "length": 12345
-            }
-        """
+    # ======================================================
+    # CLEAN TEXT
+    # ======================================================
+
+    @_ensure_client
+    def get_clean_text(self, sessionId: str):
+        logger.debug("get_clean_text")
         return self.client.call_tool(
             "getCleanText",
-            {"sessionId": sessionId},
+            {"sessionId": sessionId}
         ).get("structuredContent", {})
 
+    # ======================================================
+    # STREAM
+    # ======================================================
+
     @_ensure_client
-    def evaluate_stream(
-        self,
-        sessionId: str,
-        expression: str,
-        chunkSize: int = 100,
-    ) -> Dict[str, Any]:
-        """
-        Evaluate JS expression theo chế độ STREAM.
-        Dùng khi kết quả là array lớn (DOM, list, table, ...)
-
-        Returns (init response):
-        {
-          "stream_id": "...",
-          "total": 1234,
-          "chunk_size": 100
-        }
-        """
+    def evaluate_stream(self, sessionId: str, expression: str, chunkSize: int = 100):
+        logger.debug("evaluate_stream")
         return self.client.call_tool(
             "evaluate.stream",
             {
                 "sessionId": sessionId,
                 "expression": expression,
-                "chunkSize": int(chunkSize),
+                "chunkSize": chunkSize,
             },
         ).get("structuredContent", {})
 
     @_ensure_client
-    def stream_pull(
-        self,
-        stream_id: str,
-        offset: int = 0,
-        limit: int = 100,
-    ) -> Dict[str, Any]:
-        """
-        Kéo 1 chunk từ stream đã tạo bởi evaluate.stream
-
-        Returns:
-        {
-          "items": [...],
-          "offset": 0,
-          "has_more": true
-        }
-        """
+    def stream_pull(self, stream_id: str, offset: int = 0, limit: int = 100):
+        logger.debug("stream_pull")
         return self.client.call_tool(
             "stream.pull",
             {
                 "stream_id": stream_id,
-                "offset": int(offset),
-                "limit": int(limit),
+                "offset": offset,
+                "limit": limit,
             },
         ).get("structuredContent", {})
 
@@ -385,19 +356,10 @@ class MCPTools:
         chunkSize: int = 100,
         max_items: Optional[int] = None,
     ):
-        """
-        Helper: evaluate.stream + tự động pull toàn bộ dữ liệu.
-
-        ⚠️ Chỉ dùng khi bạn THỰC SỰ cần full data.
-        """
-        init = self.evaluate_stream(
-            sessionId=sessionId,
-            expression=expression,
-            chunkSize=chunkSize,
-        )
+        logger.info("evaluate_stream_all")
 
+        init = self.evaluate_stream(sessionId, expression, chunkSize)
         stream_id = init.get("stream_id")
-        total = init.get("total", 0)
 
         if not stream_id:
             return []
@@ -406,14 +368,8 @@ class MCPTools:
         offset = 0
 
         while True:
-            chunk = self.stream_pull(
-                stream_id=stream_id,
-                offset=offset,
-                limit=chunkSize,
-            )
-
-            part = chunk.get("items", [])
-            items.extend(part)
+            chunk = self.stream_pull(stream_id, offset, chunkSize)
+            items.extend(chunk.get("items", []))
 
             if max_items and len(items) >= max_items:
                 return items[:max_items]
@@ -425,33 +381,22 @@ class MCPTools:
 
         return items
 
-    @_ensure_client
-    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["timeout"] = int(timeoutMs)
-
-        return self.client.call_tool("waitForSelector", args).get(
-            "structuredContent", {}
-        )
+    # ======================================================
+    # KEYBOARD
+    # ======================================================
 
     @_ensure_client
-    def send_keys(
-        self, sessionId: str, key: str, interval: int = 100
-    ) -> Dict[str, Any]:
-        """
-        Gửi phím: enter, tab, esc, ctrl+c, ctrl+shift+tab, ...
-        """
+    def send_keys(self, sessionId: str, key: str, interval: int = 100):
+        logger.debug("send_keys | %s", key)
         return self.client.call_tool(
             "sendKeys",
-            {"sessionId": sessionId, "text": key, "interval": interval},
+            {"sessionId": sessionId, "text": key, "interval": interval}
         ).get("structuredContent", {})
 
+    # ======================================================
+    # PERFORM / MOUSE
+    # ======================================================
+
     @_ensure_client
     def perform(
         self,
@@ -463,18 +408,10 @@ class MCPTools:
         y: Optional[float] = None,
         from_point: Optional[dict] = None,
         to_point: Optional[dict] = None,
-    ) -> Dict[str, Any]:
-        """
-        action:
-        - click (x,y)
-        - move / hover (x,y)
-        - drag (from -> to)
-        - type (target, value)
-        """
-        args = {
-            "sessionId": sessionId,
-            "action": action,
-        }
+    ):
+        logger.debug("perform | %s", action)
+
+        args = {"sessionId": sessionId, "action": action}
 
         if target is not None:
             args["target"] = target
@@ -489,7 +426,9 @@ class MCPTools:
         if to_point is not None:
             args["to"] = to_point
 
-        return self.client.call_tool("perform", args).get("structuredContent", {})
+        return self.client.call_tool(
+            "perform", args
+        ).get("structuredContent", {})
 
     @_ensure_client
     def drag_and_drop(
@@ -500,6 +439,7 @@ class MCPTools:
         to_x: float,
         to_y: float,
     ):
+        logger.debug("drag_and_drop")
         return self.perform(
             sessionId=sessionId,
             action="drag",
@@ -507,7 +447,9 @@ class MCPTools:
             to_point={"x": to_x, "y": to_y},
         )
 
+    @_ensure_client
     def hover(self, sessionId: str, x: float, y: float):
+        logger.debug("hover")
         return self.perform(
             sessionId=sessionId,
             action="hover",
@@ -523,24 +465,11 @@ class MCPTools:
         x: Optional[float] = None,
         y: Optional[float] = None,
         selector: Optional[str] = None,
-        position: Optional[str] = None,  # "top" | "bottom"
-    ) -> Dict[str, Any]:
-        """
-        Scroll trang web.
-
-        Cách dùng:
-        - Scroll theo pixel:
-            scroll(sessionId, y=500)
-        - Scroll tới element:
-            scroll(sessionId, selector="#footer")
-        - Scroll top / bottom:
-            scroll(sessionId, position="top")
-            scroll(sessionId, position="bottom")
-        """
-
-        args: Dict[str, Any] = {
-            "sessionId": sessionId,
-        }
+        position: Optional[str] = None,
+    ):
+        logger.debug("scroll")
+
+        args = {"sessionId": sessionId}
 
         if x is not None:
             args["x"] = float(x)
@@ -552,60 +481,48 @@ class MCPTools:
             args["position"] = position
 
         if len(args) == 1:
-            return {
-                "ok": False,
-                "error": "scroll requires x/y or selector or position",
-            }
+            return {"ok": False, "error": "scroll requires x/y or selector or position"}
 
         return self.client.call_tool(
-            "scroll",
-            args,
+            "scroll", args
         ).get("structuredContent", {})
-        # ======================================================
+
+    # ======================================================
     # BROWSER RUNTIME (NO SESSION)
     # ======================================================
 
     @_ensure_client
-    def create_browser(self, payload: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
-        """
-        Start browser runtime (idempotent).
-        Không tạo session, chỉ đảm bảo browser đang RUNNING.
-
-        payload: map cho ThirdPartyOpenRequest
-        """
+    def create_browser(self, payload: Optional[Dict[str, Any]] = None):
+        logger.info("create_browser")
         return self.client.call_tool(
-            "createBrowser",
-            payload or {},
+            "createBrowser", payload or {}
         ).get("structuredContent", {})
 
     @_ensure_client
-    def release_browser(self, pop_name: str) -> Dict[str, Any]:
-        """
-        Release / stop browser runtime.
-        """
+    def release_browser(self, pop_name: str):
+        logger.info("release_browser | %s", pop_name)
         return self.client.call_tool(
-            "releaseBrowser",
-            {
-                "pod_name": pop_name
-            },
+            "releaseBrowser", {"pod_name": pop_name}
         ).get("structuredContent", {})
+
     # ======================================================
-    # VIEWPORT (Playwright-style)
+    # VIEWPORT
     # ======================================================
 
     @_ensure_client
-    def get_viewport(self, sessionId: str) -> Dict[str, Any]:
-        """
-        Get current browser viewport.
-        Equivalent to Playwright page.viewportSize().
-        """
+    def get_viewport(self, sessionId: str):
+        logger.debug("get_viewport")
         return self.client.call_tool(
-            "viewport",
-            {
-                "sessionId": sessionId,
-            },
+            "viewport", {"sessionId": sessionId}
         ).get("structuredContent", {})
 
+    @_ensure_client
+    def current_url(self, sessionId: str):
+        logger.debug("current_url")
+        return self.client.call_tool(
+            "getCurrentUrl", {"sessionId": sessionId}
+        ).get("structuredContent", {}).get("url")
+
     @_ensure_client
     def set_viewport(
         self,
@@ -615,16 +532,8 @@ 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)
         return self.client.call_tool(
             "viewport",
             {
@@ -637,23 +546,3 @@ class MCPTools:
                 },
             },
         ).get("structuredContent", {})
-    # ======================================================
-    # CURRENT TAB
-    # ======================================================
-
-    @_ensure_client
-    def current_tab(self, sessionId: str) -> Dict[str, Any]:
-        """
-        Get current active browser tab ID.
-
-        Returns:
-            {
-              "tabId": "<targetId>"
-            }
-        """
-        return self.client.call_tool(
-            "currentTab",
-            {
-                "sessionId": sessionId,
-            },
-        ).get("structuredContent", {})