npm package: @myprogressguru/mcp
Description: MCP Server for My Progress Guru (MPG) APIs
Author: MPG Team
Latest version: 1.0.5

# MPG MCP Server

MCP Server for My Progress Guru (MPG) APIs. Enables Claude to interact directly with production MPG endpoints.

## Features

- **OAuth Authentication** - Automatic browser-based login via Keycloak
- **Token Refresh** - Automatic token refresh during long sessions
- **Token Persistence** - Tokens cached in `~/.mpg-mcp-tokens.json`
- **PKCE Security** - Uses Proof Key for Code Exchange for secure auth

## Setup

### 1. Install dependencies and build

```bash
cd mpg-mcp
npm install
npm run build
```

### 2. Configure Claude Code

Add to `~/.claude.json` in the `mcpServers` section:

```json
{
  "mcpServers": {
    "mpg": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/aleksandarpetrov/Documents/Projects/MPG/mpg-mcp/dist/index.js"]
    }
  }
}
```

Or add a `.mcp.json` file in the MPG project root:

```json
{
  "mcpServers": {
    "mpg": {
      "type": "stdio",
      "command": "node",
      "args": ["./mpg-mcp/dist/index.js"]
    }
  }
}
```

### 3. Restart Claude Code

After configuring, restart Claude Code in the MPG directory. Verify with:

```bash
claude mcp list
```

### 4. First Use - Authentication

On first use, the MCP server will:
1. Open your browser to Keycloak login page
2. You log in with your MPG trainer account
3. Browser shows "Authentication Successful"
4. Token is saved for future sessions

Subsequent sessions will use the cached token (with automatic refresh).

## Available Tools

### Training Service

| Tool | Description |
|------|-------------|
| `mpg_list_trainees` | List trainer's trainees |
| `mpg_get_trainee` | Get trainee details |
| `mpg_get_trainee_summary` | AI-generated training summary |
| `mpg_list_invitations` | List pending invitations |
| `mpg_create_invitation` | Send trainee invitation |
| `mpg_approve_invitation` | Approve invitation |
| `mpg_decline_invitation` | Decline invitation |
| `mpg_promote_trainee` | Promote to Pro |
| `mpg_demote_trainee` | Demote from Pro |
| `mpg_list_workouts` | List workout templates |
| `mpg_get_workout` | Get workout details |
| `mpg_create_workout` | Create workout |
| `mpg_update_workout` | Update workout |
| `mpg_add_exercise_to_workout` | Add exercise |
| `mpg_delete_workout` | Delete workout |
| `mpg_list_exercises` | List exercises |
| `mpg_get_exercise` | Get exercise details |
| `mpg_list_workout_records` | Trainee's workout history |
| `mpg_get_workout_record` | Get workout session details |
| `mpg_get_active_workout` | Get active workout |
| `mpg_get_recent_workouts` | Recent workouts |
| `mpg_list_training_splits` | List training programs |
| `mpg_get_training_split` | Get program details |
| `mpg_create_training_split` | Create program |
| `mpg_update_training_split` | Update program |
| `mpg_copy_training_split` | Copy to trainee |
| `mpg_assign_workout_to_day` | Assign workout to day |
| `mpg_delete_training_split` | Delete program |
| `mpg_get_body_weight_history` | Weight history |
| `mpg_record_body_weight` | Record weight |
| `mpg_get_body_measurements_history` | Measurements history |
| `mpg_record_body_measurements` | Record measurements |
| `mpg_get_sleep_history` | Sleep history |
| `mpg_record_sleep_quality` | Record sleep |

### Nutrition Service

| Tool | Description |
|------|-------------|
| `mpg_get_meal_diary` | Daily meal diary |
| `mpg_get_nutrition_summary` | Nutrition summary |
| `mpg_add_meal` | Add meal |
| `mpg_add_food_to_meal` | Add food to meal |
| `mpg_delete_food_from_meal` | Remove food |
| `mpg_search_foods` | Search food database |
| `mpg_get_food` | Get food details |
| `mpg_create_custom_food` | Create custom food |
| `mpg_list_favorite_foods` | List favorites |
| `mpg_add_favorite_food` | Add to favorites |
| `mpg_remove_favorite_food` | Remove from favorites |
| `mpg_get_nutrition_plan` | Active nutrition plan |
| `mpg_list_nutrition_plans` | All nutrition plans |
| `mpg_create_nutrition_plan` | Create plan |
| `mpg_update_nutrition_plan` | Update plan |
| `mpg_activate_nutrition_plan` | Activate plan |

### Notifications Service

| Tool | Description |
|------|-------------|
| `mpg_list_notifications` | List notifications |
| `mpg_send_notification` | Send push notification |
| `mpg_mark_notification_read` | Mark as read |
| `mpg_delete_notification` | Delete notification |

### Payments Service

| Tool | Description |
|------|-------------|
| `mpg_get_subscription` | User's subscription |
| `mpg_list_subscription_plans` | Available plans |
| `mpg_get_subscription_plan` | Plan details |
| `mpg_list_subscription_offers` | Active offers |
| `mpg_activate_free_trial` | Start free trial |
| `mpg_cancel_subscription` | Cancel subscription |

## Usage Examples

```
"List my trainees"
"Show me John's workout history"
"What did Maria eat today?"
"Create a new Push/Pull/Legs training split"
"Send a notification to trainee X"
```

## Token Management

Tokens are automatically managed:
- Access tokens refresh automatically before expiry
- Refresh tokens are stored securely in `~/.mpg-mcp-tokens.json`
- If refresh token expires (long inactivity), browser login will be triggered

### Manual Token (CI/Automation)

For CI/CD or automation, you can bypass OAuth by setting `MPG_ACCESS_TOKEN`:

```json
{
  "mcpServers": {
    "mpg": {
      "type": "stdio",
      "command": "node",
      "args": ["./mpg-mcp/dist/index.js"],
      "env": {
        "MPG_ACCESS_TOKEN": "your-jwt-token"
      }
    }
  }
}
```

### Clear Cached Tokens

```bash
rm ~/.mpg-mcp-tokens.json
```

## Development

```bash
# Run with ts-node (development)
npm run dev

# Build and run (production)
npm run build
npm start
```