# Just Us?

**"Alexa, is it just us, or the whole area?"**

**Live demo:** https://just-us-zeta-eight.vercel.app · MCP endpoint: `https://just-us-zeta-eight.vercel.app/mcp`

When the internet, power or water stops, every home asks the same question. Is it my Wi-Fi, my router, my provider, or the whole neighbourhood? And when will it come back?

Just Us? is a self-hosted **MCP server for Alexa+** (MCP spec 2025-11-25, Streamable HTTP) written in Python. It answers that question in two ways:

1. **Home check (works from day one, with one home).** The server runs on a computer inside the home, so it runs **real tests on the real network**: router reachable, provider reachable, DNS answering, speed against your plan, and devices on the Wi-Fi. It says exactly which part is at fault.
2. **Neighbourhood check (gets better as homes join).** Homes report internet, power and water problems by voice, or from a small web page on any phone. Just Us? says how many homes in your area report the same thing, and estimates when it'll be back from past outages there.

It also watches your connection in the background, logs every outage, sends a phone alert, and **writes a complaint to your provider with 7 days of evidence**.

It ships with a **web app built for Hyderabad**:

- **Talk to it.** A simulated Alexa+ assistant: you speak (browser speech recognition, `en-IN`), it answers out loud, and every answer comes from a **real MCP `tools/call`** to the server. Each reply shows the JSON-RPC request and response. It understands everyday phrasing, including "current poyindi" and "bijli chali gayi".
- **A live map of 55 Hyderabad localities** in 2D or 3D. In 2D, pulsing rings mark outages people are reporting right now. In 3D, column height shows the hours each locality lost in the last 30 days, and live outages rise as coloured beacons. Click any locality for its live status, outage history and usual restore time.
- **Real data, located:** tap ⌖ (or say "use my location") and the browser's location picks your locality. Only the locality name is stored, never coordinates. If location is blocked, the home connection's IP gives a city-level hint. **Live weather for all 55 localities** (Open-Meteo, refreshed every 10 minutes) drives a real storm-risk warning (`outage_risk`: "Is a power cut likely today?"), a weather layer on the map, and a note when a storm is the likely cause of a cut. A **demo-homes switch** hides every simulated home, so the map and charts show real reports only.
- **Analysis:** outages and hours lost by locality, time of day, day by day (storm days stand out) and internet reliability by provider, with written insights. Filter it to one locality.

```
"Alexa, why is the internet slow?"
→ "Your Wi-Fi and router are fine. ACT Fibernet is giving you 8 Mbps on a 100 Mbps plan, measured at 9:40 PM."

"Alexa, power's gone."
→ "Noted. You're not alone: 8 homes in Kondapur report power cuts since 6:52 PM. It's area-wide, not your home.
   Past power cuts here lasted about 43 minutes, so it may be back around 7:35 PM."

"Alexa, write my complaint to the provider."
→ "I've written your complaint to ACT Fibernet with 7 days of evidence: 4 outages and an average speed of 63 Mbps."
```

## How it works

```mermaid
flowchart LR
    U["User speaks to Alexa+"] --> A["Alexa+<br/>picks a tool"]
    A -->|"MCP 2025-11-25<br/>Streamable HTTP"| T["Cloudflare tunnel<br/>(public HTTPS)"]
    T --> S["Just Us? server<br/>(Python, on a home computer)"]
    S --> DB[("SQLite<br/>checks · speed · outages · reports")]
    M["Background monitor<br/>every 60 s"] --> DB
    M -->|"router · provider · DNS · speed · devices"| N["Home network"]
    M -->|"outage alert"| P["ntfy phone push"]
    W["Neighbour web page<br/>(any phone)"] --> S
```

- **Tools answer from SQLite in milliseconds.** Slow work (speed tests, device scans) runs in the background, because Alexa+ expects replies within 500 ms. The live diagnosis takes about 0.4 s.
- **The background monitor** checks the router, the internet and DNS every 60 seconds (every 15 seconds during an outage), runs a speed test every 30 minutes and scans for devices every 10 minutes. After 2 failed checks where the router works but the internet doesn't, it opens a **provider outage**, adds an internet report for your area and pushes a phone alert. It closes the outage when the connection comes back.
- **The web app** (`/`) runs on the same server. Anyone can report with one tap from a phone, with no app or sign-up. The map and analysis come from `/api/city`, and the assistant calls `/mcp` directly from the browser.
- **Areas** are matched to 55 Hyderabad localities, including spoken variants such as "hitech city" or "KPHB". Locality centres come from OpenStreetMap. Answers include the right helplines (TGSPDCL 1912 for power, HMWSSB 155313 for water).

### How the diagnosis decides

| Test | How | If it fails |
|---|---|---|
| Router | ICMP ping, plus TCP 80/443 as a backup (many routers block TCP) | "The problem is inside your home." |
| Provider | TCP connections to 1.1.1.1, 8.8.8.8 and 9.9.9.9 | "Your router is fine, but your provider is down." Plus neighbours on the same provider. |
| DNS | A real DNS query to the DNS servers your computer uses, and to 1.1.1.1 | "Your provider's DNS isn't answering. Switch to 1.1.1.1." |
| Stability | Packet loss and delay | "Your connection is unstable: 12% packet loss." |
| Speed | Cloudflare's free speed endpoint, compared with your plan | "You get 8 Mbps on a 100 Mbps plan." |

## The 13 tools

| Group | Tool | Example phrase |
|---|---|---|
| Home check | `diagnose_internet` | "Why is the internet slow?" / "Is it the Wi-Fi or the provider?" |
| | `run_speed_test` | "How fast is my internet?" |
| | `whos_on_my_wifi` | "Who's on my Wi-Fi?" |
| | `internet_report` | "How was the internet this week?" / "What happened last night?" |
| | `draft_isp_complaint` | "Write my complaint to the provider." |
| Neighbourhood | `report_problem` | "Power's gone." / "No water today." |
| | `is_it_just_us` | "Is it just us?" / "Do the neighbours have power?" |
| | `area_status` | "Any outages nearby?" |
| | `mark_restored` | "Power's back." |
| | `outage_history` | "When does the power usually come back?" |
| | `outage_risk` | "Is a power cut likely today?" / "Is a storm coming?" (live Open-Meteo weather) |
| Setup and summary | `set_home_profile` | "My area is Kondapur. My plan is 100 Mbps with ACT." Also takes latitude/longitude to detect the locality. |
| | `whats_going_on` | "Anything wrong at home?" |

## Run it

You need Python 3.10 or newer. Every dependency is free and needs no API keys or accounts.

```bash
python -m venv .venv
.venv\Scripts\activate          # Windows  (macOS/Linux: source .venv/bin/activate)
pip install -e ".[dev]"          # add ,cloud for Postgres support: ".[dev,cloud]"
```

Start the server on a computer that's on your home network:

```bash
python -m justus.server --port 8000
```

- MCP endpoint: `http://localhost:8000/mcp`
- Web app (voice assistant, Hyderabad map, analysis, report page): `http://localhost:8000/`

For voice, open the web app in Chrome or Edge and allow the microphone.

Try every tool through a real MCP client:

```bash
python scripts/smoke_test.py http://localhost:8000/mcp
```

Or open it in the [MCP Inspector](https://github.com/modelcontextprotocol/inspector) (transport: Streamable HTTP, URL `http://localhost:8000/mcp`):

```bash
npx @modelcontextprotocol/inspector
```

### Give it a public URL for Alexa+

Alexa+ needs an HTTPS URL. A free Cloudflare quick tunnel works with no account:

```bash
cloudflared tunnel --url http://localhost:8000
```

Then restart the server with the tunnel's hostname, so it accepts requests addressed to it (DNS-rebinding protection rejects unknown hosts):

```bash
python -m justus.server --port 8000 --public-host your-name.trycloudflare.com
```

### Always-on deployment (Vercel + Postgres)

The website and MCP server can also run on Vercel, so the link works when your laptop is off. They share one Postgres database (for example Neon's free tier) with the home computer:

```
Alexa+ / browser ──> Vercel (always on): website + /mcp ──┐
                                                         ├──> Postgres (Neon)
Home computer: monitor + live network tests ─────────────┘
```

- Neighbourhood, weather, history and location tools work fully in the cloud.
- Home-network tools (diagnose, speed, Wi-Fi devices) answer from the latest results the home computer saved. When it has been silent for more than 5 minutes, Just Us says so: "Your home computer hasn't checked in since 7:40 PM", which itself often means the power or internet is out.

Deploy:

```bash
vercel link
vercel env add DATABASE_URL production      # or add Neon from the Vercel Marketplace, which sets it for you
vercel deploy --prod
```

Load the demo homes into the cloud database and point the home computer at it:

```bash
set DATABASE_URL=postgresql://...            # PowerShell: $env:DATABASE_URL = "postgresql://..."
python -m justus.seed --city
python -m justus.server --port 8000          # the home computer now writes its checks to the shared database
```

### Connect to Alexa+

This uses the Alexa+ MCP Toolkit (`alexa-ai` CLI, Preview) and an Amazon Developer account:

```bash
alexa-ai configure
alexa-ai new mcp --name "Just Us" --locale en-US --mcp-server-url "https://your-name.trycloudflare.com/mcp"
alexa-ai deploy
```

Then test it in the Alexa+ Web Simulator. Run `alexa-ai deploy` again whenever the tools change.

### Phone alerts (optional)

Install the free [ntfy](https://ntfy.sh) app, subscribe to a topic name only you know, then tell Just Us: *"set my alert topic to justus-charan-7731"*. You can also set `JUSTUS_NTFY_TOPIC`.

## Demo data

The neighbourhood half needs other homes. For the demo we add **clearly labelled simulated homes** ("Simulated home 4 (Kondapur)", stored with `simulated=1`). The web app says how many homes are simulated.

```bash
python -m justus.seed --city                             # ~650 simulated homes across 55 Hyderabad localities + 30 days of outages
python -m justus.seed --area Kondapur                    # or just one area: 25 simulated homes + 30 days of past outages
python -m justus.seed --area Kondapur --sample-history   # also 7 days of sample monitoring for your home
python -m justus.demo outage power --homes 8 --over 40   # 8 simulated homes in your area report a power cut over 40 s
python -m justus.demo outage water --area Madhapur --homes 6   # any locality
python -m justus.demo restore power                      # they report it's back
python -m justus.seed --reset                            # remove all simulated data
```

Answers built from sample history say so ("this includes sample demo data"), and the drafted complaint carries the same note.

## Known limits

- **When the internet is completely down, the Echo can't reach Alexa+ either.** Then you ask through the Alexa app on your phone over mobile data. Meanwhile the computer keeps testing and logs the outage, so *"what happened to the internet last night?"* has the full story afterwards. Power cuts work the same way, or through an inverter powering the router and Echo, which many Indian homes have.
- Tests run from the computer hosting the server. A wired computer tests the router and provider; a single phone with weak Wi-Fi can still be slow while the diagnosis says all is fine.
- Device detection reads the ARP table, so devices that are asleep may not appear.
- There's no public live feed of power or water outages for Hyderabad (TGSPDCL and HMWSSB don't publish one), so outage data comes from homes reporting. Weather and your own network tests are live and real.
- The neighbourhood half depends on other homes reporting. The web page means a home without an Echo can still take part.

## Privacy

Everything is stored locally in `data/justus.db` on the home computer. Neighbour reports contain only an area name, an optional label and an optional provider. The public tunnel URL exposes the tools, which include your device list, so stop the tunnel when you're not using it. Before real deployment, add Alexa+ account linking (OAuth 2.1 with PKCE).

## Tests

```bash
pytest
```

The tests fake the network, so they run anywhere. They cover the diagnosis verdicts, neighbour matching by area and provider, outage detection by the monitor, the complaint, the web API and Host-header protection.

## Project layout

```
justus/
  server.py        MCP server: 13 tools, web app routes, entry point
  tools.py         what each tool does and says
  netcheck.py      real network tests (router, internet, DNS, speed, devices, provider)
  monitor.py       background checker, outage detection, alerts
  neighbourhood.py area reports, "is it just us", typical outage length
  regions.py       55 Hyderabad localities (hyderabad_regions.json) and fuzzy matching
  analytics.py     city-wide analysis behind the map and charts
  weather.py       live weather and storm risk for every locality (Open-Meteo)
  db.py            SQLite schema and helpers
  alerts.py        ntfy phone push
  speak.py         times and durations in spoken English
  seed.py, demo.py simulated homes for the demo
  web/            web app: voice assistant (MCP client), 2D/3D map (MapLibre), charts (Chart.js), report page
scripts/smoke_test.py  call every tool over MCP
tests/                 pytest suite
```

## License

MIT. See [LICENSE](LICENSE).