MCP 服务器

MCP Mail Server

Automates email handling for a hardware store, enabling classification, response generation, and escalation using AI.

README

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)

Skapa projekt i Google Cloud Console
Aktivera Gmail API
Skapa OAuth 2.0-credentials (Desktop app)
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.