Skip to content

feat(mastra): add Stagehand code-mode MCP example - #2627

Open
shrey150 wants to merge 17 commits into
shrey/stg-2765-codemode-vercelfrom
shrey/stg-2765-codemode-mastra
Open

feat(mastra): add Stagehand code-mode MCP example#2627
shrey150 wants to merge 17 commits into
shrey/stg-2765-codemode-vercelfrom
shrey/stg-2765-codemode-mastra

Conversation

@shrey150

@shrey150 shrey150 commented Aug 6, 2026

Copy link
Copy Markdown
Contributor

Why

Agent frameworks should consume the code-mode MCP through the Vercel Sandbox security boundary, not launch the browser runtime inside the outer agent process. This layer makes Mastra a thin authenticated Streamable HTTP client of the exact package-installed sandbox from #2626.

Stack

  1. #2597 — code-mode MCP host scaffold
  2. #2619code_execute, executor, configuration, and runtime tests
  3. #2620 — canonical skill, reference, generated exports, and loading checks
  4. #2644 — publishable @browserbasehq/stagehand-codemode package
  5. #2626 — exact package artifacts installed behind the Vercel Sandbox boundary
  6. This PR — Mastra remote MCP adapter and live proof
  7. #2628 — CrewAI adapter and proof
  8. #2629 — LangChain adapter and proof

What changed

  • merges the current feat: run code-mode MCP in Vercel Sandbox #2626 parent without rewriting the public stack
  • replaces Mastra's local stdio child with its native remote MCP client
  • injects the per-sandbox bearer token only into requests to the sandbox MCP URL
  • discovers exactly code_execute and uses its canonical description as agent instructions
  • keeps one Mastra MCP client and browser session alive across direct and model-driven calls
  • keeps OPENAI_API_KEY in the outer process; the sandbox receives only its explicit Browserbase configuration
  • disconnects Mastra before stopping and deleting the sandbox
  • adds a live package-backed CI proof

Proof matrix

Command / flow Result / assertion
pnpm --filter @browserbasehq/stagehand-integrations-example-mastra typecheck Passed against @mastra/core@1.56.0 and @mastra/mcp@1.15.1.
pnpm check Passed all 9 formatting, lint, and typecheck tasks.
Vercel artifact pack Passed for the exact Stagehand and code-mode tarballs plus locked runtime manifest.
Direct Mastra MCP calls CI calls code_execute twice and requires the same page ID and DOM marker.
Real Mastra model call CI requires a real model to select code_execute, modify the existing page, and exposes the selected tool call in Mastra's step trace.
Independent post-model read A direct third call must observe the model's marker on the same page.
Credential isolation Sandbox code must observe neither OPENAI_API_KEY nor a Mastra host-only marker.
Cleanup PASS is emitted only after Mastra disconnects, then the Vercel Sandbox stops and deletes.

Changeset

None. This remains a private integration example.

@changeset-bot

changeset-bot Bot commented Aug 6, 2026

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: 288f4da

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@shrey150 shrey150 closed this Aug 6, 2026
@shrey150 shrey150 reopened this Aug 6, 2026

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

1 issue found and verified against the latest diff

Confidence score: 5/5

  • In packages/integrations/examples/mastra/package.json, an unused @browserbasehq/stagehand-integrations dependency can cause confusion about required setup and add avoidable install/maintenance overhead for this example—either remove it or add the intended import usage to keep the example aligned with examples/vercel.
Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/integrations/examples/mastra/package.json">

<violation number="1" location="packages/integrations/examples/mastra/package.json:11">
P3: The `@browserbasehq/stagehand-integrations` dependency is declared here but never imported anywhere in this example. Unlike the sibling `examples/vercel` package (whose `agent.ts` does `import ... from "@browserbasehq/stagehand-integrations/..."`), the Mastra example launches the already-built stdio server by direct file URL (`../../../dist/codemode/stdio-server.mjs`) and only imports `@mastra/core` and `@mastra/mcp`. This `workspace:*` entry is therefore unused at runtime and only pins a package that is not referenced. If it's kept to document the build dependency on the integrations dist output, a comment would help, but as-is it reads as a dead dependency.</violation>
</file>

Reply with feedback, questions, or to request a fix.

Re-trigger cubic

Comment thread packages/integrations/examples/mastra/src/smoke.ts Outdated
Comment thread .github/workflows/codemode-framework-examples.yml
"typecheck": "tsc --noEmit"
},
"dependencies": {
"@browserbasehq/stagehand-integrations": "workspace:*",

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: The @browserbasehq/stagehand-integrations dependency is declared here but never imported anywhere in this example. Unlike the sibling examples/vercel package (whose agent.ts does import ... from "@browserbasehq/stagehand-integrations/..."), the Mastra example launches the already-built stdio server by direct file URL (../../../dist/codemode/stdio-server.mjs) and only imports @mastra/core and @mastra/mcp. This workspace:* entry is therefore unused at runtime and only pins a package that is not referenced. If it's kept to document the build dependency on the integrations dist output, a comment would help, but as-is it reads as a dead dependency.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At packages/integrations/examples/mastra/package.json, line 11:

<comment>The `@browserbasehq/stagehand-integrations` dependency is declared here but never imported anywhere in this example. Unlike the sibling `examples/vercel` package (whose `agent.ts` does `import ... from "@browserbasehq/stagehand-integrations/..."`), the Mastra example launches the already-built stdio server by direct file URL (`../../../dist/codemode/stdio-server.mjs`) and only imports `@mastra/core` and `@mastra/mcp`. This `workspace:*` entry is therefore unused at runtime and only pins a package that is not referenced. If it's kept to document the build dependency on the integrations dist output, a comment would help, but as-is it reads as a dead dependency.</comment>

<file context>
@@ -0,0 +1,23 @@
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@browserbasehq/stagehand-integrations": "workspace:*",
+    "@mastra/core": "catalog:",
+    "@mastra/mcp": "catalog:"
</file context>

Comment thread packages/integrations/examples/mastra/src/agent.ts Outdated
…into shrey/stg-2765-codemode-mastra

# Conflicts:
#	.github/workflows/codemode-framework-examples.yml
#	packages/integrations/README.md
#	pnpm-lock.yaml
#	pnpm-workspace.yaml
@socket-security

socket-security Bot commented Aug 8, 2026

Copy link
Copy Markdown

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff Package Supply Chain
Security
Vulnerability Quality Maintenance License
Addednpm/​@​mastra/​core@​1.56.06610093100100
Addednpm/​@​mastra/​mcp@​1.15.1981008310080

View full report

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 6 files (changes from recent commits).

Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic

Comment thread packages/integrations/examples/mastra/src/e2e.ts Outdated
Comment thread packages/integrations/examples/mastra/src/agent.ts
Comment thread packages/integrations/examples/mastra/src/agent.ts Outdated

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 5 files (changes from recent commits).

Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic

Comment thread packages/integrations/examples/mastra/src/agent.test.ts
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant