-
Notifications
You must be signed in to change notification settings - Fork 1.7k
feat(integrations): add Cursor SDK integration #2771
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
antonvishal
wants to merge
8
commits into
browserbase:main
Choose a base branch
from
antonvishal:cursor-sdk-integration
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
8 commits
Select commit
Hold shift + click to select a range
a066595
feat(integrations): add Cursor SDK integration and docs
antonvishal 1754fc8
fix(integrations): improve cursor integration documentation and error…
antonvishal 76592a5
docs(integrations): add Cursor CLI guide
antonvishal 4eb88f8
fix(integrations): preserve Cursor CLI signal exits
antonvishal 58ca109
docs(integrations): use current Cursor agent CLI
antonvishal 0e9c705
test(integrations): cover Cursor CLI failures
antonvishal f5bd5e7
Merge origin/main into cursor-sdk-integration
antonvishal cc809c0
docs(integrations): list cursor in the package overview
antonvishal File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,101 @@ | ||
| --- | ||
| title: "Cursor" | ||
| description: "Give a local Cursor SDK agent persistent Stagehand browser tools over MCP/stdio." | ||
| --- | ||
|
|
||
| The Cursor integration creates a local agent through `@cursor/sdk` and mounts the Stagehand facade as one MCP/stdio server. One Cursor agent and one facade process own the browser across `run`, `snapshot`, and `screenshot` calls, preserving page state and snapshot IDs. | ||
|
|
||
| <Note> | ||
| Stagehand ships this experimental integration from the repository rather than publishing it as a standalone adapter. | ||
| </Note> | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| - Node.js 24 or newer | ||
| - pnpm 11.10.0 | ||
| - A Cursor user or service-account API key | ||
| - A current Google Chrome installation for local browser mode | ||
|
|
||
| ## Quickstart | ||
|
|
||
| <Steps> | ||
| <Step title="Clone and build Stagehand"> | ||
| ```bash | ||
| git clone https://github.com/browserbase/stagehand.git | ||
| cd stagehand | ||
| pnpm install --frozen-lockfile | ||
| pnpm exec turbo run build \ | ||
| --filter @browserbasehq/stagehand-integrations | ||
| ``` | ||
| </Step> | ||
| <Step title="Authenticate Cursor"> | ||
| Create a user API key in the Cursor dashboard or a service-account key in your team settings, then export it: | ||
|
|
||
| ```bash | ||
| export CURSOR_API_KEY="your-cursor-api-key" | ||
| ``` | ||
|
|
||
| The example uses `composer-2.5` by default. Set `CURSOR_STAGEHAND_MODEL` to another model ID available to your Cursor account when needed. | ||
| </Step> | ||
| <Step title="Choose the browser"> | ||
| The example defaults to Browserbase when `BROWSERBASE_API_KEY` is set, otherwise it uses local Chrome: | ||
|
|
||
| ```bash | ||
| export STAGEHAND_BROWSER="browserbase" | ||
| export BROWSERBASE_API_KEY="your-browserbase-api-key" | ||
| ``` | ||
| </Step> | ||
| <Step title="Run a browser task"> | ||
| ```bash | ||
| pnpm --dir packages/integrations/cursor start -- \ | ||
| "Open https://example.com, snapshot it, and report the heading." | ||
| ``` | ||
| </Step> | ||
| </Steps> | ||
|
|
||
| ## Configuration | ||
|
|
||
| | Variable | Purpose | | ||
| | --- | --- | | ||
| | `CURSOR_API_KEY` | Cursor user or service-account key. The example does not forward it to the MCP child. | | ||
| | `CURSOR_STAGEHAND_MODEL` | Optional Cursor model ID; defaults to `composer-2.5`. | | ||
| | `STAGEHAND_BROWSER` | Select `local` or `browserbase`. Defaults to Browserbase when `BROWSERBASE_API_KEY` is set, otherwise local. | | ||
| | `BROWSERBASE_API_KEY` | Required for Browserbase. | | ||
| | `BROWSERBASE_PROJECT_ID` | Optional Browserbase project ID. | | ||
| | `STAGEHAND_MODEL_NAME` | Optional model for Stagehand AI methods called inside `run`. | | ||
| | `STAGEHAND_MODEL_API_KEY` | Required with `STAGEHAND_MODEL_NAME`. | | ||
|
|
||
| ## SDK and session lifecycle | ||
|
|
||
| This V1 integration uses Cursor's local runtime. The agent loop and temporary workspace run locally, while Cursor hosts model inference. Cursor Cloud requires a remotely reachable MCP server and is not part of this example. | ||
|
|
||
| The example creates an isolated temporary workspace, disables ambient Cursor setting sources, and enables only Cursor's `mcp` capability group. Its only inline server is the Stagehand facade, so the model receives `run`, `snapshot`, and `screenshot` without shell, file-editing, user MCP, or project MCP tools. The example prefixes the canonical Stagehand tool instructions to the task because the main Cursor agent API does not expose a separate system-prompt option. | ||
|
|
||
| The facade process remains attached to one Cursor agent for the full run. On completion or failure, the example disposes the agent and deletes its temporary workspace. `SIGINT` and `SIGTERM` first cancel the active run so in-flight MCP calls stop cleanly. | ||
|
|
||
| Only non-empty `STAGEHAND_*` and `BROWSERBASE_*` variables cross into the MCP child. The Cursor API key and unrelated host secrets remain in the agent process. | ||
|
|
||
| ## Connect a running Cursor CLI | ||
|
|
||
| The package ships a project-scoped `.cursor/mcp.json` that mounts the Stagehand facade MCP server in the Cursor CLI. Its `args` path is relative to the package, so start the CLI from that directory: | ||
|
|
||
| ```bash | ||
| cd packages/integrations/cursor | ||
| agent mcp list | ||
| agent mcp list-tools stagehand | ||
| agent | ||
| ``` | ||
|
|
||
| Cursor inherits your shell environment, so the exports above are the only configuration. For a headless one-shot run, approve the configured MCP server so tool calls do not wait for an interactive prompt: | ||
|
|
||
| ```bash | ||
| agent -p --approve-mcps "your instruction" | ||
| ``` | ||
|
|
||
| <Warning> | ||
| `run` executes model-authored JavaScript in the browser. Use Browserbase for untrusted tasks and review the [integration security boundary](/v4/integrations/overview#security-boundary). | ||
| </Warning> | ||
|
|
||
| <Card title="Cursor integration source" icon="github" href="https://github.com/browserbase/stagehand/tree/main/packages/integrations/cursor"> | ||
| Read the isolated Cursor agent setup, MCP mount, lifecycle handling, and unit tests. | ||
| </Card> |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| { | ||
| "mcpServers": { | ||
| "stagehand": { | ||
| "command": "node", | ||
| "args": ["../core/dist/facade/stdio-server.mjs"] | ||
| } | ||
| } | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,87 @@ | ||
| # Cursor SDK + Stagehand facade over MCP/stdio | ||
|
|
||
| A runnable example embedding Cursor through `@cursor/sdk`, with the Stagehand facade | ||
| (`run` / `snapshot` / `screenshot`) mounted as the local agent's only MCP server. One Cursor | ||
| agent and one facade process stay alive for the full task, so browser state and snapshot IDs | ||
| survive across tool calls. | ||
|
|
||
| ## Setup | ||
|
|
||
| Use Node.js 24 or later. From the repository root, install dependencies and build the shared | ||
| integration package: | ||
|
|
||
| ```bash | ||
| pnpm install | ||
|
antonvishal marked this conversation as resolved.
|
||
| pnpm exec turbo run build --filter @browserbasehq/stagehand-integrations | ||
| ``` | ||
|
|
||
| Export a Cursor user or service-account API key. Browserbase is the recommended browser backend | ||
| for untrusted tasks: | ||
|
|
||
| ```bash | ||
| export CURSOR_API_KEY=key_... | ||
| export BROWSERBASE_API_KEY=bb_live_... | ||
| export BROWSERBASE_PROJECT_ID=... | ||
| ``` | ||
|
|
||
| ## Run | ||
|
|
||
| With local Chrome: | ||
|
|
||
| ```bash | ||
| STAGEHAND_BROWSER=local pnpm --dir packages/integrations/cursor start -- \ | ||
| "Open https://example.com, snapshot it, and report the heading." | ||
| ``` | ||
|
|
||
| With Browserbase: | ||
|
|
||
| ```bash | ||
| STAGEHAND_BROWSER=browserbase pnpm --dir packages/integrations/cursor start -- \ | ||
| "Open https://example.com, take a screenshot, and report the page title." | ||
| ``` | ||
|
|
||
| | Variable | Purpose | | ||
| | ------------------------- | -------------------------------------------------------------------------------------------- | | ||
| | `CURSOR_API_KEY` | Cursor user or service-account key. Never forwarded to the browser process. | | ||
| | `CURSOR_STAGEHAND_MODEL` | Optional Cursor model ID. Defaults to `composer-2.5`. | | ||
| | `STAGEHAND_BROWSER` | Browser backend. Defaults to Browserbase when `BROWSERBASE_API_KEY` is set, otherwise local. | | ||
| | `BROWSERBASE_API_KEY` | Browserbase credential for the browser session. | | ||
| | `BROWSERBASE_PROJECT_ID` | Optional Browserbase project. | | ||
| | `STAGEHAND_MODEL_NAME` | Optional model for Stagehand AI methods called inside `run`. | | ||
| | `STAGEHAND_MODEL_API_KEY` | Credential for `STAGEHAND_MODEL_NAME`. | | ||
|
|
||
| This example intentionally uses Cursor's local agent runtime. "Local" means the agent loop and | ||
| workspace run on your machine; model inference remains hosted by Cursor. The temporary workspace | ||
| loads no ambient Cursor settings, and the agent's built-in tool allowlist contains only the `mcp` | ||
| capability. Its one inline MCP server is the Stagehand facade, so Cursor does not offer shell and | ||
| file-editing tools to the model. | ||
|
|
||
| The MCP child receives only non-empty `STAGEHAND_*` and `BROWSERBASE_*` variables. The Cursor API | ||
| key and unrelated host secrets remain in the agent process. `SIGINT` and `SIGTERM` cancel the | ||
| active Cursor run before the agent, MCP process, and temporary workspace are cleaned up. | ||
|
|
||
| ## Connecting a running Cursor CLI instead | ||
|
|
||
| To use the facade from the interactive `agent` CLI rather than the SDK, the project-scoped | ||
| `.cursor/mcp.json` in this directory is all that's needed. Cursor automatically discovers it and | ||
| inherits the Stagehand and Browserbase exports above. Start the CLI from this directory: | ||
|
|
||
| ```bash | ||
| cd packages/integrations/cursor | ||
| agent mcp list | ||
| agent mcp list-tools stagehand | ||
| agent | ||
| ``` | ||
|
|
||
| For a headless one-shot run, approve the configured MCP server so tool calls do not wait for an | ||
| interactive prompt: | ||
|
|
||
| ```bash | ||
| agent -p --approve-mcps "your instruction" | ||
| ``` | ||
|
|
||
| ## Security model | ||
|
|
||
| The `run` tool executes model-authored JavaScript inside the Stagehand browser extension's service | ||
| worker, not in the Cursor agent process. Browserbase is the recommended isolation boundary: the | ||
| privileged execution environment is a disposable cloud browser. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,24 @@ | ||
| { | ||
| "name": "@browserbasehq/stagehand-integrations-example-cursor-facade", | ||
| "version": "4.0.1", | ||
| "private": true, | ||
| "type": "module", | ||
| "scripts": { | ||
| "start": "node src/agent.ts", | ||
| "test": "pnpm -w exec turbo run build --filter @browserbasehq/stagehand-integrations && vitest run", | ||
| "test:unit": "vitest run", | ||
| "typecheck": "tsc --noEmit" | ||
| }, | ||
| "dependencies": { | ||
| "@browserbasehq/stagehand-integrations": "workspace:*", | ||
| "@cursor/sdk": "catalog:" | ||
| }, | ||
| "devDependencies": { | ||
| "@types/node": "catalog:", | ||
| "typescript": "catalog:", | ||
| "vitest": "catalog:" | ||
| }, | ||
| "engines": { | ||
| "node": ">=24" | ||
| } | ||
| } |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.