auto-webmcp 0.3.1 → 0.3.3

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/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
   };
@@ -430,7 +429,7 @@ function inferToolDescription(form) {
   const heading = getNearestHeadingText(form);
   const pageTitle = document.title?.trim();
   if (heading && pageTitle)
-    return `${heading} \u2014 ${pageTitle}`;
+    return `${heading}: ${pageTitle}`;
   if (heading)
     return heading;
   if (pageTitle)
@@ -959,6 +958,7 @@ function buildExecuteHandler(form, config, toolName, metadata) {
   attachSubmitInterceptor(form, toolName);
   return async (params) => {
     pendingFillWarnings.set(form, []);
+    pendingWarnings.delete(form);
     fillFormFields(form, params);
     const missingNow = getMissingRequired(metadata, params);
     if (missingNow.length > 0)
@@ -1384,74 +1384,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(
@@ -1483,12 +1415,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);
   }