webpuppet-rs-mcp
MCP (Model Context Protocol) server for webpuppet browser automation.
This crate provides a standards-compliant MCP server that exposes webpuppet functionality as tools for AI assistants like GitHub Copilot, Claude Desktop, and other MCP-compatible clients.
Features
- MCP-compliant: Implements JSON-RPC 2.0 over stdio (standard MCP transport)
- Tool exposure: Exposes AI prompting, screenshot, and research capabilities
- Security guardrails: Inherits webpuppet's permission system
- Response screening: Filters prompt injections and malicious content
- Browser detection: Automatically finds Brave/Chrome/Chromium
- Human intervention: Pause/resume for captchas, 2FA, and manual steps
Available Tools
Installation
# Build and install
cargo install --path .
# Or run from source
cargo run -p webpuppet-mcp -- --stdio
Usage with VS Code / GitHub Copilot
Add to your .vscode/mcp.json:
{
"servers": {
"webpuppet": {
"command": "webpuppet-mcp",
"args": ["--stdio"],
"env": {}
}
}
}
Or if running from cargo:
{
"servers": {
"webpuppet": {
"command": "cargo",
"args": ["run", "-p", "webpuppet-mcp", "--", "--stdio"],
"cwd": "/path/to/webpuppet",
"env": {}
}
}
}
Usage with Claude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"webpuppet": {
"command": "webpuppet-mcp",
"args": ["--stdio"]
}
}
}
Human Intervention System
The MCP server includes tools for human-in-the-loop workflows:
When Intervention is Needed
- Captcha: reCAPTCHA, hCaptcha, Cloudflare challenges
- Two-Factor Auth: SMS codes, TOTP, email verification
- Login: Session expired, auth required
- Rate Limits: Too many requests
Workflow
- Agent calls
webpuppet_intervention_statusto check state - If intervention needed, agent notifies user
- User completes manual task in visible browser
- User/agent calls
webpuppet_intervention_completewithsuccess=true - Automation resumes
Example
Agent: "I need to send a prompt to Claude but see a captcha..."
Agent: [calls webpuppet_intervention_status]
Agent: "⚠️ A captcha is displayed. Please complete it in the browser."
User: [solves captcha manually]
User: "Done!"
Agent: [calls webpuppet_intervention_complete with success=true]
Agent: "Thank you! Continuing..."
Dependency: security-mcp wrap (DRAFT)
Recommended fleet layout for IDE/cabal agents:
Example (operator-owned; validate paths and tokens locally):
{
"servers": {
"webpuppet": {
"command": "security-mcp",
"args": ["--stdio", "--wrap", "--wrap-command", "webpuppet-mcp", "--wrap-arg", "--stdio"],
"env": {
"SECURITY_MCP_WRAP": "1"
}
}
}
}
Do not treat wrap as a pinned STABLE contract until security-mcp bulletin promotion and consumer acknowledgment in this repo are recorded (separate PR).
Security Model
All operations are subject to the webpuppet permission system:
Default (Secure) Policy
- ✅ Allowed: Navigate, ReadContent, SendPrompt, ReadResponse, NewConversation, ContinueConversation, Screenshot
- ❌ Blocked: DeleteAccount, ChangePassword, ModifyPayment, RevokeTokens, FileSystemAccess, etc.
- 🌐 Domains: Only AI provider domains (claude.ai, x.com, gemini.google.com)
- 🌐 HTTPS-only: In secure mode,
http://URLs are denied - ⚠️ Risk Threshold: Max risk level 5 (out of 10)
Permission Policies
# Secure (default) - blocks destructive operations, allows AI interaction
webpuppet-mcp --policy secure
# Read-only - only allows reading, no prompts or modifications
webpuppet-mcp --policy readonly
# Permissive - allows most non-destructive operations (use with caution)
webpuppet-mcp --policy permissive
Response Screening
All AI responses are automatically screened for:
- Invisible text: Zero-width characters, 1pt fonts
- Prompt injections: "Ignore previous instructions" patterns
- Encoded payloads: Base64, hex encoded content
- Hidden elements: CSS display:none, opacity:0
If screening detects issues, the response is sanitized and a warning is included.
Example Tool Calls
Send a Prompt
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "webpuppet_prompt",
"arguments": {
"provider": "claude",
"message": "Explain how io_uring works in Rust",
"context": "Focus on memory safety"
}
}
}
Check Permission
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "webpuppet_check_permission",
"arguments": {
"operation": "DeleteAccount"
}
}
}
Response:
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"content": [{
"type": "text",
"text": "# Permission Check\n\n**Operation**: `DeleteAccount`\n**Status**: ❌ DENIED\n**Reason**: Operation explicitly denied by policy\n**Risk Level**: 10/10"
}],
"isError": false
}
}
Architecture
┌─────────────────────────────────────────────────┐
│ MCP Client │
│ (VS Code, Claude Desktop, etc.) │
└─────────────────────┬───────────────────────────┘
│ JSON-RPC 2.0 / stdio
┌─────────────────────▼───────────────────────────┐
│ webpuppet-mcp Server │
│ ┌───────────────────────────────────────────┐ │
│ │ Permission Guard │ │
│ │ - Operation allowlist/blocklist │ │
│ │ - Domain restrictions │ │
│ │ - Risk level enforcement │ │
│ │ - Audit logging │ │
│ └───────────────────────────────────────────┘ │
│ ┌───────────────────────────────────────────┐ │
│ │ Tool Registry │ │
│ │ - webpuppet_prompt │ │
│ │ - webpuppet_screenshot │ │
│ │ - webpuppet_list_providers │ │
│ │ - webpuppet_detect_browsers │ │
│ │ - webpuppet_check_permission │ │
│ └───────────────────────────────────────────┘ │
└─────────────────────┬───────────────────────────┘
│
┌─────────────────────▼───────────────────────────┐
│ webpuppet │
│ - Browser automation (Brave/Chrome) │
│ - AI provider integration │
│ - Content screening │
│ - Session management │
└─────────────────────────────────────────────────┘
License
MIT
