# CPAP MCP Usage Guide

This document provides detailed examples of how to interact with the CPAP MCP server through AI assistants like Claude.

## Table of Contents

- [Getting Started](#getting-started)
- [Basic Workflow](#basic-workflow)
- [Example Sessions](#example-sessions)
- [Common Use Cases](#common-use-cases)
- [Tips for Best Results](#tips-for-best-results)

## Getting Started

### Preparing Your Data

Before analyzing data, you need to create a ZIP archive of your CPAP SD card data:

**Using the helper script:**
```bash
python examples/create_archive.py /path/to/sdcard --encode
```

This creates `cpap_data.zip.b64` with base64-encoded content ready for upload.

**Manual creation:**
```bash
# Create ZIP archive
cd /Volumes/RESMED  # Your SD card mount point
zip -r cpap_data.zip DATALOG/ STR.edf Identification.tgt SETTINGS/

# Encode to base64
base64 cpap_data.zip > cpap_data.zip.b64
```

### Typical SD Card Structure

```
DATALOG/
  20240101/
    20240101_220030_BRP.edf
    20240101_220030_EVE.edf
    20240101_220030_PLD.edf
    20240101_220030_SAD.edf
  20240102/
    ...
SETTINGS/
  STI_20240101_000000.tgt
STR.edf
Identification.tgt
```

### Key Files to Include

- `STR.edf` - Session summary file (required)
- `DATALOG/*/` - Session data files for detailed analysis
- `Identification.tgt` - Device identification (optional)
- `SETTINGS/*.tgt` - Settings files (optional)

## Basic Workflow

### Step 1: Upload Archive

**User**: "I want to analyze my CPAP data. I have a ZIP archive from my SD card."

**AI**: "I'll help you analyze your CPAP data! Please provide the base64-encoded ZIP archive containing your SD card data."

*User provides base64 encoded ZIP content*

*AI uses the `upload_archive` tool to extract and process the data*

### Step 2: Get Overview

**User**: "What data do you have?"

*AI uses `get_devices` and `get_sessions`:*

"I found your ResMed AirSense 10 device (Serial: 1234567890).

You have 30 nights of therapy data from November 1-30, 2024:
- Total usage: 204 hours
- Average per night: 6.8 hours
- Compliance rate: 93% (28/30 nights ≥ 4 hours)"

### Step 3: Analyze

**User**: "Analyze my therapy effectiveness."

*AI uses `analyze_therapy_effectiveness`:*

"**Therapy Effectiveness Analysis (30 days)**

✅ **Compliance: Excellent**
- 204 total hours (avg 6.8 hours/night)
- 28/30 nights with 4+ hours (93%)

✅ **AHI Control: Excellent**
- Average AHI: 2.3 events/hour
- Target is < 5 (you're well within range)
- Only 2 nights with AHI > 5

✅ **Leak Performance: Good**
- Average 95th percentile leak: 18 L/min
- Target is < 24 L/min
- 2 nights had high leak rates

**Recommendations:**
1. Your therapy is working very well overall
2. Continue with current pressure settings
3. High leak nights were Nov 15 and Nov 22 - check mask fit if this persists"

## Example Sessions

### Full Analysis Session

#### Investigating Specific Sessions

**User**: "Show me details about November 15th when I had high leaks."

*AI uses `get_sessions` with date filter, then `get_session_details`:*

"**November 15, 2024 Session**

Duration: 7.2 hours (10:15 PM - 5:28 AM)

Therapy Metrics:
- AHI: 4.8 (good)
- Obstructive apneas: 12
- Hypopneas: 23

Pressure:
- Median: 9.2 cmH2O
- 95th percentile: 11.4 cmH2O
- Range: 7.0 - 12.8 cmH2O

Leaks:
- Median: 22 L/min
- 95th percentile: 38 L/min ⚠️ (high)
- This suggests mask fit issues

The high leak likely started around 2:30 AM based on the event timeline."

#### Event Timeline

**User**: "Show me the events from that night."

*AI uses `get_session_events`:*

"**Events for November 15, 2024**

10:15 PM - Mask On
11:42 PM - Obstructive Apnea (18 seconds)
12:03 AM - Hypopnea (35 seconds)
...
2:28 AM - Large Leak Started
...
5:28 AM - Mask Off

Total Events: 35 apneas/hypopneas (4.8/hour)
Note: Most events occurred before 2 AM. The leak started at 2:28 AM but didn't significantly impact therapy effectiveness."

### Comparing Time Periods

**User**: "Compare my therapy from the first half of November to the second half."

*AI uses `get_sessions` with date filters and `get_summary_statistics`:*

"**Comparison: Nov 1-15 vs Nov 16-30**

First Half (Nov 1-15):
- Average AHI: 3.2
- Average hours: 6.5
- Average leak: 20 L/min

Second Half (Nov 16-30):
- Average AHI: 1.4 ✅ (improved!)
- Average hours: 7.1 ✅ (improved!)
- Average leak: 16 L/min ✅ (improved!)

Your therapy improved significantly in the second half of November!
This could be due to:
- Better mask fit
- Adapting to the therapy
- Changes in sleeping position"

### Settings Review

**User**: "What are my current CPAP settings?"

*AI uses `get_device_settings`:*

"**Current Device Settings**

Therapy Mode: AutoSet (APAP)
- Minimum pressure: 7.0 cmH2O
- Maximum pressure: 15.0 cmH2O

EPR (Expiratory Pressure Relief):
- Enabled: Yes
- Level: 3 (maximum comfort)
- Type: Full-time

Ramp:
- Enabled: Yes
- Start pressure: 6.0 cmH2O
- Duration: 15 minutes

Comfort Features:
- Smart Start: Enabled
- Auto Stop: Enabled
- Climate Control: Auto
- Humidifier Level: 4

Mask Type: Full Face
Response: Standard"

### Waveform Analysis

**User**: "Show me the pressure changes during my session on November 20th."

*AI uses `get_session_pressure_data` with sampling:*

"**Pressure Waveform - November 20, 2024**
(Showing 1000 sampled points from 28,800 total)

The pressure data shows:
- Started at 6.0 cmH2O (ramp)
- Gradually increased to treatment range
- Maintained between 8-11 cmH2O for most of the night
- Brief increases to 13-14 cmH2O during 3-5 AM (responding to events)
- Stable at 9-10 cmH2O for the last 2 hours

This indicates your AutoSet is working correctly, adjusting pressure in response to your breathing patterns."

### Monthly Summary Report

**User**: "Give me a monthly summary report."

*AI uses `get_summary_statistics`:*

"**November 2024 - Monthly CPAP Report**

📊 **Usage Summary**
- Total nights used: 30/30 (100%)
- Total hours: 204
- Average per night: 6.8 hours
- Nights with 4+ hours: 28 (93% compliance)

🫁 **Therapy Effectiveness**
- Average AHI: 2.3 events/hour (Excellent)
- Nights with AHI < 5: 28 (93%)
- Nights with AHI 5-15: 2 (7%)
- Nights with AHI > 15: 0

💨 **Leak Performance**
- Average 95th percentile: 18 L/min (Good)
- Nights with acceptable leak: 28 (93%)
- Nights with high leak: 2

🎯 **Overall Assessment**
Your CPAP therapy is highly effective. You're consistently using the device for adequate hours, achieving excellent AHI control, and maintaining good mask seal. Continue with current settings.

**Compliance Status**: ✅ EXCELLENT
- Meeting insurance requirements (4+ hours for 70% of nights)
- Achieving clinical treatment goals (AHI < 5)"

### Settings Adjustment Proposals

**User**: "My AHI has been around 8 for the past week. Should I increase my pressure?"

*AI uses `analyze_therapy_effectiveness` to confirm, then `propose_pressure_adjustment`:*

"**Pressure Adjustment Proposal**

Based on your recent AHI of 8.2 events/hour (above the target of <5), I'm proposing a pressure adjustment.

**Proposed Changes:**

1. Maximum Pressure: 15.0 → 17.0 cmH2O
   - Reason: Increase pressure ceiling to better control apnea events
   - Severity: Moderate
   - Safety: ✅ Within clinical limits (4-20 cmH2O)

**Expected Outcomes:**
- Improved AHI control (target < 5)
- Better therapy effectiveness
- Reduced apnea/hypopnea events

**Safety Assessment:**
- All proposed changes are within safe clinical limits
- ⚠️ This proposal requires clinical review before implementation

**Important:** This is a proposal only. Do NOT adjust your device settings without consulting your sleep medicine provider or respiratory therapist."

## Common Use Cases

### Tracking Compliance

**Questions to ask:**
- "Am I meeting the 4-hour requirement?"
- "What's my compliance rate for the last 30 days?"
- "Show me nights where I used the CPAP for less than 4 hours"

### Investigating Poor Nights

**Questions to ask:**
- "Show me my worst nights by AHI"
- "What happened on [specific date]?"
- "Show me detailed events for [session ID]"

### Monitoring Progress

**Questions to ask:**
- "Compare this month to last month"
- "Is my AHI improving over time?"
- "Show me my 30-day trend"

### Troubleshooting Issues

**Questions to ask:**
- "Why am I having high leak rates?"
- "What events am I having most frequently?"
- "Are my pressure settings appropriate?"

### Preparing for Doctor Visits

**Questions to ask:**
- "Generate a monthly summary report"
- "What should I discuss with my sleep doctor?"
- "Export all my data for review"

## Tips for Best Results

### 1. Upload Complete Data

Include `STR.edf` and all `DATALOG` files for the period you want to analyze. The more complete your data, the better the analysis.

### 2. Ask Specific Questions

Instead of "analyze my data", try:
- "Show me nights with AHI > 10"
- "What's my compliance for last week?"
- "Compare my first week to my most recent week"

### 3. Use Date Ranges

Specify time periods for focused analysis:
- "Show me sessions from January 1-15"
- "Compare last week to this week"
- "What's my average AHI for the past month?"

### 4. Request Comparisons

Ask for trends, patterns, or comparisons:
- "How has my AHI changed over time?"
- "Compare weekdays to weekends"
- "Show me my best and worst nights"

### 5. Investigate Outliers

If you see a bad night, ask for details:
- "What events occurred on that night?"
- "Show me the pressure waveform"
- "When did the leak start?"

### 6. Regular Reviews

Upload data monthly and track your progress over time. This helps you:
- Identify trends
- Catch issues early
- Document improvements for insurance/doctors
- Understand what works for you

### 7. Understand Limitations

Remember:
- The AI provides analysis, not medical advice
- Always consult your healthcare provider for therapy changes
- Settings proposals are suggestions only, not prescriptions
- Data quality depends on proper device use and SD card health

## Understanding the Output

### Key Metrics

- **AHI** (Apnea-Hypopnea Index): Events per hour
  - <5: Excellent
  - 5-15: Mild sleep apnea
  - 15-30: Moderate sleep apnea
  - >30: Severe sleep apnea

- **Leak Rate**: Air leakage in L/min
  - <24 L/min: Acceptable
  - >24 L/min: Excessive (check mask fit)

- **Compliance**: 4+ hours of use
  - 70% of nights: Insurance requirement
  - 93%+: Excellent compliance

- **Pressure**: Delivered pressure in cmH2O
  - Typical range: 4-20 cmH2O
  - AutoSet adjusts within min/max range

### Event Types

- **OA**: Obstructive Apnea - airway blocked
- **CA**: Central Apnea - brain doesn't signal breathing
- **H**: Hypopnea - shallow breathing
- **FL**: Flow Limitation - partial obstruction
- **RE**: RERA - breathing effort arousal
- **VS**: Vibratory Snore - snoring events

## Data Privacy

- All uploaded files are stored in a temporary directory
- Files are only kept in memory during the session
- Use `clear_uploaded_files` to explicitly remove data
- No data is sent to external services
- All analysis happens locally

## Getting Help

If you encounter issues:
- Review the [README.md](README.md) for tool reference
- Check [INSTALL.md](INSTALL.md) for setup troubleshooting
- Visit [DEVELOPMENT.md](DEVELOPMENT.md) for technical details
- Open an issue on GitHub for bugs or questions

---

**Medical Disclaimer**: This tool is for informational purposes only and should not replace medical advice. Always consult with your healthcare provider or sleep specialist for therapy adjustments and medical decisions.
