@mcptrail/webmcp-devtools

A zero-config dev panel for WebMCP. It lists the tools your page registers, auto-builds a form from each inputSchema, lets you invoke them, and shows the result — so you can exercise your agent tools without a flagged Chrome or a live model.

Pairs with @mcptrail/webmcp-highlight: invoke a tool from the panel and watch what it changed on the page.

Install

npm install @mcptrail/webmcp-devtools

react is an optional peer dependency (only for the /react entry).

Vanilla

import { createWebMcpDevtools } from "@mcptrail/webmcp-devtools";

// Create it BEFORE your tools register, so it intercepts navigator.modelContext.registerTool.
const devtools = createWebMcpDevtools();

That's it — a panel appears with every registered tool and a generated form.

React

import { WebMcpDevtoolsProvider } from "@mcptrail/webmcp-devtools/react";

<WebMcpDevtoolsProvider>
  <App />
</WebMcpDevtoolsProvider>;

How it works

• Discovery — patches navigator.modelContext.registerTool and records each tool (name, description, inputSchema, annotations). Create it early; you can also pass tools: [...] or call register(tool).
• Forms — a flat object schema of primitives/enums becomes real inputs (text / number / checkbox / select, with defaults and required markers). Anything nested falls back to a raw-JSON editor. Values are coerced to the schema types on invoke.
• Highlight integration — if @mcptrail/webmcp-highlight is mounted (window.WebMcpHighlight), invocations route through it so the changed DOM is highlighted. Pass an instance explicitly with highlight, or highlight: false to opt out.
• Theme — samples the host's accent + surface (same inference as webmcp-highlight), so the panel matches your design system.

Options

| Option | Default | Notes | |--------|---------|-------| | target | navigator.modelContext | the modelContext to intercept | | tools | — | seed tools explicitly | | highlight | auto | route invokes through webmcp-highlight (false to disable, or pass an instance) | | position | "bottom-left" | panel corner | | open | true | start expanded | | onInvoke | — | (name, args, { result, status, ms }) after each call |

API

const dt = createWebMcpDevtools(options);
dt.register(tool);   // add a tool manually
dt.tools();          // the current registry
dt.refresh();        // re-render
dt.destroy();        // remove the panel + restore registerTool

Also exported: fieldsFor(schema) and coerceArgs(fields, values) — the pure schema→form and form→args helpers, reusable on their own.

Development

npm install
npm run typecheck
npm test          # Vitest + jsdom
npm run build     # tsup → dist (ESM + CJS + d.ts)

License

MIT © Zied Guetari