The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the WebMCP Today listing page.
WebMCP Today is a registry for declarative packages that add WebMCP tools to sites that do not expose them. A package describes a site's tools and the API requests they use. The browser extension installs packages locally and registers their tools on matching pages.
The registry is live at webmcp.today.
The live site now registers four read-only WebMCP tools directly from
webmcp.today. These tools require no WebMCP Today extension or local bridge.
chrome://flags/#enable-webmcp-testing, enable WebMCP testing, and relaunch Chrome.| Tool | Purpose |
|---|---|
search_packages | Search all currently servable registry packages by package metadata or tool text, with optional domain filtering. |
get_package | Return the latest served package document for a package ID. |
compare_packages | Compare two to four packages, including common and package-unique tool names. |
verify_site_tools | Show which registry packages match a URL and the tool descriptors those packages would expose there. |
Sample prompts:
The annotated pre-webmcp-challenge tag marks commit 60e3660, the baseline
before challenge-specific work. NEW-WORK.md is the dated changelog
for work after that tag.
The judge path is self-sufficient within this repository: the Next.js web app
uses its own public API, database, schema package, and curated seed package. It
does not load code or package data from webmcp-packages or another repository
at runtime.
Licensing remains split as documented in License: the server and
database are AGPL-3.0-only under the root LICENSE; the reusable schema,
engine, MCP bridge, curated packages, skill, and extension carry their own
MIT licenses.
Install the public skill for researching, creating, validating, and safely testing a WebMCP Today package:
The skill creates webmcp-package.json and stops before registry publication.
| Path | What |
|---|---|
packages/schema | @webmcp-today/schema — published zod package format |
packages/engine | @webmcp-today/engine — API execution engine |
packages/db | Drizzle + Neon schema and client |
packages/mcp | @webmcp-today/mcp-bridge — published public-beta registry MCP server + local bridge for live WebMCP tools |
apps/web | Next.js registry UI + public REST API |
apps/extension | WXT extension: package lookup + WebMCP tool injection |
The extension's local bridge fallback works without the WebMCP testing flag. Enable the flag when you want Chrome's native agent to discover the extension's tools.
Prerequisites: bun@1.3.14 (pinned in root package.json packageManager), Node for Next.js/WXT and some CLIs. The local MCP bridge requires Node 20 or newer or Bun.
Setup:
apps/web/.env needs DATABASE_URL (Neon), a per-environment BETTER_AUTH_SECRET (openssl rand -base64 32), a shared OAUTH_PROXY_SECRET for local/Preview/Production (openssl rand -base64 32), the development GitHub OAuth App credentials (callback http://localhost:3000/api/auth/callback/github), and BETTER_AUTH_URL=http://localhost:3000. Leave OAUTH_PROXY_PRODUCTION_URL unset locally; in Vercel Preview and Production it is https://webmcp.today and routes OAuth through the production GitHub OAuth App callback.
These are ordinary fresh-database setup commands. They do not reset an existing database.
Historical migration baseline:
packages/db/migrations/0000_init.sql is the initial schema baseline and will
not replay against an existing deployed Neon database. Never reset or recreate
production data to apply it. For schema changes, generate and review a new
Drizzle migration and apply it with db:migrate. Run db:seed only for fresh
or local databases until it is idempotent and version-aware; use a reviewed
production procedure for curated seed changes.
Running locally:
cd apps/web && bun run dev → http://localhost:3000 (Next.js). Extension's default registry URL points here.cd apps/extension && bun run dev → WXT dev server on http://localhost:5173, launches a dedicated Chrome profile at .wxt/chrome-profile/ with --enable-features=WebMCP,WebMCPTesting force-enabled (chrome://flags still shows "Default" — check chrome://version). One instance only — second crashes on profile lock and corrupts .output/. Model Context Tool Inspector is installed once into that profile and persists.packages/mcp/README.md, then start node packages/mcp/dist/index.js. Its MCP tools invoke live WebMCP tools in the selected normal Chrome tab without Chrome DevTools MCP, a remote-debugging port, or chrome.debugger. The built-in fallback works without the WebMCP testing flag; enable it only for Chrome's native agent to discover the tools.lsof -nP -i :3000 -i :5173; killing a bun wrapper does NOT kill its node child.Quality gates: bun run typecheck && bun run lint && bun run test before every commit — same as CI (.github/workflows/ci.yml via oven-sh/setup-bun@v2 1.3.14 + --frozen-lockfile). Pre-commit runs husky + lint-staged (eslint + prettier on staged source, prettier on json/md/css/yaml) and enforces CLAUDE.md -> AGENTS.md symlink drift.
Deeper context: root AGENTS.md (stack, conventions, decisions log, cross-cutting gotchas) and nested apps/web/AGENTS.md (package-install registry model, served truth, env/t3-env notes) + apps/extension/AGENTS.md (dev browser, silent-fallback trap, selector-rot recipe).
Split, so the pieces worth adopting stay permissive:
apps/web and packages/db (root LICENSE). Run a modified copy as a network service and you owe your users the source.packages/schema (package format), packages/engine (execution engine), packages/mcp (MCP server), packages/curated-packages (curated packages), and apps/extension (browser extension). Each carries its own LICENSE.Community-submitted packages are not code and are not covered by either license. Publishing one grants the registry a permanent license to host and redistribute it, and offers it onward under CC0 1.0 — see the terms (apps/web/app/(registry)/terms). packages/curated-packages is the first-party exception: it ships as MIT source.
Contributions are covered by the agreement in CONTRIBUTING.md.