bridge-mcp 1.0.0__py3-none-any.whl

bridge_mcp-1.0.0.dist-info/METADATA

@@ -0,0 +1,521 @@
+Metadata-Version: 2.4
+Name: bridge-mcp
+Version: 1.0.0
+Summary: Universal PC Control MCP - Give any AI full control over Windows
+Project-URL: Homepage, https://github.com/BarhamAgha1/Bridge-MCP
+Author: Barham Agha
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: fuzzywuzzy>=0.18.0
+Requires-Dist: keyboard>=0.13.5
+Requires-Dist: mouse>=0.7.1
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: pyautogui>=0.9.54
+Requires-Dist: pyperclip>=1.8.2
+Requires-Dist: python-levenshtein>=0.21.0
+Requires-Dist: uiautomation>=2.0.0
+Description-Content-Type: text/markdown
+
+# 🌉 Bridge MCP
+
+### Universal PC Control for Any AI
+
+[![FastMCP](https://img.shields.io/badge/FastMCP-2.0-blue?style=for-the-badge&logo=python)](https://fastmcp.cloud)
+[![License](https://img.shields.io/badge/License-MIT-green?style=for-the-badge)](LICENSE)
+[![Python](https://img.shields.io/badge/Python-3.10+-yellow?style=for-the-badge&logo=python)](https://python.org)
+[![Windows](https://img.shields.io/badge/Platform-Windows-0078D6?style=for-the-badge&logo=windows)](https://www.microsoft.com/windows)
+
+**Give any AI complete control over your Windows PC**
+
+[Features](#-features) • [Quick Start](#-quick-start) • [Configuration](#-configuration) • [Tools](#-available-tools) • [Troubleshooting](#-troubleshooting) • [Contributing](#-contributing)
+
+---
+
+## 🔄 How Persistence Works
+
+Bridge MCP v2.0 stores agent registrations in a **persistent JSON file**:
+
+- **Windows:** `%APPDATA%\bridge-mcp\agents.json`
+- **Linux/Mac:** `~/.config/bridge-mcp/agents.json`
+
+This means:
+- ✅ Register once, works forever
+- ✅ Survives Claude Code session restarts
+- ✅ Survives computer reboots
+- ✅ Works across all AI clients
+
+### First-Time Setup
+
+1. **Start the local agent:**
+```bash
+   cd Bridge-MCP
+   python local_agent.py
+```
+
+2. **The agent auto-registers itself** - no manual registration needed!
+
+3. **Verify in any Claude session:**
+```
+   Use list_agents() to see registered agents
+```
+
+### Troubleshooting
+
+If you see "No agents connected":
+
+1. **Check if local_agent.py is running** - it must be running in a terminal
+2. **Check health:** Use `check_agent_health()` tool
+3. **Manual register:** Use `register_agent("local", "http://127.0.0.1:8006", "My PC")`
+
+### Running Local Agent as Background Service
+
+For always-on access, install local_agent as a Windows service:
+```bash
+python install_service.py install
+python install_service.py start
+```
+
+To remove:
+```bash
+python install_service.py stop
+python install_service.py remove
+```
+
+---
+
+## 🎯 What is Bridge MCP?
+
+Bridge MCP is a **Model Context Protocol (MCP)** server that gives **any AI** full control over a Windows PC. Whether you're using Claude, ChatGPT, Cursor, Gemini, or any other MCP-compatible AI, Bridge MCP lets you:
+
+* 🖥️ **Control Applications** - Launch, switch, resize, close any app
+* 🖱️ **Automate Input** - Mouse clicks, keyboard typing, hotkeys, scrolling
+* 📸 **See the Screen** - Screenshots, UI element detection, desktop state
+* 🌐 **Browse the Web** - Full Chrome automation and control
+* ⚡ **Run Commands** - PowerShell, CMD, file operations
+* 📋 **Manage Clipboard** - Copy, paste, clear
+
+> **Think of it as giving your AI eyes and hands to control your computer!**
+
+---
+
+## ✨ Features
+
+| Category | Tools | Description |
+| --- | --- | --- |
+| 🚀 **App Control** | 8 tools | Launch, switch, close, resize, minimize, maximize applications |
+| 🖱️ **Mouse & Keyboard** | 10 tools | Click, type, hotkeys, scroll, drag, move cursor |
+| 📸 **Screen Capture** | 7 tools | Screenshots, desktop state, find UI elements |
+| ⚡ **System** | 8 tools | PowerShell, CMD, file read/write, system info |
+| 🌐 **Browser** | 15 tools | Chrome control, tabs, navigation, web scraping |
+| 📋 **Clipboard** | 3 tools | Copy, paste, clear clipboard |
+| 🔧 **Utilities** | 5+ tools | Wait, dialogs, action sequences |
+
+**Total: 40+ powerful tools for complete PC automation!**
+
+---
+
+## 🏗️ Architecture
+
+Bridge MCP uses a **Relay Architecture** to work across platforms:
+```
+┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
+│    Any AI       │         │  Cloud Relay    │         │  Your Windows   │
+│  (Claude, etc.) │◄───────►│  (bridge_mcp)   │◄───────►│  PC (Agent)     │
+└─────────────────┘         └─────────────────┘         └─────────────────┘
+```
+
+* **bridge_mcp.py** - MCP server (runs locally or on FastMCP Cloud)
+* **local_agent.py** - HTTP server on your PC that executes commands (port 8006)
+
+---
+
+## 🔒 Enterprise-Grade Security
+
+Bridge MCP 2.0 includes:
+- **Auth Tokens:** Uses secure Bearer tokens to prevent unauthorized access.
+- **Auto-Config:** Tokens are auto-generated and saved to `agents.json`.
+
+## 🌐 Next-Gen Browser Automation
+
+Powered by **Playwright**, Bridge MCP can now:
+- **Click & Type:** Interact with any website element.
+- **Semantic Understanding:** Read page content programmatically.
+- **Headless Mode:** Run automations invisible or visible.
+
+## 🧠 Semantic Computer Vision
+
+Bridge MCP "sees" your apps:
+- **UI Tree:** It can read the accessibility tree of Windows apps.
+- **Precision:** Knows exactly where buttons are (no more guessing pixels).
+
+## 🛡️ Safety Sentinel (Human-in-the-Loop)
+
+Bridge MCP now puts YOU in control:
+- **Command Interception:** Dangerous commands (writing files, running shell scripts) are BLOCKED by default.
+- **Approval Overlay:** Approval requests appear directly in the AI Activity Overlay with three options:
+  - ✓ **APPROVE** - Execute this one command
+  - ✗ **DENY** - Block this command
+  - ✓ **ALWAYS APPROVE** - Disable Safe Mode and approve all future commands
+- **Dashboard Control:** View all pending requests at `http://localhost:8006`
+- **Safe Mode Toggle:** Switch Safe Mode on/off anytime from the web dashboard
+- **Peace of Mind:** You can leave the agent running without fear of it deleting your files.
+
+## 👁️ Terminator Vision (Live Observability)
+
+See what the AI sees, in real-time:
+- **Live Stream:** The dashboard features a low-latency 1080p MJPEG stream of your desktop.
+- **Semantic Overlay:** Green bounding boxes highlight every button, link, and window the AI detects.
+- **Debug Instantly:** Visual confirmation that the AI has found the correct "Submit" button.
+
+## 📚 Full MCP Specification Support
+
+Bridge MCP now implements the complete Model Context Protocol specification:
+
+### Resources API
+Expose desktop data as addressable resources:
+- `desktop://screenshot/latest` - Current screenshot
+- `desktop://windows` - Open windows list
+- `desktop://logs` - Agent command logs
+- `file:///{path}` - Read any desktop file
+- `desktop://session/context` - Recent session history
+
+### Prompts API
+Pre-built workflow templates for one-click automation:
+- `automate_desktop_task` - Step-by-step task automation
+- `debug_error` - Interactive error debugging
+- `web_automation` - Playwright web workflows
+
+### Session Memory
+Never lose context:
+- Stores last 100 commands across restarts
+- Provides AI with recent session history
+- Enables "continue where I left off" workflows
+
+---
+
+## 🚀 Quick Start
+
+### Step 1: Clone the Repository
+```bash
+git clone https://github.com/BarhamAgha1/Bridge-MCP.git
+cd Bridge-MCP
+```
+
+### Step 2: Install Dependencies
+```bash
+pip install -r requirements-local.txt
+```
+**Note:** Playwright browsers (~100MB) auto-install on first use - no manual setup needed!
+
+### Step 3: Start the Local Agent
+```bash
+python local_agent.py
+```
+
+Keep this terminal open! The agent will display:
+```
+Bridge MCP Local Agent running on http://127.0.0.1:8006
+```
+
+### Step 4: Configure Your AI Client
+
+See [Configuration](#-configuration) below for Claude Desktop, Cursor, or VS Code setup.
+
+### Step 5: Register Your Agent
+
+In your AI conversation, register the local agent:
+```
+Use register_agent with:
+- agent_id: "my-pc"
+- callback_url: "http://127.0.0.1:8006"
+- agent_name: "My Windows PC"
+```
+
+### Step 6: Start Controlling!
+
+Now use any tool like `screenshot()`, `click(100, 200)`, `type_text("Hello")`, `app_launch("notepad")`, etc.
+
+---
+
+## 🔧 Configuration
+
+### Claude Desktop
+
+1. Open the config file at `%APPDATA%\Claude\claude_desktop_config.json`
+
+2. Add Bridge MCP:
+```json
+{
+  "mcpServers": {
+    "bridge-mcp": {
+      "command": "python",
+      "args": ["C:\\Users\\YourName\\Path\\To\\Bridge-MCP\\bridge_mcp.py"]
+    }
+  }
+}
+```
+
+⚠️ **Important:** Replace the path with the **actual location** where you cloned the repository!
+
+**Example paths:**
+- `C:\\Users\\PC\\Desktop\\Bridge-MCP\\bridge_mcp.py`
+- `D:\\Projects\\Bridge-MCP\\bridge_mcp.py`
+
+3. **Restart Claude Desktop completely** (close and reopen)
+
+### Cursor
+
+Add to your MCP settings in Cursor preferences with the same configuration format.
+
+### VS Code + Claude Code
+
+Create `.vscode/mcp.json` in your project:
+```json
+{
+  "mcpServers": {
+    "bridge-mcp": {
+      "command": "python",
+      "args": ["C:\\Users\\YourName\\Path\\To\\Bridge-MCP\\bridge_mcp.py"]
+    }
+  }
+}
+```
+
+### Remote Access (Optional)
+
+To control your PC from anywhere, expose the local agent with ngrok:
+```bash
+ngrok http 8006
+```
+
+Then use the ngrok URL (e.g., `https://xxxx.ngrok.io`) as your callback_url when registering.
+
+---
+
+## 🛠️ Available Tools
+
+<details>
+<summary><b>🚀 App Control Tools</b></summary>
+
+| Tool | Description | Example |
+| --- | --- | --- |
+| `app_launch` | Launch an application | `app_launch("notepad")` |
+| `app_switch` | Switch to open app | `app_switch("Chrome")` |
+| `app_close` | Close an application | `app_close("notepad")` |
+| `app_list` | List all open apps | `app_list()` |
+
+</details>
+
+<details>
+<summary><b>🖱️ Input Tools (Mouse & Keyboard)</b></summary>
+
+| Tool | Description | Example |
+| --- | --- | --- |
+| `click` | Click at coordinates | `click(500, 300)` |
+| `double_click` | Double-click | `double_click(500, 300)` |
+| `right_click` | Right-click | `right_click(500, 300)` |
+| `type_text` | Type text | `type_text("Hello World!")` |
+| `press_key` | Press a key | `press_key("enter")` |
+| `hotkey` | Keyboard shortcut | `hotkey("ctrl,c")` |
+| `scroll` | Scroll | `scroll("down", 3)` |
+| `drag` | Drag and drop | `drag(100, 100, 500, 500)` |
+| `move_mouse` | Move cursor | `move_mouse(500, 300)` |
+
+</details>
+
+<details>
+<summary><b>📸 Screen Tools</b></summary>
+
+| Tool | Description | Example |
+| --- | --- | --- |
+| `screenshot` | Take screenshot | `screenshot()` |
+| `get_desktop_state` | Get full desktop state | `get_desktop_state()` |
+| `get_screen_size` | Get screen dimensions | `get_screen_size()` |
+| `get_mouse_position` | Get cursor position | `get_mouse_position()` |
+
+</details>
+
+<details>
+<summary><b>⚡ System Tools</b></summary>
+
+| Tool | Description | Example |
+| --- | --- | --- |
+| `run_powershell` | Run PowerShell | `run_powershell("Get-Process")` |
+| `run_cmd` | Run CMD command | `run_cmd("dir")` |
+| `file_read` | Read file | `file_read("C:/test.txt")` |
+| `file_write` | Write file | `file_write("C:/test.txt", "Hello")` |
+| `file_list` | List directory | `file_list("C:/Users")` |
+
+</details>
+
+<details>
+<summary><b>🌐 Browser Tools (Chrome)</b></summary>
+
+| Tool | Description | Example |
+| --- | --- | --- |
+| `chrome_open` | Open Chrome | `chrome_open("https://google.com")` |
+| `chrome_navigate` | Go to URL | `chrome_navigate("https://example.com")` |
+
+</details>
+
+<details>
+<summary><b>🌐 Browser Tools (Playwright - Advanced)</b></summary>
+
+| Tool | Description | Example |
+| --- | --- | --- |
+| `browser_navigate` | Go to URL | `browser_navigate("google.com")` |
+| `browser_click` | Click element (CSS) | `browser_click("#submit-btn")` |
+| `browser_type` | Type in element | `browser_type("#search", "hello")` |
+| `browser_press` | Press key | `browser_press("Enter")` |
+| `browser_content` | Get page text | `browser_content()` |
+| `browser_screenshot`| Browser screenshot | `browser_screenshot()` |
+
+</details>
+
+<details>
+<summary><b>📋 Clipboard Tools</b></summary>
+
+| Tool | Description | Example |
+| --- | --- | --- |
+| `clipboard_copy` | Copy to clipboard | `clipboard_copy("Hello")` |
+| `clipboard_paste` | Get clipboard | `clipboard_paste()` |
+
+</details>
+
+---
+
+## 💡 Usage Examples
+
+### Example 1: Open Notepad and Write Text
+```
+User: Open notepad and write "Hello from AI!"
+
+AI uses:
+1. app_launch("notepad")
+2. wait(1)
+3. type_text("Hello from AI!")
+```
+
+### Example 2: Take a Screenshot
+```
+User: What's on my screen right now?
+
+AI uses:
+1. screenshot()
+2. [AI analyzes the image and describes what it sees]
+```
+
+### Example 3: Search on Google
+```
+User: Search for "Bridge MCP" on Google
+
+AI uses:
+1. chrome_open("https://google.com")
+2. type_text("Bridge MCP")
+3. press_key("enter")
+```
+
+---
+
+## 🔧 Troubleshooting
+
+### Claude Desktop shows "Server disconnected"
+
+1. **Check the path** - Make sure the path in your config points to the actual `bridge_mcp.py` file. The path must be absolute and use double backslashes (`\\`) in JSON.
+
+2. **Test manually** - Open Command Prompt and run:
+```cmd
+   cd "C:\path\to\Bridge-MCP"
+   python bridge_mcp.py
+```
+   It should stay running (not exit immediately). Press Ctrl+C to stop.
+
+3. **Install dependencies**:
+```cmd
+   pip install fastmcp httpx
+```
+
+4. **Restart Claude Desktop** - Fully close and reopen after any config changes.
+
+### Local agent not receiving commands
+
+1. Make sure `local_agent.py` is running in a terminal (keep it open!)
+2. Verify the callback URL is correct when registering the agent
+3. For local use: `http://127.0.0.1:8006`
+4. For remote access: Use ngrok (`ngrok http 8006`) and use the ngrok URL
+
+### "No agents connected" error
+
+You need to register your local agent first:
+```
+register_agent("my-pc", "http://127.0.0.1:8006", "My PC")
+```
+
+### Unicode/Emoji errors on Windows
+
+If `local_agent.py` crashes with Unicode errors, the terminal may not support emojis. This has been fixed in the latest version.
+
+---
+
+## ☁️ FastMCP Cloud Deployment
+
+Bridge MCP can be deployed on [FastMCP Cloud](https://fastmcp.cloud) for easy access:
+
+1. Fork this repository
+2. Go to [fastmcp.cloud](https://fastmcp.cloud)
+3. Sign in with GitHub
+4. Create project from your forked repo
+5. Set entrypoint: `bridge_mcp.py`
+6. Deploy!
+
+Your MCP will be available at: `https://your-project.fastmcp.app/mcp`
+
+---
+
+## 🤝 Contributing
+
+Contributions are welcome! Here's how you can help:
+
+1. **Fork** the repository
+2. **Create** a feature branch (`git checkout -b feature/amazing-feature`)
+3. **Commit** your changes (`git commit -m 'Add amazing feature'`)
+4. **Push** to the branch (`git push origin feature/amazing-feature`)
+5. **Open** a Pull Request
+
+### Ideas for Contributions
+
+* Add more browser support (Firefox, Edge)
+* Add Linux support
+* Add macOS support
+* Add more automation tools
+* Improve UI element detection
+* Add OCR capabilities
+
+---
+
+## 📜 License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+---
+
+## 🙏 Acknowledgments
+
+* [FastMCP](https://fastmcp.cloud) - The amazing MCP framework
+* [Anthropic](https://anthropic.com) - For creating the MCP protocol
+
+---
+
+## 👤 Author
+
+**Barham Agha**
+
+* GitHub: [@BarhamAgha1](https://github.com/BarhamAgha1)
+
+---
+
+**⭐ If you find this project useful, please give it a star! ⭐**
+
+Made with ❤️ for the AI community

bridge_mcp-1.0.0.dist-info/RECORD

@@ -0,0 +1,5 @@
+bridge_mcp.py,sha256=pin8PtYpxpzrXZv3HviBm6w6LzGs3optHLGE2-7jSR8,21048
+bridge_mcp-1.0.0.dist-info/METADATA,sha256=HhiUcOxPQfps7BafEqcEw_B81s1GFbA4ZEaARj2teZI,15675
+bridge_mcp-1.0.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+bridge_mcp-1.0.0.dist-info/licenses/LICENSE,sha256=_MU_SJopMfznjUYqn3fqBbNAdah3X0H81b4Hk1LSybA,1089
+bridge_mcp-1.0.0.dist-info/RECORD,,

bridge_mcp-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

bridge_mcp-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Barham Agha
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bridge_mcp.py

@@ -0,0 +1,595 @@
+"""
+Bridge MCP - Cloud Relay with Persistent Storage
+=================================================
+This MCP server maintains agent registrations across sessions.
+
+Key Features:
+- Persistent agent storage (survives restarts)
+- Auto-discovery of local agent
+- Works across all Claude Code/Desktop sessions
+"""
+
+from fastmcp import FastMCP
+import asyncio
+import json
+import os
+from typing import Optional, Dict, Any
+import httpx
+
+# Import our persistent storage
+try:
+    from config import agent_storage, config
+except ImportError:
+    # Fallback for when running standalone
+    import sys
+    from pathlib import Path
+    sys.path.insert(0, str(Path(__file__).parent))
+    from config import agent_storage, config
+
+mcp = FastMCP("Bridge MCP")
+
+# ============================================
+# AUTO-DISCOVERY ON STARTUP
+# ============================================
+
+async def auto_discover_local_agent():
+    """
+    Automatically discover and register local agent if running.
+    Called on server startup.
+    """
+    local_url = f"http://127.0.0.1:{config.get('local_agent_port', 8006)}"
+    
+    try:
+        async with httpx.AsyncClient(timeout=2.0) as client:
+            response = await client.get(f"{local_url}/health")
+            if response.status_code == 200:
+                # Local agent is running! Auto-register if not already
+                existing = agent_storage.get("local")
+                if not existing or existing.get("callback_url") != local_url:
+                    agent_storage.register("local", local_url, "Local PC (Auto-discovered)")
+                agent_storage.update_status("local", "connected")
+                return True
+    except:
+        pass
+    return False
+
+# Run auto-discovery on import (when MCP starts)
+try:
+    asyncio.get_event_loop().run_until_complete(auto_discover_local_agent())
+except:
+    pass  # May fail if no event loop yet, that's OK
+
+# ============================================
+# RESOURCES API (Desktop Data)
+# ============================================
+
+@mcp.resource("desktop://screenshot/latest")
+async def get_latest_screenshot() -> str:
+    """Get the most recent screenshot as base64 data."""
+    result = await relay_command(None, "screenshot", {})
+    if "image" in result:
+        return f"data:image/png;base64,{result['image']}"
+    return "Screenshot not available"
+
+@mcp.resource("desktop://windows")
+async def get_windows_list() -> str:
+    """Get list of all open windows."""
+    result = await relay_command(None, "get_desktop_state", {})
+    if "windows" in result:
+        import json
+        return json.dumps(result["windows"], indent=2)
+    return "No windows data available"
+
+@mcp.resource("desktop://logs")
+async def get_agent_logs() -> str:
+    """Get recent agent command logs."""
+    agents = agent_storage.get_all()
+    if not agents:
+        return "No agents connected"
+    
+    agent_id = list(agents.keys())[0]
+    agent = agents[agent_id]
+    callback_url = agent["callback_url"]
+    
+    try:
+        async with httpx.AsyncClient(timeout=5.0) as client:
+            response = await client.get(f"{callback_url}/logs")
+            return response.text
+    except:
+        return "Logs unavailable"
+
+@mcp.resource("file:///{path}")
+async def get_file_content(path: str) -> str:
+    """Read content of a file from the desktop."""
+    result = await relay_command(None, "file_read", {"path": path})
+    if "content" in result:
+        return result["content"]
+    return f"Error reading file: {result.get('error', 'Unknown error')}"
+
+@mcp.resource("desktop://session/context")
+async def get_session_context() -> str:
+    """Get recent session history and context."""
+    agents = agent_storage.get_all()
+    if not agents:
+        return "No agents connected"
+    
+    agent_id = list(agents.keys())[0]
+    agent = agents[agent_id]
+    callback_url = agent["callback_url"]
+    
+    try:
+        async with httpx.AsyncClient(timeout=5.0) as client:
+            response = await client.get(f"{callback_url}/session/context")
+            data = response.json()
+            return data.get("summary", "No session context available")
+    except:
+        return "Session context unavailable"
+
+# ============================================
+# PROMPTS API (Workflow Templates)
+# ============================================
+
+@mcp.prompt()
+async def automate_desktop_task(task_description: str = "") -> str:
+    """Help user automate a desktop task step-by-step."""
+    return f"""You are controlling a Windows PC through Bridge MCP.
+
+Task: {task_description or "User will describe the task"}
+
+Available capabilities:
+- screenshot() - See the screen
+- click(x, y) - Click at coordinates
+- type_text(text) - Type text
+- browser_navigate(url) - Open URLs with Playwright
+- browser_click(selector) - Click web elements
+- get_desktop_state() - See open windows
+- run_powershell(cmd) - Execute commands (requires approval)
+
+Instructions:
+1. Take a screenshot first to see the current state
+2. Break the task into clear steps
+3. Execute each step and verify success
+4. If uncertain, ask the user for clarification
+
+Begin by taking a screenshot and analyzing what needs to be done."""
+
+@mcp.prompt()
+async def debug_error(error_message: str = "") -> str:
+    """Help debug an error message or problem."""
+    return f"""You are a debugging assistant with access to a Windows PC.
+
+Error/Problem: {error_message or "User will describe the error"}
+
+Available tools:
+- screenshot() - See the current screen
+- get_desktop_state() - List open applications
+- file_read(path) - Read log files
+- run_powershell(cmd) - Run diagnostic commands
+
+Debugging approach:
+1. Gather information about the error
+2. Check relevant logs or files
+3. Identify the root cause
+4.  Suggest or implement a fix
+5. Verify the fix worked
+
+Start by taking a screenshot to see the current state."""
+
+@mcp.prompt()
+async def web_automation(task: str = "", url: str = ""):
+    """Automate a web task using Playwright."""
+    return f"""You are automating a web browser task.
+
+URL: {url or "User will provide"}
+Task: {task or "User will describe"}
+
+Playwright tools available:
+- browser_navigate(url) - Go to a page
+- browser_click(selector) - Click elements (use CSS selectors)
+- browser_type(selector, text) - Fill forms
+- browser_press(key) - Press keys like 'Enter'
+- browser_content() - Read page text
+- browser_screenshot() - Capture current page
+
+Workflow:
+1. Navigate to {url or 'the target URL'}
+2. Wait for page load (1-2 seconds)
+3. Find and interact with elements using CSS selectors
+4. Verify success with screenshots or content checks
+
+CSS selector tips:
+- #id - for IDs
+- .class - for classes
+- button[type="submit"] - for specific attributes
+- Use browser dev tools to find selectors
+
+Begin by navigating to the URL."""
+
+# ============================================
+# AGENT REGISTRATION (PERSISTENT)
+# ============================================
+
+@mcp.tool
+def register_agent(agent_id: str, callback_url: str, agent_name: str = "My PC") -> dict:
+    """
+    Register a local agent that will execute commands.
+    This registration is PERSISTENT and survives server restarts.
+    
+    Args:
+        agent_id: Unique identifier for the agent (e.g., "my-pc", "work-laptop")
+        callback_url: URL where the local agent is listening (e.g., http://127.0.0.1:8006)
+        agent_name: Friendly name for the agent
+    
+    Returns:
+        Registration confirmation
+    """
+    return agent_storage.register(agent_id, callback_url, agent_name)
+
+@mcp.tool
+def unregister_agent(agent_id: str) -> dict:
+    """
+    Remove a registered agent.
+    
+    Args:
+        agent_id: ID of the agent to remove
+    
+    Returns:
+        Removal confirmation
+    """
+    return agent_storage.unregister(agent_id)
+
+@mcp.tool
+def list_agents() -> dict:
+    """
+    List all registered agents (persistent across sessions).
+    
+    Returns:
+        Dictionary of all registered agents with their status
+    """
+    agents = agent_storage.get_all()
+    return {
+        "agents": [{"id": aid, **info} for aid, info in agents.items()],
+        "count": len(agents),
+        "config_location": str(agent_storage.agents_file)
+    }
+
+@mcp.tool
+async def check_agent_health(agent_id: str = None) -> dict:
+    """
+    Check if an agent is online and responding.
+    
+    Args:
+        agent_id: Optional. Agent to check (checks all if not specified)
+    
+    Returns:
+        Health status of agent(s)
+    """
+    results = {}
+    agents = agent_storage.get_all()
+    
+    if agent_id:
+        if agent_id not in agents:
+            return {"error": f"Agent {agent_id} not registered"}
+        agents = {agent_id: agents[agent_id]}
+    
+    for aid, info in agents.items():
+        try:
+            async with httpx.AsyncClient(timeout=5.0) as client:
+                response = await client.get(f"{info['callback_url']}/health")
+                if response.status_code == 200:
+                    agent_storage.update_status(aid, "connected")
+                    results[aid] = {"status": "healthy", "url": info['callback_url']}
+                else:
+                    agent_storage.update_status(aid, "error")
+                    results[aid] = {"status": "error", "code": response.status_code}
+        except httpx.ConnectError:
+            agent_storage.update_status(aid, "disconnected")
+            results[aid] = {"status": "disconnected", "url": info['callback_url']}
+        except Exception as e:
+            results[aid] = {"status": "error", "error": str(e)}
+    
+    return results
+
+@mcp.tool
+def set_default_agent(agent_id: str) -> dict:
+    """
+    Set an agent as the default for all commands.
+    
+    Args:
+        agent_id: Agent to set as default
+    
+    Returns:
+        Confirmation
+    """
+    return agent_storage.set_default(agent_id)
+
+# ============================================
+# COMMAND RELAY (Uses Persistent Storage)
+# ============================================
+
+async def relay_command(agent_id: Optional[str], command: str, params: dict) -> dict:
+    """
+    Relay a command to a local agent.
+    Uses persistent storage to find agents.
+    """
+    agents = agent_storage.get_all()
+    
+    # If no agent specified, try to find one
+    if not agent_id:
+        # First, try auto-discovery
+        if config.get("auto_connect_localhost", True):
+            if await auto_discover_local_agent():
+                agent_id = "local"
+        
+        # Use first available agent
+        if not agent_id and agents:
+            agent_id = list(agents.keys())[0]
+    
+    if not agent_id or agent_id not in agents:
+        return {
+            "error": "No agents available",
+            "hint": "Start local_agent.py on your Windows PC. It will auto-register.",
+            "registered_agents": list(agents.keys()) if agents else [],
+            "config_file": str(agent_storage.agents_file)
+        }
+    
+    agent = agents[agent_id]
+    callback_url = agent["callback_url"]
+    token = agent.get("token")
+    
+    headers = {}
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    
+    try:
+        async with httpx.AsyncClient(timeout=config.get("connection_timeout", 30)) as client:
+            response = await client.post(
+                f"{callback_url}/execute",
+                json={"command": command, "params": params},
+                headers=headers
+            )
+            agent_storage.update_status(agent_id, "connected")
+            return response.json()
+    except httpx.ConnectError:
+        agent_storage.update_status(agent_id, "disconnected")
+        return {
+            "error": f"Cannot connect to agent '{agent_id}' at {callback_url}",
+            "hint": "Make sure local_agent.py is running on your PC"
+        }
+    except Exception as e:
+        return {"error": str(e)}
+
+# ============================================
+# PC CONTROL TOOLS (Same as before, but using persistent storage)
+# ============================================
+
+@mcp.tool
+async def screenshot(agent_id: str = None) -> dict:
+    """Take a screenshot of the PC desktop."""
+    return await relay_command(agent_id, "screenshot", {})
+
+@mcp.tool
+async def click(x: int, y: int, button: str = "left", agent_id: str = None) -> dict:
+    """Click at screen coordinates."""
+    return await relay_command(agent_id, "click", {"x": x, "y": y, "button": button})
+
+@mcp.tool
+async def double_click(x: int, y: int, agent_id: str = None) -> dict:
+    """Double-click at screen coordinates."""
+    return await relay_command(agent_id, "double_click", {"x": x, "y": y})
+
+@mcp.tool
+async def right_click(x: int, y: int, agent_id: str = None) -> dict:
+    """Right-click at screen coordinates."""
+    return await relay_command(agent_id, "right_click", {"x": x, "y": y})
+
+@mcp.tool
+async def type_text(text: str, agent_id: str = None) -> dict:
+    """Type text using keyboard."""
+    return await relay_command(agent_id, "type_text", {"text": text})
+
+@mcp.tool
+async def press_key(key: str, agent_id: str = None) -> dict:
+    """Press a keyboard key."""
+    return await relay_command(agent_id, "press_key", {"key": key})
+
+@mcp.tool
+async def hotkey(keys: str, agent_id: str = None) -> dict:
+    """Press a keyboard shortcut (e.g., 'ctrl,c' for copy)."""
+    return await relay_command(agent_id, "hotkey", {"keys": keys})
+
+@mcp.tool
+async def scroll(direction: str, amount: int = 3, agent_id: str = None) -> dict:
+    """Scroll the screen."""
+    return await relay_command(agent_id, "scroll", {"direction": direction, "amount": amount})
+
+@mcp.tool
+async def move_mouse(x: int, y: int, agent_id: str = None) -> dict:
+    """Move mouse to coordinates without clicking."""
+    return await relay_command(agent_id, "move_mouse", {"x": x, "y": y})
+
+@mcp.tool
+async def drag(start_x: int, start_y: int, end_x: int, end_y: int, agent_id: str = None) -> dict:
+    """Drag from one point to another."""
+    return await relay_command(agent_id, "drag", {
+        "start_x": start_x, "start_y": start_y,
+        "end_x": end_x, "end_y": end_y
+    })
+
+@mcp.tool
+async def get_desktop_state(agent_id: str = None) -> dict:
+    """Get the current desktop state including open windows."""
+    return await relay_command(agent_id, "get_desktop_state", {})
+
+@mcp.tool
+async def get_screen_size(agent_id: str = None) -> dict:
+    """Get screen dimensions."""
+    return await relay_command(agent_id, "get_screen_size", {})
+
+@mcp.tool
+async def get_mouse_position(agent_id: str = None) -> dict:
+    """Get current mouse cursor position."""
+    return await relay_command(agent_id, "get_mouse_position", {})
+
+@mcp.tool
+async def app_launch(name: str, agent_id: str = None) -> dict:
+    """Launch an application."""
+    return await relay_command(agent_id, "app_launch", {"name": name})
+
+@mcp.tool
+async def app_switch(name: str, agent_id: str = None) -> dict:
+    """Switch to an open application."""
+    return await relay_command(agent_id, "app_switch", {"name": name})
+
+@mcp.tool
+async def app_close(name: str, agent_id: str = None) -> dict:
+    """Close an application."""
+    return await relay_command(agent_id, "app_close", {"name": name})
+
+@mcp.tool
+async def app_list(agent_id: str = None) -> dict:
+    """List all open applications."""
+    return await relay_command(agent_id, "app_list", {})
+
+@mcp.tool
+async def run_powershell(command: str, agent_id: str = None) -> dict:
+    """Execute a PowerShell command."""
+    return await relay_command(agent_id, "run_powershell", {"command": command})
+
+@mcp.tool
+async def run_cmd(command: str, agent_id: str = None) -> dict:
+    """Execute a CMD command."""
+    return await relay_command(agent_id, "run_cmd", {"command": command})
+
+@mcp.tool
+async def file_read(path: str, agent_id: str = None) -> dict:
+    """Read contents of a file."""
+    return await relay_command(agent_id, "file_read", {"path": path})
+
+@mcp.tool
+async def file_write(path: str, content: str, agent_id: str = None) -> dict:
+    """Write content to a file."""
+    return await relay_command(agent_id, "file_write", {"path": path, "content": content})
+
+@mcp.tool
+async def file_list(directory: str, agent_id: str = None) -> dict:
+    """List files in a directory."""
+    return await relay_command(agent_id, "file_list", {"directory": directory})
+
+@mcp.tool
+async def clipboard_copy(text: str, agent_id: str = None) -> dict:
+    """Copy text to clipboard."""
+    return await relay_command(agent_id, "clipboard_copy", {"text": text})
+
+@mcp.tool
+async def clipboard_paste(agent_id: str = None) -> dict:
+    """Get clipboard contents."""
+    return await relay_command(agent_id, "clipboard_paste", {})
+
+# ============================================
+# BROWSER TOOLS (Playwright - Advanced)
+# ============================================
+
+@mcp.tool
+async def browser_navigate(url: str, agent_id: str = None) -> dict:
+    """Navigate to a URL using Playwright (Advanced)."""
+    return await relay_command(agent_id, "browser_navigate", {"url": url})
+
+@mcp.tool
+async def browser_click(selector: str, agent_id: str = None) -> dict:
+    """Click an element by CSS selector."""
+    return await relay_command(agent_id, "browser_click", {"selector": selector})
+
+@mcp.tool
+async def browser_type(selector: str, text: str, agent_id: str = None) -> dict:
+    """Type text into an element by CSS selector."""
+    return await relay_command(agent_id, "browser_type", {"selector": selector, "text": text})
+
+@mcp.tool
+async def browser_press(key: str, agent_id: str = None) -> dict:
+    """Press a key (e.g., 'Enter', 'ArrowDown')."""
+    return await relay_command(agent_id, "browser_press", {"key": key})
+
+@mcp.tool
+async def browser_screenshot(agent_id: str = None) -> dict:
+    """Take a screenshot of the browser page."""
+    return await relay_command(agent_id, "browser_screenshot", {})
+
+@mcp.tool
+async def browser_content(agent_id: str = None) -> dict:
+    """Get the text content of the browser page."""
+    return await relay_command(agent_id, "browser_content", {})
+
+@mcp.tool
+async def chrome_open(url: str = None, agent_id: str = None) -> dict:
+    """Open Chrome browser."""
+    return await relay_command(agent_id, "chrome_open", {"url": url})
+
+@mcp.tool
+async def chrome_navigate(url: str, agent_id: str = None) -> dict:
+    """Navigate to a URL in Chrome."""
+    return await relay_command(agent_id, "chrome_navigate", {"url": url})
+
+@mcp.tool
+async def wait(seconds: float, agent_id: str = None) -> dict:
+    """Wait for specified seconds."""
+    return await relay_command(agent_id, "wait", {"seconds": seconds})
+
+# ============================================
+# INFO TOOLS
+# ============================================
+
+@mcp.tool
+def get_info() -> dict:
+    """Get information about Bridge MCP."""
+    agents = agent_storage.get_all()
+    return {
+        "name": "Bridge MCP",
+        "version": "2.0.0",
+        "description": "Universal PC Control for Any AI - with Persistent Storage",
+        "architecture": "Cloud Relay + Local Agent + Persistent Config",
+        "connected_agents": len(agents),
+        "agents": list(agents.keys()),
+        "config_directory": str(agent_storage.agents_file.parent),
+        "auto_discovery": config.get("auto_connect_localhost", True),
+        "github": "https://github.com/BarhamAgha1/Bridge-MCP"
+    }
+
+@mcp.tool
+def get_setup_instructions() -> str:
+    """Get setup instructions for Bridge MCP."""
+    return """
+    Bridge MCP Setup Instructions (v2.0 - Persistent Storage)
+    ==========================================================
+    
+    QUICK START (Recommended):
+    --------------------------
+    1. Run local_agent.py on your Windows PC (keep it running)
+    2. That's it! Bridge MCP auto-discovers and remembers your agent.
+    
+    The agent registration is PERSISTENT - it survives across:
+    - Claude Code sessions
+    - Claude Desktop restarts
+    - Computer reboots (as long as local_agent.py is running)
+    
+    MANUAL REGISTRATION (if needed):
+    ---------------------------------
+    Use register_agent("my-pc", "http://127.0.0.1:8006", "My PC")
+    
+    CHECK STATUS:
+    -------------
+    - list_agents() - See all registered agents
+    - check_agent_health() - Verify agents are online
+    
+    CONFIG LOCATION:
+    ----------------
+    Windows: %APPDATA%/bridge-mcp/agents.json
+    Linux/Mac: ~/.config/bridge-mcp/agents.json
+    """
+
+# ============================================
+# ENTRY POINT
+# ============================================
+
+if __name__ == "__main__":
+    mcp.run()