AGENTS.md

Guidance for AI agents when working with this repository.

Commands

vp install            # Install dependencies
pnpm build            # Build all packages
pnpm typecheck        # Type checking
vp check --fix        # Lint, format, and fix (Oxlint + Oxfmt)
vp check              # Check without fixing (CI)
pnpm check-all        # All checks (typecheck + lint)
pnpm test:unit        # Unit tests only
pnpm test:e2e         # E2E tests only
pnpm test:wpt         # Pinned upstream WebMCP WPT (requires Chrome Canary)
vp test run           # Run tests in current package
vp pack               # Build current library package
pnpm changeset        # Create a changeset for versioning

Structure

packages/           # All NPM packages (@mcp-b/*)
apps/               # Deployed apps (landing-page, documentation-website)
e2e/                # E2E tests and test apps
docs/               # Technical documentation
.agents/skills/     # Agent skills and their bundled references/assets
.reference/         # Upstream reference repos (gitignored, shallow clones)

Apps (apps/*)

Both apps are pnpm workspace members.

apps/landing-page — @mcp-b/landing-page

Landing page at mcp-b.ai (also www.mcp-b.ai). Astro 7 (output: 'server') deployed to Cloudflare Workers via @astrojs/cloudflare v14. Dev runs on real workerd (Vite Environment API).

• pnpm dev (wrangler types → astro dev), pnpm build (wrangler types → astro check → astro build), pnpm preview.
• Cloudflare runtime: env via import { env } from 'cloudflare:workers'; Astro.request.cf; execution context at Astro.locals.cfContext. Do NOT use Astro.locals.runtime (removed from @astrojs/cloudflare in v13, used with Astro 6).
• Secrets: npx wrangler secret put <KEY>; local secrets in .dev.vars.
• Config: astro.config.mjs, wrangler.jsonc. Excluded from root pnpm build/check-all via --filter '!@mcp-b/landing-page'.

apps/documentation-website — @mcp-b/documentation-website

WebMCP docs at docs.mcp-b.ai, built with Mintlify (its own CLI runs dev/build; Vite+ only manages its dependencies). Authored following the Diataxis framework.

• pnpm dev:docs from the root, or pnpm dev in the app dir (both run mintlify dev at http://localhost:3000). pnpm build runs mintlify validate.
• docs.json is the single source of truth for navigation. Do not modify without explicit request.
• Authoring rules (Diataxis, writing style, Mintlify components, source-of-truth boundaries) are in .agents/skills/docs-authoring/SKILL.md. Read it before writing or editing docs pages.

Key Files

Quick Reference

• Node: >= 22.18
• Package manager: pnpm (not npm/yarn)
• Toolchain: Vite+ (vp CLI) — unified dev/build/test/lint/format
• Linter: Oxlint (via vp lint / vp check)
• Formatter: Oxfmt (via vp fmt / vp check)
• Bundler: tsdown via vp pack (config in each package's vite.config.ts pack block)
• Test runner: Vitest via vp test (config in each package's vite.config.ts test block)
• Zod version: MCP SDK v2 requires Zod ^4.2 when used. Zod 3 is unsupported
• Commit format: <type>(<scope>): <subject> (enforced by hook)

Commit Scopes

Package scopes: global, mcp-iframe, react-webmcp, smart-dom-reader, transports, usewebmcp, webmcp-extension, webmcp-local-relay, webmcp-polyfill, webmcp-ts-sdk, webmcp-types

Repo scopes: root, deps, release, ci, docs, *

WebMCP Architecture

WebMCP Proposal APIs

• document.modelContext is the canonical current-draft WebMCP surface.
• executeTool(tool, inputObject) takes an input object and resolves to a string. Results are JSON, except that native declarative tools can return plain text, so MCP-B treats a result as structured only when it parses to a plain JSON object. String input, string input schemas, and navigator aliases are not supported.
• The draft fires toolactivated and toolcancel at the model context. The polyfill fires both for declarative tools; BrowserMcpServer re-dispatches them and adds ontoolactivated and ontoolcancel.
• Native Chrome lanes require Chrome 155 or later, the first release with object input.
• The vendored core needs Chrome 126, Firefox 126, or Safari 18 (URL.parse()). On older engines and insecure pages, installWebMCP() installs nothing.
• Check the live draft and package source before documenting browser behavior.
• New examples and public documentation use document.modelContext.

Package Layering

┌─────────────────────────────────────────────────────┐
│  @mcp-b/global                                      │
│  Entry point. Orchestrates polyfill + server setup.  │
│  Auto-initializes in browser environments.           │
├─────────────────────────────────────────────────────┤
│  @mcp-b/webmcp-ts-sdk (BrowserMcpServer)            │
│  Wraps the underlying modelContext. Extends it with  │
│  listTools, prompt/resource helpers, and a composed  │
│  MCP server. Mirrors core tool ops down to the       │
│  native/polyfill context.                            │
├─────────────────────────────────────────────────────┤
│  @mcp-b/webmcp-polyfill                             │
│  Bundles upstream webmcp-polyfill (pinned commit).  │
│  Exposes installWebMCP() plus temporary MCP-B       │
│  declarative tools.                                 │
├─────────────────────────────────────────────────────┤
│  Native browser API (if available)                   │
│  document.modelContext provided by the browser.      │
└─────────────────────────────────────────────────────┘

Initialization Flow (@mcp-b/global)

1. Polyfill: Call installWebMCP() from @mcp-b/webmcp-polyfill. It preserves existing native/preinstalled contexts and adds declarative support when missing. That package bundles the upstream source at the commit recorded in packages/webmcp-polyfill/package.json and temporarily retains MCP-B declarative tools. MCP outputSchema belongs to @mcp-b/global.
2. Capture native: A reference to the current document context is saved as native.
3. BrowserMcpServer: Uses the page's context by default, installing the upstream polyfill when needed. Global passes its captured { native } explicitly. Browser-facing tool registrations mirror down to that context and native tools are reconciled through getTools(). In the top frame that includes tools from same-origin descendant frames; in a child frame it mirrors only the frame's own tools.
4. Replace: document.modelContext exposes the BrowserMcpServer instance, which adds registerPrompt, registerResource, listTools, and other MCP-B extensions. Browser-shaped execution uses getTools() plus executeTool(tool, inputObject).
5. Cleanup: cleanupWebModelContext() restores the original native/polyfill context. Closing the server unregisters every tool registered through it; tools registered directly on the underlying context remain. The polyfill and its declarative layer remain installed for the document lifetime.

What Lives Where

Extension Integration (@mcp-b/webmcp-extension)

• A MAIN-world content script imports @mcp-b/global; page code still uses document.modelContext normally.
• The isolated content script calls connectWebMCPClient() and receives the official MCP Client.
• Keep privileged extension APIs and secrets out of the MAIN-world bundle.
• The template is top-frame only. Do not add all_frames while @mcp-b/global selects the iframe-child transport in child frames.

Type ownership

• Upstream webmcp-types owns the WebMCP browser contracts and document.modelContext declaration. Packages pin it exactly to 0.1.9; 0.1.10 adds lifecycle members and event classes that the vendored core does not implement.
• @mcp-b/webmcp-types forwards upstream exports for existing package consumers; new code imports webmcp-types directly. Both legacy core packages are temporary aliases.
• @mcp-b/webmcp-ts-sdk owns MCP-B adapter and extension contracts plus schema helpers.
• @mcp-b/global declares only window.__webModelContextOptions. document.modelContext keeps the upstream type, so narrow it with isBrowserMcpServer() to reach MCP-B extensions.

Reference Repos (.reference/)

The .reference/ directory (gitignored) holds shallow clones of upstream repos we track for sync. They are not runtime dependencies. Most are human/AI references; wpt/ is also the pinned upstream conformance suite used by CI.

WebMCP Proposal and Conformance

For changes to browser-facing WebMCP behavior:

1. Read the live Community Group draft and compare it with the relevant file in .reference/webmcp/. The local clone can lag active proposal work.
2. Inspect .reference/wpt/webmcp/ for executable upstream behavior. WPT is a cross-browser standards suite, not a Chromium-only test repository.
3. Consult Blink's third_party/blink/renderer/core/script_tools/ only for Chromium-specific implementation details or extensions.

The pinned WPT revision and CI job live in .github/workflows/e2e.yml. Test selection and the shared local/CI runner live in scripts/run-webmcp-wpt.mjs. The WPT lane builds the standalone polyfill, disables native WebMCP, injects the bundle, and runs an explicit allowlist. When changing covered behavior, run the shared conformance suite and replay the WPT lane with CHROME_BIN=/path/to/chrome-canary pnpm test:wpt. Update the WPT pin deliberately and review the upstream diff first. See docs/TESTING.md for the test matrix and why the allowlist omits the other upstream files.

pnpm test:wpt:idl is a second lane checking API shape rather than behavior. It needs interfaces in the .reference/wpt sparse checkout and runs non-blocking in CI; see docs/TESTING.md.

Before Committing

All code must pass:

pnpm build && pnpm typecheck && vp check && pnpm test:unit