feat: add Grok Build harness and plugin for OpenDia (#65)

Ship a first-class Grok Build (and Claude Code-compatible) plugin so OpenDia is installable as a marketplace package, not only via manual MCP JSON. - Add plugins/opendia with .mcp.json, plugin.json, skills, and README - Add .grok-plugin and .claude-plugin marketplace indexes - Document Grok Build under Compatible AI Clients + config.toml path - Note harness plugins in CONTRIBUTING; Unreleased CHANGELOG entry - Tag npm keywords with grok / grok-build
2026-10-19 02:09:10 +00:00 · 2026-07-30 06:37:44 -06:00 · 2026-07-30 06:37:44 -06:00 · adcb350336
commit adcb350336
parent 8396f7bb2c
11 changed files with 366 additions and 1 deletions
--- a/.claude-plugin/marketplace.json
+++ 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."
+    }
+  ]
+}
--- 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
--- 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

--- 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)
--- a/.grok-plugin/marketplace.json
+++ 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"]
+    }
+  ]
+}
--- a/opendia-mcp/package.json
+++ b/opendia-mcp/package.json
@ -19,6 +19,8 @@
    "automation",
    "ai",
    "claude",
+    "grok",
+    "grok-build",
    "chrome",
    "extension",
    "twitter",
--- a/plugins/opendia/.mcp.json
+++ b/plugins/opendia/.mcp.json
@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "opendia": {
+      "command": "npx",
+      "args": ["-y", "opendia"]
+    }
+  }
+}
--- a/plugins/opendia/README.md
+++ 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>`):
+
+| 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.
--- a/plugins/opendia/plugin.json
+++ 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"]
+    }
+  }
+}
--- a/plugins/opendia/skills/opendia-harness/SKILL.md
+++ 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 <token>` (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.
--- a/plugins/opendia/skills/opendia/SKILL.md
+++ 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.