# NeuroRisk — Voice Memory Screening on MCP + Amazon SageMaker

Voice-based early cognitive screening for neurodegenerative disease risk,
built as a self-hosted MCP server (spec 2025-11-25, Streamable HTTP) with
a simulated Alexa+ voice experience and a machine-learning risk model
deployed on Amazon SageMaker.

> **Demo screening trained on synthetic data. Not a medical diagnosis.**

---

## What it does

A user opens the web simulator, taps the microphone (or types), and the
Alexa+-style voice assistant walks them through an 8-step cognitive
screening adapted from validated brief tests:

1. Age collection
2. Three-word delayed recall (memory_intro)
3. Orientation in time (day, month, year)
4. Forgetting scheduled events (self-report)
5. Usual location of everyday objects
6. Misplacing items at home (self-report)
7. Verbal fluency — name as many animals as possible in 60 seconds
8. Delayed recall of the three words

The answers are scored and sent to an Amazon SageMaker endpoint that
returns a risk probability (0–1). The result, a risk band (low /
intermediate / high), and a plain-language message are shown immediately.
All results are stored in Amazon S3 so users can track their progress over
multiple sessions.

---

## Architecture

```
Browser (simulator.html)
        │  Streamable HTTP  (MCP 2025-11-25)
        ▼
server.py  ── FastMCP (mcp[cli])
        │
        ├── boto3 ──► Amazon SageMaker  (cognitive-risk endpoint)
        │                  XGBoost model, binary classification
        └── boto3 ──► Amazon S3  (neurorisk-hackathon-henrique-2026)
                           └── output/history/<user_id>/*.json
```

The simulator is served by the MCP server itself at `/`, so the browser
and the MCP endpoint share the same origin — no CORS configuration needed.

---

## MCP tools exposed

| Tool | Description |
|---|---|
| `start_assessment` | Returns three random words and the question script |
| `evaluate_screening` | Scores all answers, calls SageMaker, saves result to S3 |
| `get_history` | Returns the user's past results for the progress chart |
| `get_upload_link` | Generates a pre-signed S3 URL to upload a training CSV |

---

## AWS services used

| Service | Purpose |
|---|---|
| Amazon SageMaker | Hosts the XGBoost binary classification endpoint (`cognitive-risk`) |
| Amazon S3 | Stores screening history as JSON objects |

---

## Requirements

- Python 3.11+
- An AWS account with the following resources configured:
  - **SageMaker endpoint** — a binary classification model deployed and active (XGBoost recommended). The default expected name is `cognitive-risk`, but you can override it.
  - **S3 bucket** — used to store screening history per user. Create a bucket in the same region as your endpoint.
  - **IAM permissions** — your credentials must allow `sagemaker:InvokeEndpoint`, `s3:PutObject`, `s3:GetObject`, and `s3:ListObjectsV2`.
- AWS credentials configured locally via `aws configure` or environment variables.

```bash
pip install -r requirements.txt
```

---

## Configuration

Before running, set the following environment variables to point to **your own** AWS resources:

| Variable | Default | Description |
|---|---|---|
| `AWS_DEFAULT_REGION` | `us-east-2` | AWS region where your resources live |
| `AWS_ACCESS_KEY_ID` | — | Your AWS access key |
| `AWS_SECRET_ACCESS_KEY` | — | Your AWS secret key |
| `BUCKET` | `neurorisk-hackathon-henrique-2026` | Your S3 bucket name |
| `ENDPOINT_NAME` | `cognitive-risk` | Your SageMaker endpoint name |
| `TIMEZONE` | `America/Sao_Paulo` | Timezone for orientation scoring |
| `HOST` | `127.0.0.1` | Server bind address (`0.0.0.0` to expose publicly) |
| `PORT` | `8000` | Server port |

You can set them inline, or create a `.env` file and export them before running.

> AWS credentials are also picked up automatically from `~/.aws/credentials` if you have the AWS CLI configured (`aws configure`).

---

## Running

**1. Install dependencies**

```bash
pip install -r requirements.txt
```

**2. Set your AWS environment variables**

```bash
export AWS_DEFAULT_REGION=us-east-1        # your region
export AWS_ACCESS_KEY_ID=AKIA...           # your key
export AWS_SECRET_ACCESS_KEY=...           # your secret
export BUCKET=my-bucket-name               # your S3 bucket
export ENDPOINT_NAME=my-endpoint-name      # your SageMaker endpoint
```

**3. Start the server**

```bash
python server.py
```

**4. Open the simulator**

Open `http://localhost:8000` in Chrome or Edge (speech recognition requires a Chromium-based browser).

The MCP endpoint is available at `http://localhost:8000/mcp`.

---

## Testing

```bash
python test_client.py
```

Runs a full MCP handshake and calls all four tools against the running server.

---

## Hackathon track

- **Primary:** Alexa+ (self-hosted MCP server, spec 2025-11-25, Streamable HTTP)
- **Mini challenge:** AWS Builder (SageMaker + S3)

---

## License

MIT — see [LICENSE](LICENSE).