[STG-2487] feat: static multi-marketplace manifest catalog (browse-only, CLI-only)

[shrey150]

What

Repurposes browserbase/browse-plugin into the dedicated, static (no-codebase) repo that external agent marketplaces SHA-pin. Ships only the browse plugin, in all 5 marketplace formats, CLI-only — a browse CLI skill that shells out via Bash/run_shell_command, no bundled MCP server.

Added — root marketplace manifests (one per format)

File	Format
.claude-plugin/marketplace.json	Claude Code marketplace
.codex-plugin/plugin.json	Codex plugin
.cursor-plugin/marketplace.json	Cursor marketplace (browse-only)
.agents/plugins/marketplace.json	Generic .agents marketplace
.grok-plugin/plugin.json	Grok plugin
gemini-extension.json + GEMINI.md	Gemini CLI extension (context-file skill, no MCP)

Added — per-plugin manifests under plugins/browse/

.claude-plugin/, .codex-plugin/, .cursor-plugin/, .grok-plugin/ plugin.json each referencing ./skills/ and assets/logo.svg. The canonical browse CLI SKILL.md (copied from stagehand/packages/cli/skills/browse/) lands at skills/browse/SKILL.md (repo root, post-flatten) with its name/description frontmatter intact.

SKILL.md freshness

There's no auto-sync yet (stagehand#2330 is still a draft proposal), so skills/browse/SKILL.md is a manual, point-in-time copy of stagehand/packages/cli/skills/browse/SKILL.md. Refreshed once more (2026-07-09) to pull in container/CI --remote guidance, BROWSE_SESSION precedence, and the named-contexts surface (cloud contexts create --name) that had shipped in browse@0.9.1+ but wasn't in this repo's earlier copy. Re-sync by hand until the auto-sync PR lands.

browse@0.9.5 published the same day (npm + ghcr.io/browserbase/browse) — diffed this repo's skills/browse/SKILL.md against stagehand's origin/main copy after that release and they're byte-identical, so this file matches what npm i -g browse actually installs today, not a bleeding-edge main that's ahead of the published package.

Removed — the de-Playwright, and (later) the de-MCP

Deleted the custom TypeScript MCP server and all app code (plugins/browse/{src,scripts,agent,package.json,package-lock.json,tsconfig.json}, plugins/browse/skills/browser-automation/, plugins/browse/rules/, plugins/functions/). Then, after live-testing the hosted-MCP wiring (see "Why CLI-only" below), removed it too: mcpServers stripped from every plugin.json, .mcp.json (root + per-plugin) and server.json deleted, gemini-extension.json rewritten to a plain CLI-context extension. Net across both changes: +926 / −3932.

Why CLI-only, not MCP

The plugin originally bundled both a CLI-shelling skill and a hosted-MCP reference (.mcp.json → https://mcp.browserbase.com/mcp) side by side, letting the agent pick either at runtime. Live-testing that MCP path (real marketplace installs, real headless invocations — not just schema validators) found it's currently broken for every client, and not fixable within this PR's scope:

• Every manifest shipped a bare URL with zero auth — no Authorization: Bearer, no x-bb-api-key header, no ?browserbaseApiKey= query param.
• The hosted MCP server accepts all three of those, but requires one for actual tool execution (initialize/tools/list are unauthenticated by design; start/navigate/etc. are not). With none supplied, every real tool call was rejected: {"jsonrpc":"2.0","error":{"code":-32000,"message":"Invalid query parameters"}}. Confirmed independently through two different real clients (Claude Code, Gemini CLI) — same error, same root cause both times.
• Full OAuth 2.1 — which would let each user authenticate without a manifest ever holding a secret — isn't deployed: live-checked https://mcp.browserbase.com/.well-known/oauth-protected-resource and oauth-authorization-server, both 404; zero oauth/authorize|token|register routes exist anywhere in browserbase/core's origin/main.
• This repo is a static, git-pinned, public catalog every external marketplace SHA-pins — there's no safe way to embed a real Browserbase API key in it, and no field in most of these manifest formats for a user to supply their own per-install.

Given that, and that this audience already has shell access (Claude Code, Codex, Cursor, Gemini CLI, Grok all run with a sandbox), a bundled MCP server adds no reach for these clients while introducing a broken/confusing fallback path — in testing, the agent would sometimes pick the (broken) MCP tool over the (working) CLI skill when both were present. CLI-only removes that ambiguity and matches what's actually proven to work. The hosted MCP remains the right integration for shell-less surfaces (ChatGPT, claude.ai) — that's a separate initiative, gated on OAuth for those specific directories, tracked outside this PR.

E2E Test Matrix

Manifest validators (all formats, run against this branch)

Command / flow	Observed output	Confidence / sufficiency
node scripts/validate-template.mjs	Validation passed. (exit 0) + 2 benign warnings: no hooks/hooks.json, no mcp.json (expected now — CLI-only)	Sufficient — Cursor marketplace name kebab-case, owner.name set, non-empty plugins[], source-dir/name match, referenced logo/skills paths + SKILL.md frontmatter all exist. Re-ran clean after the 2026-07-09 SKILL.md refresh.
claude plugin validate . / claude plugin validate . --strict	✔ Validation passed (both)	Sufficient — Claude Code marketplace manifest valid, strict clean.
claude plugin validate plugins/browse / ... --strict	✔ Validation passed (both)	Sufficient — per-plugin manifest valid strict.
gemini extensions validate .	Extension . has been successfully validated.	Sufficient — Gemini CLI accepts the CLI-only extension shape.
codex plugin marketplace add <abs> → codex plugin list → remove	add/list/remove all succeeded, browse@browserbase-plugins resolved at plugins/browse	Sufficient — registration path works.
Grok: catalog validator + index generator (run in the xAI plugin-marketplace clone)	Catalog OK, generated browse entry resolves skills: [{browse, ...}], no mcpServers key	Sufficient for the SHA-pin catalog path. grok CLI itself isn't installed locally — not live-invocation-tested.
Cursor deeplink encode/decode	round-trips correctly	Sufficient for encoding correctness; not click-tested in a running Cursor instance (GUI, not automatable here).

Real install-and-invoke (live, this session — not just validators)

Client	What ran	Result
Claude Code	Real claude plugin marketplace add → install → headless claude -p task ("navigate to example.com, report the title") against the actual repo files	✅ Clean pass. claude plugin details reported MCP servers (0). Transcript shows only Skill/Bash tool calls — the model shelled out to browse open ... --local, got back "title": "Example Domain", answered correctly. Zero mcp__* calls anywhere.
Gemini CLI	Real gemini extensions install ~/Developer/browse-plugin → headless gemini --yolo task, same prompt	✅ Clean pass. Extension shows a Context file (GEMINI.md), no MCP servers. Two run_shell_command calls (browse open ... --local, browse stop), correct answer, zero MCP calls.
Codex	Real codex plugin marketplace add → codex plugin add → headless codex exec, same prompt	⚠️ Partial. Registration and install verified clean (browse@browserbase-plugins installed/enabled). Invocation blocked by this machine's local codex login having an expired OpenAI API key (401 invalid_api_key) — an environment issue unrelated to the plugin; the turn never started so no tool call was attempted. Needs a valid local Codex login to complete.

All three live tests ran against the real, post-change repo files (not scratch copies), with full install → invoke → cleanup, and confirmed the working tree was left unmodified by testing.

Not proven / left for review

• Cursor and Grok are validator/encoding-verified only — no live click-test in a running Cursor instance, and no live grok CLI invocation (not installed locally).
• Codex tool-invocation is unproven on this machine specifically due to a local auth issue, not a plugin defect — worth a quick re-run once codex login is refreshed.

🤖 Generated with Claude Code

---

Note

Medium Risk
Large behavioral break for installs that relied on bundled MCP/tools, though risk to production services is low because the change removes executable code rather than altering auth or data paths.

Overview
Repurposes the repo into a static, SHA-pinnable marketplace catalog with no app code: agents get JSON manifests plus skills/browse/SKILL.md (and GEMINI.md for Gemini) that teach shelling out to the global browse CLI instead of bundling Playwright, TypeScript, or an MCP server.

Layout and packaging: Drops nested plugins/browse/ and the entire plugins/functions/ plugin. Repo root is now the plugin (source: "."), with new/updated manifests for Claude, Codex, Cursor, .agents, Grok, and gemini-extension.json. Cursor marketplace lists only browse.

Removed runtime: Deletes the custom MCP server (mcp.json, plugins/browse/src/*), npm package/build (package.json, lockfile, tsconfig), MCP-oriented skills/rules, and Chrome-profile/runtime gitignore entries. Release workflow no longer runs npm ci/build—only validate-template.mjs and tarball packaging.

Docs: README and docs/add-a-plugin.md rewritten for CLI-only positioning and flat layout; adds .github/CODEOWNERS.

^{Reviewed by Cursor Bugbot for commit 17f860a. Bugbot is set up for automated code reviews on this repo. Configure here.}