smooth-py 0.1.3.post0__py3-none-any.whl → 0.2.0__py3-none-any.whl

smooth/__init__.py

@@ -4,11 +4,8 @@ import asyncio
 import logging
 import os
 import time
-from typing import (
-  Any,
-  Literal,
-)
-from urllib.parse import urlencode
+import urllib.parse
+from typing import Any, Literal, Type
 
 import httpx
 import requests
@@ -20,6 +17,17 @@ logger = logging.getLogger("smooth")
 
 BASE_URL = "https://api2.circlemind.co/api/"
 
+
+# --- Utils ---
+
+
+def _encode_url(url: str, interactive: bool = True, embed: bool = False) -> str:
+  parsed_url = urllib.parse.urlparse(url)
+  params = urllib.parse.parse_qs(parsed_url.query)
+  params.update({"interactive": "true" if interactive else "false", "embed": "true" if embed else "false"})
+  return urllib.parse.urlunparse(parsed_url._replace(query=urllib.parse.urlencode(params)))
+
+
 # --- Models ---
 # These models define the data structures for API requests and responses.
 
@@ -40,6 +48,9 @@ class TaskRequest(BaseModel):
   """Run task request model."""
 
   task: str = Field(description="The task to run.")
+  response_model: dict[str, Any] | None = Field(
+    default=None, description="If provided, the schema describing the desired output structure. Default is None"
+  )
   agent: Literal["smooth"] = Field(default="smooth", description="The agent to use for the task.")
   max_steps: int = Field(default=32, ge=2, le=128, description="Maximum number of steps the agent can take (min 2, max 128).")
   device: Literal["desktop", "mobile"] = Field(default="mobile", description="Device type for the task. Default is mobile.")
@@ -66,13 +77,14 @@ class BrowserSessionRequest(BaseModel):
     default=None,
     description=("The session ID to open in the browser. If None, a new session will be created with a random name."),
   )
+  live_view: bool | None = Field(default=True, description="Request a live URL to interact with the browser session.")
 
 
 class BrowserSessionResponse(BaseModel):
   """Browser session response model."""
 
-  live_url: str = Field(description="The live URL to interact with the browser session.")
   session_id: str = Field(description="The ID of the browser session associated with the opened browser instance.")
+  live_url: str | None = Field(default=None, description="The live URL to interact with the browser session.")
 
 
 class BrowserSessionsResponse(BaseModel):
@@ -151,6 +163,22 @@ class BaseClient:
 # --- Synchronous Client ---
 
 
+class BrowserSessionHandle(BaseModel):
+  """Browser session handle model."""
+
+  browser_session: BrowserSessionResponse = Field(description="The browser session associated with this handle.")
+
+  def session_id(self):
+    """Returns the session ID for the browser session."""
+    return self.browser_session.session_id
+
+  def live_url(self, interactive: bool = True, embed: bool = False):
+    """Returns the live URL for the browser session."""
+    if self.browser_session.live_url:
+      return _encode_url(self.browser_session.live_url, interactive=interactive, embed=embed)
+    return None
+
+
 class TaskHandle:
   """A handle to a running task."""
 
@@ -182,20 +210,15 @@ class TaskHandle:
 
   def live_url(self, interactive: bool = True, embed: bool = False, timeout: int | None = None):
     """Returns the live URL for the task."""
-    params = {
-      "interactive": interactive,
-      "embed": embed
-    }
-
     if self._task_response and self._task_response.live_url:
-      return f"{self._task_response.live_url}?{urlencode(params)}"
+      return _encode_url(self._task_response.live_url, interactive=interactive, embed=embed)
 
     start_time = time.time()
     while timeout is None or (time.time() - start_time) < timeout:
       task_response = self._client._get_task(self.id)  # pyright: ignore [reportPrivateUsage]
       self._task_response = task_response
       if self._task_response.live_url:
-        return f"{self._task_response.live_url}?{urlencode(params)}"
+        return _encode_url(self._task_response.live_url, interactive=interactive, embed=embed)
       time.sleep(1)
 
     raise TimeoutError(f"Live URL not available for task {self.id}.")
@@ -263,6 +286,7 @@ class SmoothClient(BaseClient):
   def run(
     self,
     task: str,
+    response_model: dict[str, Any] | Type[BaseModel] | None = None,
     agent: Literal["smooth"] = "smooth",
     max_steps: int = 32,
     device: Literal["desktop", "mobile"] = "mobile",
@@ -280,6 +304,7 @@ class SmoothClient(BaseClient):
 
     Args:
         task: The task to run.
+        response_model: If provided, the schema describing the desired output structure.
         agent: The agent to use for the task.
         max_steps: Maximum number of steps the agent can take (max 64).
         device: Device type for the task. Default is mobile.
@@ -298,6 +323,7 @@ class SmoothClient(BaseClient):
     """
     payload = TaskRequest(
       task=task,
+      response_model=response_model.model_json_schema() if issubclass(response_model, BaseModel) else response_model,
       agent=agent,
       max_steps=max_steps,
       device=device,
@@ -312,11 +338,12 @@ class SmoothClient(BaseClient):
 
     return TaskHandle(initial_response.id, self)
 
-  def open_session(self, session_id: str | None = None) -> BrowserSessionResponse:
+  def open_session(self, session_id: str | None = None, live_view: bool = True) -> BrowserSessionHandle:
     """Gets an interactive browser instance.
 
     Args:
         session_id: The session ID to associate with the browser. If None, a new session will be created.
+        live_view: Whether to enable live view for the session.
 
     Returns:
         The browser session details, including the live URL.
@@ -327,10 +354,10 @@ class SmoothClient(BaseClient):
     try:
       response = self._session.post(
         f"{self.base_url}/browser/session",
-        json=BrowserSessionRequest(session_id=session_id).model_dump(exclude_none=True),
+        json=BrowserSessionRequest(session_id=session_id, live_view=live_view).model_dump(exclude_none=True),
       )
       data = self._handle_response(response)
-      return BrowserSessionResponse(**data["r"])
+      return BrowserSessionHandle(browser_session=BrowserSessionResponse(**data["r"]))
     except requests.exceptions.RequestException as e:
       logger.error(f"Request failed: {e}")
       raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
@@ -396,19 +423,15 @@ class AsyncTaskHandle:
 
   async def live_url(self, interactive: bool = True, embed: bool = False, timeout: int | None = None):
     """Returns the live URL for the task."""
-    params = {
-      "interactive": interactive,
-      "embed": embed
-    }
     if self._task_response and self._task_response.live_url:
-      return f"{self._task_response.live_url}?{urlencode(params)}"
+      return _encode_url(self._task_response.live_url, interactive=interactive, embed=embed)
 
     start_time = time.time()
     while timeout is None or (time.time() - start_time) < timeout:
       task_response = await self._client._get_task(self.id)  # pyright: ignore [reportPrivateUsage]
       self._task_response = task_response
       if task_response.live_url is not None:
-        return f"{task_response.live_url}?{urlencode(params)}"
+        return _encode_url(self._task_response.live_url, interactive=interactive, embed=embed)
       await asyncio.sleep(1)
 
     raise TimeoutError(f"Live URL not available for task {self.id}.")
@@ -428,6 +451,7 @@ class AsyncTaskHandle:
 
     raise TimeoutError(f"Recording URL not available for task {self.id}.")
 
+
 class SmoothAsyncClient(BaseClient):
   """An asynchronous client for the API."""
 
@@ -470,6 +494,7 @@ class SmoothAsyncClient(BaseClient):
   async def run(
     self,
     task: str,
+    response_model: dict[str, Any] | Type[BaseModel] | None = None,
     agent: Literal["smooth"] = "smooth",
     max_steps: int = 32,
     device: Literal["desktop", "mobile"] = "mobile",
@@ -487,6 +512,7 @@ class SmoothAsyncClient(BaseClient):
 
     Args:
         task: The task to run.
+        response_model: If provided, the schema describing the desired output structure.
         agent: The agent to use for the task.
         max_steps: Maximum number of steps the agent can take (max 64).
         device: Device type for the task. Default is mobile.
@@ -507,6 +533,7 @@ class SmoothAsyncClient(BaseClient):
     """
     payload = TaskRequest(
       task=task,
+      response_model=response_model.model_json_schema() if issubclass(response_model, BaseModel) else response_model,
       agent=agent,
       max_steps=max_steps,
       device=device,
@@ -521,11 +548,12 @@ class SmoothAsyncClient(BaseClient):
     initial_response = await self._submit_task(payload)
     return AsyncTaskHandle(initial_response.id, self)
 
-  async def open_session(self, session_id: str | None = None) -> BrowserSessionResponse:
+  async def open_session(self, session_id: str | None = None, live_view: bool = True) -> BrowserSessionHandle:
     """Opens an interactive browser instance asynchronously.
 
     Args:
         session_id: The session ID to associate with the browser.
+        live_view: Whether to enable live view for the session.
 
     Returns:
         The browser session details, including the live URL.
@@ -536,10 +564,10 @@ class SmoothAsyncClient(BaseClient):
     try:
       response = await self._client.post(
         f"{self.base_url}/browser/session",
-        json=BrowserSessionRequest(session_id=session_id).model_dump(exclude_none=True),
+        json=BrowserSessionRequest(session_id=session_id, live_view=live_view).model_dump(exclude_none=True),
       )
       data = self._handle_response(response)
-      return BrowserSessionResponse(**data["r"])
+      return BrowserSessionHandle(browser_session=BrowserSessionResponse(**data["r"]))
     except httpx.RequestError as e:
       logger.error(f"Request failed: {e}")
       raise ApiError(status_code=0, detail=f"Request failed: {str(e)}") from None
@@ -573,3 +601,20 @@ class SmoothAsyncClient(BaseClient):
   async def close(self):
     """Closes the async client session."""
     await self._client.aclose()
+
+
+# Export public API
+__all__ = [
+  "SmoothClient",
+  "SmoothAsyncClient",
+  "TaskHandle",
+  "AsyncTaskHandle",
+  "BrowserSessionHandle",
+  "TaskRequest",
+  "TaskResponse",
+  "BrowserSessionRequest",
+  "BrowserSessionResponse",
+  "BrowserSessionsResponse",
+  "ApiError",
+  "TimeoutError",
+]

smooth/mcp/__init__.py

@@ -0,0 +1,9 @@
+"""Smooth SDK MCP Integration.
+
+This module provides Model Context Protocol integration for the Smooth SDK,
+allowing browser automation through AI assistants.
+"""
+
+from .server import SmoothMCP
+
+__all__ = ["SmoothMCP"]

smooth/mcp/server.py

@@ -0,0 +1,570 @@
+"""Smooth SDK MCP Server Implementation.
+
+This module provides the SmoothMCP class that integrates the Smooth SDK
+with the Model Context Protocol for AI assistant interactions.
+"""
+
+import asyncio
+import os
+from typing import Annotated, Any, Dict, Literal, Optional
+
+try:
+  from fastmcp import Context, FastMCP
+  from fastmcp.exceptions import ResourceError
+  from pydantic import Field
+except ImportError as e:
+  raise ImportError("FastMCP is required for MCP functionality. Install with: pip install smooth-py[mcp]") from e
+
+from .. import ApiError, SmoothAsyncClient, TimeoutError
+
+
+class SmoothMCP:
+  """MCP server for Smooth SDK browser automation agent.
+
+  This class provides a Model Context Protocol server that exposes
+  Smooth SDK functionality to AI assistants and other MCP clients.
+
+  Example:
+      ```python
+      from smooth.mcp import SmoothMCP
+
+      # Create and run the MCP server
+      mcp = SmoothMCP(api_key="your-api-key")
+      mcp.run()  # Runs with STDIO transport by default
+
+      # Or run with HTTP transport
+      mcp.run(transport="http", host="0.0.0.0", port=8000)
+      ```
+  """
+
+  def __init__(
+    self,
+    api_key: Optional[str] = None,
+    server_name: str = "Smooth Browser Agent",
+    base_url: Optional[str] = None,
+  ):
+    """Initialize the Smooth MCP server.
+
+    Args:
+        api_key: Smooth API key. If not provided, will use CIRCLEMIND_API_KEY env var.
+        server_name: Name for the MCP server.
+        base_url: Base URL for the Smooth API (optional).
+    """
+    self.api_key = api_key or os.getenv("CIRCLEMIND_API_KEY")
+    if not self.api_key:
+      raise ValueError("API key is required. Provide it directly or set CIRCLEMIND_API_KEY environment variable.")
+
+    self.base_url = base_url
+    self.server_name = server_name
+
+    # Initialize FastMCP server
+    self._mcp = FastMCP(server_name)
+    self._smooth_client: Optional[SmoothAsyncClient] = None
+
+    # Register tools and resources
+    self._register_tools()
+    self._register_resources()
+
+  async def _get_smooth_client(self) -> SmoothAsyncClient:
+    """Get or create the Smooth client instance."""
+    if self._smooth_client is None:
+      kwargs = {"api_key": self.api_key}
+      if self.base_url:
+        kwargs["base_url"] = self.base_url
+      self._smooth_client = SmoothAsyncClient(**kwargs)
+    return self._smooth_client
+
+  def _register_tools(self):
+    """Register MCP tools."""
+
+    @self._mcp.tool(
+      name="run_browser_task",
+      description=(
+        "Execute browser automation tasks using natural language descriptions. "
+        "Supports both desktop and mobile devices with optional profile state, recording, and advanced configuration."
+      ),
+      annotations={"title": "Run Browser Task", "readOnlyHint": False, "destructiveHint": False, "openWorldHint": True},
+    )
+    async def run_browser_task(
+      ctx: Context,
+      task: Annotated[
+        str,
+        Field(
+          description=(
+            "Natural language description of the browser automation task to perform "
+            "(e.g., 'Go to Google and search for FastMCP', 'Fill out the contact form with test data at this url: ...')"
+          )
+        ),
+      ],
+      device: Annotated[
+        Literal["desktop", "mobile"],
+        Field(
+          description=(
+            "Device type for browser automation. Desktop provides full browser experience, "
+            "mobile uses a mobile viewport. Mobile is preferred as mobile web pages are lighter and easier to interact with"
+          )
+        ),
+      ] = "mobile",
+      max_steps: Annotated[
+        int,
+        Field(
+          description=(
+            "Maximum number of steps the agent can take to complete the task. "
+            "Higher values allow more complex multi-step workflows"
+          ),
+          ge=2,
+          le=128,
+        ),
+      ] = 32,
+      enable_recording: Annotated[
+        bool,
+        Field(
+          description="Whether to record video of the task execution. Recordings can be used for debugging and verification"
+        ),
+      ] = True,
+      profile_id: Annotated[
+        Optional[str],
+        Field(
+          description=(
+            "Browser profile ID to pass login credentials to the agent. "
+            "The user must have already created and manually populated a profile and provide the profile ID."
+          )
+        ),
+      ] = None,
+      # stealth_mode: Annotated[
+      #   bool,
+      #   Field(
+      #     description=(
+      #       "Run browser in stealth mode to avoid detection by anti-bot systems. "
+      #       "Useful for accessing sites that block automated browsers"
+      #     )
+      #   ),
+      # ] = True,
+      # proxy_server: Annotated[
+      #   Optional[str],
+      #   Field(
+      #     description=(
+      #       "Proxy server URL to route browser traffic through. "
+      #       "Must include protocol (e.g., 'http://proxy.example.com:8080')"
+      #     )
+      #   ),
+      # ] = None,
+      # proxy_username: Annotated[Optional[str], Field(description="Username for proxy server authentication")] = None,
+      # proxy_password: Annotated[Optional[str], Field(description="Password for proxy server authentication")] = None,
+      timeout: Annotated[
+        int,
+        Field(
+          description=(
+            "Maximum time to wait for task completion in seconds. Increase for complex tasks that may take longer."
+            " Max 15 minutes."
+          ),
+          ge=30,
+          le=60*15,
+        ),
+      ] = 60*15,
+    ) -> Dict[str, Any]:
+      """Run a browser automation task using the Smooth SDK.
+
+      Args:
+          ctx: MCP context for logging and communication
+          task: Natural language description of the task to perform
+          device: Device type ("desktop" or "mobile", default: "mobile")
+          max_steps: Maximum steps for the agent (2-128, default: 32)
+          enable_recording: Whether to record the execution (default: True)
+          profile_id: Optional browser profile ID to maintain state
+          stealth_mode: Run in stealth mode to avoid detection (default: False)
+          proxy_server: Proxy server URL (must include protocol)
+          proxy_username: Proxy authentication username
+          proxy_password: Proxy authentication password
+          timeout: Maximum time to wait for completion in seconds (default: 300)
+
+      Returns:
+          Dictionary containing task results, status, and URLs
+      """
+      try:
+        await ctx.info(f"Starting browser task: {task}")
+
+        # Validate device parameter
+        if device not in ["desktop", "mobile"]:
+          raise ValueError("Device must be 'desktop' or 'mobile'")
+
+        # Validate max_steps
+        if not (2 <= max_steps <= 128):
+          raise ValueError("max_steps must be between 2 and 128")
+
+        client = await self._get_smooth_client()
+
+        # Submit the task
+        task_handle = await client.run(
+          task=task,
+          device=device,  # type: ignore
+          max_steps=max_steps,
+          enable_recording=enable_recording,
+          profile_id=profile_id,
+          stealth_mode=False,
+          proxy_server=None,
+          proxy_username=None,
+          proxy_password=None,
+        )
+
+        await ctx.info(f"Task submitted with ID: {task_handle.id}")
+
+        # Wait for completion
+        await ctx.info("Waiting for task completion...")
+        result = await task_handle.result(timeout=timeout)
+
+        # Prepare response
+        response = {
+          "task_id": task_handle.id,
+          "status": result.status,
+          "output": result.output,
+          "credits_used": result.credits_used,
+          "device": result.device,
+        }
+
+        if result.recording_url:
+          response["recording_url"] = result.recording_url
+          await ctx.info(f"Recording available at: {result.recording_url}")
+
+        if result.status == "done":
+          await ctx.info("Task completed successfully!")
+        else:
+          await ctx.error(f"Task failed with status: {result.status}")
+
+        return response
+
+      except ApiError as e:
+        error_msg = f"Smooth API error: {e.detail}"
+        await ctx.error(error_msg)
+        raise Exception(error_msg) from None
+      except TimeoutError as e:
+        error_msg = f"Task timed out: {str(e)}"
+        await ctx.error(error_msg)
+        raise Exception(error_msg) from None
+      except Exception as e:
+        error_msg = f"Unexpected error: {str(e)}"
+        await ctx.error(error_msg)
+        raise Exception(error_msg) from None
+
+    @self._mcp.tool(
+      name="create_browser_profile",
+      description=(
+        "Create a new browser profile to store user credentials. "
+        "Returns a profile ID and live URL that need to be returned to the user to log in into various websites. "
+        "Once the user confirms they have logged in to the desired websites, the profile ID can be used in subsequent tasks "
+        " to access the user's authenticated state."
+      ),
+      annotations={"title": "Create Browser profile", "readOnlyHint": False, "destructiveHint": False},
+    )
+    async def create_browser_profile(
+      ctx: Context,
+      profile_id: Annotated[
+        Optional[str],
+        Field(
+          description=(
+            "Optional custom profile ID. If not provided, a random one will be generated. "
+            "Use meaningful names for easier profile management"
+          )
+        ),
+      ] = None,
+    ) -> Dict[str, Any]:
+      """Create a new browser profile to maintain state between tasks.
+
+      Args:
+          ctx: MCP context for logging and communication
+          profile_id: Optional custom profile ID. If not provided, a random one will be generated.
+
+      Returns:
+          Dictionary containing profile details and live URL
+      """
+      try:
+        await ctx.info("Creating browser profile" + (f" with ID: {profile_id}" if profile_id else ""))
+
+        client = await self._get_smooth_client()
+        profile_handle = await client.open_profile(profile_id=profile_id)
+
+        response = {
+          "profile_id": profile_handle.browser_profile.profile_id,
+          "live_url": profile_handle.browser_profile.live_url,
+        }
+
+        await ctx.info(f"Browser profile created: {response['profile_id']}")
+        await ctx.info(f"Live profile URL: {response['live_url']}")
+
+        return response
+
+      except ApiError as e:
+        error_msg = f"Failed to create browser profile: {e.detail}"
+        await ctx.error(error_msg)
+        raise Exception(error_msg) from None
+      except Exception as e:
+        error_msg = f"Unexpected error creating profile: {str(e)}"
+        await ctx.error(error_msg)
+        raise Exception(error_msg) from None
+
+    @self._mcp.tool(
+      name="list_browser_profiles",
+      description=(
+        "Retrieve a list of all saved browser profiles. "
+        "Shows profile IDs that can be passed to future tasks to access login credentials."
+      ),
+      annotations={"title": "List Browser profiles", "readOnlyHint": True, "destructiveHint": False},
+    )
+    async def list_browser_profiles(ctx: Context) -> Dict[str, Any]:
+      """List all existing browser profiles.
+
+      Args:
+          ctx: MCP context for logging and communication
+
+      Returns:
+          Dictionary containing list of profile IDs
+      """
+      try:
+        await ctx.info("Retrieving browser profiles...")
+
+        client = await self._get_smooth_client()
+        profiles = await client.list_profiles()
+
+        response = {
+          "profile_ids": profiles.profile_ids,
+          "total_profiles": len(profiles.profile_ids),
+        }
+
+        await ctx.info(f"Found {len(profiles.profile_ids)} browser profiles")
+
+        return response
+
+      except ApiError as e:
+        error_msg = f"Failed to list browser profiles: {e.detail}"
+        await ctx.error(error_msg)
+        raise Exception(error_msg) from None
+      except Exception as e:
+        error_msg = f"Unexpected error listing profiles: {str(e)}"
+        await ctx.error(error_msg)
+        raise Exception(error_msg) from None
+
+    @self._mcp.tool(
+      name="delete_browser_profile",
+      description=(
+        "Delete a browser profile and its associated credentials. "
+        "This permanently removes the profile and all associated data including cookies and cache."
+      ),
+      annotations={"title": "Delete Browser profile", "readOnlyHint": False, "destructiveHint": True},
+    )
+    async def delete_browser_profile(
+      ctx: Context,
+      profile_id: Annotated[
+        str,
+        Field(
+          description=(
+            "The ID of the browser profile to delete. "
+            "Once deleted, this profile ID cannot be reused and all associated data will be lost"
+          ),
+          min_length=1,
+        ),
+      ],
+    ) -> Dict[str, Any]:
+      """Delete a browser profile and clean up its data.
+
+      Args:
+          ctx: MCP context for logging and communication
+          profile_id: The ID of the profile to delete
+
+      Returns:
+          Dictionary confirming deletion
+      """
+      try:
+        await ctx.info(f"Deleting browser profile: {profile_id}")
+
+        client = await self._get_smooth_client()
+        await client.delete_profile(profile_id)
+
+        response = {
+          "deleted_profile_id": profile_id,
+          "status": "deleted",
+        }
+
+        await ctx.info(f"Browser profile {profile_id} deleted successfully")
+
+        return response
+
+      except ApiError as e:
+        error_msg = f"Failed to delete browser profile {profile_id}: {e.detail}"
+        await ctx.error(error_msg)
+        raise Exception(error_msg) from None
+      except Exception as e:
+        error_msg = f"Unexpected error deleting profile: {str(e)}"
+        await ctx.error(error_msg)
+        raise Exception(error_msg) from None
+
+  def _register_resources(self):
+    """Register MCP resources with comprehensive documentation and dynamic capabilities."""
+
+    # Static API information with annotations
+    @self._mcp.resource(
+      "smooth://api/info",
+      description="Comprehensive information about the Smooth SDK MCP server and its capabilities",
+      annotations={"readOnlyHint": True, "idempotentHint": True},
+      tags={"documentation", "api"},
+      mime_type="text/markdown",
+    )
+    async def get_api_info(ctx: Context) -> str:
+      """Get detailed information about the Smooth SDK and API."""
+      await ctx.info("Providing Smooth SDK API information")
+      return f"""# Smooth SDK MCP Server v{self._mcp.server_info.version}
+
+This MCP server provides access to Smooth's browser automation capabilities through the Model Context Protocol.
+
+## Server Information
+- **Name**: {self._mcp.server_info.name}
+- **Version**: {self._mcp.server_info.version}
+- **Request ID**: {ctx.request_id}
+- **Base URL**: {self.base_url or "Default (https://api2.circlemind.co/api/v1)"}
+
+## Available Tools
+
+### 🚀 run_browser_task
+Execute browser automation tasks using natural language descriptions.
+- **Device Support**: Desktop and mobile support
+- **Profile Management**: Save and access user credentials
+- **Recording**: Video capture of automation
+
+### 🔧 create_browser_profile
+Create persistent browser profiles to store and access credentials.
+- **Live Viewing**: Real-time browser access for the user to enter their credentials
+
+### 📋 list_browser_profiles
+View all active browser profiles.
+
+### 🗑️ delete_browser_profile
+Permanently removes profile data when no longer needed.
+- **Destructive**: Permanently removes profile data
+
+## Configuration
+
+Set your API key using the CIRCLEMIND_API_KEY environment variable:
+```bash
+export CIRCLEMIND_API_KEY="your-api-key-here"
+```
+
+## Best Practices
+
+1. **Use profiles**: Ask the user to create profiles for tasks requiring login and then use them.
+2. **Descriptive Tasks**: Use clear, specific task descriptions.
+3. **Error Handling**: Check task results for success/failure status
+"""
+
+    # Dynamic examples resource with path parameters
+    @self._mcp.resource(
+      "smooth://examples/{category}",
+      description="Get task examples for specific categories of browser automation",
+      annotations={"readOnlyHint": True, "idempotentHint": True},
+      tags={"examples", "templates", "dynamic"},
+      mime_type="text/markdown",
+    )
+    async def get_category_examples(category: str, ctx: Context) -> str:
+      """Get examples for a specific category of browser automation tasks."""
+      await ctx.info(f"Providing examples for category: {category}")
+
+      examples_db = {
+        "scraping": """# Web Scraping Examples
+
+## Basic Data Extraction
+- "Go to example.com and extract all product prices"
+- "Navigate to news.ycombinator.com and get the top 10 story titles"
+- "Visit Wikipedia and search for 'artificial intelligence', then summarize the first paragraph"
+
+## E-commerce Data
+- "Extract product details from Amazon search results for 'wireless headphones'"
+- "Get all customer reviews from the first product page"
+- "Compare prices across multiple product listings"
+
+## Social Media
+- "Scrape the latest 20 tweets from a public Twitter profile"
+- "Extract post engagement metrics from Instagram"
+- "Get trending topics from Reddit front page"
+""",
+        "forms": """# Form Automation Examples
+
+## Contact Forms
+- "Go to contact form at example.com and fill it with test data"
+- "Fill out the newsletter signup with email: test@example.com"
+- "Submit a support request with priority: high"
+
+## Registration
+- "Navigate to signup page and create an account with random details"
+- "Complete user registration with name: John Doe, email: john@test.com"
+- "Fill out profile information after account creation"
+
+## Applications
+- "Fill out the job application form with my resume information"
+- "Complete the rental application with provided details"
+- "Submit a loan application with financial information"
+""",
+        "testing": """# Testing & QA Examples
+
+## Functionality Testing
+- "Test the checkout flow on our e-commerce site"
+- "Verify all links on the homepage are working"
+- "Check if the contact form is submitting properly"
+
+## UI/UX Testing
+- "Test responsive design by switching between desktop and mobile"
+- "Verify navigation menu works on all pages"
+- "Check loading times for key user journeys"
+
+## Integration Testing
+- "Test login flow with valid and invalid credentials"
+- "Verify payment processing with test cards"
+- "Check email verification workflow"
+""",
+        "social": """# Social Media Automation Examples
+
+## Content Management
+- "Post a status update on Twitter" (requires login profile)
+- "Upload an image to Instagram with caption" (requires login profile)
+- "Share an article on LinkedIn with comment" (requires login profile)
+
+## Engagement
+- "Like the latest 10 posts in my feed" (requires login profile)
+- "Reply to mentions and messages" (requires login profile)
+- "Follow accounts based on specific criteria" (requires login profile)
+
+## Analytics
+- "Check latest posts performance metrics" (requires login profile)
+- "Download engagement reports" (requires login profile)
+- "Monitor brand mentions across platforms" (requires login profile)
+""",
+      }
+
+      if category not in examples_db:
+        available_categories = ", ".join(examples_db.keys())
+        raise ResourceError(f"Category '{category}' not found. Available categories: {available_categories}")
+
+      return examples_db[category]
+
+  def run(self, **kwargs):
+    """Run the MCP server.
+
+    Args:
+        **kwargs: Arguments passed to FastMCP.run() such as transport, host, port, etc.
+    """
+    try:
+      self._mcp.run(**kwargs)
+    finally:
+      # Clean up on exit
+      asyncio.run(self._cleanup())
+
+  async def _cleanup(self):
+    """Clean up resources on shutdown."""
+    if self._smooth_client:
+      await self._smooth_client.close()
+      self._smooth_client = None
+
+  @property
+  def fastmcp_server(self) -> FastMCP:
+    """Access to the underlying FastMCP server instance.
+
+    This allows advanced users to add custom tools or resources.
+    """
+    return self._mcp

{smooth_py-0.1.3.post0.dist-info → smooth_py-0.2.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: smooth-py
-Version: 0.1.3.post0
+Version: 0.2.0
 Summary: 
 Author: Luca Pinchetti
 Author-email: luca@circlemind.co
@@ -10,6 +10,8 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Provides-Extra: mcp
+Requires-Dist: fastmcp (>=2.0.0,<3.0.0) ; extra == "mcp"
 Requires-Dist: httpx (>=0.28.1,<0.29.0)
 Requires-Dist: pydantic (>=2.11.7,<3.0.0)
 Description-Content-Type: text/markdown
@@ -24,6 +26,7 @@ The Smooth Python SDK provides a convenient way to interact with the Smooth API
 *   **Task Management**: Easily run tasks and retrieve results upon completion.
 *   **Interactive Browser Sessions**: Get access to, interact with, and delete stateful browser sessions to manage your login credentials.
 *   **Advanced Task Configuration**: Customize task execution with options for device type, session recording, stealth mode, and proxy settings.
+*   **🆕 MCP Server**: Use the included Model Context Protocol server to integrate browser automation with AI assistants like Claude Desktop.
 
 ## Installation
 
@@ -33,6 +36,51 @@ You can install the Smooth Python SDK using pip:
 pip install smooth-py
 ```
 
+For MCP server functionality, also install FastMCP:
+
+```bash
+pip install fastmcp
+```
+
+## Quick Start Options
+
+### Option 1: Direct SDK Usage
+
+Use the SDK directly in your Python applications:
+
+### Option 2: MCP Server (AI Assistant Integration)
+
+Use the included MCP server to integrate browser automation with AI assistants:
+
+#### Installation
+```bash
+# Install with MCP support
+pip install smooth-py[mcp]
+```
+
+#### Basic Usage
+```python
+from smooth.mcp import SmoothMCP
+
+# Create and run the MCP server  
+mcp = SmoothMCP(api_key="your-api-key")
+mcp.run()  # STDIO transport for Claude Desktop
+
+# Or with HTTP transport for web deployment
+mcp.run(transport="http", host="0.0.0.0", port=8000)
+```
+
+#### Standalone Script (Backward Compatible)
+```bash
+# Set your API key
+export CIRCLEMIND_API_KEY="your-api-key-here"
+
+# Run the MCP server
+python mcp_server.py
+```
+
+Then configure your AI assistant (like Claude Desktop) to use the MCP server. See [MCP_README.md](MCP_README.md) for detailed setup instructions.
+
 ## Authentication
 
 The SDK requires an API key for authentication. You can provide the API key in two ways:
@@ -162,3 +210,32 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
+## MCP Server (AI Assistant Integration)
+
+The Smooth SDK includes a Model Context Protocol (MCP) server that allows AI assistants like Claude Desktop or Cursor to perform browser automation tasks through natural language commands.
+
+### Installation
+
+```bash
+pip install smooth-py[mcp]
+```
+
+### Basic Usage
+
+```python
+from smooth.mcp import SmoothMCP
+
+# Create and run the MCP server
+mcp = SmoothMCP(api_key="your-api-key")
+mcp.run()
+```
+
+### Example MCP Usage
+
+Once configured, you can ask your MCP client to perform browser automation:
+
+- "Please go to news.ycombinator.com and get the top 5 story titles"
+- "Create a browser session, log into Gmail, and check for unread emails"
+- "Go to Amazon and search for wireless headphones under $100"
+- "Fill out the contact form at example.com with test data"
+

smooth_py-0.2.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+smooth/__init__.py,sha256=U32quTlDKOWQpsstfJ7pCgsOeUWYC3AAAzQDJkpBzBk,23629
+smooth/mcp/__init__.py,sha256=0aJVFi2a8Ah3-5xtgyZ5UMbaaJsBWu2T8QLWoFQITk8,219
+smooth/mcp/server.py,sha256=9SymTD4NOGTMN8P-LNGlvYNvv81yCIZfZeeuhEcAc6s,20068
+smooth_py-0.2.0.dist-info/METADATA,sha256=o9iLsqHyEBGkOyPmW695HHmcQwV0afH2Evkp7a0O6KA,7425
+smooth_py-0.2.0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+smooth_py-0.2.0.dist-info/RECORD,,

smooth_py-0.1.3.post0.dist-info/RECORD

@@ -1,4 +0,0 @@
-smooth/__init__.py,sha256=jIEM1usuwrZWq-m1YgsUsLCkvUkhS9BNqgFc3HUPEvw,21263
-smooth_py-0.1.3.post0.dist-info/METADATA,sha256=x4u365t5CvrRvMPsrCrLy2sVNT4ojf8nK8pdntodEdw,5394
-smooth_py-0.1.3.post0.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-smooth_py-0.1.3.post0.dist-info/RECORD,,