feat: upgrade stagehand to v3 (#128)

* feat: upgrade stagehand to v3

* pnpm lockfile

* changesets

* remove playwright fully + update mcpvals version

* testing package moved to dev deps

* pnpm lockfile

* readme changes + remove cookies from options

Author: Kylejeong2

CHANGELOG.md

@@ -1,5 +1,11 @@
 # @browserbasehq/mcp-server-browserbase
 
+## 2.3.0
+
+### Minor Changes
+
+- upgrade to stagehand v3
+
 ## 2.2.0
 
 ### Minor Changes

README.md

@@ -8,6 +8,20 @@
 
 This server provides cloud browser automation capabilities using [Browserbase](https://www.browserbase.com/) and [Stagehand](https://github.com/browserbase/stagehand). It enables LLMs to interact with web pages, take screenshots, extract information, and perform automated actions with atomic precision.
 
+## What's New in Stagehand v3
+
+Powered by [Stagehand v3.0](https://github.com/browserbase/stagehand), this MCP server now includes:
+
+- **20-40% Faster Performance**: Speed improvements across all core operations (`act`, `extract`, `observe`) through automatic caching
+- **Enhanced Extraction**: Targeted extraction and observation across iframes and shadow roots
+- **Improved Schemas**: Streamlined extract schemas for more intuitive data extraction
+- **Advanced Selector Support**: CSS selector support with improved element targeting
+- **Multi-Browser Support**: Compatible with Playwright, Puppeteer, and Patchright
+- **New Primitives**: Built-in `page`, `locator`, `frameLocator`, and `deepLocator` for simplified automation
+- **Experimental Features**: Enable cutting-edge capabilities with the `--experimental` flag
+
+For more details, visit the [Stagehand v3 documentation](https://docs.stagehand.dev/).
+
 ## Features
 
 | Feature            | Description                                                 |
@@ -19,6 +33,8 @@ This server provides cloud browser automation capabilities using [Browserbase](h
 | Model Flexibility  | Supports multiple models (OpenAI, Claude, Gemini, and more) |
 | Vision Support     | Use annotated screenshots for complex DOMs                  |
 | Session Management | Create, manage, and close browser sessions                  |
+| High Performance   | 20-40% faster operations with automatic caching (v3)        |
+| Advanced Selectors | Enhanced CSS selector support for precise element targeting |
 
 ## How to Setup
 
@@ -190,7 +206,6 @@ The Browserbase MCP server accepts the following command-line flags:
 | `--persist`                | Whether to persist the Browserbase context (default: true)                  |
 | `--port <port>`            | Port to listen on for HTTP/SHTTP transport                                  |
 | `--host <host>`            | Host to bind server to (default: localhost, use 0.0.0.0 for all interfaces) |
-| `--cookies [json]`         | JSON array of cookies to inject into the browser                            |
 | `--browserWidth <width>`   | Browser viewport width (default: 1024)                                      |
 | `--browserHeight <height>` | Browser viewport height (default: 768)                                      |
 | `--modelName <model>`      | The model to use for Stagehand (default: gemini-2.0-flash)                  |
@@ -343,6 +358,30 @@ Here's how to use it for custom browser sizing. We recommend to stick with 16:9
 }
 ```
 
+### Experimental Features
+
+Stagehand v3 includes experimental features that can be enabled with the `--experimental` flag. These features provide cutting-edge capabilities that are actively being developed and refined.
+
+To enable experimental features:
+
+```json
+{
+  "mcpServers": {
+    "browserbase": {
+      "command": "npx",
+      "args": ["@browserbasehq/mcp-server-browserbase", "--experimental"],
+      "env": {
+        "BROWSERBASE_API_KEY": "",
+        "BROWSERBASE_PROJECT_ID": "",
+        "GEMINI_API_KEY": ""
+      }
+    }
+  }
+}
+```
+
+_Note: Experimental features may change or be removed in future releases. Use them at your own discretion._
+
 ### Model Configuration
 
 Stagehand defaults to using Google's Gemini 2.0 Flash model, but you can configure it to use other models like GPT-4o, Claude, or other providers.
@@ -359,7 +398,7 @@ Here's how to configure different models:
       "args": [
         "@browserbasehq/mcp-server-browserbase",
         "--modelName",
-        "anthropic/claude-3-5-sonnet-latest",
+        "anthropic/claude-sonnet-4.5",
         "--modelApiKey",
         "your-anthropic-api-key"
       ],

config.d.ts

@@ -1,4 +1,3 @@
-import type { Cookie } from "playwright-core";
 import type { AvailableModelSchema } from "@browserbasehq/stagehand";
 
 export type Config = {
@@ -59,11 +58,6 @@ export type Config = {
      */
     browserHeight?: number;
   };
-  /**
-   * Cookies to inject into the Browserbase context
-   * Format: Array of cookie objects with name, value, domain, and optional path, expires, httpOnly, secure, sameSite
-   */
-  cookies?: Cookie[];
   /**
    * Server configuration for MCP transport layer
    *

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@browserbasehq/mcp-server-browserbase",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "MCP server for AI web browser automation using Browserbase and Stagehand",
   "mcpName": "io.github.browserbase/mcp-server-browserbase",
   "license": "Apache-2.0",
@@ -46,12 +46,11 @@
   },
   "dependencies": {
     "@browserbasehq/sdk": "^2.6.0",
-    "@browserbasehq/stagehand": "^2.5.2",
+    "@browserbasehq/stagehand": "^3.0.1",
     "@mcp-ui/server": "^5.10.0",
     "@modelcontextprotocol/sdk": "^1.13.1",
     "commander": "^14.0.0",
     "dotenv": "^16.4.6",
-    "mcpvals": "^0.0.3",
     "zod": "^3.25.67"
   },
   "devDependencies": {
@@ -64,7 +63,7 @@
     "globals": "^16.2.0",
     "husky": "^9.1.7",
     "lint-staged": "^16.1.2",
-    "playwright-core": "^1.53.2",
+    "mcpvals": "^0.4.0",
     "prettier": "^3.6.1",
     "shx": "^0.3.4",
     "tsx": "^4.20.3",