@weavetab/mcp 2.5.0-beta.4 → 2.5.0-beta.5

package/README.md

@@ -1,271 +1,153 @@
-<div align="center">
-
-<img src="icon.png" width="96" alt="Weavetab" /><br /><br />
-
-<h1>Weavetab MCP</h1>
-
-<p>A local <a href="https://modelcontextprotocol.io">Model Context Protocol</a> server that gives AI agents<br />direct, physical control over browsers and desktop applications via the Chrome DevTools Protocol.</p>
-
-<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-44-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>
-
-<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>
-
-</div>
-
----
-
-Weavetab is a local, production-grade MCP server that connects AI agents directly to Chromium browsers and Electron desktop applications through the **Chrome DevTools Protocol (CDP) WebSocket at Layer 0** — no WebDriver binaries, no Playwright processes, no cloud relay.
-
-Tool invocations resolve in **3–8 ms of mean latency**. DOM state is compressed into agent-readable semantic maps and diffed across turns, cutting prompt token usage by **up to 95%**. Security is enforced locally via per-domain policies, 4-tier RBAC, and cryptographic blind credential injection.
-
-Built by [fy2ne](https://github.com/fy2ne).
-
----
-
-## Why not Playwright or Puppeteer?
-
-> The standard approach — Playwright over MCP — works. But it carries fundamental architectural costs that compound at scale.
-
-|  | 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 |
-
----
-
-## Architecture
-
-```
-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)
-```
-
-No cloud. No external process. The CDP WebSocket connection is strictly bound to `127.0.0.1`.
-
----
-
-## Quick Start
-
-```bash
-npx -y @weavetab/mcp
-```
-
-Add to your MCP client config:
-
-```json
-{
-  "mcpServers": {
-    "weavetab": {
-      "command": "npx",
-      "args": ["-y", "@weavetab/mcp"]
-    }
-  }
-}
-```
-
-| 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` |
-
----
-
-## Core Technology
-
-### Semantic Map 3.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:
-
-```
-╔═ ACTIVE DIALOG: "Confirm Payment" ═╗
-  [w:3] button "Confirm"  [w:4] button "Cancel"
-
-┌ "Pro Plan — $49/mo"
-  [w:12] button "Upgrade"   [w:13] button "View Details"
-  [w:14] input val:"john@example.com"  ph:"Email address"  FOCUSED
-
-[w:20...w:38] 18 nav links: "Dashboard" ... "Sign out"
-```
-
-Key properties:
-
-- **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%
-
-### 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.
-
-`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
-}
-```
-
-### Blind Credential Injection
-
-`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
-weavetab secrets set GITHUB_TOKEN
-# Stored. Never echoed, never logged, never surfaced to the agent.
-```
-
-### Electron & Desktop App Automation
-
-Any tool accepts an optional `app` parameter that routes the command to a registered Electron process instead of a browser tab:
-
-```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"
-  }
-}
-```
-
-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
-
-44 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` |
-| **GitHub & Documents** | `browser_github` `browser_office` |
-| **Canvas, Eval & Plugins** | `browser_eval` `browser_pdf` `browser_canvas` `browser_highlight` `list_plugins` `load_plugin` |
-
----
-
-## 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 in `~/.weavetab/policy.json`
-- **RBAC**: Four roles — `admin`, `operator`, `viewer`, `automation` — 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/logs/audit.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
-```
-
-Configuration file: `~/.weavetab/config.json`
-
-```json
-{
-  "browserType": "chromium",
-  "headless": false,
-  "extension": true,
-  "maxActionsPerMinute": 60,
-  "role": "admin",
-  "electron": {
-    "discord":     "...",
-    "vscode":      "...",
-    "antigravity": "..."
-  }
-}
-```
-
----
-
-## 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
-```
-
-See [`docs/PLUGINS.md`](docs/PLUGINS.md) for architecture, manifest spec, and SDK API reference.
-
----
-
-## License
-
-AGPL-3.0-only. Client connections over stdio or WebSocket do not extend copyleft obligations to your client application or models.
-
-[Sponsor development](https://github.com/sponsors/fy2ne) &nbsp;&middot;&nbsp; [Discussions](https://github.com/weavetab/mcp/discussions) &nbsp;&middot;&nbsp; [SUPPORT.md](SUPPORT.md)
+# MCP Registry
+
+The MCP registry provides MCP clients with a list of MCP servers, like an app store for MCP servers.
+
+[**📤 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)**
+
+## Development Status
+
+**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!
+
+**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)).
+
+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
+
+We use multiple channels for collaboration - see [modelcontextprotocol.io/community/communication](https://modelcontextprotocol.io/community/communication).
+
+Often (but not always) ideas flow through this pipeline:
+
+- **[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:
+
+#### Pre-requisites
+
+- **Docker**
+- **Go 1.24.x**
+- **ko** - Container image builder for Go ([installation instructions](https://ko.build/install/))
+- **golangci-lint v2.4.0**
+
+#### Running the server
+
+```bash
+# Start full development environment
+make dev-compose
+```
+
+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.
+
+**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`.
+
+The setup can be configured with environment variables in [docker-compose.yml](./docker-compose.yml) - see [.env.example](./.env.example) for a reference.
+
+<details>
+<summary>Alternative: Running a pre-built Docker image</summary>
+
+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
+
+# Run latest from main branch (continuous deployment)
+docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:main
+
+# Run specific release version
+docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:v1.0.0
+
+# Run development build from main branch
+docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:main-20250906-abc123d
+```
+
+**Available tags:** 
+- **Releases**: `latest`, `v1.0.0`, `v1.1.0`, etc.
+- **Continuous**: `main` (latest main branch build)
+- **Development**: `main-<date>-<sha>` (specific commit builds)
+
+</details>
+
+#### Publishing a server
+
+To publish a server, we've built a simple CLI. You can use it with:
+
+```bash
+# Build the latest CLI
+make publisher
+
+# Use it!
+./bin/mcp-publisher --help
+```
+
+See [the publisher guide](./docs/modelcontextprotocol-io/quickstart.mdx) for more details.
+
+#### Other commands
+
+```bash
+# Run lint, unit tests and integration tests
+make check
+```
+
+There are also a few more helpful commands for development. Run `make help` to learn more, or look in [Makefile](./Makefile).
+
+<!--
+For Claude and other AI tools: Always prefer make targets over custom commands where possible.
+-->
+
+## Architecture
+
+### Project Structure
+
+```
+├── 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
+```
+
+### 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
+
+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
+
+## Community Projects
+
+Check out [community projects](docs/community-projects.md) to explore notable registry-related work created by the community.
+
+## More documentation
+
+See the [documentation](./docs) for more details if your question has not been answered here!

package/dist/cdp/connector.js

@@ -614,7 +614,7 @@ export async function getTabList(agentId, targetApp) {
         }
     }
     if (!port)
-        throw new Error(`[!] No active ${targetApp ? targetApp : "browser"} session. Run browser_go or launch app first.`);
+        throw new Error(`[!] No active ${targetApp ? targetApp : "browser"} session. Run browser_navigate or launch app first.`);
     try {
         const metaSession = await withCDPTimeout(CDP({ host: "127.0.0.1", port }), 5000, "getTabList CDP");
         const { targetInfos } = await withCDPTimeout(metaSession.Target.getTargets(), 5000, "getTabList getTargets");
@@ -671,7 +671,7 @@ export async function connectToTab(targetId, port, agentId, browserContextId, ap
     const lock = readLock(appName);
     const p = port || (appName ? lock?.port : (actualPort || lock?.port));
     if (!p)
-        throw new Error(`[!] No active ${appName || "browser"} session. Run browser_go first.`);
+        throw new Error(`[!] No active ${appName || "browser"} session. Run browser_navigate first.`);
     let t = null;
     try {
         const targets = await withCDPTimeout(CDP.List({ host: "127.0.0.1", port: p }), 3000, "connectToTab CDP.List");

package/dist/cli/plugin.d.ts

@@ -1,4 +1,5 @@
 export declare function runPluginAdd(inputName: string, args?: string[]): Promise<void>;
+export declare function runPluginAddLocal(inputPath: string): Promise<void>;
 export declare function runPluginList(): Promise<void>;
 export declare function runPluginSearch(query?: string): Promise<void>;
 export declare function runPluginBrowse(): Promise<void>;

package/dist/cli/plugin.js

@@ -2,6 +2,7 @@ import * as p from "@clack/prompts";
 import pc from "picocolors";
 import boxen from "boxen";
 import ora from "ora";
+import fs from "node:fs";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { createRequire } from "node:module";
@@ -24,7 +25,7 @@ function runCommand(cmd, cmdArgs, cwd = process.cwd()) {
         const executable = isWin && !cmd.endsWith(".cmd") && !cmd.endsWith(".exe") ? `${cmd}.cmd` : cmd;
         const child = spawn(executable, cmdArgs, {
             cwd,
-            shell: false,
+            shell: isWin,
             stdio: ["ignore", "pipe", "pipe"],
         });
         let stdout = "";
@@ -47,8 +48,20 @@ function runNpmCommand(cmdArgs, cwd = process.cwd()) {
 // ---------------------------------------------------------------------------
 export async function runPluginAdd(inputName, args = []) {
     if (!inputName || inputName.startsWith("-")) {
-        console.log(pc.red("[ERROR] Please provide a package name to install."));
-        console.log(pc.dim("Usage: weavetab plugin add <packageName> [--official | --community] [--yes]"));
+        console.log(pc.red("[ERROR] Please provide a package name or local path to install."));
+        console.log(pc.dim("Usage: weavetab plugin add <packageName|./local-path> [--official | --community] [--yes]"));
+        return;
+    }
+    // Local path install: `weavetab plugin add ./my-plugin` (npm installs the directory).
+    if (inputName === "." ||
+        inputName.startsWith("./") ||
+        inputName.startsWith("../") ||
+        inputName.startsWith("file:") ||
+        inputName.startsWith("/") ||
+        inputName.startsWith("\\") ||
+        /^[a-zA-Z]:[\\/]/.test(inputName) ||
+        inputName.startsWith("~/")) {
+        await runPluginAddLocal(inputName);
         return;
     }
     const isForce = args.includes("--yes") || args.includes("-y") || args.includes("--force");
@@ -223,6 +236,49 @@ export async function runPluginAdd(inputName, args = []) {
     }
 }
 // ---------------------------------------------------------------------------
+// 1b. ADD FROM LOCAL PATH (`weavetab plugin add ./my-plugin`)
+// ---------------------------------------------------------------------------
+export async function runPluginAddLocal(inputPath) {
+    let dir = inputPath;
+    if (dir.startsWith("file:"))
+        dir = dir.slice("file:".length);
+    if (dir.startsWith("~/"))
+        dir = path.join(process.env.HOME || process.env.USERPROFILE || "", dir.slice(2));
+    const absDir = path.resolve(process.cwd(), dir);
+    if (!fs.existsSync(absDir) || !fs.statSync(absDir).isDirectory()) {
+        console.log(pc.red(`[ERROR] Local path not found: ${inputPath}`));
+        return;
+    }
+    const local = inspectInstalledPackage(absDir);
+    if (!local) {
+        console.log(pc.red(`[ERROR] No valid weavetab.json manifest in ${absDir}`));
+        console.log(pc.dim("Scaffold one with: npx @weavetab/sdk init <name>"));
+        return;
+    }
+    const spinner = ora(`Installing local plugin ${pc.cyan(local.packageName)} from ${pc.dim(absDir)} via npm...`).start();
+    const installResult = await runNpmCommand(["install", absDir]);
+    if (installResult.code !== 0) {
+        spinner.fail(pc.red(`Failed to install ${local.packageName}`));
+        if (installResult.stderr)
+            console.error(pc.dim(installResult.stderr));
+        return;
+    }
+    spinner.succeed(pc.green(`installed ${pc.bold(local.packageName)} (local path)`));
+    const targetDir = path.join(process.cwd(), "node_modules", local.packageName);
+    const installedInfo = fs.existsSync(targetDir) ? inspectInstalledPackage(targetDir) : local;
+    const manifest = (installedInfo?.manifest || local.manifest);
+    const tools = manifest.tools || [];
+    console.log();
+    console.log(boxen(`${pc.bold("Plugin Details:")}\n` +
+        `  ${pc.dim("Name:")}        ${manifest.name || local.packageName}\n` +
+        `  ${pc.dim("Version:")}     ${manifest.version || "1.0.0"}\n` +
+        `  ${pc.dim("Source:")}      ${absDir} (local path)\n` +
+        `  ${pc.dim("Description:")} ${manifest.description || "No description provided"}` +
+        (tools.length > 0 ? `\n\n${pc.bold(`Exposed Tools (${tools.length}):`)}` + tools.map((t) => `\n  • ${pc.cyan(t.name)}: ${pc.dim(t.description || "")}`).join("") : ""), { padding: 1, borderStyle: "round", borderColor: "green" }));
+    console.log();
+    console.log(pc.green("✔ Plugin is ready to use! Restart Weavetab MCP server to activate changes.\n"));
+}
+// ---------------------------------------------------------------------------
 // 2. LIST INSTALLED PLUGINS
 // ---------------------------------------------------------------------------
 export async function runPluginList() {
@@ -434,7 +490,7 @@ export async function runPluginCli(args) {
         console.log(`  weavetab plugin <command> [options]`);
         console.log();
         console.log(pc.bold("COMMANDS"));
-        console.log(`  ${pc.cyan("add <pkg>")}          Install any plugin by npm package name (e.g. @fy2ne/wt-youtube, my-plugin)`);
+        console.log(`  ${pc.cyan("add <pkg|path>")}     Install a plugin by npm name or local path (e.g. @fy2ne/wt-youtube, ./my-plugin)`);
         console.log(`  ${pc.cyan("browse")}             Interactive terminal explorer to browse & 1-click install`);
         console.log(`  ${pc.cyan("search [query]")}     Search plugins across official registry & npm`);
         console.log(`  ${pc.cyan("list")}               List all installed plugins and their registered tools`);

package/dist/config/loader.d.ts

@@ -1,6 +1,6 @@
 export type DevModeConfig = boolean;
 export type PolicyMode = "allow" | "deny" | "audit-only" | "read-only";
-export type Role = "admin" | "viewer" | "automation" | "system";
+export type Role = "admin" | "operator" | "viewer" | "automation" | "system";
 export type BrowserEngine = "chromium" | "firefox" | "webkit";
 export interface PolicyEntry {
     pattern: string;

package/dist/config/loader.js

@@ -153,7 +153,7 @@ export function validateConfigInternal(raw) {
     const d = DEFAULT_CONFIG;
     const VALID_MODES = ["session", "attach"];
     const VALID_ENGINES = ["chromium", "firefox", "webkit"];
-    const VALID_ROLES = ["admin", "viewer", "automation", "system"];
+    const VALID_ROLES = ["admin", "operator", "viewer", "automation", "system"];
     const mode = validateField("mode", raw.mode, isStr, d.mode, v => VALID_MODES.includes(v));
     // Path validation helpers
     function safePathField(field, value) {