实战:高德 MCP 服务接入指南:手把手打造智能旅行攻略生成器

一、高德 MCP 服务核心能力速览

在动手开发前，先明确高德 MCP 服务的核心价值 —— 它已将 12 类高频地理信息接口封装为标准化 MCP 工具，无需关注底层 API 细节，只需通过协议调用即可实现：

• 位置转换：地理编码（地址→经纬度）、逆地理编码（经纬度→地址）
• 定位服务：IP 定位（根据 IP 获取城市信息）
• 天气查询：通过城市名 / 编码获取预报数据
• 路径规划：驾车、公交、骑行、步行四种出行方式，支持实时路况考量
• 地点搜索：关键词搜索、周边搜索、POI 详情查询
• 距离测量：两点经纬度距离与耗时计算

这些能力恰好匹配旅行攻略的核心需求：景点筛选、路线规划、天气适配、出行方式推荐，为智能体提供了 “感知现实世界” 的基础。

二、第一步：MCP 客户端开发（基础准备）

MCP 客户端是智能体与高德服务通信的桥梁，需完成依赖安装、密钥获取、客户端封装三个关键步骤，确保通信标准化。

1.1 安装核心依赖

本次开发基于 Python 生态，需安装 MCP 协议工具、高德 SDK、智能体框架及大模型依赖：

# 1. MCP协议核心依赖：处理标准化请求/响应

pip install mcp-client

# 2. 高德MCP专用SDK：简化高德服务封装（官方适配，避免重复造轮子）

pip install amap-mcp-sdk

# 3. 智能体框架：LangChain用于构建工具调度逻辑

pip install langchain

# 4. 社区工具包：提供文件操作等扩展能力

pip install langchain-community  # 注意：pip安装时此处是短横线，非下划线

# 5. 大模型依赖：以OpenAI为例（可替换为通义千问、Claude等支持MCP的模型）

pip install openai

# 6. 辅助依赖：处理JSON数据与HTTP请求

pip install requests json5

代码解析：

• mcp-client
  是 MCP 协议的核心实现，负责将智能体的自然语言决策转换为标准化 MCP 请求，同时解析服务端响应；
• amap-mcp-sdk
  是高德官方提供的 MCP 适配包，已将 12 类接口封装为 MCP 工具格式，无需手动编写接口适配代码；
• 后续扩展的文件工具依赖langchain_community，提前安装避免后续报错。

1.2 获取高德应用 Key（权限认证关键）

接入高德 MCP 服务必须通过 Key 验证身份，获取流程如下（附实操细节）：

1. 注册并登录高德开放平台控制台，完成开发者实名认证；
2. 进入【应用管理】→【创建新应用】，填写应用名称（如 “杭州旅行攻略智能体”），选择应用类型为 “工具类应用”；
3. 应用创建后，点击【添加 Key】，服务平台选择 “Web 服务”（关键！仅该平台支持 MCP 协议调用）；
4. 可选配置 IP 白名单（生产环境建议添加，避免 Key 泄露被滥用），阅读并同意服务条款后提交；
5. 创建成功后，获取 “Key” 和 “安全密钥”，妥善保存（后续客户端开发需用到）。

注意事项：

• Key 需绑定 “MCP 服务” 权限，若创建时未勾选，可在【应用管理】→【接口权限】中补充开通；
• 免费版 Key 有调用频次限制（单日每接口 1000 次），测试完成后可根据需求升级商业版。

1.3 开发高德 MCP 客户端（标准化工具封装）

通过amap-mcp-sdk封装高德 MCP 服务，生成智能体可直接调用的标准化工具。采用异步开发模式（async/await），适配网络请求场景，提升并发效率：

import asynciofrom mcp_client import MCPClientfrom amap_mcp_sdk import AMapMCPClientfrom openai import OpenAI# 1. 初始化配置（替换为你的高德Key和安全密钥）AMAP_KEY ="你的高德应用Key"AMAP_SECRET ="你的安全密钥"OPENAI_API_KEY ="你的OpenAI API Key"# 2. 初始化高德MCP客户端（核心步骤：建立标准化通信通道）async def init_amap_mcp_client():# 创建MCP基础客户端，指定高德MCP服务端点    base_client = MCPClient(        endpoint="https://mcp.amap.com/v1",# 高德MCP官方端点        auth={"type":"amap","key": AMAP_KEY,"secret": AMAP_SECRET}# 高德认证方式)# 封装为高德专用MCP客户端，自动加载12类核心工具    amap_client = AMapMCPClient(base_client)    return amap_client# 3. 获取标准化MCP工具（关键：将高德接口转换为智能体可识别的工具）async def get_amap_mcp_tools():    amap_client =await init_amap_mcp_client()# 按需加载工具（旅行攻略核心工具集）    tools =[        amap_client.get_tool("weather_query"),# 天气查询工具        amap_client.get_tool("keyword_search"),# 景点关键词搜索工具        amap_client.get_tool("driving_route"),# 驾车路线规划（打车场景）        amap_client.get_tool("poi_detail"),# POI详情查询（景点地址/类型）        amap_client.get_tool("geocode"),# 地理编码（景点名称→经纬度）    ]    return tools# 测试客户端是否正常工作if __name__ =="__main__":    tools = asyncio.run(get_amap_mcp_tools())    print(f"成功加载{len(tools)}个高德MCP工具：")    for tool in tools:        print(f"- {tool.name}: {tool.description}")

代码解析：

• 第 2 步init_amap_mcp_client：建立与高德 MCP 服务的连接，通过auth参数传入 Key 和安全密钥，确保通信安全；
• 第 3 步get_amap_mcp_tools：按需筛选工具，避免加载冗余接口（如旅行攻略无需 IP 定位工具），每个工具包含name（工具名称）、description（功能描述）、parameters（输入参数）三个核心属性，符合 MCP 协议标准；
• 测试代码通过asyncio.run运行异步函数，验证工具是否成功加载，若输出工具列表则说明客户端开发完成。

三、第二步：创建智能体，集成 MCP 工具

智能体的核心是 “理解需求→选择工具→执行任务→整合结果”，本节基于 LangChain 框架构建智能体，实现高德 MCP 工具的自动化调度。

2.1 初始化大模型与工具集

先整合高德 MCP 工具与大模型，为智能体提供 “决策大脑” 和 “执行工具”：

from langchain.agents import initialize_agent, AgentTypefrom langchain_openai import ChatOpenAI# 1. 初始化大模型（智能体的“大脑”）llm = ChatOpenAI(    api_key=OPENAI_API_KEY,    model="gpt-4o",# 推荐使用支持工具调用的大模型    temperature=0.3# 降低随机性，确保规划结果稳定)# 2. 整合高德MCP工具（异步获取）async def get_all_tools():    amap_tools =await get_amap_mcp_tools()    return amap_tools

代码解析：

• 大模型选择gpt-4o是因为其工具调用能力更成熟，能精准理解需求并选择合适的 MCP 工具；
• temperature=0.3
  ：旅行攻略需要精准的路线、天气数据，低温度参数可减少大模型的 “幻想”，确保工具调用逻辑可靠。

2.2 创建智能体（工具调度核心）

使用 LangChain 的initialize_agent函数创建智能体，指定工具集、大模型和代理类型：

async def create_travel_agent():    tools =await get_all_tools()# 初始化智能体    agent = initialize_agent(        tools=tools,        llm=llm,        agent=AgentType.STRUCTURED_CHAT_ZERO_SHOT_REACT_DESCRIPTION,        verbose=True,# 输出详细执行日志（调试用）        handle_parsing_errors="返回'无法解析请求，请重试'，不要自行编造结果",

    )    return agent

关键参数解析：

• AgentType.STRUCTURED_CHAT_ZERO_SHOT_REACT_DESCRIPTION
  ：结构化聊天代理，适合处理需要多工具协同的复杂任务，通过REACT思维链（思考→执行→观察→迭代）实现工具调度；
• verbose=True
  ：开发阶段开启，可查看智能体的思考过程（如 “用户需要杭州天气→调用 weather_query 工具→输入参数 city = 杭州”），便于调试；
• handle_parsing_errors
  ：定义参数解析错误时的响应，避免智能体返回无效结果。

2.3 优化提示词（精准引导智能体行为）

提示词是智能体的 “操作手册”，需明确需求、约束条件和输出格式，避免智能体偏离目标：

def build_prompt():    prompt_template ="""    你是专业的旅行攻略规划师，需使用高德MCP工具完成以下任务：    1. 核心需求：为用户规划2025年端午节（5月31日-6月3日）杭州4天旅行攻略；    2. 工具使用规则：       - 先调用weather_query工具查询杭州4天天气，根据天气调整行程（雨天优先室内景点）；       - 用keyword_search工具搜索杭州热门景点（优先西湖、灵隐寺、千岛湖等核心景点），每个景点需通过poi_detail获取地址和经纬度；       - 同一天景点之间用driving_route工具规划打车路线，返回距离和预计耗时；       - 所有景点需通过geocode工具确认经纬度，确保路线规划准确；    3. 输出要求：       - 行程按“日期→时间段→景点→打车路线→备注（天气适配）”格式整理；       - 生成可直接嵌入H5的地图数据（包含景点经纬度、路线坐标串）；       - 不编造数据，所有景点、天气、路线信息必须来自高德MCP工具调用结果；    4. 最终结果：返回行程规划文本和H5地图所需的JSON数据，无需额外解释。        """        return prompt_template

提示词优化技巧：

• 明确工具调用顺序（先查天气→再搜景点→最后规划路线），引导智能体按逻辑执行；
• 限定数据来源（“必须来自高德 MCP 工具”），避免大模型编造景点信息；
• 指定输出格式，便于后续生成 H5 页面（直接提取 JSON 数据即可渲染地图）。

2.4 异步运行智能体，执行规划任务

智能体调用是异步过程，需通过asyncio运行，获取规划结果：

async def run_travel_agent():    agent =await create_travel_agent()    prompt = build_prompt()# 运行智能体，获取结果    result =await agent.arun(prompt)    return result# 执行智能体规划if __name__ =="__main__":    travel_result = asyncio.run(run_travel_agent())    print("智能体生成的旅行攻略：")    print(travel_result)

代码解析：

• 使用agent.arun(prompt)异步运行智能体，arun是 LangChain 异步代理的专用方法，支持工具的异步调用；
• 运行过程中，智能体会输出详细日志，例如：> Entering new AgentExecutor chain...> I need to first check the weather in Hangzhou during the Dragon Boat Festival.> Calling: weather_query with {'city': '杭州'}可通过日志排查工具调用是否符合预期。

四、第三步：扩展文件工具，生成 H5 页面

智能体生成行程后，需将结果保存为 H5 文件（amap.html），便于用户在浏览器中查看，同时支持高德地图 APP 跳转。

3.1 集成文件操作工具

通过langchain_community的FileManagementToolkit获取文件读写工具，扩展智能体的 “存储能力”：

from langchain_community.agent_toolkits import FileManagementToolkit# 1. 初始化文件工具（指定文件保存目录）def get_file_tools():    file_toolkit = FileManagementToolkit(        root_dir="/Users/sam/llm/.temp",# 文件保存路径（需提前创建）        tool_metadata={"name":"file_management"})# 获取核心文件工具：写文件、读文件    file_tools = file_toolkit.get_tools()    return file_tools# 2. 扩展智能体工具集（整合MCP工具+文件工具）async def get_enhanced_tools():    amap_tools =await get_amap_mcp_tools()    file_tools = get_file_tools()    return amap_tools + file_tools# 3. 重新创建增强型智能体async def create_enhanced_travel_agent():    tools =await get_enhanced_tools()    agent = initialize_agent(        tools=tools,        llm=llm,        agent=AgentType.STRUCTURED_CHAT_ZERO_SHOT_REACT_DESCRIPTION,        verbose=True,        handle_parsing_errors="返回'无法解析请求，请重试'",    )    return agent

代码解析：

• FileManagementToolkit
  的root_dir指定文件保存目录，需确保该目录已存在（否则会报错）；
• 扩展后的工具集包含 “高德 MCP 工具 + 文件工具”，智能体可在生成行程后，自动调用write_file工具保存 H5 页面。

3.2 优化提示词，添加文件保存逻辑

更新提示词，要求智能体生成 H5 页面并保存：

defbuild_enhanced_prompt():    prompt_template ="""    你是专业的旅行攻略规划师，需使用高德MCP工具和文件工具完成以下任务：    1. 核心需求：为用户规划2025年端午节（5月31日-6月3日）杭州4天旅行攻略；    2. 工具使用规则：       - 先调用weather_query工具查询杭州4天天气，根据天气调整行程（雨天优先室内景点）；       - 用keyword_search工具搜索杭州热门景点，每个景点需通过poi_detail获取地址和经纬度；       - 同一天景点之间用driving_route工具规划打车路线，返回距离、耗时和高德地图打车链接；       - 所有景点需通过geocode工具确认经纬度；    3. 输出要求：       - 行程按“日期→时间段→景点→打车路线→备注（天气适配）”格式整理；       - 生成H5页面内容，包含：         - 行程文本（居中显示）；         - 高德地图嵌入（使用iframe加载，显示景点位置和路线）；         - 打车链接、骑行路线链接（点击可跳转高德APP）；       - H5页面需使用简单CSS样式（背景色#f5f5f5，字体16px）；    4. 文件保存：调用write_file工具，将H5内容保存到/Users/sam/llm/.temp/amap.html；    5. 最终返回：仅返回“行程已生成，H5文件路径：/Users/sam/llm/.temp/amap.html”。    """    return prompt_template

提示词关键优化：

• 明确 H5 页面结构，要求嵌入高德地图 iframe（高德地图支持通过经纬度生成共享地图链接）；
• 要求生成可跳转的打车链接（高德 MCP 的driving_route工具返回amap_url字段，点击可直接打开高德 APP 导航）；
• 指定文件保存路径和 CSS 样式，确保 H5 页面可用且美观。

3.3 运行增强型智能体，生成最终结果

async def run_enhanced_agent():    agent =await create_enhanced_travel_agent()    prompt = build_enhanced_prompt()    result =await agent.arun(prompt)    return resultif __name__ =="__main__":    final_result = asyncio.run(run_enhanced_agent())    print(final_result)

运行结果说明：

• 智能体会自动完成 “天气查询→景点搜索→路线规划→H5 生成→文件保存” 全流程；
• 打开/Users/sam/llm/.temp/amap.html，可看到：
1. 格式化的 4 天行程（包含天气备注，如 “今日晴，适合户外游览”）；
2. 嵌入的高德地图（显示所有景点位置和打车路线）；
3. 可点击的打车链接（跳转高德 APP 直接导航）；
• 若需在高德地图 APP 中查看完整行程，可通过 H5 页面的 “导出行程” 功能生成高德行程链接。

五、能力扩展与优化建议

5.1 功能扩展：添加更多实用工具

• 公交 / 骑行路线：加载amap_client.get_tool("transit_route")（公交）和amap_client.get_tool("cycling_route")（骑行）工具，支持多出行方式切换；
• 酒店搜索：添加keyword_search工具（关键词 “杭州景点周边酒店”），推荐景点附近住宿；
• 距离测量：用distance_calculation工具计算景点间距离，优化行程紧凑度。

5.2 性能优化：缓存与错误处理

• 工具调用缓存：使用langchain.cache.SQLiteCache缓存重复工具调用结果（如同一城市天气查询），减少 API 调用次数；
• 错误重试：为 MCP 工具添加重试机制，处理网络波动导致的调用失败：

  from tenacity import retry, stop_after_attempt, wait_exponential@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1,min=2,max=10))async def call_mcp_tool(tool, params):    return await tool.run(params)

5.3 体验优化：个性化定制

• 支持用户输入偏好：在提示词中添加 “用户可指定景点类型（如自然景观 / 人文古迹）、预算、出行人数”，让智能体生成个性化行程；
• H5 页面增强：添加行程分享功能（生成二维码）、天气预警提示、景点开放时间查询。

总结

通过 MCP 协议，我们仅用百余行代码就实现了 “智能规划 + 高德地图集成 + H5 落地” 的旅行攻略生成器，核心优势在于：

1. 标准化集成：无需关注高德 API 细节，MCP 协议实现工具即插即用；
2. 智能调度：大模型自动选择工具、执行任务，无需人工干预；
3. 可扩展性强：新增工具（如酒店搜索、门票查询）只需按 MCP 标准封装，无需修改智能体核心逻辑。