# webpage-mcp

[![CI](https://github.com/mcpland/webpage-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/mcpland/webpage-mcp/actions/workflows/ci.yml)
[![npm](https://img.shields.io/npm/v/webpage-mcp.svg)](https://www.npmjs.com/package/webpage-mcp)
![license](https://img.shields.io/npm/l/webpage-mcp)

`webpage-mcp` is the Node.js MCP server package used by the Webpage MCP project.

It provides:

- `webpage-mcp`: CLI for registration, diagnostics, and maintenance
- `webpage-mcp-stdio`: MCP stdio server entry used by MCP clients

This package uses:

- MCP Client <-> MCP Server: `stdio`
- Webpage MCP Connector (Chrome extension) <-> MCP Server: Chrome Native Messaging
- Internal bridge: local IPC socket / pipe

No localhost HTTP server or port is required.

## Requirements

- Node.js `>= 20`
- Chrome/Chromium with the Webpage MCP Connector extension installed

## Quick Start (npm users)

1. Install the Webpage MCP Connector Chrome extension (release zip or unpacked build).
2. Configure MCP client:

```json
{
  "mcpServers": {
    "webpage-mcp": {
      "command": "npx",
      "args": ["-y", "-p", "webpage-mcp@latest", "webpage-mcp-stdio"]
    }
  }
}
```

3. Start MCP client (with Chrome open and extension enabled).

`webpage-mcp-stdio` will silently bootstrap Native Messaging on startup (manifest/runtime check + user-level auto-register when needed).

4. If connection still fails, run fallback recovery:

```bash
npx -y webpage-mcp@latest register --browser chrome --force --extension-id <your_extension_id>
npx -y webpage-mcp@latest doctor --fix
```

Recommended: copy the register command from extension popup/welcome page, because it already includes the current extension ID.

## Version Compatibility

The Webpage MCP Connector Chrome extension and this `webpage-mcp` npm package are built and released from the same CI pipeline, but Chrome Web Store review and rollout timing is not fixed. This means the latest npm package may be available before the matching Chrome extension version reaches users.

We aim to keep nearby versions compatible. If you run into connection, protocol, or tool behavior issues, first make sure the Chrome extension and the MCP npm package use the same version for the best compatibility.

## Is Register One-Time?

Usually yes. In many cases you do not need manual register because startup bootstrap handles it.

If manual register is used, re-register only when one of these changes:

- extension ID
- host install path
- Chrome profile/manifest files reset

Normal restarts (OS / Chrome / MCP client) do not require re-registering.

## CLI Commands

```bash
webpage-mcp register [--browser chrome|chromium|all] [--detect] [--system] [--extension-id <id1,id2>] [--force]
webpage-mcp doctor [--fix] [--json] [--browser chrome|chromium|all]
webpage-mcp report [--json] [--output <file>] [--copy] [--no-redact] [--include-logs none|tail|full] [--log-lines <n>] [--browser chrome|chromium|all]
webpage-mcp fix-permissions
```

Notes:

- `register --force` is kept for compatibility; registration is idempotent.
- `register --system` requires admin/sudo privileges.
- `report` is intended for issue submission and troubleshooting.

## Local Development (this monorepo)

Build package:

```bash
pnpm --filter webpage-mcp build
```

Verify local build health:

```bash
node app/mcp-server/dist/cli.js doctor
```

`webpage-mcp-stdio` started from local build also performs silent bootstrap. Only run manual register if connection still fails:

```bash
node app/mcp-server/dist/cli.js register --detect
# or
node app/mcp-server/dist/cli.js register --browser chrome --extension-id <your_extension_id>
```

Use local stdio entry in MCP client config:

```json
{
  "mcpServers": {
    "webpage-mcp-local": {
      "command": "node",
      "args": [
        "/absolute/path/to/webpage-mcp/app/mcp-server/dist/mcp/mcp-server-stdio.js"
      ]
    }
  }
}
```

## Environment Variables

- `WEBPAGE_MCP_NATIVE_SOCKET`
  - Explicit IPC socket/pipe path for both native host and stdio bridge.
- `WEBPAGE_MCP_NATIVE_SOCKET_DIR`
  - Unix only. Custom directory for default socket file.
- `WEBPAGE_MCP_STDIO_CONNECT_TIMEOUT_MS`
  - Max wait time (ms) for stdio bridge to connect to native socket.
- `WEBPAGE_MCP_STDIO_CONNECT_RETRY_INTERVAL_MS`
  - Retry interval (ms) for stdio bridge connection.
- `WEBPAGE_MCP_EXTENSION_ID` / `WEBPAGE_MCP_EXTENSION_IDS`
  - Override/add allowed extension IDs during registration.
- `WEBPAGE_MCP_ALLOWED_ORIGINS`
  - Additional allowed Chrome extension origins (comma or whitespace separated).
- `WEBPAGE_MCP_AUTH_TOKEN`
  - Optional token exposed to extension via `auth_get_token` (for UI display/copy and downstream use).

## Optional Auth Token

Set an auth token if you want the extension to read it from the native host:

```bash
export WEBPAGE_MCP_AUTH_TOKEN="your-token"
```

Current behavior:

- Token is returned by native host `auth_get_token`.
- Token is not currently enforced as an auth check for MCP tool calls.

## Troubleshooting

If you see `ENOENT` / "Unable to connect to native bridge socket":

1. Confirm extension is enabled and connected.
2. Check that the Chrome extension and `webpage-mcp` npm package versions match, especially after a fresh npm release.
3. Re-run registration with current extension ID:

```bash
npx -y webpage-mcp@latest register --browser chrome --force --extension-id <your_extension_id>
```

4. Run:

```bash
npx -y webpage-mcp@latest doctor --fix
```

5. Fully restart Chrome and retry.

## Related Docs

- Root project guide: [../../README.md](../../README.md)
- Troubleshooting: [../../docs/TROUBLESHOOTING.md](../../docs/TROUBLESHOOTING.md)
