# Outbreak Watch

An Alexa+ MCP server that answers spoken questions about disease outbreaks in India, using reports since 2009 to the government's Integrated Disease Surveillance Programme (IDSP).

> "Alexa, ask Outbreak Watch what's going around in Kerala."
> *"In Kerala so far this year, the most reported outbreaks are food poisoning with 854 cases, gastroenteritis with 780 and hepatitis with 467. That's data through March 2026."*

![Simulated Alexa+ screen answering "What's going around in Kerala?"](docs/demo-kerala.png)

## Why

India publishes outbreak reports for every district, every week, but they sit in PDFs and spreadsheets that most families, school principals and community health workers never open. Outbreak Watch puts them behind a question you can ask out loud: is dengue around here, is it the season for it, and is it getting worse.

It's built on research. In our Telemedicon 2026 abstract (Kota & Dandi) we tested whether this data can be forecast at all. Error rose from a median 77% nationally to 105% at district level, and a plain linear trend was never beaten. So Outbreak Watch tells you what has been reported and when diseases usually peak, and it declines to predict where the data is too sparse.

## What you can ask

| Question | Tool |
|---|---|
| What's going around in Pune? | `whats_going_around` |
| Is there dengue in Bangalore this year? | `outbreak_summary` |
| Where was malaria worst in 2025? Which Kerala districts have the most dengue? | `top_affected` |
| When is dengue season in Tamil Nadu? | `seasonal_pattern` |
| Is cholera getting worse? Can you predict next year? | `trend_outlook` |
| Which diseases do you track? Where does this data come from? | `list_diseases`, `about_data` |

It covers 16 diseases across 764 districts and every state, 2009 to March 2026.

## How it works

```text
Alexa+ or any MCP client
        │  POST /mcp  (JSON-RPC, Streamable HTTP, protocol 2025-11-25)
        ▼
Outbreak Watch MCP server  ──  tools, resources, prompt, server instructions
        │
        ▼
IDSP outbreak aggregates (data/, 16 diseases × 764 districts × 2009-2026)
```

Design choices that matter for a voice assistant:

- **Spoken answers.** Every tool returns one to three sentences ready to be read aloud, plus structured output (with an output schema) for screens like Echo Show. Server instructions tell the model to keep it short and say how current the data is.
- **Names people actually say.** "Bangalore" finds Bengaluru Urban, "Mumbai" covers both Mumbai districts, "Gurgaon" finds Gurugram, "jaundice" maps to hepatitis, and small speech-to-text typos still match. Telangana districts include their pre-2014 Andhra Pradesh records.
- **Asks instead of guessing.** There are two Aurangabads, so the server asks which state you mean.
- **Fair comparisons.** "This year so far" is compared with the same months of last year, not with a full year.
- **Honest about limits.** `trend_outlook` applies the study's rule (at least 24 populated months in a 48-month window) and refuses district-level forecasts.
- **Data fix.** IDSP files a report under its epidemiological year, but the source export dates it by outbreak start. That puts late-December outbreaks reported in week 1 into "December" of the new year. The server detects this and counts them in January, so coverage reads March 2026 rather than December.

### MCP details

- Protocol **2025-11-25** over **Streamable HTTP**, using the official TypeScript SDK (1.32.1).
- Stateless: each POST gets a fresh server and transport, so it scales horizontally with no session store. `GET /mcp` returns 405.
- Seven read-only tools with `readOnlyHint` annotations and output schemas, two resources (`outbreak-watch://about`, `outbreak-watch://diseases`) and a `health_brief` prompt.
- DNS-rebinding protection through Host header validation, an optional bearer token (`MCP_AUTH_TOKEN`), and a `/health` endpoint.
- An [Agent Skill](skills/outbreak-watch/SKILL.md) that teaches any agent which tool to use and how to phrase answers for voice.

## Run it

Needs Node.js 20 or later.

```bash
npm install
npm run dev        # MCP server at http://127.0.0.1:3000/mcp
npm test           # 15 tests, including a real Streamable HTTP round trip
```

Try it with the MCP Inspector: run `npx @modelcontextprotocol/inspector`, choose **Streamable HTTP**, and connect to `http://127.0.0.1:3000/mcp`.

Or add it to an agent, for example Claude Code:

```bash
claude mcp add --transport http outbreak-watch http://127.0.0.1:3000/mcp
```

### Simulated Alexa+ experience

`demo/` is an Echo Show-style web app. You tap the mic and ask a question. The demo server, an MCP client, discovers Outbreak Watch's tools, lets an LLM (Groq, `openai/gpt-oss-120b`) call them, then speaks the answer and draws a card from the structured output. The MCP trace panel shows each `tools/call` as it happens.

```bash
cp .env.example .env     # add your GROQ_API_KEY
npm run dev              # terminal 1: MCP server
npm run demo             # terminal 2: http://127.0.0.1:3001
```

Speech recognition works in Chrome and Edge. The API key stays on the demo server and is never sent to the browser.

![Seasonal pattern card for dengue in Tamil Nadu](docs/demo-season.png)

### Deploying beyond localhost

```bash
HOST=0.0.0.0 ALLOWED_HOSTS=outbreak.example.com MCP_AUTH_TOKEN=change-me npm run dev
```

Put it behind HTTPS. `ALLOWED_HOSTS` keeps Host-header validation on when you bind to all interfaces.

## Data

- **Source:** outbreak reports under the Integrated Disease Surveillance Programme, Ministry of Health and Family Welfare ([IDSP](https://idsp.mohfw.gov.in/index4.php?lang=1&level=0&linkid=406&lid=3689)), compiled by [Dataful](https://dataful.in/datasets/18514).
- **Processing:** the aggregates in `data/` come from the pipeline in [idsp-disease-surveillance](https://github.com/praharshitha-ai/idsp-disease-surveillance).
- **Caveats:** these are outbreak notifications, not every case, so they understate the true burden, and reporting completeness varies by state. This is public-health information, not medical advice.

## License

Code: [MIT](LICENSE). The data comes from public government reports; see the sources above.