wmcp-annotate 1.0.0

package/src/lib/analyzer.ts

@@ -0,0 +1,90 @@
+import Anthropic from '@anthropic-ai/sdk';
+import type { ScanResult, SuggestResult, ToolSuggestion, JsonSchema } from '../types.js';
+
+class Analyzer {
+  private client: Anthropic | null = null;
+
+  private getClient(): Anthropic {
+    if (!this.client) {
+      const apiKey = process.env.ANTHROPIC_API_KEY;
+      if (!apiKey) {
+        throw new Error('ANTHROPIC_API_KEY environment variable is required');
+      }
+      this.client = new Anthropic({ apiKey });
+    }
+    return this.client;
+  }
+
+  async suggest(scanResult: ScanResult): Promise<SuggestResult> {
+    const tools: ToolSuggestion[] = [];
+    
+    for (const element of scanResult.elements) {
+      const suggestion = await this.analyzeElement(element);
+      if (suggestion) {
+        tools.push(suggestion);
+      }
+    }
+    
+    return {
+      version: '1.0.0',
+      url: scanResult.url,
+      suggestedAt: new Date().toISOString(),
+      tools,
+    };
+  }
+
+  private async analyzeElement(element: any): Promise<ToolSuggestion | null> {
+    const client = this.getClient();
+    
+    const prompt = `Analyze this website element and generate a WebMCP tool definition.
+
+Element:
+- Type: ${element.type}
+- Label: ${element.label}
+- Selector: ${element.selector}
+${element.inputs ? `- Inputs: ${JSON.stringify(element.inputs)}` : ''}
+
+Generate a WebMCP tool definition with:
+1. name: camelCase, action-oriented verb (e.g., searchProducts, addToCart)
+2. description: 1-2 sentences explaining what it does
+3. readOnly: true if it's a search/view action, false for create/update/delete
+4. inputSchema: JSON Schema for the inputs
+
+Respond with valid JSON only:
+{
+  "name": "...",
+  "description": "...",
+  "readOnly": true/false,
+  "inputSchema": { ... }
+}`;
+
+    try {
+      const response = await client.messages.create({
+        model: 'claude-sonnet-4-20250514',
+        max_tokens: 1024,
+        messages: [{ role: 'user', content: prompt }],
+      });
+
+      const content = response.content[0];
+      if (content.type !== 'text') return null;
+
+      const json = JSON.parse(content.text);
+      
+      return {
+        name: json.name,
+        description: json.description,
+        readOnly: json.readOnly,
+        inputSchema: json.inputSchema,
+        sourceElement: {
+          type: element.type,
+          selector: element.selector,
+        },
+      };
+    } catch (error) {
+      console.error('Analysis failed for element:', element.selector, error);
+      return null;
+    }
+  }
+}
+
+export const analyzer = new Analyzer();

package/src/lib/generator.ts

@@ -0,0 +1,149 @@
+import type { SuggestResult, ToolSuggestion } from '../types.js';
+import Handlebars from 'handlebars';
+
+interface GenerateOptions {
+  format: 'js' | 'ts' | 'react' | 'vue';
+  module: 'esm' | 'cjs';
+}
+
+const jsTemplate = Handlebars.compile(`// WebMCP Tool Registration
+// Generated by wmcp-annotate
+// URL: {{url}}
+// Generated: {{generatedAt}}
+
+{{#each tools}}
+// Tool: {{name}}
+// {{description}}
+navigator.modelContext.registerTool({
+  name: "{{name}}",
+  description: "{{description}}",
+  readOnly: {{readOnly}},
+  inputSchema: {{{schemaJson}}},
+  async execute({{#if hasInputs}}{ {{inputNames}} }{{/if}}) {
+    // TODO: Implement {{name}}
+    // Source element: {{sourceElement.selector}}
+    
+    {{#if isForm}}
+    const form = document.querySelector('{{sourceElement.selector}}');
+    {{#each inputFields}}
+    form.querySelector('[name="{{this}}"]').value = {{this}};
+    {{/each}}
+    form.submit();
+    {{else}}
+    const element = document.querySelector('{{sourceElement.selector}}');
+    element.click();
+    {{/if}}
+    
+    // Return results
+    return {
+      content: [{
+        type: "text",
+        text: JSON.stringify({ success: true })
+      }]
+    };
+  }
+});
+
+{{/each}}
+`);
+
+const tsTemplate = Handlebars.compile(`// WebMCP Tool Registration
+// Generated by wmcp-annotate
+// URL: {{url}}
+
+{{#each tools}}
+interface {{pascalName}}Input {
+{{#each inputFields}}
+  {{this}}: string;
+{{/each}}
+}
+
+{{/each}}
+{{#each tools}}
+navigator.modelContext.registerTool({
+  name: "{{name}}",
+  description: "{{description}}",
+  readOnly: {{readOnly}},
+  inputSchema: {{{schemaJson}}},
+  async execute(input: {{pascalName}}Input) {
+    // TODO: Implement
+    return { content: [{ type: "text", text: JSON.stringify({ success: true }) }] };
+  }
+});
+
+{{/each}}
+`);
+
+const reactTemplate = Handlebars.compile(`// WebMCP React Hook
+// Generated by wmcp-annotate
+
+import { useEffect } from 'react';
+
+export function useWebMCPTools() {
+  useEffect(() => {
+    if (!navigator.modelContext) {
+      console.warn('WebMCP not available');
+      return;
+    }
+
+    const cleanups: (() => void)[] = [];
+
+{{#each tools}}
+    cleanups.push(
+      navigator.modelContext.registerTool({
+        name: "{{name}}",
+        description: "{{description}}",
+        readOnly: {{readOnly}},
+        inputSchema: {{{schemaJson}}},
+        async execute(input) {
+          // TODO: Implement
+          return { content: [{ type: "text", text: JSON.stringify({ success: true }) }] };
+        }
+      })
+    );
+
+{{/each}}
+    return () => cleanups.forEach(cleanup => cleanup?.());
+  }, []);
+}
+`);
+
+class Generator {
+  async generate(suggestions: SuggestResult, options: GenerateOptions): Promise<string> {
+    const data = {
+      url: suggestions.url,
+      generatedAt: new Date().toISOString(),
+      tools: suggestions.tools.map(tool => this.prepareToolData(tool)),
+    };
+
+    switch (options.format) {
+      case 'ts':
+        return tsTemplate(data);
+      case 'react':
+        return reactTemplate(data);
+      case 'vue':
+        // Vue is similar to React for this use case
+        return reactTemplate(data).replace('useWebMCPTools', 'useWebMCPTools');
+      default:
+        return jsTemplate(data);
+    }
+  }
+
+  private prepareToolData(tool: ToolSuggestion) {
+    const inputFields = tool.inputSchema.properties 
+      ? Object.keys(tool.inputSchema.properties)
+      : [];
+    
+    return {
+      ...tool,
+      schemaJson: JSON.stringify(tool.inputSchema, null, 2),
+      hasInputs: inputFields.length > 0,
+      inputNames: inputFields.join(', '),
+      inputFields,
+      isForm: tool.sourceElement.type === 'form',
+      pascalName: tool.name.charAt(0).toUpperCase() + tool.name.slice(1),
+    };
+  }
+}
+
+export const generator = new Generator();

package/src/lib/output.ts

@@ -0,0 +1,40 @@
+import fs from 'fs/promises';
+
+export async function writeOutput(data: unknown, options: { output?: string; format?: string }): Promise<void> {
+  const output = options.format === 'yaml' 
+    ? toYaml(data)
+    : JSON.stringify(data, null, 2);
+  
+  if (options.output) {
+    await fs.writeFile(options.output, output, 'utf-8');
+  } else {
+    console.log(output);
+  }
+}
+
+export async function readInput<T>(path: string): Promise<T> {
+  const content = await fs.readFile(path, 'utf-8');
+  return JSON.parse(content) as T;
+}
+
+function toYaml(data: unknown, indent = 0): string {
+  // Simple YAML conversion
+  const spaces = '  '.repeat(indent);
+  
+  if (Array.isArray(data)) {
+    return data.map(item => `${spaces}- ${toYaml(item, indent + 1).trim()}`).join('\\n');
+  }
+  
+  if (typeof data === 'object' && data !== null) {
+    return Object.entries(data)
+      .map(([key, value]) => {
+        if (typeof value === 'object' && value !== null) {
+          return `${spaces}${key}:\\n${toYaml(value, indent + 1)}`;
+        }
+        return `${spaces}${key}: ${JSON.stringify(value)}`;
+      })
+      .join('\\n');
+  }
+  
+  return JSON.stringify(data);
+}

package/src/lib/scanner.ts

@@ -0,0 +1,185 @@
+import { chromium, type Browser, type Page } from 'playwright';
+import type { ScanResult, ScannedElement, ApiCall, InputField } from '../types.js';
+
+interface ScanOptions {
+  depth?: number;
+  verbose?: boolean;
+}
+
+class Scanner {
+  private browser: Browser | null = null;
+
+  async scan(url: string, options: ScanOptions = {}): Promise<ScanResult> {
+    const { depth = 1, verbose = false } = options;
+    
+    await this.ensureBrowser();
+    const page = await this.browser!.newPage();
+    
+    try {
+      // Navigate and wait for load
+      await page.goto(url, { waitUntil: 'networkidle' });
+      
+      // Collect API calls
+      const apiCalls: ApiCall[] = [];
+      page.on('request', (request) => {
+        const reqUrl = request.url();
+        if (reqUrl.includes('/api/') || request.resourceType() === 'fetch' || request.resourceType() === 'xhr') {
+          apiCalls.push({
+            method: request.method(),
+            url: reqUrl,
+            params: Array.from(new URL(reqUrl).searchParams.keys()),
+          });
+        }
+      });
+      
+      // Scan for elements
+      const elements = await this.scanElements(page);
+      
+      return {
+        url,
+        scannedAt: new Date().toISOString(),
+        elements,
+        apiCalls,
+      };
+    } finally {
+      await page.close();
+    }
+  }
+
+  private async scanElements(page: Page): Promise<ScannedElement[]> {
+    const elements: ScannedElement[] = [];
+    
+    // Scan forms
+    const forms = await page.$$('form');
+    for (const form of forms) {
+      const id = await form.getAttribute('id');
+      const inputs = await this.getFormInputs(form);
+      const submitBtn = await form.$('button[type="submit"], input[type="submit"]');
+      
+      elements.push({
+        type: 'form',
+        id: id || undefined,
+        selector: id ? `#${id}` : 'form',
+        label: await this.getLabel(form) || 'Form',
+        inputs,
+        submitButton: submitBtn ? {
+          selector: await this.getSelector(submitBtn),
+          label: await submitBtn.textContent() || 'Submit',
+        } : undefined,
+      });
+    }
+    
+    // Scan buttons (not in forms)
+    const buttons = await page.$$('button:not(form button), [role="button"]');
+    for (const button of buttons) {
+      const label = await button.textContent();
+      if (label?.trim()) {
+        elements.push({
+          type: 'button',
+          selector: await this.getSelector(button),
+          label: label.trim(),
+        });
+      }
+    }
+    
+    // Scan links with actions
+    const actionLinks = await page.$$('a[href^="#"], a[href^="javascript:"], a[onclick]');
+    for (const link of actionLinks) {
+      const label = await link.textContent();
+      if (label?.trim()) {
+        elements.push({
+          type: 'link',
+          selector: await this.getSelector(link),
+          label: label.trim(),
+        });
+      }
+    }
+    
+    return elements;
+  }
+
+  private async getFormInputs(form: any): Promise<InputField[]> {
+    const inputs: InputField[] = [];
+    const inputElements = await form.$$('input, select, textarea');
+    
+    for (const input of inputElements) {
+      const name = await input.getAttribute('name');
+      const type = await input.getAttribute('type') || 'text';
+      const required = await input.getAttribute('required') !== null;
+      const placeholder = await input.getAttribute('placeholder');
+      const label = await this.getInputLabel(input);
+      
+      if (name && type !== 'hidden' && type !== 'submit') {
+        inputs.push({
+          name,
+          type,
+          label: label || undefined,
+          required,
+          placeholder: placeholder || undefined,
+        });
+      }
+    }
+    
+    return inputs;
+  }
+
+  private async getInputLabel(input: any): Promise<string | null> {
+    try {
+      const id = await input.getAttribute('id');
+      if (id) {
+        // Use evaluate to find the label in the DOM
+        const labelText = await input.evaluate((el: HTMLElement) => {
+          const id = el.getAttribute('id');
+          if (id) {
+            const label = document.querySelector(`label[for="${id}"]`);
+            return label?.textContent || null;
+          }
+          return null;
+        });
+        return labelText;
+      }
+    } catch {
+      // Ignore errors
+    }
+    return null;
+  }
+
+  private async getLabel(element: any): Promise<string | null> {
+    const ariaLabel = await element.getAttribute('aria-label');
+    if (ariaLabel) return ariaLabel;
+    
+    const title = await element.getAttribute('title');
+    if (title) return title;
+    
+    return null;
+  }
+
+  private async getSelector(element: any): Promise<string> {
+    const id = await element.getAttribute('id');
+    if (id) return `#${id}`;
+    
+    const className = await element.getAttribute('class');
+    if (className) {
+      const classes = className.split(' ').filter((c: string) => c && !c.includes(':'));
+      if (classes.length > 0) return `.${classes[0]}`;
+    }
+    
+    const tagName = await element.evaluate((el: HTMLElement) => el.tagName.toLowerCase());
+    return tagName;
+  }
+
+  private async ensureBrowser(): Promise<void> {
+    if (!this.browser) {
+      this.browser = await chromium.launch({ headless: true });
+    }
+  }
+
+  async close(): Promise<void> {
+    if (this.browser) {
+      await this.browser.close();
+      this.browser = null;
+    }
+  }
+}
+
+export const scanner = new Scanner();

package/src/lib/validator.ts

@@ -0,0 +1,192 @@
+import { chromium, type Browser } from 'playwright';
+import AjvModule from 'ajv';
+import type { ValidationResult, ToolValidation, ValidationIssue } from '../types.js';
+
+const Ajv = AjvModule.default || AjvModule;
+const ajv = new Ajv();
+
+class Validator {
+  private browser: Browser | null = null;
+
+  async validate(url: string): Promise<ValidationResult> {
+    await this.ensureBrowser();
+    const page = await this.browser!.newPage();
+    
+    try {
+      // Navigate with WebMCP flag (Chrome 146+)
+      await page.goto(url, { waitUntil: 'networkidle' });
+      
+      // Query registered tools
+      const tools = await page.evaluate(() => {
+        // @ts-ignore - WebMCP API
+        if (typeof navigator.modelContext?.getTools === 'function') {
+          // @ts-ignore
+          return navigator.modelContext.getTools();
+        }
+        return [];
+      });
+      
+      const validations: ToolValidation[] = [];
+      let validCount = 0;
+      let warningCount = 0;
+      let errorCount = 0;
+      
+      for (const tool of tools) {
+        const validation = this.validateTool(tool);
+        validations.push(validation);
+        
+        if (validation.status === 'valid') validCount++;
+        else if (validation.status === 'warning') warningCount++;
+        else errorCount++;
+      }
+      
+      return {
+        url,
+        validatedAt: new Date().toISOString(),
+        summary: {
+          total: tools.length,
+          valid: validCount,
+          warnings: warningCount,
+          errors: errorCount,
+        },
+        tools: validations,
+      };
+    } finally {
+      await page.close();
+    }
+  }
+
+  private validateTool(tool: any): ToolValidation {
+    const checks: Record<string, 'pass' | 'fail' | 'warning'> = {};
+    const issues: ValidationIssue[] = [];
+    
+    // Check name format (camelCase)
+    if (this.isCamelCase(tool.name)) {
+      checks.nameConvention = 'pass';
+    } else {
+      checks.nameConvention = 'fail';
+      issues.push({
+        level: 'error',
+        code: 'NAME_FORMAT',
+        message: 'Tool name must be camelCase',
+        suggestion: `Rename to: ${this.toCamelCase(tool.name)}`,
+      });
+    }
+    
+    // Check description
+    if (!tool.description) {
+      checks.descriptionPresent = 'fail';
+      issues.push({
+        level: 'error',
+        code: 'DESCRIPTION_MISSING',
+        message: 'Description is required',
+      });
+    } else if (tool.description.length < 20) {
+      checks.descriptionPresent = 'warning';
+      issues.push({
+        level: 'warning',
+        code: 'DESCRIPTION_TOO_SHORT',
+        message: 'Description should be at least 20 characters',
+        suggestion: 'Add more detail about what this tool does',
+      });
+    } else {
+      checks.descriptionPresent = 'pass';
+    }
+    
+    // Check schema validity
+    if (tool.inputSchema) {
+      try {
+        ajv.compile(tool.inputSchema);
+        checks.schemaValid = 'pass';
+        
+        // Check for property descriptions
+        const props = tool.inputSchema.properties || {};
+        const missingDesc = Object.entries(props).filter(
+          ([_, prop]: [string, any]) => !prop.description
+        );
+        
+        if (missingDesc.length > 0) {
+          checks.schemaDescriptions = 'warning';
+          issues.push({
+            level: 'warning',
+            code: 'SCHEMA_NO_DESCRIPTION',
+            message: `Properties missing descriptions: ${missingDesc.map(([k]) => k).join(', ')}`,
+          });
+        } else {
+          checks.schemaDescriptions = 'pass';
+        }
+      } catch (error) {
+        checks.schemaValid = 'fail';
+        issues.push({
+          level: 'error',
+          code: 'SCHEMA_INVALID',
+          message: `Invalid JSON Schema: ${error instanceof Error ? error.message : 'Unknown error'}`,
+        });
+      }
+    }
+    
+    // Check handler
+    if (typeof tool.execute === 'function') {
+      checks.handlerPresent = 'pass';
+      
+      // Check if async
+      if (tool.execute.constructor.name === 'AsyncFunction') {
+        checks.handlerAsync = 'pass';
+      } else {
+        checks.handlerAsync = 'fail';
+        issues.push({
+          level: 'error',
+          code: 'HANDLER_NOT_ASYNC',
+          message: 'Execute handler must be an async function',
+        });
+      }
+    } else {
+      checks.handlerPresent = 'fail';
+      issues.push({
+        level: 'error',
+        code: 'HANDLER_MISSING',
+        message: 'Execute handler is required',
+      });
+    }
+    
+    // Determine overall status
+    let status: 'valid' | 'warning' | 'error' = 'valid';
+    if (issues.some(i => i.level === 'error')) {
+      status = 'error';
+    } else if (issues.some(i => i.level === 'warning')) {
+      status = 'warning';
+    }
+    
+    return {
+      name: tool.name,
+      status,
+      checks,
+      issues: issues.length > 0 ? issues : undefined,
+    };
+  }
+
+  private isCamelCase(str: string): boolean {
+    return /^[a-z][a-zA-Z0-9]*$/.test(str);
+  }
+
+  private toCamelCase(str: string): string {
+    return str
+      .replace(/[-_\s]+(.)?/g, (_, c) => (c ? c.toUpperCase() : ''))
+      .replace(/^./, c => c.toLowerCase());
+  }
+
+  private async ensureBrowser(): Promise<void> {
+    if (!this.browser) {
+      this.browser = await chromium.launch({ headless: true });
+    }
+  }
+
+  async close(): Promise<void> {
+    if (this.browser) {
+      await this.browser.close();
+      this.browser = null;
+    }
+  }
+}
+
+export const validator = new Validator();