# webslinger-mcp

webSlinger's MCP server exposes a user's own previously recorded and validated
browser automations - "scripts" - as MCP tools, so an agent can call
`list_scripts` and `run_script` to reliably drive a real website instead of
improvising selectors live in the moment. Each script was generated once from
a human demonstration of the task and runs deterministically on every call,
returning structured JSON output. When no script yet covers a needed task,
the agent calls `request_demonstration` to ask the user to record one.

## About

Agents that browse the live web typically re-derive selectors on every single
run, which is slow, costly in tokens, and breaks the moment a page's markup
drifts - selector drift is one of the most common reliability failures in
agentic web browsing. webSlinger takes a different approach: a human
demonstrates a task once in their own browser, and webSlinger records that
demonstration as a session map and generates a reusable automation script
from it. From that point on, the MCP server lets an agent discover and run
those already-generated scripts instead of browsing ad hoc. Selectors are
made robust by generating them from context-related features of the page -
not raw positional selectors - and by generating multiple candidate
selectors per element that are cross-validated against the live page and
reconciled through a voting mechanism at run time, so a script keeps working
even as a page's markup shifts around it. Execution itself is deterministic:
no AI drives the browser during a run; the one run-time AI fallback is a
self-healing re-detection step used only when a selector fails outright.

Two things about setup are worth stating plainly rather than leaving
implicit: this server drives the user's own real, logged-in Chrome profile
through a Windows native messaging host (taskSpinner) running on their
machine, and it requires an active webSlinger account and API key. It is not
a generic, zero-setup public server that anyone can call against an
arbitrary site - it is a personal automation layer for the account holder's
own previously demonstrated tasks. When no script yet exists for a needed
task, the agent can request one: `request_demonstration` opens a pre-filled
briefing page in the user's Chrome so they can record it in a few minutes.

Get the full webSlinger browser extension at
[webslinger.ai](https://webslinger.ai) or the Chrome Web Store - it is what
records session maps and generates the scripts this server runs.

## Quickstart

This is a structurally accurate, illustrative example of the tool-call
sequence - it does not depict any real user's data. The script name
`checkVendorPortalStatus` is a generic stand-in. For real installation and
MCP client configuration steps, see **Installation** and **MCP server
configuration (mcp_config.json)** below.

1. **Discover available scripts:**

```
list_scripts()
```

Illustrative response shape:

```json
{
  "success": true,
  "script_source": "user",
  "scripts": [
    {
      "filename": "checkVendorPortalStatus.js",
      "name": "Check Vendor Portal Status",
      "description": "Logs into the vendor portal and reports the status of open orders.",
      "inputData": [{"name": "vendorId", "type": "string", "example": "12345"}],
      "outputData": [{"name": "orders", "type": "array"}],
      "initialWebsite": "https://vendor-portal.example.com",
      "created_date": "2026-07-10"
    }
  ]
}
```

2. **Run the matching script:**

```
run_script(
    script_name="checkVendorPortalStatus.js",
    input_data={"vendorId": "12345"}
)
```

This launches the user's Chrome profile, executes the script exactly as if
it had been scheduled for that moment, and blocks until the run reaches a
terminal state.

Illustrative response shape on success:

```json
{
  "success": true,
  "status": "completed",
  "run_id": "20260710_141530_a3f9",
  "output_data": {
    "orders": [
      {"orderId": "PO-4471", "status": "Shipped", "eta": "2026-07-22"},
      {"orderId": "PO-4472", "status": "Processing", "eta": null}
    ]
  },
  "summary": "{ ... execution report summary: actions run, timing, extraction counts ... }",
  "start_time": "2026-07-10T14:15:31Z",
  "end_time": "2026-07-10T14:16:48Z"
}
```

`run_script` always returns a JSON object with a `success` flag; on an
expected failure it returns `success: false` with a `status` value the agent
can branch on (for example `not_configured`, `not_allowed`,
`script_not_found`, `busy`, `throttled`, `timeout`, or `failed`) rather than
throwing.

3. **No matching script yet?** Ask the user to record one instead of
   improvising the site interaction:

```
request_demonstration(
    target_url="https://vendor-portal.example.com/orders",
    task_description="Log in and list the status of all open purchase orders.",
    goals=[
        "array: orders(orderId, status, eta)",
        "input: vendorId - the vendor account to check"
    ]
)
```

This opens a pre-filled briefing page in the user's own Chrome; the tool
returns immediately, and the agent re-checks `list_scripts` after the user
records and the script is generated.

The full tool list is `list_scripts`, `describe_script`, `run_script`,
`start_run`, `get_run_status`, `get_run_report`, `list_runs`, `cancel_run`,
`request_demonstration`, plus schedule management (`create_schedule`,
`list_schedules`, `delete_schedule`). Each tool's docstring in
`mcp_server.py` documents its exact parameters and return shape.

## What's in this repository

- `mcp_server.py` - the MCP server (stdio JSON-RPC), exposing the tools
  listed above. This is the readable, auditable copy of exactly the file the
  webSlinger installer places on your machine.
- `mcp_config.example.json` - a template for your own `mcp_config.json`
  (see below).

**This repository is not meant to be cloned and run on its own.**
`mcp_server.py` imports `taskSpinner`, the Windows native messaging host that
launches Chrome, holds the per-profile run lock, and reads
`profileRegistry.json`. taskSpinner is not published here; it is installed,
registered with Chrome, and kept up to date by the webSlinger installer. The
copy of `mcp_server.py` that the installer places next to it - together with a
bundled Python runtime and every dependency, including the MCP SDK - is the
one you register with your MCP client. Read the source here; run the installed
copy.

## Installation

1. Install the webSlinger extension from
   [webslinger.ai](https://webslinger.ai) or the Chrome Web Store.
2. Download `webSlinger_Setup.zip` from the Install page on
   [webslinger.ai](https://webslinger.ai), extract it, and run `setup.bat`.
   This installs taskSpinner, the MCP server, the bundled Python runtime, and
   all dependencies under `%LOCALAPPDATA%\webSlinger\`, and performs the
   one-time Chrome native-messaging registration the server relies on. You do
   not need Python of your own and there is nothing to `pip install`.
3. Launch one automation from your webSlinger account and click Enable. This
   grants automation permissions and registers your Chrome profile in
   `profileRegistry.json`, which the server reads to know which browser copy
   to drive.
4. Create `~/webSlinger/taskSpinner/mcp_config.json` with your API key (see
   below), or set the `WEBSLINGER_API_KEY` environment variable instead.

Note that the MCP server reads its config from and writes its logs and run
records under `~/webSlinger/taskSpinner/` (your home directory), *not* the
`%LOCALAPPDATA%` directory the program files are installed to. Reinstalling
or upgrading replaces the program files and leaves your configuration and run
history untouched.

Windows only. taskSpinner is a Windows native messaging host; macOS and Linux
hosts are planned but not yet available.

## MCP server configuration (mcp_config.json)

The MCP server reads `~/webSlinger/taskSpinner/mcp_config.json`. Copy
`mcp_config.example.json` and fill in your key. Minimal config:

```json
{
    "api_key": "wsk_..."
}
```

All fields:

| Field             | Required | Values / default        | Purpose |
|-------------------|----------|--------------------------|---------|
| `api_key`         | yes*     | your webSlinger API key | The credential shown on your webslinger.ai account page - the same one pasted into the extension. Its SHA-256 hash selects the Chrome profile and extension to launch (see below) and scopes schedule directories. |
| `extension_id`    | no       | Chrome extension id     | Manual override of which extension copy to launch. Normally omitted - the extension registers its own identity (see below). |
| `max_run_history` | no       | positive int, default 50| Number of run record directories retained under `outputData/mcpRuns/`. |
| `prune_runs`      | no       | `true` (default)        | Set `false` to keep all run records for auditing. |

*Alternative: set the `WEBSLINGER_API_KEY` environment variable, which
overrides the file's `api_key`. Prefer the environment variable when the
config file could be committed or shared - the JSON stores the key in
plaintext.

The file must be strict JSON: no comments, no trailing commas. A malformed
file makes the MCP server exit at startup (Claude Code reports reconnect
error -32000); validate with `python -m json.tool mcp_config.json`.

With no API key configured the server still starts; every tool returns
status `not_configured` with setup instructions.

## Identity: which Chrome profile and extension runs

`profileRegistry.json` (written by the webSlinger extension, next to your
local taskSpinner installation) maps `apiKeyHash -> {profileName,
extensionId}`. The extension writes this row itself - at service worker
startup and on every schedule operation - so the registered `extensionId` is
by construction the copy that holds that API key (store, unpacked, or
build).

Launch resolution precedence:

1. `extension_id` in `mcp_config.json` (manual override)
2. the registered `extensionId` for the configured key's hash
3. legacy by-name scan (only for registry rows written before extensionId
   registration existed; reload the extension to upgrade the row)

Every launch URL carries the requesting key's hash. The extension compares
it against its own stored key and refuses with `API_KEY_MISMATCH` on
disagreement, so a mix-up between accounts fails loudly instead of executing
under the wrong one.

## Tier limits and usage recording

Execution is gated and recorded per API key on every launch path:

- The MCP server pre-flights an execution-check endpoint and returns status
  `not_allowed` (with the server's message) before launching Chrome when
  your tier has no executions or the monthly limit is exhausted.
- The extension performs the same check itself before every run and fails
  closed on any error - this is the real enforcement point; the MCP
  pre-flight is a fast-fail courtesy.
- After each run the extension reports usage, which increments your
  account's execution counter.

## Registering the MCP server

Point your client at the wrapper the installer created, substituting your
Windows username. It invokes the bundled Python for you, so the server runs on
its own interpreter and its own copy of the MCP SDK and cannot conflict with
the package versions in your project's environment.

Claude Code:

```
claude mcp add webslinger --scope user -- "C:\Users\YourName\AppData\Local\webSlinger\taskSpinner\mcp_server.bat"
```

Claude Desktop - in `%APPDATA%\Claude\claude_desktop_config.json`. Backslashes
must be doubled; this is JSON, and `\U` in a Windows path is read as an escape
sequence:

```json
{
    "mcpServers": {
        "webslinger": {
            "command": "C:\\Users\\YourName\\AppData\\Local\\webSlinger\\taskSpinner\\mcp_server.bat"
        }
    }
}
```

Claude Agent SDK - entry in `ClaudeAgentOptions.mcp_servers`:

```python
"webslinger": {
    "command": r"C:\Users\YourName\AppData\Local\webSlinger\taskSpinner\mcp_server.bat",
    "env": {"WEBSLINGER_API_KEY": "wsk_..."}
}
```

Write the path out in full rather than using `%LOCALAPPDATA%` - most MCP
clients store the command literally and never expand environment variables.

Machine requirements: Windows, Chrome with the webSlinger extension loaded at
least once so `profileRegistry.json` exists, and automation permissions
granted in the extension (launch one automation from webslinger.ai and click
Enable). The installer supplies everything else.

## Troubleshooting

| Symptom | Cause / fix |
|---|---|
| `Access to the specified native messaging host is forbidden` | The active extension copy is not in the native messaging manifest's `allowed_origins`. The installer authorizes the one Web Store id it detects; if you run a second copy, add its id to `%LOCALAPPDATA%\webSlinger\taskSpinner\com.webslinger.taskspinner.json` and restart Chrome. |
| `ModuleNotFoundError: No module named 'taskSpinner'` | You are running this repository's `mcp_server.py` directly. It needs the native messaging host beside it - register the installed `mcp_server.bat` instead (see Registering the MCP server). |
| MCP reconnect error `-32000` | The server crashed at startup - almost always a malformed `mcp_config.json`. Validate with `python -m json.tool`. |
| Status `not_configured` | No API key in `mcp_config.json` / `WEBSLINGER_API_KEY`. |
| Status `launch_failed`, reason `profile_not_registered` | The configured key's hash has no row in `profileRegistry.json`. Open Chrome with the extension active (and that key configured) so it registers. |
| `API_KEY_MISMATCH` in run status | The extension's stored key differs from the MCP config's key. Copy the key from your account page into both. |
| Chrome opens a blocked-page tab | The launched extension id is disabled or wrong. Delete any stale `extension_id` override in `mcp_config.json` and reload the extension so it re-registers. |
| Status `not_allowed` | Tier gate or monthly execution limit; the message passes through the server's explanation. |

Logs: `~/webSlinger/taskSpinner/logs/taskSpinner_YYYYMMDD.log`. Run records:
`~/webSlinger/taskSpinner/outputData/mcpRuns/<run_id>/`.

## License

MIT - see [LICENSE](LICENSE).