Australian Postcodes MCP

🚀 澳大利亞郵政編碼MCP服務器

澳大利亞郵政編碼MCP服務器是一個高性能的MCP（模型上下文協議）服務器，專為處理客戶服務交互的AI助手設計。它提供澳大利亞郵政編碼和郊區數據，並具備智能模糊匹配功能。

✨ 主要特性

🔍 核心搜索功能

• 郵政編碼查郊區：根據給定的郵政編碼查找所有相關郊區。
• 郊區查郵政編碼：查找郊區對應的郵政編碼（支持模糊匹配）。
• 智能驗證：驗證郊區 - 郵政編碼組合的有效性。
• 地方政府區域查詢：列出地方政府區域（城市/議會）內的所有郊區。

🎯 針對AI優化的特性

• 模糊匹配：處理拼寫錯誤和拼寫失誤，並給出置信度評分。
• 語音搜索：匹配可能聽錯的口語化名稱。
• 自動補全：為部分郊區名稱提供補全建議。
• 智能建議：在未找到精確匹配時提供替代方案。
• 地理搜索：查找指定半徑內的附近郊區。

📊 數據覆蓋範圍

• 約17,000個澳大利亞郵政編碼和郊區信息。
• 地方政府區域（LGAs）。
• 統計區域（SA3/SA4）。
• 地理座標（緯度/經度）。
• 選舉分區。
• 州和地區信息。

🚀 快速開始

📦 安裝指南

# 克隆倉庫
git clone https://github.com/yourusername/australian-postcodes-mcp.git
cd australian-postcodes-mcp

# 安裝依賴
pip install -r requirements.txt

# 導入郵政編碼數據
python src/utils/data_loader.py

# 本地測試
fastmcp dev src/server.py

與Claude Desktop配合使用

在Claude Desktop配置中添加以下內容：

{
  "mcpServers": {
    "australian-postcodes": {
      "command": "fastmcp",
      "args": ["run", "/path/to/australian-postcodes-mcp/src/server.py"]
    }
  }
}

💻 使用示例

基礎用法

# 查找郵政編碼2300對應的郊區
result = await search_by_postcode("2300")
# 返回: Newcastle, Newcastle West, 等

# 查找郊區對應的郵政編碼
result = await search_by_suburb("Newcastle", state="NSW")
# 返回: 2300

高級用法

# 處理拼寫錯誤
result = await find_similar_suburbs("Newcaslte", state="NSW")
# 返回: Newcastle (置信度: 0.92), New Lambton (置信度: 0.75)

# 語音搜索
result = await phonetic_search("new castle")
# 返回: Newcastle, Newcastle West

# 列出紐卡斯爾地方政府區域內的郊區
result = await list_suburbs_in_lga("Newcastle", state="NSW")
# 返回: 紐卡斯爾市議會區域內的所有郊區

可用工具

搜索工具

• search_by_postcode - 根據郵政編碼查找郊區。
• search_by_suburb - 根據郊區查找郵政編碼。
• validate_suburb_postcode - 驗證郊區 - 郵政編碼組合的有效性。
• get_location_details - 智能搜索，可接受郵政編碼或郊區名稱。

模糊匹配工具

• find_similar_suburbs - 為拼寫錯誤的郊區查找最接近的匹配。
• autocomplete_suburb - 為部分名稱提供補全建議。
• validate_spelling - 提供拼寫糾正建議。
• phonetic_search - 處理可能聽錯的口語化名稱。

位置工具

• list_suburbs_in_lga - 列出地方政府區域內的所有郊區。
• find_lga_for_suburb - 獲取郊區所屬的地方政府區域/城市。
• list_suburbs_in_radius - 查找指定半徑內的附近郵政編碼。
• get_neighboring_suburbs - 查找相鄰區域。

分析工具

• get_state_statistics - 按州統計郵政編碼和郊區數量。
• list_all_lgas - 列出所有可用的地方政府區域。
• search_by_region - 按統計區域進行查詢。

部署

FastMCP雲（推薦）

1. 將代碼推送到GitHub。
2. 在 fastmcp.cloud 上連接倉庫。
3. 配置環境變量。
4. 一鍵部署。

本地開發

# 運行開發服務器
fastmcp dev src/server.py

# 運行生產服務器
python src/server.py

數據來源

數據來源於社區維護的 澳大利亞郵政編碼 倉庫。

🔧 技術細節

• 使用SQLite並優化索引，以實現快速查詢。
• 大多數查詢的響應時間低於100毫秒。
• 使用rapidfuzz庫實現高效的模糊匹配。
• 緩存語音查詢的語音編碼。

🤝 貢獻

歡迎貢獻代碼！請參考 CONTRIBUTING.md 獲取貢獻指南。

📄 許可證

本項目採用MIT許可證，詳情請參閱 LICENSE。

支持

如果有任何問題或疑問，請在GitHub上提交問題或聯繫維護者。

本項目基於 FastMCP 為 模型上下文協議 構建。