npm package: @gnkz/websight-mcp-server
Description: Local MCP bridge server for the Websight Chrome extension.
Latest version: 0.1.0-alpha.1

# @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.

```bash
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

```bash
npx -y @gnkz/websight-mcp-server
```

### Local development

From the monorepo root:

```bash
bun run dev:server
```

Or run the source entry directly:

```bash
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:

```json
{
  "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.