WebMCP Userscripts - AI Assistant Documentation Guide

This directory contains documentation and examples for developing WebMCP userscripts that inject MCP-B servers into websites. As an AI assistant, use the following guides based on your task:

Purpose: Comprehensive development guide for creating, testing, and debugging userscripts When to use:

• When asked to create a new userscript for any website
• When debugging existing userscripts
• When you need detailed workflow phases and best practices
• For understanding the complete WebMCP ecosystem

Contents:

• Complete development workflow (6 phases)
• Tool discovery and usage patterns
• Selector strategies and React compatibility
• Testing and debugging patterns
• Common issues and solutions
• Code examples and templates

Purpose: Concise, action-oriented prompt template for rapid userscript development When to use:

• When you need to quickly create a userscript without detailed explanations
• For autonomous development without user interaction
• As a copy-paste template for immediate action

Contents:

• Step-by-step autonomous workflow
• Time-boxed development phases
• Success criteria checklist
• Minimal explanations, maximum action

Purpose: Actual implementation example showing the complete workflow for ChatGPT When to use:

• As a reference when creating similar React-based userscripts
• To understand common pitfalls and solutions
• For seeing the complete test sequence

Contents:

• Real reconnaissance results
• Actual code that works
• Issues encountered and solutions
• Complete test sequence with real tab IDs

# Navigate to userscripts directory
cd /path/to/WebMCP/webmcp-userscripts

# Create new script directory
mkdir -p scripts/[sitename]/src
cd scripts/[sitename]

# Build a script
pnpm install
pnpm run build

# Output location (for injection)
# dist/[sitename].user.js

1. Reconnaissance (Playwright MCP):

   • mcp_playwright_browser_navigate
   • mcp_playwright_browser_snapshot
   • mcp_playwright_browser_evaluate

2. Development (File tools):

   • Create files in scripts/[sitename]/src/
   • Use templates from documentation

3. Testing (WebMCP Extension):

   • mcp_mcp-b_call_extension_tool(toolName: "extension_tool_list_active_tabs")
   • mcp_mcp-b_extension_tool_execute_user_script
   • mcp_mcp-b_list_website_tools
   • mcp_mcp-b_call_website_tool

webmcp-userscripts/
├── README.md                        # This file - AI usage guide
├── WEBMCP_USERSCRIPT_GUIDE.md      # Comprehensive development guide
├── AI_AUTOMATION_PROMPT.md         # Quick autonomous template
├──               # Real-world example
├── scripts/                        # Individual userscripts
│   ├── gmail/                     # Gmail MCP-B script
│   ├── google/                    # Google search script
│   └── chatgpt/                   # ChatGPT script (see example)
├── packages/                       # Shared code
├── templates/                      # File templates
└── tests/                         # Test suites

START
  │
  ├─ User wants new userscript?
  │   ├─ Yes → Use AI_AUTOMATION_PROMPT.md
  │   └─ No ↓
  │
  ├─ User having problems?
  │   ├─ Yes → Use WEBMCP_USERSCRIPT_GUIDE.md (debugging section)
  │   └─ No ↓
  │
  ├─ User wants to understand?
  │   ├─ Yes → Use WEBMCP_USERSCRIPT_GUIDE.md (complete guide)
  │   └─ No ↓
  │
  └─ Need example?
      └─ Yes → Use

1. Always use absolute paths when injecting scripts:

   /path/to/WebMCP/webmcp-userscripts/scripts/[site]/dist/[site].user.js
   

2. Tab IDs change frequently - always re-fetch before use

3. React sites need special handling - use the React helpers from the guides

4. Build before inject - always run pnpm run build after changes

5. Tools may not appear immediately - reload tab and wait 1-2 seconds if needed

1. Playwright MCP - Browser automation and selector discovery
2. WebMCP Extension Tools - Tab management and script injection
3. Website Tools - Appear after userscript injection (site-specific)

Tool name: mcp_mcp-b_extension_tool_execute_user_script Parameters:

• filePath: Absolute path to built .user.js file
• tabId: Target browser tab ID

WebMCP Userscripts is a TypeScript monorepo for building Tampermonkey userscripts that inject MCP-B (Model Context Protocol - Browser) servers into websites. This enables AI assistants to interact with web applications through structured tools rather than brittle DOM manipulation.

• 🔧 TypeScript-first development with modern tooling
• 📦 Vite + vite-plugin-monkey for optimized userscript bundling
• 🧪 Automated testing with Puppeteer
• 🏗️ pnpm workspace monorepo structure
• 🎯 Pre-built MCP-B integration patterns
• ⚡ Hot reload development workflow

See the comprehensive guide in WEBMCP_USERSCRIPT_GUIDE.md for:

• Setting up development environment
• Creating new userscripts
• Testing and debugging
• NEW: Production deployment and script registration
• Contributing to the project

After testing your userscript, register it for automatic execution:

mcp_mcp-b_extension_tool_userscripts_register({
  filePath: "/absolute/path/to/dist/script.user.js",
  id: "sitename-mcp-server",
  matches: ["https://domain/*"],
  runAt: "document_start",
  world: "MAIN"
})

Benefits: Auto-activation, no manual injection, persistent across sessions.

MIT License - see LICENSE file for details.