@weavetab/mcp 2.5.0-beta.5 → 2.5.1

package/README.md

@@ -1,153 +1,269 @@
-# MCP Registry
+<div align="center">
 
-The MCP registry provides MCP clients with a list of MCP servers, like an app store for MCP servers.
+<img src="weavetab-banner.png"  alt="Weavetab" /><br /><br />
 
-[**📤 Publish my MCP server**](docs/modelcontextprotocol-io/quickstart.mdx) | [**⚡️ Live API docs**](https://registry.modelcontextprotocol.io/docs) | [**👀 Ecosystem vision**](docs/design/ecosystem-vision.md) | 📖 **[Full documentation](./docs)**
+<p>The open automation engine for AI agents.<br />Control live browsers and desktop apps locally with instant execution.</p>
 
-## Development Status
+<p>
+  <a href="https://github.com/weavetab/mcp/releases"><img src="https://img.shields.io/github/v/release/weavetab/mcp?label=version&style=flat-square&color=3b82f6" alt="version" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-8b5cf6?style=flat-square" alt="license" /></a>
+  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-10b981?style=flat-square" alt="MCP" /></a>
+  <img src="https://img.shields.io/badge/Node.js-%3E%3D18-green?style=flat-square" alt="Node" />
+  <a href="docs/tools/tools.md"><img src="https://img.shields.io/badge/tools-41-ec4899?style=flat-square" alt="tools" /></a>
+  <a href="https://github.com/sponsors/fy2ne"><img src="https://img.shields.io/badge/sponsor-fy2ne-ea4aaa?style=flat-square&logo=github-sponsors" alt="sponsor" /></a>
+</p>
 
-**2025-10-24 update**: The Registry API has entered an **API freeze (v0.1)** 🎉. For the next month or more, the API will remain stable with no breaking changes, allowing integrators to confidently implement support. This freeze applies to v0.1 while development continues on v0. We'll use this period to validate the API in real-world integrations and gather feedback to shape v1 for general availability. Thank you to everyone for your contributions and patience—your involvement has been key to getting us here!
+<p>
+  <a href="docs/tools/tools.md">Tool Reference</a> &nbsp;&middot;&nbsp;
+  <a href="docs/DOCUMENTATION.md">Documentation</a> &nbsp;&middot;&nbsp;
+  <a href="ARCHITECTURE.md">Architecture</a> &nbsp;&middot;&nbsp;
+  <a href="SUPPORT.md">Support</a> &nbsp;&middot;&nbsp;
+  <a href="SECURITY.md">Security</a>
+</p>
 
-**2025-09-08 update**: The registry has launched in preview 🎉 ([announcement blog post](https://blog.modelcontextprotocol.io/posts/2025-09-08-mcp-registry-preview/)). While the system is now more stable, this is still a preview release and breaking changes or data resets may occur. A general availability (GA) release will follow later. We'd love your feedback in [GitHub discussions](https://github.com/modelcontextprotocol/registry/discussions/new?category=ideas) or in the [#registry-dev Discord](https://discord.com/channels/1358869848138059966/1369487942862504016) ([joining details here](https://modelcontextprotocol.io/community/communication)).
+</div>
 
-Registry Working Group:
-- **Radoslav (Rado) Dimitrov** (Stacklok) [@rdimitrov](https://github.com/rdimitrov) - WG Lead
-- **Tadas Antanavicius** (PulseMCP) [@tadasant](https://github.com/tadasant)
-- **Bob Dickinson** (TeamSpark) [@BobDickinson](https://github.com/BobDickinson)
-- **Preeti (Pree) Dewani** (Ravenmail) [@pree-dew](https://github.com/pree-dew)
+---
 
-## Contributing
+Weavetab is the open automation engine for AI agents. It connects models directly to live Chromium browsers and Electron desktop applications via native **Chrome DevTools Protocol (CDP)** sockets — no WebDriver binaries, no cloud relay, zero telemetry.
 
-We use multiple channels for collaboration - see [modelcontextprotocol.io/community/communication](https://modelcontextprotocol.io/community/communication).
+Actions execute with **sub-10ms latency**. Web pages are translated into agent-readable semantic maps with turn-by-turn diffing that reduces token usage by **up to 95%**. Built-in security enforces local domain policies, role-based access control, and client-side credential injection.
 
-Often (but not always) ideas flow through this pipeline:
+Built and architected by [fy2ne](https://github.com/fy2ne).
 
-- **[Discord](https://modelcontextprotocol.io/community/communication)** - Real-time community discussions
-- **[Discussions](https://github.com/modelcontextprotocol/registry/discussions)** - Propose and discuss product/technical requirements
-- **[Issues](https://github.com/modelcontextprotocol/registry/issues)** - Track well-scoped technical work  
-- **[Pull Requests](https://github.com/modelcontextprotocol/registry/pulls)** - Contribute work towards issues
+---
 
-### Quick start:
+## Why not Playwright or Puppeteer?
 
-#### Pre-requisites
+> The standard approach — Playwright over MCP — works. But it carries fundamental architectural costs that compound at scale.
 
-- **Docker**
-- **Go 1.24.x**
-- **ko** - Container image builder for Go ([installation instructions](https://ko.build/install/))
-- **golangci-lint v2.4.0**
+|  | Playwright / Puppeteer | **Weavetab** |
+|---|---|---|
+| **Protocol layer** | WebDriver BiDi or CDP via browser binary | Raw CDP WebSocket, Layer 0 |
+| **Tool execution latency** | 50–300 ms (binary + IPC overhead) | **3–8 ms** |
+| **Desktop app control** | Browser only | Chrome + any Electron app (Discord, VS Code, Figma…) |
+| **DOM representation** | Full HTML dump to LLM | Semantic Map 3.0 with delta diffing |
+| **Token cost per map** | ~2,000–8,000 tokens | **~80–400 tokens** (95% reduction via delta) |
+| **CAPTCHA** | API service required | **Zero-API** via CDP mouse physics |
+| **Credential safety** | Secrets passed in plaintext | **Blind Injection** — never in LLM context |
+| **Extension access** | Limited | Full Chrome Extension API surface |
 
-#### Running the server
+---
+
+## Architecture
 
-```bash
-# Start full development environment
-make dev-compose
+```
+MCP Client (Claude / Cursor / Antigravity / Copilot / Windsurf)
+       |
+       |  JSON-RPC 2.0  (stdio or WebSocket :3000)
+       v
++-------------------------------------------------------------+
+|                   Weavetab MCP Server                       |
+|                                                             |
+|  +-----------------+   +---------------------------------+  |
+|  | Security Layer  |-->|  Intelligence Engine            |  |
+|  | Rate · RBAC     |   |  Map 3.0 · Delta · Memory       |  |
+|  | Policy · Audit  |   |  Pruner · Framework Detector    |  |
+|  +-----------------+   +----------------+----------------+  |
+|                                         |                   |
+|                              +----------v----------------+  |
+|                              |  CDP Bridge               |  |
+|                              |  Ghost Cursor · Typing    |  |
+|                              |  App Router · Loop Guard  |  |
+|                              +----------+----------------+  |
++-------------------------------------------------------------+
+                                          |  CDP WebSocket (127.0.0.1)
+              +---------------------------+-----------------------------+
+              v                           v                            v
+       Chrome / Edge               VS Code / Discord          Your Electron App
+       (any tab)                   (Electron apps)            (local dev)
 ```
 
-This starts the registry at [`localhost:8080`](http://localhost:8080) with PostgreSQL. The database uses ephemeral storage and is reset each time you restart the containers, ensuring a clean state for development and testing.
+No cloud. No external process. The CDP WebSocket connection is strictly bound to `127.0.0.1`.
 
-**Note:** The registry uses [ko](https://ko.build) to build container images. The `make dev-compose` command automatically builds the registry image with ko and loads it into your local Docker daemon before starting the services.
+---
 
-By default, the registry seeds from the production API with a filtered subset of servers (to keep startup fast). This ensures your local environment mirrors production behavior and all seed data passes validation. For offline development you can seed from a file without validation with `MCP_REGISTRY_SEED_FROM=data/seed.json MCP_REGISTRY_ENABLE_REGISTRY_VALIDATION=false make dev-compose`.
+## Quick Start
 
-The setup can be configured with environment variables in [docker-compose.yml](./docker-compose.yml) - see [.env.example](./.env.example) for a reference.
+```bash
+npx -y @weavetab/mcp
+```
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "weavetab": {
+      "command": "npx",
+      "args": ["-y", "@weavetab/mcp"]
+    }
+  }
+}
+```
 
-<details>
-<summary>Alternative: Running a pre-built Docker image</summary>
+| Client | Config path |
+|---|---|
+| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Claude Code | `claude mcp add weavetab -- npx -y @weavetab/mcp` |
+| Cursor | `.cursor/mcp.json` |
+| Antigravity | `~/.gemini/antigravity/mcp/weavetab/` |
+| VS Code Copilot | `.vscode/mcp.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
 
-Pre-built Docker images are automatically published to GitHub Container Registry. Note that the image does not bundle PostgreSQL, so you need to run your own and point the registry at it via `MCP_REGISTRY_DATABASE_URL` (see [docker-compose.yml](./docker-compose.yml) for a working example):
+---
 
-```bash
-# Run latest stable release
-docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:latest
+## Core Technology
 
-# Run latest from main branch (continuous deployment)
-docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:main
+### Semantic Map 3.0
 
-# Run specific release version
-docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:v1.0.0
+The primary bottleneck in browser-based agents is DOM representation. Full HTML dumps are noisy, large, and structurally meaningless to language models. Weavetab's `browser_map` runs an in-browser CDP walker that produces a compact semantic map:
 
-# Run development build from main branch
-docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:main-20250906-abc123d
 ```
+╔═ ACTIVE DIALOG: "Confirm Payment" ═╗
+  [w:3] button "Confirm"  [w:4] button "Cancel"
 
-**Available tags:** 
-- **Releases**: `latest`, `v1.0.0`, `v1.1.0`, etc.
-- **Continuous**: `main` (latest main branch build)
-- **Development**: `main-<date>-<sha>` (specific commit builds)
+┌ "Pro Plan — $49/mo"
+  [w:12] button "Upgrade"   [w:13] button "View Details"
+  [w:14] input val:"john@example.com"  ph:"Email address"  FOCUSED
 
-</details>
+[w:20...w:38] 18 nav links: "Dashboard" ... "Sign out"
+```
 
-#### Publishing a server
+Key properties:
 
-To publish a server, we've built a simple CLI. You can use it with:
+- **Ref IDs** (`w:N`) are stable within a session and used by all interaction tools
+- **Container binding** — buttons and inputs are grouped under their parent card, row, or section header
+- **Modal hoisting** — open dialogs are isolated at the top so agents cannot miss them
+- **Link collapsing** — repeated nav/footer runs of 4+ links compress into a single token line
+- **Semantic delta** — on re-reads, only changed nodes are transmitted (`~` modified, `+` added, `−` removed), cutting re-read cost by up to 95%
 
-```bash
-# Build the latest CLI
-make publisher
+### Ghost Cursor
+
+Clicks are not dispatched as synthetic DOM events. They are delivered as a physical sequence of `Input.dispatchMouseEvent` CDP calls along a Bezier curve trajectory with randomized acceleration, natural jitter, and hold durations. Anti-bot fingerprinting that flags event-based automation does not trigger.
 
-# Use it!
-./bin/mcp-publisher --help
+`browser_pointer` supports `hover_chain` for multi-level menu traversal in a single tool call:
+
+```json
+{
+  "hover_chain": ["File", "Export As", "PNG"],
+  "click_final": true
+}
 ```
 
-See [the publisher guide](./docs/modelcontextprotocol-io/quickstart.mdx) for more details.
+### Blind Credential Injection
 
-#### Other commands
+`browser_type_secret` resolves secrets server-side from `~/.weavetab/secrets.json`. The resolved value is never included in the MCP response, never appears in DOM snapshots, and is permanently masked as `[REDACTED]` in all audit logs. The LLM context never sees the credential.
 
 ```bash
-# Run lint, unit tests and integration tests
-make check
+weavetab secrets set GITHUB_TOKEN
+# Stored. Never echoed, never logged, never surfaced to the agent.
 ```
 
-There are also a few more helpful commands for development. Run `make help` to learn more, or look in [Makefile](./Makefile).
+### Electron & Desktop App Automation
 
-<!--
-For Claude and other AI tools: Always prefer make targets over custom commands where possible.
--->
+Any tool accepts an optional `app` parameter that routes the command to a registered Electron process instead of a browser tab:
 
-## Architecture
+```json
+{ "app": "discord", "ref": "w:24", "text": "Hey, deploying now" }
+```
+
+Register apps in `~/.weavetab/config.json`:
+
+```json
+{
+  "electron": {
+    "discord":  "C:\\Users\\<user>\\AppData\\Local\\Discord\\Discord.exe",
+    "vscode":   "C:\\Users\\<user>\\AppData\\Local\\Programs\\Microsoft VS Code\\Code.exe",
+    "figma":    "C:\\Users\\<user>\\AppData\\Local\\Figma\\Figma.exe"
+  }
+}
+```
 
-### Project Structure
+Weavetab auto-attaches via CDP to the registered process. No code changes required in the target application.
 
+### Zero-API CAPTCHA Solving
+
+`browser_captcha` solves Cloudflare Turnstile, reCAPTCHA v2/v3, GeeTest, and hCaptcha by orchestrating CDP mouse events that replicate human behavioral signatures — velocity curves, micro-pauses, scroll inertia — with no third-party API, no external service, and no API key required.
+
+---
+
+## Tool Suite
+
+41 tools across 9 categories. Full parameter reference: [`docs/tools/tools.md`](docs/tools/tools.md)
+
+| Category | Tools |
+|---|---|
+| **Vision & DOM** | `browser_map` `browser_find` `browser_scrape` `browser_inspect` `browser_snapshot` `browser_screenshot` `browser_console` `browser_extract_design` |
+| **Input & Interaction** | `browser_click` `browser_type` `browser_type_secret` `browser_key` `browser_pointer` `browser_select` `browser_fill` `browser_upload` `browser_scroll` |
+| **Navigation & Environment** | `browser_navigate` `browser_tabs` `browser_detect` `browser_viewport` `browser_emulate` |
+| **Mission & Automation** | `browser_burst` `browser_automation` `browser_recording` `browser_pattern_learn` |
+| **Safety & Human Oversight** | `browser_dialog` `browser_thoughts` `browser_clipboard` `browser_wait` |
+| **Autonomous CAPTCHA** | `browser_captcha` |
+| **Network & Storage** | `browser_network_intercept` `browser_storage` `browser_cookies` `browser_checkpoint` `browser_performance` |
+| **Office Documents** | `browser_office` |
+| **Canvas & Eval** | `browser_eval` `browser_pdf` `browser_canvas` `browser_highlight` |
+
+---
+
+## Security
+
+- **Transport**: CDP WebSocket strictly bound to `127.0.0.1`. No listener on external interfaces.
+- **Policy Engine**: Per-domain `allow` / `read-only` / `deny` / `audit` rules under the top-level `policies` array in `~/.weavetab/config.json`
+- **RBAC**: Five roles — `admin`, `operator`, `viewer`, `automation`, `system` — enforce tool-level permission gates
+- **Blind Injection**: Credentials resolved server-side, masked in all outputs and audit logs
+- **Loop Breaker**: Strike-based stuck-loop detector halts runaway autonomous sequences
+- **Audit Log**: All tool invocations, policy decisions, and errors written to `~/.weavetab-system/logs/mission_<timestamp>.log`
+
+Security vulnerabilities: `security@fy2ne.me` (do not use public issues).
+
+---
+
+## CLI Reference
+
+```bash
+weavetab                        # Start in stdio mode (default)
+weavetab --ws --port 3000       # WebSocket daemon mode
+weavetab config                 # Interactive configuration wizard
+weavetab secrets set KEY_NAME   # Store a secret (never echoed)
+weavetab secrets list           # List stored secret keys (not values)
+weavetab plugin add <name>      # Install a plugin from npm
+weavetab plugin list            # List installed plugins
 ```
-├── cmd/                     # Application entry points
-│   └── publisher/           # Server publishing tool
-├── data/                    # Seed data
-├── deploy/                  # Deployment configuration (Pulumi)
-├── docs/                    # Documentation
-├── internal/                # Private application code
-│   ├── api/                 # HTTP handlers and routing
-│   ├── auth/                # Authentication (GitHub OAuth, JWT, namespace blocking)
-│   ├── config/              # Configuration management
-│   ├── database/            # Data persistence (PostgreSQL)
-│   ├── service/             # Business logic
-│   ├── telemetry/           # Metrics and monitoring
-│   └── validators/          # Input validation
-├── pkg/                     # Public packages
-│   ├── api/                 # API types and structures
-│   │   └── v0/              # Version 0 API types
-│   └── model/               # Data models for server.json
-├── scripts/                 # Development and testing scripts
-├── tests/                   # Integration tests
-└── tools/                   # CLI tools and utilities
-    └── validate-*.sh        # Schema validation tools
+
+Configuration file: `~/.weavetab/config.json`
+
+```json
+{
+  "browserType": "chromium",
+  "headless": false,
+  "extension": true,
+  "maxActionsPerMinute": 60,
+  "role": "admin",
+  "electron": {
+    "discord":     "...",
+    "vscode":      "...",
+    "antigravity": "..."
+  }
+}
 ```
 
-### Authentication
+---
 
-Publishing supports multiple authentication methods:
-- **GitHub OAuth** - For publishing by logging into GitHub
-- **GitHub OIDC** - For publishing from GitHub Actions
-- **DNS verification** - For proving ownership of a domain and its subdomains
-- **HTTP verification** - For proving ownership of a domain
+## Extensibility
+
+Weavetab exposes a typed Plugin SDK for authoring custom MCP tools, HUD overlays, and tool lifecycle hooks:
+
+```bash
+npx @weavetab/sdk init my-plugin
+```
 
-The registry validates namespace ownership when publishing. E.g. to publish...:
-- `io.github.domdomegg/my-cool-mcp` you must login to GitHub as `domdomegg`, or be in a GitHub Action on domdomegg's repos
-- `me.adamjones/my-cool-mcp` you must prove ownership of `adamjones.me` via DNS or HTTP challenge
+See [`docs/PLUGINS.md`](docs/PLUGINS.md) for architecture, manifest spec, and SDK API reference.
 
-## Community Projects
+---
 
-Check out [community projects](docs/community-projects.md) to explore notable registry-related work created by the community.
+## License
 
-## More documentation
+AGPL-3.0-only. Client connections over stdio or WebSocket do not extend copyleft obligations to your client application or models.
 
-See the [documentation](./docs) for more details if your question has not been answered here!
+[Sponsor development](https://github.com/sponsors/fy2ne) &nbsp;&middot;&nbsp; [Discussions](https://github.com/weavetab/mcp/discussions) &nbsp;&middot;&nbsp; [SUPPORT.md](SUPPORT.md)