（一）服务概述
维智 MCP Server 基于标准化 MCP 协议，整合丰富地理信息数据，为智能体提供地点搜索、正 / 逆地理编码、IP 定位解析、天气查询四大核心能力。数据覆盖城市级、街道级、坐标级查询，支持 HTTP/SSE 双传输协议，可快速适配 VSCode、Cursor、各类编程语言开发环境，助力智能体高效实现地理信息相关功能。
（二）快速接入指南
1. 核心前提准备
- 申请 API Key：所有接口均需通过 API-Key 鉴权，需先在维智平台申请应用 access_key，该 Key 为接口调用的唯一权限凭证。
- 环境要求：支持 MCP 协议的客户端（VSCode、Cursor、Browser MCP Client）或各类编程语言的 MCP SDK，推荐使用 Python FastMCP Client 快速集成。
2. 客户端配置说明
（1）标准 MCP 客户端配置（适用于 VSCode/Cursor）
在客户端配置文件中添加如下 JSON 配置，替换 YOUR_ACCESS_KEY 为实际申请的 API Key：
{ "mcpServers": { "wayz-lot-mcp": { "type": "sse", "url": "https://positionboard.newayz.com/mcp", "headers": { "X-API-Key": "YOUR_ACCESS_KEY" }, "timeout": 60, "sse_read_timeout": 300 } } }（2）Python FastMCP Client 配置示例
python 运行
from fastmcp import Client config = { "mcpServers": { "server_name": { "transport": "http", # 可选 "sse" 协议 "url": "https://positionboard.newayz.com/mcp", "headers": {"X-API-Key": ACCESS_KEY} # 替换为实际 API Key } } } client = Client(config)3. 核心接口调用示例
（1）地理编码（地址转坐标）
python 运行
client.call_tool("geocode_tool", { "address": "北京市东城区东长安街", "city": "北京" })（2）逆地理编码（坐标转结构化地址）
python 运行
client.call_tool("regeocode_tool", { "longitude": 116.397128, "latitude": 39.916527 })（3）IP 定位查询
python 运行
client.call_tool("ip_location_tool", {"ip": "8.8.8.8"})（4）天气查询（支持城市名称或 adcode）
python 运行
client.call_tool("get_weather_tool", {"name": "北京"})（三）常见问题排查
1. 接口调用失败
- 检查 API Key 有效性：确认 X-API-Key 配置正确，未过期或泄露，重新申请并替换无效 Key。
- 网络连接问题：验证目标服务器地址（https://positionboard.newayz.com/mcp）是否可访问，调整 timeout（默认 60 秒）和 sse_read_timeout（默认 300 秒）参数。
- 参数格式错误：确保地址、坐标、IP、城市名称等参数符合接口要求，坐标类参数需保留正确精度。
2. 协议适配问题
- 传输协议选择：HTTP 协议适用于短连接请求，SSE 协议支持服务器推送场景，根据开发环境需求切换配置。
- 客户端兼容性：确保使用的 MCP 客户端支持标准 MCP 协议，优先选择文档推荐的客户端或 SDK。
3. 数据查询精度问题
- 提升查询精度：街道级查询需补充详细地址，坐标级查询确保经纬度参数准确，城市级查询明确指定城市名称避免歧义。
- 数据覆盖范围：若查询结果缺失，可能是该区域数据暂未覆盖，可尝试扩大查询范围或联系技术支持反馈。
