Geocode MCP Service

一个基于 Python + uv 的 Model Context Protocol (MCP) 服务，封装湖北 POI 要素定位器地理编码接口。

远程底层服务： GET https://geosc41.aakle.cn/server/rest/services/湖北POI_要素定位器/GeocodeServer/findAddressCandidates

功能

• 暴露一个 MCP 工具：geocode_poi（可自定义）
• 输入：address (字符串)
• 内部映射为远程接口 SingleLine
• 固定参数：maxLocations=8, f=pjson, outSR=4326, outFields=*
• 输出：简化的候选列表（名称、坐标、得分、原始 JSON）

快速开始

# 创建并激活虚拟环境 (可选)
python -m venv .venv
.\.venv\Scripts\activate

# 安装依赖 (使用 uv 或 pip)
pip install -r requirements.txt
# 或者
uv pip install -r requirements.txt

# 运行本地测试脚本
python src/test_geocode.py "中国地质大学"

作为 MCP 服务器运行

python -m geocode_mcp.server

服务器会通过标准输入输出与支持 MCP 的客户端通信。

安装为可执行脚本后也可直接运行（两种等价）：

geocode-mcp
# 或使用别名脚本
geocode-poi-server

百炼 / uvx 托管配置示例

mcpServers JSON：

{
  "mcpServers": {
    "geocode_poi": {
      "type": "stdio",
      "command": "uvx",
      "args": ["geocode-mcp-hubei>=0.1.0,<0.2", "geocode-mcp"]
    }
  }
}

或使用新增的别名脚本（省去显式写第二个参数）：

{
  "mcpServers": {
    "geocode_poi": {
      "type": "stdio",
      "command": "uvx",
      "args": ["geocode-mcp-hubei>=0.1.0,<0.2", "geocode-poi-server"]
    }
  }
}

工具调用示例（伪 JSON-RPC）

{
  "method": "tools/call",
  "params": {
    "name": "geocode_poi",
    "arguments": {"address": "中国地质大学"}
  }
}

部署到阿里云

1. 选择部署方式：
   • 函数计算（推荐无服务器）
   • ECS 容器/实例
2. 函数计算示例：
   • Runtime: Python 3.11
   • 入口：fc_handler.handler
3. 打包：

Compress-Archive -Path src,requirements.txt -DestinationPath package.zip

4. 上传并在启动代码里调用 from geocode_mcp.server import run_server，需要改造成 HTTP 触发器包装。

MCP 典型运行基于长连接/标准 IO，若在函数计算上使用，需要将协议桥接为 HTTP：可创建一个简单的 HTTP 转 MCP 工具适配层（后续 TODO）。

TODO

• 阿里云 HTTP 适配层 (把 HTTP 请求映射为 geocode 工具调用)
• 增加缓存与错误重试
• 添加单元测试