内容
# Azure Maps MCP 服务器
一个模型上下文协议（MCP）服务器，公开了 **Azure Maps** 的常见功能，作为大型语言模型（LLMs）的工具。它基于 Azure Functions（隔离）构建，并使用 Azure Maps .NET SDK 和 REST API 进行搜索、路由、渲染、天气、时区和地理位置。
> 重要：此MCP服务器处于预览状态。接口和行为可能会发生变化。请避免在生产环境中使用。
## 功能
- 地址和地点编码与搜索（正向和反向）
- 获取可用的行政边界
- 规划路线、计算矩阵或可达范围（等时线）
- 渲染静态地图图像
- 通过 IP（单个或批量）解析国家并验证 IP
- 获取坐标的时区信息
- 获取天气状况、每小时/每日预报和警报
- 查找国家元数据并按名称/代码搜索
该项目集成了 Azure Maps 服务。一些端点使用 Azure Maps .NET SDK（搜索、路由、渲染、地理位置），而其他端点则调用 Azure Maps REST API（例如，天气、时区、Snap to Roads）。多边形和某些细节的可用性可能会因地区和数据源而异。
## 工具及使用场景
每个工具都接受一组最小的参数，专注于常见场景。类似布尔值的工具输入应作为字符串提供："true" 或 "false"（不区分大小写）。
### 位置和国家
- location_find
- 功能：对地址/地点查询进行地理编码。返回坐标、格式化地址、组件、置信度。可选地包含边界多边形。
- 场景：您有像 "埃菲尔铁塔 巴黎" 这样的文本或地址，需要纬度/经度和地址部分。
- 输入：query（字符串），maxResults（1-20），includeBoundaries（"true"|"false"）。
- 注意：边界搜索尝试请求的类型的解析，然后在解析和边界类型之间进行回退（本地 → 邮政编码 → 管理区 → 国家地区）。并非所有地方都存在边界。
- location_analyze
- 功能：将纬度/经度反向地理编码为地址，并获取所选级别的边界多边形。
- 场景：您已经有坐标，需要地址上下文和多边形。
- 输入：latitude，longitude，boundaryType（locality|postalCode|adminDistrict|countryRegion），resolution（small|medium|large）。
- 注意：如果特定的多边形不可用，则包含与上述相同的回退策略。
- search_country_info
- 功能：通过 ISO 代码（alpha-2 或 alpha-3）获取国家信息，例如，US 或 USA。
- 场景：您需要快速的代码 → 名称查找。
- search_countries
- 功能：按名称或代码搜索国家。
- 场景：您需要匹配部分名称/代码并从列表中选择。
### 路线和导航
- navigation_calculate
- 功能：方向、距离/时间矩阵或可达范围的单一工具。
- 场景：
- 方向：将航点列表转换为路线。
- 矩阵：获取一组点的所有到所有旅行时间/距离。
- 范围：使用时间或距离预算从中心点计算等时线。
- 输入：coordinates（LatLon[]），calculationType（directions|matrix|range），travelMode，routeType，avoidTolls（"true"|"false"），avoidHighways（"true"|"false"），timeBudgetMinutes 或 distanceBudgetKm for range。
- 注意：使用 Azure Maps Routing。数据可用性可能会因模式和地区而异。
- navigation_analyze
- 功能：分析航点的国际旅行（穿越国家、基本考虑）。
- 场景：除了路线外，还需要高级别的旅行上下文。
### 地点（POI）
- places_nearby
- 功能：在给定坐标附近找到具有简单半径的地点。
- 场景：您需要附近的 POI（例如，当前位置周围的咖啡店）。
- 输入：latitude，longitude，radiusMeters（100-20000，默认 2000），limit（1-25，默认 10）。
- places_search
- 功能：按关键词模糊搜索，可选地偏向纬度/经度。
- 场景：您有一个术语，如 "pharmacy 98052" 或 "bakery"，并且可选地偏向位置。
- 输入：query（字符串），可选的纬度/经度偏向，limit（1-25，默认 10）。
- places_categories
- 功能：检索 POI 类别树（ID 和名称）。
- 场景：您需要按类别分类或筛选 POI 搜索。
### 地图渲染
- render_staticmap
- 功能：为边界框生成静态 PNG；支持标记和路径。
- 场景：您需要显示带有叠加层的简单地图快照。
- 输入：boundingBox（JSON：{west,south,east,north}），zoomLevel（1-20），width/height（1-8192），mapStyle（road|satellite|hybrid），可选的标记/路径。
### 地理位置（IP）
- geolocation_ip
- 功能：将公共 IPv4/IPv6 解析为 ISO 国家代码（alpha-2）和国家名称。
- 场景：您需要一个 IP 的粗略国家位置。
- 注意：私有和回环 IP 地址是不可地理定位的。
- geolocation_ip_batch
- 功能：批量版本（最多 100 个 IP）。去重并并行处理。
- 场景：您需要高效地解析多个 IP。
- geolocation_ip_validate
- 功能：验证 IP 格式并指示公共/私有、回环、IPv4/IPv6 和地理定位。
- 场景：您需要在尝试地理定位之前进行预检查。
### 时区
- timezone_by_coordinates
- 功能：获取坐标的时区信息（标准/夏令时偏移、名称、日出/日落）。
- 场景：您需要一个点的本地时间上下文和偏移量。
### 天气
- weather_current
- 功能：当前条件（温度、风、湿度、降水等）。
- 场景：您需要坐标的现在天气概况。
- weather_hourly
- 功能：指定小时的小时预报（取决于 SKU 可用性）。
- 场景：您需要近期的详细预报。
- weather_daily
- 功能：指定天数的每日预报（取决于 SKU 可用性）。
- 场景：您需要中期的预报摘要。
- weather_alerts
- 功能：靠近坐标的严重天气警报。
- 场景：您需要了解影响该位置的极端事件。
### 道路
- snap_to_roads
- 功能：将 GPS 点吸附到道路网络；可选地插值并包含速度限制。
- 场景：您需要清理嘈杂的轨迹或推理道路对齐。
- 输入：points（LatLon[]），includeSpeedLimit（"true"|"false"），interpolate（"true"|"false"），travelMode（driving|truck）。
## 输入和输出
- 类似布尔值的参数必须作为字符串提供："true" 或 "false"（不区分大小写）。这避免了不同 MCP 客户端之间的函数绑定问题。
- 响应具有一致的包装器：{ success, meta, data }。在 data 内：
- 类似列表的响应通常遵循 { query, items, summary }。
- 单结果响应遵循 { query, result }。
- 一些工具添加了有用的字段（例如，边界的 resolvedType/resolvedResolution）。
MCP 调用有效载体示例（location_find）：
```json
{
"method": "tools/call",
"params": {
"name": "location_find",
"arguments": {
"query": "埃菲尔铁塔 巴黎",
"maxResults": 5,
"includeBoundaries": "true"
}
}
}
```
## 设置
先决条件：
- [.NET 9 SDK](https://dotnet.microsoft.com/download)
- [Azure Functions Core Tools](https://learn.microsoft.com/azure/azure-functions/functions-run-local)
- 一个 Azure Maps 帐户和订阅密钥（在 Azure 门户中创建 → Azure Maps 资源 → 身份验证）
本地配置（source/local.settings.json）：
```json
{
"IsEncrypted": false,
"Values": {
"AzureWebJobsStorage": "None",
"AzureWebJobsSecretStorageType": "Files",
"FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
"AZURE_MAPS_SUBSCRIPTION_KEY": "<您的 Azure Maps 订阅密钥>"
}
}
```
永远不要提交真实的密钥。在生产环境中使用环境变量或 Azure Key Vault。
## 构建和运行
使用 VS Code 任务：
- 构建（函数）：清理 + 构建
- func：主机启动：启动本地 Functions 主机（依赖于构建）
CLI（可选）：
```bash
cd source
dotnet build
cd bin/Debug/net9.0
func host start
```
本地 Functions 主机默认监听 http://localhost:7071。
## 项目布局
```
azure-maps-mcp/
├── source/
│ ├── Program.cs
│ ├── Services/
│ │ ├── IAzureMapsService.cs
│ │ └── AzureMapsService.cs
│ ├── Common/（验证、响应、REST 客户端的帮助程序）
│ └── Tools/（公开 MCP 工具的函数）
└── README.md
```
## 关于 Azure Maps 的说明（在高级别上经过事实核查）
- Azure Maps 提供 REST API 和 SDK，用于搜索/地理编码、路由、渲染、时区、天气、地理位置和其他地理空间服务。一些 API 可通过此处使用的 Azure Maps .NET SDK（搜索、路由、渲染、地理位置）获得。其他 API 通过 REST 访问（例如，天气、时区、Snap to Roads）。
- 行政边界多边形的可用性因地区和边界级别而异。对于给定的类型/分辨率，在特定坐标处可能不会返回多边形。
- 天气和预报范围、警报可用性和详细信息级别取决于数据提供商的覆盖范围和您的 Azure Maps 定价层/SKU。
有关官方详细信息和最新的服务功能，请参阅 Azure Maps 文档：https://learn.microsoft.com/azure/azure-maps/
## 故障排除
- 缺少密钥：确保已配置 AZURE_MAPS_SUBSCRIPTION_KEY。
- 布尔值绑定错误：为类似布尔值的工具输入发送 "true"/"false" 字符串。
- 无边界几何：这可能是正常的；服务器尝试多个类型/分辨率，并在可用时返回几何。
## 贡献和支持
该项目遵循微软开源代码行为准则。参见存储库的 CODE_OF_CONDUCT.md。
- 问题和功能请求：打开 GitHub 问题。
- Azure Maps 指导：https://learn.microsoft.com/azure/azure-maps/
- 商业支持：https://azure.microsoft.com/support/
商标：使用微软商标需遵守微软商标和品牌准则。
MCP 市场
