mcp-server-browser-use

To report progress in a tool, use Progress() as the default value for the progress parameter.

Important Rules:

1. Do not use Optional[Progress] = None: This bypasses FastMCP's dependency injection system and may cause tools to fail in background task modes.
2. Always check for availability: Before calling methods on the progress object, check if it exists (if progress:) to avoid crashes when progress is not available.
3. Always await progress methods: All progress operations (e.g., set_total, set_message, increment) are asynchronous.

Recommended Helper Pattern for Graceful Degradation: If building a class that needs to report progress, implement a helper that checks for the existence of the progress object before attempting operations.

from fastmcp.dependencies import Progress
from typing import Optional

@server.tool(task=TaskConfig(mode="optional"))
async def long_running_task(
    topic: str,
    progress: Progress = Progress(),  # ✅ Correct
) -> str:
    if progress:
        await progress.set_total(100)
        await progress.set_message("Starting task...")

    # Do work...

    if progress:
        await progress.increment()

    return "Complete"

The project operates as a FastMCP server that communicates with MCP clients (like Claude Desktop or CLI tools) via HTTP POST requests to /mcp.

At its core, the server exposes MCP tools such as run_browser_agent and run_deep_research. These tools leverage the browser-use library (Agent + Playwright) to perform web automation. The architecture is composed of several key modules:

• FastMCP Server: The entry point providing tools and managing connections.
• Providers: A factory supporting 12 different LLM providers (including OpenAI, Anthropic, Gemini, Groq, and Ollama).
• Skills: A system for learning and running browser skills using CDP network capture and LLM extraction.
• Research: A workflow for deep research involving planning, searching, and synthesizing results.
• Observability: Task tracking and persistence using SQLite.

┌─────────────────────────────────────────────────────────────────────────┐
│                           MCP CLIENTS                                    │
│              (Claude Desktop, mcp-remote, CLI call)                      │
└─────────────────────────────────┬───────────────────────────────────────┘
                                  │ HTTP POST /mcp
                                  ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                         FastMCP SERVER                                   │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                      MCP TOOLS                                    │  │
│  • run_browser_agent    • skill_list/get/delete                    │  │
│  • run_deep_research    • health_check/task_list/task_get          │  │
│  └──────────────────────────────────────────────────────────────────┘   │
└────────┬──────────────┬─────────────────┬────────────────┬──────────────┘
         │              │                 │                │
         ▼              ▼                 ▼                ▼
┌─────────────┐  ┌─────────────┐  ┌─────────────────┐  ┌─────────────────────┐
│   CONFIG    │  │  PROVIDERS  │  │     SKILLS      │  │    OBSERVABILITY    │
│  Pydantic   │  │ 12 LLMs     │  │  Learn+Run      │  │   Task Tracking     │
└─────────────┘  └─────────────┘  └─────────────────┘  └─────────────────────┘
                                         │
                                         ▼
                              ┌─────────────────────────┐
                              │      browser-use        │
                              │   (Agent + Playwright)  │
                              └─────────────────────────┘

To report progress from internal classes (like a ResearchMachine) to the MCP client, pass the Progress object into the class constructor. Use an internal helper method to safely report updates.

Key patterns:

• Use Optional["Progress"] for type hints to avoid circular imports.
• Always check if not self.progress: before attempting to report.
• Use methods like set_total, set_message, and increment to update the client.

class ResearchMachine:
    def __init__(self, ..., progress: Optional["Progress"] = None):
        self.progress = progress

    async def _report_progress(self, message: Optional[str] = None, increment: bool = False, total: Optional[int] = None) -> None:
        if not self.progress:
            return
        if total is not None:
            await self.progress.set_total(total)
        if message:
            await self.progress.set_message(message)
        if increment:
            await self.progress.increment()

When implementing tools using FastMCP to support background execution and progress reporting, follow these mandatory patterns:

1. Context Injection: Use CurrentContext() as the default value for the context parameter, not Context().
2. Progress Injection: Use Progress() as the default value for the progress parameter, not None.
3. Task Configuration: Use TaskConfig(mode="optional") in the @server.tool decorator to allow the tool to run both synchronously and as a background task.
4. Progress Safety: Always check if progress: before calling any progress methods (e.g., set_total, set_message, increment), as it may be a no-op if the client didn't request it.

@server.tool(task=TaskConfig(mode="optional"))
async def my_tool(
    arg: str,
    ctx: Context = CurrentContext(),
    progress: Progress = Progress(),
) -> str:
    if progress:
        await progress.set_message("Working...")
    # ... logic ...
    return "Done"