Filialsucher MCP

分支机构 MCP 服务器

模型上下文协议 （MCP） 服务器，用于储蓄银行分行和自动取款机搜索。

概述

该 MCP 服务器允许 AI 助理和其他 MCP 客户端对 Sparkasse 分行和自动取款机位置数据进行标准化访问。实施遵循明确的层架构，并展示了专业的软件工程实践。

⚠️ 模拟Modus： 目前的实施利用 MockFilialfinderClient 具有现实的示例数据，因为无法访问Sparkasse REST API。一 RealFilialfinderClient 可以通过 FilialfinderPort一旦API访问数据可用，即插入接口。

建筑

该项目遵循清洁层架构：

• 域层 (domain/商业模型和视图模型映射
• 基础设施层 (infra/端口接口和客户端实现
• 工具层 (tools/MCP 工具定义
• MCP层 (mcpServer.ts)：协议包装器

特性

• 基于位置的搜索查找附近的分行和自动取款机
• 类型过滤有针对性地搜索 FILIALE、GELDAUTOMAT 或 SB_FILIALE
• 距离计算精确距离的Haversine公式
• 开放时间检查当前的可用性
• 详细信息完整的地址、服务和联系方式

安装

前提条件

• Node.js 18 或更高版本
• npm 或 yarn

设置

# 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

使用

快速演示

查看运行中的 MCP 服务器的最快方法：

npm run demo

这将运行所有5个工具并显示它们的结构化JSON响应：

• 基于位置的搜索和过滤器（半径，类型，设备）
• 详细的分支机构信息，包括开放时间和联系方式
• 可用的设备特性和物体类型
• 服务器配置

配置

环境变量 （可选im-Mock Modus）：

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

或者手动设置：

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

使用 Claude Desktop

添加到 Claude Desktop 配置文件：

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

视窗: %APPDATA%\Claude\claude_desktop_config.json

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

重新启动 Claude Desktop。

可用工具

所有工具都提供结构化的JSON，用于机器可读的处理。

1. search_branch_or_atm

搜索位置附近的储蓄银行分行、自动取款机或SB分行。

参数：

• latitude （号码，必填）： 搜索中心的宽度
• longitude （号码，必填）： 搜索中心的长度
• radius_km （数字，可选）：以公里为单位的Suchradius（标准：5km）
• type_group （enum， optional）： 按类型过滤器 （ATM, BRANCH, SELF_SERVICE)
• open_now （boolean， optional）：仅当前打开的位置
• facilities （integer\[\]， 可选）： 按设备 ID 过滤
• limit （整数，可选）：结果的最大数量（默认：10）
• page （integer，可选）：用于分页的页码（默认：1）

返回值： JSON mit results （BranchSummary\[\]）， total_results, page, page_size, search_center, filters

2. get_object_details

提供有关特定分行或自动取款机的详细信息。

参数：

• id （整数，必需）：唯一的位置ID

返回值： 包含完整信息的 JSON BranchDetail 对象

3. list_facilities

提供所有可用设备的列表。

参数：

• 不需要参数

返回值： JSON mit facilities （数组von{id，name}）， total

4. list_object_types

提供所有可用对象类型的列表。

参数：

• 不需要参数

返回值： JSON mit object_types （数组von{id，name，groupName}）， total

5. get_configuration

提供当前分支机构查找器配置。

参数：

• 不需要参数

返回值： JSON mit blz, name, supportedObjectTypes

设计决策

层架构

实施遵循 端口和适配器 图案：

1. 域层纯粹的商业模式和映射，无外部依赖
2. 基础设施层: FilialfinderPort 接口允许可互换实现（模拟与真实API）
3. 工具层MCP 工具定义使用端口接口，无论具体实现如何
4. MCP层官方MCP SDK的薄包装

模拟与生产

当前状态 ： MockFilialfinderClient 具有6个真实的位置（美因茨地区），Haversine距离计算和完整的过滤器支持（半径，设施，类型，open_now）。

生产迁移： RealFilialfinderClient 实施为 stub （src/infra/realFilialfinderClient.ts）并显示确切的整合路径：

• HTTP客户端限制 /rest/v2/objects/{lon}/{lat} 其他终点
• XML解析 fast-xml-parser （依赖项已在 package.json）
• 结构化错误处理模式
• 请求日志和超时配置

迁移： 在 src/index.ts 简单 new MockFilialfinderClient() 通过 new RealFilialfinderClient(config) 取代 。不需要更改工具（端口和适配器模式）。

技术亮点

• Haversine Formel精确的地理距离计算
• 类型安全所有层的完全 TypeScript 类型化
• 明确分离域、基础设施和演示文稿之间的清洁分离
• 可测试性端口接口允许简单的单元测试

肺炎球菌

# Watch-Modus für Entwicklung
npm run dev

# Build für Produktion
npm run build

项目结构

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

当前限制

• 模拟数据原型采用模拟实现，可通过端口接口轻松集成高效客户端
• 地理覆盖模拟数据仅限于美因茨空间（6个现实位置）
• 没有持久性仅存储数据

生产轮胎

为了提高生产力，需要采取以下步骤：

1. 真实API客户端: RealFilialfinderClient implements FilialfinderPort 创建
2. 错误处理重试逻辑和 API 调用的断路器
3. 缓存用于常见查询的 Redis/Memory Cache
4. 监控记录和指标（例如OpenTelemetry）
5. 速率限制防止 Sparkasse API 过载
6. 测试单元测试所有层，集成测试与测试API