🕷️ The BEST Web Scraping framework that handles everything from a single request to a full-scale crawl! Don't be shy, join here: https://discord.gg/EMgGbDceNQ and follow here for daily tips and tricks: https://x.com/Scrapling_dev
Python aiai-scrapingautomationcrawlercrawlingcrawling-pythondatadata-extractionmcpmcp-serverplaywrightpythonscrapingselectorsstealthweb-scraperweb-scrapingweb-scraping-pythonwebscrapingxpath
feat(mcp): Add snapshot searching
Karim shoair5c39feb851d8
diff --git a/agent-skill/Scrapling-Skill.zip b/agent-skill/Scrapling-Skill.zipindex 7d7b955..1dc147d 100644Binary files a/agent-skill/Scrapling-Skill.zip and b/agent-skill/Scrapling-Skill.zip differdiff --git a/agent-skill/Scrapling-Skill/references/mcp-server.md b/agent-skill/Scrapling-Skill/references/mcp-server.mdindex 9714b79..006cd61 100644--- a/agent-skill/Scrapling-Skill/references/mcp-server.md+++ b/agent-skill/Scrapling-Skill/references/mcp-server.md@@ -141,6 +141,14 @@ With `extraction_type="snapshot"`, the response keeps `status` and `url` and retReturns a plain-text AI ARIA snapshot of the current whole page, including element roles, names, and references. Takes `session_id` from `browser_open` and optional `depth` to limit the tree. Element positions and sizes in viewport CSS pixels are included by default; set `boxes=false` to omit them. Use it after `browser_fetch` finishes. Raises for an unknown or HTTP session, or a missing, closed, or busy page.+Set `search` to nonempty text for a case-insensitive literal search. Set `regex=true` to treat it as a Python regular expression instead; regex matching is case-sensitive unless you use an inline flag such as `(?i)`. Regex mode requires `search`, and invalid patterns fail before capture. Omit `search` for the unchanged full snapshot.++Search applies to each line of the captured snapshot, after the `depth` limit. Results include all matching lines, three lines before and after each match, and parent nodes. Overlapping context appears once; `...` marks omitted lines. Refs and boxes are preserved. If no lines match, the result is an empty string. Search does not navigate or reload the page.++```json+{"session_id": "browser", "search": "Next"}+```+### `browser_actions` -- Chain mouse, field, keyboard, and wait actionsRuns actions in order on the existing page in a stealthy browser session. Call `browser_fetch` first. The flat `actions` list can mix any of the eleven action types below; use `browser_snapshot` when you need to inspect the page before choosing later actions.diff --git a/docs/ai/mcp-server.md b/docs/ai/mcp-server.mdindex 560d60c..dad8078 100644--- a/docs/ai/mcp-server.md+++ b/docs/ai/mcp-server.md@@ -34,7 +34,7 @@ The Scrapling MCP Server provides fourteen tools for web scraping and browser in#### AI Snapshots-- **`browser_snapshot`**: Give the AI a structured text view of the current page without reloading it. Includes element roles, names, references, positions, and sizes to help the AI understand the page and target clicks.+- **`browser_snapshot`**: Give the AI a structured text view of the current page without reloading it. Includes element roles, names, references, positions, and sizes to help the AI understand the page and target clicks. Search for text to return matching lines with nearby context and parent nodes, making large pages easier to inspect.#### Browser Actionsdiff --git a/docs/api-reference/mcp-server.md b/docs/api-reference/mcp-server.mdindex 7d09377..b1e3e17 100644--- a/docs/api-reference/mcp-server.md+++ b/docs/api-reference/mcp-server.md@@ -77,7 +77,7 @@ The main MCP server class that provides all web scraping tools:- **`make_request`**: Fetch one URL through HTTP with browser impersonation and automatic client cleanup. Supports GET, POST, PUT, and DELETE.- **`browser_fetch_once`**: Fetch one URL through a stealthy browser with JavaScript rendering and Cloudflare handling, then close the browser. Use a persistent session for later actions or network history.-- **`browser_snapshot`**: Inspect the current page without reloading it. Structured text includes element roles, names, references, positions, and sizes to help the AI target page controls.+- **`browser_snapshot`**: Inspect the current page without reloading it. Structured text includes element roles, names, references, positions, and sizes to help the AI target page controls. Search for text to return matching lines with nearby context and parent nodes, making large pages easier to inspect.- **`browser_actions`**: Chain mouse moves, hovers, clicks, scrolling, field filling, keyboard shortcuts, and waits in one call. Fill a search box, submit it, wait for results, and open a result without a separate call for each step.Moves and clicks target selectors, snapshot references, or coordinates; element targets wait and scroll into view. Supports movement in multiple steps, left, right, and middle clicks, double-clicks, and scrolling nested panels.diff --git a/scrapling/core/ai/_snapshot_search.py b/scrapling/core/ai/_snapshot_search.pynew file mode 100644index 0000000..6d575af--- /dev/null+++ b/scrapling/core/ai/_snapshot_search.py@@ -0,0 +1,30 @@+from scrapling.core._types import List, Pattern, Tuple+++def _search_snapshot(snapshot: str, pattern: Pattern[str]) -> str:+ """Keep matching lines, nearby context and ancestor paths without changing refs."""+ lines = snapshot.split("\n") if snapshot else []+ matches = [index for index, line in enumerate(lines) if pattern.search(line)]+ if not matches:+ return ""+ retained = {nearby for index in matches for nearby in range(max(0, index - 3), min(len(lines), index + 4))}+ ancestors: List[Tuple[int, int]] = []+ for index, line in enumerate(lines):+ if not line.strip():+ continue+ indent = len(line) - len(line.lstrip())+ while ancestors and ancestors[-1][0] >= indent:+ ancestors.pop()+ if index in retained:+ retained.update(parent for _, parent in ancestors)+ ancestors.append((indent, index))+ output: List[str] = []+ previous = -1+ for index in sorted(retained):+ if index > previous + 1:+ output.append("...")+ output.append(lines[index])+ previous = index+ if previous < len(lines) - 1:+ output.append("...")+ return "\n".join(output)diff --git a/scrapling/core/ai/server.py b/scrapling/core/ai/server.pyindex df959d2..83de07e 100644--- a/scrapling/core/ai/server.py+++ b/scrapling/core/ai/server.py@@ -1,3 +1,4 @@+import refrom uuid import uuid4from os import environfrom json import dumps@@ -33,6 +34,7 @@ from ._browser_actions import (_validate_actions,)from ._network_formatting import NetworkPart, NetworkRequestInfo, NetworkRequestModel, _request_details+from ._snapshot_search import _search_snapshotfrom scrapling.core.shell import Convertor, _CONTROL_CHARS_PATTERNfrom scrapling.engines.toolbelt.custom import Response as _ScraplingResponsefrom scrapling.fetchers import FetcherSession, AsyncStealthySession@@ -429,14 +431,28 @@ class ScraplingMCPServer:session_id: str,depth: Optional[int] = None,boxes: bool = True,+ search: Optional[NonEmptyString] = None,+ regex: bool = False,) -> str:- """Return the current page's AI ARIA snapshot with element references as plain text, without navigating.+ """Return the current page's AI ARIA snapshot or search results as plain text, without navigating.+ Search keeps element refs, ancestor paths, and three lines of context around each matching line.:param session_id: ID from `browser_open`; call `browser_fetch` first.- :param depth: Maximum snapshot depth; unlimited if omitted.+ :param depth: Maximum snapshot depth before search; unlimited if omitted.:param boxes: Include element bounding boxes in viewport CSS pixels.+ :param search: Case-insensitive literal text; omitted returns the full snapshot.+ :param regex: Treat search as a Python regex; case-sensitive unless (?i) is used."""- return await self._browser_snapshot(session_id, depth=depth, boxes=boxes)+ if regex and search is None:+ raise ValueError("regex requires search.")+ pattern = None+ if search is not None:+ try:+ pattern = re.compile(search if regex else re.escape(search), 0 if regex else re.IGNORECASE)+ except re.error as error:+ raise ValueError(f"Invalid search regex: {error}") from error+ snapshot = await self._browser_snapshot(session_id, depth=depth, boxes=boxes)+ return _search_snapshot(snapshot, pattern) if pattern is not None else snapshotasync def _browser_snapshot(self,diff --git a/tests/ai/test_browser_snapshot.py b/tests/ai/test_browser_snapshot.pyindex cc3623e..92d82a0 100644--- a/tests/ai/test_browser_snapshot.py+++ b/tests/ai/test_browser_snapshot.py@@ -1,4 +1,5 @@import asyncio+import refrom os import getenvfrom re import searchfrom unittest.mock import AsyncMock, Mock@@ -6,12 +7,14 @@ from unittest.mock import AsyncMock, Mockimport pytestfrom mcp.client import Clientfrom mcp.types import TextContent-from patchright.async_api import TimeoutError as PatchrightTimeoutError+from patchright.async_api import Page, TimeoutError as PatchrightTimeoutErrorfrom scrapling.core.ai import ScraplingMCPServer, SessionTypefrom scrapling.core.ai.server import _SessionEntry-from scrapling.core._types import Any+from scrapling.core.ai._snapshot_search import _search_snapshot+from scrapling.core._types import Any, castfrom scrapling.engines._browsers._base import AsyncSession+from scrapling.engines._browsers._stealth import AsyncStealthySessionfrom scrapling.engines.toolbelt.custom import Response@@ -45,8 +48,11 @@ async def test_browser_snapshot_returns_plain_mcp_text(boxes: bool | None) -> Noassert "session_snapshot" not in toolstool = tools["browser_snapshot"]assert tool.output_schema is None- assert set(tool.input_schema["properties"]) == {"session_id", "depth", "boxes"}+ assert set(tool.input_schema["properties"]) == {"session_id", "depth", "boxes", "search", "regex"}assert tool.input_schema["properties"]["boxes"]["default"] is True+ assert tool.input_schema["properties"]["regex"]["default"] is False+ assert tool.input_schema["properties"]["search"]["default"] is None+ assert {"type": "string", "minLength": 1} in tool.input_schema["properties"]["search"]["anyOf"]assert tool.input_schema["required"] == ["session_id"]fetch_props = tools["browser_fetch"].input_schema["properties"]assert set(fetch_props["extraction_type"]["enum"]) == {"markdown", "html", "text", "snapshot"}@@ -307,3 +313,226 @@ async def test_browser_fetch_snapshot_error_does_not_refetch() -> None:page.aria_snapshot.assert_not_awaited()assert session.page_pool.pages[0].state == "ready"page.close.assert_not_called()+++ "snapshot, expression, expected",+ [+ ("", ".*", ""),+ (SNAPSHOT, "missing", ""),+ (SNAPSHOT, "save", ""),+ (SNAPSHOT, "(?i)save", SNAPSHOT),+ ("- text: Save Save", "Save", "- text: Save Save"),+ ("- text: A\n- text: B", ".*", "- text: A\n- text: B"),+ ("- text: Straße\n- text: Αθήνα", "(?i)αθήνα", "- text: Straße\n- text: Αθήνα"),+ ("- text: First\n- text: Second", "First.*Second", ""),+ ("- text: First\n- text: Second", "(?m)^- text: Second$", "- text: First\n- text: Second"),+ ("- text: A\u2028B", "B", "- text: A\u2028B"),+ ],+)+def test_snapshot_search_matches_lines(snapshot: str, expression: str, expected: str) -> None:+ assert _search_snapshot(snapshot, re.compile(expression)) == expected+++ "expression, expected",+ [+ ("line 0$", "- text: line 0\n- text: line 1\n- text: line 2\n- text: line 3\n..."),+ ("line 10$", "...\n- text: line 7\n- text: line 8\n- text: line 9\n- text: line 10"),+ (+ "line [45]$",+ "...\n- text: line 1\n- text: line 2\n- text: line 3\n- text: line 4\n- text: line 5\n- text: line 6\n- text: line 7\n- text: line 8\n...",+ ),+ (+ "line (0|10)$",+ "- text: line 0\n- text: line 1\n- text: line 2\n- text: line 3\n...\n- text: line 7\n- text: line 8\n- text: line 9\n- text: line 10",+ ),+ (+ "line (3|7)$",+ "\n".join(f"- text: line {index}" for index in range(11)),+ ),+ ],+)+def test_snapshot_search_keeps_neighbors_and_merges_overlap(expression: str, expected: str) -> None:+ snapshot = "\n".join(f"- text: line {index}" for index in range(11))+ assert _search_snapshot(snapshot, re.compile(expression)) == expected+++def test_snapshot_search_preserves_ancestors_for_matches_and_neighbors() -> None:+ snapshot = """- main [ref=e1]:+ - region "Before" [ref=e2]:+ - heading "Unrelated"+ - text: old 1+ - text: old 2+ - link "Previous" [ref=e6]:+ - /url: /previous+ - region "Matched" [ref=e8]:+ - list [ref=e9]:+ - listitem "Needle" [ref=e10] [box=10,20,30,40]+ - listitem "Next" [ref=e11]+ - region "After" [ref=e12]:+ - text: context+ - text: omitted 1+ - text: omitted 2"""+ expected = """- main [ref=e1]:+ - region "Before" [ref=e2]:+...+ - link "Previous" [ref=e6]:+ - /url: /previous+ - region "Matched" [ref=e8]:+ - list [ref=e9]:+ - listitem "Needle" [ref=e10] [box=10,20,30,40]+ - listitem "Next" [ref=e11]+ - region "After" [ref=e12]:+ - text: context+..."""+ assert _search_snapshot(snapshot, re.compile("Needle")) == expected+++def test_snapshot_search_keeps_all_matches_without_a_result_limit() -> None:+ snapshot = "\n".join(f'- link "Result {index}" [ref=e{index}]' for index in range(150))+ assert _search_snapshot(snapshot, re.compile("Result")) == snapshot+++ "snapshot, query, regex, expected",+ [+ (SNAPSHOT, "save", False, SNAPSHOT),+ (SNAPSHOT, "save", True, ""),+ (SNAPSHOT, "(?i)save", True, SNAPSHOT),+ (SNAPSHOT, '^.*button "S.ve"', True, SNAPSHOT),+ (SNAPSHOT, "/Save/", True, ""),+ (+ "- text: Price [USD]\n- text: Price USD",+ "[USD]",+ False,+ "- text: Price [USD]\n- text: Price USD",+ ),+ ("- text: C++", "C++", False, "- text: C++"),+ ("- text: Αθήνα", "ΑΘΉΝΑ", False, "- text: Αθήνα"),+ (SNAPSHOT, None, False, SNAPSHOT),+ ('- main:\n - button "Save"\n', None, False, '- main:\n - button "Save"\n'),+ ],+)+async def test_browser_snapshot_search_mcp(snapshot: str, query: str | None, regex: bool, expected: str) -> None:+ server, session, page = _server()+ page.aria_snapshot.return_value = snapshot+ async with Client(server._build_server("127.0.0.1", 8000)) as client:+ result = await client.call_tool(+ "browser_snapshot",+ {"session_id": "browser", "search": query, "regex": regex, "depth": 2, "boxes": False},+ )+ assert not result.is_error+ assert result.structured_content is None+ assert result.content == [TextContent(type="text", text=expected)]+ page.aria_snapshot.assert_awaited_once_with(mode="ai", depth=2, boxes=False)+ assert session.page_pool.pages[0].state == "ready"+ page.goto.assert_not_called()+++ "args", [{"regex": True}, {"regex": True, "search": None}, {"regex": True, "search": "["}, {"search": ""}]+)+async def test_browser_snapshot_search_rejects_invalid_input_before_page_capture(+ args: dict[str, Any], monkeypatch: pytest.MonkeyPatch+) -> None:+ server, session, page = _server()+ reserve = Mock(wraps=session.page_pool.get_ready_page)+ monkeypatch.setattr(type(session.page_pool), "get_ready_page", reserve)+ async with Client(server._build_server("127.0.0.1", 8000)) as client:+ result = await client.call_tool("browser_snapshot", {"session_id": "browser", **args})+ assert result.is_error+ assert result.content and isinstance(result.content[0], TextContent)+ assert "search" in result.content[0].text.lower() or "regular expression" in result.content[0].text.lower()+ reserve.assert_not_called()+ page.aria_snapshot.assert_not_awaited()+ assert session.page_pool.pages[0].state == "ready"++[email protected]("kwargs", [{"regex": True}, {"search": "[", "regex": True}])+async def test_browser_snapshot_search_errors_are_value_errors(kwargs: dict[str, Any]) -> None:+ server, session, page = _server()+ with pytest.raises(ValueError):+ await server.browser_snapshot("browser", **kwargs)+ page.aria_snapshot.assert_not_awaited()+ assert session.page_pool.pages[0].state == "ready"+++async def test_browser_snapshot_search_live_refs_and_state() -> None:+ server = ScraplingMCPServer(executable_path=getenv("SCRAPLING_EXECUTABLE_PATH"))+ requests: list[str] = []+ html = (+ '<main aria-label="Results"><section aria-label="Catalog">'+ + "".join(f"<p>Before result {index}</p>" for index in range(12))+ + "<button onclick=\"document.querySelector('output').textContent='Saved'\">Save result</button>"+ + "".join(f"<p>After result {index}</p>" for index in range(12))+ + "</section><output>Waiting</output></main>"+ )++ async def serve(route: Any) -> None:+ if route.request.is_navigation_request():+ requests.append(route.request.url)+ await route.fulfill(content_type="text/html", body=html)++ async with Client(server._build_server("127.0.0.1", 8000)) as client:+ opened = await client.call_tool("browser_open", {"session_id": "browser"})+ assert not opened.is_error+ try:+ session = cast(AsyncStealthySession, server._sessions["browser"].session)+ await session.context.route("**/*", serve)+ fetched = await client.call_tool(+ "browser_fetch",+ {+ "session_id": "browser",+ "url": "https://snapshot-search.test/",+ "google_search": False,+ "extraction_type": "snapshot",+ },+ )+ assert not fetched.is_error and fetched.structured_content is not None+ full_snapshot = fetched.structured_content["content"][0]+ page_info = session.page_pool.pages[0]+ page = cast(Page, page_info.page)+ navigations: list[str] = []+ page.on("framenavigated", lambda frame: navigations.append(frame.url))+ await page.evaluate("window.snapshotSearchState = 'retained'")+ result = await client.call_tool("browser_snapshot", {"session_id": "browser", "search": "save RESULT"})+ assert not result.is_error and isinstance(result.content[0], TextContent)+ snapshot = result.content[0].text+ assert snapshot.startswith('- main "Results"')+ assert len(snapshot) < len(full_snapshot)+ assert "[box=" in snapshot+ assert 'main "Results"' in snapshot and 'region "Catalog"' in snapshot+ assert "Before result 0" not in snapshot and "After result 11" not in snapshot+ assert "\n...\n" in snapshot and snapshot.endswith("...")+ matched = search(r'button "Save result".*?\[ref=([^\]]+)\]', snapshot)+ assert matched is not None+ clicked = await client.call_tool(+ "browser_actions",+ {"session_id": "browser", "actions": [{"type": "click", "target": f"aria-ref={matched[1]}"}]},+ )+ assert not clicked.is_error+ assert await page.locator("output").inner_text() == "Saved"+ without_boxes = await client.call_tool(+ "browser_snapshot",+ {"session_id": "browser", "search": '^ +-[ ]button "Save result"', "regex": True, "boxes": False},+ )+ assert not without_boxes.is_error and isinstance(without_boxes.content[0], TextContent)+ assert without_boxes.content[0].text.startswith('- main "Results"')+ assert "[box=" not in without_boxes.content[0].text+ assert "[ref=" in without_boxes.content[0].text+ shallow = await client.call_tool(+ "browser_snapshot", {"session_id": "browser", "search": "Save result", "depth": 1}+ )+ assert not shallow.is_error+ assert shallow.content == [TextContent(type="text", text="")]+ assert await page.evaluate("window.snapshotSearchState") == "retained"+ assert requests == ["https://snapshot-search.test/"] and not navigations+ assert session.page_pool.pages == [page_info] and page_info.state == "ready"+ finally:+ closed = await client.call_tool("close_session", {"session_id": "browser"})+ assert not closed.is_error