企业官网建设流程全解析

1. 为什么 Java 开发者需要一个国产 MCP Server 方案

MCP（Model Context Protocol）这两年在 AI 圈子里热度一直不低，它的核心价值是把大模型和外部工具、数据源用一套标准协议连起来。你写一个工具方法，模型就能在对话里按需调用它，不用为每个模型单独适配一遍。但如果你去搜 MCP Server 的入门教程，会发现一个很尴尬的现实：绝大多数示例都是 Python 或者 Node.js 写的。Java 开发者想跟做，要么找不到对应依赖，要么找到的 SDK 文档稀薄、版本对不上，跑一半就卡在环境上。

我自己是常年写 Java 的，第一次接触 MCP 的时候翻了半天资料，能直接复制粘贴跑通的 Java 示例少得可怜。更麻烦的是版本兼容问题——很多新框架默认要求 Java 17 甚至 Java 21，而不少公司生产环境还停在 Java 8。你总不能为了跑一个 MCP 工具就把整个项目的 JDK 升上去。

Solon AI MCP 就是在这个背景下值得关注的一个国产解决方案。Solon 本身是国内开发者很熟悉的 Java 框架，轻量、启动快、对低版本 JDK 友好。它新增的 solon-ai-mcp 模块同时支持 Mcp Server 和 Mcp Client，官方明确支持 Java 8 到 Java 24，版本号跟随 Solon 主线走，当前是 3.2.0。这意味着你手头不管是老项目还是新项目，基本都能直接引入。

这篇文章要解决的就是一件事：让你从零跑通第一个 Solon AI MCP Server 的 Helloworld。我会给出完整的 Maven 依赖、可复制的端点配置、工具方法写法，以及一个用 McpClientToolProvider 写的单元测试来验证工具真的被调用了。整个过程不需要你懂 MCP 协议的底层细节，照着写就行。适合谁？适合有 Java 基础、想快速把 MCP 能力接进自己项目的开发者，尤其是那些被 Python 示例劝退、或者被 JDK 版本卡住的人。

2. Solon AI MCP 前置准备与依赖引入踩坑记录

在动手写代码之前，先把环境理清楚。Solon AI MCP 的前置条件其实很宽松，这也是它相比其他方案的一个明显优势。

JDK 方面，官方声明支持 Java 8 到 Java 24。我实测下来，Java 8、Java 11、Java 17 都能正常编译运行，没有出现因为语言特性导致的编译失败。构建工具用 Maven 就行，Gradle 也可以，但本文以 Maven 为主，因为大部分 Java 项目还是 Maven 居多。Solon 的版本管理比较集中，solon-ai-mcp 的版本号跟 Solon 主版本保持一致，当前是 3.2.0，你不需要单独去记一个独立的版本号。

引入依赖这一步看起来简单，但有几个坑我踩过，提前说清楚能帮你省时间。

第一个坑是依赖坐标写错。solon-ai-mcp 的 groupId 是 org.noear，artifactId 是 solon-ai-mcp，不是 solon-ai 也不是 solon-mcp。网上有些文章写的是旧版本或者笔误，复制过去会直接报找不到依赖。

第二个坑是只引了 solon-ai-mcp 却没引 Solon 的核心依赖。solon-ai-mcp 是建立在 Solon 运行时之上的，你需要确保项目里有 solon 的核心包。如果你是用 Solon 官方脚手架生成的项目，核心依赖已经在了；如果是往一个普通 Maven 项目里加，记得补上。

第三个坑是版本冲突。如果你的项目里已经有其他 AI 相关的 SDK，注意检查有没有传递依赖把 Solon 的版本拉低或者拉高。我遇到过一次因为另一个库引入了不同版本的 noear 包，导致启动时报类找不到，最后用 dependencyManagement 锁死版本才解决。

下面是完整的 Maven 依赖片段，你可以直接复制到 pom.xml 的 dependencies 里：

<dependency> <groupId>org.noear</groupId> <artifactId>solon-ai-mcp</artifactId> <version>3.2.0</version> </dependency>

如果你是从零建项目，建议再补上 Solon 的基础依赖和测试依赖，方便后面写单元测试：

<dependency> <groupId>org.noear</groupId> <artifactId>solon-web</artifactId> <version>3.2.0</version> </dependency> <dependency> <groupId>org.noear</groupId> <artifactId>solon-test</artifactId> <version>3.2.0</version> <scope>test</scope> </dependency>

这里有个细节值得说：solon-ai-mcp 支持多端点架构，你可以手动构建端点，也可以用注解构建。注解方式对 Java 开发者来说最友好，因为它跟写 Spring MVC 的 Controller 几乎一模一样，学习成本极低。这也是我推荐新手从这个方案入手的原因——你不需要理解 MCP 的 JSON-RPC 消息格式，注解会帮你处理掉。

另外提醒一句，Solon 的启动类写法跟 Spring Boot 不同，它用的是 Solon.start 而不是 SpringApplication.run。如果你之前没接触过 Solon，这一点要适应一下，但也就一行代码的事。

3. 可复制的 MCP Server 端点与工具配置片段

这一节是核心，我会把完整的代码结构拆开讲，每一段都可以直接复制。Solon AI MCP 的注解体系设计得很像 MVC，你只要理解三个注解就能写出第一个工具。

先看整体结构。一个最小的 MCP Server 需要两部分：一个启动类，一个带 @McpServerEndpoint 注解的服务类。启动类负责把 Solon 跑起来，服务类负责暴露工具。

启动类长这样：

import org.noear.solon.Solon; public class App { public static void main(String[] args) { Solon.start(App.class, args); } }

就这么简单。Solon.start 会自动扫描注解，把 @McpServerEndpoint 标记的类注册成 MCP 端点。你不需要额外写配置文件，也不需要手动注册路由。

接下来是工具服务类，这是重点：

import org.noear.solon.ai.mcp.server.annotation.McpServerEndpoint; import org.noear.solon.ai.mcp.server.annotation.ToolMapping; import org.noear.solon.ai.mcp.server.annotation.ToolParam; @McpServerEndpoint(sseEndpoint = "/sse") public class HelloService { @ToolMapping(description = "你好世界") public String hello(@ToolParam(description = "名字") String name) { return "hello " + name; } }

逐行解释一下。@McpServerEndpoint(sseEndpoint = "/sse") 表示这个类是一个 MCP 服务端点，对外暴露的 SSE 地址是 /sse。SSE 是 MCP 常用的传输方式之一，客户端通过这个地址建立连接。你可以把它理解成 Web 里的 @RestController 加 @RequestMapping 的组合。

@ToolMapping 标记这个方法是一个可被模型调用的工具。description 属性非常关键，它不是给你看的注释，而是给大模型看的提示词。模型会根据这段描述判断什么时候该调用这个工具。所以描述要写清楚工具的功能，别写得太模糊。比如你写“处理数据”，模型根本不知道处理什么数据；写“根据名字返回问候语”，模型就能准确判断。

@ToolParam 标记方法参数，description 同样会传给模型，告诉它这个参数是什么含义。模型在调用时会根据参数描述来填充值。

方法体就是普通的 Java 代码，你可以在里面做任何事——查数据库、调外部接口、做计算都行。返回值会被序列化后返回给客户端。

这里有个容易忽略的点：@ToolMapping 的方法返回值类型。简单类型比如 String、int 可以直接返回，复杂对象 Solon 会帮你转成 JSON。我建议第一个 Helloworld 就用 String，跑通之后再试复杂类型。

如果你需要多个工具，就在同一个类里写多个 @ToolMapping 方法，或者建多个 @McpServerEndpoint 类。Solon 支持多端点，每个端点可以有自己独立的 sseEndpoint 路径。

配置层面，Solon 默认端口是 8080。如果你想改端口，可以在 resources 下建一个 app.yml：

server: port: 8080

这个文件不是必须的，但建议加上，方便你后面调整。Solon 的配置文件格式支持 yml 和 properties，跟 Spring Boot 类似，迁移过来没什么障碍。

把这三段代码放好，目录结构大概是：

src/main/java/App.java src/main/java/HelloService.java src/main/resources/app.yml

启动 main 方法，控制台会打印 Solon 的启动信息和端点注册信息。看到类似“McpServerEndpoint registered: /sse”的日志，就说明端点注册成功了。

4. 验证 Helloworld 工具调用：用 McpClientToolProvider 写单测

服务跑起来了，但你怎么确认工具真的能被调用？光看启动日志不够，得实际发一次请求。Solon AI MCP 提供了 McpClientToolProvider，可以很方便地在单元测试里模拟客户端调用。

先看测试类的完整代码：

import lombok.extern.slf4j.Slf4j; import org.junit.jupiter.api.Test; import org.noear.solon.ai.mcp.client.McpClientToolProvider; import org.noear.solon.test.SolonTest; import org.noear.solon.test.HttpTester; import org.noear.solon.core.util.Maps; import java.io.IOException; @Slf4j @SolonTest(App.class) public class HelloTest extends HttpTester { @Test public void hello() throws IOException { McpClientToolProvider clientToolProvider = McpClientToolProvider.builder() .apiUrl("http://localhost:8080/sse") .build(); String rst = clientToolProvider.callToolAsText("hello", Maps.of("name", "solon")); log.warn(rst); } }

拆解一下这段测试。@SolonTest(App.class) 是 Solon 的测试注解，它会启动一个测试用的 Solon 容器，加载 App 类里的所有配置和端点。这样你不需要手动先启动 main 方法，测试框架会帮你把服务拉起来。

McpClientToolProvider.builder() 构建一个客户端工具提供者，apiUrl 指向服务端的 SSE 地址。注意这里的地址要跟 @McpServerEndpoint 里配的 sseEndpoint 对应上，端口也要一致。

callToolAsText 是调用工具的方法，第一个参数是工具名，也就是 @ToolMapping 标记的方法名 hello；第二个参数是参数 Map，key 是 @ToolParam 的 name，value 是你要传的值。这里传了 "solon"。

运行这个测试，如果一切正常，控制台会打印出：

hello solon

看到这行输出，就说明整条链路通了：客户端通过 SSE 连上服务端，服务端找到 hello 工具，传入 name 参数，执行方法，返回结果，客户端拿到文本。

我实测的时候第一次跑报了个连接超时的错，排查后发现是测试启动的端口跟我本地已经跑着的服务冲突了。解决办法是在测试配置里指定一个不同的端口，或者先把本地服务停掉。这个坑后面排障章节会详细说。

如果你想验证更复杂的场景，比如传多个参数、返回 JSON 对象，可以把 hello 方法改成接收两个参数，返回一个 Map。callToolAsText 会返回 JSON 字符串，你用 JSON 库解析一下就能验证字段对不对。

还有一点值得提：McpClientToolProvider 不仅能调工具，还能列出服务端注册了哪些工具。你可以在测试里加一行 clientToolProvider.listTools() 看看返回的工具列表，确认 hello 工具确实被注册了。这个在调试阶段很有用。

到这里，一个完整的 Helloworld 就闭环了。从依赖引入、端点配置、工具编写到客户端验证，每一步都有可复制的代码。接下来把常见的报错整理一下，帮你少走弯路。

5. 本篇常见报错排查：401、连接失败与工具找不到

跑第一个 MCP Server 的时候，报错基本集中在几个地方。我把遇到过的和社区里反馈比较多的问题整理成对照表，你对着排查会快很多。

报错一：启动时报 ClassNotFoundException: org.noear.solon.ai.mcp.xxx

这个通常是依赖没引全或者版本不对。先检查 pom.xml 里 solon-ai-mcp 的版本是不是 3.2.0，再确认有没有其他依赖把 noear 的包版本覆盖了。用 mvn dependency:tree 看一下依赖树，找到冲突的包，用 exclusions 排除掉，或者在 dependencyManagement 里锁死版本。

报错二：客户端连接 http://localhost:8080/sse 返回 404

说明端点没注册上。检查三件事：@McpServerEndpoint 注解有没有加在类上；sseEndpoint 的值是不是 /sse；启动类有没有用 Solon.start 并且传了正确的 App.class。如果注解加了但没生效，可能是包扫描路径不对，Solon 默认扫描启动类所在包及其子包，你的服务类要放在这个范围内。

报错三：callToolAsText 返回 null 或者抛异常说工具不存在

工具名写错了。callToolAsText 的第一个参数必须跟 @ToolMapping 方法的名称完全一致，大小写敏感。另外确认方法是不是 public 的，private 方法不会被注册。

报错四：连接超时或者 Connection refused

服务没起来，或者端口不对。先确认 main 方法跑起来了，控制台有没有 Solon 启动成功的日志。如果端口被占用，改 app.yml 里的 server.port，同时记得把测试里的 apiUrl 也改掉。我踩过一次坑是本地已经有一个服务占着 8080，测试启动时静默失败了，日志里只有一行不起眼的警告，找了半天才发现。

报错五：OAuth 相关的认证错误

如果你接的是需要认证的 MCP 服务端，可能会遇到 OAuth 报错。Solon AI MCP 的客户端支持配置认证信息，在 builder 后面加 .header("Authorization", "Bearer xxx") 就行。但 Helloworld 阶段一般用不到，本地服务不需要认证。如果你确实遇到了，检查一下是不是误连了外部服务。

报错六：reading choices 解析失败

这个报错通常出现在客户端解析服务端返回时。MCP 协议对返回格式有要求，如果你的工具方法返回了一个无法序列化的对象，客户端解析就会失败。解决办法是确保返回值是基本类型或者标准的 POJO，别返回 InputStream 这类无法直接序列化的东西。

报错七：local proxy failed

这个多半是网络层面的问题，比如本地代理设置干扰了 localhost 的连接。检查一下系统代理配置，把 localhost 和 127.0.0.1 加到代理排除列表里。这个报错在 Windows 上比较常见。

排查的时候有个通用思路：先看服务端日志，确认端点注册和请求接收；再看客户端日志，确认连接建立和请求发送；最后看返回值，确认数据格式。三段日志对着看，问题基本定位得到。

6. 从 Helloworld 到实际项目：下一步怎么走

Helloworld 跑通之后，你手里已经有一个能工作的 MCP Server 了。接下来可以往几个方向扩展。

第一个方向是加更多工具。在 HelloService 里继续写 @ToolMapping 方法，每个方法是一个独立工具。比如加一个查天气的工具、一个算数学表达式的工具。注意每个工具的 description 要写清楚，这是模型能否正确调用的关键。

第二个方向是接真实数据源。工具方法里可以注入 Solon 的 Bean，连数据库、调 Redis、请求外部 API 都行。Solon 的依赖注入跟 Spring 类似，用 @Inject 或者构造函数注入都可以。这样你的 MCP Server 就不只是玩具，而是能真正干活的组件。

第三个方向是接入大模型做联调。MCP Server 本身只是提供工具，真正调用它的是大模型客户端。你可以用支持 MCP 的客户端连上你的 /sse 端点，然后在对话里让模型调用你的工具。这一步能验证工具描述写得够不够清楚——如果模型总是调错工具或者不调用，说明 description 需要优化。

如果你打算长期做 AI 相关的编码和 Agent 开发，可以考虑用 Coding Plan 这类方案来管理你的开发环境和模型调用额度，省去自己折腾配置的时间。验证模型调用效果的时候，模型对话页面可以直接测试工具是否被正确触发。接入过程中遇到配置问题，API Keys 页面和接入文档里有详细的参数说明。

回到技术本身，Solon AI MCP 这个方案最大的价值在于它降低了 Java 开发者进入 MCP 生态的门槛。你不需要学 Python，不需要升 JDK，用熟悉的注解和 Maven 就能写出符合 MCP 协议的服务。对于国内团队来说，国产框架在文档、社区响应和版本节奏上也有天然优势。

最后一个实用建议：把 Helloworld 的代码提交到 Git，作为你后续项目的模板。每次新建 MCP Server 的时候直接复制，改改工具方法就行。我自己的模板里还加了日志切面和异常处理，工具调用出问题的时候能快速定位。这些都是在实际项目里一点点攒出来的，比任何教程都管用。