webmcp-stack: generate WebMCP tools from the API spec you already have

`npx @webmcp-stack/codegen generate`

The main command. Resolves where tools come from and where they go, in this order:

A config file (codegen.config.mjs, or --config PATH) when one exists.
--spec / --out flags as quick overrides.
Remembered choices from .webmcp-codegen.json.
Auto-detection: the spec by filename, the web app by its package.json.

  --spec PATH    Which OpenAPI spec to use (auto-detected when omitted)
  --out DIR      Where the tool files go (default: your web app's src/webmcp)
  --dry-run      Preview what would be written, write nothing
  --skip-audit   Skip the safety report
  --force        Write files even when the audit reports errors
  --config PATH  Use a config file at PATH
  --watch        Re-generate when files change
  --llm          Improve the names and descriptions of the tools being generated (LLM)
  --suggest      Find schemas worth declaring as tools (LLM)

A successful run also wires registration into your app (two additive lines; see Quickstart) and remembers detection choices in .webmcp-codegen.json.

Exit codes: 0 on success, 1 when the audit blocks generation (unless --force).

`npx @webmcp-stack/codegen generate --dry-run`

Computes everything and writes nothing: the tool list with risk labels, skipped endpoints and why, the audit findings, the files it would write, and the registration edits it would make. The first command to run in any repo.

`npx @webmcp-stack/codegen generate --watch`

Re-runs on every relevant file change. Regeneration is cheap and merge-safe, so watch mode keeps tools in sync while you edit the spec. The watcher ignores its own outputs (src/webmcp, .webmcp-codegen.json), so it never loops.

The two LLM flags

Both are opt-in — plain generate never touches a model, never sends anything anywhere, never needs a key. Turn one on only when you want the LLM's help. They answer two different questions:

generate --llm — "make the tools I already generate better." You have a spec (or a config) and tools generate. The LLM reads each tool's name, description, and fields and proposes clearer descriptions and names, printed as ◦ draft lines for you to review. Nothing is auto-applied; your hand-written text always wins; safety classification is never the model's call.

generate --suggest — "find tools I haven't declared yet." You have validation schemas but no generated tools. The CLI finds your schema modules itself (no file path needed) and the LLM proposes which schemas are worth declaring as tools. Nothing is written; declaring is your edit to codegen.config.mjs.

The rule of thumb: tools already exist → --llm; starting from schemas → --suggest.

The API key

Neither flag requires your own key. The first time you run one without a key configured, an interactive terminal offers three choices:

Use the free hosted tier — webmcp-stack's shared key (rate-limited), zero setup. The key lives on our server, never in the package.
Enter my own API key — OpenRouter, OpenAI, or any OpenAI-compatible provider. Used for this command only, never stored, input is masked.
Skip — continue without LLM features, exactly as if you'd passed neither flag.

In CI (non-interactive), both flags quietly produce the deterministic output — a prompt never blocks a pipeline, and a failing provider becomes one note line, never a failure. To use your own key always, set WEBMCP_LLM_API_KEY or OPENAI_API_KEY in your environment.

`npx @webmcp-stack/codegen verify`

Measures your generated tools against the quality standard they are supposed to meet, before anything ships. Runs the same pipeline as generate (writing nothing) and reports a scorecard:

✓ Names: all 35 names within 30 characters, verb-first
! Descriptions: 2 problems
✓ Fields: every input field described, nested ones included
✓ Annotations: reads declare readOnlyHint; content declares its trust
! Surface: 35 registered

Each finding names the tool and what to do about it. Exits 1 on error-level findings (a tool with no description), so CI can gate on it.

verify --url https://your-app.com adds one check against the deployed page: whether it serves an origin trial token, because tools being generated and tools being live in a visitor's browser are different facts.

`npx @webmcp-stack/codegen dev`

Opens the tools dashboard on http://localhost:4700 (override with --port N). A local control panel for what was generated:

The webmcp-codegen dashboard

Browse and search every tool, grouped by risk level
Edit descriptions and toggle tools on or off. Edits save to .webmcp-codegen.json and survive regeneration
Run any tool directly to check the wiring, without opening the app

The dashboard serves a localhost page from inside the CLI. Nothing is added to your app, and it stops existing when you Ctrl+C.

`npx @webmcp-stack/codegen init`

Writes a starter codegen.config.mjs, pointed at your detected spec. The config imports from the package, so this path needs an install:

npm install -D webmcp-codegen

You do not need init to use the CLI. Config is for when you outgrow the defaults: multiple sources, custom safety options, generator options.

Global flags

  --help         Print help

CLI reference