wmcp-annotate 1.0.0

package/specs/generate-command.md

@@ -0,0 +1,147 @@
+# Spec: Generate Command
+
+## JTBD
+As a developer, I want to generate ready-to-use JavaScript/TypeScript code that implements WebMCP tool registrations, so I can copy-paste it into my project.
+
+## Command
+```bash
+wmcp-annotate generate <url> [options]
+
+Options:
+  --suggest-file, -s   Use existing suggestions instead of live analysis
+  --output, -o         Output file
+  --format, -f         Output format: js, ts, react, vue, svelte
+  --module, -m         Module format: esm, cjs
+```
+
+## Behavior
+
+### Input
+- URL to analyze (or existing suggestions file)
+- Output format preference
+
+### Process
+1. Run suggest (or load suggestions file)
+2. For each tool:
+   - Generate registration code
+   - Add execute handler stub
+   - Include comments with implementation hints
+3. Wrap in appropriate module format
+4. Add TypeScript types if ts format
+
+### Output Examples
+
+#### JavaScript (ESM)
+```javascript
+// WebMCP Tool Registration
+// Generated by wmcp-annotate
+// URL: https://example.com
+
+// Tool: searchProducts
+// Search for products by keyword, category, or filters
+navigator.modelContext.registerTool({
+  name: "searchProducts",
+  description: "Search for products by keyword, category, or filters",
+  readOnly: true,
+  inputSchema: {
+    type: "object",
+    properties: {
+      query: {
+        type: "string",
+        description: "Search keywords"
+      },
+      category: {
+        type: "string",
+        enum: ["electronics", "clothing", "home"]
+      }
+    },
+    required: ["query"]
+  },
+  async execute({ query, category }) {
+    // TODO: Implement search logic
+    // Suggested implementation:
+    // 1. Find form: document.querySelector('#search-form')
+    // 2. Fill inputs with provided values
+    // 3. Submit form or make API call
+    // 4. Return results
+
+    const form = document.querySelector('#search-form');
+    const queryInput = form.querySelector('input[name="query"]');
+    const categorySelect = form.querySelector('select[name="category"]');
+    
+    queryInput.value = query;
+    if (category) categorySelect.value = category;
+    
+    // Trigger search
+    form.dispatchEvent(new Event('submit'));
+    
+    // Wait for results (implement based on your app)
+    await new Promise(r => setTimeout(r, 1000));
+    
+    const results = document.querySelectorAll('.product-item');
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify(Array.from(results).map(el => ({
+          name: el.querySelector('.name')?.textContent,
+          price: el.querySelector('.price')?.textContent
+        })))
+      }]
+    };
+  }
+});
+```
+
+#### TypeScript
+```typescript
+// WebMCP Tool Registration
+// Generated by wmcp-annotate
+
+interface SearchProductsInput {
+  query: string;
+  category?: "electronics" | "clothing" | "home";
+}
+
+navigator.modelContext.registerTool({
+  name: "searchProducts",
+  description: "Search for products by keyword, category, or filters",
+  readOnly: true,
+  inputSchema: { /* ... */ },
+  async execute(input: SearchProductsInput) {
+    // Implementation
+  }
+});
+```
+
+#### React Hook
+```typescript
+// useWebMCPTools.ts
+import { useEffect } from 'react';
+
+export function useWebMCPTools() {
+  useEffect(() => {
+    if (!navigator.modelContext) return;
+    
+    const cleanup = navigator.modelContext.registerTool({
+      name: "searchProducts",
+      // ...
+    });
+    
+    return () => cleanup?.();
+  }, []);
+}
+```
+
+## Tests
+1. Generate JS → valid JavaScript that runs
+2. Generate TS → valid TypeScript that compiles
+3. Generate React → valid React hook
+4. Multiple tools → all registered
+5. Complex schemas → properly typed
+
+## Templates
+Store templates in `templates/` directory:
+- `templates/js-esm.hbs`
+- `templates/ts.hbs`
+- `templates/react.hbs`
+- `templates/vue.hbs`

package/specs/scan-command.md

@@ -0,0 +1,92 @@
+# Spec: Scan Command
+
+## JTBD
+As a developer, I want to scan any website and identify elements that could become WebMCP tools, so I can understand what annotations my site needs.
+
+## Command
+```bash
+wmcp-annotate scan <url> [options]
+
+Options:
+  --depth <n>       How many pages deep to crawl (default: 1)
+  --output, -o      Output file
+  --format, -f      Output format: json, table, markdown
+  --verbose, -v     Show detailed progress
+```
+
+## Behavior
+
+### Input
+- URL of website to scan
+- Optional: crawl depth, output preferences
+
+### Process
+1. Launch headless browser (Playwright)
+2. Navigate to URL
+3. Wait for page load (network idle)
+4. Identify actionable elements:
+   - Forms (with inputs, selects, textareas)
+   - Buttons (submit, action buttons)
+   - Links (navigation, actions)
+   - AJAX/fetch calls (intercepted)
+5. For each element, extract:
+   - Type (form, button, link, api)
+   - Selector (CSS/XPath)
+   - Visible text/label
+   - Input fields (for forms)
+   - Current values
+6. If depth > 1, follow links and repeat
+
+### Output
+```json
+{
+  "url": "https://example.com",
+  "scannedAt": "2026-02-24T02:45:00Z",
+  "elements": [
+    {
+      "type": "form",
+      "id": "search-form",
+      "selector": "#search-form",
+      "label": "Search",
+      "inputs": [
+        {
+          "name": "query",
+          "type": "text",
+          "label": "Search query",
+          "required": true
+        }
+      ],
+      "submitButton": {
+        "selector": "#search-form button[type=submit]",
+        "label": "Search"
+      }
+    },
+    {
+      "type": "button",
+      "selector": ".add-to-cart",
+      "label": "Add to Cart",
+      "context": "product-page"
+    }
+  ],
+  "apiCalls": [
+    {
+      "method": "GET",
+      "url": "/api/products",
+      "params": ["category", "limit"]
+    }
+  ]
+}
+```
+
+## Tests
+1. Scan a simple static site → finds forms and links
+2. Scan a SPA (React) → finds dynamic elements
+3. Scan with depth=2 → follows links
+4. Scan site with API calls → intercepts fetch/XHR
+5. Handle errors (404, timeout, blocked)
+
+## Edge Cases
+- Sites that block headless browsers → retry with stealth
+- SPAs that need interaction to reveal elements → basic interaction
+- Infinite scroll → limit to visible content
+- Auth-required pages → accept cookies/headers option

package/specs/suggest-command.md

@@ -0,0 +1,120 @@
+# Spec: Suggest Command
+
+## JTBD
+As a developer, I want to get AI-powered suggestions for WebMCP tool definitions based on my site's elements, so I can quickly understand what tools to implement.
+
+## Command
+```bash
+wmcp-annotate suggest <url> [options]
+
+Options:
+  --scan-file, -s   Use existing scan output instead of live scan
+  --output, -o      Output file
+  --format, -f      Output format: json, yaml
+```
+
+## Behavior
+
+### Input
+- URL to analyze (or existing scan file)
+
+### Process
+1. Run scan (or load scan file)
+2. For each identified element:
+   - Analyze semantic meaning using AI
+   - Determine appropriate tool name (camelCase, descriptive)
+   - Generate inputSchema (JSON Schema)
+   - Write human-readable description
+   - Identify if read-only (no confirmation needed)
+3. Group tools logically
+4. Add metadata (version, author hints)
+
+### Output
+```json
+{
+  "version": "1.0.0",
+  "tools": [
+    {
+      "name": "searchProducts",
+      "description": "Search for products by keyword, category, or filters",
+      "readOnly": true,
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "query": {
+            "type": "string",
+            "description": "Search keywords"
+          },
+          "category": {
+            "type": "string",
+            "enum": ["electronics", "clothing", "home"],
+            "description": "Product category filter"
+          },
+          "maxPrice": {
+            "type": "number",
+            "description": "Maximum price filter"
+          }
+        },
+        "required": ["query"]
+      },
+      "sourceElement": {
+        "type": "form",
+        "selector": "#search-form"
+      }
+    },
+    {
+      "name": "addToCart",
+      "description": "Add a product to the shopping cart",
+      "readOnly": false,
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "productId": {
+            "type": "string",
+            "description": "Product identifier"
+          },
+          "quantity": {
+            "type": "integer",
+            "default": 1,
+            "minimum": 1
+          }
+        },
+        "required": ["productId"]
+      },
+      "sourceElement": {
+        "type": "button",
+        "selector": ".add-to-cart"
+      }
+    }
+  ]
+}
+```
+
+## AI Analysis Prompt
+```
+Given this website element:
+- Type: {type}
+- Label: {label}
+- Inputs: {inputs}
+- Context: {context}
+
+Generate a WebMCP tool definition:
+1. Tool name (camelCase, action-oriented verb)
+2. Description (1-2 sentences, what it does)
+3. Is it read-only? (search/view = yes, create/update/delete = no)
+4. Input schema (JSON Schema with descriptions)
+
+Follow WebMCP spec conventions.
+```
+
+## Tests
+1. Form → generates tool with input schema matching form fields
+2. Button → generates action tool
+3. Search form → marks as readOnly: true
+4. Checkout button → marks as readOnly: false
+5. Complex form → handles nested fields
+
+## Rate Limiting
+- Free tier: 10 suggestions/day
+- Pro tier: unlimited
+- Cache results for same URL (1 hour TTL)

package/specs/validate-command.md

@@ -0,0 +1,108 @@
+# Spec: Validate Command
+
+## JTBD
+As a developer, I want to validate my existing WebMCP implementation against the W3C spec, so I can ensure compatibility with AI agents.
+
+## Command
+```bash
+wmcp-annotate validate <url> [options]
+
+Options:
+  --output, -o      Output file
+  --format, -f      Output format: json, table, markdown
+  --strict          Fail on warnings (not just errors)
+  --ci              Exit code 1 on any issues (for CI)
+```
+
+## Behavior
+
+### Input
+- URL of site with WebMCP implementation
+
+### Process
+1. Launch browser with WebMCP flag enabled
+2. Navigate to URL
+3. Query `navigator.modelContext.tools` or equivalent
+4. For each registered tool, validate:
+   - Name follows conventions (camelCase, no spaces)
+   - Description is present and meaningful
+   - inputSchema is valid JSON Schema
+   - Required fields are specified
+   - Types are correct
+   - Execute handler is async function
+   - ReadOnly hint is appropriate
+5. Test tool execution (optional, with --test flag)
+6. Generate report
+
+### Output
+```json
+{
+  "url": "https://example.com",
+  "validatedAt": "2026-02-24T03:00:00Z",
+  "summary": {
+    "total": 5,
+    "valid": 4,
+    "warnings": 1,
+    "errors": 0
+  },
+  "tools": [
+    {
+      "name": "searchProducts",
+      "status": "valid",
+      "checks": {
+        "nameConvention": "pass",
+        "descriptionPresent": "pass",
+        "schemaValid": "pass",
+        "handlerAsync": "pass"
+      }
+    },
+    {
+      "name": "checkout",
+      "status": "warning",
+      "checks": {
+        "nameConvention": "pass",
+        "descriptionPresent": "warning",
+        "schemaValid": "pass",
+        "handlerAsync": "pass"
+      },
+      "issues": [
+        {
+          "level": "warning",
+          "code": "DESCRIPTION_TOO_SHORT",
+          "message": "Description should be at least 20 characters",
+          "suggestion": "Add more detail about what this tool does"
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Validation Rules
+
+| Rule | Level | Description |
+|------|-------|-------------|
+| NAME_FORMAT | error | Name must be camelCase, alphanumeric |
+| NAME_LENGTH | warning | Name should be 3-50 characters |
+| DESCRIPTION_MISSING | error | Description is required |
+| DESCRIPTION_TOO_SHORT | warning | Description < 20 chars |
+| SCHEMA_INVALID | error | inputSchema must be valid JSON Schema |
+| SCHEMA_NO_DESCRIPTION | warning | Properties should have descriptions |
+| HANDLER_NOT_ASYNC | error | Execute must be async function |
+| HANDLER_MISSING | error | Execute handler is required |
+| READONLY_HINT | warning | Consider marking read-only tools |
+
+## Tests
+1. Valid implementation → all pass
+2. Missing description → error reported
+3. Invalid schema → error reported
+4. Sync handler → error reported
+5. --ci flag → exits 1 on errors
+6. --strict flag → exits 1 on warnings
+
+## CI Integration Example
+```yaml
+# .github/workflows/webmcp.yml
+- name: Validate WebMCP
+  run: npx wmcp-annotate validate ${{ env.DEPLOY_URL }} --ci
+```

package/src/commands/generate.ts

@@ -0,0 +1,48 @@
+import type { GenerateOptions, SuggestResult } from '../types.js';
+import { generator } from '../lib/generator.js';
+import { analyzer } from '../lib/analyzer.js';
+import { scanner } from '../lib/scanner.js';
+import { writeOutput, readInput } from '../lib/output.js';
+import ora from 'ora';
+import chalk from 'chalk';
+
+export async function generateCommand(url: string | undefined, options: GenerateOptions): Promise<void> {
+  const spinner = ora('Generating...').start();
+  
+  try {
+    // Get suggestions (from file or live analysis)
+    let suggestions: SuggestResult;
+    if (options.suggestFile) {
+      spinner.text = 'Loading suggestions file...';
+      suggestions = await readInput<SuggestResult>(options.suggestFile);
+    } else if (url) {
+      spinner.text = `Scanning ${url}...`;
+      const scanResult = await scanner.scan(url, { depth: 1 });
+      
+      spinner.text = 'Generating tool suggestions...';
+      suggestions = await analyzer.suggest(scanResult);
+    } else {
+      throw new Error('Either URL or --suggest-file is required');
+    }
+    
+    spinner.text = `Generating ${options.format.toUpperCase()} code...`;
+    const code = await generator.generate(suggestions, {
+      format: options.format as 'js' | 'ts' | 'react' | 'vue',
+      module: options.module as 'esm' | 'cjs',
+    });
+    
+    spinner.succeed(`Generated code for ${suggestions.tools.length} tools`);
+    
+    if (options.output) {
+      const fs = await import('fs/promises');
+      await fs.writeFile(options.output, code, 'utf-8');
+      console.log(chalk.green(`\\nSaved to ${options.output}`));
+    } else {
+      console.log('\\n' + code);
+    }
+  } catch (error) {
+    spinner.fail('Generation failed');
+    console.error(chalk.red(error instanceof Error ? error.message : 'Unknown error'));
+    process.exit(1);
+  }
+}

package/src/commands/scan.ts

@@ -0,0 +1,28 @@
+import type { ScanOptions, ScanResult } from '../types.js';
+import { scanner } from '../lib/scanner.js';
+import { writeOutput } from '../lib/output.js';
+import ora from 'ora';
+import chalk from 'chalk';
+
+export async function scanCommand(url: string, options: ScanOptions): Promise<void> {
+  const spinner = ora(`Scanning ${url}...`).start();
+  
+  try {
+    const result = await scanner.scan(url, {
+      depth: parseInt(options.depth, 10),
+      verbose: options.verbose,
+    });
+    
+    spinner.succeed(`Found ${result.elements.length} elements and ${result.apiCalls.length} API calls`);
+    
+    await writeOutput(result, options);
+    
+    if (!options.output) {
+      console.log(chalk.dim('\\nUse --output to save results to a file'));
+    }
+  } catch (error) {
+    spinner.fail('Scan failed');
+    console.error(chalk.red(error instanceof Error ? error.message : 'Unknown error'));
+    process.exit(1);
+  }
+}

package/src/commands/suggest.ts

@@ -0,0 +1,39 @@
+import type { SuggestOptions, SuggestResult, ScanResult } from '../types.js';
+import { analyzer } from '../lib/analyzer.js';
+import { scanner } from '../lib/scanner.js';
+import { writeOutput, readInput } from '../lib/output.js';
+import ora from 'ora';
+import chalk from 'chalk';
+
+export async function suggestCommand(url: string | undefined, options: SuggestOptions): Promise<void> {
+  const spinner = ora('Analyzing...').start();
+  
+  try {
+    // Get scan results (from file or live scan)
+    let scanResult: ScanResult;
+    if (options.scanFile) {
+      spinner.text = 'Loading scan file...';
+      scanResult = await readInput<ScanResult>(options.scanFile);
+    } else if (url) {
+      spinner.text = `Scanning ${url}...`;
+      scanResult = await scanner.scan(url, { depth: 1 });
+    } else {
+      throw new Error('Either URL or --scan-file is required');
+    }
+    
+    spinner.text = 'Generating tool suggestions with AI...';
+    const result = await analyzer.suggest(scanResult);
+    
+    spinner.succeed(`Generated ${result.tools.length} tool suggestions`);
+    
+    await writeOutput(result, options);
+    
+    if (!options.output) {
+      console.log(chalk.dim('\\nUse --output to save results to a file'));
+    }
+  } catch (error) {
+    spinner.fail('Suggestion failed');
+    console.error(chalk.red(error instanceof Error ? error.message : 'Unknown error'));
+    process.exit(1);
+  }
+}

package/src/commands/validate.ts

@@ -0,0 +1,44 @@
+import type { ValidateOptions, ValidationResult } from '../types.js';
+import { validator } from '../lib/validator.js';
+import { writeOutput } from '../lib/output.js';
+import ora from 'ora';
+import chalk from 'chalk';
+
+export async function validateCommand(url: string, options: ValidateOptions): Promise<void> {
+  const spinner = ora(`Validating ${url}...`).start();
+  
+  try {
+    const result = await validator.validate(url);
+    
+    const { summary } = result;
+    
+    if (summary.errors > 0) {
+      spinner.fail(`Validation failed: ${summary.errors} errors, ${summary.warnings} warnings`);
+    } else if (summary.warnings > 0) {
+      spinner.warn(`Validation passed with ${summary.warnings} warnings`);
+    } else {
+      spinner.succeed(`Validation passed: ${summary.total} tools validated`);
+    }
+    
+    await writeOutput(result, options);
+    
+    // Handle CI mode
+    if (options.ci) {
+      if (summary.errors > 0 || (options.strict && summary.warnings > 0)) {
+        process.exit(1);
+      }
+    }
+    
+    // Print summary
+    console.log('\\n' + chalk.bold('Summary:'));
+    console.log(`  Total tools: ${summary.total}`);
+    console.log(`  Valid: ${chalk.green(summary.valid)}`);
+    console.log(`  Warnings: ${chalk.yellow(summary.warnings)}`);
+    console.log(`  Errors: ${chalk.red(summary.errors)}`);
+    
+  } catch (error) {
+    spinner.fail('Validation failed');
+    console.error(chalk.red(error instanceof Error ? error.message : 'Unknown error'));
+    process.exit(1);
+  }
+}

package/src/index.ts

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { scanCommand } from './commands/scan.js';
+import { suggestCommand } from './commands/suggest.js';
+import { generateCommand } from './commands/generate.js';
+import { validateCommand } from './commands/validate.js';
+
+const program = new Command();
+
+program
+  .name('wmcp-annotate')
+  .description('Make any website AI-agent ready with WebMCP annotations')
+  .version('1.0.0');
+
+program
+  .command('scan <url>')
+  .description('Analyze a website for WebMCP opportunities')
+  .option('-d, --depth <number>', 'How many pages deep to crawl', '1')
+  .option('-o, --output <file>', 'Output file')
+  .option('-f, --format <format>', 'Output format: json, table, markdown', 'json')
+  .option('-v, --verbose', 'Show detailed progress')
+  .action(scanCommand);
+
+program
+  .command('suggest [url]')
+  .description('Generate AI-powered WebMCP tool suggestions')
+  .option('-s, --scan-file <file>', 'Use existing scan output')
+  .option('-o, --output <file>', 'Output file')
+  .option('-f, --format <format>', 'Output format: json, yaml', 'json')
+  .action(suggestCommand);
+
+program
+  .command('generate [url]')
+  .description('Generate WebMCP registration code')
+  .option('-s, --suggest-file <file>', 'Use existing suggestions')
+  .option('-o, --output <file>', 'Output file')
+  .option('-f, --format <format>', 'Output format: js, ts, react, vue', 'js')
+  .option('-m, --module <type>', 'Module format: esm, cjs', 'esm')
+  .action(generateCommand);
+
+program
+  .command('validate <url>')
+  .description('Validate WebMCP implementation')
+  .option('-o, --output <file>', 'Output file')
+  .option('-f, --format <format>', 'Output format: json, table, markdown', 'json')
+  .option('--strict', 'Fail on warnings')
+  .option('--ci', 'Exit code 1 on any issues')
+  .action(validateCommand);
+
+program.parse();