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

Related MCP server: NetGuardian

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:

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:

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

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:

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):

   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).