xio-browser (XIOBR)

Playwright-based browser automation MCP server for the XIO Mesh. Data-driven, workflow-plugin architecture. Runs on Colab, accessible via Tailscale.

---

Quick Start (Colab)

1. Open colab/start.ipynb in Google Colab
2. Edit the CONFIG cell — set your Mac's Tailscale IP in DEFAULT_EXIT
3. Run all cells top-to-bottom
4. Copy the printed MCP config into your Mac's ~/.config/mcp/config.json

On subsequent runs, Tailscale identity is restored from Shared Drive automatically — no re-authentication needed.

---

How It Works

Mac Agent (AGY/Claude)
  → calls xb_run_workflow via MCP (HTTP/SSE over Tailscale)
      → Colab picks the exit_node (default: your Mac IP)
      → switches Tailscale exit node → all browser traffic exits through your residential IP
      → builds fingerprint from your Mac's real OS/arch (via tailscale status --json)
      → runs the .mjs workflow plugin step-by-step
      → screenshots each step → saved to Shared Drive in real time
      → stores Playwright storageState to Drive on completion
  → poll xb_job_poll to watch progress with per-step screenshots
  → call xb_session_export to get cookies → inject into XIOV0

---

Tools

Workflow Execution

Tool	Description
xb_run_workflow	Start a workflow (async) → returns job_id
xb_job_poll	Get status + all step screenshots for a job
xb_job_cancel	Cancel a queued or running job
xb_job_list	List recent jobs
xb_interact	Send a raw action to a live session page

Session Management

Tool	Description
xb_session_list	List all session slots
xb_session_create	Register a new session slot
xb_session_delete	Delete a session and its Drive files
xb_session_status	Live-check if a session is still logged in
xb_session_export	Export storageState JSON (for XIOV0)
xb_session_import	Import external cookies into a session

Workflow Plugins (Hot-Swap)

Tool	Description
xb_workflow_list	List all available plugins
xb_workflow_get	Read a workflow's .mjs source
xb_workflow_push	Upload/update a workflow (live, no restart)
xb_workflow_delete	Remove a workflow

Server

Tool	Description
xb_node_status	Tailscale IP, exit node, active jobs, uptime

---

Writing a Workflow Plugin

// my-workflow.mjs
export const meta = {
  id: 'my-workflow',
  service: 'example.com',
  action: 'signin',
  description: 'Sign into example.com',
  params: {
    email:    { type: 'string', required: true },
    password: { type: 'string', required: true },
  }
};

export async function run(ctx, params) {
  await ctx.step('navigate', async () => {
    await ctx.page.goto('https://example.com/login');
  });

  await ctx.step('fill_form', async () => {
    await ctx.page.fill('[name="email"]', params.email);
    await ctx.page.fill('[name="password"]', params.password);
    await ctx.page.click('button[type="submit"]');
  });

  await ctx.step('verify', async () => {
    const url = ctx.page.url();
    ctx.setResult({ success: true, url });
  });
}

Push it live:

xb_workflow_push({ id: "my-workflow", source: "<file contents>" })

Call it immediately:

xb_run_workflow({ workflow: "my-workflow", session_id: "my-account",
  params: { email: "me@example.com", password: "..." },
  exit_node: "100.86.149.127"   // optional, defaults to Mac IP
})

---

Built-in Workflows

ID	Service	Action
v0-signin	v0.dev	Email + password sign-in
v0-export-session	v0.dev	Verify login + export storageState
google-signin	Google	Email + password + optional TOTP

---

Drive Layout

Shared Drive (XIO_MESH/)
├── tailscale_states/colab_master.state
├── workflows/          ← plugin source files (source of truth)
├── sessions/           ← storageState JSON blobs per session
├── chrome_profiles/    ← trimmed Chrome profiles (.tar.gz)
├── xio-browser.db      ← SQLite: session index + job log
└── jobs/               ← step screenshots per job
      └── job-abc123/
            ├── 00_navigate.png
            └── result.json

---

Local Dev (Mac)

cd /path/to/xio-browser
npm install
npx playwright install chromium

# stdio mode (for testing locally)
node bin/xio-browser.mjs --stdio --drive ./dev-drive --default-exit 100.86.149.127

---

Repos

Repo	URL
XIOV0	https://github.com/MDShahid94/XIOV0_MCP_SERVER
XIOBR	https://github.com/MDShahid94/xio-browser