samkaraca/mis48b-term-project-mcp-server

AI Voicemail MCP Server

This project is a Model Context Protocol (MCP) server that acts as a personal AI voicemail and assistant. It allows users to connect their Google account, manage their calendar and emails, and receive WhatsApp notifications. The server exposes a set of tools via MCP for integration with AI agents and legacy clients.

Features

• Google OAuth2 Authentication: Securely connect your Google account to access calendar and email features.
• Calendar Management: Create, list, and delete Google Calendar events.
• Email Management: Fetch, send, and reply to emails using your Gmail account.
• WhatsApp Notifications: Receive WhatsApp messages for important events or voicemails.
• MCP Tools: Exposes a set of tools for AI agents to interact with your calendar, email, and WhatsApp.
• Phone Number Registration: Collects and stores your phone number for WhatsApp notifications.

Environment Variables

Create a .env file in the root directory and fill in the following variables:

# GOOGLE CREDENTIALS
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_REDIRECT_URI=http://localhost:3000/api/auth/oauth2callback

# OPENAI
OPENAI_API_KEY=your-openai-api-key
OPENAI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai/
OPENAI_MODEL=gemini-2.5-flash-preview-04-17

# TWILIO
TWILIO_ACCOUNT_SID=your-twilio-account-sid
TWILIO_AUTH_TOKEN=your-twilio-auth-token
TWILIO_PHONE_NUMBER=whatsapp:+14155238886

# (Optional) PORT
PORT=3000

Installation

1. Clone the repository:

   git clone https://github.com/samkaraca/mis48b-term-project-mcp-server
   cd mis48b-term-project-mcp-server
   

2. Install dependencies:

   npm install
   

3. Configure environment variables:
   • Copy the example above into a .env file and fill in your credentials.

Running the Server

npm run dev

The server will start on the port specified in your .env (default: 3000).

Using the MCP Server

To interact with the MCP server, you must connect your client to the /sse endpoint:

Example:

http://localhost:3000/sse

Google Account Setup

1. Visit Google Cloud Console and create OAuth 2.0 credentials.
2. Set the redirect URI to http://localhost:3000/api/auth/oauth2callback (or your server's URL).
3. Fill in the GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and GOOGLE_REDIRECT_URI in your .env.

Twilio Setup (for WhatsApp Messaging)

To enable WhatsApp notifications, you need a Twilio account with WhatsApp access:

1. Sign up for Twilio:
   • Go to Twilio Console and create an account.
2. Enable WhatsApp Sandbox:
   • In the Twilio Console, search for "WhatsApp" and activate the WhatsApp Sandbox.
   • Follow the instructions to join the sandbox with your phone number.
3. Get your credentials:
   • Copy your Account SID and Auth Token from the Twilio Console dashboard.
   • Use the sandbox phone number (e.g., whatsapp:+14155238886) for TWILIO_PHONE_NUMBER.
4. Configure your .env:
   • Set TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, and TWILIO_PHONE_NUMBER in your .env file.
5. (Optional) Go Live:
   • For production, request access to WhatsApp Business API and use your own WhatsApp-enabled number.

Authentication & Phone Number Registration

1. Open your browser and go to http://localhost:3000/api/auth.
2. Complete the Google OAuth flow.
3. After authentication, you will be prompted to enter your phone number (used for WhatsApp notifications).
4. Once setup is complete, you can close the window.

Endpoints

• GET /health — Health check endpoint.
• GET /api/auth — Start Google OAuth authentication.
• GET /api/auth/status — Check authentication status.
• GET /api/auth/phone-setup — Phone number registration page.
• POST /api/auth/save-phone — Save phone number after registration.
• GET /sse — Server-Sent Events endpoint for MCP
• POST /messages — Message endpoint for MCP.

MCP Tools

The MCP server exposes the following tools for AI agents:

• get-events: List calendar events in a time range.
• create-event: Create a new calendar event.
• remove-event: Delete a calendar event by eventId.
• get-current-time: Get the current time in Turkey (ISO format).
• get-emails: Fetch recent emails (subject, from, to, date, snippet, body).
• send-email: Send an email (HTML content).
• reply-email: Reply to an email by messageId.
• send-message-to-user: Send a WhatsApp message to the user.
• send-summary-to-user: Summarize a phone conversation and send to the user.

Project Structure

src/
  index.ts                # Main server entrypoint
  routes/
    auth.routes.ts        # Authentication and phone setup routes
  lib/
    mcp.ts                # MCP server and tool definitions
    oAuth2Client.ts       # Google OAuth2 logic
    gmail.ts              # Gmail integration
    userProfile.ts        # User profile management
    twilioClient.ts       # WhatsApp (Twilio) integration
    summarizeConversationAndSendMessage.ts # Summarization logic
  tools/
    calendar.tools.ts     # Google Calendar integration
  pages/
    phone-setup.html      # Phone number registration UI
    setup-complete.html   # Setup completion UI