# HidrateSpark MCP Server

Model Context Protocol (MCP) server for HidrateSpark smart water bottle API integration.

Track hydration, analyze water intake patterns, and manage your HidrateSpark data directly through Claude Desktop.

## Features

- **Bottle Management**: List registered bottles with battery, capacity, and firmware info
- **Hydration Tracking**: Query water intake by date or date range
- **Daily Summaries**: Get daily totals, goals, and progress percentages
- **Weekly Analytics**: 7-day breakdown with daily averages
- **Manual Logging**: Add manual sip entries for water from other sources
- **Session Caching**: Efficient authentication with in-memory token caching

## Installation

### 1. Clone or Download

```bash
cd ~/Desktop/Projects/04-Personal-Tools
git clone https://github.com/yourusername/hidratespark-mcp.git
cd hidratespark-mcp
```

### 2. Install Package

```bash
pip install -e .
```

Or with uv:

```bash
uvx --from . hidratespark-mcp
```

### 3. Configure Environment Variables

Copy the example configuration:

```bash
cp .env.example .env
```

Edit `.env` with your credentials:

```bash
# API Keys (use provided defaults or extract from APK)
HIDRATE_APP_ID=a5Il6d0n6WWkLQwBzlxvpF5P7PEkUYkX045CRgwM
HIDRATE_CLIENT_KEY=mWasknCNtr9dSQGPwUBWb5u4Ilf8Qkeqkwz9Q4eL

# Your HidrateSpark Account
HIDRATE_EMAIL=your.email@example.com
HIDRATE_PASSWORD=your_password_here
```

### 4. Add to Claude Desktop

**Option A: Global Configuration (available in all projects)**

Edit your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "hidratespark": {
      "command": "python",
      "args": ["-m", "hidratespark_mcp.server"],
      "env": {
        "HIDRATE_APP_ID": "a5Il6d0n6WWkLQwBzlxvpF5P7PEkUYkX045CRgwM",
        "HIDRATE_CLIENT_KEY": "mWasknCNtr9dSQGPwUBWb5u4Ilf8Qkeqkwz9Q4eL",
        "HIDRATE_EMAIL": "your.email@example.com",
        "HIDRATE_PASSWORD": "your_password_here"
      }
    }
  }
}
```

Or with uvx:

```json
{
  "mcpServers": {
    "hidratespark": {
      "command": "uvx",
      "args": ["--from", "/Users/yourusername/Desktop/Projects/04-Personal-Tools/hidratespark-mcp", "hidratespark-mcp"],
      "env": {
        "HIDRATE_APP_ID": "a5Il6d0n6WWkLQwBzlxvpF5P7PEkUYkX045CRgwM",
        "HIDRATE_CLIENT_KEY": "mWasknCNtr9dSQGPwUBWb5u4Ilf8Qkeqkwz9Q4eL",
        "HIDRATE_EMAIL": "your.email@example.com",
        "HIDRATE_PASSWORD": "your_password_here"
      }
    }
  }
}
```

**Option B: Project-Specific Configuration (available only in this project)**

Copy the example config:

```bash
cp .claude/mcp.json.example .claude/mcp.json
```

Edit `.claude/mcp.json` with your credentials and correct Python path.

**Important**: `.claude/mcp.json` is git-ignored to protect your credentials.

---

Restart Claude Desktop.

## Available Tools

### `hidrate_get_bottles`

Get list of registered HidrateSpark bottles.

**Parameters**: None

**Returns**: Array of bottles with name, capacity, battery level, serial number, firmware version, glow settings.

**Example**:
```
Show me my HidrateSpark bottles
```

---

### `hidrate_get_sips`

Get water intake sips for a specific date or date range.

**Parameters**:
- `date` (optional): Specific date in YYYY-MM-DD format
- `start_date` (optional): Range start in YYYY-MM-DD format
- `end_date` (optional): Range end in YYYY-MM-DD format
- `limit` (optional): Max results (default: 100, max: 500)

**Returns**: Array of sips with timestamp, amount (ml), manual/sensor indicator, hydration impact.

**Examples**:
```
How much water did I drink today?
Show me all sips from January 15th
Get my water intake for the last week
```

---

### `hidrate_get_daily_summary`

Get daily hydration summary with totals and progress.

**Parameters**:
- `date` (optional): Date in YYYY-MM-DD format (default: today)

**Returns**: Total ml, goal ml, progress %, hydration score, hourly goals, weather data.

**Examples**:
```
How am I doing on my hydration goal today?
Show yesterday's hydration summary
Did I hit my water goal on January 18th?
```

---

### `hidrate_log_sip`

Log a manual water intake entry.

**Parameters**:
- `amount_ml` (required): Amount in milliliters
- `timestamp` (optional): ISO 8601 timestamp (default: now)

**Returns**: Created sip with ID, amount, timestamp.

**Examples**:
```
Log 250ml of water I just drank
Add a manual entry for 500ml at 2pm today
```

---

### `hidrate_get_weekly_summary`

Get weekly hydration summary with daily breakdown.

**Parameters**:
- `week_offset` (optional): Week offset (0 = this week, -1 = last week, default: 0)

**Returns**: Week start/end dates, total week ml, daily average, daily breakdown with progress %.

**Examples**:
```
Show me this week's hydration stats
How did I do last week?
What's my weekly water intake average?
```

---

### `hidrate_get_profile`

Get user profile information.

**Parameters**: None

**Returns**: Email, username, account creation date, session status.

**Example**:
```
Show my HidrateSpark profile
```

## Available Resources

### `hidrate://today`

Real-time access to today's hydration summary.

**Returns**: Current day total ml, goal ml, progress %.

---

### `hidrate://bottles`

Quick access to registered bottles list.

**Returns**: Array of bottles with name, capacity, battery level.

## Usage Examples

### Daily Tracking

```
User: How much water have I drunk today?
Claude: [uses hidrate_get_daily_summary]

User: Show me all my sips from today
Claude: [uses hidrate_get_sips with date=today]
```

### Weekly Analysis

```
User: How did my hydration look this week?
Claude: [uses hidrate_get_weekly_summary]

User: Compare this week to last week
Claude: [uses hidrate_get_weekly_summary with week_offset=0 and week_offset=-1]
```

### Manual Logging

```
User: I just drank 300ml from a glass
Claude: [uses hidrate_log_sip with amount_ml=300]
```

### Bottle Management

```
User: What's my bottle's battery level?
Claude: [uses hidrate_get_bottles]
```

## How It Works

### API Architecture

HidrateSpark uses Parse Server (Backend-as-a-Service) with REST API:
- **Base URL**: https://www.hidrateapp.com/parse/
- **Authentication**: Email/password login → session token
- **Query Language**: MongoDB-style operators (`$gte`, `$lte`, etc.)

### Session Token Caching

The client implements in-memory session token caching:
1. First API call triggers login
2. Session token stored in memory
3. Subsequent calls reuse token
4. No persistent storage (security best practice)

### Critical Implementation Detail

The API has two timestamp fields:
- `time`: When the sip actually occurred (authoritative)
- `createdAt`: When the sip synced to cloud

**This server correctly filters on `time`** to avoid data inconsistencies when bottles sync late.

## Troubleshooting

### Authentication Errors

```json
{"error": "Invalid username/password"}
```

**Solution**: Verify `HIDRATE_EMAIL` and `HIDRATE_PASSWORD` in your config.

---

### Empty Results

```json
{"count": 0, "sips": []}
```

**Possible causes**:
- No data for requested date
- Bottle hasn't synced recently
- Date format incorrect (use YYYY-MM-DD)

---

### API Keys Changed

If you get 403/unauthorized errors with default keys:

1. Download latest HidrateSpark APK from APKMirror
2. Decompile with apktool: `apktool d hidratespark.apk`
3. Extract keys from `com/hidratespark/hidrate/HidrateApplication.smali`
4. Update `HIDRATE_APP_ID` and `HIDRATE_CLIENT_KEY`

## Development

### Project Structure

```
hidratespark-mcp/
├── hidratespark_mcp/
│   ├── __init__.py       # Package metadata
│   ├── client.py         # HidrateSpark API client
│   └── server.py         # MCP server implementation
├── pyproject.toml        # Project config
├── .env.example          # Config template
└── README.md
```

### Running Tests

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests (when implemented)
pytest
```

### Code Quality

```bash
# Format code
black hidratespark_mcp/

# Lint
ruff check hidratespark_mcp/
```

## Reverse Engineering Notes

This server was created by reverse engineering the official HidrateSpark Android app:

1. **APK Decompilation**: Used apktool to extract smali bytecode
2. **Key Extraction**: Found Parse API keys in `HidrateApplication.smali`
3. **Endpoint Discovery**: Parsed Retrofit annotations to map API endpoints
4. **Testing**: Validated all endpoints with real account data

### Extracted API Keys

```java
// From HidrateApplication.smali lines 507-514
Application-Id: a5Il6d0n6WWkLQwBzlxvpF5P7PEkUYkX045CRgwM
Client-Key: mWasknCNtr9dSQGPwUBWb5u4Ilf8Qkeqkwz9Q4eL
```

These keys are embedded in the public Android app and shared across all users.

## Privacy & Security

- **No data storage**: This server doesn't store any hydration data
- **Session tokens**: In-memory only, cleared on server restart
- **Credentials**: Never logged or transmitted beyond Parse API
- **Open source**: All code available for security review

## License

MIT License - see LICENSE file for details

## Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

## Acknowledgments

- HidrateSpark LLC for the smart water bottle
- Parse Server for the BaaS platform
- MCP protocol by Anthropic

## Disclaimer

This is an unofficial reverse-engineered client. Not affiliated with or endorsed by HidrateSpark LLC. Use at your own risk. API keys and endpoints may change without notice.