webmcp-kit

May 19, 2026 · View on GitHub

npm version npm downloads license: MIT types: TypeScript

Type-safe WebMCP tools with Zod.

What is WebMCP?

WebMCP is a browser API that lets websites expose tools to AI agents, developed under the WebML working group.

The API adds navigator.modelContext, which websites use to register tools that agents can discover and call. Think of it like making your site's functionality available to AI assistants.

The current spec exposes a single method — navigator.modelContext.registerTool(tool, { signal }) — and tools are unregistered by aborting the AbortSignal you passed at registration time. webmcp-kit handles that controller lifecycle for you.

Major browsers are starting to experiment with implementations.

What does webmcp-kit do?

webmcp-kit wraps the raw WebMCP API to make building tools easier:

  • Zod schemas: Define inputs once, get JSON Schema conversion and TypeScript inference
  • Built-in validation: Inputs are validated against your schema before execute runs
  • Less boilerplate: Feature detection, response formatting, and registration handled for you
  • Automatic feature detection: Works when the API exists, falls back gracefully when it doesn't
  • Dev panel: Test and debug tools in the browser without needing a real agent
import { defineTool } from 'webmcp-kit';
import { z } from 'zod';

const addToCart = defineTool({
  name: 'addToCart',
  description: 'Add a product to cart',
  inputSchema: z.object({
    productId: z.string(),
    quantity: z.number().min(1),
  }),
  execute: async ({ productId, quantity }) => {
    // productId and quantity are typed
    return `Added ${quantity}x ${productId}`;
  },
});

addToCart.register();

Install

npm install webmcp-kit zod

Requires Zod v4.

Install and Use the add-webmcp-tools Skill

Install the skill from this repository using Vercel's Skills CLI:

npx skills add victorhuangwq/webmcp-kit

Then invoke it with requests like:

  • "add a webmcp tool for search"
  • "debug why my tool is not in dev panel"
  • "update tool schema and validation"

References:

Usage

Define a Tool

import { defineTool } from 'webmcp-kit';
import { z } from 'zod';

const searchProducts = defineTool({
  name: 'searchProducts',
  title: 'Search Products', // optional human-friendly label
  description: 'Search the product catalog',
  inputSchema: z.object({
    query: z.string().describe('Search query'),
    limit: z.number().optional().default(10),
  }),
  execute: async ({ query, limit }) => {
    const results = await db.products.search(query, limit);
    return JSON.stringify(results);
  },
});

searchProducts.register();

The schema is converted to JSON Schema for the WebMCP API. Your execute function receives typed inputs. Inputs that fail Zod validation never reach execute — the kit returns a validation error response instead. Exceptions thrown inside execute are caught and surfaced as error responses (isError: true), so a single tool blowing up won't crash the page.

Annotations

Use annotations to hint at tool behavior, matching the spec's ToolAnnotations:

defineTool({
  name: 'searchProducts',
  description: 'Search the product catalog',
  inputSchema: z.object({ query: z.string() }),
  annotations: {
    readOnlyHint: true,         // tool does not modify state
    untrustedContentHint: true, // surfaces third-party content the model should treat as untrusted
  },
  execute: async ({ query }) => { /* ... */ },
});

Only set readOnlyHint: true for tools that genuinely make no state changes. For sensitive mutations, prompt for confirmation inline via client.requestUserInteraction(...) (see below).

Testing tools

Call a tool directly without registering it. Input is validated against the Zod schema, and you always get back a ToolResponse:

const response = await searchProducts.execute({ query: 'shoes', limit: 5 });
// response: { content: [...], isError?: boolean }

Between tests, use unregisterAll() to tear down kit-managed registrations and resetMockModelContext() (from webmcp-kit) to reset the in-process mock registry.

Response Helpers

import { textContent, jsonContent, errorContent } from 'webmcp-kit';

// String responses are auto-wrapped, but you can be explicit:
return textContent('Done');
return jsonContent({ status: 'ok' });
return errorContent('Something went wrong');

Dev Panel

Test tools without a real agent:

import { enableDevMode } from 'webmcp-kit/devtools';

enableDevMode();
// or with a custom position:
enableDevMode({ position: { bottom: 24, right: 24 } });

This injects a panel that lists your tools, generates input forms from schemas, and lets you execute them. If the native navigator.modelContextTesting API is available (Chrome 146+ EPP), the panel uses it; otherwise it falls back to the kit's mock registry.

For more control, injectDevPanel(options?) and removeDevPanel() are also exported from webmcp-kit/devtools.

Testing tools directly

tool.execute(input, client?) runs the same validation + execute pipeline used by the WebMCP API, so unit tests don't need to register anything:

import { createMockClient } from 'webmcp-kit';

const result = await checkout.execute(
  { cartId: 'abc' },
  createMockClient({
    onUserInteraction: async () => ({ confirmed: true }),
  })
);

expect(result.isError).toBeUndefined();

The client argument is optional — omit it and a default mock client is used.

API

defineTool(options)

const tool = defineTool({
  name: string,
  title?: string,
  description: string,
  inputSchema: ZodSchema,
  execute: (input, client) => Promise<string | ToolResponse>,
  annotations?: ToolAnnotations,
});

tool.register();     // Add to navigator.modelContext (mints an AbortController internally)
tool.unregister();   // Aborts the signal — removes the tool
tool.execute(input); // Validates input, returns Promise<ToolResponse> — useful in unit tests
tool.schema;         // The original Zod schema (readonly)

execute can return a string (auto-wrapped via textContent) or a full ToolResponse when you need multi-content output or isError: true.

annotations accepts two hints from the WebMCP spec:

  • readOnlyHint — the tool does not modify external state.
  • untrustedContentHint — the tool may surface untrusted third-party content to the model.

Internally, tool.register() calls navigator.modelContext.registerTool(tool, { signal }) with a kit-owned AbortController. tool.unregister() aborts it. You don't need to manage controllers yourself.

unregisterAll() / getRegisteredTools()

The kit tracks every tool you register via defineTool().register() in a process-wide set. This is handy for HMR, SPA route teardown, and test cleanup:

import { unregisterAll, getRegisteredTools } from 'webmcp-kit';

// e.g. on Vite HMR dispose
if (import.meta.hot) {
  import.meta.hot.dispose(() => unregisterAll());
}

console.log(getRegisteredTools().map((t) => t.name));

enableDevMode()

import { enableDevMode } from 'webmcp-kit/devtools';

enableDevMode();
// or, with custom positioning:
enableDevMode({ position: { bottom: 16, right: 16 } });

webmcp-kit/devtools also exports injectDevPanel(options?) and removeDevPanel() if you want explicit control over when the panel mounts and unmounts. injectDevPanel returns a cleanup function.

How It Works

defineTool() creates a tool object. When you call .register():

  1. It mints a fresh AbortController for this registration.
  2. It checks isWebMCPSupported() (i.e. whether navigator.modelContext exists).
  3. If yes, it calls navigator.modelContext.registerTool(tool, { signal }) with that controller's signal.
  4. If no, it registers with an internal mock so the dev panel still works.
  5. It adds the tool to the kit's process-wide registration tracker (used by unregisterAll() / getRegisteredTools()).

.unregister() simply aborts the controller — both the native API and the mock listen for that signal, so the tool disappears from wherever it was registered. The tracker untracks itself via the abort listener, so it stays in sync even if the signal fires from elsewhere.

Your code doesn't change based on environment. When browsers ship WebMCP support, the same code will use the real API. isWebMCPSupported() is also exported if you want to gate behavior on the native API yourself.

If you need to gate UI on capability, isWebMCPSupported() and isBrowser() are exported from webmcp-kit.

Examples

  • examples/pizza-shop: pizza ordering flow with multiple tools (getMenu, addToCart, getCart, clearCart, checkout).
  • examples/flight-booking: multi-step flight purchase flow (searchFlights, selectFlight, addTraveler, addExtras, reviewBooking, purchaseFlight).

Both examples include setup instructions for testing with native WebMCP and mock mode.

Support

If you find webmcp-kit useful:

  • Star the repo: It helps others discover the project
  • Report issues: Found a bug or have a feature request? Open an issue

License

MIT