# Google MCP Router

A Google-only MCP (Model Context Protocol) Router for scheduling meetings and sending email confirmations.

## Features

- **5 MCP Tools**: `time.resolve`, `calendar.find_free_slots`, `calendar.create_event`, `calendar.cancel_event`, `email.send`
- **Policy Enforcement**: Working hours, calendar allowlist, overlap prevention
- **OAuth Integration**: Secure Google API authentication with PKCE
- **Idempotency**: Prevents duplicate operations
- **Observability**: Structured logging, Prometheus metrics, OpenTelemetry tracing

## Quick Start

### Prerequisites

- Node.js ≥ 20
- Redis (optional, falls back to in-memory store)
- Google Cloud project with Calendar API and Gmail API enabled

### Installation

#### Quick Setup (Recommended)

**Windows:**
```cmd
setup.bat
```

**Linux/Mac:**
```bash
chmod +x setup.sh
./setup.sh
```

#### Manual Setup

1. Clone the repository:
```bash
git clone <repository-url>
cd google-mcp-router
```

2. Install dependencies:
```bash
npm install
```

3. Set up environment variables:
```bash
cp .env.example .env
# Edit .env with your configuration
```

4. Build the project:
```bash
npm run build
```

5. Start the server:
```bash
npm start
```

### Environment Configuration

Create a `.env` file with the following variables:

```env
NODE_ENV=staging
APP_PORT=8080
DEFAULT_TZ=America/Chicago
DEFAULT_MEETING_MIN=30
ALLOWLIST_CALENDAR_IDS=primary
WORK_HOURS_START=08:00
WORK_HOURS_END=18:00
WORK_DAYS=Mon,Tue,Wed,Thu,Fri
GOOGLE_CLIENT_ID=your_google_client_id_here
GOOGLE_CLIENT_SECRET=your_google_client_secret_here
GOOGLE_REDIRECT_URI=http://localhost:8080/oauth/google/callback
TOKEN_ENC_KEY=base64:your_base64_encryption_key_here
REDIS_URL=redis://localhost:6379
LOG_LEVEL=info
GMAIL_SENDER_EMAIL=assistant@yourdomain.com
GMAIL_SENDER_NAME=Thinh's Assistant
```

### Google Cloud Setup

1. Create a Google Cloud project
2. Enable Calendar API and Gmail API
3. Create OAuth 2.0 credentials (Web application)
4. Set redirect URI to `http://localhost:8080/oauth/google/callback`
5. Configure OAuth scopes:
   - `https://www.googleapis.com/auth/calendar.events`
   - `https://www.googleapis.com/auth/gmail.send`

## API Usage

### Authentication

1. Visit `/oauth/google/login` to start OAuth flow
2. Complete Google authentication
3. You'll be redirected to `/oauth/google/callback` with tokens stored

### Tool Execution

Execute MCP tools via POST requests:

```bash
# Resolve time expression
curl -X POST http://localhost:8080/mcp/tools/time.resolve \
  -H "Content-Type: application/json" \
  -d '{"input": "next Tuesday 3pm"}'

# Find free slots
curl -X POST http://localhost:8080/mcp/tools/calendar.find_free_slots \
  -H "Content-Type: application/json" \
  -d '{
    "window_start_iso": "2024-01-15T09:00:00-06:00",
    "window_end_iso": "2024-01-15T17:00:00-06:00",
    "duration_min": 30
  }'

# Create event
curl -X POST http://localhost:8080/mcp/tools/calendar.create_event \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Team Meeting",
    "start_iso": "2024-01-15T14:00:00-06:00",
    "end_iso": "2024-01-15T15:00:00-06:00",
    "attendees": [{"email": "colleague@example.com"}],
    "idempotency_key": "unique-key-123"
  }'
```

### Available Tools

1. **`time.resolve`** - Parse natural language time expressions
2. **`calendar.find_free_slots`** - Find available time slots
3. **`calendar.create_event`** - Create calendar events
4. **`calendar.cancel_event`** - Cancel calendar events
5. **`email.send`** - Send templated emails

## Development

### Running in Development Mode

```bash
npm run dev
```

### Running Tests

```bash
npm test
npm run test:coverage
```

### Linting

```bash
npm run lint
```

### Type Checking

```bash
npm run type-check
```

## Architecture

```
src/
├── server.ts                 # Fastify server
├── mcp/
│   ├── index.ts             # MCP tool registry
│   ├── tools/               # Individual tool implementations
│   └── schemas/             # JSON schemas for validation
├── adapters/                # Google API adapters
├── policy/                   # Business rule enforcement
├── auth/                     # OAuth and token management
├── templates/                # Email templates
└── util/                     # Shared utilities
```

## Security

- OAuth 2.0 with PKCE for secure authentication
- AES-256-GCM encryption for token storage
- Policy enforcement for all operations
- Input validation and sanitization
- Rate limiting and idempotency

## Monitoring

- **Health Check**: `GET /health`
- **Metrics**: `GET /metrics` (Prometheus format)
- **Logs**: Structured JSON logging with Pino

## License

MIT License