LOLServ - Gmail AI MCP Server

A modern Model Context Protocol (MCP) server that provides AI-powered Gmail tools for email analysis, summarization, drafting replies, and rewriting content. Built with the latest MCP SDK patterns and full type safety.

Features

• Email Analysis: Comprehensive email analysis with sentiment, tone, priority, and category detection
• Email Summarization: Convert long emails into concise bullet points
• Reply Drafting: Generate contextual email replies with customizable tone
• Content Rewriting: Improve and modify email drafts based on instructions
• Modern MCP: Built with McpServer and registerTool for clean, maintainable code
• MCP Tool Hints: Proper readOnlyHint and idempotentHint annotations for better client integration
• Tool Debugging: Built-in debugging hints showing which MCP tools were used to generate responses
• Modular Architecture: Each tool in its own file for better organization and maintainability
• Type Safety: Full Zod validation and TypeScript integration
• Runtime Validation: Comprehensive input/output validation with detailed error messages
• Enterprise Ready: Production-grade error handling and fallback mechanisms

Quick Start

1. Install dependencies:

   npm install
   

2. Set up environment variables: Create a .env file with your OpenAI API key:

   OPENAI_API_KEY=your_openai_api_key_here
   OPENAI_MODEL=gpt-3.5-turbo  # Optional: gpt-4o-mini, gpt-4, etc.
   

3. Start the MCP server:

   # Stdio mode (default - for MCP clients like Claude Desktop)
   npm run mcp
   
   # HTTP mode (for web access and testing)
   npm run http
   
   # Streaming HTTP mode (for real-time streaming with MCP clients)
   npm run streaming-http
   
   # Production mode
   npm run build
   npm start
   

MCP Tools

The server exposes the following MCP tools with full type safety, validation, and MCP tool hints for better client integration:

intelligent_chat

AI-powered conversational assistant that can help with email tasks and suggest actions.

MCP Hints:

• readOnlyHint: false - Can suggest actions and operations
• idempotentHint: false - Different responses for same input based on context

Parameters:

• message (string, required): The user's message or question
• conversationHistory (array, optional): Previous messages in the conversation
  • role (string): "user", "assistant", or "system"
  • content (string): Message content
  • timestamp (string): When the message was sent
• currentContext (object, optional): Current email context
  • selectedEmailId (string): Currently selected email ID
  • threadEmails (array): All emails in the current thread
    • id (string): Email ID
    • subject (string): Email subject
    • sender (string): Sender email address
    • time (string): Email timestamp
    • body (string): Email body content
    • messageIndex (number): Position in thread (0-based)
  • availableEmails (array): List of available emails
  • userEmail (string): User's email address

Returns:

• content (array): MCP content array with structured response
  • type: "text"
  • text: JSON string containing:
    • response: The AI's conversational response
    • suggestedActions: Array of actions the user might want to take (optional)
    • shouldPerformAction: Boolean indicating if an action should be auto-performed (optional)
    • actionToPerform: Specific action to perform if auto-execution is enabled (optional)

Example Response:

{
  "response": "I can help you draft a reply to that email!",
  "suggestedActions": [
    {
      "action": "draftReply",
      "description": "Draft a professional reply to the email",
      "parameters": {
        "emailContent": "Hi, can we reschedule our meeting for next week?",
        "tone": "professional"
      }
    }
  ]
}

analyzeEmail

Comprehensive email analysis with structured insights.

MCP Hints:

• readOnlyHint: true - Only reads and analyzes content without making changes
• idempotentHint: true - Multiple calls with same input produce same results

Parameters:

• emailContent (string or object, required): Email content
  • Simple usage: Pass as string for basic analysis
  • Full usage: Pass as object with complete email structure:
    • subject (string, required): Email subject line
    • sender (string, required): Sender email address (validated)
    • recipients (object, optional): Recipient information
      • to (array of emails, default: []): To recipients
      • cc (array of emails, default: []): CC recipients
      • bcc (array of emails, default: []): BCC recipients
    • body (string, required): Plain text email body
    • bodyHtml (string, optional): HTML email body

HTTP API Usage:

• emailContent (string): The email text to analyze
• subject (string, optional): Email subject (defaults to "No Subject")
• sender (string, optional): Sender email (defaults to "unknown@example.com")
• bodyHtml (string, optional): HTML version of email body

Returns:

• content (array): MCP content array with structured analysis
  • type: "text"
  • text: JSON string containing:
    • summary: Email summary
    • mainPoints: Array of key points
    • suggestedActions: Array of suggested actions
    • priority: "low" | "medium" | "high"
    • category: "work" | "personal" | "marketing" | "notification" | "other"
    • sentiment: "positive" | "neutral" | "negative"
    • tone: "professional" | "casual" | "formal" | "urgent" | "friendly" | "polite" | "aggressive" | "apologetic" | "neutral"

summarizeEmail

Convert long emails into concise bullet points.

MCP Hints:

• readOnlyHint: true - Only reads and analyzes content without making changes
• idempotentHint: true - Multiple calls with same input produce same results

Parameters:

• text (string, required): Email content to summarize (min 1 character)

Returns:

• content (array): MCP content array with summary
  • type: "text"
  • text: Bullet point summary

draftReply

Generate contextual email replies with customizable tone.

MCP Hints:

• readOnlyHint: true - Generates draft content but doesn't send or modify emails
• idempotentHint: false - Multiple calls may produce different drafts due to AI generation

Parameters:

• email (string, required): Original email content (min 1 character)
• tone (string, optional): Reply tone (default: "polite")

Returns:

• content (array): MCP content array with generated reply
  • type: "text"
  • text: Generated reply content

rewriteReply

Rewrite email drafts according to specific instructions.

MCP Hints:

• readOnlyHint: true - Modifies draft content but doesn't send or permanently change emails
• idempotentHint: false - Multiple calls may produce different rewrites due to AI generation

Parameters:

• draft (string, required): Original email draft (min 1 character)
• instruction (string, required): Rewrite instructions (min 1 character)

Returns:

• content (array): MCP content array with rewritten email
  • type: "text"
  • text: Rewritten email content

Supported Email Formats

The server accepts various email address formats commonly used in email systems:

✅ Simple Format: paul@dserv.io ✅ RFC 5322 Format: Paul Wilkinson <paul@dserv.io> ✅ Quoted Format: "Paul Wilkinson" <paul@dserv.io> ✅ Multiple Recipients: Paul Wilkinson <paul@dserv.io>, Jane Doe <jane@example.com> ✅ Mixed Formats: paul@dserv.io, "Jane Smith" <jane.smith@company.com>

All email fields (sender, recipients.to, recipients.cc, recipients.bcc) support these formats.

Usage with MCP Clients

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "gmail-ai": {
      "command": "npx",
      "args": ["tsx", "/path/to/lolserv/src/mcpServer.ts"],
      "env": {
        "OPENAI_API_KEY": "your-api-key-here"
      }
    }
  }
}

HTTP Mode

For web access and testing, start the server in HTTP mode:

npm run http

Then visit:

• Server Status: http://localhost:4000/
• MCP Endpoint: http://localhost:4000/mcp

Streaming HTTP Mode

For real-time streaming with MCP clients that support streaming HTTP transport:

npm run streaming-http

This mode uses the StreamableHTTPServerTransport for efficient, real-time communication:

• MCP Endpoint: http://localhost:4000/mcp
• Transport: Streamable HTTP (supports streaming responses)
• Benefits: Lower latency, real-time updates, better performance for long-running operations

Other MCP Clients

The server supports multiple transport modes:

# Stdio mode (default)
npx tsx src/mcpServer.ts

# HTTP mode
MCP_MODE=http npx tsx src/mcpServer.ts

# Streaming HTTP mode
MCP_MODE=streaming-http npx tsx src/mcpServer.ts

Environment Variables

Configure the server behavior using environment variables:

# Server mode (stdio, http, streaming-http)
MCP_MODE=streaming-http

# Server port (for HTTP modes)
PORT=4000

# OpenAI configuration
OPENAI_API_KEY=your-api-key-here
OPENAI_MODEL=gpt-3.5-turbo

Testing

Run the test suite:

npm test

The test suite includes:

• Server status endpoint validation
• HTTP server connectivity checks
• Tool availability verification
• MCP protocol initialization testing
• MCP tool discovery testing

Adding New Tools

The modular architecture makes it easy to add new tools:

1. Create a new tool file in src/tools/:

   // src/tools/myNewTool.ts
   import { z } from "zod";
   import { callLLM } from "../llm.js";
   
   export const myNewTool = {
     name: "myNewTool",
     title: "My New Tool",
     description: "Description of what this tool does",
     inputSchema: {
       input: z.string().min(1, "Input is required"),
     },
     annotations: {
       readOnlyHint: true, // Set to true if tool only reads data
       idempotentHint: true, // Set to true if same input produces same output
     },
     handler: async ({ input }: { input: string }) => {
       // Tool implementation
       const result = await callLLM(`Process: ${input}`);
       return {
         content: [{ type: "text" as const, text: result }],
       };
     },
   };
   

2. Export the tool in src/tools/mcpServer.ts:

   export { myNewTool } from "./myNewTool.js";
   

3. Register the tool in src/mcpServer.ts:

   server.registerTool(
     myNewTool.name,
     {
       title: myNewTool.title,
       description: myNewTool.description,
       inputSchema: myNewTool.inputSchema,
       annotations: myNewTool.annotations,
     },
     myNewTool.handler
   );
   

Development

• TypeScript: Full TypeScript support with strict type checking
• ES Modules: Modern ES module syntax
• Zod Validation: Runtime type validation with detailed error messages
• Modern MCP: Built with latest MCP SDK patterns (McpServer, registerTool)
• Modular Design: Clean separation of concerns with individual tool files
• Error Handling: Comprehensive error handling and logging
• Environment Variables: Secure configuration management

Development Commands

# Start development server (stdio mode)
npm run mcp

# Start development server (HTTP mode)
npm run http

# Start development server (Streaming HTTP mode)
npm run streaming-http

# Build for production
npm run build

# Start production server
npm start

# Run tests
npm test

Project Structure

src/
├── mcpServer.ts    # Main MCP server entry point
├── mcpClient.ts    # MCP client for testing and development
├── llm.ts           # OpenAI client configuration
├── schemas.ts       # Zod schemas for type validation
└── tools/           # Individual tool implementations
    ├── mcpClient.ts     # Tool exports
    ├── summarizeEmail.ts
    ├── draftReply.ts
    ├── rewriteReply.ts
    └── analyzeEmail.ts

Architecture

The server uses a modern, modular architecture:

• Modular Design: Each tool is in its own file for better organization and maintainability
• Modern MCP: Uses McpServer and registerTool patterns for clean tool registration
• Zod Integration: Full runtime validation using Zod schemas defined in schemas.ts
• Type Safety: TypeScript types are inferred from Zod schemas for compile-time safety
• MCP Compliance: Full Model Context Protocol compliance with proper content formatting

MCP Tool Hints

This server uses MCP tool hints to provide better client integration and tool behavior understanding:

Available Hints

• readOnlyHint: Indicates whether the tool only reads data without making changes
• idempotentHint: Indicates whether multiple calls with the same input produce the same result
• destructiveHint: Indicates whether the tool can cause destructive operations (not used in this server)
• openWorldHint: Indicates whether the tool can access external data (not used in this server)

Tool Hint Usage

• Analysis Tools (analyzeEmail, summarizeEmail): readOnlyHint: true, idempotentHint: true
• Generation Tools (draftReply, rewriteReply): readOnlyHint: true, idempotentHint: false

These hints help MCP clients make better decisions about tool usage, caching, and user experience.

Type Safety & Validation

This server implements enterprise-grade type safety:

Zod Schemas

• Input Validation: All tool inputs are validated against Zod schemas
• Output Validation: Tool outputs are validated to ensure consistency
• Email Validation: Proper email address format validation
• Enum Validation: Strict validation for priority, category, sentiment, and tone values

Error Handling

• Detailed Error Messages: Zod provides specific validation error messages
• Graceful Fallbacks: Fallback analysis when AI responses fail to parse
• Runtime Safety: Prevents runtime errors from invalid data

Example Validation

// Input validation with detailed error messages
const validatedInput = SummarizeEmailInputSchema.parse({ text });
// Throws: "Email text is required" if text is empty

// Email validation
const emailSchema = z.string().email("Invalid sender email address");
// Throws: "Invalid sender email address" for malformed emails

OpenAI API Quota Management

Increasing Your Quota

1. Add Payment Method: Go to OpenAI Platform → Settings → Billing
2. Check Usage: Visit Usage Dashboard to see current limits
3. Upgrade Plan: Free tier has limited credits; paid plans offer higher quotas

Cost-Effective Models

• gpt-3.5-turbo: Cheapest option, good for most tasks
• gpt-4o-mini: Balanced cost/performance
• gpt-4: Most capable but expensive

Requirements

• Node.js 18+
• OpenAI API key
• TypeScript (for development)

License

ISC

Debugging Tool Usage

The server now includes built-in debugging information to help you understand which MCP tools were used to generate responses. This is particularly useful for:

• Development: Understanding tool execution flow
• Debugging: Identifying which tools were called and their success/failure status
• Optimization: Monitoring tool usage patterns
• Troubleshooting: Seeing detailed error information when tools fail

Debugging Information Structure

Each response includes:

• toolsUsed: Array of tools executed with timestamps and success status
• debuggingInfo: Summary with tool count, names, and execution status

Example

{
  "success": true,
  "response": "I've analyzed and summarized your email.",
  "toolsUsed": [
    {
      "name": "analyzeEmail",
      "arguments": { "emailContent": {...} },
      "timestamp": "2024-01-15T10:30:45.123Z",
      "success": true
    }
  ],
  "debuggingInfo": {
    "toolsExecuted": 1,
    "toolsList": ["analyzeEmail"],
    "executionSummary": "analyzeEmail ✅"
  }
}

See DEBUGGING-EXAMPLE.md for detailed examples and testing instructions.

Contributing

1. Fork the repository
2. Create a feature branch
3. Add your new tool following the modular pattern
4. Add tests for your tool
5. Submit a pull request

Support

For issues and questions:

• Check the MCP Documentation
• Review the tool examples in src/tools/
• Ensure your OpenAI API key is properly configured