MRI Knee Analyzer

A local, single-patient MRI knee analysis tool that loads DICOM scans and runs AI-assisted detection for ACL tears, PCL assessment, meniscus tears, and general abnormalities — with GradCAM attention overlays, clinical grading, and treatment pathway guidance.

Built on Stanford's MRNet architecture.

---

Getting Started

1. Add your DICOM files

Place your knee MRI .dcm files inside the assets/ folder:

mri-scanner/
└── assets/
    ├── scan001.dcm
    ├── scan002.dcm
    └── ...

The app auto-discovers all series in the folder — you can have multiple sequences (sagittal, coronal, axial) mixed together and it will separate them for you.

Your DICOM files stay entirely on your machine. Nothing is uploaded anywhere.

2. Set up the environment

python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt

3. Run the app

streamlit run app.py

Open http://localhost:8501 in your browser.

---

Features

Section	What it shows
Slice Viewer	Scroll through all MRI slices with a GradCAM attention overlay toggle
Detection Scores	ACL tear / Meniscus tear / Abnormality probability (0–100%)
ACL Health	Grade 0–3 classification (Normal → Sprain → Partial → Complete tear)
PCL Health	Grade 0–3 PCL assessment derived from abnormality signal
Meniscus–ACL Interaction	Flags the ACL-Meniscus Triad when both are elevated — warns if meniscus injury is skewing the ACL reading
Treatment Pathway	Conservative vs surgical guidance with timelines for ACL, PCL, and meniscus

GradCAM Heatmaps

Toggle the heatmap in the slice viewer to see which pixels the model focused on when generating each score. Select the condition (ACL / Meniscus / Abnormality) to switch the attention map.

---

Getting Calibrated ACL Weights (Optional but Recommended)

By default the app runs with ImageNet-pretrained features. GradCAM attention is still meaningful but probability scores are uncalibrated.

For calibrated ACL scores, obtain the MRNet pre-trained weights from Stanford:

1. Visit the MRNet dataset page: https://stanford.redivis.com/datasets/4a2c-4cpkzrn2c
2. Register and download, or email mrnet-competition@cs.stanford.edu to request acl.pth
3. Place the file at models/mrnet_acl.pth
4. Restart the app — the sidebar will confirm the model is calibrated

You only need mrnet_acl.pth for calibrated ACL analysis. Meniscus and abnormality fall back gracefully.

Train your own ACL model

If you download the full MRNet dataset, you can train locally:

# expects data/train/sagittal/*.npy and data/train-acl.csv
python scripts/train_acl.py --data data/ --view sagittal --epochs 50

Weights are saved automatically to models/mrnet_acl.pth as training improves.

---

MCP Server (for LLM integration)

The repo includes an MCP server that exposes the knee analysis as tools any LLM can call — structured JSON data plus base64 slice images with GradCAM overlays.

Add to .claude/settings.local.json (or your MCP client config):

{
  "mcpServers": {
    "knee-analyzer": {
      "command": "/path/to/.venv/bin/python3",
      "args": ["/path/to/mri-scanner/mcp_server.py"],
      "cwd": "/path/to/mri-scanner"
    }
  }
}

Available tools:

Tool	Description
list_series	List all DICOM series with UIDs and slice counts
analyze_knee	Full analysis JSON: scores, grades, interaction, treatment pathway
get_slice	Base64 PNG of any slice, optionally with GradCAM overlay

The server launches automatically — no need to run it manually.

---

Project Structure

mri-scanner/
├── assets/                  ← Put your .dcm files here
├── models/                  ← Place mrnet_acl.pth here when available
├── src/
│   ├── dicom_loader.py      DICOM I/O, series discovery, preprocessing
│   ├── mrnet_model.py       MRNet architecture + inference
│   ├── gradcam.py           GradCAM heatmap computation
│   ├── acl_grader.py        ACL/PCL/meniscus grading + healability rules
│   └── visualizer.py        Slice rendering, overlay, charts
├── scripts/
│   ├── train_acl.py         ACL model training script
│   └── download_weights.py  Weight status checker + download instructions
├── app.py                   Streamlit app
├── mcp_server.py            MCP server for LLM integration
└── requirements.txt

---

Important Disclaimer

This tool is for research and educational purposes only. It is not a medical device and has not been validated for clinical use. All findings must be reviewed by a licensed radiologist or orthopaedic surgeon before any clinical decisions are made.

---

Credits

• MRNet — Bien et al., Stanford ML Group, PLOS Medicine 2018
• MONAI ecosystem for medical imaging patterns
• Streamlit for the UI

---

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details. Copyright 2026 Sunny Singh.