GlassCloud MCP Server

GlassCloud

MCP Relay Server for GlassBridge - a cloud service that bridges the GlassBridge Android app with Google services and third-party tools via the Model Context Protocol (MCP).

Purpose

GlassCloud solves a fundamental challenge in mobile AI assistants: how do you give a voice assistant on smart glasses access to your personal data (email, calendar) securely?

The answer is a cloud relay that:

1. Authenticates users via Google OAuth on a web browser
2. Links devices via QR code scanning (no typing passwords on glasses)
3. Proxies tool calls from the Android app to Google APIs
4. Manages OAuth tokens securely with encryption at rest

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Smart Glasses  │────▶│   GlassCloud    │────▶│  Google APIs    │
│  + Android App  │ WS  │  (This Server)  │     │  Gmail/Calendar │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                               │
                               ▼
                        ┌─────────────────┐
                        │  Web Console    │
                        │  (OAuth + QR)   │
                        └─────────────────┘

Key Features

• WebSocket Relay - Real-time bidirectional communication with Android devices
• Google OAuth - Secure authentication without exposing credentials to the mobile app
• QR Code Linking - Scan-to-link flow for easy device pairing
• MCP Tool Execution - Gmail and Calendar tools with automatic token refresh
• Voice-First Design - Progress messages for immediate audio feedback during tool execution

Quick Start

# Install dependencies
npm install

# Copy and configure environment
cp .env.example .env
# Edit .env with your settings (see Configuration below)

# Development (auto-reload)
npm run dev

# Production
npm run build
npm start

Then open: http://localhost:3000/console

Configuration

Required Environment Variables

# Security - MUST be unique random values (32+ chars)
# Generate with: node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
JWT_SECRET=your-random-secret-here
ENCRYPTION_KEY=your-random-key-here

# Google OAuth (optional for dev, required for production)
# Create at: https://console.cloud.google.com/apis/credentials
GOOGLE_CLIENT_ID=xxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=xxx
GOOGLE_CALLBACK_URL=http://localhost:3000/auth/google/callback

Optional Settings

PORT=3000                      # Server port
NODE_ENV=development           # development | production
LOG_LEVEL=debug               # trace | debug | info | warn | error
DATABASE_PATH=./data/glasscloud.db
CORS_ORIGINS=http://localhost:3000

Architecture

System Components

┌─────────────────────────────────────────────────────────────────┐
│                        GlassCloud Server                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐           │
│  │  WebSocket  │   │  REST API   │   │  MCP Proxy  │           │
│  │   Server    │   │  (Express)  │   │   Manager   │           │
│  │             │   │             │   │             │           │
│  │ - Device    │   │ - OAuth     │   │ - Gmail     │           │
│  │   connections│   │ - QR codes  │   │ - Calendar  │           │
│  │ - Tool      │   │ - Devices   │   │ - Token     │           │
│  │   routing   │   │ - Console   │   │   refresh   │           │
│  └──────┬──────┘   └──────┬──────┘   └──────┬──────┘           │
│         │                 │                 │                   │
│         └─────────────────┼─────────────────┘                   │
│                           │                                     │
│                  ┌────────┴────────┐                            │
│                  │   SQLite + WAL  │                            │
│                  │                 │                            │
│                  │ - Users         │                            │
│                  │ - Devices       │                            │
│                  │ - OAuth tokens  │                            │
│                  │ - Link tokens   │                            │
│                  └─────────────────┘                            │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Directory Structure

src/
├── index.ts                 # Entry point, server startup
├── config/
│   ├── env.ts              # Zod environment validation
│   ├── mcp-services.ts     # Built-in service definitions
│   └── index.ts
├── server/
│   ├── express.ts          # Express app setup (CORS, helmet, rate limiting)
│   └── websocket.ts        # WebSocket server with zombie cleanup
├── routes/
│   ├── auth.ts             #