opencode-browser-mcp 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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.

package/README.md

@@ -0,0 +1,302 @@
+# OpenCode Browser MCP Plugin
+
+An OpenCode plugin that integrates [Browser MCP](https://browsermcp.io) to enable browser automation capabilities within OpenCode. This plugin allows the AI to control a browser, navigate websites, fill forms, click elements, and perform other browser automation tasks.
+
+## Features
+
+- Full browser automation support through Browser MCP
+- Automatic detection of browser-related tasks
+- Context preservation for browser state across session compactions
+- Logging and monitoring of browser automation activities
+- Seamless integration with OpenCode's existing tools
+
+## Prerequisites
+
+Before using this plugin, you need:
+
+1. **Node.js** installed on your system
+2. **OpenCode** installed and configured
+3. **Browser MCP extension** installed in your browser (Chrome/Edge)
+
+## Installation
+
+### Step 1: Install Browser MCP Extension
+
+1. Visit [https://browsermcp.io/install](https://browsermcp.io/install)
+2. Install the Browser MCP extension for your browser (Chrome or Edge)
+3. Follow the extension setup instructions
+
+### Step 2: Configure OpenCode
+
+Create or update your `opencode.json` configuration file. You can create this file in one of two locations:
+
+- **Global configuration** (applies to all projects): `~/.config/opencode/opencode.json`
+- **Project-specific configuration** (applies to current project only): `./opencode.json` (in your project root)
+
+Learn more about OpenCode configuration at [https://opencode.ai/docs/config](https://opencode.ai/docs/config)
+
+Add this configuration to your `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["opencode-browser"],
+  "mcp": {
+    "browsermcp": {
+      "type": "local",
+      "command": ["npx", "-y", "@browsermcp/mcp@latest"],
+      "enabled": true
+    }
+  }
+}
+```
+
+This configuration does two things:
+1. **Installs the plugin** - OpenCode automatically downloads `opencode-browser` from npm
+2. **Configures Browser MCP** - Sets up the MCP server that actually controls the browser
+
+That's it! No manual file copying required. OpenCode handles everything automatically.
+
+#### Alternative: Install Locally (for development/testing)
+
+If you want to modify the plugin or test changes:
+
+**For global installation:**
+```bash
+mkdir -p ~/.config/opencode/plugin
+cp index.ts ~/.config/opencode/plugin/browser-mcp.ts
+```
+
+**For project-specific installation:**
+```bash
+mkdir -p .opencode/plugin
+cp index.ts .opencode/plugin/browser-mcp.ts
+```
+
+The plugin will be automatically loaded on OpenCode startup.
+
+## Configuration
+
+### Basic Configuration
+
+The minimal configuration requires only the MCP server setup:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "browsermcp": {
+      "type": "local",
+      "command": ["npx", "-y", "@browsermcp/mcp@latest"],
+      "enabled": true
+    }
+  }
+}
+```
+
+### Advanced Configuration
+
+For more control, you can disable Browser MCP tools globally and enable them per agent:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "browsermcp": {
+      "type": "local",
+      "command": ["npx", "-y", "@browsermcp/mcp@latest"],
+      "enabled": true
+    }
+  },
+  "tools": {
+    "browsermcp_*": false
+  },
+  "agent": {
+    "browser-agent": {
+      "tools": {
+        "browsermcp_*": true
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+If you need to pass environment variables to the Browser MCP server:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "browsermcp": {
+      "type": "local",
+      "command": ["npx", "-y", "@browsermcp/mcp@latest"],
+      "enabled": true,
+      "environment": {
+        "BROWSER_MCP_DEBUG": "true"
+      }
+    }
+  }
+}
+```
+
+## Usage
+
+Once installed and configured, you can use browser automation in your OpenCode prompts:
+
+### Basic Browser Navigation
+
+```
+Navigate to https://github.com and search for "opencode"
+```
+
+### Form Filling
+
+```
+Go to the contact form at https://example.com/contact and fill in:
+- Name: John Doe
+- Email: john@example.com
+- Message: Hello from OpenCode!
+Then submit the form.
+```
+
+### Web Scraping
+
+```
+Visit https://news.ycombinator.com and get the titles of the top 5 stories
+```
+
+### Complex Automation
+
+```
+Go to https://example.com/login, log in with the test credentials,
+navigate to the dashboard, and screenshot the main metrics panel
+```
+
+### Prompt Tips
+
+For best results when using browser automation:
+
+1. **Be specific** about URLs and actions
+2. **Use step-by-step instructions** for complex workflows
+3. **Specify selectors** when needed (CSS selectors, text content, etc.)
+4. **Ask for verification** when critical (screenshots, text content)
+
+You can also add browser automation guidelines to your `AGENTS.md` file:
+
+```markdown
+## Browser Automation
+
+When performing browser automation tasks:
+- Always confirm the page has loaded before interacting
+- Use descriptive selectors (prefer text content over CSS selectors)
+- Take screenshots when verification is needed
+- Handle errors gracefully (page not found, element not visible, etc.)
+- Close tabs when the task is complete
+```
+
+## Plugin Features
+
+### Automatic Browser Tool Detection
+
+The plugin automatically detects when Browser MCP tools are being used and logs the activity.
+
+### Session Context Preservation
+
+During session compaction, the plugin preserves browser automation context, ensuring the AI remembers:
+- Browser interactions that occurred
+- Current browser state considerations
+- Need to verify page state before assumptions
+
+### Tool Execution Hooks
+
+The plugin hooks into tool execution to:
+- Log browser automation activities
+- Monitor tool arguments and results
+- Enable custom post-processing of browser actions
+
+## Troubleshooting
+
+### Browser MCP Not Working
+
+1. **Check extension is installed**: Open your browser and verify the Browser MCP extension is installed and enabled
+2. **Verify MCP server config**: Ensure your `opencode.json` has the correct MCP configuration
+3. **Check Node.js**: Ensure Node.js is installed: `node --version`
+4. **Test MCP connection**: Restart OpenCode after adding the MCP configuration
+
+### Plugin Not Loading
+
+1. **Check file location**: Ensure the plugin file is in the correct directory
+2. **Check file name**: Plugin files should end in `.ts` or `.js`
+3. **Check syntax**: Ensure the TypeScript/JavaScript syntax is valid
+4. **Check logs**: Look for plugin initialization messages in OpenCode output
+
+### Tools Not Available
+
+1. **Check MCP server status**: Ensure the Browser MCP server started successfully
+2. **Check tool configuration**: Verify tools aren't disabled in your config
+3. **Restart OpenCode**: Try restarting OpenCode after configuration changes
+
+### Debug Mode
+
+Enable debug logging by modifying the plugin or checking OpenCode logs:
+
+```bash
+# Check OpenCode logs
+opencode --verbose
+```
+
+## Development
+
+### Building from Source
+
+If you want to modify the plugin:
+
+1. Clone the repository
+2. Make your changes to `index.ts`
+3. Test locally by copying to your OpenCode plugin directory
+4. Submit a PR if you'd like to contribute!
+
+### Plugin Architecture
+
+The plugin uses OpenCode's plugin system hooks:
+
+- `session.created`: Initialize session-specific state
+- `tool.execute.before`: Pre-process browser tool calls
+- `tool.execute.after`: Post-process browser tool results
+- `experimental.session.compacting`: Preserve browser context
+- `event`: Handle OpenCode events
+
+## Contributing
+
+Contributions are welcome! Please:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Submit a pull request
+
+## Resources
+
+- [Browser MCP Documentation](https://docs.browsermcp.io/)
+- [OpenCode Documentation](https://opencode.ai/docs/)
+- [OpenCode Plugin Guide](https://opencode.ai/docs/plugins/)
+- [MCP Servers in OpenCode](https://opencode.ai/docs/mcp-servers/)
+
+## License
+
+MIT License - See LICENSE file for details
+
+## Support
+
+For issues and questions:
+
+- Browser MCP issues: [Browser MCP GitHub](https://github.com/browsermcp/browser-mcp)
+- OpenCode issues: [OpenCode GitHub](https://github.com/anomalyco/opencode)
+- Plugin issues: Open an issue in this repository
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for a detailed list of changes in each version.
+

package/index.ts

@@ -0,0 +1,105 @@
+import type { Plugin } from "@opencode-ai/plugin"
+
+/**
+ * OpenCode Plugin for Browser MCP Integration
+ * 
+ * This plugin integrates Browser MCP (https://browsermcp.io) to enable browser automation
+ * capabilities within OpenCode. It allows the AI to control a browser, navigate websites,
+ * fill forms, click elements, and perform other browser automation tasks.
+ * 
+ * Setup:
+ * 1. Install the Browser MCP extension in your browser
+ * 2. Configure the MCP server in your opencode.json (see README.md)
+ * 3. Enable this plugin
+ * 
+ * The plugin automatically detects browser-related requests and provides context hints
+ * to help the AI use Browser MCP tools effectively.
+ */
+export const BrowserMCPPlugin: Plugin = async (ctx) => {
+  const { client, project } = ctx
+  
+  // Track if we've informed the user about browser automation capabilities
+  let browserCapabilitiesShown = false
+  
+  return {
+    /**
+     * Hook into session creation to inject browser automation context
+     */
+    "session.created": async ({ session }) => {
+      // Session created - ready for browser automation
+    },
+    
+    /**
+     * Hook before tool execution to provide browser-specific guidance
+     */
+    "tool.execute.before": async (input, output) => {
+      // Detect if a browser-related MCP tool is being called
+      if (input.tool.startsWith("browsermcp_")) {
+        // Browser tool execution starting
+      }
+    },
+    
+    /**
+     * Hook after tool execution to handle browser automation results
+     */
+    "tool.execute.after": async (input, output) => {
+      if (input.tool.startsWith("browsermcp_")) {
+        // You can add custom post-processing here, such as:
+        // - Logging results to a file
+        // - Sending notifications
+        // - Updating external systems
+      }
+    },
+    
+    /**
+     * Hook to add browser automation context during session compaction
+     * This helps preserve browser-related context across long sessions
+     */
+    "experimental.session.compacting": async (input, output) => {
+      // Check if any browser automation was performed in this session
+      // Guard against input.messages being undefined
+      const hasBrowserTools = input.messages?.some(msg => 
+        msg.content?.some(part => 
+          part.type === "tool_use" && part.name?.startsWith("browsermcp_")
+        )
+      )
+      
+      if (hasBrowserTools) {
+        output.context.push(`## Browser Automation Context
+
+The Browser MCP integration has been used in this session. When resuming:
+- Browser state may have changed since last interaction
+- Browser tabs opened during automation may still be active
+- Consider checking current browser state before making assumptions
+- Use Browser MCP tools to verify page state when needed`)
+      }
+    },
+    
+    /**
+     * Hook into TUI toast notifications to show browser-specific tips
+     */
+    "tui.toast.show": async (input, output) => {
+      // You could customize toast messages related to browser automation here
+    },
+    
+    /**
+     * Event handler for various OpenCode events
+     */
+    event: async ({ event }) => {
+      // Handle session idle - could be used to close browser tabs
+      if (event.type === "session.idle") {
+        // Session is idle
+      }
+      
+      // Handle session errors - could help debug browser automation issues
+      if (event.type === "session.error") {
+        // Session error occurred
+      }
+    }
+  }
+}
+
+/**
+ * Default export for the plugin
+ */
+export default BrowserMCPPlugin

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "opencode-browser-mcp",
+  "version": "1.0.2",
+  "description": "OpenCode plugin that integrates Browser MCP for browser automation",
+  "type": "module",
+  "main": "index.ts",
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "plugin",
+    "browser",
+    "browser-automation",
+    "mcp",
+    "model-context-protocol",
+    "automation",
+    "browser-control",
+    "web-automation",
+    "puppeteer-alternative"
+  ],
+  "author": "",
+  "license": "MIT",
+  "peerDependencies": {
+    "@opencode-ai/plugin": "*"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/michaljach/opencode-browser.git"
+  },
+  "homepage": "https://github.com/michaljach/opencode-browser#readme",
+  "bugs": {
+    "url": "https://github.com/michaljach/opencode-browser/issues"
+  },
+  "files": [
+    "index.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}