Filialsucher

Model Context Protocol (MCP) Server für Sparkasse Filial- und Geldautomatensuche.

Übersicht

Dieser MCP Server ermöglicht AI-Assistenten und anderen MCP Clients den standardisierten Zugriff auf Sparkasse Filial- und Geldautomaten-Standortdaten. Die Implementierung folgt einer klaren Schichtenarchitektur und demonstriert professionelle Software-Engineering-Praktiken.

⚠️ Mock-Modus: Die aktuelle Implementation nutzt MockFilialfinderClient mit realistischen Beispieldaten, da kein Zugriff auf die Sparkasse REST API besteht. Ein RealFilialfinderClient kann via FilialfinderPort-Interface eingepluggt werden, sobald API-Zugangsdaten verfügbar sind.

Architektur

Das Projekt folgt einer sauberen Schichtenarchitektur:

• Domain Layer (domain/): Business-Modelle und View-Model-Mappings
• Infrastructure Layer (infra/): Port-Interface und Client-Implementierungen
• Tools Layer (tools/): MCP-Tool-Definitionen
• MCP Layer (mcpServer.ts): Protocol-Wrapper

Features

• Standortbasierte Suche: Filialen und Geldautomaten im Umkreis finden
• Typ-Filterung: Gezielte Suche nach FILIALE, GELDAUTOMAT oder SB_FILIALE
• Distanzberechnung: Haversine-Formel für präzise Entfernungen
• Öffnungszeiten: Aktuelle Verfügbarkeit prüfen
• Detailinformationen: Vollständige Adresse, Services und Kontaktdaten

Installation

Voraussetzungen

• Node.js 18 oder höher
• npm oder yarn

Einrichtung

# Abhängigkeiten installieren
npm install

# Projekt bauen
npm run build

# Demo ausführen (zeigt alle 5 Tools mit JSON-Ausgabe)
npm run demo

# Oder MCP Server für Claude Desktop starten
npm start

Verwendung

Schnelle Demo

Der schnellste Weg, um den MCP Server in Aktion zu sehen:

npm run demo

Dies führt alle 5 Tools aus und zeigt deren strukturierte JSON-Antworten:

• Standortbasierte Suche mit Filtern (Radius, Typ, Ausstattung)
• Detaillierte Filialinformationen mit Öffnungszeiten und Kontaktdaten
• Verfügbare Ausstattungsmerkmale und Objekttypen
• Server-Konfiguration

Konfiguration

Umgebungsvariablen (optional im Mock-Modus):

# Vorlage kopieren und bei Bedarf anpassen
cp .env.example .env

Oder manuell setzen:

export FILIALFINDER_BASE_URL=https://filialfinder-service.sparkasse.de
export FILIALFINDER_API_KEY=your_api_key_here
export FILIALFINDER_BLZ=50050000
export REQUEST_TIMEOUT_MS=2500

Konfiguration mit Claude Desktop

Zur Claude Desktop Konfigurationsdatei hinzufügen:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "filialsucher": {
      "command": "node",
      "args": ["/absolute/path/to/filialsucher-mcp/dist/index.js"]
    }
  }
}

Nach Konfiguration Claude Desktop neu starten.

Verfügbare Tools

Alle Tools liefern strukturiertes JSON für maschinenlesbare Verarbeitung.

1. search_branch_or_atm

Sucht nach Sparkasse-Filialen, Geldautomaten oder SB-Filialen im Umkreis eines Standorts.

Parameter:

• latitude (number, erforderlich): Breitengrad des Suchzentrums
• longitude (number, erforderlich): Längengrad des Suchzentrums
• radius_km (number, optional): Suchradius in Kilometern (Standard: 5km)
• type_group (enum, optional): Filter nach Typ (ATM, BRANCH, SELF_SERVICE)
• open_now (boolean, optional): Nur aktuell geöffnete Standorte
• facilities (integer[], optional): Filter nach Ausstattungs-IDs
• limit (integer, optional): Maximale Anzahl der Ergebnisse (Standard: 10)
• page (integer, optional): Seitennummer für Paginierung (Standard: 1)

Rückgabewert: JSON mit results (BranchSummary[]), total_results, page, page_size, search_center, filters

2. get_object_details

Liefert Detailinformationen zu einer bestimmten Filiale oder einem Geldautomaten.

Parameter:

• id (integer, erforderlich): Die eindeutige ID des Standorts

Rückgabewert: JSON BranchDetail-Objekt mit vollständigen Informationen

3. list_facilities

Liefert eine Liste aller verfügbaren Ausstattungsmerkmale.

Parameter:

• Keine Parameter erforderlich

Rückgabewert: JSON mit facilities (Array von {id, name}), total

4. list_object_types

Liefert eine Liste aller verfügbaren Objekttypen.

Parameter:

• Keine Parameter erforderlich

Rückgabewert: JSON mit object_types (Array von {id, name, groupName}), total

5. get_configuration

Liefert die aktuelle Filialfinder-Konfiguration.

Parameter:

• Keine Parameter erforderlich

Rückgabewert: JSON mit blz, name, supportedObjectTypes

Design-Entscheidungen

Schichtenarchitektur

Die Implementierung folgt dem Ports & Adapters Pattern:

1. Domain Layer: Reine Business-Modelle und Mappings, keine externen Abhängigkeiten
2. Infrastructure Layer: FilialfinderPort Interface ermöglicht austauschbare Implementierungen (Mock vs. Real API)
3. Tools Layer: MCP-Tool-Definitionen nutzen das Port-Interface, unabhängig von konkreter Implementierung
4. MCP Layer: Dünner Wrapper um die offizielle MCP SDK

Mock vs. Production

Aktueller Stand: MockFilialfinderClient mit 6 realistischen Standorten (Mainz-Gebiet), Haversine-Distanzberechnung und vollständiger Filter-Unterstützung (radius, facilities, type, open_now).

Produktions-Migration: RealFilialfinderClient ist als Stub implementiert (src/infra/realFilialfinderClient.ts) und zeigt den exakten Integrationsweg:

• HTTP-Client mit /rest/v2/objects/{lon}/{lat} und weiteren Endpunkten
• XML-Parsing via fast-xml-parser (Dependencies bereits in package.json)
• Strukturierte Error-Handling-Patterns
• Request-Logging und Timeout-Konfiguration

Migration: In src/index.ts einfach new MockFilialfinderClient() durch new RealFilialfinderClient(config) ersetzen. Keine Änderungen in Tools notwendig (Ports & Adapters Pattern).

Technische Highlights

• Haversine-Formel: Präzise geografische Distanzberechnung
• Type Safety: Vollständige TypeScript-Typisierung durch alle Layer
• Klare Trennung: Saubere Separation zwischen Domain, Infrastructure und Presentation
• Testbarkeit: Port-Interface ermöglicht einfaches Unit-Testing

Entwicklung

# Watch-Modus für Entwicklung
npm run dev

# Build für Produktion
npm run build

Projektstruktur

filialsucher-mcp/
├── src/
│   ├── index.ts                         # Einstiegspunkt
│   ├── config.ts                        # Konfiguration
│   ├── demo.ts                          # Demo-Skript
│   ├── mcpServer.ts                     # MCP-Wrapper
│   ├── domain/
│   │   ├── models.ts                   # Domain-Modelle
│   │   └── mappers.ts                  # Modell-Mapper
│   ├── infra/
│   │   ├── filialfinderClient.ts       # Port-Interface
│   │   ├── mockFilialfinderClient.ts   # Mock-Adapter
│   │   └── realFilialfinderClient.ts   # Produktions-Adapter (Stub)
│   └── tools/
│       ├── searchBranchOrAtm.ts        # Such-Tool
│       ├── getObjectDetails.ts         # Detail-Tool
│       ├── listFacilities.ts           # Ausstattungs-Tool
│       ├── listObjectTypes.ts          # Objekttypen-Tool
│       └── getConfiguration.ts         # Konfigurations-Tool
├── dist/                                # Kompilierte Ausgabe (generiert)
├── .env.example                         # Umgebungsvorlage
├── .gitignore
├── package.json
├── tsconfig.json
└── README.md

Aktuelle Einschränkungen

• Mock-Daten: Prototyp nutzt Mock-Implementierung, produktiver Client über Port-Interface einfach integrierbar
• Geografische Abdeckung: Mock-Daten beschränkt auf Raum Mainz (6 realistische Standorte)
• Keine Persistenz: Daten nur im Speicher

Produktionsreife

Für den Produktiveinsatz sind folgende Schritte notwendig:

1. Real API Client: RealFilialfinderClient implements FilialfinderPort erstellen
2. Error Handling: Retry-Logik und Circuit Breaker für API-Calls
3. Caching: Redis/Memory-Cache für häufige Anfragen
4. Monitoring: Logging und Metrics (z.B. OpenTelemetry)
5. Rate Limiting: Schutz vor Überlastung der Sparkasse API
6. Testing: Unit Tests für alle Layer, Integration Tests mit Test-API