SpringAI MCP服务端开发实战：从天气查询到邮件发送

1. SpringAI MCP 服务端概述

SpringAI的Model Context Protocol（MCP）是一个强大的工具集成框架，它允许开发者将各种功能封装成可调用的工具，并通过标准化协议与AI模型进行交互。作为一名长期从事Java开发的工程师，我在实际项目中发现MCP特别适合构建需要AI增强能力的服务端应用。

MCP服务端主要支持三种通信模式：

• Stdio（标准输入输出）：适合本地调试和简单工具
• SSE（Server-Sent Events）：适用于需要流式响应的场景
• Streamable HTTP：功能最完整的HTTP协议实现

这三种模式各有优势，开发者可以根据具体需求选择。下面我将通过四个实际案例，详细讲解如何构建不同类型的MCP服务端。

2. Stdio服务端实现：高德天气查询

2.1 项目配置与依赖

首先创建一个基础的Spring Boot项目，添加以下关键依赖：

xml复制<properties>
    <java.version>17</java.version>
    <spring-ai.version>1.1.2</spring-ai.version>
</properties>

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server</artifactId>
</dependency>

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.ai</groupId>
            <artifactId>spring-ai-bom</artifactId>
            <version>${spring-ai.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

这里使用SpringAI 1.1.2版本，需要Java 17或更高版本。MCP服务端核心依赖是spring-ai-starter-mcp-server。

2.2 天气服务工具实现

核心工具类需要完成两个功能：

1. 根据城市名获取城市编码
2. 根据城市编码获取天气信息

java复制@Service
public class WeatherService {
    private final String KEY;
    private final RestClient restClient;

    public WeatherService() {
        this.restClient = RestClient.builder().build();
        this.KEY = System.getenv("AMAP_KEY");
    }

    @Tool(description = "根据城市名称查询对应的城市编码")
    public String getAdCode(@ToolParam(description = "查询的城市，比如: 北京") String keywords) {
        // 实现细节...
    }

    @Tool(description = "根据城市编码查询对应城市的天气信息")
    public String getWeather(@ToolParam(description = "查询的城市编码，比如: 110101") String adCode) {
        // 实现细节...
    }
}

关键点说明：

• @Tool注解标记这是一个MCP工具
• @ToolParam描述参数用途
• 使用RestClient进行HTTP调用
• API密钥通过环境变量注入，提高安全性

2.3 工具注册与测试

在启动类中注册工具：

java复制@SpringBootApplication
public class Application {
    @Bean
    public ToolCallbackProvider weatherTools(WeatherService weatherService) {
        return MethodToolCallbackProvider.builder()
            .toolObjects(weatherService)
            .build();
    }
}

测试时可以使用Cherry Studio工具，配置如下JSON：

json复制{
  "mcpServers": {
    "weather-server": {
      "command": "java",
      "args": [
        "-Dfile.encoding=UTF-8",
        "-Dsun.jnu.encoding=UTF-8",
        "-jar",
        "path/to/your.jar"
      ],
      "env": {
        "AMAP_KEY": "your_api_key"
      }
    }
  }
}

注意事项：

1. 高德API有调用频率限制，生产环境需要添加缓存
2. 错误处理要完善，考虑网络超时等情况
3. API密钥不要硬编码在代码中

3. SSE服务端实现：百度翻译API

3.1 项目配置

SSE服务端需要不同的starter：

xml复制<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId>
    <version>${spring-ai.version}</version>
</dependency>

配置文件设置：

properties复制server.port=8086
spring.ai.mcp.server.protocol=sse
spring.ai.mcp.server.sse-endpoint=/sse

3.2 翻译服务实现

翻译服务需要考虑多语言支持：

java复制@Service
public class TranslationService {
    @Tool(description = "将句子或词从一种语言翻译为另一种语言")
    public String translate(
            @ToolParam(description = "需要翻译的句子或词") String text,
            @ToolParam(description = "句子当前语言标识") Language languageFrom,
            @ToolParam(description = "将要翻译的语言标识") Language languageTo) {
        // 实现细节...
    }
    
    public enum Language {
        ZH("zh", "中文"),
        EN("en", "英语"),
        // 其他语言...
    }
}

百度翻译API需要签名验证，关键签名方法：

java复制private Map<String, String> buildTranslateParams(String query, String from, String to) throws Exception {
    Map<String, String> params = new HashMap<>();
    params.put("q", query);
    params.put("from", from);
    params.put("to", to);
    params.put("appid", appId);
    String salt = String.valueOf(System.currentTimeMillis());
    params.put("salt", salt);
    params.put("sign", md5(appId + query + salt + securityKey));
    return params;
}

3.3 测试与优化

测试时注意：

1. 长文本需要分段处理
2. 自动检测语言时准确率问题
3. 特殊字符的转义处理

优化建议：

1. 添加本地缓存减少API调用
2. 实现批量翻译接口
3. 添加翻译记忆功能

4. Streamable HTTP服务端：邮件发送

4.1 邮件服务配置

添加邮件相关依赖：

xml复制<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-mail</artifactId>
</dependency>

配置SMTP：

properties复制spring.mail.host=smtp.163.com
spring.mail.port=465
spring.mail.username=your@163.com
spring.mail.password=your_password
spring.mail.properties.mail.smtp.ssl.enable=true

4.2 邮件工具实现

支持多种邮件格式：

java复制@Service
public class EmailService {
    @Tool(description = "给指定邮箱发送邮件信息")
    public String sendSimpleEmail(
            @ToolParam(description = "收件人邮箱") String[] to,
            @ToolParam(description = "邮件主题") String subject,
            @ToolParam(description = "邮件正文") String content,
            @ToolParam(description = "邮件类型") EmailType emailType) {
        // 实现细节...
    }
    
    public enum EmailType {
        MARKDOWN, HTML, TEXT
    }
}

Markdown转HTML使用Flexmark：

java复制public static String convertToHtml(String markdownStr) {
    MutableDataSet dataSet = new MutableDataSet();
    return HtmlRenderer.builder(dataSet).build()
            .render(Parser.builder(dataSet).build()
                    .parse(markdownStr));
}

4.3 安全注意事项

1. 邮件内容需要过滤XSS攻击
2. 设置发送频率限制防止滥用
3. 敏感信息不能通过明文邮件发送
4. 使用DKIM、SPF等提高邮件可信度

5. 联网搜索实现：SearXNG集成

5.1 SearXNG环境搭建

使用Docker快速部署：

bash复制docker pull searxng/searxng:latest
mkdir -p ./searxng/config/ ./searxng/data/
docker run --name searxng -d \
    -p 8888:8080 \
    -v "./config/:/etc/searxng/" \
    -v "./data/:/var/cache/searxng/" \
    docker.io/searxng/searxng:latest

配置修改config/settings.yml：

yaml复制server:
  base_url: "http://localhost:8888/"
  secret_key: "your_secret_key"
search:
  formats:
    - json

5.2 搜索工具实现

java复制@Service
public class SearXNGService {
    @Tool(description = "根据关键字联网搜索")
    public String search(@ToolParam(description = "搜索关键字") String keyword) {
        String url = "/search?q=" + keyword 
            + "&format=json&engines=bing&categories=general&language=zh-CN";
        Response response = restClient.get().uri(url).retrieve().body(Response.class);
        // 结果处理...
    }
}

5.3 高级功能扩展

1. 搜索结果缓存
2. 多搜索引擎聚合
3. 结果排名算法调整
4. 搜索建议功能
5. 个性化搜索历史

6. 性能优化与最佳实践

6.1 性能优化技巧

1. 连接池配置：对RestClient和数据库连接进行合理配置
2. 缓存策略：使用Redis缓存频繁访问的数据
3. 异步处理：耗时操作改为异步执行
4. 批处理：合并多个小请求为批量请求

6.2 安全最佳实践

1. API密钥管理：使用Vault或KMS管理敏感信息
2. 输入验证：对所有输入参数进行严格验证
3. 速率限制：防止API被滥用
4. 日志脱敏：确保日志不记录敏感信息

6.3 监控与运维

1. 添加健康检查端点
2. 集成Prometheus监控
3. 配置合理的日志级别
4. 实现优雅停机

7. 常见问题排查

7.1 工具无法注册

症状：工具在Cherry Studio中不可见
排查步骤：

1. 检查@Tool注解是否正确使用
2. 确认工具类被Spring管理
3. 检查ToolCallbackProvider是否正确注册
4. 查看启动日志是否有错误

7.2 API调用失败

症状：工具能注册但调用失败
排查步骤：

1. 检查网络连接
2. 验证API密钥是否正确
3. 检查参数格式是否符合要求
4. 查看第三方API文档是否有变更

7.3 性能问题

症状：响应缓慢或超时
优化建议：

1. 添加缓存层
2. 优化数据库查询
3. 考虑异步处理
4. 增加超时设置

在实际项目中，我发现SpringAI MCP最大的优势在于它的灵活性。通过标准化的协议，我们可以轻松集成各种功能，同时保持与AI模型的无缝交互。特别是在需要快速原型开发的场景中，这种架构可以大大缩短开发周期。