cherchyk · cherchyk · May 13, 2026 · May 13, 2026 · May 13, 2026 · May 13, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -41,6 +41,17 @@ jobs:
 
         echo "✅ All versions synchronized at $MCP_VERSION"
 
+    - name: Build MCP Bundle
+      run: |
+        cd MCPBrowser
+        npm run build:mcpb
+
+    - name: Verify MCP Bundle
+      run: |
+        ls -lh MCPBrowser/dist/*.mcpb
+        # Verify it's a valid ZIP with manifest.json
+        unzip -l MCPBrowser/dist/*.mcpb | head -5
+
     - name: Verify VS Code Extension packages
       run: |
         npm install -g @vscode/vsce ovsx

diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml
@@ -99,6 +99,12 @@ jobs:
         cd VSCodeExtension
         ovsx publish mcpbrowser-${{ steps.version.outputs.version }}.vsix -p ${{ secrets.OVSX_PAT }}
 
+    - name: Build MCP Bundle
+      run: |
+        cd MCPBrowser
+        npm run build:mcpb
+        ls -lh dist/*.mcpb
+
     - name: Extract changelog for version
       id: changelog
       run: |
@@ -126,7 +132,8 @@ jobs:
         gh release create "v$VERSION" \
           --title "v$VERSION" \
           --notes-file release-notes.md \
-          VSCodeExtension/mcpbrowser-$VERSION.vsix
+          VSCodeExtension/mcpbrowser-$VERSION.vsix \
+          MCPBrowser/dist/mcpbrowser-$VERSION.mcpb
 
     - name: Deployment Summary
       run: |
@@ -136,5 +143,5 @@ jobs:
         echo "  ✅ MCP Registry (Visual Studio & other MCP clients)"
         echo "  ✅ VS Code Marketplace"
         echo "  ✅ Open VSX Registry"
-        echo "  ✅ GitHub Releases"
+        echo "  ✅ GitHub Releases (with .vsix + .mcpb bundle)"
 
diff --git a/MCPBrowser/README.md b/MCPBrowser/README.md
@@ -5,7 +5,7 @@
 [![Claude Desktop](https://img.shields.io/badge/Claude-Desktop-5865F2?logo=anthropic)](https://modelcontextprotocol.io/quickstart/user)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-> ⚠️ **Security Notice:** MCPBrowser extracts webpage content and provides it to your AI agent (e.g., GitHub Copilot, Claude, Kiro, Antigravity), which then sends it to the LLM provider it uses (e.g., Anthropic, OpenAI, GitHub) for processing. Make sure you trust both your agent and the LLM provider — especially when accessing pages with sensitive or private data.
+> ⚠️ **Security Notice:** MCPBrowser extracts webpage content and provides it to your AI agent (e.g., GitHub Copilot, Claude, Kiro, Antigravity), which then sends it to the LLM provider it uses (e.g., Anthropic, OpenAI, GitHub) for processing. Make sure you trust both your agent and the LLM provider — especially when accessing pages with sensitive or private data. MCPBrowser combines private data access, untrusted content exposure, and external communication (the MCP "[lethal trifecta](https://blog.modelcontextprotocol.io/posts/2026-03-16-tool-annotations/)") — all tool annotations accurately declare these risks so MCP clients can enforce appropriate safety controls. See [MCP_COMPLIANCE.md](docs/MCP_COMPLIANCE.md) for details.
 
 > 💡 **Why MCPBrowser over Puppeteer/Playwright MCP servers?** Puppeteer and Playwright are browser automation libraries — their MCP servers give agents raw, low-level browser commands. MCPBrowser uses Puppeteer under the hood and was built specifically for AI agents, adding an intelligence layer that handles the hard parts automatically.
 >
@@ -167,7 +167,7 @@ For VS Code, Kiro, Antigravity, or other editors — manual MCP setup. Add to yo
 
 ### `browser_fetch_webpage`
 
-Fetches web pages using your Chrome/Edge browser. Handles authentication, CAPTCHA, SSO, anti-bot protection, and JavaScript-heavy sites. Opens the URL in a browser tab (reuses existing tab for same domain) and waits for the page to fully load before returning content. **Automatically detects SPAs** (React, Vue, Angular) and waits for JavaScript to render content.
+Fetches web pages using your Chrome/Edge/Brave browser. Handles authentication, CAPTCHA, SSO, anti-bot protection, and JavaScript-heavy sites. Opens the URL in a browser tab (reuses existing tab for same domain) and waits for the page to fully load before returning content. **Automatically detects SPAs** (React, Vue, Angular) and waits for JavaScript to render content.
 
 **Parameters:**
 - `url` (string, required) - The URL to fetch
@@ -458,7 +458,7 @@ Environment variables for advanced setup:
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `CHROME_PATH` | Path to Chrome/Edge | Auto-detect |
+| `CHROME_PATH` | Path to Chrome/Edge/Brave | Auto-detect |
 | `CHROME_USER_DATA_DIR` | Browser profile directory | `%LOCALAPPDATA%/ChromeAuthProfile` |
 | `CHROME_REMOTE_DEBUG_PORT` | DevTools port | `9222` |
 

diff --git a/MCPBrowser/docs/MCP_COMPLIANCE.md b/MCPBrowser/docs/MCP_COMPLIANCE.md
@@ -21,11 +21,11 @@ Per the MCP spec, each tool definition must include:
 | `title` | ⚪ Optional | ✅ Implemented | Human-readable display name (moved from annotations to top-level) |
 | `outputSchema` | ⚪ Optional | ✅ Implemented | JSON Schema for structured output validation |
 | `icons` | ⚪ Optional | ❌ Not used | Array of icons for UI display |
-| `annotations` | ⚪ Optional | ❌ Removed | Properties describing tool behavior |
+| `annotations` | ⚪ Optional | ✅ Implemented | Risk hints: readOnlyHint, destructiveHint, idempotentHint, openWorldHint |
 
 ## Verified Tool Definitions
 
-All 5 tools conform to the specification:
+All 12 tools conform to the specification:
 
 ### 1. browser_fetch_webpage ✅
 
@@ -262,37 +262,52 @@ Following MCP security recommendations:
 - ⚠️ **Timeouts**: Clients should implement tool call timeouts
 - ⚠️ **Audit logging**: Clients should log tool usage
 
-## Changes Made for Compliance
+## Tool Annotations ✅
 
-### Before (Non-Compliant)
-```javascript
-{
-  name: "browser_close_tab",
-  description: "...",
-  inputSchema: { ... },
-  outputSchema: { ... },
-  annotations: {
-    title: "Close Tab"  // ❌ Title in annotations
-  }
-}
-```
+All 12 tools declare MCP risk annotations per the [Tool Annotations spec](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#annotations):
 
-### After (Compliant)
-```javascript
-{
-  name: "browser_close_tab",
-  title: "Close Tab",  // ✅ Title at top level
-  description: "...",
-  inputSchema: { ... },
-  outputSchema: { ... }
-}
-```
+| Tool | readOnly | destructive | idempotent | openWorld |
+|------|----------|-------------|------------|-----------|
+| `browser_fetch_webpage` | ✅ true | false | ✅ true | ✅ true |
+| `browser_get_current_html` | ✅ true | false | ✅ true | false |
+| `browser_take_screenshot` | ✅ true | false | ✅ true | false |
+| `browser_detect_forms` | ✅ true | false | ✅ true | false |
+| `browser_plugin_info` | ✅ true | false | ✅ true | false |
+| `browser_scroll_page` | false | false | false | false |
+| `browser_click_element` | false | false | false | ✅ true |
+| `browser_type_text` | false | false | false | false |
+| `browser_navigate_history` | false | false | false | ✅ true |
+| `browser_plugin_action` | false | false | false | ✅ true |
+| `browser_execute_javascript` | false | ⚠️ true | false | ✅ true |
+| `browser_close_tab` | false | ⚠️ true | ✅ true | false |
+
+Clients can use these hints to auto-approve read-only tools and prompt for confirmation on destructive ones.
+
+## Security Model — Lethal Trifecta ⚠️
+
+MCPBrowser inherently combines all three legs of the "lethal trifecta" defined in the [MCP Tool Annotations blog post](https://blog.modelcontextprotocol.io/posts/2026-03-16-tool-annotations/):
+
+| Leg | Present | How |
+|-----|---------|-----|
+| **Private data access** | ✅ | Connects to user's existing browser with cookies, SSO sessions, and saved credentials |
+| **Untrusted content exposure** | ✅ | Loads and processes arbitrary web pages |
+| **External communication** | ✅ | Can navigate to any URL, execute JavaScript in page context |
+
+This is **by design** — browser automation requires all three capabilities. The following mitigations are in place:
+
+- **Tool annotations** accurately reflect risk levels (see table above)
+- **Destructive tools** (`execute_javascript`, `close_tab`) are annotated with `destructiveHint: true`
+- **Open-world tools** that reach external resources are annotated with `openWorldHint: true`
+- **Single-user model** — connects to the user's own browser (no shared/multi-tenant mode)
+- **EULA acceptance** required before first use
+- **Sequential request queue** — one operation at a time, no parallel mutations
+- **HTML sanitization** — script tags and event handlers stripped from extracted content
 
 ## Testing
 
-All 5 tools verified with:
-- ✅ 158 unit tests passing
-- ✅ 5 MCP compliance tests passing
+All 12 tools verified with:
+- ✅ Unit tests passing
+- ✅ MCP compliance tests passing
 - ✅ Response format validation
 - ✅ Structured content validation
 
@@ -302,11 +317,10 @@ All 5 tools verified with:
 
 All tool definitions:
 - Follow required field structure
-- Implement optional fields correctly
+- Implement optional fields correctly (title, outputSchema, annotations)
 - Use valid JSON Schema format
 - Document inputs and outputs
 - Handle errors properly
 - Follow naming conventions
 - Support structured output validation
-
-No violations or warnings.
+- Declare risk annotations for client safety UX
diff --git a/MCPBrowser/package-lock.json b/MCPBrowser/package-lock.json
diff --git a/MCPBrowser/package.json b/MCPBrowser/package.json
@@ -1,9 +1,9 @@
 {
   "name": "mcpbrowser",
-  "version": "0.3.52",
+  "version": "0.3.53",
   "mcpName": "io.github.cherchyk/mcpbrowser",
   "type": "module",
-  "description": "MCP browser server — load and interact with any web page using a real Chrome/Edge/Brave browser with full JavaScript execution. Handles login flows, authentication, SSO, CAPTCHAs, and anti-bot protection. Use whenever a real browser is needed to load a page, especially when JavaScript rendering or user login is required.",
+  "description": "MCP browser server — loads and interacts with web pages using the user's Chromium-based browser with full JavaScript execution. Handles authentication, SSO, and anti-bot protection automatically via the user's existing browser session.",
   "main": "src/mcp-browser.js",
   "bin": {
     "mcpbrowser": "src/mcp-browser.js"
@@ -13,7 +13,8 @@
     "test": "node tests/run-all.js",
     "test:unit": "node tests/run-unit.js",
     "test:cli": "node tests/cli.test.js",
-    "test:descriptions": "node tests/tool-selection/run-tool-selection-tests.js"
+    "test:descriptions": "node tests/tool-selection/run-tool-selection-tests.js",
+    "build:mcpb": "node scripts/build-mcpb.js"
   },
   "keywords": [
     "mcp",