thordata-mcp-server 0.4.4__py3-none-any.whl → 0.5.0__py3-none-any.whl

thordata_mcp/__init__.py

@@ -1,4 +1,4 @@
 """
 Thordata MCP Server package.
 """
-__version__ = "0.4.4"
+__version__ = "0.5.0"

thordata_mcp/browser_session.py

@@ -1,8 +1,7 @@
 """Browser session management for Thordata Scraping Browser.
 
 This module provides a high-level wrapper around Playwright connected to
-Thordata's Scraping Browser (via `AsyncThordataClient.get_browser_connection_url`),
-inspired by Bright Data's browser session design but implemented in Python.
+Thordata's Scraping Browser (via `AsyncThordataClient.get_browser_connection_url`).
 
 Design goals:
 - Domain-scoped browser sessions (one browser/page per domain).
@@ -18,6 +17,8 @@ from urllib.parse import urlparse
 
 from playwright.async_api import Browser, Page, Playwright, async_playwright
 
+import time
+
 from thordata.async_client import AsyncThordataClient
 
 from .aria_snapshot import AriaSnapshotFilter
@@ -37,6 +38,11 @@ class BrowserSession:
         self._requests: Dict[str, Dict[Any, Any]] = {}
         self._dom_refs: Set[str] = set()
         self._current_domain: str = "default"
+        # Console and network diagnostics cache
+        self._console_messages: Dict[str, List[Dict[str, Any]]] = {}
+        self._network_requests: Dict[str, List[Dict[str, Any]]] = {}
+        self._max_console_messages = 10
+        self._max_network_requests = 20
 
     @staticmethod
     def _get_domain(url: str) -> str:
@@ -139,11 +145,26 @@ class BrowserSession:
             
         # Reset network tracking for this domain
         self._requests[domain] = {}
+        self._console_messages[domain] = []
+        self._network_requests[domain] = []
         
         async def on_request(request: Any) -> None:
             if domain in self._requests:
                 self._requests[domain][request] = None
-                
+            try:
+                self._network_requests.setdefault(domain, [])
+                self._network_requests[domain].append(
+                    {
+                        "url": request.url,
+                        "method": request.method,
+                        "resourceType": getattr(request, "resource_type", None),
+                        "timestamp": int(time.time() * 1000),
+                    }
+                )
+                self._network_requests[domain] = self._network_requests[domain][-self._max_network_requests :]
+            except Exception:
+                pass
+
         async def on_response(response: Any) -> None:
             if domain in self._requests:
                 try:
@@ -151,15 +172,78 @@ class BrowserSession:
                 except Exception:
                     # Best-effort, non-fatal
                     pass
+            try:
+                # Update last matching request with status
+                req = response.request
+                url = getattr(req, "url", None)
+                if url and domain in self._network_requests:
+                    for item in reversed(self._network_requests[domain]):
+                        if item.get("url") == url and item.get("statusCode") is None:
+                            item["statusCode"] = response.status
+                            break
+            except Exception:
+                pass
 
         page.on("request", on_request)
         page.on("response", on_response)
-        
+
+        # Console message tracking
+        async def on_console(msg: Any) -> None:
+            try:
+                self._console_messages.setdefault(domain, [])
+                self._console_messages[domain].append(
+                    {
+                        "type": msg.type,
+                        "message": msg.text,
+                        "timestamp": int(time.time() * 1000),
+                    }
+                )
+                self._console_messages[domain] = self._console_messages[domain][-self._max_console_messages :]
+            except Exception:
+                pass
+
+        page.on("console", on_console)
+
         self._pages[domain] = page
         return page
 
-    async def capture_snapshot(self, filtered: bool = True) -> Dict[str, Any]:
-        """Capture an ARIA-like snapshot and optional DOM snapshot."""
+    def get_console_tail(self, n: int = 10, domain: Optional[str] = None) -> List[Dict[str, Any]]:
+        """Return recent console messages for the given domain."""
+        d = domain or self._current_domain
+        items = self._console_messages.get(d, [])
+        return items[-max(0, int(n)) :]
+
+    def get_network_tail(self, n: int = 20, domain: Optional[str] = None) -> List[Dict[str, Any]]:
+        """Return recent network request summaries for the given domain."""
+        d = domain or self._current_domain
+        items = self._network_requests.get(d, [])
+        return items[-max(0, int(n)) :]
+
+    def reset_page(self, domain: Optional[str] = None) -> None:
+        """Drop cached page for a domain so the next call recreates it."""
+        d = domain or self._current_domain
+        self._pages.pop(d, None)
+        self._requests.pop(d, None)
+        self._console_messages.pop(d, None)
+        self._network_requests.pop(d, None)
+
+
+    async def capture_snapshot(
+        self,
+        *,
+        filtered: bool = True,
+        mode: str = "compact",
+        max_items: int = 80,
+        include_dom: bool = False,
+    ) -> Dict[str, Any]:
+        """Capture an ARIA-like snapshot and optional DOM snapshot.
+
+        Args:
+            filtered: Whether to apply AriaSnapshotFilter (legacy, kept for compatibility).
+            mode: "compact" | "full". Compact returns minimal interactive elements.
+            max_items: Maximum number of interactive elements to include (compact mode only).
+            include_dom: Whether to include dom_snapshot (compact mode defaults to False).
+        """
         page = await self.get_page()
         
         try:
@@ -175,16 +259,64 @@ class BrowserSession:
                 "aria_snapshot": full_snapshot,
             }
         
+        if mode == "compact":
+            # Compact: return only filtered interactive elements, optionally without dom_snapshot
+            filtered_snapshot = AriaSnapshotFilter.filter_snapshot(full_snapshot)
+            filtered_snapshot = self._limit_aria_snapshot_items(filtered_snapshot, max_items=max_items)
+            dom_snapshot = None
+            if include_dom:
+                dom_snapshot_raw = await self._capture_dom_snapshot(page)
+                self._dom_refs = {el["ref"] for el in dom_snapshot_raw}
+                dom_snapshot = AriaSnapshotFilter.format_dom_elements(dom_snapshot_raw)
+            return {
+                "url": page.url,
+                "title": await page.title(),
+                "aria_snapshot": filtered_snapshot,
+                "dom_snapshot": dom_snapshot,
+                "_meta": {"mode": mode, "max_items": max_items, "include_dom": include_dom},
+            }
+
+        # Full mode: include both filtered aria and dom_snapshot (legacy behavior)
         filtered_snapshot = AriaSnapshotFilter.filter_snapshot(full_snapshot)
-        dom_snapshot = await self._capture_dom_snapshot(page)
-        self._dom_refs = {el["ref"] for el in dom_snapshot}
-        
+        dom_snapshot_raw = await self._capture_dom_snapshot(page)
+        self._dom_refs = {el["ref"] for el in dom_snapshot_raw}
         return {
             "url": page.url,
             "title": await page.title(),
             "aria_snapshot": filtered_snapshot,
-            "dom_snapshot": AriaSnapshotFilter.format_dom_elements(dom_snapshot),
+            "dom_snapshot": AriaSnapshotFilter.format_dom_elements(dom_snapshot_raw),
+            "_meta": {"mode": mode},
         }
+
+    @staticmethod
+    def _limit_aria_snapshot_items(text: str, *, max_items: int) -> str:
+        """Limit snapshot to the first N interactive element blocks.
+
+        The snapshot format is a list where each element starts with a line beginning
+        with '- ' (Playwright raw) or '[' (AriaSnapshotFilter compact), and may include
+        one or more indented continuation lines.
+        """
+        try:
+            n = int(max_items)
+        except Exception:
+            n = 80
+        if n <= 0:
+            return ""
+        if not text:
+            return text
+
+        lines = text.splitlines()
+        out: list[str] = []
+        items = 0
+        for line in lines:
+            if line.startswith("- ") or line.startswith("["):
+                if items >= n:
+                    break
+                items += 1
+            # Include continuation lines only if we've started collecting items.
+            if items > 0:
+                out.append(line)
+        return "\n".join(out).strip()
             
     async def _get_interactive_snapshot(self, page: Page) -> str:
         """Generate a text snapshot of interactive elements with refs."""
@@ -194,12 +326,25 @@ class BrowserSession:
                 const lines = [];
                 let refCounter = 0;
 
+                function normalizeRole(tag, explicitRole) {
+                    const role = (explicitRole || '').toLowerCase();
+                    const t = (tag || '').toLowerCase();
+                    if (role) return role;
+                    // Map common interactive tags to standard ARIA roles
+                    if (t === 'a') return 'link';
+                    if (t === 'button') return 'button';
+                    if (t === 'input') return 'textbox';
+                    if (t === 'select') return 'combobox';
+                    if (t === 'textarea') return 'textbox';
+                    return t;
+                }
+
                 function traverse(node) {
                     if (node.nodeType === Node.ELEMENT_NODE) {
-                        const role = node.getAttribute('role') || node.tagName.toLowerCase();
                         const tag = node.tagName.toLowerCase();
                         const interactiveTag = ['a', 'button', 'input', 'select', 'textarea'].includes(tag);
-                        const interactiveRole = ['button', 'link', 'textbox', 'checkbox'].includes(role);
+                        const role = normalizeRole(tag, node.getAttribute('role'));
+                        const interactiveRole = ['button', 'link', 'textbox', 'searchbox', 'combobox', 'checkbox', 'radio', 'switch', 'tab', 'menuitem', 'option'].includes(role);
 
                         if (interactiveTag || interactiveRole) {
                             if (!node.dataset.fastmcpRef) {

thordata_mcp/config.py

@@ -6,6 +6,14 @@ from pydantic_settings import BaseSettings
 class Settings(BaseSettings):
     """Environment-driven configuration for the MCP server."""
 
+    # MCP tool exposure mode (BrightData-like)
+    # - rapid: minimal core tools
+    # - pro: all tools
+    # - custom: enable by THORDATA_GROUPS and THORDATA_TOOLS
+    THORDATA_MODE: str = "rapid"
+    THORDATA_GROUPS: str | None = None
+    THORDATA_TOOLS: str | None = None
+
     # Thordata credentials
     THORDATA_SCRAPER_TOKEN: str | None = None
     THORDATA_PUBLIC_TOKEN: str | None = None
@@ -20,9 +28,9 @@ class Settings(BaseSettings):
     # Tasks discovery UX (to avoid dumping hundreds of tools to the client by default)
     # - mode=curated: only return tools from THORDATA_TASKS_GROUPS, with pagination
     # - mode=all: return all discovered tools
-    # Default to listing ALL Web Scraper tasks, but paginated (no env changes required for “100+ tools” use-case).
-    THORDATA_TASKS_LIST_MODE: str = "all"
-    THORDATA_TASKS_LIST_DEFAULT_LIMIT: int = 100
+    # Default to curated mode to reduce tool selection noise for LLMs.
+    THORDATA_TASKS_LIST_MODE: str = "curated"
+    THORDATA_TASKS_LIST_DEFAULT_LIMIT: int = 60
     THORDATA_TASKS_GROUPS: str = "ecommerce,social,video,search,travel,code,professional"
 
     # Optional: restrict which SDK tool_keys are allowed to execute (safety/UX)
@@ -49,6 +57,9 @@ class Settings(BaseSettings):
     # Logging
     LOG_LEVEL: str = "INFO"
     
+    # Debug tools exposure
+    THORDATA_DEBUG_TOOLS: bool = False
+    
     class Config:
         env_file = ".env"
         extra = "ignore"

thordata_mcp/context.py

@@ -35,4 +35,4 @@ class ServerContext:
             
         if cls._client:
             await cls._client.close()
-            cls._client = None
+            cls._client = None

thordata_mcp/tools/data/browser.py

@@ -298,16 +298,96 @@ def register(mcp: FastMCP) -> None:
 
     @mcp.tool(name="browser.click_ref", description="Click an element by its ref ID")
     @handle_mcp_errors
-    async def browser_click_ref(ref: str, element: str = "element") -> dict[str, Any]:
-        """Click an element using the [ref=X] ID from the snapshot."""
+    async def browser_click_ref(
+        ref: str,
+        element: str = "element",
+        wait_for_navigation_ms: Optional[int] = None,
+    ) -> dict[str, Any]:
+        """Click an element using the [ref=X] ID from the snapshot.
+        
+        Args:
+            ref: The ref ID from snapshot (e.g., ref-w545663wqs)
+            element: Description of the element for error messages
+            wait_for_navigation_ms: Optional wait time in ms to detect navigation after click
+        """
         session = await ServerContext.get_browser_session()
-        locator = await session.ref_locator(ref, element)
-        await locator.click(timeout=5_000)
-        return ok_response(
-            tool="browser.click_ref",
-            input={"ref": ref, "element": element},
-            output={"message": f"Successfully clicked {element}", "ref": ref},
-        )
+        page = await session.get_page()
+        
+        url_before = page.url
+        try:
+            locator = await session.ref_locator(ref, element)
+            await locator.click(timeout=5_000)
+            
+            # Check for navigation if requested
+            did_navigate = False
+            url_after = url_before
+            if wait_for_navigation_ms and wait_for_navigation_ms > 0:
+                import asyncio
+                await asyncio.sleep(wait_for_navigation_ms / 1000)
+                url_after = page.url
+                did_navigate = url_after != url_before
+            
+            return ok_response(
+                tool="browser.click_ref",
+                input={"ref": ref, "element": element, "wait_for_navigation_ms": wait_for_navigation_ms},
+                output={
+                    "message": f"Successfully clicked {element}",
+                    "ref": ref,
+                    "url_before": url_before,
+                    "url_after": url_after,
+                    "did_navigate": did_navigate,
+                },
+            )
+        except Exception as e:
+            # Enhanced error with diagnostics + self-heal for common browser lifecycle issues
+            from ...utils import error_response
+
+            err_s = str(e).lower()
+            did_reset = False
+            if any(k in err_s for k in [
+                "target closed",
+                "page closed",
+                "browser has been closed",
+                "execution context was destroyed",
+                "has been disposed",
+            ]):
+                try:
+                    session.reset_page()
+                    did_reset = True
+                except Exception:
+                    did_reset = False
+
+            # Try to get console and network diagnostics from session cache
+            try:
+                console_tail = session.get_console_tail(n=10)
+            except Exception:
+                console_tail = []
+            try:
+                network_tail = session.get_network_tail(n=20)
+            except Exception:
+                network_tail = []
+
+            hint = "Try taking a new snapshot to get fresh refs, or check if the element is still visible"
+            if did_reset:
+                hint = "Browser page was closed/reset. Take a new snapshot to get fresh refs, then retry the click."
+
+            return error_response(
+                tool="browser.click_ref",
+                input={"ref": ref, "element": element, "wait_for_navigation_ms": wait_for_navigation_ms},
+                error_type="browser_interaction_error",
+                code="E5001",
+                message=f"Failed to click element: {str(e)}",
+                details={
+                    "ref": ref,
+                    "element": element,
+                    "url_before": url_before,
+                    "url_after": page.url,
+                    "did_reset": did_reset,
+                    "hint": hint,
+                    "console_tail": console_tail,
+                    "network_tail": network_tail,
+                },
+            )
 
     @mcp.tool(
         name="browser.type_ref",
@@ -322,15 +402,41 @@ def register(mcp: FastMCP) -> None:
     ) -> dict[str, Any]:
         """Type text into an element using the [ref=X] ID."""
         session = await ServerContext.get_browser_session()
-        locator = await session.ref_locator(ref, element)
-        await locator.fill(text)
-        if submit:
-            await locator.press("Enter")
-        return ok_response(
-            tool="browser.type_ref",
-            input={"ref": ref, "text": text, "submit": submit, "element": element},
-            output={"message": "Typed into element", "ref": ref},
-        )
+        page = await session.get_page()
+        url_before = page.url
+        
+        try:
+            locator = await session.ref_locator(ref, element)
+            await locator.fill(text)
+            if submit:
+                await locator.press("Enter")
+            
+            return ok_response(
+                tool="browser.type_ref",
+                input={"ref": ref, "text": text, "submit": submit, "element": element},
+                output={
+                    "message": "Typed into element" + (" and submitted" if submit else ""),
+                    "ref": ref,
+                    "url_before": url_before,
+                    "url_after": page.url,
+                },
+            )
+        except Exception as e:
+            from ...utils import error_response
+            return error_response(
+                tool="browser.type_ref",
+                input={"ref": ref, "text": text, "submit": submit, "element": element},
+                error_type="browser_interaction_error",
+                code="E5002",
+                message=f"Failed to type into element: {str(e)}",
+                details={
+                    "ref": ref,
+                    "element": element,
+                    "url_before": url_before,
+                    "url_after": page.url,
+                    "hint": "Try taking a new snapshot to get fresh refs, or check if the element is still visible and editable",
+                },
+            )
 
     @mcp.tool(name="browser.screenshot_page", description="Take a screenshot of the current browser page")
     @handle_mcp_errors

thordata_mcp/tools/debug.py

@@ -0,0 +1,125 @@
+from __future__ import annotations
+
+import asyncio
+from typing import Any, Optional
+
+from mcp.server.fastmcp import FastMCP
+
+from thordata_mcp.config import settings
+from thordata_mcp.context import ServerContext
+from thordata_mcp.utils import ok_response
+from thordata_mcp.tools.params_utils import normalize_params
+
+
+def register(mcp: FastMCP) -> None:
+    @mcp.tool(name="debug.status", description="Return server status and effective configuration (no secrets).")
+    async def debug_status() -> dict[str, Any]:
+        def _mask(v: str | None) -> dict[str, Any]:
+            if not v:
+                return {"set": False}
+            return {
+                "set": True,
+                "length": len(v),
+                "tail4": v[-4:] if len(v) >= 4 else v,
+            }
+
+        return ok_response(
+            tool="debug.status",
+            input={},
+            output={
+                "python": __import__("sys").version,
+                "settings": {
+                    "THORDATA_SCRAPER_TOKEN": _mask(settings.THORDATA_SCRAPER_TOKEN),
+                    "THORDATA_PUBLIC_TOKEN": _mask(settings.THORDATA_PUBLIC_TOKEN),
+                    "THORDATA_PUBLIC_KEY": _mask(settings.THORDATA_PUBLIC_KEY),
+                    "THORDATA_BROWSER_USERNAME": _mask(settings.THORDATA_BROWSER_USERNAME),
+                    "THORDATA_BROWSER_PASSWORD": _mask(settings.THORDATA_BROWSER_PASSWORD),
+                    "THORDATA_TASKS_LIST_MODE": settings.THORDATA_TASKS_LIST_MODE,
+                    "THORDATA_TASKS_LIST_DEFAULT_LIMIT": settings.THORDATA_TASKS_LIST_DEFAULT_LIMIT,
+                },
+            },
+        )
+
+    @mcp.tool(name="browser.diagnostics", description="Return recent browser console/network diagnostics for the current session.")
+    async def browser_diagnostics(
+        console_limit: int = 10,
+        network_limit: int = 20,
+    ) -> dict[str, Any]:
+        session = await ServerContext.get_browser_session()
+        page = await session.get_page()
+        
+        return ok_response(
+            tool="browser.diagnostics",
+            input={"console_limit": console_limit, "network_limit": network_limit},
+            output={
+                "url": page.url,
+                "title": await page.title(),
+                "console_tail": session.get_console_tail(n=console_limit),
+                "network_tail": session.get_network_tail(n=network_limit),
+            },
+        )
+
+    @mcp.tool(
+        name="debug.self_test",
+        description=(
+            "Run a small, non-destructive smoke test suite for core scraping capabilities and return a compact report. "
+            "Useful after restarting the MCP server. Params: {\"timeout_s\": 30}."
+        ),
+    )
+    async def debug_self_test(*, params: Any = None) -> dict[str, Any]:
+        try:
+            p = normalize_params(params, "debug.self_test", "run")
+        except Exception:
+            p = {}
+
+        timeout_s = int(p.get("timeout_s", 30))
+        timeout_s = max(5, min(timeout_s, 120))
+
+        async def _run(name: str, fn) -> dict[str, Any]:
+            try:
+                out = await asyncio.wait_for(fn(), timeout=timeout_s)
+                return {"check": name, "ok": True, "detail": out}
+            except Exception as e:
+                return {"check": name, "ok": False, "error": str(e)}
+
+        client = await ServerContext.get_client()
+
+        async def _check_serp() -> dict[str, Any]:
+            from thordata.types import SerpRequest
+
+            req = SerpRequest(query="thordata", engine="google", num=3, output_format="light_json")
+            data = await client.serp_search_advanced(req)
+            organic = data.get("organic") if isinstance(data, dict) else None
+            return {"has_organic": isinstance(organic, list) and len(organic) > 0, "organic_count": len(organic) if isinstance(organic, list) else None}
+
+        async def _check_unlocker() -> dict[str, Any]:
+            html = await client.universal_scrape(url="https://example.com", js_render=True, output_format="html")
+            s = html if isinstance(html, str) else str(html)
+            return {"html_len": len(s), "contains_example_domain": "Example Domain" in s}
+
+        async def _check_browser_snapshot() -> dict[str, Any]:
+            session = await ServerContext.get_browser_session()
+            snap = await session.capture_snapshot(url="https://example.com", filtered=True, max_items=20)
+            aria = snap.get("aria_snapshot") if isinstance(snap, dict) else None
+            return {"aria_non_empty": bool(aria), "aria_len": len(aria) if isinstance(aria, str) else None, "url": snap.get("url") if isinstance(snap, dict) else None}
+
+        results = await asyncio.gather(
+            _run("serp.search", _check_serp),
+            _run("unlocker.fetch(html,js_render=true)", _check_unlocker),
+            _run("browser.snapshot(filtered,max_items=20)", _check_browser_snapshot),
+        )
+
+        summary = []
+        ok_all = True
+        for r in results:
+            if r.get("ok"):
+                summary.append({"check": r.get("check"), "ok": True})
+            else:
+                ok_all = False
+                summary.append({"check": r.get("check"), "ok": False, "error": r.get("error")})
+
+        return ok_response(
+            tool="debug.self_test",
+            input={"params": {"timeout_s": timeout_s}},
+            output={"ok_all": ok_all, "summary": summary, "_meta": {"timeout_s": timeout_s}},
+        )

thordata_mcp/tools/params_utils.py

@@ -0,0 +1,107 @@
+"""Common parameter normalization utilities for thordata MCP tools."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, Optional
+
+from thordata_mcp.utils import error_response
+
+
+def normalize_params(params: Any, tool_name: str, action: Optional[str] = None) -> Dict[str, Any]:
+    """
+    Normalize params to dictionary with clear error messages.
+    
+    This function handles the common case where Cursor might pass params as a string
+    instead of a dictionary object, and provides helpful error messages.
+    
+    Args:
+        params: The params value passed to the tool
+        tool_name: Name of the tool for error reporting
+        action: Optional action name for error reporting
+        
+    Returns:
+        Normalized params dictionary
+        
+    Raises:
+        ValueError: If params cannot be normalized to a dictionary
+    """
+    if params is None:
+        return {}
+    
+    if isinstance(params, dict):
+        return params
+    
+    if isinstance(params, str):
+        try:
+            parsed = json.loads(params)
+            if not isinstance(parsed, dict):
+                raise ValueError("Parsed JSON is not a dictionary")
+            return parsed
+        except json.JSONDecodeError as e:
+            error_msg = (
+                f"Invalid JSON in params: {e}. "
+                f"Params should be a dictionary object, not a string. "
+                f"Example: params={{'url': 'https://example.com'}}. "
+                f"Received: {params[:100]}{'...' if len(params) > 100 else ''}"
+            )
+            raise ValueError(error_msg)
+    
+    # Handle other types (list, number, etc.)
+    error_msg = (
+        f"params must be a dictionary object, not {type(params).__name__}. "
+        f"Example: params={{'url': 'https://example.com'}}. "
+        f"Received: {str(params)[:100]}{'...' if len(str(params)) > 100 else ''}"
+    )
+    raise ValueError(error_msg)
+
+
+def create_params_error(tool_name: str, action: str, params: Any, error_message: str) -> Dict[str, Any]:
+    """
+    Create a standardized error response for parameter validation errors.
+    
+    Args:
+        tool_name: Name of the tool
+        action: Action being performed
+        params: The invalid params value
+        error_message: Detailed error message
+        
+    Returns:
+        Error response dictionary
+    """
+    return error_response(
+        tool=tool_name,
+        input={"action": action, "params": params},
+        error_type="validation_error",
+        code="E4001",
+        message=error_message,
+    )
+
+
+def create_json_error(tool_name: str, action: str, params: str, error_detail: str) -> Dict[str, Any]:
+    """
+    Create a standardized error response for JSON parsing errors.
+    
+    Args:
+        tool_name: Name of the tool
+        action: Action being performed
+        params: The invalid JSON string
+        error_detail: JSON parsing error detail
+        
+    Returns:
+        Error response dictionary
+    """
+    error_message = (
+        f"Invalid JSON in params: {error_detail}. "
+        f"Use dictionary format: params={{'url': 'https://example.com'}} "
+        f"or valid JSON string: params='{{\"url\":\"https://example.com\"}}'. "
+        f"Received: {params[:100]}{'...' if len(params) > 100 else ''}"
+    )
+    
+    return error_response(
+        tool=tool_name,
+        input={"action": action, "params": params},
+        error_type="json_error",
+        code="E4002",
+        message=error_message,
+    )