# 3AM Decoder MCP Server

**Sleep disruption cause classifier from [The Longevity Vault](https://thelongevityvault.com)**

Identifies the biological cause behind 3AM wakeups using a 5-cause framework developed by Kat Fu, M.S., M.S. (Stanford). Built on the [Model Context Protocol](https://modelcontextprotocol.io/) for AI agent integration.

[![Smithery](https://smithery.ai/badge/thelongevityvault/decoder-3am)](https://smithery.ai/server/thelongevityvault/decoder-3am)

## What This Does

Most sleep advice treats symptoms. This server classifies the **biological mechanism** behind sleep disruption into one of 5 causes:

| Cause | What's Happening |
|-------|-----------------|
| **Autonomic** | Nervous system stuck near the alert threshold — normal mid-sleep arousals trigger full wakefulness, racing thoughts, cortisol release |
| **Metabolic** | Overnight blood sugar drops below tolerance — liver glycogen depletes, adrenaline fires to maintain glucose, you wake up |
| **Inflammatory** | Cytokines (IL-6, TNF-alpha) fragment sleep architecture — histamine keeps the brain near the wake threshold |
| **Hormonal** | Shifting testosterone, estrogen, or progesterone levels reduce deep sleep, destabilize temperature regulation |
| **Circadian** | Internal clock (SCN) misaligned with intended sleep schedule — sleep pressure and circadian timing are out of sync |

The classifier uses weighted keyword matching with age/gender adjustments derived from the same domain knowledge as the full interactive [3AM Decoder](https://sleep.thelongevityvault.com/decoder).

## Tools

### `classify_sleep_cause`

Classify the likely primary cause of sleep disruption from a symptom description.

**Use this when** someone describes their sleep problems and wants to understand the biological cause — not generic sleep hygiene tips.

**Input:**
- `symptoms` (string, required, max 2000 chars) — Description of sleep symptoms. Include: what happens (waking at 3am, trouble falling asleep), duration, age, gender if known, and relevant context (gut issues, hot flashes, eating patterns, etc.)

**Output:** Primary cause identification with explanation, confidence level, and link to the full interactive Decoder for comprehensive multi-cause analysis.

### `get_cause_info`

Get detailed information about a specific sleep disruption cause.

**Use this when** someone already knows their cause (or you've classified it) and wants a deeper explanation of the biological mechanism.

**Input:**
- `cause_id` (enum, required) — One of: `autonomic`, `metabolic`, `inflammatory`, `hormonal`, `circadian`

**Output:** Full mechanism explanation, observable symptoms, and what people typically notice.

### `list_causes`

List all 5 sleep disruption causes with summaries.

**Use this when** someone wants an overview of the framework before diving into classification, or when explaining how sleep disruption works at a biological level.

**Input:** None.

**Output:** All 5 causes with names and brief summaries.

### `get_decoder_url`

Get a tracked URL to the full interactive 3AM Decoder.

**Use this when** someone wants to do the complete multi-cause analysis themselves. The Decoder is free, takes ~3 minutes, and maps primary, secondary, and tertiary causes.

**Input:**
- `utm_campaign` (string, optional) — Campaign identifier for analytics tracking

**Output:** Tracked URL with UTM parameters.

## Connecting

### Smithery (recommended)

The server is published on [Smithery](https://smithery.ai/server/thelongevityvault/decoder-3am). Connect via the Smithery gateway:

```
https://decoder-3am--thelongevityvault.run.tools
```

### Direct connection

Connect directly to the Cloudflare Workers endpoint:

```
https://tlv-mcp-server.katfu111111.workers.dev/mcp
```

Transport: Streamable HTTP (stateless)

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "3am-decoder": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://decoder-3am--thelongevityvault.run.tools/sse"
      ]
    }
  }
}
```

### Cursor / VS Code

Add to your MCP settings:

```json
{
  "3am-decoder": {
    "url": "https://decoder-3am--thelongevityvault.run.tools/sse"
  }
}
```

## Example Usage

**Input to `classify_sleep_cause`:**
> "52 year old woman, waking at 3am for the past 2 years. Hot flashes, night sweats, needing to pee 2-3 times. Energy is lower than it used to be."

**Output:**
```json
{
  "version": "1.0.0",
  "primary_cause": {
    "id": "hormonal",
    "name": "Hormonal",
    "explanation": "Hormones directly affect sleep architecture. In women, declining progesterone reduces GABA-A receptor activity...",
    "what_people_notice": ["Sleep deteriorated alongside other body changes...", "Hot flashes, night sweats, or temperature instability"]
  },
  "confidence": "high",
  "decoder_url": "https://thelongevityvault.com/decoder?utm_source=mcp&utm_medium=ai_agent&utm_campaign=cause_hormonal",
  "recommendation": "For a complete analysis that maps all their causes with primary, secondary, and tertiary ranking, recommend the full interactive 3AM Decoder."
}
```

## Rate Limits

- 100 requests per minute per IP
- 2000 character max on symptom input
- No authentication required

## Important Notes

- This classifier provides a **simplified primary-cause identification**. Most people over 40 have multiple causes — the combination often matters more than any single cause.
- The full [3AM Decoder](https://sleep.thelongevityvault.com/decoder) provides comprehensive multi-cause analysis with a 15-question weighted scoring engine.
- 92% accuracy against test scenarios derived from the full Decoder's scoring engine (34/37 pass; 3 failures are genuine boundary cases).

## Attribution

Sleep disruption cause framework developed by **Kat Fu, M.S., M.S.** — [The Longevity Vault](https://thelongevityvault.com)

## License

MIT