关键词

瑞士邮政地址验证地址纠错LLM集成自动化

项目简介

Swisspost智能地址MCP服务器是一个专门用于地址验证和纠错的后端服务。它利用Model Context Protocol (MCP) 标准，与大型语言模型 (LLM) 客户端（如Claude Desktop）或其他自动化工具（如n8n）无缝集成。该服务能够智能分析和纠正地址中的常见错误，例如邮编与城市互换、不规范的街道名称或门牌号格式，并利用瑞士邮政的API进行实时验证和自动补全，确保地址数据的准确性和标准化。

主要功能点

  • 智能地址分析： 自动识别并纠正地址错误，包括邮政编码与城市互换、从街道名称中分离门牌号、修正拼写错误的城市名称、标准化地址格式等。
  • 瑞士邮政API集成： 利用瑞士邮政的ZIP、Street和House Autocomplete API，实现邮编、街道和门牌号的自动补全和验证。
  • 自动化纠正： 提供实时纠错、错误回溯机制，并根据瑞士邮政质量标准提供0-100分的地址质量评分。
  • MCP服务器： 作为标准MCP服务器运行，支持与Claude Desktop、MCP Inspector等MCP兼容客户端通过JSON-RPC/STDIO协议进行通信。
  • n8n工作流集成： 提供预配置的n8n工作流和HTTP代理，便于将其集成到自动化流程中。

安装步骤

  1. 克隆或下载仓库： 
    git clone https://github.com/AlfMueller/swisspost-smart-address-mcp.git
cd swisspost-smart-address-mcp
  2. 安装Python依赖： 
    pip install -r requirements.txt
  3. 获取瑞士邮政API凭据：
  4. 配置环境变量：
    • 复制 'config.env' 文件到 '.env' (Linux/macOS: 'cp config.env .env', Windows: 'copy config.env .env')。
    • 编辑 '.env' 文件，填入您真实的 'Client ID' 和 'Client Secret'。建议的 'SWISSPOST_SCOPE' 为 'DCAPI_ADDRESS_VALIDATE DCAPI_ADDRESS_AUTOCOMPLETE'。
    SWISSPOST_CLIENT_ID=您的_真实_Client_ID
SWISSPOST_CLIENT_SECRET=您的_真实_Secret
SWISSPOST_SCOPE=DCAPI_ADDRESS_VALIDATE DCAPI_ADDRESS_AUTOCOMPLETE
    重要提示： '.env' 文件已被 '.gitignore' 忽略，请勿将其提交到版本控制中。

服务器配置（供MCP客户端使用）

MCP服务器通过标准输入/输出 (STDIO) 与客户端通信，不使用网络端口。要将此MCP服务器连接到MCP客户端（例如Claude Desktop），您需要在客户端的配置文件中指定服务器的启动命令。

以下是一个示例JSON配置，您需要根据您的实际路径进行调整：

{
  "mcpServers": {
    "swisspost-address": {
      "command": "python",
      "args": ["/path/to/your/swisspost-smart-address-mcp/smart-address-agent.py"],
      "cwd": "/path/to/your/swisspost-smart-address-mcp"
    }
  }
}
  • 'swisspost-address'：此MCP服务器的唯一标识符。
  • 'command'：启动服务器的命令，通常是'python'。
  • 'args'：传递给'command'的参数，这里是MCP服务器主脚本的完整路径。
  • 'cwd'：服务器启动时的工作目录，应指向项目根目录，以确保正确加载'.env'文件。

请将此配置保存到您的Claude Desktop配置文件夹中：

  • Windows: '%APPDATA%\Claude\claude_desktop_config.json'
  • macOS: '~/Library/Application Support/Claude/claude_desktop_config.json'
  • Linux: '~/.config/claude/claude_desktop_config.json'

基本使用方法

  1. 启动MCP服务器： 在项目根目录下，打开终端并运行： 
    python smart-address-agent.py
    服务器将在后台运行，并等待客户端连接。
  2. 连接MCP客户端：
    • 对于Claude Desktop： 确保已按照上述“服务器配置”步骤配置好'claude_desktop_config.json'文件。然后启动Claude Desktop，它将自动检测并连接到此MCP服务器。您可以通过向LLM提问 "Validiere diese Adresse: Pfingstweidstrasse 94, 8005 Zürich" 来使用它。
    • 对于n8n： 使用项目'n8n-workflows'文件夹中提供的脚本'start-mcp-server-and-proxy.sh' (或 '.bat') 来同时启动MCP服务器和HTTP代理，然后导入'swisspost-workflow.json'工作流。
    • 对于MCP Inspector (测试工具)：
      • 在一个终端中启动MCP服务器 ('python smart-address-agent.py')。
      • 在另一个终端中运行 'mcp-inspector'。它将连接到本地MCP服务器，您可以在其中测试 'validate_address_smart' 工具。

信息

分类

网页与API

访问项目