feat(mastra): add Stagehand code-mode MCP example - #2627
Open
shrey150 wants to merge 17 commits into
Open
Conversation
|
shrey150
marked this pull request as ready for review
August 6, 2026 19:12
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
1 issue found and verified against the latest diff
Confidence score: 5/5
- In
packages/integrations/examples/mastra/package.json, an unused@browserbasehq/stagehand-integrationsdependency 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 withexamples/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
| "typecheck": "tsc --noEmit" | ||
| }, | ||
| "dependencies": { | ||
| "@browserbasehq/stagehand-integrations": "workspace:*", |
Contributor
There was a problem hiding this comment.
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>
This was referenced Aug 7, 2026
…into shrey/stg-2765-codemode-mastra # Conflicts: # .github/workflows/codemode-framework-examples.yml # packages/integrations/README.md # pnpm-lock.yaml # pnpm-workspace.yaml
|
Review the following changes in direct dependencies. Learn more about Socket for GitHub.
|
…rowserbase/stagehand into shrey/stg-2765-codemode-mastra
Contributor
There was a problem hiding this comment.
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
Contributor
There was a problem hiding this comment.
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
miguelg719
added a commit
that referenced
this pull request
Aug 9, 2026
## Why The code-mode product work spans three distinct review domains: process hosting, browser code execution, and agent guidance. This bottom PR isolates the package and Model Context Protocol (MCP) host so its build, transport, and shutdown behavior can be reviewed without the execution engine or prompt content. ## Stack 1. **This PR:** private package, MCP stdio host, lifecycle, repository build/test wiring 2. #2619: Stagehand executor, local and Browserbase configuration, schemas, queueing, and `code_execute` registration 3. #2620: `SKILL.md`, `REFERENCE.md`, generated exports, package assets, and guidance loading checks 4. [#2626](#2626) — Vercel AI SDK MCP example and smoke flows 5. [#2627](#2627) — Mastra MCP example and smoke flows 6. [#2628](#2628) — CrewAI MCP example and smoke flows 7. [#2629](#2629) — LangChain Deep Agents MCP example and smoke flows Each PR is intended to build, test, and make a truthful claim independently. ## What changed - adds the private `@browserbasehq/stagehand-integrations` workspace package - adds a compiled stdio entrypoint backed by the MCP SDK - negotiates MCP server metadata without advertising capabilities that do not exist yet - bounds concurrent shutdown cleanup to five seconds - preserves conventional process exit codes for `SIGINT` and `SIGTERM` - wires the package into workspace, Turbo, Vitest, and CI discovery ## Intentionally not included - no MCP tools - no browser or model configuration - no Stagehand executor - no skill or reference content - no published package surface; the package remains private ## E2E Test Matrix | Command / flow | Observed output | Confidence / sufficiency | | --- | --- | --- | | `pnpm --filter @browserbasehq/stagehand-integrations typecheck && pnpm --filter @browserbasehq/stagehand-integrations build && pnpm --filter @browserbasehq/stagehand-integrations test:unit` | Package typecheck and build passed; 3 test files and 9 tests passed. | Covers host construction, bounded cleanup, compiled stdio startup, end-of-file shutdown, and signal exit codes. It intentionally does not prove a tool or browser session. | | Manual MCP client connected to the compiled stdio entrypoint | `{"initialized":true,"toolsCapability":null,"readyMessage":true}` | Proves the built artifact starts as a child process, negotiates MCP, emits its readiness message, and truthfully advertises no tools. | | `pnpm exec turbo run test:unit --filter=@browserbasehq/stagehand-integrations` | 2/2 Turbo tasks passed; package build plus 9/9 tests passed. | Proves the repository task graph builds the package before compiled-child tests. | | `pnpm check` | 9/9 repository tasks passed. | Supports repository-wide formatting, lint, and type compatibility for this layer. | ## Changeset None. This introduces a private workspace package and does not publish a release. --------- Co-authored-by: miguel <miguelg71921@gmail.com>
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
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
code_execute, executor, configuration, and runtime tests@browserbasehq/stagehand-codemodepackageWhat changed
code_executeand uses its canonical description as agent instructionsOPENAI_API_KEYin the outer process; the sandbox receives only its explicit Browserbase configurationProof matrix
pnpm --filter @browserbasehq/stagehand-integrations-example-mastra typecheck@mastra/core@1.56.0and@mastra/mcp@1.15.1.pnpm checkcode_executetwice and requires the same page ID and DOM marker.code_execute, modify the existing page, and exposes the selected tool call in Mastra's step trace.OPENAI_API_KEYnor a Mastra host-only marker.Changeset
None. This remains a private integration example.