# @striderlabs/mcp-spectrum

MCP (Model Context Protocol) server for Spectrum/Charter ISP account management. Automates common account tasks via browser automation using Playwright and Browserbase.

## Features

- **Account Overview** — View current plan, balance due, and data usage
- **Service Details** — Get details on internet, TV, phone, and mobile services
- **Pay Bill** — Initiate one-time bill payments
- **Bill History** — View past billing history
- **Check Outages** — Check for service outages by ZIP code or address
- **Schedule Technician** — Book a technician visit

## Requirements

- Node.js 18+
- A [Browserbase](https://browserbase.com) account with a CDP URL
- Valid Spectrum account credentials

## Installation

```bash
npm install @striderlabs/mcp-spectrum
```

Or install from the tarball:

```bash
npm install ./striderlabs-mcp-spectrum-1.0.0.tgz
```

## Configuration

Set the required environment variable:

```bash
export BROWSERBASE_CDP_URL="wss://connect.browserbase.com?apiKey=YOUR_KEY"
```

## Usage with Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "spectrum": {
      "command": "npx",
      "args": ["-y", "@striderlabs/mcp-spectrum"],
      "env": {
        "BROWSERBASE_CDP_URL": "wss://connect.browserbase.com?apiKey=YOUR_KEY"
      }
    }
  }
}
```

## Tools

### `get_account_overview`

Retrieves current plan, balance due, payment due date, and data usage.

**Parameters:**
- `username` (required) — Spectrum account email/username
- `password` (required) — Spectrum account password

### `get_service_details`

Gets details for active Spectrum services.

**Parameters:**
- `username` (required)
- `password` (required)
- `service_type` (optional) — One of: `internet`, `tv`, `phone`, `voice`, `mobile`

### `pay_bill`

Loads the payment form pre-filled with the specified amount. **Does not auto-submit** — user must confirm payment.

**Parameters:**
- `username` (required)
- `password` (required)
- `amount` (required) — Payment amount without `$` (e.g., `"89.99"`)
- `payment_method` (optional) — Payment method label as shown on account

### `get_bill_history`

Retrieves past bills with dates, amounts, and payment status.

**Parameters:**
- `username` (required)
- `password` (required)
- `months` (optional) — Months of history to fetch (default: 12, max: 24)

### `check_outages`

Checks for active outages in a given area.

**Parameters:**
- `zip_code` (optional) — ZIP code to check
- `address` (optional) — Service address to check
- `username` (optional) — For account-specific outage info
- `password` (optional)

### `schedule_technician`

Opens and pre-fills the technician scheduling form. **Does not auto-submit.**

**Parameters:**
- `username` (required)
- `password` (required)
- `issue_description` (required) — Description of the problem
- `preferred_date` (optional) — Date in `YYYY-MM-DD` format
- `preferred_time` (optional) — Time window (e.g., `"Morning (8am-12pm)"`)
- `contact_phone` (optional) — Contact phone number

## How It Works

This MCP server uses Playwright to automate a real Chromium browser connected via [Browserbase](https://browserbase.com)'s CDP (Chrome DevTools Protocol) URL. Each tool:

1. Connects to the remote browser via `chromium.connectOverCDP()`
2. Logs in to spectrum.net with your credentials
3. Navigates to the relevant page
4. Extracts or populates data
5. Returns structured results as JSON

## Security Notes

- Credentials are passed per-request and never stored by this server
- Payment and appointment submission require manual user confirmation — the server will not auto-submit financial transactions
- All browser sessions run in Browserbase's isolated cloud environment

## Development

```bash
git clone <repo>
cd mcp-spectrum
npm install
npm run build
```

Run in dev mode:

```bash
BROWSERBASE_CDP_URL="..." npx ts-node src/index.ts
```

## License

MIT