Skip to content

🕷️ 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

perf(mcp): Make session creating return shorter output

Karim shoair3c3e3f95ff1f
diff --git a/docs/ai/mcp-server.md b/docs/ai/mcp-server.md
index 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.py
index 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.py
index 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"].session
closed = 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._sessions
def _png_height(data: bytes) -> int: