@gnkz/websight-mcp-server

Local MCP stdio server for pairing Websight with a Chrome extension, exposing browser tools to MCP clients over a localhost bridge.

Overview

This package is the server half of Websight. It starts an MCP server over stdio, serves a localhost pairing page, manages browser pairing sessions, and forwards browser tool requests to the Websight extension over a websocket bridge.

If your MCP client can launch a local process, you can use this package to add browser-aware tools like page snapshots, selector queries, clicks, scrolls, and input filling.

Quick Start

1. Run the published package.

npx -y @gnkz/websight-mcp-server

2. Load the Websight extension in Chrome or Brave.

3. Create a pairing session from your MCP client.

4. Open the returned http://127.0.0.1:44646/connect/<pairingId> URL.

5. Click Connect and approve the request in the extension window.

Once the pairing reaches connected, browser tools are ready to use.

Installation

Published package

npx -y @gnkz/websight-mcp-server

Local development

From the monorepo root:

bun run dev:server

Or run the source entry directly:

bun apps/mcp-server/src/index.ts

Usage

This package is meant to be launched by an MCP client as a local stdio server.

Example OpenCode entry:

{
  "websight-local": {
    "type": "local",
    "command": [
      "bun",
      "/absolute/path/to/websight/apps/mcp-server/src/index.ts"
    ],
    "enabled": true,
    "timeout": 300000
  }
}

The default local endpoints are:

• health: http://127.0.0.1:44646/health
• pairing page: http://127.0.0.1:44646/connect/<pairingId>
• bridge websocket: ws://127.0.0.1:44646/bridge
• MCP metadata endpoint: http://127.0.0.1:44646/mcp

Pairing Flow

The intended agent flow is:

1. Call create_pairing_session
2. Open the returned localhost URL in the browser with the extension installed
3. Click Connect on the page
4. Approve the connection in the extension window
5. Poll get_pairing_status until it becomes connected
6. Start using browser tools like get_active_tab and get_page_snapshot

Available Tools

Pairing

• create_pairing_session
• get_pairing_status

Browser access

• get_active_tab
• get_page_snapshot
• query_selector_all
• fill_input
• click_element
• scroll_to
• wait_for_element

Configuration

| Variable | Description | Default | |----------|-------------|---------| | WEBSIGHT_BRIDGE_PORT | Localhost port for the HTTP bridge and websocket endpoint | 44646 | | WEBSIGHT_HOST | Bind host for the local server | 127.0.0.1 | | WEBSIGHT_MCP_ENDPOINT | MCP metadata path | /mcp |

Troubleshooting

The server starts but browser tools say the bridge is unavailable

Check http://127.0.0.1:44646/health. If bridgeConnected is false, reload the extension and complete a fresh pairing flow.

Pairing is approved but the bridge does not connect

Reload the extension build and create a new pairing session. Pairing links are one-time and short-lived.

Page snapshot fails on a normal site

Make sure the extension was rebuilt and reloaded after any manifest changes. The active tab must also be a normal http or https page.

Notes

• This package provides the local MCP server only. You still need the companion Websight extension loaded in the browser.
• The current extension setup uses broad host permissions for local testing.