Address MCP Server

A Model Context Protocol (MCP) server for Hong Kong address lookup and correction using the Address Lookup Service (ALS) open data from the HKSAR Government.

Features

• Fuzzy address matching — Corrects typos in building names, street names, estate names (Chinese & English)
• Structured input parsing — Parses the standard HK address form format (室/層/樓/大廈名稱/街名及街號/地區)
• Free-text search — Search by any combination of address fields
• Bilingual — Full support for Traditional Chinese and English addresses
• LLM-powered correction — Uses Dify LLM API to compose the final corrected full address
• Offline fallback — Falls back to local-only matching if LLM is unavailable
• GeoAddress & Coordinates — Returns GeoAddress identifiers and WGS84 coordinates

Data Source

Uses the ALS GeoJSON files (18 district files) from DATA.GOV.HK:

• als_addresses_(district_name).geojson — One file per District Council district

Tools

check_address

Look up and correct a Hong Kong address using structured fields.

Parameters: | Field | Description | Example | |-------|-------------|---------| | buildingName | Building name (大廈名稱) | 其士商業中心 | | streetName | Street name (街名) | 宏開道 | | buildingNo | Street number (街號) | 8 | | estateName | Estate name (屋邨/屋苑) | 德福花園 | | villageName | Village name (村) | 三家村 | | district | District (地區) | 九龍灣 | | region | Region (地區選項) | 九龍 / KLN | | floor | Floor (層) | 8 | | unit | Unit/Room (室) | 215 |

parse_and_check_address

Parse a structured Chinese address form and look up/correct it.

Input example:

室：215
層：8
樓：(未填寫)
大廈名稱：科士商業中心
屋邨／屋苑／村：(未填寫)
街名及街號：宏開道 8號
地區：九龍灣
地區選項：已勾選 九龍

Output: Identifies that "科士商業中心" should be "其士商業中心" (CHEVALIER COMMERCIAL CENTRE).

correct_address ⭐ (Recommended)

The main tool — parses, looks up, and corrects an address using ALS open data + Dify LLM. Returns the final corrected full address.

Parameters: | Field | Description | |-------|-------------| | address | Any address text — structured form or free text (Chinese/English) |

Example output:

CHINESE: 九龍觀塘區宏開道8號其士商業中心8樓215室
ENGLISH: Unit 215, 8/F, CHEVALIER COMMERCIAL CENTRE, 8 WANG HOI ROAD, KWUN TONG DISTRICT, KLN
GEOADDRESS: 3981120257T20050430
CORRECTIONS: 大廈名稱: "科士商業中心" → "其士商業中心" (CHEVALIER COMMERCIAL CENTRE)

search_address_by_text

Free-text search for addresses.

Parameters: | Field | Description | |-------|-------------| | query | Free-text query (Chinese or English) | | maxResults | Max results (default: 5) |

Setup

Install dependencies

npm install

Configure Environment Variables

Copy the example environment file and update with your credentials:

cp .env.example .env

Edit .env to set your Dify API credentials:

DIFY_API_KEY=your-api-key-here
DIFY_API_ENDPOINT=https://your-dify-endpoint.com/v1

Note: The .env file is gitignored to protect your credentials.

Run as MCP server

node index.js

Configure in your MCP client

Add to your MCP settings (e.g. ~/.cursor/mcp.json or Windsurf MCP config):

{
  "mcpServers": {
    "address-mcp": {
      "command": "node",
      "args": ["/Users/hillmantam/AddressMCP/index.js"]
    }
  }
}

Environment Variables Reference

| Variable | Required | Description | |----------|----------|-------------| | DIFY_API_KEY | Yes | Your Dify API key | | DIFY_API_ENDPOINT | Yes | Your Dify API base URL (e.g., https://your-endpoint.com/v1) |

Run tests

npm test

Example Correction

Input: 科士商業中心 at 宏開道 8號, 九龍灣

Output:

• ⚠️ 大廈名稱: "科士商業中心" → "其士商業中心" (CHEVALIER COMMERCIAL CENTRE)
• Correct address: 九龍觀塘區宏開道8號其士商業中心
• GeoAddress: 3981120257T20050430
• Coordinates: 22.32133, 114.21127

Architecture

User Input → Parse structured fields → Fuse.js fuzzy search (local GeoJSON)
                                          ↓
                                    Top 5 candidates
                                          ↓
                                    Dify LLM API → Final corrected address
                                          ↓
                              (Fallback: local-only if LLM fails)

• Fuse.js — Fuzzy string matching for Chinese and English text
• Dify LLM — AI-powered address correction and formatting
• MCP SDK — Standard Model Context Protocol server over stdio
• GeoJSON — All 18 district files loaded into memory with indexed search