# WebMCP Tool Catalog

WebMCP exposes public marketing actions as named, callable tools via `navigator.modelContext` (or `document.modelContext` in newer builds). Tools register only when `WEBMCP_ENABLED=True` in Django settings.

## Enablement

### 1. Django setting

```python
# company_site/settings.py (or environment-specific settings)
WEBMCP_ENABLED = True
```

Default is `False` so production stays opt-in until you deliberately enable agent tooling.

### 2. Chrome experimental flag

WebMCP requires the experimental web platform features flag:

1. Open `chrome://flags/#enable-experimental-web-platform-features`
2. Set **Enable experimental web platform features** to **Enabled**
3. Restart Chrome

Serve the site over HTTPS (or `localhost`) — WebMCP requires a secure context.

### 3. Lighthouse audit

```bash
npx lighthouse@latest http://127.0.0.1:8000/contact \
  --only-categories=agentic-browsing \
  --chrome-flags="--enable-experimental-web-platform-features" \
  --output=html --output-path=agentic-browsing-contact.html

npx lighthouse@latest http://127.0.0.1:8000/ \
  --only-categories=agentic-browsing \
  --chrome-flags="--enable-experimental-web-platform-features" \
  --output=html --output-path=agentic-browsing-home.html
```

Run against a local dev server with `WEBMCP_ENABLED=True`. For contact submission audits, `DEBUG=True` skips reCAPTCHA validation.

## Registered tools

| Tool | Pages | readOnly | Description |
|------|-------|----------|-------------|
| `list_services` | All public pages | Yes | Returns service name, slug, URL, and summary |
| `get_page_content` | All public pages | Yes | Look up a page by slug or display name |
| `navigate_to_service` | All public pages | Yes | Resolve a service to its canonical URL |
| `open_contact_with_subject` | All public pages | Yes | Build a contact URL with `?subject=` pre-filled |
| `submit_contact_inquiry` | `/contact` only | No | POST a contact inquiry to the Django contact endpoint |

### `submit_contact_inquiry`

**Input schema:**

| Field | Type | Required |
|-------|------|----------|
| `name` | string | Yes |
| `email` | string | Yes |
| `subject` | string | Yes |
| `message` | string | No |

**Output:** JSON with `success: true` and a confirmation message, or `success: false` with an `error` string.

**reCAPTCHA limitation:** In production (`DEBUG=False`), the contact endpoint requires reCAPTCHA v3. Automated agents cannot complete captcha without a real browser session and the reCAPTCHA widget. For Lighthouse demos, run with `DEBUG=True` or use the declarative HTML form (agent fills fields; user submits manually).

### Declarative form annotation

The contact `<form>` also declares WebMCP coverage via HTML attributes when enabled:

```html
<form toolname="submit_contact_inquiry"
      tooldescription="Submit a contact inquiry to AI ML Operations">
```

This satisfies Lighthouse **form coverage** without duplicating field schemas in JavaScript. The imperative `registerTool` on `/contact` adds structured `execute` behavior with success/error responses.

## Data source

Service metadata is sourced from `PUBLIC_PAGE_ENTRIES` in `public/seo.py` — the same config that powers `sitemap.xml` and `llms.txt`. Navigation tools always stay in sync with SEO endpoints.

## Security scope

- Tools run in the visitor's browser session (no API keys)
- Only unauthenticated marketing flows are exposed
- Planning, financial, and admin actions are **not** registered

## Manual verification

Use [Chrome Labs Awesome WebMCP](https://github.com/chrome-labs/awesome-webmcp) or DevTools console:

```javascript
// Feature-detect (Chrome with experimental flag)
'modelContext' in navigator && typeof navigator.modelContext.registerTool === 'function'
```

With a WebMCP-capable browser on `/`, call `list_services` from the agent UI. On `/contact`, call `submit_contact_inquiry` with test data (DEBUG mode).

## References

- [WebMCP specification overview](https://specification.website/spec/agent-readiness/webmcp/)
- [Google Chrome modern-web-guidance — agentic JavaScript tools](https://github.com/GoogleChrome/modern-web-guidance/blob/main/skills/modern-web-guidance/guides/webmcp/agentic-javascript-tools.md)
- [Awesome WebMCP demos](https://github.com/chrome-labs/awesome-webmcp)
- Gitea issue #9
