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 为 模型上下文协议 构建。