swisspost-smart-address-mcp by AlfMueller - MCP Server

🇨🇭 Swisspost Smart Address MCP Server

Ein intelligenter Adress-Validator mit Swisspost API Integration, der als MCP (Model Context Protocol) Server fungiert. Der Agent erkennt und korrigiert automatisch häufige Adressfehler und nutzt die Swisspost Autocomplete-APIs für maximale Genauigkeit.

Keywords: swisspost mcp address-validation claude-desktop n8n switzerland postal-api address-correction automation

🚀 Features

🧠 Intelligente Adressanalyse

PLZ/Ort-Vertauschung - Erkennt automatisch wenn PLZ und Ort vertauscht wurden
Hausnummer-Erkennung - Trennt automatisch Hausnummern von Straßennamen
Stadtname-Korrektur - Korrigiert falsch geschriebene Ortsnamen (z.B. "Musterstadt" → "Musterstadt-Korrekt")
Adress-Normalisierung - Standardisiert Adressformate für bessere Validierung

🔗 Swisspost API Integration

ZIP-Autocomplete - Findet korrekte Ortsnamen basierend auf Postleitzahl
Street-Autocomplete - Korrigiert Straßennamen und Schreibweisen
House-Autocomplete - Validiert und korrigiert Hausnummern
Vollständige Adressvalidierung - Überprüft komplette Adressen mit Personendaten

⚡ Automatische Korrekturen

Echtzeit-Korrektur - Korrigiert Fehler während der Validierung
Fallback-Mechanismen - Bekannte Korrekturen für häufige Fehler
Qualitätsbewertung - Score von 0-100 basierend auf Swisspost-Qualitätsstufen
Detaillierte Rückmeldung - Zeigt alle durchgeführten Korrekturen an

🔧 Integration & Automatisierung

MCP Server - Nahtlose Integration in Claude Desktop und andere MCP-fähige Tools
n8n Workflow - Produktiver Webhook für Automatisierung
HTTP Proxy - Brücke zwischen n8n und MCP Server
REST API - Einfache Integration in bestehende Systeme

🔐 Sicherheit & Best Practices

Umgebungsvariablen - Credentials nur in .env Datei, keine hardcodierten Werte
OAuth2 Authentifizierung - Sichere API-Zugriffe mit Token-Management
Fehlerbehandlung - Robuste Behandlung von API-Fehlern und Timeouts
Logging - Detaillierte Protokollierung für Debugging und Monitoring

📋 Voraussetzungen

Python 3.8+
Swisspost API Credentials
MCP Inspector (optional, für Testing)

🛠️ Installation

1. Repository klonen/herunterladen

git clone <repository-url>
cd swissspost_mcp

2. Python Dependencies installieren

Option A: Mit requirements.txt (empfohlen)

pip install -r requirements.txt

Option B: Einzeln installieren

pip install httpx mcp python-dotenv

Hinweis: Falls Sie PlatformIO installiert haben, können Dependency-Konflikte auftreten. Diese beeinträchtigen die MCP-Funktionalität nicht.

3. Swisspost API Credentials besorgen

Registrieren Sie sich bei Swisspost Developer Portal
Erstellen Sie eine neue App
Notieren Sie sich Client ID und Client Secret

4. Umgebungsvariablen konfigurieren

Option A: .env Datei (empfohlen)

# .env Datei erstellen
# Linux/macOS:
cp config.env .env

# Windows:
copy config.env .env

# .env bearbeiten und echte Credentials eintragen
SWISSPOST_CLIENT_ID=ihre_echte_client_id
SWISSPOST_CLIENT_SECRET=ihr_echtes_secret
# Verfügbare Scopes siehe Abschnitt "API Scopes" unten
# WICHTIG: Für City Correction wird auch DCAPI_ADDRESS_AUTOCOMPLETE benötigt!
SWISSPOST_SCOPE=DCAPI_ADDRESS_VALIDATE DCAPI_ADDRESS_AUTOCOMPLETE DCAPI_ADDRESS_AUTOCOMPLETE

Hinweis: Die .env Datei wird automatisch geladen (python-dotenv). Keine manuellen Umgebungsvariablen nötig!

Option B: Direkt in PowerShell setzen

$env:SWISSPOST_CLIENT_ID="ihre_client_id"
$env:SWISSPOST_CLIENT_SECRET="ihr_secret"
$env:SWISSPOST_SCOPE="DCAPI_ADDRESS_VALIDATE DCAPI_ADDRESS_AUTOCOMPLETE"

Option C: config.env verwenden

# config.env Datei bearbeiten
notepad config.env

# Umgebungsvariablen laden (Windows PowerShell)
Get-Content config.env | ForEach-Object { 
    if($_ -match "^([^#][^=]+)=(.*)") { 
        [Environment]::SetEnvironmentVariable($matches[1], $matches[2], "Process") 
    } 
}

5. MCP Inspector installieren (optional)

npm install -g @modelcontextprotocol/inspector

🧪 Testing

Automatische Tests ausführen

python mcp-test-script.py

Das Test-Skript prüft automatisch 5 Problem-Szenarien:

✅ PLZ und Ort vertauscht - "8005" im Stadtfeld, "Zürich" im PLZ-Feld
✅ Hausnummer am Anfang - "94 Pfingstweidstrasse" statt "Pfingstweidstrasse 94"
✅ Abkürzungen - "Hauptstr." statt "Hauptstrasse"
✅ Verklebte Hausnummer - "Bahnhofstrasse43" ohne Leerzeichen
✅ Korrekte Adresse - Sollte ohne Änderungen durchgehen

MCP Inspector verwenden

# MCP Inspector starten
mcp-inspector

# Server starten (in separatem Terminal)
python smart-address-agent.py

Server direkt testen

# Server im MCP-Modus starten
python smart-address-agent.py

# In anderem Terminal: MCP Inspector verbinden
mcp-inspector

📖 Verwendung

Als MCP Server

WICHTIG: Der MCP Server muss immer zuerst gestartet werden!

Schritt 1: MCP Server starten

# Im Projektverzeichnis
python .\smart-address-agent.py

Der Server läuft dann im Hintergrund und wartet auf Verbindungen.

Schritt 2: Client verbinden

Option A: Claude Desktop

Konfigurationsdatei erstellen claude_desktop_config.json:

{
  "mcpServers": {
    "swisspost-address": {
      "command": "python",
      "args": ["/path/to/your/swissspost_mcp/smart-address-agent.py"],
      "cwd": "/path/to/your/swissspost_mcp"
    }
  }
}

Datei speichern in Claude Desktop Konfigurationsordner:
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Linux: ~/.config/claude/claude_desktop_config.json
Pfad anpassen in der Konfiguration (args-Array) auf Ihren tatsächlichen Pfad
.env Datei erstellen im Projektverzeichnis mit Ihren echten Credentials
Claude Desktop starten - Verbindet sich automatisch und lädt .env
Verwenden: "Validiere diese Adresse: Pfingstweidstrasse 94, 8005 Zürich"

Option B: MCP Inspector (für Tests)

# Terminal 1: Server starten
python .\smart-address-agent.py

# Terminal 2: Inspector starten
mcp-inspector

Option C: n8n Workflow (produktiv)

MCP Server + HTTP Proxy starten:

# Windows:
start-mcp-server-and-proxy.bat

# Linux/macOS:
chmod +x start-mcp-server-and-proxy.sh
./start-mcp-server-and-proxy.sh

n8n Workflow importieren:
- Workflow: n8n-workflows/swisspost-workflow.json
- Webhook URL: https://your-n8n-instance.com/webhook/swisspost-validate
Features des n8n Workflows:
- ✅ Automatische City-Correction (z.B. "Musterstadt" → "Musterstadt-Korrekt")
- ✅ Vollständige Adressvalidierung mit Personendaten
- ✅ Qualitätsbewertung (Score 0-100)
- ✅ Detaillierte Korrekturen mit Rückmeldung
- ✅ REST API für einfache Integration
- ✅ Produktiver Webhook der dauerhaft läuft

🔌 MCP Kommunikation

WICHTIG: MCP nutzt KEINEN Port!

Kommunikationsart:

STDIO (Standard Input/Output)
JSON-RPC über stdin/stdout
Prozess-zu-Prozess Kommunikation

Warum kein Port?

Sicherer - keine Netzwerk-Exposition
Einfacher - keine Port-Konflikte
Standard - MCP-Protokoll nutzt STDIO

Verbindungsarten:

Claude Desktop: Startet Server als Subprozess
n8n: Verbindet sich über MCP-Connector
MCP Inspector: Testet über STDIO-Verbindung

⚠️ WICHTIG: MCP Server muss auf dem Client laufen

Warum lokal?

STDIO-Kommunikation erfordert lokale Prozesse
Keine Netzwerk-Verbindung möglich
Sicherheit - keine externe Server nötig

Deployment-Optionen:

Option 1: Lokal auf jedem Client

# Auf jedem Rechner installieren
git clone <repository>
cd swissspost_mcp
pip install -r requirements.txt
python smart-address-agent.py

Option 2: Docker Container (lokal)

# Dockerfile erstellen
FROM python:3.12
COPY . /app
WORKDIR /app
RUN pip install -r requirements.txt
CMD ["python", "smart-address-agent.py"]

Option 3: Windows Service

# Als Windows Service installieren
sc create SwisspostMCP binPath="python C:\path\to\smart-address-agent.py"

Für n8n:

n8n Server muss auf demselben Rechner laufen
MCP Server muss lokal verfügbar sein
Keine Remote-Verbindung möglich

Direkt als Python Modul

from smart_address_agent import SmartAddressAgent

agent = SmartAddressAgent()
result = await agent.validate_smart({
    'street': 'Pfingstweidstrasse 94',
    'city': 'Zürich',
    'postcode': '8005'
})
print(result)

🔧 API Referenz

Tool: `validate_address_smart`

Eingabe:

street (required): Straße mit oder ohne Hausnummer
city (required): Ort
postcode (required): Postleitzahl
firstname (optional): Vorname
lastname (optional): Nachname
company (optional): Firma

Ausgabe:

{
  "status": "success|failed",
  "quality": "CERTIFIED|VERIFIED|USABLE|UNUSABLE",
  "score": 0-100,
  "corrections": [
    {
      "type": "swap_plz_city|city_corrected|street_corrected|house_number_corrected",
      "message": "Beschreibung der Korrektur",
      "old": "Ursprünglicher Wert",
      "new": "Korrigierter Wert"
    }
  ],
  "corrected": {
    "street_name": "Korrigierter Straßenname",
    "house_number": "Korrigierte Hausnummer",
    "city": "Korrigierter Ort",
    "postcode": "PLZ",
    "street_full": "Vollständige Straße"
  }
}

🏗️ Architektur

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Input         │    │  Address Analyzer│    │  Swisspost APIs │
│   Adresse       │───▶│  - PLZ/Ort Swap  │───▶│  - ZIP Lookup   │
│                 │    │  - Street Split  │    │  - Street Lookup│
└─────────────────┘    │  - Normalization │    │  - House Lookup │
                       └──────────────────┘    └─────────────────┘
                                │                        │
                                ▼                        ▼
                       ┌──────────────────┐    ┌─────────────────┐
                       │  Corrections     │    │  Final          │
                       │  - Auto-fix      │    │  Validation     │
                       │  - Quality Score │    │  - Swisspost    │
                       └──────────────────┘    └─────────────────┘

📁 Projektstruktur

swissspost_mcp/
├── smart-address-agent.py    # Haupt-MCP-Server
├── mcp-test-script.py        # Automatische Tests
├── config.env               # Umgebungsvariablen Template
├── .env                     # Ihre echten Credentials (wird automatisch geladen)
├── start-mcp-server.bat     # Start-Skript MCP Server (Windows)
├── start-mcp-server.sh      # Start-Skript MCP Server (Linux/macOS)
├── start-mcp-server-and-proxy.bat  # Start-Skript MCP + Proxy (Windows)
├── start-mcp-server-and-proxy.sh   # Start-Skript MCP + Proxy (Linux/macOS)
├── n8n-workflows/           # n8n Workflow für Adressvalidierung
│   ├── swisspost-workflow.json      # n8n Workflow
│   ├── http-proxy.py                # HTTP-Proxy für MCP
│   ├── test-swisspost-workflow.js   # Test Script
│   ├── package.json
│   └── README.md
├── README.md                # Diese Dokumentation
└── requirements.txt         # Python Dependencies (optional)

🔧 Verfügbare Tools

`validate_address_smart`

Das einzige verfügbare Tool für die intelligente Adressvalidierung.

Eingabeparameter:

street (required): Straße mit oder ohne Hausnummer
city (required): Ort
postcode (required): Postleitzahl
firstname (optional): Vorname
lastname (optional): Nachname
company (optional): Firma

Ausgabeformat:

status: "success" oder "failed"
quality: Swisspost Qualitätsbewertung
score: Numerischer Score (0-100)
corrections: Array aller vorgenommenen Korrekturen
corrected: Finale, validierte Adresse
validation: Vollständige Swisspost API Antwort

🐛 Troubleshooting

Häufige Probleme

1. "Credentials müssen gesetzt sein"

# Prüfen Sie Ihre Umgebungsvariablen
echo $env:SWISSPOST_CLIENT_ID
echo $env:SWISSPOST_CLIENT_SECRET

2. "Kann server.py nicht importieren"

# Stellen Sie sicher, dass Sie im richtigen Verzeichnis sind
cd /path/to/your/swissspost_mcp

3. "OAuth Fehler"

Überprüfen Sie Ihre API Credentials
Stellen Sie sicher, dass Ihr API-Account aktiv ist
Prüfen Sie die Scope-Berechtigung

4. "Timeout Fehler"

Überprüfen Sie Ihre Internetverbindung
Swisspost API könnte temporär nicht verfügbar sein

5. "Import mcp.server could not be resolved"

# MCP Paket installieren
pip install mcp

6. "Kann server.py nicht importieren" (Test-Skript)

# Stellen Sie sicher, dass smart-address-agent.py im gleichen Verzeichnis ist
# Das Test-Skript sucht nach 'server.py', aber die Datei heißt 'smart-address-agent.py'

7. ".env Datei wird nicht geladen"

# Stellen Sie sicher, dass python-dotenv installiert ist
pip install python-dotenv

# .env Datei im gleichen Verzeichnis wie smart-address-agent.py
# Format: SWISSPOST_CLIENT_ID=ihre_client_id

Debug-Modus

# In smart-address-agent.py Debug-Ausgaben aktivieren
import logging
logging.basicConfig(level=logging.DEBUG)

📝 Lizenz

MIT License - siehe LICENSE Datei für Details.

🤝 Contributing

Fork das Repository
Erstellen Sie einen Feature Branch
Committen Sie Ihre Änderungen
Pushen Sie zum Branch
Erstellen Sie einen Pull Request

📚 API Dokumentation

n8n Webhook API

Endpoint: https://your-n8n-instance.com/webhook/swisspost-validate Method: POST Content-Type: application/json

Request Format:

{
  "company": "Firmenname GmbH",
  "firstname": "Max",
  "lastname": "Mustermann",
  "street": "Bahnhofstrasse 1",
  "city": "Zürich",
  "postcode": "8001"
}

Response Format:

{
  "success": true,
  "data": {
    "status": "success",
    "quality": "CERTIFIED",
    "score": 100,
    "corrections": [
      {
        "type": "city_corrected",
        "message": "Ortsname korrigiert via Fallback-Lookup",
        "old": "Musterstadt",
        "new": "Musterstadt-Korrekt"
      }
    ],
    "input": {
      "street": "Musterstrasse 123",
      "city": "Musterstadt",
      "postcode": "8001"
    },
    "corrected": {
      "street_name": "Musterstrasse",
      "house_number": "123",
      "city": "Musterstadt-Korrekt",
      "postcode": "8001",
      "street_full": "Musterstrasse 123"
    },
    "validation": {
      "quality": "DOMICILE_CERTIFIED",
      "expires": "20251003T002909+0200",
      "address": {
        "type": "DOMICILE",
        "addressee": {
          "firstName": "Max",
          "lastName": "Mustermann",
          "companyName": "Beispiel GmbH"
        },
        "geographicLocation": {
          "house": {
            "street": "Musterstrasse",
            "houseNumber": "123",
            "houseKey": "12345678"
          },
          "zip": {
            "zip": "8001",
            "city": "Musterstadt-Korrekt"
          }
        },
        "id": "dba6e3d2-904d-4676-978b-0f86558db187"
      }
    },
    "has_corrections": true
  },
  "timestamp": 1759440549.6417124
}

Qualitätsstufen:

CERTIFIED / DOMICILE_CERTIFIED - Höchste Qualität (Score: 100)
USABLE - Gute Qualität (Score: 80-99)
UNUSABLE - Niedrige Qualität (Score: 0-79)

Korrektur-Typen:

city_corrected - Ortsname korrigiert
street_corrected - Straßenname korrigiert
house_number_corrected - Hausnummer korrigiert
swap_plz_city - PLZ und Ort waren vertauscht

cURL Beispiel:

curl -X POST https://your-n8n-instance.com/webhook/swisspost-validate \
  -H "Content-Type: application/json" \
  -d '{
    "company": "Beispiel GmbH",
    "firstname": "Max",
    "lastname": "Mustermann",
    "street": "Musterstrasse 123",
    "city": "Musterstadt",
    "postcode": "8001"
  }'

📞 Support

Bei Problemen oder Fragen:

Erstellen Sie ein Issue im Repository
Überprüfen Sie die Swisspost API Dokumentation
Schauen Sie in die Troubleshooting Sektion

🚀 Quick Start

Option A: Mit Start-Skripten (empfohlen)

Nur MCP Server (für Claude Desktop):

# Windows:
start-mcp-server.bat

# Linux/macOS:
chmod +x start-mcp-server.sh
./start-mcp-server.sh

MCP Server + HTTP Proxy (für n8n):

# Windows:
start-mcp-server-and-proxy.bat

# Linux/macOS:
chmod +x start-mcp-server-and-proxy.sh
./start-mcp-server-and-proxy.sh

Option B: Manuell

# 1. Dependencies installieren
pip install -r requirements.txt

# 2. .env Datei erstellen und Credentials eintragen
# Linux/macOS:
cp config.env .env

# Windows:
copy config.env .env

# .env bearbeiten mit echten Credentials

⚠️ **SICHERHEIT**: Die `.env` Datei ist in `.gitignore` und wird nicht committet!

# 3. Testen
python mcp-test-script.py

# 4. MCP Server starten (WICHTIG: Immer zuerst!)
python smart-address-agent.py

# 5. Client verbinden (Claude Desktop, n8n, oder MCP Inspector)

🔄 Workflow für verschiedene Clients

n8n Workflow

Für n8n Integration siehe den separaten n8n-workflows/ Ordner:

cd n8n-workflows
npm test  # Teste den n8n Workflow

Verfügbarer n8n Workflow:

Swisspost Workflow: Intelligente Adressvalidierung mit Monitoring
HTTP Proxy: HTTP-Proxy für MCP-Integration
Test Script: Automatische Tests für alle Szenarien

Siehe n8n-workflows/README.md für detaillierte Anleitung.

Claude Desktop

Konfiguration erstellen: claude_desktop_config.json
Pfad anpassen und Credentials eintragen
Claude Desktop starten (startet Server automatisch)
Verwenden: "Validiere diese Adresse: ..."

Detaillierte Claude Desktop Anleitung:

Schritt 1: Konfigurationsdatei erstellen

# Beispiel-Konfiguration kopieren
cp claude_desktop_config.json %APPDATA%\Claude\claude_desktop_config.json

Schritt 2: Konfiguration anpassen

{
  "mcpServers": {
    "swisspost-address": {
      "command": "python",
      "args": ["/path/to/your/swissspost_mcp/smart-address-agent.py"],
      "cwd": "/path/to/your/swissspost_mcp"
    }
  }
}

Wichtige Änderungen:

✅ Keine hardcodierten Credentials mehr in der Konfiguration
✅ cwd Parameter hinzugefügt für korrekte .env Ladung
✅ Sicherheit verbessert - Credentials nur in .env Datei

Pfad anpassen:

Windows: C:\\swissspost_mcp\\smart-address-agent.py
macOS: /Users/username/swissspost_mcp/smart-address-agent.py
Linux: /home/username/swissspost_mcp/smart-address-agent.py

Schritt 3: .env Datei erstellen

# Im Projektverzeichnis .env Datei erstellen
# Linux/macOS:
cp config.env .env

# Windows:
copy config.env .env

# Dann .env bearbeiten und echte Credentials eintragen:
SWISSPOST_CLIENT_ID=ihre_echte_client_id
SWISSPOST_CLIENT_SECRET=ihr_echtes_secret
SWISSPOST_SCOPE=DCAPI_ADDRESS_VALIDATE DCAPI_ADDRESS_AUTOCOMPLETE

Schritt 4: Claude Desktop starten

Claude Desktop startet automatisch den MCP Server
MCP lädt automatisch die .env Datei
Kein manueller Server-Start nötig

n8n

Server starten: python smart-address-agent.py
n8n MCP-Connector konfigurieren
Workflow mit Adressvalidierung erstellen

MCP Inspector (Tests)

Terminal 1: python smart-address-agent.py
Terminal 2: mcp-inspector
Verbindung herstellen und testen

📊 Qualitätsbewertungen

Quality	Score	Beschreibung
`DOMICILE_CERTIFIED`	100	Vollständig zertifiziert
`CERTIFIED`	100	Zertifiziert
`VERIFIED`	90	Verifiziert
`USABLE`	50	Verwendbar
`COMPROMISED`	60	Kompromittiert
`UNUSABLE`	0	Nicht verwendbar

🔍 Korrekturtypen

comma_removed_from_street: Komma aus Straßenname entfernt
house_number_moved_to_end: Hausnummer vom Anfang der Straße ans Ende verschoben
street_name_capitalized: Straßenname mit Großbuchstaben am Anfang korrigiert
street_from_api_enforced: Strasse aus SwissPost API übernommen
house_number_from_api_enforced: Hausnummer aus SwissPost API übernommen
house_number_from_street2: Hausnummer aus street2 übernommen
street2_capitalized: street2 in Großbuchstaben korrigiert
garbage_cleaned: Müll-Strings (nur Bindestriche/Zahlen) entfernt
swap_plz_city: PLZ und Ort waren vertauscht
city_corrected: Ortsname via ZIP-Lookup korrigiert
street_abbreviation_expanded: Strassen-Abkürzung wurde erweitert
street_corrected: Straßenname via Street-Lookup korrigiert
house_number_corrected: Hausnummer via House-Lookup korrigiert
street_corrected_after_usable: Straßenname nach USABLE-Resultat via Street-Lookup verbessert
city_corrected_after_usable: Ort nach USABLE-Resultat via ZIP-Lookup verbessert
firstname_formatted: Vorname in konsistente Schreibweise formatiert
lastname_formatted: Nachname in konsistente Schreibweise formatiert
company_legal_form_normalized: Rechtsform in Firmenname normalisiert

Beispiel für company_legal_form_normalized

{
  "corrections": [
    {
      "type": "company_legal_form_normalized",
      "message": "Rechtsform in Firmenname normalisiert",
      "old": "testfirma gmbh",
      "new": "testfirma GmbH"
    }
  ]
}

🔐 Sicherheit & Best Practices

Sichere Konfiguration (NEU!)

✅ Empfohlene Konfiguration:

{
  "mcpServers": {
    "swisspost-address": {
      "command": "python",
      "args": ["/path/to/your/swissspost_mcp/smart-address-agent.py"],
      "cwd": "/path/to/your/swissspost_mcp"
    }
  }
}

❌ Vermeiden Sie:

{
  "mcpServers": {
    "swisspost-address": {
      "command": "python",
      "args": ["/path/to/your/swissspost_mcp/smart-address-agent.py"],
      "env": {
        "SWISSPOST_CLIENT_ID": "hardcoded_credentials",  // ❌ Sicherheitsrisiko!
        "SWISSPOST_CLIENT_SECRET": "hardcoded_secret"    // ❌ Sicherheitsrisiko!
      }
    }
  }
}

Warum .env verwenden?

Sicherheit - Credentials werden nicht in Git committet
Flexibilität - Einfacher Wechsel zwischen Umgebungen
Wartbarkeit - Keine doppelten Credential-Definitionen
Best Practice - Standard für sensible Konfigurationsdaten

.env Datei Setup

# .env Datei im Projektverzeichnis erstellen
SWISSPOST_CLIENT_ID=ihre_echte_client_id
SWISSPOST_CLIENT_SECRET=ihr_echtes_secret
SWISSPOST_SCOPE=DCAPI_ADDRESS_VALIDATE DCAPI_ADDRESS_AUTOCOMPLETE

Wichtig: Die .env Datei ist in .gitignore und wird NICHT hochgeladen!

🔐 API Scopes

Die Swisspost Digital Commerce API bietet verschiedene Berechtigungsbereiche (Scopes):

Adress-Services

DCAPI_ADDRESS_READ - Lesen von Adressdaten
DCAPI_ADDRESS_VALIDATE - Validierung von Adressen (Standard für dieses Projekt)
DCAPI_ADDRESS_AUTOCOMPLETE - Autocomplete für Städte, Straßen und Hausnummern (Für City Correction erforderlich)

Versand-Services

DCAPI_SHIPPING - Zugriff auf Versanddienste
DCAPI_TRACKING - Sendungsverfolgung

Barcode-Services

DCAPI_BARCODE - Barcode-Generierung für Sendungen

Scope-Konfiguration

Für Adressvalidierung (empfohlen):

SWISSPOST_SCOPE=DCAPI_ADDRESS_VALIDATE DCAPI_ADDRESS_AUTOCOMPLETE

Für erweiterte Adressfunktionen:

SWISSPOST_SCOPE=DCAPI_ADDRESS_READ DCAPI_ADDRESS_VALIDATE DCAPI_ADDRESS_AUTOCOMPLETE

Für Versanddienste:

SWISSPOST_SCOPE=DCAPI_SHIPPING DCAPI_TRACKING

Hinweis: Die genauen verfügbaren Scopes können je nach API-Version und Ihrem Account variieren. Konsultieren Sie die Swisspost API Dokumentation für die aktuellsten Informationen.

Entwickelt mit ❤️ für die Schweizer Adressvalidierung

AlfMueller/swisspost-smart-address-mcp

🇨🇭 Swisspost Smart Address MCP Server

🚀 Features

🧠 Intelligente Adressanalyse

🔗 Swisspost API Integration

⚡ Automatische Korrekturen

🔧 Integration & Automatisierung

🔐 Sicherheit & Best Practices

📋 Voraussetzungen

🛠️ Installation

1. Repository klonen/herunterladen

2. Python Dependencies installieren

3. Swisspost API Credentials besorgen

4. Umgebungsvariablen konfigurieren

5. MCP Inspector installieren (optional)

🧪 Testing

Automatische Tests ausführen

MCP Inspector verwenden

Server direkt testen

📖 Verwendung

Als MCP Server

Schritt 1: MCP Server starten

Schritt 2: Client verbinden

🔌 MCP Kommunikation

Kommunikationsart:

Warum kein Port?

Verbindungsarten:

⚠️ WICHTIG: MCP Server muss auf dem Client laufen

Warum lokal?

Deployment-Optionen:

Option 1: Lokal auf jedem Client

Option 2: Docker Container (lokal)

Option 3: Windows Service

Für n8n:

Direkt als Python Modul

🔧 API Referenz

Tool: validate_address_smart

🏗️ Architektur

📁 Projektstruktur

🔧 Verfügbare Tools

validate_address_smart

🐛 Troubleshooting

Häufige Probleme

Debug-Modus

📝 Lizenz

🤝 Contributing

📚 API Dokumentation

n8n Webhook API

Request Format:

Response Format:

Qualitätsstufen:

Korrektur-Typen:

cURL Beispiel:

📞 Support

🚀 Quick Start

Option A: Mit Start-Skripten (empfohlen)

Option B: Manuell

🔄 Workflow für verschiedene Clients

n8n Workflow

Claude Desktop

Detaillierte Claude Desktop Anleitung:

n8n

MCP Inspector (Tests)

📊 Qualitätsbewertungen

🔍 Korrekturtypen

Beispiel für company_legal_form_normalized

🔐 Sicherheit & Best Practices

Sichere Konfiguration (NEU!)

Warum .env verwenden?

.env Datei Setup

🔐 API Scopes

Adress-Services

Versand-Services

Barcode-Services

Scope-Konfiguration

Tool: `validate_address_smart`

`validate_address_smart`