@webmcp/cli

Command-line tools for webMCP processing, validation, and optimization.

Installation

# Global installation
npm install -g @webmcp/cli

# Or use with npx
npx @webmcp/cli --help

Commands

webmcp scan

Scan HTML files and generate webMCP configurations.

# Scan local HTML file
webmcp scan index.html --output page.wmcp

# Scan remote URL
webmcp scan https://example.com --output example.wmcp --format json

# Verbose output with details
webmcp scan login.html --verbose

Options:

• -o, --output <file> - Output file for webMCP configuration
• -f, --format <format> - Output format (json|wmcp), default: wmcp
• --url <url> - Page URL for context
• --verbose - Enable verbose output

webmcp validate

Validate webMCP configuration files against schema and best practices.

# Basic validation
webmcp validate page.wmcp

# Strict validation mode
webmcp validate page.wmcp --strict

# JSON output for CI/CD
webmcp validate page.wmcp --json

Options:

• --schema <version> - Schema version to validate against, default: 0.2
• --strict - Enable strict validation mode
• --json - Output results in JSON format

webmcp optimize

Optimize webMCP configurations for AI consumption.

# Optimize for GPT-4o
webmcp optimize page.wmcp --target gpt-4o --level advanced

# Generate AI-ready prompt
webmcp optimize page.wmcp --goal "Login to the website" --output prompt.txt

# Premium compression
webmcp optimize page.wmcp --level premium --target claude-3.5-sonnet

Options:

• -t, --target <model> - Target AI model (gpt-4o, gpt-4, claude-3.5-sonnet, etc.)
• -l, --level <level> - Compression level (basic|advanced|premium)
• -o, --output <file> - Output file for optimized configuration
• --goal <goal> - Goal description for AI optimization

webmcp lint

Lint webMCP files for best practices and consistency.

# Lint single file
webmcp lint page.wmcp

# Lint multiple files with glob pattern
webmcp lint "src/**/*.wmcp"

# Auto-fix issues
webmcp lint "*.wmcp" --fix

# Custom linter configuration
webmcp lint page.wmcp --config .webmcp-lint.json

Options:

• --fix - Automatically fix issues where possible
• --config <file> - Linter configuration file

webmcp dev-server

Start development server with webMCP processing capabilities.

# Start development server
webmcp dev-server

# Custom port with auto-open
webmcp dev-server --port 8080 --open

# Watch mode for file changes
webmcp dev-server --watch

Options:

• -p, --port <port> - Server port, default: 3000
• --watch - Watch for file changes
• --open - Open browser automatically

webmcp benchmark (Premium)

Benchmark webMCP performance across different AI models.

# Basic benchmark (limited in open source)
webmcp benchmark page.wmcp

# Premium: Full model comparison
webmcp benchmark page.wmcp --models gpt-4o,claude-3.5-sonnet,gpt-4 --iterations 100

# Detailed performance metrics
webmcp benchmark page.wmcp --detailed

Options:

• --models <models> - Comma-separated list of models to test
• --iterations <num> - Number of test iterations, default: 10
• --detailed - Show detailed performance metrics

Examples

Complete Workflow

# 1. Scan HTML to generate webMCP
webmcp scan login.html --output login.wmcp --verbose

# 2. Validate the generated configuration
webmcp validate login.wmcp --strict

# 3. Lint for best practices
webmcp lint login.wmcp --fix

# 4. Optimize for your target AI model
webmcp optimize login.wmcp --target gpt-4o --level advanced --goal "Login with username and password"

# 5. Start dev server for testing
webmcp dev-server --port 3000 --open

CI/CD Integration

#!/bin/bash
# validate-webmcp.sh

# Validate all webMCP files
if webmcp validate "src/**/*.wmcp" --json > validation-report.json; then
    echo "✅ All webMCP files are valid"
else
    echo "❌ webMCP validation failed"
    cat validation-report.json
    exit 1
fi

# Lint files
webmcp lint "src/**/*.wmcp" --fix

# Generate optimization report
webmcp optimize app.wmcp --target gpt-4o --output optimized-app.wmcp

Automation Script

#!/bin/bash
# process-pages.sh

# Process multiple HTML files
for file in src/pages/*.html; do
    echo "Processing $file..."
    
    # Generate webMCP
    webmcp scan "$file" --output "${file%.html}.wmcp"
    
    # Validate and lint
    webmcp validate "${file%.html}.wmcp" --strict
    webmcp lint "${file%.html}.wmcp" --fix
    
    # Optimize for different models
    webmcp optimize "${file%.html}.wmcp" --target gpt-4o --level premium --output "${file%.html}-gpt4o.json"
    webmcp optimize "${file%.html}.wmcp" --target claude-3.5-sonnet --level advanced --output "${file%.html}-claude.json"
done

echo "✅ All pages processed successfully!"

Development Server API

When running webmcp dev-server, the following API endpoints are available:

POST /api/parse

Parse HTML content to webMCP format.

{
  "html": "<form>...</form>",
  "url": "https://example.com/login"
}

POST /api/validate

Validate webMCP configuration.

{
  "webmcp": { "version": "0.2", ... }
}

POST /api/optimize

Optimize webMCP for AI consumption.

{
  "webmcp": { "version": "0.2", ... },
  "options": { "target_model": "gpt-4o", "compression_level": "advanced" }
}

POST /api/prompt

Generate AI-ready prompt.

{
  "webmcp": { "version": "0.2", ... },
  "goal": "Login to the website"
}

GET /api/status

Get server status and statistics.

Configuration

Linter Configuration (.webmcp-lint.json)

{
  "rules": {
    "missing-context": "error",
    "empty-elements": "error",
    "invalid-element-names": "error",
    "duplicate-selectors": "warning",
    "duplicate-names": "error",
    "missing-required-flag": "warning",
    "insecure-password-fields": "warning",
    "missing-metadata": "info",
    "large-element-count": "warning",
    "invalid-schema-version": "error",
    "invalid-css-selectors": "warning"
  },
  "autoFix": true,
  "strictMode": false
}

Performance

Processing Speed

• Scanning: ~100ms for typical pages (1,000 elements)
• Validation: ~10ms average
• Optimization: ~50ms average
• Linting: ~25ms average

Output Sizes

• Original HTML: ~50KB average
• webMCP JSON: ~10KB average (80% reduction)
• Optimized payload: ~2KB average (96% reduction)

Integration Examples

GitHub Actions

name: webMCP Validation
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
      
      - name: Install webMCP CLI
        run: npm install -g @webmcp/cli
      
      - name: Validate webMCP files
        run: webmcp validate "src/**/*.wmcp" --json > validation-report.json
      
      - name: Upload validation report
        uses: actions/upload-artifact@v3
        with:
          name: validation-report
          path: validation-report.json

Pre-commit Hook

#!/bin/sh
# .git/hooks/pre-commit

echo "Running webMCP validation..."

# Lint and validate all webMCP files
if ! webmcp lint "src/**/*.wmcp" --fix; then
    echo "❌ webMCP linting failed"
    exit 1
fi

if ! webmcp validate "src/**/*.wmcp"; then
    echo "❌ webMCP validation failed"
    exit 1
fi

echo "✅ webMCP validation passed"

Troubleshooting

Common Issues

File not found error

# Make sure file path is correct
ls -la page.wmcp
webmcp validate ./page.wmcp

Invalid JSON error

# Validate JSON syntax first
cat page.wmcp | jq .

Permission denied

# Fix permissions
chmod 644 page.wmcp

Port already in use

# Use different port
webmcp dev-server --port 8080

Debug Mode

Set environment variable for detailed logging:

DEBUG=webmcp* webmcp scan page.html --verbose

License

MIT License - see LICENSE file for details.

Links

• Documentation
• GitHub Repository
• Issue Tracker