# 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](https://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
```bash
npm install
```

### Configure Environment Variables

Copy the example environment file and update with your credentials:

```bash
cp .env.example .env
```

Edit `.env` to set your Dify API credentials:

```env
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
```bash
node index.js
```

### Configure in your MCP client

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

```json
{
  "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
```bash
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