@weavetab/mcp 2.5.0-beta.0 → 2.5.0-beta.2

package/AGENTS.md

@@ -9,6 +9,7 @@ This document is the universal specification for AI agents (Cursor, Antigravity,
 1. **Layer 0 Direct CDP**:
    * Weavetab connects directly to Chrome DevTools Protocol (CDP) via WebSocket (`127.0.0.1`).
    * **Do NOT introduce Puppeteer, Playwright, or Selenium wrapper abstractions**.
+   * Supports both standard browsers (Chrome/Chromium) and **any Electron/desktop webview app** (Discord, VS Code, Antigravity, Figma, Obsidian, Slack, or local apps from source) via the generic `app` parameter and `electron` config mapping.
 
 2. **Deterministic State & Token Efficiency**:
    * Use the **Semantic Delta Engine** for DOM snapshot diffing.

package/LICENSE

@@ -1,5 +1,5 @@
-Weavetab v2.5.0+ — Copyright (C) 2026 fy2ne
-Licensing inquiries: license@weavetab.dev
+Weavetab — Copyright (C) 2026 fy2ne
+Licensing inquiries: license@weavetab.pages.dev
 Commercial licenses available for proprietary/embedded use.
 
 MCP Transport Clarification:

package/README.md

@@ -3,8 +3,8 @@
 ![WeaveTab MCP Logo](icon.png)
 
   <h1>WeaveTab MCP</h1>
-  <p><strong>The Production-Grade Browser Automation MCP Server</strong></p>
-  <p><em>Direct CDP at Layer 0 — No WebDriver. No Cloud. No Compromise.</em></p>
+  <p><strong>Direct Layer 0 interface for AI agents across web and desktop applications.</strong></p>
+  <p><em>No WebDriver. No Cloud. Pure Control.</em></p>
 
   <p>
     <img src="https://img.shields.io/badge/version-2.5.0-3b82f6?style=flat-square" alt="Version" />
@@ -17,7 +17,7 @@
 
   <p>
     <a href="https://github.com/weavetab/mcp">GitHub</a> ·
-    <a href="docs/TOOLS.md">Tool Reference</a> ·
+    <a href="docs/tools/overview.md">Tool Reference</a> ·
     <a href="docs/DOCUMENTATION.md">Documentation</a> ·
     <a href="SECURITY.md">Security Policy</a> ·
     <a href="CONTRIBUTING.md">Contributing</a>
@@ -26,7 +26,7 @@
 
 ---
 
-**Weavetab** is a local, high-performance [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that grants AI agents human-like control over Chromium browsers. Unlike Playwright or Puppeteer, Weavetab communicates directly over the **Chrome DevTools Protocol (CDP) WebSocket at Layer 0** — no WebDriver process, no browser binary download, no heavy abstraction layer. This architectural decision yields **3–8ms mean tool execution latency** and eliminates an entire class of process-level overhead.
+**Weavetab** is a local, high-performance [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server providing AI agents with direct, physical control across Chromium browsers and Electron desktop applications (Discord, VS Code, Antigravity, Figma, Slack, and local projects). Communicating directly over the **Chrome DevTools Protocol (CDP) WebSocket at Layer 0**, Weavetab eliminates WebDriver binaries, browser wrappers, and cloud middleware for deterministic **3–8ms tool execution latency**.
 
 Built by **fy2ne**, Weavetab is engineered for autonomous AI agents operating in production environments where latency, security, and token efficiency are non-negotiable.
 
@@ -37,6 +37,7 @@ Built by **fy2ne**, Weavetab is engineered for autonomous AI agents operating in
 - [Quick Start](#quick-start)
 - [Architecture](#architecture)
 - [Core Features](#core-features)
+- [Electron & Desktop App Automation](#electron--desktop-app-automation)
 - [Tool Categories](#tool-categories)
 - [CLI Reference](#cli-reference)
 - [Configuration](#configuration)
@@ -215,6 +216,136 @@ Chain N actions in a single MCP round-trip with `browser_burst`. Supports macro
 
 ---
 
+## Electron & Desktop App Automation
+
+Weavetab extends its Layer 0 CDP engine beyond web browsers to **any Electron-based desktop application or locally hosted webview app** (e.g. **Discord**, **Slack**, **VS Code**, **Antigravity IDE**, **Figma**, **Obsidian**, **Postman**, or your own custom Electron projects running from source).
+
+Because Electron is built on Chromium and Blink, Weavetab controls desktop apps using the exact same low-latency CDP primitives (`browser_map`, `browser_click`, `browser_type`, `browser_tabs`, etc.) with zero app-specific hacks or overhead.
+
+### 1. Configuring Installed Desktop Apps
+
+Add your application executable paths to `~/.weavetab/config.json` (or `./.weavetab/config.json`) under the `"electron"` dictionary:
+
+```json
+{
+  "browserType": "chromium",
+  "electron": {
+    "discord": "C:\\Users\\<user>\\AppData\\Local\\Discord\\app-1.0.9183\\Discord.exe",
+    "antigravity": "C:\\Users\\<user>\\AppData\\Local\\Programs\\antigravity\\Antigravity.exe",
+    "vscode": "C:\\Users\\<user>\\AppData\\Local\\Programs\\Microsoft VS Code\\Code.exe",
+    "figma": "C:\\Users\\<user>\\AppData\\Local\\Figma\\Figma.exe",
+    "obsidian": "C:\\Users\\<user>\\AppData\\Local\\Obsidian\\Obsidian.exe",
+    "slack": "/Applications/Slack.app/Contents/MacOS/Slack"
+  }
+}
+```
+
+### 2. Automating Local / Source-Hosted Electron Projects
+
+If you are developing a local Electron app from source code or running it via Vite / Webpack / Next.js on `localhost`, you can automate it in two ways:
+
+#### Option A: Launch with Remote Debugging Flag
+Start your development process passing the Chrome DevTools Protocol remote debugging port:
+
+```bash
+# Standard Electron CLI / npm script
+npx electron . --remote-debugging-port=9222
+
+# Or within your package.json scripts:
+# "dev:debug": "electron . --remote-debugging-port=9222"
+npm run dev:debug
+```
+
+Then configure `"attachPort": 9222` in `.weavetab/config.json` or register it in `"electron"`:
+```json
+{
+  "electron": {
+    "my-dev-app": "npm run dev:debug"
+  }
+}
+```
+
+#### Option B: Register Local App Executable / Wrapper Script
+Specify your local build binary or launch script in `"electron"`:
+```json
+{
+  "electron": {
+    "my-local-app": "C:\\Users\\<user>\\projects\\my-app\\node_modules\\electron\\dist\\electron.exe"
+  }
+}
+```
+
+### 3. Controlling Desktop Apps via MCP Tools
+
+All Weavetab tools accept an optional `app` parameter specifying which application to target. When specified, Weavetab automatically connects to that app's dedicated CDP session without launching or interfering with your default browser.
+
+#### Launch / Focus Desktop App
+```json
+{
+  "name": "browser_navigate",
+  "arguments": {
+    "app": "antigravity"
+  }
+}
+```
+
+#### List & Switch Windows / Workbenches
+Desktop apps often run multiple browser windows or background webviews. Inspect and switch active contexts using `browser_tabs`:
+```json
+{
+  "name": "browser_tabs",
+  "arguments": {
+    "action": "list",
+    "app": "antigravity"
+  }
+}
+```
+
+Switch to a specific window/tab:
+```json
+{
+  "name": "browser_tabs",
+  "arguments": {
+    "action": "switch",
+    "tabId": "D8832CBF1FEF413B6E09E96EF8C82DFF",
+    "app": "antigravity"
+  }
+}
+```
+
+#### Inspect DOM & Interact with UI Elements
+Generate actionable Ref IDs (`w:NN`) and interact directly with native desktop UI components:
+```json
+// 1. Snapshot the Desktop App UI
+{
+  "name": "browser_map",
+  "arguments": {
+    "app": "antigravity"
+  }
+}
+
+// 2. Click Settings or Menus
+{
+  "name": "browser_click",
+  "arguments": {
+    "ref": "w:14",
+    "app": "antigravity"
+  }
+}
+
+// 3. Type text into Desktop inputs
+{
+  "name": "browser_type",
+  "arguments": {
+    "ref": "w:28",
+    "text": "Hello from WeaveTab automation!",
+    "app": "discord"
+  }
+}
+```
+
+---
+
 ## Tool Categories
 
 Weavetab exposes **44+ MCP tools** organized into functional categories. See the complete reference in [`docs/TOOLS.md`](docs/TOOLS.md).
@@ -389,12 +520,17 @@ Weavetab auto-generates a config file at `~/.weavetab/config.json` on first run.
 {
   "browserType": "chromium",
   "headless": false,
+  "extension": true,
   "devMode": false,
   "maxActionsPerMinute": 60,
   "role": "admin",
   "telemetry": false,
   "downloadDir": "~/Downloads",
-  "profileDir": "~/.weavetab/profile"
+  "profileDir": "~/.weavetab/profile",
+  "electron": {
+    "discord": "C:\\Users\\<user>\\AppData\\Local\\Discord\\app-1.0.9183\\Discord.exe",
+    "antigravity": "C:\\Users\\<user>\\AppData\\Local\\Programs\\antigravity\\Antigravity.exe"
+  }
 }
 ```
 
@@ -402,10 +538,12 @@ Weavetab auto-generates a config file at `~/.weavetab/config.json` on first run.
 |-----|------|---------|-------------|
 | `browserType` | `"chromium"` \| `"firefox"` \| `"webkit"` | `"chromium"` | Which browser to launch/attach |
 | `headless` | boolean | `false` | Run browser without a window |
+| `extension` | boolean | `true` | Enable Weavetab Chrome extension integration |
 | `devMode` | boolean | `false` | Verbose CDP logging |
 | `maxActionsPerMinute` | number | `60` | Rate limit threshold |
 | `role` | `"admin"` \| `"system"` \| `"viewer"` \| `"automation"` | `"admin"` | RBAC role |
 | `telemetry` | boolean | `false` | Opt-in telemetry |
+| `electron` | `Record<string, string>` | `{}` | Named map of Electron desktop apps to executable paths or startup scripts |
 
 ### Domain Policy
 
@@ -472,12 +610,12 @@ Weavetab connects out-of-the-box via stdio JSON-RPC 2.0 with all major AI coding
 
 | Environment | Setup Method | Guided Web Installer |
 | :--- | :--- | :--- |
-| **Cursor** | `.cursor/mcp.json` | [weavetab.dev/mcp/install/cursor](https://weavetab.dev/mcp/install/cursor) |
-| **Antigravity** | `~/.gemini/antigravity/mcp/` | [weavetab.dev/mcp/install/antigravity](https://weavetab.dev/mcp/install/antigravity) |
-| **Claude Desktop** | `claude_desktop_config.json` | [weavetab.dev/mcp/install/claude-desktop](https://weavetab.dev/mcp/install/claude-desktop) |
-| **Claude Code** | `claude mcp add` | [weavetab.dev/mcp/install/claude-code](https://weavetab.dev/mcp/install/claude-code) |
-| **VS Code / Copilot** | 1-Click Protocol / `settings.json` | [weavetab.dev/mcp/install/vscode](https://weavetab.dev/mcp/install/vscode) |
-| **Windsurf** | `mcp_config.json` | [weavetab.dev/mcp/install/windsurf](https://weavetab.dev/mcp/install/windsurf) |
+| **Cursor** | `.cursor/mcp.json` | [weavetab.pages.dev/mcp/install/cursor](https://github.com/weavetab/mcp/mcp/install/cursor) |
+| **Antigravity** | `~/.gemini/antigravity/mcp/` | [weavetab.pages.dev/mcp/install/antigravity](https://github.com/weavetab/mcp/mcp/install/antigravity) |
+| **Claude Desktop** | `claude_desktop_config.json` | [weavetab.pages.dev/mcp/install/claude-desktop](https://github.com/weavetab/mcp/mcp/install/claude-desktop) |
+| **Claude Code** | `claude mcp add` | [weavetab.pages.dev/mcp/install/claude-code](https://github.com/weavetab/mcp/mcp/install/claude-code) |
+| **VS Code / Copilot** | 1-Click Protocol / `settings.json` | [weavetab.pages.dev/mcp/install/vscode](https://github.com/weavetab/mcp/mcp/install/vscode) |
+| **Windsurf** | `mcp_config.json` | [weavetab.pages.dev/mcp/install/windsurf](https://github.com/weavetab/mcp/mcp/install/windsurf) |
 
 ---
 
@@ -716,58 +854,85 @@ Setting `"devMode": true` in configuration or `WEAVETAB_DEV=1` activates diagnos
 
 ## Plugin System
 
-Weavetab supports dynamic tool extension via the **Plugin System**. Any npm package containing a valid `weavetab.json` manifest found in `node_modules` (or official `@weavetab/plugin-*` packages) is automatically discovered and loaded at startup. Community plugins are not restricted to any prefix—name them anything (e.g., `wt-n8n`, `seo-auditor`, `pdf-extract`).
+> [!NOTE]
+> **PLUGIN ENGINE (v2.5.0-beta.2)**
+> 
+> The Weavetab Plugin System and SDK are in **v2.5.0-beta.2**.
+> Use the official **[`@weavetab/sdk`](https://www.npmjs.com/package/@weavetab/sdk)** to build, scaffold, and publish plugins.
+
+Weavetab supports dynamic tool extension via the **Plugin System**. Any npm package containing a valid `weavetab.json` manifest found in `node_modules` (or official `@weavetab/plugin-*` packages) is automatically discovered and loaded into the MCP server.
 
-> 📖 See [Developer Plugin Guide](../docs/dev_plugin.md) for a step-by-step tutorial, and [docs/PLUGINS.md](docs/PLUGINS.md) for the complete architecture and manifest specification.
+### Key Capabilities in v2.5.0-beta.2:
+1. **Isolated Configuration Sandbox**: Each plugin maintains its own settings in `~/.weavetab/plugins/<name>/config.json` without modifying core Weavetab config.
+2. **Sandboxed Key-Value & File Storage**: Secure storage inside `~/.weavetab/plugins/<name>/` via `ctx.storage` with path traversal protection.
+3. **Real-time Extension & HUD Visuals**: Floating thought bubbles (`ctx.extension.showThought`), status badges (`setHudState`), and custom CSS injection (`injectStyles`).
+4. **Tool Overrides & Wrapping**: Wrap or modify built-in MCP tools (e.g. `browser_eval`, `browser_click`) via `ctx.mcp.overrideTool`.
+5. **Lifecycle Hooks**: Intercept actions before and after tool calls with `ctx.hooks.beforeToolCall` and `ctx.hooks.afterToolCall`.
+
+> 📖 See [Developer Plugin Guide](docs/dev_plugin.md) for a step-by-step tutorial, and [docs/PLUGINS.md](docs/PLUGINS.md) for the complete architecture and manifest specification.
 
 ### Quick Scaffold & Build
 
 ```bash
-# 1. Interactive scaffolding wizard
-npx weavetab init
+# 1. Scaffold a new plugin
+npx @weavetab/sdk init my-custom-plugin
+cd my-custom-plugin
+npm install
 
-# 2. Build, type-check, and auto-sync weavetab.json
-npx weavetab build
+# 2. Build and compile
+npm run build
 ```
 
 ### Installing a Plugin
 
 ```bash
 # Official plugin
-wt plugin add @weavetab/plugin-sample
+weavetab plugin add @weavetab/plugin-youtube
 
-# Community plugin (any npm name)
-wt plugin add seo-auditor
-# or via npm
-npm install wt-n8n
+# Community plugin (any npm package name)
+weavetab plugin add seo-auditor
 ```
 
-Restart `weavetab` — the plugin's tools are automatically registered as additional MCP tools.
+Restart `weavetab` — the plugin's tools are automatically registered into the MCP runtime.
 
-### Developing a Plugin
+### Authoring a Plugin
 
 ```typescript
 // src/index.ts
-import type { WeavetabPlugin } from "@weavetab/mcp";
+import { definePlugin, type PluginContext } from "@weavetab/sdk";
+
+export default definePlugin({
+  name: "weavetab-plugin-sample",
+
+  defaultConfig: {
+    showVisualHud: true,
+  },
 
-const plugin: WeavetabPlugin = {
-  name: "my-plugin",
-  version: "1.0.0",
-  tools: [
-    {
+  async onLoad(ctx: PluginContext) {
+    ctx.mcp.registerTool({
       name: "my_custom_tool",
-      description: "WHAT: Does something | WHEN: Use for X | EXAMPLE: my_custom_tool({ param: 'value' })",
-      schema: { param: { type: "string", description: "Input parameter" } },
-      handler: async (args, session, config) => {
-        // Your tool implementation using Chrome DevTools Protocol session
-        const evalResult = await session.evaluate(() => document.title);
-        return { success: true, title: evalResult };
+      description: "Custom tool registered into Weavetab runtime",
+      schema: {
+        type: "object",
+        properties: {
+          param: { type: "string", description: "Input parameter" }
+        }
+      },
+      handler: async (args: { param?: string }, session: any) => {
+        // Show thought bubble on active tab
+        if (ctx.config.showVisualHud && session) {
+          await ctx.extension.showThought(session, `✨ Running tool with ${args.param || "default"}`);
+        }
+
+        return {
+          content: [
+            { type: "text", text: `Executed with: ${args.param || "default"}` }
+          ]
+        };
       }
-    }
-  ]
-};
-
-export default plugin;
+    });
+  }
+});
 ```
 
 Plugin tools follow the standard MCP contract: structured Zod input, deterministic JSON output, audit logging, and `WeaveError` protocol on failure.
@@ -884,7 +1049,7 @@ Commit format: `feat:`, `fix:`, `docs:`, `chore:`, `refactor:`, `test:`
 Running Weavetab MCP as an independent process and communicating with it over standard Model Context Protocol transports (`stdio` or WebSocket JSON-RPC) does **not** cause AGPL copyleft obligations to extend to your client application, IDE, or host AI models.
 
 ### Commercial Licensing
-For commercial, proprietary, or embedded distribution without AGPL copyleft requirements, dual-licensing options are available. Inquire at `license@weavetab.dev`.
+For commercial, proprietary, or embedded distribution without AGPL copyleft requirements, dual-licensing options are available. Inquire at `license@weavetab.pages.dev`.
 
 ---
 
@@ -895,7 +1060,7 @@ For commercial, proprietary, or embedded distribution without AGPL copyleft requ
 | [GitHub Issues](https://github.com/weavetab/mcp/issues) | Bug reports, feature requests |
 | [TROUBLESHOOTING.md](TROUBLESHOOTING.md) | Common issues and fixes |
 | [docs/](docs/) | Full documentation |
-| security@weavetab.dev | Security vulnerabilities (private) |
+| security@weavetab.pages.dev | Security vulnerabilities (private) |
 
 ---
 

package/SECURITY.md

@@ -131,7 +131,7 @@ If you discover a security vulnerability in Weavetab, please **do not** open a p
 
 Instead, report via one of the following channels:
 
-- **Email**: security@Weavetab.dev
+- **Email**: security@weavetab.pages.dev
 - **GitHub**: Use the private vulnerability reporting feature on the repository
 
 ### Disclosure Timeline
@@ -185,8 +185,8 @@ To receive security notifications:
 
 For security-related inquiries:
 
-- **Security Vulnerabilities**: security@Weavetab.dev
-- **Security Questions**: conduct@Weavetab.dev
+- **Security Vulnerabilities**: security@weavetab.pages.dev
+- **Security Questions**: conduct@weavetab.pages.dev
 - **GitHub Security**: https://github.com/weavetab/mcp/security
 
 ---

package/TROUBLESHOOTING.md

@@ -199,7 +199,7 @@ browser_click({ id: "w:42" })
 **Cause:** Extension incompatibility or corrupted Chrome profile.
 
 **Solution:**
-- Try running without extension: Set `loadExtension: false` in config
+- Try running without extension: Set `"extension": false` in config
 - Use a fresh Chrome profile: Set `profileDir` to a new directory
 - Check Chrome version compatibility (requires Chrome 90+)
 - Disable hardware acceleration in Chrome settings

package/dist/cdp/bridge.d.ts

@@ -4,6 +4,7 @@ export interface BrowserInfo {
     name: string;
     path: string;
 }
+export declare function isValidElectronExecutablePath(execPath: string): boolean;
 export declare function findBrowser(preferred?: string): BrowserInfo | null;
 export declare function findFirefox(): BrowserInfo | null;
 export declare function probeAllBrowsers(): BrowserInfo[];
@@ -14,3 +15,12 @@ export declare function launchWithBridge(config: Config): Promise<{
     engine?: BrowserEngine;
 }>;
 export declare function injectStealthScript(session: CDP.Client): Promise<void>;
+export declare function getFreePort(preferredPort?: number): Promise<number>;
+export declare function testPortListening(port: number): Promise<boolean>;
+export declare function launchElectronApp(appName: string, config: Config): Promise<{
+    path: string;
+    name: string;
+    port: number;
+    engine: "chromium";
+    isElectron: true;
+}>;