feat(integrations): add Cursor SDK integration
Closed
AN
2mo ago+983+983+012345678901234567890123456789-143-143-012345678901234567890123456789
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/sdkintegration using Cursor's local runtime. - Mounts the Stagehand facade as the only enabled MCP tool surface.
- Preserves one browser session across
run,snapshot, andscreenshot. - Uses an isolated temporary workspace and disables ambient Cursor settings.
- Forwards only
STAGEHAND_*andBROWSERBASE_*variables to the MCP child. - Cancels active runs on
SIGINTandSIGTERMand 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.jsonso theagentCLI 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 forwardsCURSOR_API_KEY. - Keeps one browser session for the full run; defaults the model to
composer-2.5(override withCURSOR_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.