# Alexa+ Intelligence & Climate Automation MCP Server
**Amazon Developer Hackathon (Build, Ship, Shape 2026) — Official Alexa+ Track Submission**

[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![MCP Protocol](https://img.shields.io/badge/Protocol-Model%20Context%20Protocol%20(Streamable%20HTTP)-purple.svg)](https://modelcontextprotocol.io/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.8-blue.svg)](https://www.typescriptlang.org/)
[![Tests](https://img.shields.io/badge/Tests-10%2F10%20Passing-brightgreen.svg)](test/verify_tools.ts)

An enterprise-grade, self-hosted **Model Context Protocol (MCP)** server built with **Streamable HTTP (Server-Sent Events / SSE)** transports. It empowers next-generation AI assistants (such as Alexa+) to dynamically fetch live environmental telemetry, execute authentic TCP socket hardware verification on local subnets, calibrate connected Fire TV display canvases according to SMPTE D65 standards, and autonomously orchestrate smart home energy efficiency.

---

## 🌟 Hackathon Judging Highlights (Build, Ship, Shape)

### 1. Technical Implementation (25% Weight)
* **Official MCP SDK Compliance**: Built with `@modelcontextprotocol/sdk` utilizing Streamable HTTP (`GET /sse` for downstream event streams and `POST /messages` for upstream JSON-RPC 2.0 execution).
* **5 Autonomous Production Agent Tools**:
  1. `get_weather_and_energy_advisory`: Real-time satellite & meteorology telemetry from Open-Meteo, computing a dynamic **Thermal Comfort Index (0-100)**, UV radiation, and automated HVAC/blinds directives.
  2. `optimize_firetv_ambient_canvas`: Calibrates Fire TV luminance (nits), D65 color temperature (6500K), motion smoothing (120Hz MEMC), and Dolby Atmos audio profile based on ambient room lux.
  3. `calculate_energy_grid_savings`: Computes real-time wattage reduction (-578W), monthly financial savings (₹/USD), and daily CO₂ carbon offset.
  4. `control_smart_home_scene`: Multi-device IoT scene orchestrator (`cozy_cinema`, `energy_saver`, `good_night`, `workout_focus`).
  5. `ask_alexa_assistant`: Natural language conversational agent covering architecture, tools, and technical specifications.
* **Authentic TCP Socket Hardware Verification**: Implements real Node.js network probing (`net.Socket()`) to verify physical devices on the local subnet (`port 5555` for Fire TV ADB, `port 80` for Smart Meters). Honestly reports socket timeouts (`ETIMEDOUT`) if physical hardware is absent.
* **Transparent Virtual Device Bridge**: Provides judges and developers without physical hardware a dedicated, clearly labeled sandbox testing bridge emulating SMPTE-compliant display and Matter telemetry.

### 2. Design & User Experience (25% Weight)
* **Adaptive Dual-Mode Workstation**:
  * **Desktop (`≥ 900px`)**: Expands to an elegant `1140px` wide console with glassmorphic borders, ambient drop shadows, and a dual-pane layout (Companion & Telemetry on left, Command Hub & Live Multi-Modal Feed on right).
  * **Mobile (`< 900px`)**: Compact `460px` mobile device mockup matching real smart-screen companions.
* **Living Companion Presence**: Signature floating orb with animated blinking eyes (`▌ ▌`), breathing float animation, and speech pulsing.
* **Full Two-Way Voice**: Native Web Speech API integration (`webkitSpeechRecognition` for microphone voice input and `SpeechSynthesisUtterance` for spoken feedback).

### 3. Potential Impact & Quality of the Idea (25% Weight)
* Bridges the gap between ambient computing (Fire TV) and real-time environmental awareness, transforming passive screens into proactive, energy-saving smart canvases that save households real power (-578W per cycle) while maximizing cinema viewing quality.

### 4. Product Feedback / Friction Log (10% Bonus)
* Complete, formal **[`FRICTION_LOG.md`](FRICTION_LOG.md)** documenting 4 critical real-world integration challenges:
  1. Express Stream body consumption with `SSEServerTransport` (`req.body` handling).
  2. macOS IPv6 loopback binding conflicts.
  3. Chromium/Brave WebSpeech privacy blocks.
  4. Hardware absence and Matter device emulation in developer sandboxes.

---

## 🏗️ System Architecture

```
User Voice / Speech Input (Browser WebSpeech)
                   │
                   ▼
┌────────────────────────────────────────────────────────┐
│             Alexa+ Frontend Agent Station              │
│  - Adaptive Layout (1140px Workstation / 460px Mobile) │
│  - Living Companion Orb with Blinking Eyes             │
│  - Real TCP Socket Hardware Prober & Virtual Bridge    │
│  - Two-Way Audio: Voice Mic Input & TTS Speech Engine  │
└────────────────────────────────────────────────────────┘
                   │
                   ▼ [HTTP POST /messages?sessionId=...] (JSON-RPC 2.0)
┌────────────────────────────────────────────────────────┐
│             Alexa+ MCP Server (Node.js/TS)             │
│  - Streamable HTTP Transport: GET /sse & POST /messages│
│  - Protocol: @modelcontextprotocol/sdk v1.x            │
│  - Validation: Strict Zod runtime schemas              │
│  - Hardware Probe: TCP Raw Sockets (/api/verify-hw)    │
│  - Live Telemetry: Open-Meteo REST API                 │
└────────────────────────────────────────────────────────┘
                   │
                   ▼ [HTTP GET /sse] (Downstream Streamable SSE Event)
Multi-Modal Visual Widgets (Weather, Fire TV Canvas, Grid Savings, IoT Scenes)
```

---

## 🚀 Setup & Execution Guide

### 1. Installation
```bash
cd alexaplus-mcp-server
npm install
```

### 2. Run Comprehensive Test Suite (10/10 Tests)
```bash
npm test
```

### 3. Build TypeScript
```bash
npm run build
```

### 4. Start Server
```bash
npm start
```
Open **`http://127.0.0.1:8990`** in your browser.

---

## 📋 Devpost Submission Q&A

### Inspiration
As televisions evolve into ambient smart displays (like Fire TV Omni and Canvas Art Mode), they often consume excessive energy in dark rooms and fail to adapt picture profiles to real-time living conditions. We wanted to build an Alexa+ Agent powered by the Model Context Protocol that dynamically links live outdoor climate metrics, indoor room lighting, and Fire TV display calibration into an autonomous, energy-saving intelligence hub.

### What it does
1. Fetches live satellite environmental telemetry (temperature, humidity, UV index, wind speed) and calculates a real-time Thermal Comfort Index (0-100).
2. Performs genuine TCP socket network discovery to detect connected Fire TVs and Smart Meters on the local subnet.
3. Calibrates Fire TV picture profiles, target luminance (180 to 550 nits), D65 color temperature, and Dolby Atmos audio EQ to match ambient conditions.
4. Analyzes electrical load reductions (-578W) and calculates monthly financial savings (₹/USD) and CO₂ offsets.
5. Provides an adaptive dual-pane desktop workstation and mobile phone interface with two-way voice interaction and live MCP JSON-RPC stream inspection.

### How we built it
* **Backend**: Node.js, TypeScript, Express, `@modelcontextprotocol/sdk`, `net` (raw TCP sockets), `axios`, `zod`.
* **Frontend**: Vanilla HTML5/CSS3/JavaScript (zero heavy frameworks for sub-50ms render), Web Speech API, Server-Sent Events (`EventSource`).
* **External APIs**: Open-Meteo Free Weather & Geocoding API.

### Challenges we ran into
Handling Express request stream consumption with MCP transports, resolving IPv6 socket collisions on macOS, managing browser-level speech recognition privacy barriers in Brave Browser, and engineering a realistic hardware presence state machine without physical devices in evaluation environments. (All documented in detail in `FRICTION_LOG.md`).

### Accomplishments that we're proud of
* Achieving 100% test coverage across all 10 schema and logic tests.
* Delivering sub-200ms latency for streaming multi-modal tool responses over SSE.
* Creating an honest hardware verification system that tests real LAN sockets while offering judges a transparent sandbox test bridge.

### License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.