Metadata-Version: 2.4
Name: dhcckb-reverse-geocode-district
Version: 0.1.0
Summary: 通过 WGS84 经纬度查询 OpenStreetMap 区/县级行政区名称的 MCP Server，调用 Overpass API 实现反向地理编码。
Author-email: 数字人文平台 <dev@dhcckb.org>
License-Expression: MIT
Keywords: mcp,overpass,geocoding,openstreetmap,district
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.0.0
Requires-Dist: httpx>=0.28.0

# dhcckb-reverse-geocode-district

通过 WGS84 经纬度查询 OpenStreetMap 区/县级行政区名称的 MCP Server。

调用 [Overpass API](https://overpass-api.de/api/interpreter) 实现反向地理编码，支持多级回退查询。

## 安装

```bash
pip install dhcckb-reverse-geocode-district
```

或使用 `uvx` 直接运行：

```bash
uvx dhcckb-reverse-geocode-district
```

## 功能

| 工具                        | 说明                                                                                            |
| --------------------------- | ----------------------------------------------------------------------------------------------- |
| `reverse_geocode_district`  | 输入 WGS84 经纬度，返回对应区/县级行政区名称、所属城市、省份、行政区级别及 OSM ID                |

### 查询策略

- **中国坐标**（约 73°E–135°E, 18°N–54°N）：主查 `admin_level=6`（区/县），回退 5→4；中文名优先 `name:zh`。
- **国际坐标**：主查 `admin_level=8`（街道/城镇），回退 6→5→4；始终返回 `name`。
- **大洋/荒漠**：返回 `found: false` 及清晰的说明信息。

## 用法示例

### MCP Client 配置

```json
{
  "mcpServers": {
    "reverse-geocode-district": {
      "command": "uvx",
      "args": ["dhcckb-reverse-geocode-district"]
    }
  }
}
```

### 调用示例

```json
// 请求
{
  "name": "reverse_geocode_district",
  "arguments": {
    "latitude": 39.9087,
    "longitude": 116.3975
  }
}

// 响应
{
  "found": true,
  "district_name": "东城区",
  "city": "北京市",
  "province": "北京市",
  "admin_level": 6,
  "admin_level_desc": "admin_level=6 (区/县 (district/county))",
  "osm_id": 554089,
  "osm_type": "relation",
  "in_china": true
}
```

## 环境变量

| 变量名               | 默认值                                        | 说明                      |
| --------------------- | --------------------------------------------- | ------------------------- |
| `OVERPASS_BASE_URL`   | `https://overpass-api.de/api/interpreter`     | Overpass API 端点         |
| `OVERPASS_RATE_LIMIT` | `1.0`                                         | 请求间隔（秒）            |

## 依赖

- Python >= 3.10
- mcp >= 1.0.0
- httpx >= 0.28.0

## 许可

MIT
