DEV Community

OLI Untangled
OLI Untangled

Posted on

webmcp-gen: Generate Chrome WebMCP Tool Definitions from TypeScript

#webmcp #chrome #typescript #ai

Chrome 149 shipped WebMCP — a browser-native API that lets web pages expose structured tools to AI agents via navigator.modelContext. The ecosystem is forming fast: webmcp-core crawls live sites to auto-generate tool definitions, and @webmcp-registry/kit provides a runtime SDK with Zod-based defineTool().

What's missing is build-time codegen from your existing TypeScript. If you already have typed interfaces for your API, you shouldn't have to rewrite them as Zod schemas or wait for a crawler to discover them.

webmcp-gen fills that gap. Write your API as TypeScript interfaces, run one command, get spec-compliant WebMCP tool definitions + handler stubs with security best practices baked in.

Where it fits

Tool Approach When to use
webmcp-core Crawl a live URL You have a site, want tools auto-discovered
@webmcp-registry/kit Zod schemas at runtime You want runtime registration + React hooks
webmcp-gen TypeScript interfaces at build time You have typed TS, want static JSON + stubs

They're complementary — different layers for different workflows.

Quick example 

// api.ts

/** Search products by keyword. */
interface SearchProducts {
  query: string;
  category?: "electronics" | "clothing" | "home";
  limit?: number;
}
Enter fullscreen mode Exit fullscreen mode 
npx webmcp-gen --api api.ts
Enter fullscreen mode Exit fullscreen mode

Output: a .webmcp.json definition + a .handler.ts stub with navigator.modelContext.registerTool() wired up and ready to implement.

What it does

  • Parses TypeScript interfaces and type aliases via ts-morph
  • Maps TS types to JSON Schema (strings, numbers, enums, arrays, nested objects, optionals)
  • Pulls descriptions from JSDoc comments
  • Validates output against the WebMCP spec
  • Generates handler stubs with Google's security guidance built in:
    • requestUserInteraction() reminders for mutating tools
    • Input sanitisation warnings for freeform string inputs
    • readOnlyHint annotations for query-only tools

Security by default

WebMCP allows AI agents to execute tools that affect live web applications. Google advises using human-in-the-loop hooks and protecting against indirect prompt injection. webmcp-gen bakes this into every generated handler stub — mutating tools get requestUserInteraction() reminders, freeform inputs get sanitisation warnings. Safe defaults, not afterthoughts.

Install 

npm install -g webmcp-gen
Enter fullscreen mode Exit fullscreen mode

Includes 4 starter templates (CRUD, search, form handler, data transformer) to get you going:

webmcp-gen --template crud-api
webmcp-gen --api crud-api.ts
Enter fullscreen mode Exit fullscreen mode

MIT licensed. Contributions welcome.

v1.2.0 — security-hardened release

The current npm version (v1.2.0) has been through a 4-agent security audit covering line-by-line diff scanning, cross-file tracing, removed-behavior analysis, and dedicated security review. 10 findings were fixed before public announcement, including injection hardening in generated code, path traversal protection, and Chrome 150 compatibility (the origin trial API moved from navigator.modelContext to document.modelContext). Full changelog in the README.

GitHub: oliuntangled/webmcp-gen
npm: webmcp-gen

Not affiliated with or endorsed by Google or the W3C. Built with AI assistance.

Top comments (0)