Gemini Web Automation MCP

Instructions

Implementation Reference

• server.py:202-268 (handler)

  Primary handler for the 'check_web_task' MCP tool. Registered via @mcp.tool() decorator. Processes input parameters (task_id, compact), retrieves status from task_manager, adds runtime polling guidance for running tasks, and returns the result dictionary.
  @mcp.tool() async def check_web_task(task_id: str, compact: bool = True) -> dict[str, Any]: """ Check progress of a background web browsing task. Returns a summary of task progress. By default, returns compact format to avoid filling your context window with verbose progress logs. IMPORTANT: To prevent context bloat, wait at least 3-5 seconds between checks. Use the 'recommended_poll_after' timestamp as guidance. Args: task_id: Task ID from start_web_task() compact: Return summary only (default: True). Set to False for full details. Returns: Dictionary containing: - ok: Boolean indicating success - task_id: Task identifier - status: "pending", "running", "completed", "failed", or "cancelled" - progress_summary: Recent actions (compact mode only) - progress: Full action history (full mode only) - result: Task results (when completed) - error: Error message (when failed) - recommended_poll_after: Timestamp to check again (when running) - polling_guidance: Message about polling frequency Examples: - check_web_task("abc-123-def") # Compact summary - check_web_task("abc-123-def", compact=False) # Full details Best Practice: Only poll every 3-5 seconds to keep your context window clean. Use the wait() tool to pause between checks if your platform doesn't support automatic delays. Recommended workflow: 1. start_web_task("...") 2. wait(5) 3. check_web_task(task_id) 4. If still running, repeat steps 2-3 """ logger.info(f"Checking status for task: {task_id}") status = task_manager.get_task_status(task_id, compact=compact) if not status: return { "ok": False, "error": f"Task {task_id} not found" } # Add poll delay guidance for running tasks from datetime import datetime, timedelta, timezone result = { "ok": True, **status } if status.get("status") == "running": next_check = datetime.now(timezone.utc) + timedelta(seconds=5) result["recommended_poll_after"] = next_check.isoformat() result["polling_guidance"] = "Task in progress. Wait 5 seconds before next check to avoid context bloat." return result
• task_manager.py:187-211 (helper)

  Core helper method in BrowserTaskManager that fetches the task object, syncs live progress updates if the task is running, and returns either a compact summary or full details using the task's to_dict/to_compact_dict methods.
  def get_task_status(self, task_id: str, compact: bool = True) -> Optional[Dict[str, Any]]: """Get current status of a task. Args: task_id: Task identifier compact: If True, return compact summary (default). If False, return full progress. Returns: Task status dictionary or None if not found """ with self._lock: task = self.tasks.get(task_id) if not task: return None # Get live progress from agent if task is running if task.status == TaskStatus.RUNNING and task.agent: task.progress_updates = task.agent.progress_updates.copy() # Return compact or full format if compact: return task.to_compact_dict() else: return task.to_dict()
• task_manager.py:41-91 (helper)

  BrowserTask class methods to_dict() and to_compact_dict() that define the structure and content of the status dictionaries returned by get_task_status, serving as the output schema for the tool.
  def to_dict(self) -> Dict[str, Any]: """Convert task to dictionary for API responses.""" return { "task_id": self.task_id, "task_description": self.task_description, "url": self.url, "status": self.status, "created_at": self.created_at, "started_at": self.started_at, "completed_at": self.completed_at, "progress": self.progress_updates.copy() if self.progress_updates else [], "result": self.result, "error": self.error, } def to_compact_dict(self) -> Dict[str, Any]: """Convert task to compact dictionary with progress summary. Returns a smaller response suitable for frequent polling to avoid context window bloat in AI models. """ # Get last 3 progress items recent_progress = [] if self.progress_updates: recent_progress = [ item["message"] for item in self.progress_updates[-3:] ] # Build compact response compact = { "task_id": self.task_id, "task_description": self.task_description, "url": self.url, "status": self.status, "created_at": self.created_at, "started_at": self.started_at, "completed_at": self.completed_at, "progress_summary": { "total_steps": len(self.progress_updates) if self.progress_updates else 0, "recent_actions": recent_progress } } # Add result or error if task is complete if self.status == TaskStatus.COMPLETED: compact["result"] = self.result elif self.status == TaskStatus.FAILED: compact["error"] = self.error return compact