@striderlabs/mcp-spectrum 1.0.0

package/src/index.ts

@@ -0,0 +1,733 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  Tool,
+} from "@modelcontextprotocol/sdk/types.js";
+import { chromium, Browser, Page } from "playwright";
+
+// ── Constants ──────────────────────────────────────────────────────────────────
+const SPECTRUM_BASE = "https://www.spectrum.com";
+const SPECTRUM_MY_ACCOUNT = "https://www.spectrum.net/login";
+const SPECTRUM_ACCOUNT_OVERVIEW = "https://www.spectrum.net/account/overview";
+const SPECTRUM_BILL = "https://www.spectrum.net/account/billing";
+const SPECTRUM_SERVICES = "https://www.spectrum.net/account/services";
+const SPECTRUM_SUPPORT = "https://www.spectrum.net/support";
+const SPECTRUM_OUTAGES = "https://www.spectrum.net/support/internet/spectrum-internet-outages";
+const SPECTRUM_SCHEDULE = "https://www.spectrum.net/account/services/schedule";
+
+// ── Browser helper ─────────────────────────────────────────────────────────────
+async function getBrowser(): Promise<Browser> {
+  const cdpUrl = process.env.BROWSERBASE_CDP_URL;
+  if (!cdpUrl) {
+    throw new Error(
+      "BROWSERBASE_CDP_URL environment variable is required. " +
+        "Set it to your Browserbase CDP WebSocket URL."
+    );
+  }
+  return chromium.connectOverCDP(cdpUrl);
+}
+
+async function getPage(browser: Browser): Promise<Page> {
+  const contexts = browser.contexts();
+  const ctx = contexts.length > 0 ? contexts[0] : await browser.newContext();
+  const pages = ctx.pages();
+  return pages.length > 0 ? pages[0] : await ctx.newPage();
+}
+
+/** Navigate and wait for network idle */
+async function navigate(page: Page, url: string): Promise<void> {
+  await page.goto(url, { waitUntil: "domcontentloaded", timeout: 30_000 });
+}
+
+/** Login helper — reuses session if already logged in */
+async function ensureLoggedIn(
+  page: Page,
+  username: string,
+  password: string
+): Promise<void> {
+  const currentUrl = page.url();
+  if (currentUrl.includes("spectrum.net/account")) {
+    // Already on account pages — likely logged in
+    return;
+  }
+
+  await navigate(page, SPECTRUM_MY_ACCOUNT);
+
+  // Check if already redirected past login
+  await page.waitForTimeout(1500);
+  if (page.url().includes("/account")) {
+    return;
+  }
+
+  // Fill login form
+  await page.fill('input[name="IDToken1"], input[type="text"][id*="username"], #IDToken1', username);
+  await page.fill('input[name="IDToken2"], input[type="password"], #IDToken2', password);
+  await page.click('button[type="submit"], input[type="submit"], button:has-text("Sign In"), button:has-text("Log In")');
+
+  // Wait for redirect after login
+  await page.waitForURL(/spectrum\.net\/(account|my-account)/, { timeout: 20_000 }).catch(() => {
+    // May redirect to different page — ignore timeout and check url
+  });
+}
+
+/** Extract visible text from a selector, or return a fallback */
+async function safeText(page: Page, selector: string, fallback = ""): Promise<string> {
+  try {
+    return (await page.textContent(selector, { timeout: 3000 }))?.trim() ?? fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+// ── Tool implementations ───────────────────────────────────────────────────────
+
+async function getAccountOverview(args: {
+  username: string;
+  password: string;
+}): Promise<string> {
+  let browser: Browser | null = null;
+  try {
+    browser = await getBrowser();
+    const page = await getPage(browser);
+    await ensureLoggedIn(page, args.username, args.password);
+    await navigate(page, SPECTRUM_ACCOUNT_OVERVIEW);
+
+    // Wait for content to load
+    await page.waitForTimeout(2000);
+
+    // Scrape account summary
+    const pageText = await page.evaluate(() => document.body.innerText);
+
+    // Extract key info using regex patterns
+    const planMatch = pageText.match(/(?:plan|package|service)[:\s]+([^\n]+)/i);
+    const balanceMatch = pageText.match(/(?:balance|amount due|total due)[:\s]*\$?([\d,.]+)/i);
+    const dueDateMatch = pageText.match(/(?:due date|payment due)[:\s]+([^\n]+)/i);
+    const dataUsageMatch = pageText.match(/(?:data usage|data used)[:\s]*([\d.]+\s*(?:GB|MB|TB))/i);
+
+    const result = {
+      account_url: page.url(),
+      current_plan: planMatch?.[1]?.trim() ?? "Unable to retrieve",
+      balance_due: balanceMatch?.[1] ? `$${balanceMatch[1]}` : "Unable to retrieve",
+      payment_due_date: dueDateMatch?.[1]?.trim() ?? "Unable to retrieve",
+      data_usage: dataUsageMatch?.[1]?.trim() ?? "Unable to retrieve",
+      raw_summary: pageText.slice(0, 2000),
+    };
+
+    return JSON.stringify(result, null, 2);
+  } finally {
+    if (browser) await browser.close();
+  }
+}
+
+async function getServiceDetails(args: {
+  username: string;
+  password: string;
+  service_type?: string;
+}): Promise<string> {
+  let browser: Browser | null = null;
+  try {
+    browser = await getBrowser();
+    const page = await getPage(browser);
+    await ensureLoggedIn(page, args.username, args.password);
+    await navigate(page, SPECTRUM_SERVICES);
+
+    await page.waitForTimeout(2000);
+
+    const pageText = await page.evaluate(() => document.body.innerText);
+
+    // Parse out service sections
+    const services: Record<string, string> = {};
+    const serviceTypes = ["internet", "tv", "voice", "phone", "mobile"];
+
+    for (const svc of serviceTypes) {
+      if (
+        !args.service_type ||
+        args.service_type.toLowerCase() === svc
+      ) {
+        const svcRegex = new RegExp(
+          `${svc}[^\\n]*\\n([\\s\\S]{0,500})`,
+          "i"
+        );
+        const match = pageText.match(svcRegex);
+        if (match) {
+          services[svc] = match[1].trim().slice(0, 300);
+        }
+      }
+    }
+
+    return JSON.stringify(
+      {
+        services_url: page.url(),
+        service_type_filter: args.service_type ?? "all",
+        services,
+        raw_content: pageText.slice(0, 3000),
+      },
+      null,
+      2
+    );
+  } finally {
+    if (browser) await browser.close();
+  }
+}
+
+async function payBill(args: {
+  username: string;
+  password: string;
+  amount: string;
+  payment_method?: string;
+}): Promise<string> {
+  let browser: Browser | null = null;
+  try {
+    browser = await getBrowser();
+    const page = await getPage(browser);
+    await ensureLoggedIn(page, args.username, args.password);
+    await navigate(page, SPECTRUM_BILL);
+
+    await page.waitForTimeout(2000);
+
+    // Look for "Make a Payment" or "Pay Now" button
+    const payButton = await page
+      .locator(
+        'button:has-text("Make a Payment"), a:has-text("Make a Payment"), button:has-text("Pay Now"), a:has-text("Pay Now")'
+      )
+      .first();
+
+    const payButtonExists = (await payButton.count()) > 0;
+    if (!payButtonExists) {
+      const pageText = await page.evaluate(() => document.body.innerText);
+      return JSON.stringify({
+        status: "navigation_required",
+        message: "Could not locate the payment button automatically. Manual navigation required.",
+        billing_url: page.url(),
+        page_content_preview: pageText.slice(0, 500),
+      });
+    }
+
+    await payButton.click();
+    await page.waitForTimeout(2000);
+
+    // Try to fill amount if field exists
+    const amountField = page.locator(
+      'input[name*="amount"], input[placeholder*="amount"], input[id*="amount"]'
+    ).first();
+
+    if ((await amountField.count()) > 0) {
+      await amountField.clear();
+      await amountField.fill(args.amount);
+    }
+
+    // Select payment method if specified
+    if (args.payment_method) {
+      const pmSelect = page.locator(
+        'select[name*="payment"], select[id*="payment"]'
+      ).first();
+      if ((await pmSelect.count()) > 0) {
+        await pmSelect.selectOption({ label: args.payment_method });
+      }
+    }
+
+    const currentUrl = page.url();
+    const pageText = await page.evaluate(() => document.body.innerText);
+
+    return JSON.stringify({
+      status: "payment_form_ready",
+      message: `Payment form loaded. Amount field populated with $${args.amount}. Review and confirm to complete payment.`,
+      payment_url: currentUrl,
+      amount_entered: args.amount,
+      payment_method: args.payment_method ?? "default on file",
+      page_content_preview: pageText.slice(0, 500),
+      warning: "Payment has NOT been submitted. You must click the final confirm/submit button to complete payment.",
+    });
+  } finally {
+    if (browser) await browser.close();
+  }
+}
+
+async function getBillHistory(args: {
+  username: string;
+  password: string;
+  months?: number;
+}): Promise<string> {
+  let browser: Browser | null = null;
+  try {
+    browser = await getBrowser();
+    const page = await getPage(browser);
+    await ensureLoggedIn(page, args.username, args.password);
+    await navigate(page, SPECTRUM_BILL);
+
+    await page.waitForTimeout(2000);
+
+    // Look for bill history section
+    const historyLink = page.locator(
+      'a:has-text("Bill History"), a:has-text("Billing History"), a:has-text("View All"), button:has-text("Bill History")'
+    ).first();
+
+    if ((await historyLink.count()) > 0) {
+      await historyLink.click();
+      await page.waitForTimeout(2000);
+    }
+
+    const pageText = await page.evaluate(() => document.body.innerText);
+
+    // Try to parse bill entries from table or list
+    const bills: Array<{ date: string; amount: string; status: string }> = [];
+    const billPattern =
+      /(\w+\s+\d{1,2},?\s+\d{4})[^\n]*\$([\d,.]+)[^\n]*\n?([^\n]*(?:paid|pending|due|payment)[^\n]*)?/gi;
+
+    let match;
+    const maxBills = (args.months ?? 12) * 2; // rough upper bound
+    while ((match = billPattern.exec(pageText)) !== null && bills.length < maxBills) {
+      bills.push({
+        date: match[1].trim(),
+        amount: `$${match[2]}`,
+        status: match[3]?.trim() ?? "unknown",
+      });
+    }
+
+    return JSON.stringify(
+      {
+        billing_url: page.url(),
+        months_requested: args.months ?? 12,
+        bills_found: bills.length,
+        bill_history: bills,
+        raw_content: pageText.slice(0, 4000),
+      },
+      null,
+      2
+    );
+  } finally {
+    if (browser) await browser.close();
+  }
+}
+
+async function checkOutages(args: {
+  zip_code?: string;
+  address?: string;
+  username?: string;
+  password?: string;
+}): Promise<string> {
+  let browser: Browser | null = null;
+  try {
+    browser = await getBrowser();
+    const page = await getPage(browser);
+
+    // Outage check can work without login if zip is provided
+    if (args.username && args.password) {
+      await ensureLoggedIn(page, args.username, args.password);
+    }
+
+    await navigate(page, SPECTRUM_OUTAGES);
+    await page.waitForTimeout(2000);
+
+    // If zip code provided, try to fill the outage checker
+    if (args.zip_code) {
+      const zipField = page.locator(
+        'input[placeholder*="zip"], input[name*="zip"], input[id*="zip"], input[placeholder*="ZIP"], input[type="text"]'
+      ).first();
+
+      if ((await zipField.count()) > 0) {
+        await zipField.fill(args.zip_code);
+        await page.keyboard.press("Enter");
+        await page.waitForTimeout(3000);
+      }
+    }
+
+    const pageText = await page.evaluate(() => document.body.innerText);
+
+    // Look for outage indicators
+    const hasOutage = /outage|service disruption|service interruption|we.?re aware/i.test(pageText);
+    const noOutage = /no outage|no known outage|service is operating normally|no current outage/i.test(pageText);
+
+    // Extract any outage details
+    const outageMatch = pageText.match(
+      /(outage|disruption)[^\n.]*[.\n][^\n.]*/i
+    );
+
+    return JSON.stringify(
+      {
+        outage_check_url: page.url(),
+        zip_code: args.zip_code ?? "not provided",
+        address: args.address ?? "not provided",
+        outage_detected: hasOutage && !noOutage,
+        service_normal: noOutage,
+        status_summary: outageMatch?.[0]?.trim() ?? (noOutage ? "No outages detected" : "Unable to determine outage status"),
+        raw_content: pageText.slice(0, 3000),
+      },
+      null,
+      2
+    );
+  } finally {
+    if (browser) await browser.close();
+  }
+}
+
+async function scheduleTechnician(args: {
+  username: string;
+  password: string;
+  issue_description: string;
+  preferred_date?: string;
+  preferred_time?: string;
+  contact_phone?: string;
+}): Promise<string> {
+  let browser: Browser | null = null;
+  try {
+    browser = await getBrowser();
+    const page = await getPage(browser);
+    await ensureLoggedIn(page, args.username, args.password);
+
+    // Try scheduling URL first, fall back to support
+    await navigate(page, SPECTRUM_SCHEDULE);
+    await page.waitForTimeout(2000);
+
+    if (!page.url().includes("schedule")) {
+      // Try support flow
+      await navigate(page, SPECTRUM_SUPPORT);
+      await page.waitForTimeout(2000);
+
+      const scheduleLink = page.locator(
+        'a:has-text("Schedule"), a:has-text("Technician"), button:has-text("Schedule Appointment")'
+      ).first();
+
+      if ((await scheduleLink.count()) > 0) {
+        await scheduleLink.click();
+        await page.waitForTimeout(2000);
+      }
+    }
+
+    const pageText = await page.evaluate(() => document.body.innerText);
+
+    // Try to fill in scheduling form fields if present
+    const issueField = page.locator(
+      'textarea, input[name*="description"], input[placeholder*="describe"], textarea[placeholder*="issue"]'
+    ).first();
+
+    if ((await issueField.count()) > 0) {
+      await issueField.fill(args.issue_description);
+    }
+
+    if (args.preferred_date) {
+      const dateField = page.locator(
+        'input[type="date"], input[name*="date"], input[placeholder*="date"]'
+      ).first();
+      if ((await dateField.count()) > 0) {
+        await dateField.fill(args.preferred_date);
+      }
+    }
+
+    if (args.preferred_time) {
+      const timeSelect = page.locator(
+        'select[name*="time"], select[id*="time"]'
+      ).first();
+      if ((await timeSelect.count()) > 0) {
+        await timeSelect.selectOption({ label: args.preferred_time });
+      }
+    }
+
+    if (args.contact_phone) {
+      const phoneField = page.locator(
+        'input[type="tel"], input[name*="phone"], input[placeholder*="phone"]'
+      ).first();
+      if ((await phoneField.count()) > 0) {
+        await phoneField.fill(args.contact_phone);
+      }
+    }
+
+    return JSON.stringify(
+      {
+        scheduling_url: page.url(),
+        status: "form_ready",
+        issue_description: args.issue_description,
+        preferred_date: args.preferred_date ?? "not specified",
+        preferred_time: args.preferred_time ?? "not specified",
+        contact_phone: args.contact_phone ?? "not provided",
+        message:
+          "Scheduling form has been populated. Review the form and click the submit/confirm button to complete scheduling.",
+        warning: "Appointment has NOT been submitted yet. Manual confirmation required.",
+        page_content_preview: pageText.slice(0, 500),
+      },
+      null,
+      2
+    );
+  } finally {
+    if (browser) await browser.close();
+  }
+}
+
+// ── Tool definitions ───────────────────────────────────────────────────────────
+
+const TOOLS: Tool[] = [
+  {
+    name: "get_account_overview",
+    description:
+      "Get Spectrum account overview including current plan, balance due, payment due date, and data usage summary.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        username: {
+          type: "string",
+          description: "Spectrum account username or email address",
+        },
+        password: {
+          type: "string",
+          description: "Spectrum account password",
+        },
+      },
+      required: ["username", "password"],
+    },
+  },
+  {
+    name: "get_service_details",
+    description:
+      "Get details about active Spectrum services (internet, TV, phone/voice, mobile). Optionally filter by service type.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        username: {
+          type: "string",
+          description: "Spectrum account username or email address",
+        },
+        password: {
+          type: "string",
+          description: "Spectrum account password",
+        },
+        service_type: {
+          type: "string",
+          enum: ["internet", "tv", "phone", "voice", "mobile"],
+          description: "Filter to a specific service type. Omit to retrieve all services.",
+        },
+      },
+      required: ["username", "password"],
+    },
+  },
+  {
+    name: "pay_bill",
+    description:
+      "Initiate a one-time bill payment for a Spectrum account. Loads the payment form with the specified amount. Note: final submission requires user confirmation.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        username: {
+          type: "string",
+          description: "Spectrum account username or email address",
+        },
+        password: {
+          type: "string",
+          description: "Spectrum account password",
+        },
+        amount: {
+          type: "string",
+          description: "Payment amount in dollars (e.g., '89.99'). Do not include the $ sign.",
+        },
+        payment_method: {
+          type: "string",
+          description: "Payment method label as it appears on the account (e.g., 'Visa ending in 4242'). Omit to use the default payment method on file.",
+        },
+      },
+      required: ["username", "password", "amount"],
+    },
+  },
+  {
+    name: "get_bill_history",
+    description:
+      "Retrieve past billing history for a Spectrum account, including bill dates, amounts, and payment status.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        username: {
+          type: "string",
+          description: "Spectrum account username or email address",
+        },
+        password: {
+          type: "string",
+          description: "Spectrum account password",
+        },
+        months: {
+          type: "number",
+          description: "Number of months of history to retrieve (default: 12, max: 24)",
+          minimum: 1,
+          maximum: 24,
+        },
+      },
+      required: ["username", "password"],
+    },
+  },
+  {
+    name: "check_outages",
+    description:
+      "Check for active Spectrum service outages in a given area by ZIP code or address. Login is optional but provides account-specific outage info.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        zip_code: {
+          type: "string",
+          description: "ZIP/postal code to check for outages (e.g., '90210')",
+        },
+        address: {
+          type: "string",
+          description: "Full service address to check for outages",
+        },
+        username: {
+          type: "string",
+          description: "Optional: Spectrum account username for account-specific outage check",
+        },
+        password: {
+          type: "string",
+          description: "Optional: Spectrum account password",
+        },
+      },
+    },
+  },
+  {
+    name: "schedule_technician",
+    description:
+      "Schedule a Spectrum technician visit for service issues, installation, or equipment problems. Populates the scheduling form; final submission requires user confirmation.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        username: {
+          type: "string",
+          description: "Spectrum account username or email address",
+        },
+        password: {
+          type: "string",
+          description: "Spectrum account password",
+        },
+        issue_description: {
+          type: "string",
+          description: "Description of the issue requiring a technician visit (e.g., 'Internet dropping intermittently', 'TV signal pixelating on all channels')",
+        },
+        preferred_date: {
+          type: "string",
+          description: "Preferred appointment date in YYYY-MM-DD format (e.g., '2025-03-20')",
+        },
+        preferred_time: {
+          type: "string",
+          description: "Preferred time window (e.g., 'Morning (8am-12pm)', 'Afternoon (1pm-5pm)', 'Evening (5pm-8pm)')",
+        },
+        contact_phone: {
+          type: "string",
+          description: "Contact phone number for the technician appointment (e.g., '555-123-4567')",
+        },
+      },
+      required: ["username", "password", "issue_description"],
+    },
+  },
+];
+
+// ── MCP Server ─────────────────────────────────────────────────────────────────
+
+const server = new Server(
+  {
+    name: "@striderlabs/mcp-spectrum",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: TOOLS,
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    let result: string;
+
+    switch (name) {
+      case "get_account_overview":
+        result = await getAccountOverview(
+          args as { username: string; password: string }
+        );
+        break;
+
+      case "get_service_details":
+        result = await getServiceDetails(
+          args as { username: string; password: string; service_type?: string }
+        );
+        break;
+
+      case "pay_bill":
+        result = await payBill(
+          args as {
+            username: string;
+            password: string;
+            amount: string;
+            payment_method?: string;
+          }
+        );
+        break;
+
+      case "get_bill_history":
+        result = await getBillHistory(
+          args as { username: string; password: string; months?: number }
+        );
+        break;
+
+      case "check_outages":
+        result = await checkOutages(
+          args as {
+            zip_code?: string;
+            address?: string;
+            username?: string;
+            password?: string;
+          }
+        );
+        break;
+
+      case "schedule_technician":
+        result = await scheduleTechnician(
+          args as {
+            username: string;
+            password: string;
+            issue_description: string;
+            preferred_date?: string;
+            preferred_time?: string;
+            contact_phone?: string;
+          }
+        );
+        break;
+
+      default:
+        return {
+          content: [{ type: "text", text: `Unknown tool: ${name}` }],
+          isError: true,
+        };
+    }
+
+    return {
+      content: [{ type: "text", text: result }],
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ error: message, tool: name }, null, 2),
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+// ── Entrypoint ─────────────────────────────────────────────────────────────────
+
+async function main(): Promise<void> {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("@striderlabs/mcp-spectrum MCP server running on stdio");
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});