Google MCP Router

# 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