diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..27996d0 --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,14 @@ +{ + "name": "opendia", + "description": "OpenDia — connect your real browser to AI harnesses via MCP.", + "owner": { + "name": "Aeon Inc" + }, + "plugins": [ + { + "name": "opendia", + "source": "./plugins/opendia", + "description": "Browser automation through your logged-in Chrome/Firefox session — MCP server, skills, and harness docs." + } + ] +} diff --git a/.github/CHANGELOG.md b/.github/CHANGELOG.md index b1546c2..bceb6bc 100644 --- a/.github/CHANGELOG.md +++ b/.github/CHANGELOG.md @@ -8,6 +8,10 @@ itself rather than reconstructing it at tag time. ## Unreleased +### Added + +- **Grok Build harness + plugin.** Marketplace index at `.grok-plugin/marketplace.json` (and Claude-compatible `.claude-plugin/marketplace.json`), plugin package under `plugins/opendia/` with `.mcp.json`, skills (`opendia`, `opendia-harness`), and harness docs. README lists Grok Build under Compatible AI Clients with plugin and `config.toml` setup. + ### ⚠️ Breaking - **`--tunnel` now requires a bearer token.** Publishing the MCP server through a diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md index de594df..faaa956 100644 --- a/.github/CONTRIBUTING.md +++ b/.github/CONTRIBUTING.md @@ -13,6 +13,8 @@ both and landing a PR. - **New browser tools / site support** — bridging a new capability across the server and extension. - **Docs** — setup, tunnel mode, client compatibility. +- **Harness plugins** — Grok Build / Claude Code packaging under `plugins/` + (marketplace indexes: `.grok-plugin/`, `.claude-plugin/`). ## Before you start diff --git a/.github/README.md b/.github/README.md index 6444ac8..da5d554 100644 --- a/.github/README.md +++ b/.github/README.md @@ -39,7 +39,7 @@ OpenDia lets AI models control your browser automatically. **The key advantage? - ✅ **Local testing**: Perfect for development with Cursor - test with real user sessions **✨ Key Benefits:** -- 🔄 **Universal AI Support**: Works with Claude, ChatGPT, Cursor and even local models +- 🔄 **Universal AI Support**: Works with Claude, ChatGPT, Cursor, Grok Build and even local models - 🎯 **Anti-Detection**: Specialized bypasses for Twitter/X, LinkedIn, Facebook - 📱 **Smart Automation**: AI understands your pages and finds the right elements - 🛡️ **Privacy-First**: Everything runs locally, your data stays with you @@ -66,6 +66,7 @@ OpenDia exposes a standard MCP server, so it works with any client that speaks t - **Claude Desktop** — paste the config below, restart. - **Claude Code** — same MCP config, runs from any terminal. - **Cursor** — add via Settings → MCP, or paste the same JSON. +- **Grok Build** — install the OpenDia plugin or add the MCP block to `~/.grok/config.toml` (see [Grok Build](#grok-build) below). - **ChatGPT** — works with Auto-Tunnel mode (`npx opendia --tunnel`), then add the ngrok URL as a connector. **Should work** (any MCP-compatible client): Windsurf, Zed, Continue, Cline, Goose, Open WebUI. @@ -149,6 +150,37 @@ Add to your Claude Desktop configuration: **For Cursor or other AI tools**, use the same configuration or follow their specific setup instructions. +### Grok Build + +OpenDia ships a first-class **Grok Build plugin** under [`plugins/opendia/`](../plugins/opendia) (marketplace index: [`.grok-plugin/marketplace.json`](../.grok-plugin/marketplace.json)). + +**Option A — Plugin (recommended)** + +```bash +grok plugin marketplace add aeonfun/opendia +grok plugin install opendia --trust +``` + +Enable the plugin in `/plugins` (trust is required for MCP). Details, skills, and troubleshooting: [`plugins/opendia/README.md`](../plugins/opendia/README.md). + +**Option B — Manual `config.toml`** + +Add to `~/.grok/config.toml` (or a project `.grok/config.toml`): + +```toml +[mcp_servers.opendia] +command = "npx" +args = ["-y", "opendia"] +enabled = true +startup_timeout_sec = 60 +``` + +Then install the browser extension and confirm it is connected to `ws://localhost:5555`. + +```bash +grok mcp doctor opendia +``` + ## Usage Modes ### Local Mode (Default) diff --git a/.grok-plugin/marketplace.json b/.grok-plugin/marketplace.json new file mode 100644 index 0000000..fd3b7e1 --- /dev/null +++ b/.grok-plugin/marketplace.json @@ -0,0 +1,23 @@ +{ + "name": "opendia", + "description": "OpenDia — connect your real browser to AI harnesses via MCP (Grok Build, Claude Code, Cursor, and more).", + "owner": { + "name": "Aeon Inc", + "email": "hello@aeon.fun" + }, + "plugins": [ + { + "name": "opendia", + "description": "Browser automation through your logged-in Chrome/Firefox session — MCP server, skills, and Grok Build harness docs.", + "category": "browser", + "source": { + "type": "local", + "path": "./plugins/opendia" + }, + "version": "1.0.0", + "homepage": "https://github.com/aeonfun/opendia", + "tags": ["browser", "mcp", "automation", "chrome", "firefox", "grok", "harness"], + "keywords": ["opendia", "browser-automation", "mcp", "grok-build"] + } + ] +} diff --git a/opendia-mcp/package.json b/opendia-mcp/package.json index 736af4a..d59d933 100644 --- a/opendia-mcp/package.json +++ b/opendia-mcp/package.json @@ -19,6 +19,8 @@ "automation", "ai", "claude", + "grok", + "grok-build", "chrome", "extension", "twitter", diff --git a/plugins/opendia/.mcp.json b/plugins/opendia/.mcp.json new file mode 100644 index 0000000..9aa6ea3 --- /dev/null +++ b/plugins/opendia/.mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "opendia": { + "command": "npx", + "args": ["-y", "opendia"] + } + } +} diff --git a/plugins/opendia/README.md b/plugins/opendia/README.md new file mode 100644 index 0000000..9a42fa6 --- /dev/null +++ b/plugins/opendia/README.md @@ -0,0 +1,109 @@ +# OpenDia — Grok Build plugin + +Install OpenDia as a **Grok Build** (or Claude Code–compatible) plugin. It wires the local OpenDia MCP server into the harness and ships skills so the model uses your **real browser session** correctly. + +## Prerequisites + +1. **Browser extension** loaded (Chrome / Firefox / Chromium) from [releases](https://github.com/aeonfun/opendia/releases). +2. **Node.js 16+** so `npx opendia` can run. +3. Extension shows **connected** (green) to the MCP server (`ws://localhost:5555` by default). + +The plugin starts the MCP process over **stdio**. The extension still talks to the server over the local WebSocket; `npx opendia` opens both. + +## Install (Grok Build) + +### One-shot install from this repo + +```bash +# After this PR merges into aeonfun/opendia: +grok plugin marketplace add aeonfun/opendia +grok plugin install opendia --trust + +# Or install the plugin folder directly (works from a fork/branch too): +grok plugin install aeonfun/opendia#plugins/opendia --trust +``` + +Plugins stay off until enabled. Confirm with: + +```bash +grok plugin list +grok mcp list +grok mcp doctor opendia +``` + +In the TUI: `/plugins` → enable **opendia**, ensure it is **trusted** (required for MCP). + +### Manual harness config (no plugin) + +Add to `~/.grok/config.toml` (or project `.grok/config.toml`): + +```toml +[mcp_servers.opendia] +command = "npx" +args = ["-y", "opendia"] +enabled = true +# First cold start may download the npm package +startup_timeout_sec = 60 +``` + +Restart Grok Build or reload MCP (`/mcps`). + +## What you get + +| Component | Path | Purpose | +|-----------|------|---------| +| MCP server | `.mcp.json` / `plugin.json` | Spawns `npx -y opendia` (stdio + local WS/SSE) | +| Skill | `skills/opendia/SKILL.md` | When/how to drive the browser through OpenDia | +| Skill | `skills/opendia-harness/SKILL.md` | Setup, ports, extension connect, troubleshooting | + +## Tool surface + +Once the extension is connected, tools include (names as registered by the server; Grok exposes them as `opendia__`): + +| Tool | Role | +|------|------| +| `page_analyze` | Discover interactive elements / page structure | +| `page_extract_content` | Clean text extraction | +| `page_navigate` / `page_wait_for` / `page_scroll` | Navigation & timing | +| `element_click` / `element_fill` / `element_get_state` | Interaction | +| `tab_create` / `tab_close` / `tab_list` / `tab_switch` | Tabs | +| `get_bookmarks` / `add_bookmark` / `get_history` | Browser data | +| `get_selected_text` / `get_page_links` | Selection & links | +| `page_style` | Visual themes / accessibility styling | + +Cold `tools/list` may return fallback schemas until the extension registers; OpenDia emits `notifications/tools/list_changed` when that happens. + +## Grok Build vs cloud browser MCPs + +| | OpenDia | Cloud/CDP browsers (e.g. Hyperbrowser) | +|--|---------|----------------------------------------| +| Session | Your real profile (cookies, wallets, extensions) | Ephemeral / remote | +| Privacy | Local-first | Leaves the machine | +| Best for | Social posts, logged-in admin UIs, wallet dApps, local app testing | Headless scrape, CI, disposable profiles | + +Prefer OpenDia when the task needs **accounts you already have open**. Prefer a cloud browser when you need isolation or no local extension. + +## Claude Code / Cursor + +Same MCP command works: + +```json +{ + "mcpServers": { + "opendia": { + "command": "npx", + "args": ["-y", "opendia"] + } + } +} +``` + +Claude Code can also use this marketplace via `.claude-plugin/marketplace.json` at the repo root. + +## Security + +OpenDia holds broad browser permissions and can act as you on every site. Only enable it in harnesses you trust. Tunnel / non-loopback HTTP requires a bearer token — see root [SECURITY.md](../../.github/SECURITY.md). + +## License + +MIT — same as the OpenDia repository. diff --git a/plugins/opendia/plugin.json b/plugins/opendia/plugin.json new file mode 100644 index 0000000..f93a265 --- /dev/null +++ b/plugins/opendia/plugin.json @@ -0,0 +1,27 @@ +{ + "name": "opendia", + "version": "1.0.0", + "description": "OpenDia for Grok Build / Claude Code: control your real browser (logged-in sessions, cookies, wallets) via the OpenDia MCP server and extension.", + "author": { + "name": "Aeon Inc" + }, + "keywords": [ + "opendia", + "browser", + "automation", + "mcp", + "chrome", + "firefox", + "grok-build", + "harness" + ], + "license": "MIT", + "repository": "https://github.com/aeonfun/opendia", + "homepage": "https://github.com/aeonfun/opendia", + "mcpServers": { + "opendia": { + "command": "npx", + "args": ["-y", "opendia"] + } + } +} diff --git a/plugins/opendia/skills/opendia-harness/SKILL.md b/plugins/opendia/skills/opendia-harness/SKILL.md new file mode 100644 index 0000000..487458c --- /dev/null +++ b/plugins/opendia/skills/opendia-harness/SKILL.md @@ -0,0 +1,83 @@ +--- +name: opendia-harness +description: > + Install, configure, and troubleshoot OpenDia for Grok Build (and other MCP + harnesses). Use when setting up the plugin, config.toml MCP entry, ports, + extension disconnects, tool timeouts, or tunnel mode. +--- + +# OpenDia harness setup (Grok Build) + +## Install plugin + +```bash +grok plugin marketplace add aeonfun/opendia +grok plugin install opendia --trust +``` + +Or pin a path: + +```bash +grok plugin install aeonfun/opendia#plugins/opendia --trust +``` + +Enable the plugin (`/plugins` or `[plugins].enabled`). **Trust is required** for the MCP server to attach. + +## Manual `config.toml` + +```toml +[mcp_servers.opendia] +command = "npx" +args = ["-y", "opendia"] +enabled = true +startup_timeout_sec = 60 +``` + +Optional custom ports (must match what the extension expects): + +```bash +npx opendia --ws-port=5555 --http-port=5556 +``` + +Default: WebSocket **5555** (extension), HTTP/SSE **5556**, stdio for the AI client. + +## Extension checklist + +1. Install from [GitHub Releases](https://github.com/aeonfun/opendia/releases) (Chrome zip or Firefox zip). +2. Load unpacked / temporary add-on as documented in the main README. +3. Open the extension popup — must show **Connected** to `ws://localhost:5555` (or your chosen WS port). +4. If disconnected: start or restart `npx opendia`, then reload the extension. + +## Doctor commands (Grok Build) + +```bash +grok mcp list +grok mcp doctor opendia +grok plugin details opendia +``` + +## Common failures + +| Symptom | Likely cause | Fix | +|---------|--------------|-----| +| MCP tools timeout | Extension not connected | Connect extension; confirm WS port | +| Tools present but actions no-op | Stale socket / server restart | Restart `npx opendia`, reload extension | +| Cold schemas only | Extension not registered yet | Wait for connect + `tools/list_changed`, re-list | +| Port conflict | Another process on 5555/5556 | `npx opendia --port=6000` and point extension at new WS | +| `npx` slow / fails startup | Cold npm download | Raise `startup_timeout_sec`; ensure network for first install | +| Tunnel 401 | Missing bearer token | Pass `Authorization: Bearer ` (printed at startup) | + +## Modes + +- **Local (default)** — stdio + loopback WS/SSE. Correct for Grok Build, Claude Code, Cursor. +- **`--tunnel`** — ngrok public URL for ChatGPT-style remote connectors. Requires token. Not the default for local harnesses. +- **`--http-host=0.0.0.0`** — LAN bind; also requires token. Avoid unless intentional. + +## When not to use OpenDia + +- Need fully isolated / headless CI browser → use a cloud or CDP-based MCP instead. +- User has not installed the extension → guide install; do not pretend browser control works. + +## Related skill + +`opendia` — runtime playbook for page analyze → act → verify once the harness is healthy. diff --git a/plugins/opendia/skills/opendia/SKILL.md b/plugins/opendia/skills/opendia/SKILL.md new file mode 100644 index 0000000..9a2dc3e --- /dev/null +++ b/plugins/opendia/skills/opendia/SKILL.md @@ -0,0 +1,61 @@ +--- +name: opendia +description: > + Drive the user's real browser through OpenDia MCP (logged-in sessions, cookies, + wallets, bookmarks, history). Use when automating Chrome/Firefox for social posts, + form fills, multi-tab research, local webapp testing, or any task that needs the + user's existing browser profile — not a disposable cloud browser. +--- + +# OpenDia browser automation + +OpenDia connects this harness to the **user's installed browser** via a local MCP server and browser extension. Prefer it whenever the work needs real sessions (Twitter/X, LinkedIn, GitHub, wallets, password-manager autofill, cookies). + +## Preconditions (check before acting) + +1. OpenDia MCP server is connected in this session (`opendia` MCP tools available). +2. Browser extension is **connected** (popup green / "Connected"). If tools time out or return connection errors, stop and tell the user to load the extension and run `npx opendia` if needed. +3. Do **not** fall back to a cloud browser MCP for the same task without asking — that drops the user's session. + +## Recommended tool loop + +1. **Orient** — `tab_list` to see open tabs; `page_analyze` on the target tab. +2. **Navigate** — `page_navigate` → `page_wait_for` until content is ready. +3. **Act** — `element_click` / `element_fill` using selectors or descriptions from `page_analyze` / `element_get_state`. +4. **Verify** — re-analyze or extract content; never assume a click/submit succeeded. +5. **Browser data** — `get_history`, `get_bookmarks`, `get_selected_text`, `get_page_links` when the user asks about "what I was reading" or selection context. + +## Social / anti-detection sites (X, LinkedIn, Facebook) + +- Prefer OpenDia's normal interaction tools over raw script injection. +- Go slower: wait for UI after each step; avoid blasting many rapid writes. +- If a post/composer fails, re-analyze the composer UI rather than retrying the same click blindly. + +## Development / local testing + +Strong fit for Cursor/Grok Build workflows: + +- Multi-step signup or checkout flows with screenshots described via extract/analyze. +- Wallet-connected dApps (MetaMask etc. already in the user's browser). +- Validating forms against real validation and cookies. + +## Tool map (server names) + +Use the MCP tools registered by the `opendia` server (in Grok Build they appear as `opendia__…` / `use_tool` with server `opendia`): + +| Area | Tools | +|------|--------| +| Page | `page_analyze`, `page_extract_content`, `page_navigate`, `page_wait_for`, `page_scroll`, `page_style` | +| Elements | `element_click`, `element_fill`, `element_get_state` | +| Tabs | `tab_create`, `tab_close`, `tab_list`, `tab_switch` | +| Data | `get_bookmarks`, `add_bookmark`, `get_history`, `get_selected_text`, `get_page_links` | + +## Safety + +- Confirm before irreversible actions (send message, place order, transfer funds, delete). +- Never exfiltrate cookies, passwords, or wallet seed material into chat logs or remote services. +- Tunnel mode (`--tunnel`) is a different trust boundary; do not enable it unless the user asked for remote/ChatGPT access. + +## If tools are missing or stale + +After extension connect, schemas can update via `tools/list_changed`. If the tool list still looks like cold fallbacks, re-list tools or restart the MCP client once the extension is green. See skill `opendia-harness` for ports and install steps.