🕷️ 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
perf(mcp): Make session creating return shorter output
Karim shoair3c3e3f95ff1f
diff --git a/docs/ai/mcp-server.md b/docs/ai/mcp-server.mdindex b88da11..386b788 100644--- a/docs/ai/mcp-server.md+++ b/docs/ai/mcp-server.md@@ -19,8 +19,8 @@ The Scrapling MCP Server provides sixteen tools for web scraping and browser int### Session tools#### 🔌 Session Management-- **`browser_open`**: Create a persistent stealthy browser session that stays open across multiple `browser_fetch` calls, avoiding the overhead of launching a new browser each time. It holds the browser-level configuration and returns the session's effective `settings` for the AI agent (empty for CDP sessions).-- **`open_request_session`**: Create a persistent HTTP requests session (no browser) used with `session_make_request`, keeping cookies, connections, and the browser fingerprint (`impersonate`) between requests. It returns the same `settings` receipt and shows in `list_sessions` as a `static` session.+- **`browser_open`**: Create a persistent stealthy browser session that stays open across multiple `browser_fetch` calls, avoiding the overhead of launching a new browser each time. It holds the browser-level configuration and returns only `session_id` and `session_type`. Use `list_sessions` to see its effective `settings` (empty for CDP sessions).+- **`open_request_session`**: Create a persistent HTTP requests session (no browser) used with `session_make_request`, keeping cookies, connections, and the browser fingerprint (`impersonate`) between requests. It returns only `session_id` and `session_type`, with type `static`. Use `list_sessions` to see its effective `settings`.- **`close_session`**: Close a persistent session (browser or requests) and free its resources.- **`list_sessions`**: List all active sessions with their details and `settings`.diff --git a/scrapling/core/ai/server.py b/scrapling/core/ai/server.pyindex 792e43d..b2ef8ee 100644--- a/scrapling/core/ai/server.py+++ b/scrapling/core/ai/server.py@@ -127,11 +127,16 @@ class NetworkRequestsModel(BaseModel):dropped_count: int-class SessionInfo(BaseModel):- """Information about an open browser session."""+class SessionCreatedModel(BaseModel):+ """Response returned when a new session is created."""session_id: str = Field(description="The unique identifier of the session.")session_type: SessionType = Field(description="The type of the session: 'stealthy' or 'static'.")+++class SessionInfo(SessionCreatedModel):+ """Information about an open browser session."""+created_at: str = Field(description="ISO timestamp of when the session was created.")is_alive: bool = Field(description="Whether the session is still alive and usable.")settings: Dict[str, Any] = Field(@@ -140,12 +145,6 @@ class SessionInfo(BaseModel):)-class SessionCreatedModel(SessionInfo):- """Response returned when a new session is created."""-- message: str = Field(description="A confirmation message.")--class SessionClosedModel(BaseModel):"""Response returned when a session is closed."""@@ -261,16 +260,8 @@ class ScraplingMCPServer:def _register_session(self, session_id: str, session: Any, session_type: SessionType) -> SessionCreatedModel:"""Store a started session and build its creation receipt."""- entry = _SessionEntry(session=session, session_type=session_type)- self._sessions[session_id] = entry- return SessionCreatedModel(- session_id=session_id,- session_type=session_type,- created_at=entry.created_at,- is_alive=True,- settings=_session_settings(session),- message=f"Session '{session_id}' ({session_type}) created successfully.",- )+ self._sessions[session_id] = _SessionEntry(session=session, session_type=session_type)+ return SessionCreatedModel(session_id=session_id, session_type=session_type)async def browser_open(self,diff --git a/tests/ai/test_ai_mcp.py b/tests/ai/test_ai_mcp.pyindex a0654e5..996ef48 100644--- a/tests/ai/test_ai_mcp.py+++ b/tests/ai/test_ai_mcp.py@@ -416,8 +416,7 @@ class TestSessionManagement:"""Test opening and closing a stealthy session"""result = await server.browser_open(headless=True)assert isinstance(result, SessionCreatedModel)- assert result.session_type == "stealthy"- assert result.is_alive is True+ assert result.model_dump() == {"session_id": result.session_id, "session_type": "stealthy"}session_id = result.session_id# Close the session@@ -572,9 +571,7 @@ class TestStaticSessionManagement:"""Open a requests session, make GET and POST requests through it, then close it"""created = await server.open_request_session(session_id="st")assert isinstance(created, SessionCreatedModel)- assert created.session_type == "static"- assert created.is_alive is True- assert created.settings["impersonate"] == "chrome"+ assert created.model_dump() == {"session_id": "st", "session_type": "static"}response = await server.session_make_request(url=f"{httpbin.url}/html", session_id="st")assert isinstance(response, ResponseModel)@@ -587,7 +584,8 @@ class TestStaticSessionManagement:listed = await server.list_sessions()assert listed[0].session_type == "static"- assert listed[0].settings == created.settings+ assert listed[0].is_alive is True+ assert listed[0].settings["impersonate"] == "chrome"session = server._sessions["st"].sessionclosed = await server.close_session("st")@@ -987,7 +985,7 @@ class TestModeSplitContract:class TestSessionSettingsReceipt:- """browser_open and list_sessions return the session's effective settings."""+ """list_sessions returns the session's effective settings."""def test_session_settings_extracts_json_safe_fields(self):"""The helper keeps JSON primitives and drops the rest (callables, structs, sequences)"""@@ -1012,16 +1010,39 @@ class TestSessionSettingsReceipt:assert all(isinstance(v, (str, int, float, bool)) or v is None for v in settings.values()), settings@pytest.mark.asyncio- async def test_browser_open_and_list_report_the_receipt(self, monkeypatch):- """browser_open returns the receipt and list_sessions reports the same one"""+ @pytest.mark.parametrize("tool,session_type", [("browser_open", "stealthy"), ("open_request_session", "static")])+ async def test_creation_receipt_is_compact_and_list_keeps_details(self, monkeypatch, tool, session_type):monkeypatch.setattr("scrapling.core.ai.server.AsyncStealthySession", _FakeStealthySession)server = ScraplingMCPServer()-- created = await server.browser_open()-- assert created.settings["headless"] is True- listed = await server.list_sessions()- assert listed[0].settings == created.settings+ expected = {"session_id": "compact", "session_type": session_type}+ async with Client(server._build_server("127.0.0.1", 8000)) as client:+ schema = next(item for item in (await client.list_tools()).tools if item.name == tool).output_schema+ assert schema is not None+ assert set(schema["properties"]) == set(schema["required"]) == set(expected)+ created = await client.call_tool(tool, {"session_id": "compact"})+ assert not created.is_error+ try:+ assert created.structured_content == expected+ assert len(created.content) == 1 and isinstance(created.content[0], TextContent)+ assert loads(created.content[0].text) == expected+ listed = await client.call_tool("list_sessions", {})+ assert not listed.is_error+ assert isinstance(listed.content[0], TextContent)+ details = loads(listed.content[0].text)+ assert listed.structured_content == {"result": [details]}+ entry = server._sessions["compact"]+ assert details == {+ **expected,+ "created_at": entry.created_at,+ "is_alive": True,+ "settings": _session_settings(entry.session),+ }+ assert details["settings"]["headless" if session_type == "stealthy" else "impersonate"] == (+ True if session_type == "stealthy" else "chrome"+ )+ finally:+ assert not (await client.call_tool("close_session", {"session_id": "compact"})).is_error+ assert not server._sessionsdef _png_height(data: bytes) -> int: