@napster-corp/webmcp-toolkit 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Napster
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,531 @@
+# @napster-corp/webmcp-toolkit
+
+> Let an AI agent actually operate your web app — by exposing the app's real operations as tools the agent can call, on top of the WebMCP standard.
+
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)
+[![standard: WebMCP](https://img.shields.io/badge/standard-WebMCP-purple.svg)](https://github.com/webmachinelearning/webmcp)
+
+Most AI agents on websites today are observers. A voice-and-video assistant on
+your homepage, or a chatbot in the corner, can answer questions about your
+product, read off pricing, maybe file a support ticket. But when the user says
+"add the 65-inch OLED to my cart and check out," the agent's answer is
+something like "sure, click the Add to Cart button." It can't actually do it.
+The user still drives the UI by hand.
+
+WebMCP closes that gap. Your app declares which of its real operations an
+agent is allowed to run — `products.search`, `cart.add`,
+`checkout.placeOrder`, whatever you choose to expose — and any compatible
+agent running in the same page can call them. The agent doesn't simulate your
+app; it operates the app, using the same functions your buttons and forms
+already call. The cart drawer slides open. The product page navigates. The
+order gets placed.
+
+This is **the Model Context Protocol, but for the browser.** The original MCP
+exposes server-side tools to an AI client over a wire protocol; WebMCP exposes
+the app's in-browser tools to whichever agent is running on the same page,
+through `document.modelContext`. A compatible agent SDK finds the app's tools
+at runtime and wires itself up — no glue code, nothing to dispatch by hand.
+
+The **Napster WebMCP Toolkit** is a thin layer on top of that standard. It
+**polyfills** WebMCP so `document.modelContext` exists in every browser, and it
+**adds value** on top — safety tiers, live-state resources, and a dev panel —
+without changing how you register tools. Your `registerTool` code is standard
+WebMCP: remove the toolkit and it still works against the native browser API.
+
+```bash
+npm install @napster-corp/webmcp-toolkit
+```
+
+---
+
+## Why this exists
+
+Even when teams try to make a website agent that *does* things instead of
+just talking, the usual path is to build a second, parallel system next to
+the app: copy your data into a vector store, hand-wrap your APIs as agent
+tools, write a workflow mapping layer, and keep all of it in sync with the
+real application every time it ships. The parallel system drifts. The agent
+makes confident, wrong claims based on stale knowledge — and when it does
+try to act, it acts on a copy of the app, not the app itself.
+
+WebMCP inverts this. Instead of duplicating your app for the agent, you
+point the agent **at** the live app. You expose an approved set of operations
+the agent is allowed to invoke and an approved set of state slices the agent
+is allowed to observe. The agent calls the same functions the UI calls; the
+app stays the source of truth.
+
+Two consequences worth stating up front:
+
+- **The UI stays in sync automatically.** An agent's `cart.add` updates the
+  one cart store, and every component bound to it re-renders. You don't write
+  sync code.
+- **The agent runs as the signed-in user.** The toolkit doesn't grant new
+  permissions; it picks a subset of the user's existing rights and makes them
+  callable through the agent. Auth, validation, and authorization stay
+  exactly where they already are.
+
+And one that's specific to building on a standard:
+
+- **Zero lock-in.** Tools are registered through the native
+  `document.modelContext.registerTool` API. If the customer removes this
+  toolkit, their tool code keeps working against the browser's own WebMCP
+  implementation — and any standards-compliant WebMCP agent can already drive
+  them. The toolkit's extras (tiers, resources, dev panel) layer on top
+  without owning the call site.
+
+---
+
+## What importing the package does
+
+Importing `@napster-corp/webmcp-toolkit` is a **browser-only side effect**. On
+import it does two things:
+
+1. **Polyfills WebMCP.** It initializes
+   [`@mcp-b/webmcp-polyfill`](https://www.npmjs.com/package/@mcp-b/webmcp-polyfill)
+   so `document.modelContext` exists cross-browser. When the browser already
+   supports WebMCP natively, this is a no-op.
+2. **Installs the resource extension.** It adds an MCP-shaped live-state
+   "resource extension" onto `document.modelContext` (see
+   [Live state](#live-state--the-eyes)).
+
+Outside a browser — SSR (Next.js / Nuxt / Remix / SvelteKit), web workers, edge
+runtimes — importing the package **does nothing and touches no globals**. The
+real surface comes up in the browser when the bundle hydrates. You don't need
+to add any guards in your own code; the package handles it.
+
+```ts
+// src/webmcp/index.ts
+import '@napster-corp/webmcp-toolkit';   // polyfill + resource extension (side effect)
+import './tools';                         // your registerTool / registerStatefulTool calls
+import './resources';                     // your registerResource calls
+```
+
+---
+
+## Quick example
+
+The website developer writes **standard WebMCP tools** — there's no
+Napster-specific call required to register a tool:
+
+```ts
+// src/webmcp/tools.ts
+document.modelContext.registerTool({
+  name: 'cart.add',
+  description: 'Add a product to the cart.',
+  inputSchema: {
+    type: 'object',
+    properties: { productId: { type: 'string' } },
+    required: ['productId'],
+  },
+  annotations: { readOnlyHint: false },   // WebMCP defines only readOnlyHint + untrustedContentHint
+  async execute({ productId }) {
+    cartStore.add(productId);
+    return { content: [{ type: 'text', text: 'Added to cart' }] };   // standard MCP result shape
+  },
+});
+```
+
+That's the entire integration for a plain tool. A WebMCP-aware agent SDK
+detects `document.modelContext`, reads the tool list, and wires itself up — no
+glue code, nothing to dispatch by hand.
+
+> `cartStore` is a stand-in for your app's own code — the same functions your
+> UI's buttons and forms already call. The toolkit doesn't replace any of
+> them; it exposes the ones you choose to a connected agent.
+
+See [`examples/app-side.ts`](./examples/app-side.ts) for the full app-side
+pattern.
+
+### The three value-adds, briefly
+
+Everything Napster adds lives **off** the standard call site, so your base
+tools stay portable:
+
+| Add-on | Call | Why it's not in the standard |
+| --- | --- | --- |
+| Safety tiers | `registerStatefulTool({ ..., napsterTier })` | The polyfill drops custom annotation keys from `getTools()`, so the tier is recorded in a side registry |
+| Live state | `registerResource({ uri, get, subscribe })` | WebMCP hasn't formalized resources yet; consumed over Napster's own path |
+| Dev panel | `installDevPanel()` | Dev-only inspector, not part of the runtime contract |
+
+---
+
+## Have a coding agent set it up for you
+
+If you'd rather not work through tool and state design by hand, this repo ships
+three composing skills that any Agent Skills-compatible tool (Claude Code,
+Cursor, Codex, OpenCode, etc.) can load.
+
+```bash
+npx skills add napster-corp/webmcp-toolkit
+```
+
+The skills:
+
+- **`setup-edge-mcp`** — the main entry point. Installs the package, registers
+  the agreed tools and resources against the app's real code, walks the
+  developer through sign-off.
+- **`plan-capabilities-and-state`** — invoked by `setup-edge-mcp` as its first
+  step. Analyzes the codebase, proposes a curated starter plan (tools, live-state
+  resources, and deliberate withholds), walks the developer through it until
+  approved. No file output — the plan lives in the conversation, the code is the
+  record.
+- **`add-edge-mcp-dev-panel`** *(opt-in)* — installs a small dev-only floating
+  panel for testing by hand: a form-based runner for every tool (fields rendered
+  from each tool's `inputSchema`), a live view of every resource, and an event
+  log. `setup-edge-mcp` offers it at the end; run it directly any time after
+  setup.
+
+In your project, just say what you want in plain language — "set up WebMCP",
+"agentify this app", "what should I expose to the agent?", "add a panel for
+testing" — and the matching skill fires.
+
+These skills stop once your WebMCP surface is built. Connecting an actual agent
+(Napster's Omniagent, or any other WebMCP-compatible vendor) is a separate step
+handled by that vendor's own SDK or skills. For the Napster Omniagent, install
+`napster/omniagent-api-skills` alongside this one; its Web SDK auto-attaches to
+`document.modelContext` at runtime.
+
+---
+
+## Core concepts
+
+### Tools — the hands
+
+What the agent can do. One tool per real operation you choose to expose. Name
+them in your app's own domain terms (`products.search`, `cart.add`,
+`orders.cancel`), not in agent-product terms.
+
+`execute` calls your app's **real** code — the same function the UI's own
+button or form submits to. Composing several real operations into one tool is
+fine (and often necessary). What's forbidden is re-deriving business logic the
+app already owns; if you find yourself recomputing a price the app already
+calculates, stop.
+
+Register with the standard `document.modelContext.registerTool(...)`. Reach for
+`registerStatefulTool(...)` (below) when you want a safety tier recorded.
+
+### Live state — the eyes
+
+What the agent can perceive that it didn't get back from a tool. Resources are
+the **exception, not the rule**. Most things don't need one — if a tool returns
+its result, the agent already knows.
+
+Add a resource only for state that changes **out of band**:
+
+- The user edits something by hand (cart quantity, filter, navigation)
+- The server changes state over time (an order moves from `processing` to
+  `shipped` mid-conversation)
+
+Pure pull state — something you could just read on demand — is better modeled
+as a read-only tool than as a resource. And if a tool already returns the
+answer, do **not** add a resource that mirrors it. A search that returns its
+results inline needs no `searchResults` resource; the agent has the data
+already.
+
+### Safety tiers
+
+Tools you register with `registerStatefulTool` carry a `napsterTier`. Consumers
+use it to gate confirmation flows.
+
+| Tier | Example | Confirmation |
+| --- | --- | --- |
+| `read` | search, look up, compare | None — call freely |
+| `reversible` | add to cart, save draft, apply filter | Brief announce |
+| `irreversible` | place order, cancel, send | Explicit user confirmation, wait for consent |
+
+Set the safer tier when in doubt. **The consumer (the Web SDK / agent) enforces
+confirmation — never the model.** A plain `registerTool` tool with no recorded
+tier is treated as `reversible`.
+
+For irreversible tools, also set `idempotent: true` if your underlying
+operation tolerates safe retries (e.g. via an idempotency key on the server).
+
+---
+
+## API
+
+### `registerStatefulTool(tool)`
+
+A thin wrapper over `document.modelContext.registerTool`. It registers a
+**standard** WebMCP tool **and** records a safety tier in a name-keyed registry.
+The side registry is necessary because the polyfill strips custom annotation
+keys out of `getTools()`, so the tier wouldn't survive on the tool itself.
+
+```ts
+import { registerStatefulTool } from '@napster-corp/webmcp-toolkit';
+
+const unregister = registerStatefulTool({
+  // ...all the same fields as registerTool (name, description, inputSchema, execute)...
+  name: 'checkout.placeOrder',
+  description: 'Submit the cart for purchase.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      paymentMethodId: { type: 'string' },
+      addressId: { type: 'string' },
+    },
+    required: ['paymentMethodId', 'addressId'],
+  },
+  napsterTier: 'irreversible',   // 'read' | 'reversible' | 'irreversible'
+  idempotent: true,              // optional
+  untrustedContent: false,       // optional
+  async execute({ paymentMethodId, addressId }) {
+    const order = await placeOrder(paymentMethodId, addressId);
+    return { content: [{ type: 'text', text: `Order ${order.id} placed` }] };
+  },
+});
+
+// later: unregister();
+```
+
+**Extra fields (beyond `registerTool`):**
+
+| Field | Purpose |
+| --- | --- |
+| `napsterTier` | `'read'` \| `'reversible'` \| `'irreversible'` — the confirmation tier |
+| `idempotent?` | mark an irreversible op as safe to retry |
+| `untrustedContent?` | the tool returns content that may carry injected instructions |
+
+The tier maps to the standard WebMCP annotations the agent reads off the tool:
+`read` → `readOnlyHint: true`, and `untrustedContent: true` →
+`untrustedContentHint: true`.
+
+**Returns** an `unregister()` function.
+
+### `getTier(name)` / `getTierMap()`
+
+Read back the recorded tiers (consumer-facing).
+
+```ts
+import { getTier, getTierMap } from '@napster-corp/webmcp-toolkit';
+
+getTier('checkout.placeOrder');  // 'irreversible'
+getTierMap();                    // { 'cart.add': 'reversible', 'checkout.placeOrder': 'irreversible', ... }
+```
+
+A tool with no recorded tier is treated as `reversible`.
+
+### `registerResource(resource)`
+
+Register a live-state resource, modeled on MCP resources. Use it only for
+[out-of-band state](#live-state--the-eyes).
+
+```ts
+import { registerResource } from '@napster-corp/webmcp-toolkit';
+
+registerResource({
+  uri: 'state://cart',
+  name: 'cart',
+  description: 'The current shopping cart',   // optional
+  mimeType: 'application/json',               // optional
+  get: () => cartStore.getCurrent(),
+  subscribe: (onChange) => cartStore.subscribe(onChange),   // optional; return an unsubscribe fn
+});
+```
+
+The consumer-side surface lives on `document.modelContext` (installed by the
+import side effect):
+
+| Member | Purpose |
+| --- | --- |
+| `getResources()` | List registered resources |
+| `readResource(uri)` | Read the current value of one resource |
+| `subscribeResource(uri, handler)` | Subscribe to changes for one resource |
+| `resourceupdated` event | `CustomEvent` with `detail = { uri, value }` |
+| `resourcelistchanged` event | Fired when the resource list changes |
+
+> This resource channel is consumed by the Napster agent over its own path. It
+> is **not interoperable** with third-party WebMCP agents until the standard
+> formalizes resources. The standard tool surface, by contrast, is fully
+> interoperable today.
+
+### `installDevPanel(options?)`
+
+A dev-only in-page inspector. Imported from a subpath so it never ships in your
+production bundle if you don't reference it.
+
+```ts
+import { installDevPanel } from '@napster-corp/webmcp-toolkit/dev-panel';
+
+const uninstall = installDevPanel({ shortcut: 'cmd+shift+e', startOpen: false });
+```
+
+It reads `document.modelContext` directly — **it takes no instance argument**.
+Toggle with **Cmd+Shift+E** (**Ctrl+Shift+E** on non-Mac).
+
+### Adapter exports
+
+The single swap-point over the polyfill, for code that wants the model-context
+object directly instead of reaching for the global:
+
+| Export | Returns |
+| --- | --- |
+| `getModelContext()` | `document.modelContext` (with a deprecated `navigator.modelContext` fallback) |
+| `getModelContextWithResources()` | the same object, with the resource extension surface |
+| `isBrowserEnvironment()` | `true` only in a real browser |
+
+---
+
+## How an agent discovers your app
+
+A WebMCP agent — or the Napster Companion Web SDK — attaches with no
+coordination from you:
+
+1. **Detect** by the presence of `document.modelContext`.
+2. **Read tools** via `getTools()`.
+3. **Invoke** via `executeTool(toolInfo, JSON.stringify(args))`.
+4. **Observe tool changes** via the `toolchange` event — a bare `Event` with no
+   `detail`; re-read `getTools()` when it fires.
+5. **Relay live state** via `subscribeResource` / the `resourceupdated` event.
+
+Because every one of those steps is standard, **the agent attaches to any
+WebMCP-enabled site** — even one that never installed this toolkit. The
+Napster extras (safety tiers, live-state resources) simply light up when the
+toolkit is present and are absent otherwise; nothing breaks either way.
+
+---
+
+## Hosting
+
+The toolkit is browser-only and runs in the same module graph as your UI. A few
+notes worth knowing up front:
+
+- **Recommended file layout.** Keep your WebMCP wiring in a `src/webmcp/`
+  folder: `index.ts` imports the toolkit and wires everything up, `tools.ts`
+  holds your `registerTool` / `registerStatefulTool` calls, and `resources.ts`
+  holds your `registerResource` calls.
+- **Imperative actions from outside the component tree.** A tool's `execute`
+  lives in a plain module. Things like navigation often only exist inside the
+  framework (e.g. React Router's `useNavigate` hook). Register a module-level
+  handle from an in-tree component at mount and have `execute` call through
+  that; otherwise it has no way to drive navigation.
+- **Server-side rendering is a no-op.** Outside the browser (SSR, workers, edge
+  runtimes), importing the package does nothing and touches no globals. This is
+  deliberate: the toolkit connects an in-browser agent to in-browser state;
+  running it on the server would bleed per-user state through the Node
+  process's shared globals. The real surface comes up in the browser when the
+  bundle hydrates.
+
+---
+
+## Automation — keep your tools file in sync
+
+Your tool list is hand-curated, but it drifts as the app changes — a route gets
+renamed, an operation is removed, a new one becomes worth exposing. The package
+ships an **opt-in agent** that re-analyzes the app and rewrites your tools file
+(e.g. `src/webmcp/tools.ts`) to match the current code — runnable from a
+post-commit hook locally, or from CI on a pull request. It produces
+**uncommitted** changes you review.
+
+It uses this package's own `plan-capabilities-and-state` / `setup-edge-mcp`
+skills as the methodology, and by default runs on the **Claude Agent SDK**
+(`@anthropic-ai/claude-agent-sdk`, Claude Opus 4.8).
+
+### Setup (in the host app)
+
+```bash
+npm install @napster-corp/webmcp-toolkit
+npm install -D @anthropic-ai/claude-agent-sdk   # the default engine's runtime
+npx webmcp-toolkit install-hook                        # installs the opt-in post-commit hook
+export ANTHROPIC_API_KEY=...                      # local: your key; CI: a secret
+```
+
+Put your engine's key where the CLI can read it — exported, in CI as a secret,
+or in the app's gitignored `.env.local`.
+
+### How it triggers — opt-in marker
+
+The hook runs **only** when a commit message contains the marker `[webmcp-toolkit]`:
+
+```bash
+git commit -m "feat(cart): add bulk remove  [webmcp-toolkit]"
+```
+
+Every other commit is untouched — no agent run, no token cost. When the marker
+is present, the agent analyzes the app and leaves **uncommitted** changes to
+your tools file — a post-commit hook can't amend the commit, so you review the
+diff and commit it separately:
+
+```
+✎ src/webmcp/tools.ts (unstaged)
+  + cart.bulkRemove (reversible) — src/store/cart.ts:bulkRemove
+  ~ checkout.placeOrder (signature changed) — src/api/checkout.ts:placeOrder
+→ review & commit when ready
+```
+
+### Run it manually / in CI
+
+`webmcp-toolkit generate` is the same command the hook calls — run it anywhere:
+
+```bash
+npx webmcp-toolkit generate          # regenerate now, against the current working tree
+```
+
+On CI (e.g. a GitHub Action on `pull_request`), set the engine's key as a
+secret and run `npx webmcp-toolkit generate`, then open/update a PR with the result.
+It auto-detects the tools file (`src/webmcp/`, `lib/webmcp/`, …); override with
+`--file path` if needed.
+
+### What the agent may touch
+
+Locked down by design: the agent is restricted to `Read` / `Grep` / `Glob` /
+`Edit` / `Write`, with no shell — it reads the app to find real operations and
+edits **only** your tools file. It cannot run commands, install packages, or
+touch git.
+
+### Engines
+
+Pluggable — pick with `--engine` or `WEBMCP_TOOLKIT_ENGINE`:
+
+| Engine | Default | Needs | Notes |
+| --- | --- | --- | --- |
+| `anthropic` | ✅ | `ANTHROPIC_API_KEY` + `@anthropic-ai/claude-agent-sdk` | Claude Agent SDK (Opus 4.8); restricted to read/edit tools (no shell) |
+| `copilot` | | the GitHub **Copilot CLI** + a Copilot subscription | Shells out to the CLI; no Anthropic key |
+
+```bash
+WEBMCP_TOOLKIT_ENGINE=copilot npx webmcp-toolkit generate     # or: npx webmcp-toolkit generate --engine copilot
+```
+
+The skills, prompt, path detection, opt-in marker, and uncommitted-output
+policy are identical across engines — only the agent runtime changes.
+
+> The Copilot CLI's non-interactive flags evolve, so the exact invocation is
+> env-overridable rather than hardcoded — set `WEBMCP_TOOLKIT_COPILOT_BIN` and
+> `WEBMCP_TOOLKIT_COPILOT_ARGS` to match your installed `copilot --help`.
+
+### Commands
+
+| Command | What it does |
+| --- | --- |
+| `webmcp-toolkit install-hook` | Install/refresh the opt-in `[webmcp-toolkit]` post-commit hook (idempotent; composes with an existing hook) |
+| `webmcp-toolkit generate [--engine anthropic\|copilot]` | Analyze the app and rewrite your tools file (local or CI) |
+
+---
+
+## Migrating from `@napster-corp/edge-mcp`
+
+This package was re-based from the proprietary "Edge MCP" contract onto the
+**WebMCP standard**. If you're coming from the old package:
+
+- There is no more `createEdgeMcp()` instance, and no well-known global slot.
+  Register tools directly on `document.modelContext` instead.
+- `registerCapability({ ..., sideEffect, run })` →
+  `document.modelContext.registerTool({ ..., execute })`, or
+  `registerStatefulTool({ ..., napsterTier, execute })` when you want a tier.
+  The `sideEffect` field becomes `napsterTier`; `run` becomes `execute` and
+  returns the standard `{ content: [...] }` shape.
+- `registerStateProvider(...)` → `registerResource({ uri, get, subscribe })`.
+  Read it consumer-side with `getResources()` / `readResource()` /
+  `subscribeResource()` and the `resourceupdated` event.
+- The consumer API (`listCapabilities()`, `invoke()`, `snapshot()`,
+  `getState()`, `onStateChange()`), the discovery helpers (`publishEdgeMcp`,
+  `whenEdgeMcpReady`, …), and the `EDGE_MCP_KEY` symbol are gone — discovery is
+  now standard WebMCP (`getTools()` / `executeTool()` / the `toolchange` event).
+- `installDevPanel` no longer takes an instance argument — it reads
+  `document.modelContext`.
+
+---
+
+## License
+
+[MIT](./LICENSE).

package/bin/webmcp-toolkit.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// webmcp-toolkit CLI — tooling for keeping a host app's WebMCP tools in sync
+// with its code via an autonomous Claude agent.
+//
+//   webmcp-toolkit install-hook   Install the opt-in post-commit hook into this repo.
+//   webmcp-toolkit generate       Analyze the app and (re)write the WebMCP tools file (src/webmcp/tools.ts).
+//
+// `generate` is also what CI calls on a PR — it's the same command, just run on
+// a server with ANTHROPIC_API_KEY provided as a secret.
+
+import { generateCapabilities } from "../tools/generate-capabilities.mjs";
+import { installHook } from "../tools/install-hook.mjs";
+
+const HELP = `webmcp-toolkit — keep WebMCP tools in sync with your code
+
+Usage:
+  webmcp-toolkit install-hook [dir]                       Install the opt-in [webmcp-toolkit] post-commit hook
+  webmcp-toolkit generate [dir] [--engine x] [--file p]   Regenerate the tools file now
+  webmcp-toolkit --help
+
+  [dir]            target app directory (default: current directory)
+  --engine NAME    agent engine: anthropic (default) | copilot
+                   (or set WEBMCP_TOOLKIT_ENGINE)
+  --file PATH      tools file to write (default: auto-detected)
+
+Notes:
+  - anthropic engine needs ANTHROPIC_API_KEY + @anthropic-ai/claude-agent-sdk.
+  - copilot engine needs the GitHub Copilot CLI + a Copilot subscription.
+  - generate writes UNCOMMITTED changes for you to review.
+  - the hook only runs generate when a commit message contains [webmcp-toolkit].
+`;
+
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--file") out.file = argv[++i];
+    else if (a.startsWith("--file=")) out.file = a.slice("--file=".length);
+    else if (a === "--engine") out.engine = argv[++i];
+    else if (a.startsWith("--engine=")) out.engine = a.slice("--engine=".length);
+    else out._.push(a);
+  }
+  return out;
+}
+
+async function main() {
+  const cmd = process.argv[2];
+  const args = parseArgs(process.argv.slice(3));
+  const targetDir = args._[0]; // optional positional dir; undefined → cwd
+  try {
+    switch (cmd) {
+      case "install-hook": {
+        const hookPath = await installHook({ targetDir });
+        console.log(`[webmcp-toolkit] installed post-commit hook → ${hookPath}`);
+        console.log(
+          "[webmcp-toolkit] add `[webmcp-toolkit]` to a commit message to trigger regeneration.",
+        );
+        break;
+      }
+      case "generate": {
+        console.log("[webmcp-toolkit] analyzing app and regenerating tools…\n");
+        await generateCapabilities({ targetDir, file: args.file, engine: args.engine });
+        break;
+      }
+      case "--help":
+      case "-h":
+      case undefined:
+        console.log(HELP);
+        break;
+      default:
+        console.error(`[webmcp-toolkit] unknown command: ${cmd}\n`);
+        console.log(HELP);
+        process.exit(1);
+    }
+  } catch (err) {
+    console.error(`[webmcp-toolkit] ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+}
+
+main();

package/dist/debug.d.ts

@@ -0,0 +1,5 @@
+/** Enable or disable the toolkit's `[webmcp-toolkit]` flow logs. */
+export declare function setDebug(on: boolean): void;
+/** Log a flow event when debug is on. No-op otherwise. */
+export declare function debugLog(...args: unknown[]): void;
+//# sourceMappingURL=debug.d.ts.map

package/dist/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../src/debug.ts"],"names":[],"mappings":"AAMA,oEAAoE;AACpE,wBAAgB,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,IAAI,CAE1C;AAWD,0DAA0D;AAC1D,wBAAgB,QAAQ,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,CAIjD"}

package/dist/debug.js

@@ -0,0 +1,26 @@
+// Opt-in flow logging for the toolkit. OFF by default so the published package
+// is quiet in production. Turn it on either from code — `setDebug(true)` — or at
+// runtime from the browser console: `globalThis.__WEBMCP_DEBUG__ = true`.
+let enabled = false;
+/** Enable or disable the toolkit's `[webmcp-toolkit]` flow logs. */
+export function setDebug(on) {
+    enabled = on;
+}
+function isOn() {
+    if (enabled)
+        return true;
+    try {
+        return Boolean(globalThis.__WEBMCP_DEBUG__);
+    }
+    catch {
+        return false;
+    }
+}
+/** Log a flow event when debug is on. No-op otherwise. */
+export function debugLog(...args) {
+    if (!isOn())
+        return;
+    // eslint-disable-next-line no-console
+    console.info('[webmcp-toolkit]', ...args);
+}
+//# sourceMappingURL=debug.js.map

package/dist/debug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.js","sourceRoot":"","sources":["../src/debug.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,iFAAiF;AACjF,0EAA0E;AAE1E,IAAI,OAAO,GAAG,KAAK,CAAC;AAEpB,oEAAoE;AACpE,MAAM,UAAU,QAAQ,CAAC,EAAW;IAClC,OAAO,GAAG,EAAE,CAAC;AACf,CAAC;AAED,SAAS,IAAI;IACX,IAAI,OAAO;QAAE,OAAO,IAAI,CAAC;IACzB,IAAI,CAAC;QACH,OAAO,OAAO,CAAE,UAA6C,CAAC,gBAAgB,CAAC,CAAC;IAClF,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,QAAQ,CAAC,GAAG,IAAe;IACzC,IAAI,CAAC,IAAI,EAAE;QAAE,OAAO;IACpB,sCAAsC;IACtC,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,GAAG,IAAI,CAAC,CAAC;AAC5C,CAAC"}