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. Local Ollama LLM  (default, free, no AWS)
                                              2. AWS Bedrock       (optional upgrade path)
                                              3. 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 a local Ollama LLM first (free, offline, no AWS account needed), 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 Ollama is the default, not Bedrock

This project runs entirely free with zero AWS spend: install Ollama, pull a small model, and NetGuardian gets real LLM reasoning with no AWS account or payment method involved. 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 Ollama (recommended, free)

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

NetGuardian will detect it automatically at http://localhost:11434 (override with the OLLAMA_HOST / OLLAMA_MODEL env vars).

Tools exposed

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.