Agent Scope Java 2.x 系列【9】接入高德 MCP 服务

文章目录

• [1. 概述](#1. 概述)
• [2. 原理](#2. 原理)
• [3. 环境准备](#3. 环境准备)
• • [3.1 获取高德 API Key](#3.1 获取高德 API Key)
  • [3.2 Maven 依赖](#3.2 Maven 依赖)
• [4. 接入步骤](#4. 接入步骤)
• • [4.1 创建 MCP 客户端](#4.1 创建 MCP 客户端)
  • [4.2 注册到 Toolkit 并构建 Agent](#4.2 注册到 Toolkit 并构建 Agent)
  • [4.3 调用](#4.3 调用)
• [5. Spring Boot 完整示例](#5. Spring Boot 完整示例)
• • [5.1 配置类](#5.1 配置类)
  • [5.2 application.yml](#5.2 application.yml)
  • [5.3 控制器](#5.3 控制器)
• [6. 三种传输方式](#6. 三种传输方式)
• [7. 多 MCP Server 同时接入](#7. 多 MCP Server 同时接入)
• [8. 自定义 Header 认证](#8. 自定义 Header 认证)

1. 概述

AgentScope 2.0 通过 Toolkit 内置的 MCP 客户端管理器，支持统一接入任意 MCP 兼容服务器。高德地图提供了公开的 MCP Server（https://mcp.amap.com），提供地理编码、逆地理编码、天气查询、路线规划等工具。

---

2. 原理

AgentScope                        高德 MCP Server
──────────                        ──────────────
Toolkit                           mcp.amap.com
   │                                  │
   ├─ registerMcpClient()  ──────────→│  建立 streamable-http 连接
   │                                  │
   ├─ 自动 listTools()     ←─────────│  返回 ToolSchema 列表
   │                                  │  (geocode / regeo / weather / direction...)
   │                                  │
   └─ Agent 调用 tool →  callTool() ──→│  执行并返回结果

Toolkit.registerMcpClient(clientWrapper) 注册后，Agent 自动获取 MCP Server 提供的所有工具，无需手动定义。

---

3. 环境准备

3.1 获取高德 API Key

1. 访问 高德开放平台 注册账号
2. 创建应用 → 获取 Key

3.2 Maven 依赖

<dependency>
    <groupId>io.agentscope</groupId>
    <artifactId>agentscope</artifactId>
    <version>2.0.0-RC2</version>
</dependency>
<!-- MCP SDK 已由 agentscope 传递依赖引入 -->

---

4. 接入步骤

4.1 创建 MCP 客户端

高德 MCP Server 使用 streamable-http 传输（也支持其他方式），API Key 通过 URL 查询参数传递：

import io.agentscope.core.tool.mcp.McpClientBuilder;
import io.agentscope.core.tool.mcp.McpClientWrapper;

// 同步客户端（适合 WebMVC）
McpClientWrapper mcpClient = McpClientBuilder.create("amap")
    .streamableHttpTransport("https://mcp.amap.com/mcp?key=YOUR_AMAP_API_KEY")
    .timeout(Duration.ofSeconds(60))
    .buildSync();  // 同步

// 或异步客户端（适合 WebFlux）
McpClientWrapper mcpClient = McpClientBuilder.create("amap")
    .streamableHttpTransport("https://mcp.amap.com/mcp?key=YOUR_AMAP_API_KEY")
    .timeout(Duration.ofSeconds(60))
    .buildAsync()
    .block();  // 异步初始化

4.2 注册到 Toolkit 并构建 Agent

Toolkit toolkit = new Toolkit();

// 注册 MCP 客户端（异步初始化）
toolkit.registerMcpClient(mcpClient).block();

// 构建 Agent
ReActAgent agent = ReActAgent.builder()
    .name("amap-assistant")
    .description("高德地图助手")
    .model(DashScopeChatModel.builder()
        .apiKey(System.getenv("DASHSCOPE_API_KEY"))
        .modelName("qwen-plus").build())
    .toolkit(toolkit)
    .sysPrompt("你是一个地图助手，可以使用高德地图提供的工具来查询地理位置、天气、路线规划等。用中文回答。")
    .maxIters(5)
    .build();

4.3 调用

Msg msg = Msg.builder().role(MsgRole.USER)
    .content(List.of(TextBlock.builder().text("查询北京市朝阳区的天气").build()))
    .build();

Msg reply = agent.call(List.of(msg)).block();
System.out.println(reply.getTextContent());

---

5. Spring Boot 完整示例

5.1 配置类

@Configuration
public class AmapAgentConfig {

    @Value("${DASHSCOPE_API_KEY}")
    private String dashscopeKey;

    @Value("${AMAP_API_KEY}")
    private String amapKey;

    @Bean
    public ReActAgent amapAgent() {
        // 1. 创建 MCP 客户端
        McpClientWrapper mcpClient = McpClientBuilder.create("amap")
            .streamableHttpTransport("https://mcp.amap.com/mcp?key=" + amapKey)
            .timeout(Duration.ofSeconds(60))
            .buildSync();

        // 2. 注册到 Toolkit
        Toolkit toolkit = new Toolkit();
        toolkit.registerMcpClient(mcpClient).block();

        // 3. 构建 Agent
        return ReActAgent.builder()
            .name("amap-agent")
            .model(DashScopeChatModel.builder()
                .apiKey(dashscopeKey).modelName("qwen-plus").build())
            .toolkit(toolkit)
            .sysPrompt("""
                你是一个高德地图助手，可以使用以下工具：
                - 地理编码/逆地理编码
                - 天气查询
                - 路线规划
                用中文回答用户问题。
                """)
            .build();
    }
}

5.2 application.yml

server.port: 8090
DASHSCOPE_API_KEY: ${DASHSCOPE_API_KEY:your-key}
AMAP_API_KEY: ${AMAP_API_KEY:your-amap-key}

5.3 控制器

@RestController
@RequestMapping("/amap")
public class AmapController {

    private final ReActAgent agent;

    @GetMapping("/call")
    public Mono<Map<String, Object>> call(@RequestParam String query) {
        Msg msg = Msg.builder().role(MsgRole.USER)
            .content(List.of(TextBlock.builder().text(query).build()))
            .build();
        return agent.call(List.of(msg))
            .map(r -> Map.of("query", query, "response", r.getTextContent()));
    }

    @GetMapping(value = "/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
    public Flux<String> stream(@RequestParam String query) {
        Msg msg = Msg.builder().role(MsgRole.USER)
            .content(List.of(TextBlock.builder().text(query).build()))
            .build();
        return agent.streamEvents(List.of(msg))
            .filter(e -> e instanceof TextBlockDeltaEvent)
            .map(e -> "data: " + ((TextBlockDeltaEvent) e).getDelta() + "\n\n");
    }
}

---

6. 三种传输方式

AgentScope 的 McpClientBuilder 支持三种 MCP 传输协议：

传输方式	方法	适用场景
Streamable HTTP（推荐）	streamableHttpTransport(url)	远程 MCP Server，如高德
SSE	sseTransport(url)	兼容旧版 MCP Server
Stdio	stdioTransport(command, args...)	本地进程，如本地 Python MCP Server

// Streamable HTTP（高德）
McpClientBuilder.create("amap")
    .streamableHttpTransport("https://mcp.amap.com/mcp?key=xxx")
    .buildSync();

// SSE
McpClientBuilder.create("weather")
    .sseTransport("http://localhost:8080/sse")
    .buildSync();

// 本地 Stdio
McpClientBuilder.create("local-tool")
    .stdioTransport("python", List.of("-m", "my_mcp_server"))
    .buildSync();

---

7. 多 MCP Server 同时接入

Toolkit toolkit = new Toolkit();

// 高德地图
McpClientWrapper amap = McpClientBuilder.create("amap")
    .streamableHttpTransport("https://mcp.amap.com/mcp?key=" + amapKey)
    .buildSync();

// 自定义 MCP Server
McpClientWrapper custom = McpClientBuilder.create("custom")
    .sseTransport("http://localhost:19000")
    .buildSync();

// 同时注册
toolkit.registerMcpClient(amap).block();
toolkit.registerMcpClient(custom).block();

ReActAgent agent = ReActAgent.builder()
    .name("multi-mcp-agent")
    .model(model)
    .toolkit(toolkit)
    .build();

Agent 自动获得两个 MCP Server 的全部工具，LLM 会根据查询选择合适的工具调用。

---

8. 自定义 Header 认证

部分 MCP Server 需要 Bearer Token 等 Header 认证：

McpClientWrapper client = McpClientBuilder.create("secure-mcp")
    .streamableHttpTransport("https://secure-mcp.example.com/mcp")
    .header("Authorization", "Bearer " + token)
    .header("X-Custom-Header", "value")
    .timeout(Duration.ofSeconds(30))
    .buildSync();

---