wmcp-annotate 1.0.0

package/AGENTS.md

@@ -0,0 +1,108 @@
+# AGENTS.md - wmcp-annotate
+
+## Project Overview
+CLI tool to automatically analyze websites and generate WebMCP tool annotations.
+
+## Tech Stack
+- Node.js 20+
+- TypeScript
+- Playwright (browser automation)
+- Commander.js (CLI)
+- Vitest (testing)
+- Claude API (AI analysis)
+
+## Commands
+
+### Install dependencies
+```bash
+npm install
+```
+
+### Build
+```bash
+npm run build
+```
+
+### Test
+```bash
+npm test
+```
+
+### Run locally
+```bash
+npm run dev -- scan https://example.com
+```
+
+### Lint
+```bash
+npm run lint
+```
+
+## Backpressure Commands
+Run these after each implementation task:
+
+```bash
+# Build check
+npm run build
+
+# Type check
+npx tsc --noEmit
+
+# Tests
+npm test
+
+# Lint
+npm run lint
+```
+
+## File Structure
+```
+wmcp-annotate/
+├── src/
+│   ├── index.ts          # CLI entry point
+│   ├── commands/
+│   │   ├── scan.ts       # Scan command
+│   │   ├── suggest.ts    # Suggest command
+│   │   ├── generate.ts   # Generate command
+│   │   └── validate.ts   # Validate command
+│   ├── lib/
+│   │   ├── scanner.ts    # Playwright scanning logic
+│   │   ├── analyzer.ts   # AI analysis
+│   │   ├── generator.ts  # Code generation
+│   │   └── validator.ts  # Compliance checking
+│   ├── templates/        # Output templates
+│   └── types.ts          # TypeScript types
+├── tests/
+│   ├── scan.test.ts
+│   ├── suggest.test.ts
+│   ├── generate.test.ts
+│   └── validate.test.ts
+├── specs/                # Requirements specs
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+## Environment Variables
+```bash
+ANTHROPIC_API_KEY=sk-ant-...  # For AI analysis
+WMCP_RATE_LIMIT=10            # Free tier limit
+```
+
+## Key Dependencies
+- playwright: browser automation
+- commander: CLI framework
+- @anthropic-ai/sdk: AI analysis
+- handlebars: template engine
+- ajv: JSON Schema validation
+
+## Coding Standards
+- Use TypeScript strict mode
+- Async/await for all async operations
+- Error handling with specific error types
+- JSDoc comments for public APIs
+- 100% test coverage for core logic
+
+## Learnings
+(Updated during development)
+- 

package/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,187 @@
+# IMPLEMENTATION_PLAN.md - wmcp-annotate
+
+## Overview
+Build `wmcp-annotate` CLI tool for WebMCP adoption.
+
+## Status
+🔵 IN PROGRESS
+
+---
+
+## Phase 1: Project Setup (Day 1)
+
+### Task 1.1: Initialize project ⬜
+- [ ] Create package.json with name "wmcp-annotate"
+- [ ] Set up TypeScript config (strict mode)
+- [ ] Add dependencies: playwright, commander, @anthropic-ai/sdk, handlebars, ajv
+- [ ] Add dev dependencies: vitest, typescript, eslint, prettier
+- [ ] Create src/ directory structure
+- [ ] Add npm scripts: build, test, dev, lint
+
+### Task 1.2: CLI scaffolding ⬜
+- [ ] Create src/index.ts with Commander setup
+- [ ] Add scan, suggest, generate, validate command stubs
+- [ ] Add global options (--output, --format, --verbose)
+- [ ] Add version and help commands
+- [ ] Test: `wmcp-annotate --help` works
+
+### Task 1.3: Types definition ⬜
+- [ ] Create src/types.ts with interfaces:
+  - ScanResult, ScannedElement
+  - ToolSuggestion, ToolDefinition
+  - ValidationResult, ValidationIssue
+- [ ] Export all types
+
+---
+
+## Phase 2: Scan Command (Day 1-2)
+
+### Task 2.1: Scanner core ⬜
+- [ ] Create src/lib/scanner.ts
+- [ ] Implement launchBrowser() with Playwright
+- [ ] Implement scanPage(url) → identifies forms, buttons, links
+- [ ] Handle SPA wait (networkidle)
+- [ ] Extract element metadata (selector, label, inputs)
+
+### Task 2.2: API interception ⬜
+- [ ] Intercept fetch/XHR requests
+- [ ] Capture API endpoints and parameters
+- [ ] Add to scan results
+
+### Task 2.3: Scan command integration ⬜
+- [ ] Connect scanner to CLI command
+- [ ] Add --depth option for multi-page crawl
+- [ ] Add --output and --format options
+- [ ] Test with 3 different websites
+
+---
+
+## Phase 3: Suggest Command (Day 2-3)
+
+### Task 3.1: Analyzer core ⬜
+- [ ] Create src/lib/analyzer.ts
+- [ ] Implement Claude API integration
+- [ ] Create prompt template for tool analysis
+- [ ] Parse AI response into ToolSuggestion[]
+
+### Task 3.2: Schema generation ⬜
+- [ ] Generate JSON Schema from form inputs
+- [ ] Handle different input types (text, number, select, checkbox)
+- [ ] Add descriptions from labels/placeholders
+- [ ] Set required fields correctly
+
+### Task 3.3: Suggest command integration ⬜
+- [ ] Connect analyzer to CLI command
+- [ ] Add --scan-file option to use existing scan
+- [ ] Cache results (1 hour TTL)
+- [ ] Add rate limiting for free tier
+
+---
+
+## Phase 4: Generate Command (Day 3-4)
+
+### Task 4.1: Generator core ⬜
+- [ ] Create src/lib/generator.ts
+- [ ] Create Handlebars templates:
+  - templates/js-esm.hbs
+  - templates/ts.hbs
+  - templates/react.hbs
+- [ ] Implement template rendering
+
+### Task 4.2: Code generation ⬜
+- [ ] Generate valid navigator.modelContext.registerTool() code
+- [ ] Add execute handler stubs with implementation hints
+- [ ] Add TypeScript types for TS output
+- [ ] Add React hook wrapper for React output
+
+### Task 4.3: Generate command integration ⬜
+- [ ] Connect generator to CLI command
+- [ ] Add --suggest-file option
+- [ ] Add --format option (js, ts, react, vue)
+- [ ] Test generated code is valid
+
+---
+
+## Phase 5: Validate Command (Day 4-5)
+
+### Task 5.1: Validator core ⬜
+- [ ] Create src/lib/validator.ts
+- [ ] Query navigator.modelContext.tools from page
+- [ ] Implement validation rules from spec
+- [ ] Return structured ValidationResult
+
+### Task 5.2: Validation rules ⬜
+- [ ] NAME_FORMAT: camelCase check
+- [ ] DESCRIPTION_MISSING/TOO_SHORT
+- [ ] SCHEMA_INVALID: JSON Schema validation
+- [ ] HANDLER_NOT_ASYNC
+- [ ] READONLY_HINT
+
+### Task 5.3: Validate command integration ⬜
+- [ ] Connect validator to CLI command
+- [ ] Add --strict and --ci flags
+- [ ] Generate report in multiple formats
+- [ ] Exit codes for CI
+
+---
+
+## Phase 6: Polish & Publish (Day 5-6)
+
+### Task 6.1: Documentation ⬜
+- [ ] Write comprehensive README.md
+- [ ] Add usage examples for each command
+- [ ] Add CI integration examples
+- [ ] Add troubleshooting section
+
+### Task 6.2: Testing ⬜
+- [ ] Add unit tests for each module
+- [ ] Add integration tests with real websites
+- [ ] Achieve 80%+ code coverage
+- [ ] Add test fixtures
+
+### Task 6.3: Publishing ⬜
+- [ ] Set up npm publish workflow
+- [ ] Create GitHub repository
+- [ ] Add GitHub Actions CI
+- [ ] Publish v1.0.0 to npm
+- [ ] Add badges to README
+
+---
+
+## Phase 7: Marketing Launch (Day 6-7)
+
+### Task 7.1: Content ⬜
+- [ ] Write Dev.to article
+- [ ] Create demo video
+- [ ] Write Twitter thread
+- [ ] Prepare HN post
+
+### Task 7.2: Launch ⬜
+- [ ] Post to Hacker News
+- [ ] Tweet announcement
+- [ ] Post to Dev.to
+- [ ] Share in AI/dev communities
+
+### Task 7.3: Outreach ⬜
+- [ ] Email 50 potential enterprise customers
+- [ ] Reach out to WebMCP early adopters
+- [ ] Contact AI agent builders
+
+---
+
+## Completion Checklist
+- [ ] All commands working
+- [ ] Tests passing
+- [ ] Published to npm
+- [ ] Documentation complete
+- [ ] Marketing launched
+- [ ] First paying customers
+
+---
+
+## Notes
+(Add learnings and blockers here)
+
+---
+
+**STATUS: PLANNING_COMPLETE**

package/LAUNCH.md

@@ -0,0 +1,217 @@
+# 🚀 wmcp-annotate Launch Checklist
+
+**Status:** Ready to launch  
+**Date:** February 24, 2026
+
+---
+
+## ✅ Completed
+
+- [x] Core CLI implementation (scan, suggest, generate, validate)
+- [x] TypeScript build passing
+- [x] Package.json configured for npm
+- [x] README.md with full documentation
+- [x] Landing page HTML (`docs/index.html`)
+- [x] Social posts written (LinkedIn, Twitter/X, HN)
+- [x] Email outreach templates ready
+
+---
+
+## 🔐 Needs Your Action (npm publish)
+
+Run these commands:
+
+```bash
+cd ~/workspace/projects/wmcp-annotate
+
+# 1. Login to npm (one-time)
+npm login
+
+# 2. Publish to npm registry
+npm publish --access public
+
+# 3. Verify it's live
+npm info wmcp-annotate
+```
+
+---
+
+## 📱 Social Media Posts (Copy & Post)
+
+### LinkedIn (Post Now)
+```
+Google just changed how AI agents interact with websites. Is your site ready?
+
+Two weeks ago, Google and Microsoft shipped WebMCP in Chrome 146—a W3C standard that lets websites declare structured tools for AI agents.
+
+Instead of AI scraping your DOM or analyzing screenshots (expensive, fragile), WebMCP lets you tell agents exactly what your site can do.
+
+The problem? 99% of sites don't have these annotations yet.
+
+So we built wmcp-annotate.
+
+One command:
+
+npx wmcp-annotate generate https://your-site.com
+
+It scans your site, uses AI to suggest tool definitions, and generates ready-to-use code.
+
+Think of it as "making your website API-first for AI."
+
+We're launching today. Open source core, Pro tier for teams.
+
+→ GitHub: https://github.com/avatarconsulting/wmcp-annotate
+→ Try it: npm install -g wmcp-annotate
+
+If you're building AI agents or want your SaaS to be agent-friendly, this is the fastest path.
+
+Questions? Drop them below.
+
+#AI #WebDevelopment #Automation #AIAgents #WebMCP
+```
+
+### Twitter/X Thread (Post Now)
+```
+🧵 Google just shipped the biggest change to web automation since Selenium.
+
+WebMCP is now in Chrome 146.
+
+Here's what it means and how to get your site ready in 5 minutes:
+
+---
+
+WebMCP lets websites declare "tools" that AI agents can call directly.
+
+No more:
+- DOM scraping
+- Screenshot analysis (2000+ tokens each!)
+- Broken automation when CSS changes
+
+---
+
+Instead, your site says:
+"Here's a searchProducts tool. It takes a query string. Here's how to call it."
+
+The AI agent calls the tool. Gets structured data back. Done.
+
+---
+
+The catch? 99% of websites don't have WebMCP annotations.
+
+Someone needs to add them.
+
+---
+
+Enter: wmcp-annotate
+
+We built a CLI that:
+1. Scans your site
+2. Identifies forms/buttons/APIs
+3. Uses AI to generate tool definitions
+4. Outputs ready-to-use code
+
+---
+
+npx wmcp-annotate generate https://your-site.com
+
+That's it. You get JavaScript you can copy-paste into your app.
+
+---
+
+Open source core. Free to use.
+Pro tier ($49/mo) for unlimited AI + CI integration.
+
+Try it: npm install -g wmcp-annotate
+GitHub: https://github.com/avatarconsulting/wmcp-annotate
+```
+
+### Hacker News (Submit to Show HN)
+
+**Title:** Show HN: wmcp-annotate – Make any website AI-agent ready with WebMCP
+
+**URL:** https://github.com/avatarconsulting/wmcp-annotate
+
+**Text:**
+```
+Two weeks ago, Google and Microsoft shipped WebMCP in Chrome 146 (https://webmcp.link). It's a W3C standard that lets websites declare structured tools for AI agents—no more DOM scraping or screenshot parsing.
+
+We built wmcp-annotate to help developers adopt it quickly.
+
+What it does:
+- Scans any website and identifies forms, buttons, API calls
+- Uses Claude to generate meaningful tool definitions
+- Outputs ready-to-use JS/TS/React code
+- Validates existing implementations
+
+Usage:
+npm install -g wmcp-annotate
+wmcp-annotate generate https://your-site.com --format typescript
+
+Why this matters:
+AI agents currently waste ~2000 tokens per screenshot to understand a page. With WebMCP, it's ~100 tokens to call a declared tool. That's 95% cost reduction. Plus, the automation is stable—no more broken scripts when CSS changes.
+
+Business model:
+Open source CLI (MIT). Pro tier ($49/mo) for unlimited AI analysis and CI integration. Enterprise ($499/mo) for teams.
+
+We're a small consulting firm (Avatar Consulting) that does AI transformation for banks. This came out of client work—everyone wanted their internal tools to be agent-accessible.
+
+Would love feedback on the tool and the approach.
+```
+
+---
+
+## 🌐 Landing Page
+
+The HTML is ready at: `docs/index.html`
+
+**To deploy:**
+
+Option A - GitHub Pages:
+```bash
+# Push to gh-pages branch
+git subtree push --prefix docs origin gh-pages
+```
+
+Option B - Vercel:
+```bash
+cd docs
+vercel --prod
+```
+
+Option C - Just serve the HTML file anywhere
+
+---
+
+## 📧 Email Outreach (Week 1)
+
+Target list in `marketing/email-outreach.md`. Key targets:
+
+1. **AI/ML Newsletter authors** - TheSequence, Import AI, Last Week in AI
+2. **Dev tool journalists** - The Changelog, Dev.to editors
+3. **VC contacts** - especially those who funded browser/AI tools
+4. **SaaS founders** - tweet about AI compatibility
+
+---
+
+## 📊 Success Metrics (Week 1)
+
+- [ ] npm downloads > 500
+- [ ] GitHub stars > 100
+- [ ] HN front page (or close)
+- [ ] 3+ inbound leads for Pro/Enterprise
+- [ ] 5+ mentions in tweets/posts
+
+---
+
+## 🎯 Post-Launch (Week 2+)
+
+1. **Blog post:** "How we built wmcp-annotate" (dev story)
+2. **Tutorial video:** 5-min demo on YouTube
+3. **Integrations:** VS Code extension, GitHub Action
+4. **Partnerships:** Reach out to Playwright, Puppeteer, browser-use
+
+---
+
+**Questions?** Text me or drop them in Command Center.
+
+— Edison 💡

package/PRD.md

@@ -0,0 +1,199 @@
+# PRD: wmcp-annotate
+
+## Product Overview
+
+**wmcp-annotate** is a CLI tool that automatically analyzes websites and generates WebMCP tool annotations, enabling AI agents to interact with any web application through the new W3C WebMCP standard.
+
+## Problem Statement
+
+Google and Microsoft shipped WebMCP in Chrome 146 (February 2026) as a W3C standard. This protocol lets websites declare structured tools that AI agents can call directly—no DOM scraping, 89% token reduction vs screenshots.
+
+**The problem:** 99% of websites don't have WebMCP annotations yet. Developers need to:
+1. Understand the WebMCP spec
+2. Identify which UI elements should become tools
+3. Write the JavaScript registration code
+4. Test and validate the implementation
+
+This is manual, error-prone, and slow. Most teams won't do it.
+
+## Solution
+
+**wmcp-annotate** automates WebMCP adoption:
+1. **Scan** any website and identify actionable elements (forms, buttons, links, APIs)
+2. **Suggest** WebMCP tool definitions with proper schemas
+3. **Generate** ready-to-use JavaScript code
+4. **Validate** existing WebMCP implementations
+5. **Inject** annotations into React/Vue/Svelte/vanilla codebases
+
+## ICP (Ideal Customer Profile)
+
+### Primary: Web Development Teams
+- Frontend engineers at SaaS companies
+- Agencies building client sites
+- Enterprise IT teams modernizing internal apps
+
+### Secondary: AI Agent Builders
+- Teams building AI agents that need to interact with websites
+- Automation engineers
+- RPA modernization projects
+
+## Key Features
+
+### v1.0 (MVP - 2 weeks)
+1. **Scan mode**: Analyze any URL, identify actionable elements
+2. **Suggest mode**: Generate WebMCP tool definitions as JSON
+3. **Generate mode**: Output ready-to-use JavaScript code
+4. **Validate mode**: Check existing WebMCP implementations for compliance
+
+### v1.1 (Week 3-4)
+5. **Inject mode**: Add annotations to React/Vue/Svelte projects
+6. **CI integration**: GitHub Actions / GitLab CI support
+7. **Report mode**: Generate compliance reports
+
+### v2.0 (Month 2)
+8. **Watch mode**: Monitor sites for changes, suggest updates
+9. **Catalog integration**: Publish to wmcp-catalog registry
+10. **Enterprise**: Team workspaces, audit logs, SSO
+
+## Non-Features (Out of Scope)
+- Browser extension (use CLI instead)
+- Visual editor (code-first approach)
+- Hosting/proxy services
+- WebMCP runtime (browser handles that)
+
+## Technical Architecture
+
+### CLI Structure
+```
+wmcp-annotate <command> [options]
+
+Commands:
+  scan <url>          Analyze a website for WebMCP opportunities
+  suggest <url>       Generate tool definition suggestions
+  generate <url>      Output JavaScript registration code
+  validate <url>      Check WebMCP compliance
+  inject <dir>        Add annotations to codebase
+  report <url>        Generate compliance report
+
+Options:
+  --output, -o        Output file (default: stdout)
+  --format, -f        Output format: json, js, ts, react, vue
+  --config, -c        Config file path
+  --verbose, -v       Verbose output
+  --headless          Run browser in headless mode (default: true)
+```
+
+### Core Components
+1. **Scanner**: Playwright-based crawler that identifies forms, buttons, links, API calls
+2. **Analyzer**: AI-powered analysis to determine tool semantics
+3. **Generator**: Template engine for JS/TS/React/Vue output
+4. **Validator**: WebMCP spec compliance checker
+5. **Injector**: AST-based code modification for existing projects
+
+### Tech Stack
+- **Runtime**: Node.js 20+
+- **Browser**: Playwright
+- **AI**: Claude API for semantic analysis
+- **Parser**: TypeScript compiler API for injection
+- **CLI**: Commander.js
+- **Testing**: Vitest
+
+## Success Metrics
+
+### Week 1
+- [ ] CLI scaffolding complete
+- [ ] Scan command working on 3 test sites
+- [ ] Suggest command generating valid schemas
+
+### Week 2
+- [ ] Generate command outputting working JS
+- [ ] Validate command checking compliance
+- [ ] 10 beta users testing
+
+### Month 1
+- [ ] 100 GitHub stars
+- [ ] 50 npm weekly downloads
+- [ ] 5 paying enterprise customers
+- [ ] $5K MRR
+
+### Month 3
+- [ ] 1000 GitHub stars
+- [ ] 500 npm weekly downloads
+- [ ] 20 paying customers
+- [ ] $25K MRR
+
+## Pricing
+
+### Open Source (Free)
+- Scan, suggest, generate commands
+- Community support
+- Rate-limited AI analysis (10/day)
+
+### Pro ($49/month)
+- Unlimited AI analysis
+- Inject command
+- CI integration
+- Email support
+
+### Enterprise ($499/month)
+- Team workspaces
+- Audit logs
+- SSO/SAML
+- Priority support
+- Custom integrations
+
+## Go-to-Market
+
+### Week 1: Launch
+- [ ] Ship to npm
+- [ ] Post on Hacker News
+- [ ] Twitter/X announcement
+- [ ] Dev.to article: "Make Your Site AI-Agent Ready in 5 Minutes"
+
+### Week 2: Community
+- [ ] Discord server
+- [ ] GitHub discussions
+- [ ] YouTube demo video
+- [ ] Reach out to 50 AI agent builders
+
+### Month 1: Revenue
+- [ ] ProductHunt launch
+- [ ] Paid ads on dev newsletters
+- [ ] Partner with WebMCP early adopters
+- [ ] Enterprise outreach (50 companies)
+
+## Risks & Mitigations
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| WebMCP spec changes | High | Version lock, follow W3C group |
+| Competition from Google | High | Move fast, focus on DX |
+| Low adoption | Medium | Strong content marketing |
+| AI analysis quality | Medium | Human review option, feedback loop |
+
+## Team
+
+- **Edison** (Avatar Consulting): Product strategy, marketing
+- **Atlas**: Implementation lead
+- **Cipher**: Technical architecture
+- **Aria**: Documentation, content
+
+## Timeline
+
+| Week | Milestone |
+|------|-----------|
+| 1 | CLI scaffold, scan/suggest commands |
+| 2 | Generate/validate commands, beta launch |
+| 3 | Inject command, CI integration |
+| 4 | ProductHunt launch, enterprise outreach |
+
+## Appendix
+
+### WebMCP Reference
+- Spec: https://webmcp.link
+- Chrome flags: chrome://flags → WebMCP
+- W3C Community Group: Web Machine Learning CG
+
+### Competitive Landscape
+- No direct competitors yet (first mover advantage)
+- Indirect: Puppeteer, Playwright (low-level), browser extensions