feat(integrations): add Cursor SDK integration

Closed
AN
2mo ago
+983-143

why

Add a Cursor SDK example alongside the existing Claude Code and Codex integrations, giving local Cursor agents persistent Stagehand browser tools over MCP/stdio.

what changed

  • Adds a runnable @cursor/sdk integration using Cursor's local runtime.
  • Mounts the Stagehand facade as the only enabled MCP tool surface.
  • Preserves one browser session across run, snapshot, and screenshot.
  • Uses an isolated temporary workspace and disables ambient Cursor settings.
  • Forwards only STAGEHAND_* and BROWSERBASE_* variables to the MCP child.
  • Cancels active runs on SIGINT and SIGTERM and cleans up all temporary resources.
  • Adds unit tests, setup documentation, an integration guide, navigation, and a Cursor icon.
  • Verifies the integration with a live Browserbase smoke test.

Summary by cubic

Adds a Cursor SDK integration so local @cursor/sdk agents and the Cursor CLI can use persistent Stagehand browser tools over MCP/stdio. Previously Cursor was unsupported; now one agent and one facade share one browser across run, snapshot, and screenshot, with signal handling that preserves CLI exit signals.

  • Introduces packages/integrations/cursor (@browserbasehq/stagehand-integrations-example-cursor-facade) that launches a local Cursor agent with the Stagehand facade as the only MCP tool; ships .cursor/mcp.json so the agent CLI can mount the same facade.
  • Isolates runs in a temp workspace, disables Cursor setting sources, stores the local agent store in-workspace, and forwards only non-empty STAGEHAND_*/BROWSERBASE_* env vars to the MCP child; never forwards CURSOR_API_KEY.
  • Keeps one browser session for the full run; defaults the model to composer-2.5 (override with CURSOR_STAGEHAND_MODEL) and clarifies Browserbase vs. local Chrome selection.
  • On SIGINT/SIGTERM, cancels the active run, always cleans up the agent and workspace, surfaces explicit errors for interrupted/failed/empty-text runs, and re-emits the original signal so the CLI exits with the same signal status.
  • Adds docs: v4/integrations/cursor.mdx, overview/nav updates to include Cursor, a Cursor icon, and an entry in the integrations package README; documents CLI usage and headless approvals.
  • Adds unit tests for env allowlisting, agent options, prompt shaping, signal handling and re-raise, cleanup, error paths, and CLI failure handling.