Configuration

Two files, two jobs

codegen.config.mjs is code. It defines structure: sources, generators, safety options. Write it with npx @webmcp-stack/codegen init when you outgrow the defaults. It imports from the package, so it needs npm install -D webmcp-codegen.

.webmcp-codegen.json is data. The CLI writes it to remember choices it had to ask or detect (which spec, which app is your web app), and the dev dashboard writes per-tool overrides to it. It needs no install, and it is meant to be committed.

{
  "spec": "apps/server/openapi/openapi.json",
  "app": "apps/web",
  "overrides": {
    "get-trips": { "description": "List my trips, newest first." },
    "delete-trip": { "enabled": true }
  }
}

Overrides apply after the safety review, so they win over derived defaults and survive regeneration. Editing this file by hand is fine.

codegen.config.mjs

import { defineConfig } from "@webmcp-stack/codegen";
import { openapi } from "@webmcp-stack/codegen/sources";
import { js } from "@webmcp-stack/codegen/generators";

export default defineConfig({
  sources: [openapi({ spec: "./openapi.yaml" })],
  generate: [js({ outDir: "./src/webmcp" })],
  safety: {
    // Extra field names to treat as PII, on top of the built-in list:
    // piiFields: ["internalId"],
    // Tools to skip entirely (matched against name and route):
    // exclude: ["internal"],
  },
});

Config files are plain JavaScript so the CLI loads them with a plain dynamic import. No TypeScript loader, no build step. Paths (spec, outDir) resolve from the directory you run the command in.

Options

sources

An array; today there is one source. openapi({ spec }) reads an OpenAPI 3.x document (YAML or JSON). Add more entries to combine several specs into one toolset.

generate

An array; today there is one generator. js({ outDir }) writes the plain-TypeScript output described in Regeneration. Framework generators (react, html) are on the roadmap.

safety.piiFields

Extends the built-in list of field names the audit flags as likely PII in responses (email, password, phone, and friends). Add your domain's own sensitive fields.

safety.exclude

Substrings matched against tool names and routes, case-insensitive. Excluded endpoints are skipped and listed in the report with the reason, never silently dropped.

Precedence

When several sources of truth exist, the winner is:

1. codegen.config.mjs (structure)
2. --spec / --out flags (one-off overrides)
3. .webmcp-codegen.json (remembered choices, per-tool overrides)
4. Detection (spec filenames, web-app package.json)