An external Cloudflare Worker injects browser-native WebMCP tools into the AgentBridge storefront without changing its Next.js source. The Worker receives browser traffic, proxies it to the configured origin, and adds the browser bridge only to HTML responses.
Agents need stable semantic capabilities, not fragile click paths, while the origin must retain its existing authorization and commerce controls.
The Worker injects the constrained runtime bridge, which calls the origin's existing same-origin APIs using the browser's authenticated session.
This repository is an API Adapter. It transforms approved AgentBridge REST capabilities into browser-native WebMCP tools; it is not a UI or browser-automation adapter.
Agent
↑
WebMCP tools
↑
External API Adapter — fetch() with credentials: "include"
↑
AgentBridge Website REST API
The companion AgentBridge storefront repository is the origin application. It exposes the /api/* routes and owns all business logic, authentication, and database access. This adapter calls those routes from the browser; it does not automate the website UI, access Neon directly, or bypass origin authorization. Playwright is used only for E2E validation.
The original adapter design described 18 tools, including checkout. The deployed safe implementation exposes 17 tools because real-order checkout is intentionally omitted until the origin offers an isolated sandbox.
WebMCP lets a website expose tools to a browser-resident AI agent through document.modelContext.
Structured tools reduce ambiguous UI navigation and make errors, IDs, and state transitions explicit.
┌──────────────┐ HTTPS ┌──────────────────────────────┐
│ User / Agent │ ───────────► │ Cloudflare Worker │
│ in Chromium │ │ worker/index.ts │
└──────┬───────┘ │ • proxies to origin │
│ │ • injects bridge-v2.js │
│ WebMCP tools └──────────────┬───────────────┘
▼ │ proxied HTTPS
┌──────────────┐ ▼
│ document. │ ┌──────────────────────────┐
│ modelContext │◄─ bridge-v2.js ─►│ AgentBridge Next.js app │
└──────┬───────┘ │ /api → services → Prisma │
│ tool call │ → Neon PostgreSQL │
└──────────────────────────►└──────────────────────────┘
Connection details are defined in wrangler.toml: AGENTBRIDGE_ORIGIN is the storefront target, worker/index.ts injects the bridge asset, and bridge-v2.js registers tools with the browser. See the fuller architecture document.
- The browser opens the Worker URL or a Cloudflare route mapped to that Worker.
- The Worker fetches the configured origin and injects
/__agentbridge-webmcp/bridge-v2.jsinto HTML. - The bridge calls
document.modelContext.registerToolfor permitted capabilities. - The agent discovers a schema, invokes a tool with JSON arguments, and the bridge calls
/api/*on the Worker origin. - The Worker proxies the API request to the storefront; the storefront still performs authentication, validation, stock, ownership, and business-rule checks.
- The structured API result returns through the bridge to the agent; a state change is then visible in the website UI.
The deployment evidence shows the Worker response, injected bridge-v2.js request, and protected anonymous cart request.
17 fixed tools cover catalog, cart, wishlist, orders, recommendations, and shipping. The canonical list is in src/registry/toolRegistry.ts; runtime definitions are in bridge-v2.js. Checkout is intentionally not exposed because the origin lacks an isolated payment sandbox.
The bridge calls document.modelContext.registerTool only when WebMCP exists; normal visitors are unaffected. Inspect the live Worker tool inventory endpoint and follow the browser validation guide.
Schemas use required IDs, bounded quantities, enums, and structured failures. See the audited contracts, TypeScript contract definitions, and runtime validation implementation.
Search → details; search → add to cart → inspect cart; inspect cart → remove; and shipping estimation are supported.
Public catalog tools register for every visitor. Account, cart, wishlist, and order tools register only after /api/auth/session confirms a signed-in user; cart mutation tools register only after a populated cart is detected or an add succeeds. See state model.
Failures return { success: false, error: { code, message, retryable } }; authentication, validation, and network failures are distinct.
Tool outputs include IDs and cart state needed by the next step; callers must stop when success is false.
Retry temporary errors only; ask the user to log in for authentication and correct invalid IDs. See failure modes.
Separate deterministic contract tests, runtime bridge tests, browser E2E, and probabilistic LLM evaluation.
npm test and npm run test:webmcp test registry/schemas, invalid inputs, cart-aware registration, and structured failures. See final validation for the recorded result.
npm run eval:webmcp uses a configured Responses API provider and repeats generic cases. It does not invent results without a key.
The storefront Playwright journey uses a disposable deployment and verifies tool-caused search, detail, cart add/remove, inspection, and visible UI state changes.
Browser evidence and the remaining Inspector checklist are in validation, including the versioned response screenshots.
Selection accuracy, argument accuracy, chain success, wrong-tool/argument rates, and latency are emitted to eval-results/.
Only generated evaluation output is a result. No LLM, v2-browser, or baseline metric is claimed before it is measured.
Follow the demo flow: open the Worker origin, discover tools, search, sign in with a disposable user, add a returned product ID, inspect the cart, and verify the UI.
Current response captures are Worker HTML, bridge asset, and anonymous cart protection. See the validation checklist for remaining Inspector captures.
Cloudflare Workers, TypeScript, WebMCP imperative API, Vitest, Playwright, Next.js, Prisma, and Neon PostgreSQL.
worker/— Cloudflare proxy and HTML injection.public/— browser bridge assets served by Worker Assets.src/— typed tool contracts, safety rules, and executors.tests/— deterministic registry and runtime checks.evals/— generic datasets and provider runner.docs/— audit, validation, reports, and evidence.
Run npm ci, set the origin in wrangler.toml or Cloudflare Worker variables, then deploy with npx wrangler deploy or Workers Builds. The full isolated setup is in webmcp-testing-environment.md.
Use the Worker URL below for the WebMCP demonstration:
https://agentbridge--external-webmcp-api-adapter.mmisba221373.workers.dev/
This Worker is working and proxies the Vercel-hosted storefront configured by AGENTBRIDGE_ORIGIN, injecting bridge-v2.js into HTML responses. The Worker is not currently configured to serve through the registered misba.ninja domain because that domain's Worker route registration is unresolved. Use the Worker URL above, not the Vercel website URL or misba.ninja, when testing WebMCP tool discovery and execution.
AGENTBRIDGE_ORIGIN, E2E_BASE_URL, E2E_EMAIL, E2E_PASSWORD, and optional OPENAI_API_KEY, LLM_EVAL_MODEL, LLM_EVAL_TRIALS. Never commit secrets.
Configure wrangler.toml with an origin you control, run npx wrangler dev for local proxy testing, or deploy through Cloudflare. Map a Cloudflare Worker route to the storefront domain only after confirming the Worker origin works; then verify the injected bridge request in DevTools.
For a seeded local demo origin, use customer@example.com or admin@example.com with ChangeMe123!. These are public seed credentials only; replace them for every non-demo deployment. The authoritative setup notes are in the storefront repository.
Run npm test, npm run test:webmcp, and from the storefront npm run test:e2e.
Set a provider key and run npm run eval:webmcp; JSON and Markdown results appear in ignored eval-results/.
Use the isolated environment and exact commands in testing environment.
No arbitrary HTTP capability, credentials never enter tool output, origin authorization remains authoritative, and real checkout is omitted.
Current imperative WebMCP registration cannot safely remove a tool mid-page; reload restores empty-cart exposure.
Add a payment sandbox, contract generation to eliminate bridge duplication, CI browser capture, and an equivalent browser-only baseline.
The project supplies audited browser-native tools, state/safety documentation, deterministic tests, evaluation datasets, runner, and honest evidence boundaries.
Chrome WebMCP and WebMCP evaluations.
Distributed under the MIT License.