wmcp-annotate

The missing bridge between today's web and tomorrow's AI agents

The WebMCP Moment

In February 2026, Google and Microsoft shipped WebMCP in Chrome 146 — a W3C standard that lets websites declare structured tools for AI agents.

This isn't incremental. It's architectural.

Before WebMCP: Agents scraped DOM (fragile) or parsed screenshots (expensive). After WebMCP: Websites declare capabilities. Agents call tools directly.

The problem isn't the standard. It's adoption. 99% of websites have zero WebMCP annotations.

That's why this exists.

Installation

Option 1: Install globally (recommended)

npm install -g wmcp-annotate
wmcp-annotate scan https://example.com

Option 2: Run directly with npx

npx wmcp-annotate scan https://example.com

Option 3: Run from GitHub (no npm publish needed)

npx github:rsatyan/wmcp-annotate scan https://example.com

Note: Option 3 requires npm 10+. Check with npm --version and update with npm install -g npm@latest if needed.

Zero additional setup required. Works instantly for static HTML sites.

Quick Start

# Scan a website (instant, no dependencies)
wmcp-annotate scan https://example.com

# Generate WebMCP tool definitions with AI
wmcp-annotate suggest https://example.com

# Output production-ready code
wmcp-annotate generate https://example.com --format typescript

Commands

scan — Analyze a website

Discovers forms, buttons, links, and interactive elements.

# Default: Fast HTML parsing (works for most sites)
wmcp-annotate scan https://example.com

# For JavaScript-heavy SPAs (requires Playwright setup)
wmcp-annotate scan https://react-app.com --browser

Output:

{
  "url": "https://example.com",
  "elements": [
    {
      "type": "form",
      "selector": "#search",
      "label": "Search",
      "inputs": [{ "name": "q", "type": "text" }]
    }
  ]
}

suggest — Generate tool definitions

Uses AI to create meaningful WebMCP tool definitions from scan results.

wmcp-annotate suggest https://example.com
wmcp-annotate suggest https://react-app.com --browser  # For SPAs
wmcp-annotate suggest --scan-file scan.json --output tools.json

Requires an AI provider (see Configuration).

generate — Output production code

Creates ready-to-use JavaScript/TypeScript code.

wmcp-annotate generate https://example.com --format js
wmcp-annotate generate https://example.com --format ts
wmcp-annotate generate https://example.com --format react
wmcp-annotate generate https://react-app.com --browser --format ts  # For SPAs

validate — Check compliance

Validates existing WebMCP implementations against the spec.

wmcp-annotate validate https://example.com
wmcp-annotate validate https://example.com --ci  # Exit 1 on issues

AI Provider Configuration

The suggest command requires an AI provider. Configure one:

OpenAI:

export OPENAI_API_KEY=sk-...

Anthropic:

export ANTHROPIC_API_KEY=sk-ant-...
npm install @anthropic-ai/sdk  # Required for Anthropic

OpenAI-compatible APIs (Groq, Together, etc.):

export OPENAI_API_KEY=your_key
export OPENAI_BASE_URL=https://api.groq.com/openai
export WMCP_MODEL=llama-3.3-70b-versatile

Ollama (local, free):

export OLLAMA_HOST=http://localhost:11434
export WMCP_MODEL=llama3

Browser Mode (for SPAs)

By default, wmcp-annotate uses fast HTML parsing which works for 80%+ of websites.

For JavaScript-heavy single-page apps (React, Vue, Angular), use --browser mode:

# One-time setup
npm install playwright
npx playwright install chromium

# Scan with browser engine
wmcp-annotate scan https://react-app.com --browser

Example Output

Generated code is fully compliant with the WebMCP spec:

navigator.modelContext.registerTool({
  name: "searchProducts",
  description: "Search the product catalog by keyword",
  inputSchema: {
    type: "object",
    properties: {
      query: { type: "string", description: "Search terms" }
    },
    required: ["query"]
  },
  annotations: { readOnlyHint: true },
  async execute({ query }, client) {
    const form = document.querySelector('#search-form');
    form.querySelector('input[name="q"]').value = query;
    form.submit();
    return {
      content: [{ type: "text", text: JSON.stringify({ success: true }) }]
    };
  }
});

Why Open Source?

WebMCP adoption benefits everyone building AI agents. Gatekeeping the tooling slows the ecosystem.

This tool is MIT licensed. Fork it. Ship it. Make it better.

Author

Satyan Avatara
📧 [email protected]

Building at the intersection of AI, web infrastructure, and financial services.

License

MIT — use it, fork it, ship it.