auto-webmcp 0.3.0 → 0.3.2

package/README.md

@@ -37,10 +37,11 @@ await autoWebMCP();
 ## What it does
 
 1. Scans the page for all `<form>` elements (on load + dynamically via `MutationObserver`)
-2. Infers a meaningful **tool name**, **description**, and **JSON Schema** from the form's DOM
-3. Registers each form as a WebMCP tool via `navigator.modelContext.registerTool()`
-4. Intercepts submissions to return structured results back to the agent
-5. Degrades silently in browsers without WebMCP
+2. Also discovers inputs **outside** `<form>` tags (orphan input groups) and inputs inside **Web Component shadow roots**
+3. Infers a meaningful **tool name**, **description**, and **JSON Schema** from the form's DOM
+4. Registers each form as a WebMCP tool via `navigator.modelContext.registerTool()`
+5. Intercepts submissions to return structured results back to the agent
+6. Degrades silently in browsers without WebMCP
 
 ---
 
@@ -50,15 +51,12 @@ await autoWebMCP();
 import { autoWebMCP } from 'auto-webmcp';
 
 await autoWebMCP({
-  // Skip specific forms
+  // Skip specific forms (CSS selectors)
   exclude: ['#login-form', '[data-no-webmcp]'],
 
   // Auto-submit when agent invokes (default: false — human must click submit)
   autoSubmit: false,
 
-  // Optional AI enrichment for richer descriptions
-  enhance: { provider: 'claude', apiKey: 'sk-...' },
-
   // Per-form name / description overrides
   overrides: {
     '#checkout-form': {
@@ -74,7 +72,23 @@ await autoWebMCP({
 
 ### Per-form HTML overrides
 
-Override individual forms without JavaScript:
+**Native WebMCP spec attributes** (highest priority):
+
+```html
+<form
+  toolname="book_appointment"
+  tooldescription="Book a doctor appointment"
+  toolautosubmit
+>
+  <input
+    name="date"
+    type="date"
+    toolparamdescription="Preferred appointment date"
+  >
+</form>
+```
+
+**data-webmcp-* attributes** (fallback, useful when you cannot edit the form element directly):
 
 ```html
 <form
@@ -88,7 +102,6 @@ Override individual forms without JavaScript:
     data-webmcp-title="Appointment Date"
     data-webmcp-description="Preferred appointment date"
   >
-  …
 </form>
 ```
 
@@ -102,36 +115,131 @@ Override individual forms without JavaScript:
 
 ## Tool name inference (priority order)
 
-1. `data-webmcp-name` attribute on `<form>`
-2. Submit button text (e.g. "Search Flights" → `search_flights`)
-3. Nearest `<h1>`–`<h3>` heading above the form
-4. Form `id` or `name` attribute
-5. Last segment of form `action` URL
-6. Fallback: `form_N`
+1. `toolname` native attribute on `<form>` (WebMCP spec)
+2. `data-webmcp-name` attribute on `<form>`
+3. Submit button text (e.g. "Search Flights" → `search_flights`)
+4. Nearest `<h1>`–`<h3>` heading above the form
+5. Form `id` or `name` attribute
+6. Last segment of form `action` URL
+7. Fallback: `form_N`
 
 ## Tool description inference (priority order)
 
-1. `data-webmcp-description` attribute on `<form>`
-2. `<legend>` text inside the form
-3. `aria-label` on the form
-4. `aria-describedby` target
-5. Nearest heading + page `<title>`
+1. `tooldescription` native attribute on `<form>` (WebMCP spec)
+2. `data-webmcp-description` attribute on `<form>`
+3. `<legend>` text inside the form
+4. `aria-label` on the form
+5. `aria-describedby` target
+6. Nearest heading + page `<title>`
+
+## Field title inference (priority order)
+
+1. `data-webmcp-title` attribute on the field
+2. Associated `<label>` text
+3. `name` attribute (humanized)
+4. `id` attribute (humanized)
+5. `placeholder` text
+
+## Field description inference (priority order)
+
+1. `toolparamdescription` native attribute on the field (WebMCP spec)
+2. `data-webmcp-description` attribute on the field
+3. `aria-description` / `aria-describedby` target
+4. `placeholder` text
+
+---
 
 ## HTML → JSON Schema mapping
 
-| HTML type              | JSON Schema             |
-|------------------------|-------------------------|
-| `text`, `search`, `tel`| `string`                |
-| `email`                | `string` + format:email |
-| `url`                  | `string` + format:uri   |
-| `number`, `range`      | `number` (+ min/max)    |
-| `date`                 | `string` + format:date  |
-| `datetime-local`       | `string` + format:date-time |
-| `checkbox`             | `boolean`               |
-| `radio`                | `string` + enum         |
-| `select`               | `string` + enum         |
-| `textarea`             | `string`                |
-| `file`, `hidden`, `password` | _skipped_         |
+| HTML input                   | JSON Schema                        |
+|------------------------------|------------------------------------|
+| `text`, `search`, `tel`      | `string`                           |
+| `email`                      | `string` + `format: email`         |
+| `url`                        | `string` + `format: uri`           |
+| `number`, `range`            | `number` (+ `min` / `max`)         |
+| `date`                       | `string` + `format: date`          |
+| `datetime-local`             | `string` + `format: date-time`     |
+| `checkbox`                   | `boolean`                          |
+| checkbox group (same `name`) | `array` + `items.enum`             |
+| `radio` group                | `string` + `enum` + `oneOf`        |
+| `select`                     | `string` + `enum` + `oneOf`        |
+| `select[multiple]`           | `array` + `items.enum`             |
+| `textarea`                   | `string`                           |
+| ARIA role inputs             | mapped by role (textbox, checkbox…) |
+| `file`, `hidden`, `password` | _skipped_                          |
+
+Additional schema enrichment:
+- Pre-filled field values are exposed as `schema.default`
+- `<optgroup>` labels and `<datalist>` suggestions are included as metadata
+- Disabled select options and placeholder options (`"Select..."`, `"---"`) are excluded
+
+---
+
+## ToolAnnotations
+
+auto-webmcp automatically infers [WebMCP ToolAnnotations](https://webmachinelearning.github.io/webmcp/) from your HTML:
+
+| Annotation | Auto-inferred when |
+|---|---|
+| `readOnlyHint` | Form method is `GET`, or submit button says "Search", "Find", etc. |
+| `destructiveHint` | Submit button says "Delete", "Remove", "Cancel", etc. |
+| `idempotentHint` | Form is read-only or GET |
+| `openWorldHint` | Form modifies data (default for POST forms) |
+
+Override any annotation with data attributes:
+
+```html
+<form
+  data-webmcp-destructive="true"
+  data-webmcp-openworld="true"
+>
+  <!-- delete account form -->
+</form>
+```
+
+---
+
+## Advanced discovery
+
+### Shadow DOM (Web Components)
+
+Inputs inside custom element shadow roots are automatically discovered and included in the schema. No extra configuration needed.
+
+```html
+<form>
+  <custom-date-picker></custom-date-picker> <!-- shadow root inputs discovered -->
+  <button type="submit">Book</button>
+</form>
+```
+
+### Orphan inputs (no `<form>` tag)
+
+Input groups not wrapped in a `<form>` element (common in SPAs) are detected by finding the nearest ancestor that contains a visible submit button. Each group is registered as a separate tool.
+
+### React and framework-managed forms
+
+auto-webmcp fills React-controlled inputs using native `HTMLInputElement` prototype setters and `execCommand` to trigger `onChange`. A post-fill snapshot preserves field values if the framework re-renders before submit.
+
+---
+
+## Structured execute result
+
+Every tool execution returns a two-item `content` array:
+
+- `content[0].text` — human-readable summary: `"Form submitted. Fields: {...}"`
+- `content[1].text` — JSON-stringified structured data:
+
+```json
+{
+  "status": "success",
+  "filled_fields": { "email": "a@b.com", "frequency": "weekly" },
+  "skipped_fields": [],
+  "missing_required": [],
+  "warnings": []
+}
+```
+
+`status` is `"partial"` when required fields were missing or a value was clamped. Each warning in the `warnings` array has a `field`, `type` (`clamped`, `not_filled`, `missing_required`, `type_mismatch`), `message`, and optionally `original` / `actual` values.
 
 ---
 
@@ -148,12 +256,23 @@ handle.destroy()     // Promise<void> — unregister all tools & stop observing
 ### Events
 
 ```js
+// auto-webmcp lifecycle events
 window.addEventListener('form:registered', (e) => {
   console.log('Registered:', e.detail.toolName, e.detail.form);
 });
 window.addEventListener('form:unregistered', (e) => {
   console.log('Removed:', e.detail.toolName);
 });
+
+// WebMCP spec events
+window.addEventListener('toolactivated', (e) => {
+  // Agent has filled the form fields, waiting for submit
+  console.log('Agent activated:', e.detail.toolName);
+});
+window.addEventListener('toolcancel', (e) => {
+  // User reset the form or agent cancelled
+  console.log('Cancelled:', e.detail.toolName);
+});
 ```
 
 ### Prevent auto-init (IIFE build)
@@ -177,16 +296,15 @@ npm install
 npm run build          # compile to dist/
 npm run build:watch    # rebuild on change
 npm run typecheck      # TypeScript type check only
-npm test               # Playwright integration tests
+npm test               # Playwright integration tests (Chromium)
 ```
 
 ---
 
 ## Browser support
 
-- Chrome 146+ with `#enable-webmcp-testing` flag (or WebMCP GA) for full functionality
-- All other browsers: forms are analyzed and the library loads without error —
-  `navigator.modelContext` calls are silently no-opped (progressive enhancement)
+- Chrome 146+ with `chrome://flags/#enable-webmcp-testing` enabled for full functionality
+- All other browsers: the library loads, analyzes forms, and silently no-ops `navigator.modelContext` calls (progressive enhancement)
 
 ---
 

package/dist/analyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAmJ,MAAM,aAAa,CAAC;AAC1L,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,WAAW,eAAe;IAC9B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,UAAU,CAAC;IACxB,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,6FAA6F;IAC7F,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAKD,iDAAiD;AACjD,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAED,gDAAgD;AAChD,wBAAgB,WAAW,CAAC,IAAI,EAAE,eAAe,EAAE,QAAQ,CAAC,EAAE,YAAY,GAAG,YAAY,CAOxF;AAynBD;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,OAAO,EAClB,MAAM,EAAE,KAAK,CAAC,gBAAgB,GAAG,mBAAmB,GAAG,iBAAiB,CAAC,EACzE,SAAS,EAAE,iBAAiB,GAAG,gBAAgB,GAAG,IAAI,GACrD,YAAY,CAKd"}
+{"version":3,"file":"analyzer.d.ts","sourceRoot":"","sources":["../src/analyzer.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAmJ,MAAM,aAAa,CAAC;AAC1L,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,WAAW,eAAe;IAC9B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,UAAU,CAAC;IACxB,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B,6FAA6F;IAC7F,aAAa,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC;AAKD,iDAAiD;AACjD,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAED,gDAAgD;AAChD,wBAAgB,WAAW,CAAC,IAAI,EAAE,eAAe,EAAE,QAAQ,CAAC,EAAE,YAAY,GAAG,YAAY,CAOxF;AAipBD;;;GAGG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,OAAO,EAClB,MAAM,EAAE,KAAK,CAAC,gBAAgB,GAAG,mBAAmB,GAAG,iBAAiB,CAAC,EACzE,SAAS,EAAE,iBAAiB,GAAG,gBAAgB,GAAG,IAAI,GACrD,YAAY,CAKd"}

package/dist/auto-webmcp.cjs.js

@@ -102,7 +102,6 @@ function resolveConfig(userConfig) {
   return {
     exclude: userConfig?.exclude ?? [],
     autoSubmit: userConfig?.autoSubmit ?? false,
-    enhance: userConfig?.enhance ?? null,
     overrides: userConfig?.overrides ?? {},
     debug: userConfig?.debug ?? false
   };
@@ -503,17 +502,39 @@ function extractDefaultValue(control) {
   }
   return void 0;
 }
+function collectShadowControls(root, visited = /* @__PURE__ */ new Set()) {
+  if (visited.has(root))
+    return [];
+  visited.add(root);
+  const results = [];
+  for (const el of Array.from(root.querySelectorAll("*"))) {
+    if (el.shadowRoot) {
+      results.push(
+        ...Array.from(
+          el.shadowRoot.querySelectorAll(
+            "input, textarea, select"
+          )
+        ),
+        ...collectShadowControls(el.shadowRoot, visited)
+      );
+    }
+  }
+  return results;
+}
 function buildSchema(form) {
   const properties = {};
   const required = [];
   const fieldElements = /* @__PURE__ */ new Map();
   const processedRadioGroups = /* @__PURE__ */ new Set();
   const processedCheckboxGroups = /* @__PURE__ */ new Set();
-  const controls = Array.from(
-    form.querySelectorAll(
-      "input, textarea, select"
-    )
-  );
+  const controls = [
+    ...Array.from(
+      form.querySelectorAll(
+        "input, textarea, select"
+      )
+    ),
+    ...collectShadowControls(form)
+  ];
   for (const control of controls) {
     const name = control.name;
     const fieldKey = name || resolveNativeControlFallbackKey(control);
@@ -691,9 +712,6 @@ function resolveAriaFieldKey(el) {
   return null;
 }
 function inferAriaFieldTitle(el) {
-  const nativeTitle = el.getAttribute("toolparamtitle");
-  if (nativeTitle?.trim())
-    return nativeTitle.trim();
   const htmlEl = el;
   if (htmlEl.dataset?.["webmcpTitle"])
     return htmlEl.dataset["webmcpTitle"];
@@ -732,9 +750,6 @@ function inferAriaFieldDescription(el) {
   return "";
 }
 function inferFieldTitle(control) {
-  const nativeTitle = control.getAttribute("toolparamtitle");
-  if (nativeTitle?.trim())
-    return nativeTitle.trim();
   if ("dataset" in control && control.dataset["webmcpTitle"]) {
     return control.dataset["webmcpTitle"];
   }
@@ -944,6 +959,9 @@ function buildExecuteHandler(form, config, toolName, metadata) {
   return async (params) => {
     pendingFillWarnings.set(form, []);
     fillFormFields(form, params);
+    const missingNow = getMissingRequired(metadata, params);
+    if (missingNow.length > 0)
+      pendingWarnings.set(form, missingNow);
     window.dispatchEvent(new CustomEvent("toolactivated", { detail: { toolName } }));
     return new Promise((resolve, reject) => {
       pendingExecutions.set(form, { resolve, reject });
@@ -970,9 +988,10 @@ function buildExecuteHandler(form, config, toolName, metadata) {
                 attachSubmitInterceptor(submitForm, toolName);
               }
             }
-            const missing = getMissingRequired(metadata, params);
-            if (missing.length > 0)
-              pendingWarnings.set(submitForm, missing);
+            if (submitForm !== form && pendingWarnings.has(form)) {
+              pendingWarnings.set(submitForm, pendingWarnings.get(form));
+              pendingWarnings.delete(form);
+            }
             submitForm.requestSubmit();
           } catch (err) {
             reject(err instanceof Error ? err : new Error(String(err)));
@@ -994,17 +1013,37 @@ function attachSubmitInterceptor(form, toolName) {
     pendingExecutions.delete(form);
     const formData = serializeFormData(form, lastParams.get(form), formFieldElements.get(form));
     lastFilledSnapshot.delete(form);
-    const missing = pendingWarnings.get(form);
+    const missingRequired = pendingWarnings.get(form) ?? [];
     pendingWarnings.delete(form);
     const fillWarnings = pendingFillWarnings.get(form) ?? [];
     pendingFillWarnings.delete(form);
-    const allWarnings = [
-      ...missing?.length ? [`required fields were not filled: ${missing.join(", ")}`] : [],
-      ...fillWarnings
+    const skippedFields = fillWarnings.filter((w) => w.type === "not_filled").map((w) => w.field);
+    const structured = {
+      status: missingRequired.length > 0 || skippedFields.length > 0 ? "partial" : "success",
+      filled_fields: formData,
+      skipped_fields: skippedFields,
+      missing_required: missingRequired,
+      warnings: [
+        ...missingRequired.map((f) => ({
+          field: f,
+          type: "missing_required",
+          message: `required field "${f}" was not provided`
+        })),
+        ...fillWarnings
+      ]
+    };
+    const allWarnMessages = [
+      ...missingRequired.length ? [`required fields were not filled: ${missingRequired.join(", ")}`] : [],
+      ...fillWarnings.map((w) => w.message)
     ];
-    const warningText = allWarnings.length ? ` Note: ${allWarnings.join("; ")}.` : "";
+    const warningText = allWarnMessages.length ? ` Note: ${allWarnMessages.join("; ")}.` : "";
     const text = `Form submitted. Fields: ${JSON.stringify(formData)}${warningText}`;
-    const result = { content: [{ type: "text", text }] };
+    const result = {
+      content: [
+        { type: "text", text },
+        { type: "text", text: JSON.stringify(structured) }
+      ]
+    };
     if (e.agentInvoked && typeof e.respondWith === "function") {
       e.preventDefault();
       e.respondWith(Promise.resolve(result));
@@ -1138,16 +1177,26 @@ function fillInput(input, form, key, value) {
     const raw = String(value ?? "");
     const num = Number(raw);
     if (raw === "" || isNaN(num)) {
-      pendingFillWarnings.get(form)?.push(`"${key}" expects a number, got: ${JSON.stringify(value)}`);
+      pendingFillWarnings.get(form)?.push({
+        field: key,
+        type: "type_mismatch",
+        message: `"${key}" expects a number, got: ${JSON.stringify(value)}`,
+        original: value
+      });
       return;
     }
     const min = input.min !== "" ? parseFloat(input.min) : -Infinity;
     const max = input.max !== "" ? parseFloat(input.max) : Infinity;
     if (num < min || num > max) {
-      pendingFillWarnings.get(form)?.push(
-        `"${key}" value ${num} is outside allowed range [${input.min || "?"}, ${input.max || "?"}]`
-      );
-      input.value = String(Math.min(Math.max(num, min), max));
+      const clamped = Math.min(Math.max(num, min), max);
+      pendingFillWarnings.get(form)?.push({
+        field: key,
+        type: "clamped",
+        message: `"${key}" value ${num} is outside allowed range [${input.min || "?"}, ${input.max || "?"}], clamped to ${clamped}`,
+        original: num,
+        actual: clamped
+      });
+      input.value = String(clamped);
     } else {
       input.value = String(num);
     }
@@ -1334,74 +1383,6 @@ function getMissingRequired(metadata, params) {
   return metadata.inputSchema.required.filter((fieldKey) => !(fieldKey in params));
 }
 
-// src/enhancer.ts
-async function enrichMetadata(metadata, enhancer) {
-  try {
-    const enriched = await callLLM(metadata, enhancer);
-    return { ...metadata, description: enriched };
-  } catch (err) {
-    console.warn("[auto-webmcp] Enrichment failed, using heuristic description:", err);
-    return metadata;
-  }
-}
-async function callLLM(metadata, config) {
-  const prompt = buildPrompt(metadata);
-  if (config.provider === "claude") {
-    return callClaude(prompt, config);
-  } else {
-    return callGemini(prompt, config);
-  }
-}
-function buildPrompt(metadata) {
-  const fields = Object.entries(metadata.inputSchema.properties).map(([name, prop]) => `- ${prop.title ?? name} (${prop.type}): ${prop.description ?? ""}`).join("\n");
-  return `You are helping describe a web form as an AI tool. Given this form information:
-
-Name: ${metadata.name}
-Current description: ${metadata.description}
-Fields:
-${fields}
-
-Write a concise (1-2 sentence) description of what this tool does and when an AI agent should use it. Be specific and actionable. Respond with only the description, no preamble.`;
-}
-async function callClaude(prompt, config) {
-  const model = config.model ?? "claude-haiku-4-5-20251001";
-  const response = await fetch("https://api.anthropic.com/v1/messages", {
-    method: "POST",
-    headers: {
-      "x-api-key": config.apiKey,
-      "anthropic-version": "2023-06-01",
-      "content-type": "application/json"
-    },
-    body: JSON.stringify({
-      model,
-      max_tokens: 150,
-      messages: [{ role: "user", content: prompt }]
-    })
-  });
-  if (!response.ok) {
-    throw new Error(`Claude API error: ${response.status}`);
-  }
-  const data = await response.json();
-  return data.content.filter((block) => block.type === "text").map((block) => block.text).join("").trim();
-}
-async function callGemini(prompt, config) {
-  const model = config.model ?? "gemini-1.5-flash";
-  const url = `https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=${config.apiKey}`;
-  const response = await fetch(url, {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({
-      contents: [{ parts: [{ text: prompt }] }],
-      generationConfig: { maxOutputTokens: 150, temperature: 0.2 }
-    })
-  });
-  if (!response.ok) {
-    throw new Error(`Gemini API error: ${response.status}`);
-  }
-  const data = await response.json();
-  return data.candidates[0]?.content.parts.map((p) => p.text).join("").trim() ?? "";
-}
-
 // src/discovery.ts
 function emit(type, form, toolName) {
   window.dispatchEvent(
@@ -1433,12 +1414,7 @@ async function registerForm(form, config) {
     } catch {
     }
   }
-  let metadata = analyzeForm(form, override);
-  if (config.enhance) {
-    if (config.debug)
-      console.debug(`[auto-webmcp] Enriching: ${metadata.name}\u2026`);
-    metadata = await enrichMetadata(metadata, config.enhance);
-  }
+  const metadata = analyzeForm(form, override);
   if (config.debug) {
     warnToolQuality(metadata.name, metadata.description);
   }