> ## 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 服务器启动器 (`spring-ai-mcp-server-boot-starter`) 简化了符合模型上下文协议 (MCP) 的服务器应用程序的创建。

## 概述

MCP 服务器启动器提供了：

* 自动配置 MCP 端点。
* 用于处理 MCP 请求的组件。
* 与 Spring Boot 应用程序的无缝集成。

## 入门

要开始使用 MCP 服务器启动器，请将以下依赖项添加到您的 `pom.xml` 文件中：

```xml theme={"system"}
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-mcp-server-boot-starter</artifactId>
</dependency>
```

## 配置

MCP 服务器启动器可以通过 `application.properties` 或 `application.yml` 文件进行配置。以下是一些常见的配置选项：

### 服务器属性

* `spring.ai.mcp.server.enabled`: 启用或禁用 MCP 服务器 (默认为 `true`)。
* `spring.ai.mcp.server.path`: MCP API 端点的基础路径 (默认为 `/mcp`)。
* `spring.ai.mcp.server.port`: MCP 服务器监听的端口 (默认为应用程序的服务器端口)。

示例 `application.properties`：

```properties theme={"system"}
spring.ai.mcp.server.path=/api/mcp
```

### 模型配置

您需要配置您的 Spring AI 模型 (例如，ChatModel、EmbeddingModel)。MCP 服务器将使用这些已配置的模型来处理传入的请求。
确保您已按照各个模型文档中的说明配置了所需的模型 bean。

例如，要配置 OpenAI 聊天模型：

```properties theme={"system"}
spring.ai.openai.api-key=YOUR_OPENAI_API_KEY
spring.ai.openai.chat.options.model=gpt-4o
```

## 用法

一旦配置完成，MCP 服务器启动器将自动暴露处理 MCP 请求所需的端点。

### MCP 端点

默认情况下，MCP 服务器在 `/mcp/v1/chat/completions` (对于聊天模型) 和 `/mcp/v1/embeddings` (对于嵌入模型) 上暴露端点。这些路径可以通过 `spring.ai.mcp.server.path` 属性进行自定义。

### 处理程序

启动器提供了 `McpChatHandler` 和 `McpEmbeddingHandler` 来处理相应的 MCP 请求。这些处理程序使用已配置的 Spring AI 模型与底层 AI 提供程序进行交互。

您可以自定义这些处理程序的行为，或者通过提供您自己的 `McpChatHandler` 或 `McpEmbeddingHandler` bean 来提供您自己的实现。

#### 自定义 `McpChatHandler`

```java theme={"system"}
@Bean
public McpChatHandler customMcpChatHandler(ChatModel chatModel) {
    // 自定义逻辑
    return new McpChatHandler(chatModel, new McpChatOptions(), null);
}
```

其中 `McpChatOptions` 可以包含特定于聊天的选项，如默认提示模板或后处理器。

### 请求和响应格式

服务器期望请求并以 MCP 指定的格式发送响应。有关详细信息，请参阅 MCP 规范。

## 示例：创建一个简单的 MCP 服务器

1. **添加依赖项**：如上所述，将 `spring-ai-mcp-server-boot-starter` 和模型特定的启动器 (例如，`spring-ai-openai-spring-boot-starter`) 添加到您的 `pom.xml` 中。

2. **配置属性**：在 `application.properties` 中配置您的 AI 模型凭证和可选的 MCP 服务器属性。

   ```properties theme={"system"}
   # OpenAI 配置
   spring.ai.openai.api-key=YOUR_OPENAI_API_KEY
   spring.ai.openai.chat.options.model=gpt-4o

   # MCP 服务器配置 (可选)
   # spring.ai.mcp.server.path=/custom-mcp-path
   ```

3. **运行应用程序**：启动您的 Spring Boot 应用程序。

MCP 服务器现在应该正在运行并准备好在配置的路径上处理 MCP 请求。

## 安全性

保护您的 MCP 端点非常重要。考虑使用 Spring Security 或其他身份验证/授权机制来保护您的 API。

以下是使用 Spring Security 进行基本身份验证的简单示例：

1. 添加 Spring Security 依赖项：

   ```xml theme={"system"}
   <dependency>
       <groupId>org.springframework.boot</groupId>
       <artifactId>spring-boot-starter-security</artifactId>
   </dependency>
   ```

2. 配置安全规则：

   ```java theme={"system"}
   import org.springframework.context.annotation.Bean;
   import org.springframework.context.annotation.Configuration;
   import org.springframework.security.config.annotation.web.builders.HttpSecurity;
   import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
   import org.springframework.security.core.userdetails.User;
   import org.springframework.security.core.userdetails.UserDetails;
   import org.springframework.security.provisioning.InMemoryUserDetailsManager;
   import org.springframework.security.web.SecurityFilterChain;

   import static org.springframework.security.config.Customizer.withDefaults;

   @Configuration
   @EnableWebSecurity
   public class SecurityConfig {

       @Bean
       public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
           http
               .authorizeHttpRequests(authorizeRequests ->
                   authorizeRequests
                       .requestMatchers("/mcp/**").authenticated() // 保护 MCP 端点
                       .anyRequest().permitAll()
               )
               .httpBasic(withDefaults());
           return http.build();
       }

       @Bean
       public InMemoryUserDetailsManager userDetailsService() {
           UserDetails user = User.withDefaultPasswordEncoder()
               .username("user")
               .password("password")
               .roles("USER")
               .build();
           return new InMemoryUserDetailsManager(user);
       }
   }
   ```

<Warning>
  上述安全配置仅为示例。对于生产环境，请实施更强大的安全措施。
</Warning>

## 故障排除

* **404 未找到**：验证 MCP 端点路径是否正确配置，并且您的应用程序是否正在运行。
* **身份验证错误**：确保您的 AI 模型凭证正确无误且具有必要的权限。
* **依赖项冲突**：检查您的 `pom.xml` 是否存在可能导致问题的冲突依赖项。

有关更多详细信息和高级配置，请参阅 Spring AI MCP [参考文档](https://docs.spring.io/spring-ai/reference/api/mcp.html) 和 [GitHub 仓库](https://github.com/spring-projects/spring-ai/tree/main/spring-ai-spring-boot-starters/spring-ai-mcp-server-spring-boot-starter)。

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