用 Solon AI 从零构建 MCP 工具服务：让 AI Agent 拥有真实世界的能力

你是否想过，让 AI 助手不仅能聊天，还能帮你查天气、订机票、发邮件？MCP（Model Context Protocol）正是实现这一目标的桥梁。而 Solon AI，作为一款轻量级 Java 框架，能帮助你快速搭建 MCP 工具服务。本文将手把手带你从零构建一个 MCP 服务，让 AI Agent 拥有“真实世界”的能力。## 什么是 MCP 和 Solon AI？### MCP：AI 与世界的接口MCP 是一种协议，定义了 AI 模型如何调用外部工具（如 API、数据库、文件系统）。它让 AI 从“闭门造车”变为“开门迎客”——通过工具调用，AI 可以获取实时数据、执行操作，从而更精准地响应用户需求。例如，用户说“帮我查今天北京的天气”，AI 通过 MCP 调用天气 API，返回结果。### Solon AI：轻量级框架的利器Solon AI 是基于 Solon 框架的 AI 扩展，它简化了 MCP 服务的开发。Solon 本身以“轻量、高效、易用”著称，无需 Spring Boot 的复杂配置，却能提供类似的功能。结合 Solon AI，你可以用几行代码定义工具服务，然后让 AI Agent 自动发现并调用它们。## 准备工作：搭建开发环境在开始编码前，确保你的环境满足以下条件：- JDK 17+（推荐使用 OpenJDK）- Maven 3.6+ 或 Gradle 7± 一个文本编辑器或 IDE（如 IntelliJ IDEA）我们将使用 Maven 构建项目，并添加 Solon AI 依赖。## 从零构建 MCP 工具服务### 第一步：创建项目并添加依赖创建一个 Maven 项目，在 pom.xml 中添加以下依赖：xml<dependencies> <!-- Solon AI 核心依赖 --> <dependency> <groupId>org.noear</groupId> <artifactId>solon-ai</artifactId> <version>2.7.0</version> </dependency> <!-- Solon Web 支持（用于启动服务） --> <dependency> <groupId>org.noear</groupId> <artifactId>solon-web</artifactId> <version>2.7.0</version> </dependency> <!-- JSON 解析库 --> <dependency> <groupId>com.alibaba.fastjson2</groupId> <artifactId>fastjson2</artifactId> <version>2.0.40</version> </dependency></dependencies>### 第二步：定义第一个 MCP 工具——计算器MCP 工具本质上是一个带有注解的 Java 方法。Solon AI 通过 @McpTool 注解标记工具类和方法，然后自动生成服务端点。以下是一个简单的计算器工具：javaimport org.noear.solon.annotation.Component;import org.noear.solon.ai.mcp.annotation.McpTool;import org.noear.solon.ai.mcp.annotation.McpParam;@Component // 声明为 Solon 组件，自动扫描public class CalculatorTools { @McpTool(description = "执行数学计算，支持加、减、乘、除") public String calculate( @McpParam(description = "第一个数字") double a, @McpParam(description = "操作符，如 +、-、*、/") String operator, @McpParam(description = "第二个数字") double b ) { double result; switch (operator) { case "+": result = a + b; break; case "-": result = a - b; break; case "*": result = a * b; break; case "/": if (b == 0) { return "错误：除数不能为零"; } result = a / b; break; default: return "错误：不支持的操作符 " + operator; } return String.format("%.2f %s %.2f = %.2f", a, operator, b, result); }}代码解释：- @Component：让 Solon 在启动时自动扫描该类。- @McpTool：标记该方法为 MCP 工具，description 描述工具功能，AI Agent 会读取此信息来选择调用。- @McpParam：定义每个参数的含义，帮助 AI 理解参数用途。- 方法返回字符串，包含计算结果或错误信息。### 第三步：启动服务并测试编写一个启动类，运行 Solon 应用：javaimport org.noear.solon.Solon;public class McpServerApp { public static void main(String[] args) { // 启动 Solon 应用，默认端口 8080，并启用 MCP 服务 Solon.start(McpServerApp.class, args, app -> { // 配置 MCP 服务的端点路径（可选，默认为 /mcp） app.context().getBeanOfType(McpService.class) .setEndpoint("/my-mcp-tools"); }); }}运行后，访问 http://localhost:8080/my-mcp-tools 即可看到 MCP 服务端点。你可以用 Postman 或 curl 测试：bashcurl -X POST http://localhost:8080/my-mcp-tools \ -H "Content-Type: application/json" \ -d '{"tool":"calculate","params":{"a":10,"operator":"+","b":5}}'返回结果：10.00 + 5.00 = 15.00### 第四步：集成真实 API——天气查询工具计算器是入门，真实世界的需求往往需要调用外部 API。下面我们构建一个天气查询工具，调用 OpenWeatherMap 的免费 API：javaimport org.noear.solon.annotation.Component;import org.noear.solon.ai.mcp.annotation.McpTool;import org.noear.solon.ai.mcp.annotation.McpParam;import java.net.URI;import java.net.http.HttpClient;import java.net.http.HttpRequest;import java.net.http.HttpResponse;import com.alibaba.fastjson2.JSONObject;@Componentpublic class WeatherTools { // 注意：请替换为你的 OpenWeatherMap API Key（免费注册即可获取） private static final String API_KEY = "your-api-key-here"; @McpTool(description = "查询指定城市的实时天气，返回温度、湿度、天气状况") public String getWeather( @McpParam(description = "城市名称，如 Beijing、Shanghai、New York") String city ) { try { // 构建 API 请求 URL String url = String.format( "https://api.openweathermap.org/data/2.5/weather?q=%s&appid=%s&units=metric&lang=zh_cn", city, API_KEY ); // 发送 HTTP 请求 HttpClient client = HttpClient.newHttpClient(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(url)) .GET() .build(); HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString()); // 解析 JSON 响应 JSONObject json = JSONObject.parseObject(response.body()); if (json.getIntValue("cod") != 200) { return "错误：无法获取 " + city + " 的天气信息，请检查城市名称"; } // 提取关键信息 JSONObject main = json.getJSONObject("main"); double temp = main.getDouble("temp"); int humidity = main.getIntValue("humidity"); String description = json.getJSONArray("weather") .getJSONObject(0) .getString("description"); return String.format("城市：%s\n温度：%.1f°C\n湿度：%d%%\n天气状况：%s", city, temp, humidity, description); } catch (Exception e) { return "错误：查询失败 - " + e.getMessage(); } }}代码解释：- 使用 Java 原生 HttpClient 发送 HTTP 请求，无需额外依赖。- 调用 OpenWeatherMap API，获取 JSON 格式的天气数据。- 解析 JSON 并返回格式化字符串，方便 AI Agent 理解。- 错误处理：如果城市不存在或网络问题，返回友好提示。测试天气工具：bashcurl -X POST http://localhost:8080/my-mcp-tools \ -H "Content-Type: application/json" \ -d '{"tool":"getWeather","params":{"city":"Beijing"}}'返回示例：城市：Beijing温度：15.3°C湿度：45%天气状况：晴## 让 AI Agent 调用 MCP 工具现在，你已经有了两个 MCP 工具。接下来，集成 AI Agent（如 OpenAI、Claude 或本地模型）即可。Solon AI 支持自动生成 MCP 服务描述，AI Agent 通过 tools 参数发现工具。例如，在 OpenAI 的 API 调用中，你可以将 MCP 端点 URL 作为 tools 参数传递。Solon AI 会自动将 @McpTool 注解信息转换为 JSON Schema，供 AI 理解。## 总结通过本文，你学会了：1. MCP 的核心概念：它是 AI 与外部世界的桥梁，让 AI Agent 能调用真实服务。2. Solon AI 的便捷性：用 @McpTool 和 @McpParam 注解，几行代码就能定义工具服务。3. 实战构建：从计算器到天气查询，展示了从简单到真实的工具开发过程。MCP 工具服务的潜力远不止于此——你可以扩展它调用数据库、发送邮件、控制 IoT 设备等。Solon AI 的轻量特性，让开发者能快速迭代，让 AI Agent 真正融入业务场景。现在，打开你的 IDE，开始构建属于你的 MCP 服务吧！