Meeting Scheduler MCP

# Meeting Scheduler MCP Natural Language Meeting Scheduling with Personal Touch ## The Problem with Scheduling Tools Traditional scheduling tools like Calendly and Cal.com feel transactional for important contacts: - Impersonal: Automated links lack human touch - Manual Hell: Calendar tab-switching between email and scheduling apps - Context Loss: No integration with email conversations Our Goal: Natural language scheduling that feels personal and integrates seamlessly with your email workflow. ## What We're Building A Mistral Le Chat powered meeting scheduler that combines: - Email Search: Find meeting requests in your inbox - Calendar Management: YAML-based scheduling with holidays support - Natural Language Interface: Chat-based scheduling workflow - Email Threading: Maintain conversation context with proper email headers ### Architecture Overview ```mermaid sequenceDiagram participant U as User participant L as Mistral Le Chat participant M as MCP Server participant I as IMAP Server participant Y as calendar.yaml U->>L: "Find a meeting request from Lisa" activate L L->>M: search_emails(query="Lisa") activate M M->>I: IMAP SEARCH activate I I-->>M: Email results deactivate I M-->>L: Email deactivate M L->>M: get_free_slots() activate M M->>Y: Read free slots activate Y Y-->>M: Available times deactivate Y M-->>L: Free slots deactivate M L-->>U: "Lisa wants to meet. You're free Tue 2pm or Thu 10am" U->>L: "Suggest Thursday, keep it casual" L-->>U: Draft preview U->>L: "Send it" L->>M: save_draft_and_block_slot(...) activate M M->>Y: Write blocked slot M->>I: IMAP APPEND to INBOX.Drafts M-->>L: Confirmation deactivate M L-->>U: "Draft saved, slot blocked" deactivate L ``` ## Tech Stack - Backend: Python 3.13+ with FastMCP - Email Integration: IMAP with TLS/SSL support - Calendar Storage: YAML file-based system - Transport: HTTP/SSE for Mistral connector - Data Models: Pydantic v2 for validation ## Features ### 1. Email Integration - IMAP Search: Find emails by criteria (sender, subject, etc.) - Email Threading: Maintain conversation context with Message-ID, In-Reply-To, References - Draft Management: Save email drafts with proper threading headers - TLS/SSL Support: Secure connections with configurable SSL options ### 2. Calendar Management - YAML Configuration: Simple, human-readable calendar format - Weekly Availability: Define working hours and available slots - Holiday Support: Automatic holiday detection (country-specific) - Time Zone Awareness: Full timezone support with ZoneInfo - Slot Finding: Intelligent free slot detection ### 3. Natural Language Workflow 1. Find Requests: "Find meeting requests from Lisa" 2. Get Availability: "What times am I free this week?" 3. Suggest Times: "Suggest Thursday morning" 4. Confirm & Block: "Confirm the meeting and block the slot" ## Getting Started ### Prerequisites - Python 3.13+ - IMAP-enabled email account - Mistral Le Chat integration ### Installation ```bash # Clone the repository uv add git+https://github.com/seb-schulz/meeting-scheduler-mcp.git # Install dependencies uv sync # Set up environment variables cp .env.example .env # Edit .env with your IMAP credentials ``` ### Configuration Create a `.env` file with your IMAP settings: ```env # Required settings IMAP_HOST=imap.example.com # IMAP server hostname IMAP_USER=your@email.com # IMAP username/email IMAP_PASSWORD=secure_password # IMAP password IMAP_FROM=your@email.com # From address for sent emails # TLS/SSL Configuration (optional with sensible defaults) IMAP_PORT=993 # IMAP port IMAP_USE_SSL=true # Use SSL/TLS IMAP_USE_STARTTLS=false # Use STARTTLS IMAP_VERIFY_SSL=true # Verify SSL certificates ``` ### Calendar Configuration Edit `calendar.yaml` to define your availability: ```yaml schedule: timezone: Europe/Berlin slot_duration: 30 holidays: DE weekly: - days: - mon - tue - wed - thu - fri slots: - start: 09:00:00 end: "12:00:00" - start: "13:00:00" end: "17:00:00" blocked: [] ``` ### Running the Server ```bash # Start the FastMCP server with Python module syntax uv run python -m meeting_scheduler_mcp # Server will be available at http://0.0.0.0:8000 ``` ## API Tools ### 1. `search_emails` Search emails with full metadata and threading support: ```python emails = search_emails( mailbox="INBOX", criteria="FROM lisa@example.com" ) # Returns: List of emails with id, subject, from, to, date, message_id, in_reply_to, references, body ``` ### 2. `get_free_slots` Get available time slots from your calendar: ```python free_slots = get_free_slots() # Returns: List of up to 50 available slots with date, start, end times, and timezone ``` ### 3. `save_draft_and_block_slot` Complete workflow: block calendar slot and save confirmation email draft: ```python result = save_draft_and_block_slot( datetime="2025-12-15T14:00:00+01:00", duration=30, reason="Meeting with Lisa", subject="Meeting Confirmed", body="Let's meet on Thursday at 2pm", to="lisa@example.com", in_reply_to="<original-message-id@example.com>" ) # Returns: {"success": true} or {"error": "message", "success": false} ``` ## Testing ### Unit Tests Run tests with: ```bash uv run pytest ``` ### Integration Tests with Docker Compose For IMAP integration testing, use Docker Compose with Greenmail: ```bash # Start Greenmail IMAP server cd .devcontainer docker-compose up -d greenmail # Seed test emails uv run python scripts/seed_test_emails.py # Run tests with test configuration IMAP_CONFIG=.env.test uv run pytest tests/test_integration.py ``` ### Test Coverage Run tests with coverage: ```bash uv run pytest --cov=meeting_scheduler_mcp --cov-report=term-missing ``` ## Contributing Contributions welcome! Please follow: - **Code Style**: Ruff linting rules - **Type Safety**: Full Pydantic v2 typing - **Testing**: Comprehensive pytest coverage - **Documentation**: Keep README updated ## License MIT License - See [LICENSE](LICENSE) for details. ## Learn More - [FastMCP Documentation](https://fastmcp.com) - [Pydantic v2](https://pydantic.dev) - [IMAP Protocol](https://tools.ietf.org/html/rfc3501)