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

{
  "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:

{
  "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.
• mcp_config.example.json - a template for your own mcp_config.json (see below).

This repository is the standalone MCP server component only. It depends on taskSpinner already being installed and registered on the machine by the main webSlinger browser extension - the extension's installer sets up the Windows native messaging manifest, registry entries, and the local profileRegistry.json this server reads to know which Chrome profile and extension copy to launch. Install the webSlinger extension from webslinger.ai or the Chrome Web Store first; that installer places a full taskSpinner checkout under %LOCALAPPDATA%\webSlinger\taskSpinner and performs the one-time OS-level registration this MCP server relies on.

Installation

1. Install the webSlinger browser extension and run its installer at least once with Chrome open, so profileRegistry.json exists and the native messaging host is registered. Launch one automation from your webSlinger account and click Enable to grant automation permissions.
2. Clone this repository (or download it) anywhere on your machine.
3. Install the Python dependencies: mcp, psutil, and pytz.
4. Copy mcp_config.example.json to mcp_config.json in the same directory and fill in your API key (see below) - or set the WEBSLINGER_API_KEY environment variable instead.

Note that regardless of where you clone this repo, the MCP server reads its config from and writes its logs/run records under ~/webSlinger/taskSpinner/ (your home directory) rather than the repo checkout directory - this keeps runtime state stable even if you move or re-clone the repo. Copy mcp_config.example.json there as ~/webSlinger/taskSpinner/mcp_config.json.

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:

{
    "api_key": "wsk_...",
    "environment": "prod"
}

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.
environment	no	dev (default) / prod	Selects the server endpoint for script listing and metadata. Must match the environment your extension is configured for, or the key-hash guard will refuse runs.
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 account or environment switches fail loudly instead of executing under the wrong account.

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

Claude Code:

claude mcp add webslinger --scope user -- python /path/to/webslinger-mcp/mcp_server.py

Claude Agent SDK - entry in ClaudeAgentOptions.mcp_servers:

"webslinger": {
    "command": "python",
    "args": ["/path/to/webslinger-mcp/mcp_server.py"],
    "env": {"WEBSLINGER_API_KEY": "wsk_..."}
}

Machine requirements: this repo checkout, Python with mcp, psutil, and pytz installed, 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).

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. Reload/reinstall the webSlinger extension so it re-registers, or reinstall taskSpinner via the extension's installer.
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 - account or dev/prod environment switch. Align the two.
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.