Filialsucher MCP Server

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: ``bash 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:

Domain Layer: Reine Business-Modelle und Mappings, keine externen Abhängigkeiten
Infrastructure Layer: FilialfinderPort Interface ermöglicht austauschbare Implementierungen (Mock vs. Real API)
Tools Layer: MCP-Tool-Definitionen nutzen das Port-Interface, unabhängig von konkreter Implementierung
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:

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

filialsucher-mcp