浏览器助手

概述

Browser Orchestrator Control

Publication package: browser-orchestrator-control-0.2.7.zip

Overview

Use this skill to operate Browser Orchestrator as a headed Browser Node behind MCP Relay. Browser Orchestrator pairs with Relay using a short-lived pairing token, stores issued node credentials locally, then keeps an outbound authenticated worker WebSocket open for assigned browser tasks.

The headed browser stays local. Login, MFA, CAPTCHA, and sensitive verification steps remain manual.

Connection

Target Workbuddy experience:

• The user sees a Browser Orchestrator or MCP Relay card in Workbuddy.
• Clicking the card's try/connect action opens the MCP Relay authorization page.
• The user signs in with an MCP Relay employee account from Permissions and approves the requested MCP scopes.
• The authorization flow returns to Workbuddy.
• Workbuddy can then call the MCP Relay /mcp tools, and Relay routes approved browser tasks to paired Browser Orchestrator nodes.

MCP Relay now owns the first marketplace-style connector implementation: OAuth protected-resource metadata, authorization-server metadata, Dynamic Client Registration, authorization-code with PKCE, approval, token issuance, and user-scoped /mcp tool enforcement. This Skill teaches the Agent how to use the connection after it exists. Do not treat SKILL.md as the OAuth server.

MCP Relay also writes OAuth and user-scoped /mcp authorization audit events to its configured audit path and can restrict connector access with MCP_RELAY_OAUTH_ALLOWED_CLIENTS plus MCP_RELAY_OAUTH_ALLOWED_REDIRECT_URIS.

Token types:

• MCP_RELAY_PAIRING_TOKEN: short-lived token used only to pair this Browser Node through POST /api/nodes/pair.
• node_secret: issued by pairing and stored in .local/relay-node.json; used only by the Browser Node worker WebSocket.
• MCP Relay employee session: the Web Console login session for an employee listed in Permissions; desktop Agents that preserve the browser login session can use it to authorize same-origin /mcp connector calls.
• MCP_RELAY_MCP_TOKEN: bearer token used by desktop Agents or @tpxipsterliu/mcp-connect to call the MCP Relay Streamable HTTP MCP endpoint at /mcp when the connector cannot preserve the Web session.

Token source:

• The Relay operator sets MCP_RELAY_MCP_TOKEN on the MCP Relay server before starting npm.cmd run mcp:http.
• The Relay operator sets or issues MCP_RELAY_PAIRING_TOKEN for Browser Node pairing before starting the worker-channel server.
• The current MCP Relay console does not mint MCP API tokens. If no MCP_RELAY_MCP_TOKEN was configured on the relay server, Bearer-token connector mode is unavailable, but browser-login connector mode can still work when the Web service is configured with MCP_RELAY_MCP_PROXY_TOKEN.

Installation model:

• Install this Skill on the desktop Agent machine that will talk to MCP Relay or control a local Browser Orchestrator MCP fallback.
• Run Browser Orchestrator itself on the headed Browser Node workstation where the real browser, profile, extension, and manual login happen.
• If the desktop Agent and Browser Node are different machines, the Agent should use the mcpRelay connector. Do not expect local Browser Orchestrator commands to work on the Agent machine unless Browser Orchestrator is also installed there.
• Keep pairing and worker startup on the Browser Node workstation; keep MCP Relay /mcp connector setup on the Agent machine.

Preferred Relay mode:

$env:MCP_RELAY_URL = "https://mcp-relay.cloudplus.im"
$env:MCP_RELAY_WS_URL = "wss://mcp-relay.cloudplus.im/ws/nodes"
$env:MCP_RELAY_PAIRING_TOKEN = "replace-with-one-time-token"
npm.cmd run relay:pair
npm.cmd run relay:worker

The pairing command writes .local/relay-node.json by default. Do not ask the user to paste the issued node_secret into chat. After pairing, start the worker with npm.cmd run relay:worker; it sends node.hello, heartbeats, task progress, logs, completion, and failure events to Relay.

Electron debug console mode:

1. Open the MCP Relay Worker panel.
2. Fill Relay URL, Worker WS, Pairing Token, credentials path, node metadata, capacity, capabilities, and optional capture selector.
3. Click Pair Relay.
4. Click Start Relay after pairing.

MCP Relay connector mode for desktop Agents:

Preferred Workbuddy or browser-login connector flow:

1. Create or confirm an employee in MCP Relay Permissions.
2. Add the MCP endpoint as https://mcp-relay.cloudplus.im/mcp in the desktop Agent connector.
3. When the connector discovers OAuth metadata, authorize through MCP Relay, sign in with the MCP Relay employee account, and approve the requested scopes.
4. If Workbuddy requires Dynamic Client Registration, it registers through POST /oauth/register and then uses the returned dynamic client_id.
5. The OAuth callback returns to the desktop Agent connector with a user-scoped access token.
6. Return to the desktop Agent and complete the connector setup.

Relay operators must set the public OAuth metadata origin and Workbuddy allowlist before exposing the connector beyond local testing:

$env:MCP_RELAY_PUBLIC_ORIGIN = "https://mcp-relay.cloudplus.im"
$env:MCP_RELAY_OAUTH_ALLOWED_CLIENTS = "workbuddy"
$env:MCP_RELAY_OAUTH_ALLOWED_REDIRECT_URIS = "workbuddy://workbuddy/mcp/*/oauth/callback"
$env:MCP_RELAY_OAUTH_AUDIT_PATH = ".local/audit/oauth-mcp-audit.jsonl"

Restart the MCP Relay Web service after changing these values. Before reconnecting Workbuddy, verify:

curl.exe -i https://mcp-relay.cloudplus.im/mcp
curl.exe -s https://mcp-relay.cloudplus.im/.well-known/oauth-protected-resource/mcp
curl.exe -s https://mcp-relay.cloudplus.im/.well-known/oauth-authorization-server

The /mcp 401 Unauthorized response must advertise authorization_server as https://mcp-relay.cloudplus.im. If it advertises http://localhost:5173, Workbuddy will try OAuth dynamic client registration and authorization against the user's own machine, fail with ECONNREFUSED or incompatible-auth-server errors, and stay stuck at "authorizing". This is a Relay server configuration/deployment issue, not a Browser Orchestrator node issue.

The authorization-server metadata must advertise registration_endpoint as https://mcp-relay.cloudplus.im/oauth/register. If Workbuddy reports that the auth server does not support Dynamic Client Registration, the Relay server is running an older build or the Web service has not been restarted after deployment.

For simpler connectors that open /mcp in a browser but do not complete OAuth, MCP Relay still provides the /mcp/auth Web-session bridge. That bridge requires the connector to preserve the same-origin MCP Relay session cookie when it sends POST /mcp. Prefer the OAuth connector flow when the desktop Agent supports it.

The employee role matters for Web Console APIs: admin is required for destructive console actions, while operator can inspect and use normal console flows. MCP Relay's OAuth path should enforce /mcp access through user-scoped tokens and approved scopes; remaining production hardening belongs in Relay's Permissions and audit implementation.

Use @tpxipsterliu/mcp-connect only for connecting a desktop Agent to a remote Streamable HTTP MCP Relay endpoint, not for Browser Node worker login. The token for this mode must be the Relay MCP auth token configured on the relay server as MCP_RELAY_MCP_TOKEN; do not use MCP_RELAY_PAIRING_TOKEN or the saved Browser Node node_secret here.

npx @tpxipsterliu/mcp-connect init
npx @tpxipsterliu/mcp-connect create mcpRelay `
  --url https://mcp-relay.cloudplus.im/mcp `
  --env-header Authorization=MCP_RELAY_MCP_AUTH_HEADER
$env:MCP_RELAY_MCP_AUTH_HEADER = "Bearer <MCP_RELAY_MCP_TOKEN>"
npx @tpxipsterliu/mcp-connect doctor mcpRelay

Do not use https://mcp-relay.cloudplus.im/api/mcp; /api/* belongs to the Web Console and worker REST API namespace.

If a desktop MCP connector opens a browser authentication window for https://mcp-relay.cloudplus.im/mcp, prefer the employee login flow above. Connectors that do not preserve the Web session cookie should still use the explicit Authorization: Bearer <MCP_RELAY_MCP_TOKEN> header through mcp-connect.

Desktop agents can launch the connector with:

npx @tpxipsterliu/mcp-connect run mcpRelay

Local Browser Orchestrator MCP fallback:

Development command:

npm.cmd run mcp

Built command after npm.cmd run build:

node dist/mcp/server.js

Packaged command:

browser-orchestrator-mcp

Workflow

1. Prefer Relay mode when the user wants this machine to receive tasks from MCP Relay.
2. Pair once with a short-lived MCP_RELAY_PAIRING_TOKEN; store credentials under .local/relay-node.json.
3. Start the Relay Worker and confirm it reports connected.
4. On the desktop Agent machine, connect the Agent to Relay /mcp; prefer MCP Relay employee browser-login authorization when supported, otherwise use the Bearer-token fallback.
5. For assigned tasks, navigate only to explicit HTTP(S) target boundaries and keep the browser headed.
6. If login, MFA, CAPTCHA, or manual setup is needed, ask the user to complete it in the browser before continuing.
7. Use local MCP tools directly only for debugging or when the user asks for local browser control instead of Relay task routing.
8. Call page_screenshot or Relay screenshot behavior when visual evidence or debugging is useful.
9. Use the configured capture selector for extension capture; otherwise leave the headed browser inspectable and request manual capture.

Tools

Relay commands:

• relay:pair: pair this Browser Node with MCP Relay using MCP_RELAY_PAIRING_TOKEN.
• relay:worker: maintain the authenticated worker WebSocket to MCP Relay.

Local MCP tools:

• browser_start: start the headed browser with persistent profile and default extension path.
• browser_status: report session, run directory, URL, and extension availability.
• browser_stop: close the active browser session.
• page_goto: navigate to a URL.
• page_snapshot: return structured page state and visible body text.
• page_click: click an element by Playwright selector.
• page_fill: fill an input-like element by Playwright selector.
• page_wait: wait by time or selector.
• page_screenshot: save a screenshot into the active run directory.
• capture_trigger: trigger the scraping extension through a known selector or ask for manual capture.

Safety Rules

• Keep login, MFA, CAPTCHA, and verification steps manual.
• Do not ask the user for passwords or secret tokens in chat.
• Do not print or commit .local/relay-node.json, node secrets, pairing tokens, cookies, or browser profiles.
• Do not bypass site access controls.
• Ask for confirmation before destructive, paid, account-changing, or high-volume actions.
• Keep scraping targets explicit and user-approved.
• Use the extension capture path instead of inventing a separate scraper unless the user explicitly requests otherwise.

Capture Behavior

If capture_trigger returns mode: "manual_required", tell the user to click the extension capture button in the headed browser. Continue only after the user confirms capture finished.

If the extension injects a page button and the selector is known, call capture_trigger with selector.