> ## Documentation Index
> Fetch the complete documentation index at: https://javaai.pig4cloud.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP 助手

# MCP 助手

Spring AI 提供了几个助手类来简化与模型上下文协议 (MCP) 的交互。

## `McpUtils`

`McpUtils` 类提供了一组实用方法，用于创建符合 MCP 规范的消息。

### 创建用户消息

你可以使用 `McpUtils.user()` 方法创建一个用户角色的消息：

```java theme={"system"}
import org.springframework.ai.model.content. யூserMessage;
import org.springframework.ai.mcp.McpUtils;

// ...

UserMessage userMessage = McpUtils.user("Tell me a joke about a cat."); // 示例提示内容通常保留英文
```

### 创建助手消息

你可以使用 `McpUtils.assistant()` 方法创建一个助手角色的消息：

```java theme={"system"}
import org.springframework.ai.model.content.AssistantMessage;
import org.springframework.ai.mcp.McpUtils;

// ...

AssistantMessage assistantMessage = McpUtils.assistant("Why was the cat sitting on the computer? To keep an eye on the mouse!"); // 示例提示内容通常保留英文
```

### 创建带工具调用的助手消息

你可以使用 `McpUtils.assistant()` 方法创建一个包含工具调用的助手消息：

```java theme={"system"}
import org.springframework.ai.model.content.AssistantMessage;
import org.springframework.ai.mcp.McpUtils;
import org.springframework.ai.model. யூserMessage;

import java.util.List;

// ...

AssistantMessage.ToolCall toolCall = new AssistantMessage.ToolCall("toolCallId", "weatherTool", "{\"location\": \"San Francisco\"}"); // 示例参数保留英文
AssistantMessage assistantMessageWithToolCall = McpUtils.assistant(List.of(toolCall));
```

### 创建带工具调用响应的工具消息

你可以使用 `McpUtils.tool()` 方法创建一个包含工具调用响应的工具消息：

```java theme={"system"}
import org.springframework.ai.model.content.ToolResponseMessage;
import org.springframework.ai.mcp.McpUtils;

import java.util.UUID;

// ...

String toolCallId = UUID.randomUUID().toString();
ToolResponseMessage toolResponseMessage = McpUtils.tool("The weather in San Francisco is sunny.", toolCallId, "weatherTool"); // 示例响应及参数保留英文
```

## `McpReason`

`McpReason` 类表示工具调用的原因。它帮助将工具调用请求与相应的工具调用响应关联起来。

### 创建 `McpReason`

你可以为工具调用请求创建一个 `McpReason`：

```java theme={"system"}
import org.springframework.ai.mcp.McpReason;
import org.springframework.ai.model.content.AssistantMessage;

// ...

AssistantMessage.ToolCall toolCall = new AssistantMessage.ToolCall("toolCallId", "calculatorTool", "{\"expression\": \"2 + 2\"}"); // 示例参数保留英文
McpReason reason = new McpReason(List.of(toolCall), null);
```

或者，你可以为工具调用响应创建一个 `McpReason`：

```java theme={"system"}
import org.springframework.ai.mcp.McpReason;
import org.springframework.ai.model.content.ToolResponseMessage;

import java.util.List;

// ...

ToolResponseMessage toolResponseMessage = new ToolResponseMessage("4", "toolCallId", "calculatorTool"); // 示例响应及参数保留英文
McpReason reason = new McpReason(null, List.of(toolResponseMessage));
```

## `McpRole`

`McpRole` 枚举定义了 MCP 消息中允许的角色：`USER`, `ASSISTANT`, 和 `TOOL`。

```java theme={"system"}
import org.springframework.ai.mcp.McpRole;

// ...

McpRole userRole = McpRole.USER;
McpRole assistantRole = McpRole.ASSISTANT;
McpRole toolRole = McpRole.TOOL;
```

## `McpMessage`

`McpMessage` 是 MCP 消息的基类。它包含消息的通用属性，如 `id`, `role`, `reason`, 和 `sequenceId`。

` யூserMessage`, `AssistantMessage`, 和 `ToolResponseMessage` 都扩展了 `McpMessage`。

### 消息内容

消息内容可以以多种格式提供，包括纯文本、模板化文本和多部分内容。

#### 纯文本内容

```java theme={"system"}
import org.springframework.ai.model.content. யூserMessage;
import org.springframework.ai.mcp.McpUtils;

// ...

UserMessage userMessage = McpUtils.user("What is the capital of France?"); // 示例提示内容通常保留英文
```

#### 模板化内容

你可以使用 `MessageBuilder` 来创建模板化内容：

```java theme={"system"}
import org.springframework.ai.mcp.McpMessage;
import org.springframework.ai.mcp.McpRole;
import org.springframework.ai.model. யூserMessage;
import org.springframework.ai.model.MessageBuilder;

import java.util.Map;

// ...

String template = "Tell me a joke about {animal}."; // 示例模板通常保留英文
Map<String, Object> model = Map.of("animal", "dog");

McpMessage<String> templatedMessage = MessageBuilder.with रोल(McpRole.USER)
    .withTemplate(template)
    .withModel(model)
    .build();
```

#### 多部分内容

多部分内容允许你在单个消息中组合不同类型的内容（例如，文本和图像）。

```java theme={"system"}
import org.springframework.ai.model.content.MultiPart யூserMessage;
import org.springframework.ai.model.content. யூserMessage;
import org.springframework.ai.model.Media;
import org.springframework.util.MimeTypeUtils;

import java.net.URI;
import java.net.URISyntaxException;
import java.util.List;

// ...

MultiPartUserMessage multiPartUserMessage;
try {
    multiPartUserMessage = new MultiPartUserMessage(
        "What is in this image?", // 示例提示内容通常保留英文
        List.of(new Media(MimeTypeUtils.IMAGE_PNG, new URI("https://example.com/image.png")))
    );
} catch (URISyntaxException e) {
    throw new RuntimeException(e);
}
```

## 总结

这些助手类旨在简化在 Spring AI 应用程序中构建和使用 MCP 消息的过程。

<Card title="文档有误？请协助编辑" icon="pencil" href="https://github.com/javaai-pig4cloud-com/javaai-docs/edit/main/spring-ai/api/mcp/mcp-helpers.mdx">
  发现文档问题？点击此处直接在 GitHub 上编辑并提交 PR，帮助我们改进文档！
</Card>