内容
# 地理空间上下文MCP服务器
将坐标转换为代理准备的地理空间上下文：反向地理编码、附近的OpenStreetMap特征和紧凑的来源位置简介。
当前实现使用公共OpenStreetMap基础设施：
- Nominatim用于反向地理编码。
- Overpass API用于附近的特征。
未来提供商插槽可以添加Google Maps Platform、Google Earth Engine、Census、NOAA、FEMA、USGS和本地数据集，而无需更改MCP工具合同。
## 快速入门
```bash
npm install
npm run build
npm test
npm run list-tools
```
对于本地MCP客户端：
```json
{
"mcpServers": {
"geospatial-context": {
"command": "node",
"args": ["/home/unmodeledtyler/geospatial-context/dist/index.js"],
"env": {
"GEO_CONTEXT_USER_AGENT": "geospatial-context/0.1.0 (you@example.com)"
}
}
}
}
```
Nominatim要求客户端标识自己。在大量使用之前，请将`GEO_CONTEXT_USER_AGENT`设置为应用程序/联系字符串。
通用stdio服务器设置：
```yaml
command: node
args:
- /path/to/geospatial-context/dist/index.js
env:
GEO_CONTEXT_USER_AGENT: geospatial-context/0.1.0 (you@example.com)
```
Hermes Agent示例：
```yaml
mcp_servers:
geospatial-context:
command: node
args:
- /path/to/geospatial-context/dist/index.js
connect_timeout: 30
timeout: 180
env:
GEO_CONTEXT_USER_AGENT: geospatial-context/0.1.0 (you@example.com)
```
## 工具
### `reverse_geocode`
将精确坐标解析为类似地址的位置标识。
输入：
```json
{
"latitude": 37.8199,
"longitude": -122.4783,
"language": "zh-CN"
}
```
### `geocode_address`
将街道地址、地点名称或位置查询解析为坐标。
输入：
```json
{
"address": "350 5th Ave, New York, NY",
"language": "zh-CN"
}
```
### `nearby_osm_features`
查找附近的OSM特征，分为代理友好的类别，如地标、交通、食品、住宿、健康、教育、公共、公园、水、自然和基础设施。
输入：
```json
{
"latitude": 37.8199,
"longitude": -122.4783,
"radiusMeters": 1000,
"limit": 40,
"includeInfrastructure": false,
"priorityMode": "human_landmarks"
}
```
### `get_boundary_context`
将坐标或地址解析为时区、行政等级和美国人口普查地理区域（如果可用）。
输入：
```json
{
"address": "350 5th Ave, New York, NY",
"language": "zh-CN"
}
```
### `get_physical_context`
将坐标或地址解析为物理站点上下文，如海拔和地形摘要。
输入：
```json
{
"latitude": 40.7484405,
"longitude": -73.9856644
}
```
### `get_location_context`
将地理编码/反向地理编码和附近的特征组合成结构化的上下文数据包和可读的Markdown简介。
坐标输入：
```json
{
"latitude": 37.8199,
"longitude": -122.4783,
"radiusMeters": 1000,
"language": "zh-CN",
"includeInfrastructure": true,
"priorityMode": "balanced"
}
```
地址输入：
```json
{
"address": "埃菲尔铁塔，巴黎",
"radiusMeters": 1000,
"language": "fr",
"includeInfrastructure": false,
"priorityMode": "human_landmarks"
}
```
提供`address`或`latitude`和`longitude`。
## 注意
该服务器故意为只读。它调用公共地理空间API，并返回每个结果的源元数据，以便代理可以从证据中推断出上下文，而不是创建本地上下文。
主要上下文数据包现在包括：
- `identity`：地理编码或反向地理编码的位置标识
- `nearby`：分类的OpenStreetMap特征
- `boundary`：时区、行政等级和美国人口普查地理区域（如果可用）
- `physical`：海拔和地形摘要（如果可用）
`nearby`特征记录包括`matchedBy`：
- `center_within_radius`：特征点/中心在请求的半径内
- `geometry_intersects_radius`：Overpass匹配了特征几何，但返回的中心可能位于半径之外
`get_location_context`对稀疏数据和部分提供商故障具有鲁棒性。响应将提供商状态与结果丰富度分开：
- `status.providerStatus`：`complete`、`partial`或`failed`
- `status.dataCoverage`：`rich`、`limited`或`empty`
- `issues`：提供商故障，如速率限制或无法访问的API
- `notices`：成功的无结果响应，如无反向地理编码匹配
为了兼容性，`completeness`仍然作为`status.providerStatus`的别名被包含。
提供商调用重试瞬时HTTP故障，包括`429`速率限制，反向地理编码结果在内存中被短暂缓存。可以通过以下方式调整：
```bash
GEO_CONTEXT_HTTP_RETRIES=2
REVERSE_GEOCODE_CACHE_TTL_MS=300000
```
