BillShield MCP — Autonomous Household Financial Defense & Recall Claim Add-on for Alexa+

BillShield MCP is a multi-modal Alexa+ Model Context Protocol (MCP) Add-on (Inline, Fullscreen, and Voice-only) that acts as an autonomous household financial auditor for both renters and homeowners. Built on a 19-tool hybrid agentic architecture (Atomic Live Public APIs + Pure Parameterized Math Calculators with zero hardcoded constants + V8 Code Mode Sandbox + One-Shot Workflows), families can ask Alexa+ by voice or web chat to audit inflated medical/ISP bills, optimize electric peak/off-peak utility tariffs, unlock renter-safe cash rebates, scan kitchen/nursery items for CPSC & openFDA cash recall refunds, and generate statute-cited dispute packets ready to sign and send.

Built on top of our companion open-source SDK alexa-mcp-kit and verified with our fast Pre-Flight Readiness Linter (certification-verdict.json), designed to pair directly with Amazon's official npx @alexa-ai/addon-local-inspector. Supports both the latest 2026-07-28 Stateless Streamable HTTP MCP specification and 2025-11-25 / 2025-06-18 Stateful Mcp-Session-Id negotiation. See FRICTION_LOG.md for our detailed Alexa+ MCP Toolkit engineering feedback.

Why BillShield MCP? (Zero Homeowner/Renter Friction)

American households lose $2,400–$4,800 per year to four invisible bureaucratic leaks:

1. Upcoded & Unbundled Bills ($876.36 avg. overcharge): Hospital ER bills and ISP statements routinely bundle mutually exclusive CPT codes (NCCI Column 1/2 edits), duplicate radiology line items, or charge "$15/mo customer-owned router rental fees."

2. Peak-Hour Electric Tariff Traps ($1,444.68/yr loss): Utilities on Time-of-Use (TOU) schedules charge up to 2.16x more between 4 PM and 9 PM, yet families run dryers, dishwashers, and EV chargers during peak windows without realizing the exact dollar penalty.

3. Unclaimed Renter-Safe Cash Rebates ($2,560.00 available): Renters assume federal IRA / utility incentives only apply to homeowners replacing roofs or furnaces, missing out on 100% portable, zero-landlord-permission rebates (window heat pumps, plug-in induction cooktops, smart thermostats, and community solar bill credits).

4. Unclaimed CPSC & FDA Recall Refunds ($154.00+ per household): Millions of recalled kitchen appliances, nursery monitors, and OTC medications qualify for no-receipt cash refunds, sitting untouched in cupboards.

Related MCP server: Northbridge Home Ops

System Architecture

flowchart LR
  subgraph AlexaHost["Alexa+ Multi-Modal Host (Web / Echo Show 15 / Echo Dot)"]
    Inline["Inline Mode (Chat Card)"]
    Full["Fullscreen Mode (Echo Show 15 Canvas)"]
    Voice["Voice-Only Mode (Spoken Summary + SSML)"]
  end

  subgraph BillShield["BillShield MCP Server (Streamable HTTP 2026-07-28 / 2025-11-25)"]
    T1["audit_household_bill\nui://billshield/autopsy-board"]
    T2["optimize_utility_tariff\nui://billshield/tariff-optimizer"]
    T3["find_cash_rebates\nui://billshield/rebate-board"]
    T4["scan_household_recalls\nui://billshield/recall-radar"]
    T5["generate_official_dispute_or_claim\nui://billshield/claim-packet"]
  end

  subgraph DataEngines["Official Statutory & Live API Engines"]
    E1["CMS CY2026 Fee Schedule\n& NCCI PTP Unbundling Edits"]
    E2["OpenEI Regional TOU\nPeak / Off-Peak Rate Engine"]
    E3["IRA HEAR & Utility\nRenter/Homeowner Rebate Engine"]
    E4["Live openFDA API (api.fda.gov)\n& CPSC SaferProducts Recall DB"]
  end

  AlexaHost <-->|"POST /mcp (JSON-RPC 2.0)\n+ postMessage Bridge"| BillShield
  T1 --> E1
  T2 --> E2
  T3 --> E3
  T4 --> E4
  T1 -.->|"1-Click Dispute Chain"| T5

Quickstart (Zero Config, Node.js >= 20)

# 1. Start the BillShield Alexa+ MCP Server + Multimodal Device Simulator
npm start
# -> Alexa+ Streamable HTTP MCP Endpoint: http://127.0.0.1:4040/mcp
# -> Alexa+ 3-Mode Interactive Device Simulator: http://127.0.0.1:4040/simulator

Run Pre-Certification Audit & Verification Suite

# Generate certification-verdict.json and inspection-summary.json
npm run cert

# Run full automated verification suite (Engines + MCP Server + Simulator + Live API Tools + Parameterized Math + Code Mode)
npm test

Inspect with Official Amazon Local Inspector

npx @alexa-ai/addon-local-inspector http://127.0.0.1:4040/mcp

The 19 Alexa+ MCP Tools & 6 ui:// App Resources

BillShield MCP exposes 19 registered MCP tools organized into 5 layers so Alexa+ can either invoke a single composite tool or chain atomic API + parameterized math tools inside Code Mode (execute_codemode):

Interactive Device Sandbox & Example Workflows (http://127.0.0.1:4040/simulator)

BillShield MCP includes an interactive multi-modal workbench (GET /simulator) for testing ui:// widgets across Inline, Fullscreen, and Voice-only display modes, as well as executing custom live voice/chat commands and multi-step execute_codemode plans:

1. Medical & ISP Bill Autopsy (audit_household_bill):

   • Queries live NIH Clinical Tables (clinicaltables.nlm.nih.gov), openFDA National Drug Code (NDC) (api.fda.gov/drug/ndc.json), and Zippopotam.us locality GPCI indices before auditing line items against CMS Physician Fee Schedule RVU weights and NCCI Procedure-to-Procedure (PTP) unbundling rules.

   • Detects upcoding (e.g., CPT 99285 vs. 99284), mutually exclusive bundled procedures (CPT 36415 with 80053), duplicate imaging charges (CPT 71046), and unlawful customer-owned router rental fees (47 CFR § 76.1205).

2. Adaptive 3-Display-Mode Switching (Inline ↔ Fullscreen ↔ Voice-only):

   • Inline Mode: Compact 2-KPI summary card designed for the Alexa+ conversational stream.

   • Fullscreen Mode: Split-screen itemized audit table and action bar designed for Echo Show 8 / 15 and Fire TV (>= 48px touch targets, 6.47:1 minimum WCAG 2.1 AA contrast).

   • Voice-Only Mode: Spoken summary transcript and <speak><prosody> SSML output for headless Echo Dot / Echo Auto devices.

   • Interactive widget buttons dispatch standard MCP Apps window.parent.postMessage (method: "tools/call") events—for example, chaining directly from an itemized bill audit into generate_official_dispute_or_claim (ui://billshield/claim-packet).

3. Renter-Safe Cash Rebates & 50-State Utility Tariff Optimizer (find_cash_rebates & optimize_utility_tariff):

   • Resolves any U.S. ZIP code via live geolocation (api.zippopotam.us) and filters federal IRA HEAR / utility rebates by tenure: "renter" | "homeowner" so renters only see 100% portable upgrades requiring zero landlord permission.

   • Computes appliance-level Peak-to-Off-Peak Time-of-Use (TOU) load-shift savings across all 50 U.S. states and D.C.

4. Live CPSC & openFDA Recall Cash Refunds (scan_household_recalls):

   • Queries the live U.S. CPSC SaferProducts API (saferproducts.gov) and openFDA Enforcement API (api.fda.gov) for every scanned household item to surface active recall notices and no-receipt cash/replacement remedies.

Repository Structure

billshield-mcp/
├── src/
│   ├── server.mjs                 # Streamable HTTP (2026-07-28 + 2025-11-25) MCP Server (19 tools, 6 ui:// resources)
│   ├── simulator.mjs              # Interactive Alexa+ 3-Mode Web Simulator + Live Custom Command Tester (GET /simulator)
│   ├── run-cert.mjs               # Pre-certification runner emitting certification-verdict.json
│   ├── tools/
│   │   ├── api-tools.mjs          # 5 Atomic Live Public API tools (NIH, Zippopotam, openFDA NDC & Enforcement, CPSC)
│   │   ├── calc-tools.mjs         # 4 Pure Parameterized Math Calculator tools (zero hardcoded policy constants)
│   │   └── ui-tools.mjs           # 2 Dynamic Echo Show UI & Dispute Packet builder tools
│   └── engines/
│       ├── bill-autopsy.mjs       # CMS CY2026 Fee Schedule & NCCI PTP unbundling auditor
│       ├── utility-tariff.mjs     # 50-State + DC OpenEI Time-of-Use Peak/Off-Peak optimizer
│       ├── rebate-finder.mjs      # Renter vs. Homeowner IRA/HEAR cash rebate engine
│       ├── recall-scanner.mjs     # Live openFDA + CPSC household recall refund scanner
│       └── dispute-generator.mjs  # Statute-cited dispute & claim packet generator
├── lib/
│   └── alexa-mcp-kit/             # Bundled copy of our open-source Alexa+ MCP SDK & Auditor
├── tests/
│   ├── check_engines.mjs            # Phase 1: Core domain engines & live openFDA recall matching
│   ├── check_mcp_server.mjs         # Phase 2: Streamable HTTP MCP server (19 tools & 6 ui:// resources)
│   ├── check_simulator_and_cert.mjs # Phase 3: Simulator UI, 7/7 certification audit & negative compliance checks
│   ├── check_phase5_api_tools.mjs   # Phase 5: Atomic live public API tools & MCP schema compatibility
│   ├── check_phase6_calc_tools.mjs  # Phase 6: Parameterized math calculators (dynamic conversionFactor & multipliers)
│   ├── check_phase7_agentic_flow.mjs# Phase 7: Progressive tool discovery & 7-step V8 Code Mode sandbox execution
│   └── verify_all.mjs               # Master verification suite runner
├── certification-verdict.json     # Automated pre-certification verdict ("CERTIFIED", 7/7 rules)
├── inspection-summary.json        # Detailed per-tool & per-resource inspection report
├── FRICTION_LOG.md                # Alexa+ MCP Toolkit engineering architecture & developer friction notes
└── package.json