# Weekly Planning Assistant MCP

> An intelligent MCP server that turns your Google Calendar into actionable weekly insights through natural conversation.

[![MCP](https://img.shields.io/badge/MCP-Server-blue)](https://modelcontextprotocol.io)
[![Python](https://img.shields.io/badge/Python-3.11+-green)](https://www.python.org/)
[![License](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)

## What It Does

Ask Claude natural questions about your schedule and get intelligent analysis:

- **"What does my week look like?"** → Day-by-day breakdown with meeting hours, office days, and free time
- **"When should I book boxing classes?"** → Ranked workout time suggestions based on your actual schedule
- **"Which days am I going to the office?"** → Office day detection with commute warnings
- **"Do I have any scheduling problems?"** → Identifies conflicts, missing lunch breaks, and marathon meeting blocks

## How It Works

```mermaid
graph LR
    A[You ask Claude] --> B[Weekly Planner MCP]
    B --> C[Google Calendar MCP]
    C --> D[Your Google Calendar]
    D --> C
    C --> B
    B --> A
```

This server demonstrates **MCP chaining** - it acts as both a server (to Claude) and a client (to Google Calendar MCP), providing domain-specific intelligence on top of raw calendar data.

## Features

### 🗓️ **Week Analysis**
- Office vs. WFH day detection
- Total meeting hours per day
- Free time gaps (>1 hour)
- Back-to-back meeting blocks
- Busiest/lightest day identification

### ⚠️ **Danger Zone Detection**
- Missing lunch breaks (meetings 12-2pm)
- Marathon meetings (3+ hours straight)
- Days with zero free time
- Calendar conflicts and overlaps

### 🏃 **Workout Planning**
- Quality-scored time slot suggestions
- Preference-based filtering (morning/lunch/evening)
- Commute-aware recommendations
- Duration-based slot matching

### 🚗 **Commute Planning**
- Office day detection via keywords
- Earliest arrival time calculation
- Early morning gym warnings
- Multi-calendar support

## Installation

### Prerequisites

- **Python 3.11+** - [Download](https://www.python.org/downloads/)
- **Node.js** - [Download](https://nodejs.org/) (for Google Calendar MCP)
- **Claude Desktop** - [Download](https://claude.ai/download)
- **Google Account** with Calendar access

### 1. Clone and Install

```bash
# Clone the repository
git clone https://github.com/yourusername/weekly-planner-mcp.git
cd weekly-planner-mcp

# Install uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh
source $HOME/.local/bin/env

# Install dependencies
uv sync
```

### 2. Configure Settings

```bash
# Copy example configuration
cp config.example.json config.json

# Edit with your preferences
nano config.json
```

Example `config.json`:
```json
{
  "calendar_ids": ["primary"],
  "office_keywords": ["office", "HQ"],
  "work_hours": {
    "start": "09:00",
    "end": "18:00"
  },
  "preferred_workout_times": ["morning", "lunch"],
  "min_workout_duration": 60
}
```

### 3. Set Up Google Calendar OAuth

#### A. Create Google Cloud Project

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Click **"New Project"**
3. Name it (e.g., "Weekly Planner")
4. Click **"Create"**

#### B. Enable Calendar API

1. Search for **"Google Calendar API"**
2. Click **"Enable"**

#### C. Configure OAuth Consent Screen

1. Go to **"APIs & Services"** → **"OAuth consent screen"**
2. Select **"External"** user type
3. Fill in app name and your email
4. Click **"Save and Continue"** through all steps
5. Under **"Test users"**, click **"+ ADD USERS"**
6. Add your Gmail address

#### D. Create OAuth Credentials

1. Go to **"Credentials"** → **"Create Credentials"** → **"OAuth client ID"**
2. Application type: **"Desktop app"** ⚠️ (NOT Web application!)
3. Name: "Weekly Planner Desktop"
4. Click **"Create"** and **"Download JSON"**

#### E. Save and Authenticate

```bash
# Save credentials
mkdir -p ~/.config/google-calendar-mcp
mv ~/Downloads/client_secret_*.json ~/.config/google-calendar-mcp/gcp-oauth.keys.json

# Authenticate
export GOOGLE_OAUTH_CREDENTIALS="$HOME/.config/google-calendar-mcp/gcp-oauth.keys.json"
npx -y @cocal/google-calendar-mcp auth
```

Your browser will open - sign in and grant calendar permissions.

### 4. Add to Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "weekly-planner": {
      "command": "/Users/yourusername/.local/bin/uv",
      "args": [
        "--directory",
        "/absolute/path/to/weekly-planner-mcp",
        "run",
        "python",
        "-m",
        "weekly_planner",
        "--stdio"
      ],
      "env": {
        "GOOGLE_OAUTH_CREDENTIALS": "/Users/yourusername/.config/google-calendar-mcp/gcp-oauth.keys.json"
      }
    }
  }
}
```

**Replace:**
- `/Users/yourusername/` with your actual home directory (run `echo $HOME`)
- `/absolute/path/to/weekly-planner-mcp` with full path to this project

### 5. Restart Claude Desktop

Quit Claude Desktop (⌘+Q) and reopen. Test with:
```
"What does my week look like?"
```

## Configuration

### Basic Settings

Edit `config.json` to customize behavior:

```json
{
  "calendar_ids": ["primary"],           // Which calendars to analyze
  "office_keywords": ["office", "HQ"],   // Keywords for office detection
  "work_hours": {
    "start": "09:00",
    "end": "18:00"
  },
  "preferred_workout_times": ["morning", "lunch", "evening"],
  "min_workout_duration": 60             // Minutes
}
```

### Adding Multiple Calendars

To include work calendars or imported calendars, first list your available calendars, then add their IDs to `config.json`.

See the full command in the Development section below for listing calendars.

## Architecture

### Project Structure
```
weekly-planner-mcp/
├── src/weekly_planner/
│   ├── server.py          # FastMCP server with 4 tools
│   ├── gcal_client.py     # Google Calendar MCP client
│   ├── analysis.py        # Core scheduling analysis logic
│   ├── models.py          # Pydantic models for structured output
│   └── config.py          # Configuration management
├── config.json            # Your configuration
├── config.example.json    # Example configuration
└── pyproject.toml         # Dependencies
```

### Tools Provided

1. **`analyze_week`** - Comprehensive weekly overview with day-by-day breakdown
2. **`find_danger_zones`** - Identifies scheduling problems and conflicts
3. **`suggest_workout_slots`** - Intelligent workout time suggestions with quality scoring
4. **`check_commute_requirements`** - Office day detection with commute planning

All tools return structured Pydantic models for type-safe, validated responses.

## Example Usage

**Week Overview:**
```
You: What does my week look like?

Claude: Here's your week breakdown:

Monday (4.5h meetings)
• Office day detected
• Free slots: 9:00-10:00, 14:00-16:00
• 3-hour back-to-back block in morning

Tuesday (2h meetings)
• Lightest day this week
• Large gap: 11:00-17:00
```

**Workout Planning:**
```
You: When should I book a 60-minute workout this week?

Claude: Best times ranked by quality:

1. Tuesday 11:00-12:00 (Score: 8.5/10)
   • Long gap available
   • Lunch time slot
   • Not near office days

2. Friday 18:30-19:30 (Score: 7.8/10)
   • Evening slot
   • After work hours
```

**Office Days:**
```
You: Which days am I going to the office?

Claude: You have 2 office days this week:

• Monday: Office all day (earliest: 9:30am)
  ⚠️ Early start - avoid morning gym

• Thursday: Afternoon in office (earliest: 2:00pm)
  ✓ Morning free for workout
```

## Development

### List Available Calendars

```bash
cd /path/to/weekly-planner-mcp
export GOOGLE_OAUTH_CREDENTIALS="$HOME/.config/google-calendar-mcp/gcp-oauth.keys.json"

uv run python -c "
import asyncio, os
os.environ['GOOGLE_OAUTH_CREDENTIALS'] = os.path.expanduser('~/.config/google-calendar-mcp/gcp-oauth.keys.json')
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def list_cals():
    params = StdioServerParameters('npx', ['-y', '@cocal/google-calendar-mcp', 'start'], env=os.environ.copy())
    async with stdio_client(params) as (r, w):
        async with ClientSession(r, w) as s:
            await s.initialize()
            result = await s.call_tool('list-calendars', {})
            import json
            for cal in json.loads(result.content[0].text)['calendars']:
                print(f'{cal[\"summary\"]}: {cal[\"id\"]}')
asyncio.run(list_cals())
"
```

Add calendar IDs to `config.json` under `calendar_ids`.

### Check Logs

```bash
# Claude Desktop logs
tail -f ~/Library/Logs/Claude/mcp-server-weekly-planner.log

# Re-authenticate if needed
npx -y @cocal/google-calendar-mcp auth
```

## Troubleshooting

### "OAuth credentials not found"
- Verify: `ls -la ~/.config/google-calendar-mcp/gcp-oauth.keys.json`
- Ensure `GOOGLE_OAUTH_CREDENTIALS` is set in Claude Desktop config

### "No events returned"
- Re-authenticate: `npx -y @cocal/google-calendar-mcp auth`
- Verify calendar IDs in `config.json`
- Check logs: `tail -f ~/Library/Logs/Claude/mcp-server-weekly-planner.log`

### "Access denied" during OAuth
- Add yourself as a test user in Google Cloud Console
- Use the exact Gmail address you added
- Application type must be "Desktop app" not "Web application"

### "Token expired"
```bash
export GOOGLE_OAUTH_CREDENTIALS="$HOME/.config/google-calendar-mcp/gcp-oauth.keys.json"
npx -y @cocal/google-calendar-mcp auth
```

## What This Demonstrates

This project showcases key MCP concepts:

- **MCP Chaining** - One MCP server calling another MCP server
- **Structured Output** - Type-safe responses using Pydantic models
- **Domain Abstractions** - High-level analysis tools built on generic calendar API
- **Configuration Management** - File-based and environment variable configuration
- **FastMCP Usage** - Modern MCP server implementation with decorators
- **OAuth Integration** - Secure Google Calendar API authentication