金大哥 - australian-postcodes-mcp MCP 详情

article

README

🚀 澳大利亚邮政编码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云（推荐）

将代码推送到GitHub。
在 fastmcp.cloud 上连接仓库。
配置环境变量。
一键部署。

本地开发

# 运行开发服务器
fastmcp dev src/server.py

# 运行生产服务器
python src/server.py

数据来源

数据来源于社区维护的澳大利亚邮政编码仓库。

🔧 技术细节

使用SQLite并优化索引，以实现快速查询。
大多数查询的响应时间低于100毫秒。
使用rapidfuzz库实现高效的模糊匹配。
缓存语音查询的语音编码。

🤝 贡献

欢迎贡献代码！请参考 CONTRIBUTING.md 获取贡献指南。

📄 许可证

本项目采用MIT许可证，详情请参阅 LICENSE。

支持

如果有任何问题或疑问，请在GitHub上提交问题或联系维护者。

本项目基于 FastMCP 为模型上下文协议构建。

australian-postcodes-mcp