# Project Aegis — Cyber-Physical Zero-Trust Guardian

A fully spec-compliant Model Context Protocol (MCP) server for Amazon Alexa+,
built for **Build, Ship, Shape: Amazon Developer Hackathon** (Alexa+ track).

This is the full rebuild: it implements **all three MCP primitives**
(Resources, Prompts, Tools), correlates a **physical** domain (a Ring-style
perimeter feed) with the **digital** domain (router telemetry) to catch
attacks neither can see alone, and renders a **cinematic 3D WebGL dashboard**
(orbital topology, particle "packet stream" attack visualization, camera
dolly on containment) instead of a flat list.

## Why the architecture is a genuine MCP implementation, not just tools

| Primitive | What it's for | What Aegis does with it |
|---|---|---|
| **Resources** | Read-only context the host can pull in on its own | `aegis://telemetry/network/latest`, `aegis://telemetry/perimeter/front-door`, `aegis://telemetry/honeypot/log`, `aegis://telemetry/devices` |
| **Prompts** | A reusable, structured workflow invoked by name, so the model doesn't reinvent the analysis process every time | `analyze_cyber_physical_threat` — forces the model to read both resource feeds and cross-reference them before concluding anything |
| **Tools** | Executable actions with real side effects | `analyze_threat_vectors`, `engage_honeypot_sandbox`, `deploy_honeypot_vlan`, `block_device`, `unblock_device`, `trust_device`, `create_guest_access`, `render_aegis_dashboard`, plus the raw-data tools `get_connected_devices` / `get_network_security_report` |

## Why the scenario itself is different from what's already out there

Every existing Alexa×MCP project — and the earlier "Home Network Sentinel"
version of this project — treats network security as a purely digital
problem: read a device list, maybe block a MAC address. Project Aegis
correlates **two domains Amazon itself already spans** — Ring (physical) and
the home router (digital) — to catch a pattern neither domain reveals alone:
a **wardriving attempt**, where a car idles outside while a device probes the
Wi-Fi with a weak, edge-of-property signal. Neither signal is alarming by
itself; correlated in time, it is. That's what `analyze_threat_vectors` does.

## Project layout

```
project-aegis/
├── aegis_domain.py                  # shared business logic (single source of truth)
├── aegis_server.py                  # FastMCP, HTTP transport — deploy this for Alexa+
├── aegis_server_stdio.py            # base MCP SDK, stdio transport — local desktop hosts
├── test_client.py                   # exercises all three MCP pillars against aegis_server.py
├── requirements.txt
├── demo/
│   ├── aegis_dashboard.html         # cinematic dark-mode 3D dashboard (MCP-UI resource)
│   └── aegis_dashboard_light.html   # "Aegis Light" — corporate glassmorphism variant
└── aegis-light-dashboard-react/     # standalone React + R3F + Framer Motion + Tailwind app
```

## Two servers, on purpose

You'll notice **two** server entry points. This isn't redundancy — it's
because "strictly follow the official MCP quickstart" and "connect to
Alexa+" pull in different directions, and pretending otherwise would ship
something that doesn't actually run:

| | `aegis_server.py` | `aegis_server_stdio.py` |
|---|---|---|
| SDK | FastMCP (high-level wrapper) | base `mcp` SDK (`mcp.server.Server`) |
| Transport | HTTP | stdio |
| Use it for | **Deploying to Alexa+** — Alexa+ is a cloud service; it can only reach a public HTTP(S) endpoint, never a local subprocess | Local development in Claude for Desktop, `mcp dev`, or the MCP Inspector, to sanity-check your resources/prompts/tools before touching Alexa+ at all |
| Logging | stdout is fine (nothing reads it as a protocol stream) | **stderr only** — stdout is the JSON-RPC wire; anything else written there corrupts every message |

Both import their domain logic (`NetworkAdapter`, `PerimeterAdapter`,
`CorrelationEngine`) from **`aegis_domain.py`**, so the two transports are
never testing two different, drifting implementations of what counts as a
threat.

Run the stdio variant locally:
```bash
pip install "mcp[cli]"
python aegis_server_stdio.py          # or: mcp dev aegis_server_stdio.py
```

## Two dashboards, one backend

Both dashboards are generated from the exact same live data
(`get_network_security_report` + `analyze_threat_vectors` + perimeter feed)
— pick whichever fits the audience:

- **`render_aegis_dashboard`** → `aegis_dashboard.html` — dark, cinematic,
  "hacker ops" aesthetic: glowing core, red pulsing rogue node, particle
  packet-stream, camera-dolly-and-shatter containment.
- **`render_aegis_dashboard_light`** → `aegis_dashboard_light.html` —
  "Aegis Light": off-white/light-slate glassmorphism, translucent glass
  router core, light-blue glass satellites, and a **frosted-glass
  quarantine box that smoothly grows around the rogue node** instead of an
  aggressive shatter — Apple-clean, enterprise-ready, no dark mode.

## Run it locally

```bash
python3 -m venv venv
source venv/bin/activate         # Windows: venv\Scripts\activate
pip install -r requirements.txt

python aegis_server.py           # starts on http://localhost:8000/mcp
```

In a second terminal:

```bash
python test_client.py
```

You'll see the resource list, the structured prompt, the tool list, a
detected `cross_domain_threat_detected` correlation with a plain-language
narrative, a honeypot deployment, and confirmation the dashboard renders.

## The 3D dashboard

`render_aegis_dashboard` returns a self-contained `text/html` MCP-UI
resource (the spec-correct way to deliver a rich UI today — no separate
Vercel deployment or webview URL needed, which also means it works offline
and never breaks judging if a third-party host goes down):

- **Router core** — a glowing, slowly rotating icosahedron at the center.
- **Trusted devices** — teal satellites orbiting smoothly on an inner ring.
- **Flagged devices** — amber satellites on a wider ring.
- **The rogue node** — when `analyze_threat_vectors` finds a correlation, a
  pulsing red node appears on the outermost ring with a live particle
  "packet stream" flowing toward the core.
- **Isolate Threat button** — triggers a cinematic camera dolly toward the
  rogue node; the particle stream chokes off, the node dims and is pushed
  out to a sandboxed orbit, and a toast confirms containment. This mirrors
  exactly what `engage_honeypot_sandbox` / `deploy_honeypot_vlan` does on
  the backend.
- Built with vanilla Three.js (r128, loaded from cdnjs) and hand-rolled
  CSS transitions for the glassmorphic side panel — no React/Vercel
  dependency, so the whole experience ships as one file and renders
  identically wherever the MCP host displays it.

## Connecting to Alexa+

1. **Expose the server publicly** (for a hackathon demo, a tunnel is enough):
   ```bash
   ngrok http 8000
   ```
   For a production-style deployment, put `aegis_server.py` behind AWS
   Lambda + API Gateway instead.

2. **Register in the Amazon Developer Console**
   - Open the **Alexa+ MCP Toolkit** section of your (free) Amazon Developer
     Account.
   - Add a new MCP server connection with your public URL
     (`https://…ngrok.app/mcp`).
   - Alexa+ queries the endpoint and auto-registers every resource, prompt,
     and tool defined above — no manual intent/slot definitions needed.

3. **Demo script**
   - *"Alexa, is my home safe right now?"* → the assistant follows the
     `analyze_cyber_physical_threat` prompt, calls `analyze_threat_vectors`,
     finds the wardriving correlation, and calls `render_aegis_dashboard`.
     The screen shows the 3D scene with the pulsing rogue node and particle
     stream; Alexa gives a one-sentence plain-language summary.
   - *"Isolate it."* → Alexa calls `engage_honeypot_sandbox` with the MAC
     address it already has from the correlation. On screen, the same
     containment cinematic plays (camera dolly, particle stream cut off,
     node pushed to the sandboxed ring) driven by the dashboard's own
     "Isolate Threat" logic, matching the server-side state change 1:1.
   - *"What's the honeypot log show?"* → Alexa reads the
     `aegis://telemetry/honeypot/log` resource directly, no tool call needed.

## Swapping in real hardware

- `NetworkAdapter` isolates all router-facing logic — replace `_seed` /
  `list_devices` with a real router API, SNMP, or a UPnP scan.
- `PerimeterAdapter` isolates all Ring-facing logic — replace `latest()`
  with a real Ring API poll.
- `CorrelationEngine` never needs to change; it only depends on the shape
  of data both adapters already return.

## Honest limitations (worth saying to judges)

- Both adapters are simulated for demo reliability — a real Ring
  integration requires OAuth and a paid Ring Protect plan; a real router
  integration is vendor-specific. The `CorrelationEngine`'s logic is fully
  real and would work unchanged against live data.
- State resets on restart in this MVP (in-memory); a shipped version would
  persist the trust ledger and honeypot log to a real database per
  household/account.
- The dashboard's "Isolate Threat" button drives its own local animation
  state for demo purposes; in a live Alexa+ session the same button would
  `postMessage` back to the host to invoke `engage_honeypot_sandbox`
  server-side (the hook for this is already in the code).