NetGuardian

A self-hosted MCP server that lets Alexa+ answer plain-English questions about your home network — "is my wifi struggling?", "what's using all my bandwidth?", "is anything on my network acting weird?" — using live network/OS diagnostics and an AWS Bedrock reasoning layer.

Built for the Amazon Developer Hackathon — Alexa+ track, stacked with the AWS Builder and Open Source mini challenges.

Why this exists

Most people can't self-diagnose home network problems — they just know "the wifi is bad" and have no path from that feeling to an actual fix. NetGuardian gives Alexa+ real diagnostic data (ping latency, bandwidth per interface, connected devices, interface error counters) and lets an LLM turn that into one clear, spoken sentence with an actual next step.

Related MCP server: connectivity-diagnostics

Architecture

Alexa+  --(MCP, Streamable HTTP, spec 2025-11-25)-->  NetGuardian server
                                                              |
                                            network_tools.py (psutil, ping, ARP)
                                                              |
                                            reasoning.py
                                              1. Gemini API         (default, free, no card)
                                              2. Local Ollama LLM   (offline backup, free)
                                              3. AWS Bedrock        (optional upgrade path)
                                              4. Rule-based fallback (always available)

• Transport: MCP Streamable HTTP per spec 2025-11-25 — single /mcp endpoint, session tracked via Mcp-Session-Id header.

• Diagnostics: network_tools.py — gateway/internet ping, per-interface bandwidth sampling, ARP-table device listing, interface error/drop counters.

• Reasoning: reasoning.py tries the Gemini API first (free tier, no credit card required — just a Google account), then falls back to a local Ollama LLM if Gemini is unavailable, then an optional AWS Bedrock call if credentials are configured (bedrock_client.py), then a deterministic rule-based summary as a last resort. The tool response always reports which tier answered via reasoning_source, so it's clear during a demo — or to anyone reading the code — exactly what produced the diagnosis.

Why Gemini is the default, not Bedrock

This project runs entirely free with zero AWS spend: get a free API key at Google AI Studio (no credit card needed) and NetGuardian gets real cloud LLM reasoning with no local hardware strain. Bedrock (bedrock_client.py) is left in as a documented, working upgrade path — set AWS credentials and it activates automatically — but it is intentionally not required to run or demo NetGuardian.

Running with Gemini (recommended, free, no card)

1. Go to aistudio.google.com, sign in, click Get API key → Create API key → Create project (keep it separate from any other projects you have).

2. Set the key as an environment variable before running the server:

   export GEMINI_API_KEY=your_key_here   # macOS/Linux
   set GEMINI_API_KEY=your_key_here      # Windows cmd, same terminal session

3. Run python server.py. reasoning_source in tool responses will read "gemini" when this is working.

Running with Ollama (offline backup, also free)

# Install Ollama: https://ollama.com/download
ollama pull llama3.2:1b
ollama serve   # usually starts automatically after install

NetGuardian falls back to this automatically if no GEMINI_API_KEY is set or the Gemini call fails, detecting Ollama at http://127.0.0.1:11434 (override with the OLLAMA_HOST / OLLAMA_MODEL env vars). Note: local models are noticeably slower and lower-quality than Gemini on modest hardware (8GB RAM, no dedicated GPU).

Tools exposed

Tool orchestration

diagnose_network_issue doesn't run every diagnostic every time. It always collects a fast baseline (connectivity + bandwidth), then asks Gemini which extra checks — interface health, connected devices — are actually relevant to the specific question, and only runs those. The response includes extra_tools_used so this decision is visible, not hidden. If no Gemini key is configured, it safely defaults to running everything rather than skipping diagnostics it can't intelligently choose between.

Session history and pattern detection

Every diagnosis is recorded to a local SQLite database (history.py, no new dependency, zero cost). Future calls fold in a summary of recent patterns — "the router failed to respond in 2 of the last 3 checks" — so NetGuardian can speak to trends over time instead of treating every question in total isolation.

Setup

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # fill in AWS credentials for the Bedrock layer

Run locally

python server.py

The server binds to 0.0.0.0:8811 by default (override with NETGUARDIAN_HOST / NETGUARDIAN_PORT) and serves the MCP endpoint at /mcp.

Test it directly:

curl -i -X POST http://127.0.0.1:8811/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"test","version":"0.1"}}}'

Grab the Mcp-Session-Id header from the response and pass it as Mcp-Session-Id on subsequent tools/list / tools/call requests.

Deploying for the demo (AWS EC2) — optional

This step is only needed if you want a publicly reachable endpoint for live Alexa+ integration testing, or if you choose to enable the Bedrock upgrade path. NetGuardian runs and demos fine locally with Ollama alone.

1. Launch a small EC2 instance (free-tier eligible, e.g. t3.micro, Amazon Linux or Ubuntu).

2. Attach an IAM role with bedrock:InvokeModel permission — don't hardcode AWS keys on the instance if you can avoid it.

3. Open the security group to allow inbound traffic on your chosen port from wherever you'll demo from.

4. Clone this repo, pip install -r requirements.txt, and run python server.py.

5. Point your Alexa+ Agent Skill / MCP client config at http://<ec2-public-ip>:8811/mcp.

This is also the AWS Builder mini-challenge integration: EC2 hosts the server, Bedrock powers the reasoning tool — both load-bearing, not decorative.

Safety notes

• restart_network_service only accepts a small whitelist of services and defaults to a dry run. It will not touch anything outside that whitelist.

• The Bedrock call has an explicit fallback path so a missing/expired AWS credential degrades the diagnosis quality — it does not crash the tool.

License

MIT — see LICENSE.