# MCP Email Server

A Dockerized MCP (Model Context Protocol) email assistant for law firms and legal teams.

Integrates:
- IMAP/SMTP email operations
- Shared/public folder support
- New-message tracking and flagging
- Conflict check search
- CalDAV/CardDAV (e.g., Nextcloud) for calendar and contacts
- Triage guidance using personnel/chain-of-command

Designed to be consumed by LLMs via MCP (Streamable HTTP) in Open WebUI.

## Quick start

1. Build:

   docker build -t mcp-email-server /home/user/wall-o/mcp-email-server

2. Run (example):

   docker run -d \
     -p 8000:8000 \
     -e API_KEY="your_api_key_here" \
     -e LOG_LEVEL="DEBUG" \
     -e IMAP_HOST=imap.example.com \
     -e IMAP_PORT=993 \
     -e IMAP_USE_SSL=true \
     -e IMAP_USERNAME="user@example.com" \
     -e IMAP_PASSWORD="secret" \
     -e SMTP_HOST=smtp.example.com \
     -e SMTP_PORT=587 \
     -e SMTP_USE_TLS=true \
     -e SMTP_USE_SSL=false \
     -e SMTP_USERNAME="user@example.com" \
     -e SMTP_PASSWORD="secret" \
     -e SMTP_FROM="user@example.com" \
     -e DEFAULT_CC="supervisor@example.com" \
     -e BUSINESS_DESCRIPTION="A law firm handling corporate and litigation matters." \
     -e PERSONNEL_JSON='[{"name":"Jane Doe","role":"Managing Partner","email":"jane@example.com","escalates_to":null},{"name":"John Smith","role":"Associate","email":"john@example.com","escalates_to":"Jane Doe"}]' \
     mcp-email-server

3. Health check:

   http://localhost:8000/health

4. MCP endpoint:

   - POST http://localhost:8000/mcp
   - Uses JSON-RPC 2.0 (methods: initialize, tools/list, tools/call)

5. Integrate with Open WebUI (MCP Streamable HTTP):

   - Admin Settings → External Tools → Add Server
   - Type: MCP (Streamable HTTP)
   - Server URL: http://<your-server>:8000/mcp
   - Auth: Bearer
   - Key: your_api_key_here
   - Save, then enable tools in a chat.

## Environment variables

See env.example for a full list.

Core:

- API_KEY:
  - If set, all /mcp requests must include:
    Authorization: Bearer <API_KEY>
  - Leave empty to disable auth (not recommended in production).

- LOG_LEVEL:
  - e.g., INFO, DEBUG, ERROR (default: INFO)

IMAP (incoming mail):

- IMAP_HOST
- IMAP_PORT
- IMAP_USE_SSL
- IMAP_USERNAME
- IMAP_PASSWORD

SMTP (outgoing mail):

- SMTP_HOST
- SMTP_PORT
- SMTP_USE_TLS
- SMTP_USE_SSL
- SMTP_USERNAME
- SMTP_PASSWORD
- SMTP_FROM

Optional email:

- DEFAULT_CC: Comma-separated CC addresses.
- DEFAULT_BCC: Comma-separated BCC addresses.
- BUSINESS_DESCRIPTION: Context for the LLM (e.g., firm description).
- PERSONNEL_JSON: JSON array of personnel/chain-of-command:
  - Example:
    [
      {
        "name": "Jane Doe",
        "role": "Managing Partner",
        "email": "jane@example.com",
        "escalates_to": null
      },
      {
        "name": "John Smith",
        "role": "Associate",
        "email": "john@example.com",
        "escalates_to": "Jane Doe"
      }
    ]
- SCHEDULED_SEND_INTERVAL: Seconds between checks for scheduled emails (default: 10).

CalDAV/CardDAV (e.g., Nextcloud):

- DAV_BASE_URL: Base DAV URL (e.g., https://cloud.example.com/remote.php/dav)
- DAV_USERNAME
- DAV_PASSWORD
- DAV_VERIFY_TLS: true/false (default: true)

## MCP tools

All tools are exposed via MCP (Streamable HTTP) at POST /mcp.

Email:

- list_folders
- search_messages
- get_new_messages
- sync_seen
- mark_as_read
- flag_message
- move_message
- copy_message
- apply_label
- remove_label
- list_labels
- get_unread_summary
- send_email
- reply_to_message
- forward_message
- save_draft
- list_attachments
- download_attachment
- search_attachments
- schedule_send
- export_conversation
- conflict_check_search
- get_triage_config

Contacts (CardDAV):

- list_carddav_addressbooks
- search_carddav_contacts
- get_carddav_contact
- create_carddav_contact
- update_carddav_contact
- delete_carddav_contact

Calendar (CalDAV):

- list_caldav_calendars
- search_caldav_events
- create_caldav_event
- update_caldav_event
- delete_caldav_event

## Notes

- IMAP operations use UIDs for stability.
- Conflict check search scans subject lines across specified folders for given terms.
- New-message tracking is in-memory per container instance.
- For production:
  - Always set API_KEY.
  - Use HTTPS and secure IMAP/SMTP settings.