MCP Mail Server - Bengtssons Trävaror

En MCP-server (Model Context Protocol) för automatisk e-posthantering hos ett fiktivt byggvaruhus.

Arkitektur

┌─────────────────────────────────────────────────────────────────────────────┐
│                              MCP-ARKITEKTUR                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│   ┌─────────────────────────┐         ┌─────────────────────────────────┐   │
│   │      MCP-KLIENT         │         │         MCP-SERVER              │   │
│   │     (mcp_client.py)     │         │        (server.py)              │   │
│   │                         │         │                                 │   │
│   │  "Hjärnan" - BESTÄMMER  │  stdio  │  "Händerna" - UTFÖR arbete     │   │
│   │                         │ ◄─────► │                                 │   │
│   │  • AI-klassificering    │   MCP   │  • Hämta mail                   │   │
│   │  • Beslut om åtgärd     │ proto-  │  • Skicka svar                  │   │
│   │  • Anropar rätt tool    │   col   │  • Logga ärenden                │   │
│   │                         │         │  • Beräkna material             │   │
│   └─────────────────────────┘         └─────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Flödesdiagram

┌──────────────────────────────────────────────────────────────────────────────┐
│                           MAIL-HANTERINGSFLÖDE                               │
└──────────────────────────────────────────────────────────────────────────────┘

    KLIENT (AI-beslut)                         SERVER (Tool-exekvering)
    ══════════════════                         ═══════════════════════

    ┌─────────────┐
    │   START     │
    └──────┬──────┘
           │
           ▼
    ┌─────────────┐      get_unread_emails()      ┌─────────────────┐
    │ Hämta mail  │ ─────────────────────────────►│ Returnerar JSON │
    └──────┬──────┘                               │ med alla mail   │
           │◄─────────────────────────────────────└─────────────────┘
           │
           ▼
    ┌─────────────────┐
    │  För varje mail │
    └────────┬────────┘
             │
             ▼
    ┌─────────────────────┐
    │  AI KLASSIFICERAR   │  (Gemini 2.0 Flash)
    │                     │
    │  Kategorier:        │
    │  • support          │
    │  • sales            │
    │  • estimate         │
    │  • meeting          │
    │  • other            │
    │                     │
    │  Prioritet:         │
    │  • high_priority    │
    └─────────┬───────────┘
              │
              ▼
    ┌─────────────────────┐
    │  HÖG PRIORITET?     │
    │         │           │
    │    JA ──┴── NEJ     │
    │    │                │
    │    ▼                │
    │  notify_manager()   │
    │  (mail till chef)   │
    └─────────┬───────────┘
              │
              ▼
    ┌─────────────────────┐
    │ Anropa rätt handler │
    └─────────┬───────────┘
              │
     ┌────────┴────────┬─────────────────┬─────────────────┐
     ▼                 ▼                 ▼                 ▼
┌─────────┐      ┌─────────┐      ┌─────────────┐   ┌─────────┐
│ support │      │  sales  │      │  estimate   │   │ meeting │
└────┬────┘      └────┬────┘      └──────┬──────┘   └────┬────┘
     │                │                  │               │
     ▼                ▼                  ▼               ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                              SERVER TOOLS                                    │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  handle_support_email()    handle_sales_email()    handle_estimate_email()  │
│  ├─ Logga klagomål        ├─ Sök produkter        ├─ AI beräknar material  │
│  ├─ AI genererar svar     ├─ Formatera svar       ├─ Beräkna priser        │
│  └─ Skicka mail           └─ Skicka mail          └─ Skicka mail           │
│                                                                             │
│  handle_meeting_email()                                                     │
│  ├─ Notera önskad tid                                                       │
│  └─ Skicka bekräftelse                                                      │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
              │
              ▼
    ┌─────────────────┐
    │ Nästa mail...   │
    └─────────────────┘

Filstruktur

MCP-Mail-Server/
├── server.py              # MCP-server med tools och resources
├── mcp_client.py          # Autonom klient med AI-klassificering
├── core/
│   ├── __init__.py
│   ├── agents.py          # AI-agenter (ComplaintAgent, SalesAgent)
│   ├── autoresponder.py   # Gmail API-integration
│   ├── conversations.py   # Konversationshistorik per kund
│   ├── products.py        # Produktkatalog
│   └── test_data.py       # Testmail för demonstration
├── conversations.json     # Kundhistorik (ej i repo, GDPR)
├── credentials.json       # Google OAuth (ej i repo)
├── .env                   # API-nycklar (ej i repo)
└── requirements.txt

Tools (server.py)

Tool	Beskrivning	Input
get_unread_emails	Hämtar alla olästa mail från inkorgen	-
handle_support_email	Hanterar klagomål: loggar, genererar AI-svar, skickar	from_email, subject, body
handle_sales_email	Hanterar produktförfrågningar: söker, formaterar, skickar	from_email, subject, product_query
handle_estimate_email	Hanterar materialberäkningar: AI-beräkning, prissättning, skickar	from_email, subject, project_description
handle_meeting_email	Hanterar mötesförfrågningar: noterar tid, skickar bekräftelse	from_email, subject, meeting_time (valfri)
notify_manager	Skickar eskalering till chef vid högprioriterade ärenden	from_email, subject, body, email_type

Resources (server.py)

Resource	Beskrivning
products://catalog	Produktkatalog med priser och dimensioner

Core-moduler

agents.py

Klass	Metod	Beskrivning
BaseAgent	run_llm()	Kör prompt mot Gemini, returnerar text
BaseAgent	run_llm_json()	Kör prompt, returnerar JSON
ComplaintAgent	write_response_to_complaint()	Genererar svar på klagomål (med konversationshistorik)
SalesAgent	estimate_materials_json()	Beräknar materialåtgång för byggprojekt

conversations.py

Funktion	Beskrivning
add_message()	Sparar ett meddelande i historiken
get_history()	Hämtar konversationshistorik för en kund
format_history_for_prompt()	Formaterar historik för AI-prompten

autoresponder.py

Klass	Metod	Beskrivning
AutoResponder	_send_email()	Skickar mail via Gmail API

products.py

Konstant	Beskrivning
PRODUCTS	Dict med produkter: {namn: (pris, dimension)}

Installation

# Klona och installera
cd MCP-Mail-Server
python -m venv venv
venv\Scripts\activate          # Windows
pip install -r requirements.txt

# Konfigurera
cp .env.example .env
# Redigera .env med din GEMINI_API_KEY

Konfiguration

Miljövariabler (.env)

GEMINI_API_KEY=din-api-nyckel
SENDER_EMAIL=din@email.com
USE_GMAIL=false                # true för att läsa från riktig Gmail
SEND_REAL_EMAILS=false         # true för att skicka riktiga mail
MANAGER_EMAIL=chef@foretag.se  # Mail för eskalering av högprioriterade ärenden

Google OAuth (för Gmail-utskick)

1. Skapa projekt i Google Cloud Console
2. Aktivera Gmail API
3. Skapa OAuth 2.0-credentials (Desktop app)
4. Ladda ner credentials.json till projektmappen

Användning

Kör den autonoma klienten

# Kör en gång
python mcp_client.py

# Kör kontinuerligt (var 5:e minut)
python mcp_client.py --loop

# Kör kontinuerligt med eget intervall (var 60:e minut)
python mcp_client.py --loop 60

Klienten startar MCP-servern automatiskt, hämtar mail, klassificerar och hanterar dem.

Använd med Claude Desktop

Lägg till i claude_desktop_config.json:

{
  "mcpServers": {
    "bengtssons-travaror": {
      "command": "python",
      "args": ["server.py"],
      "cwd": "c:/Users/henri/source/repos/Python/MCP-Mail-Server",
      "env": {
        "GEMINI_API_KEY": "din-api-nyckel"
      }
    }
  }
}

MCP-principen

┌────────────────────────────────────────────────────────────────┐
│                                                                │
│   KLIENT = AI som BESTÄMMER           SERVER = Tools som GÖR   │
│                                                                │
│   • Klassificering sker i klienten    • Inga AI-beslut         │
│   • Väljer vilken tool att anropa     • Utför instruktioner    │
│   • Styr hela arbetsflödet            • Returnerar resultat    │
│                                                                │
└────────────────────────────────────────────────────────────────┘

Denna arkitektur följer MCP-standarden där:

• Servern exponerar verktyg (tools) och data (resources)
• Klienten innehåller AI-logiken som fattar beslut

Prioritering och eskalering

AI:n klassificerar varje mail med en high_priority-flagga. Högprioriterade ärenden eskaleras automatiskt till chefen via mail.

Vad triggar hög prioritet?

• Kunden hotar med myndigheter, advokat, media
• Kunden säger att de byter leverantör/konkurrent
• Återkommande problem ("igen", "tredje gången")
• Kunden kräver svar från chef/ansvarig
• Mycket aggressiv ton med hot eller ultimatum

Vad är INTE hög prioritet?

• Vanliga klagomål utan hot
• Kunden är lite irriterad men inte arg
• Första gången kunden klagar

Vid hög prioritet skickas ett mail till MANAGER_EMAIL med ärendeinformation, sedan hanteras mailet som vanligt.