企业官网建设流程全解析

• 教程
• 文档
• 人工智能

本篇文章以开源仓库 mcp-for-beginners 中的 Basic Calculator MCP Service 文档为主线，完整拆解一个基于 Spring Boot + WebFlux 的 MCP 计算器服务：从 SSE 传输原理、@Tool自动工具注册、9 个计算器工具的源码实现，到 Maven 构建、java -jar/ Docker 部署、MCP Inspector 联调，以及用 LangChain4j 将计算器工具接入大语言模型聊天机器人。读者学完后，将能够独立复刻并扩展一个可运行、可调试、可容器化的 Java MCP Server，并掌握 SSE 客户端接入 AI 模型的完整链路。

一、示例定位与传输协议背景

这是一个面向初学者的入门示例，位于仓库 03-GettingStarted/samples/java/calculator 目录。它通过 Model Context Protocol（MCP）对外提供基础计算器运算能力，技术栈为Spring Boot + WebFlux，并采用SSE（Server-Sent Events）作为服务端事件推送通道。

关于协议版本，原文档有一处必须注意的说明：

[!NOTE] 本示例使用旧版HTTP+SSE传输，面向与 MCP2025-11-25兼容的 SDK。新建远程服务端时，应改用2026-07-28的Streamable HTTP支持。

也就是说，本示例适合作为理解 MCP 传输演进与 SSE 交互模型的入门素材；若从零搭建生产级远程服务，建议直接参考仓库中面向2026-07-28新协议的其他示例（如 01-CoreConcepts/mcp-2026-07-28.md）。

二、服务能力一览

该服务通过 MCP 协议对外暴露以下 API（工具）端点：

能力分为三层：

1. 基础算术运算：加、减、乘、除（除法带除零检查）；
2. 进阶运算：幂运算、平方根（带负数检查）、取模、绝对值；
3. 帮助系统：内置help()函数，一次性解释所有可用操作及示例用法。

三、源码级拆解：@Tool注解与自动工具注册

MCP 服务端的核心价值在于"把普通 Java 方法变成 AI 可调用的工具"。本示例的两块源码清晰地展示了这一机制。

3.1 计算器服务：普通 @Service + @Tool 注解

所有计算逻辑集中在 CalculatorService.java。每个公开方法上标注 Spring AI 的@Tool(description = "...")注解，方法签名即工具参数 Schema，注解描述即工具说明（会被模型用于判断何时调用）。以加法为例：

@Tool(description = "Add two numbers together") public String add(double a, double b) { double result = a + b; return formatResult(a, "+", b, result); }

几个值得注意的实现细节：

• 统一返回格式化字符串：formatResult(double a, String operator, double b, double result)使用String.format("%.2f %s %.2f = %.2f", ...)输出如5.00 + 3.00 = 8.00的可读结果，便于模型直接引用；
• 除零与负数防御：divide/modulus在b == 0时返回"Error: Cannot divide by zero"；squareRoot在number < 0时返回"Error: Cannot calculate square root of a negative number"，工具不会抛出异常而是返回人类可读的错误文本；
• help()聚合说明：返回多行文本列出全部 8 个运算工具及示例（add(5, 3) will return 5 + 3 = 8），方便模型"自我学习"服务能力。

3.2 启动类：MethodToolCallbackProvider 把工具注册进 MCP

在 McpServerApplication.java 中，通过一个@Bean完成工具回调的批量注册：

@Bean public ToolCallbackProvider calculatorTools(CalculatorService calculator) { return MethodToolCallbackProvider.builder().toolObjects(calculator).build(); }

MethodToolCallbackProvider会扫描传入对象上所有带@Tool注解的方法，将其转换为 MCP 协议中的工具定义。结合spring-ai-starter-mcp-server-webflux依赖，Spring AI 自动完成 SSE 端点挂载、协议编解码与工具清单发布，无需手写任何 MCP 协议处理代码——这正是"自动工具注册"的底层原理。

四、项目骨架与依赖配置（pom.xml 详解）

项目基于 pom.xml，关键配置如下：

• 父工程：spring-boot-starter-parent3.4.4；
• Java 版本：21（maven.compiler.release21）；
• Spring AI BOM：spring-ai-bom1.0.0-SNAPSHOT（通过dependencyManagement统一版本）；
• LangChain4j 版本：1.0.0-beta3（属性langchain4j.version）。

核心依赖（原文档完整列出）：

<!-- For MCP Server --> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-mcp-server-webflux</artifactId> </dependency> <!-- For LangChain4j integration --> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-mcp</artifactId> <version>${langchain4j.version}</version> </dependency> <!-- For Microsoft Foundry's OpenAI-compatible endpoint --> <dependency> <groupId>dev.langchain4j</groupId> <artifactId>langchain4j-open-ai-official</artifactId> <version>${langchain4j.version}</version> </dependency>

此外还包括spring-boot-starter-actuator（健康检查与指标）、spring-boot-starter-test+junit-jupiter（测试）。仓库还配置了三个仓库源：Central Portal Snapshots、Spring Milestones 与 Spring Snapshots，用于拉取快照版本依赖。

五、构建、运行与容器化部署

5.1 Maven 构建

使用项目自带 Maven Wrapper 构建（跳过测试）：

./mvnw clean install -DskipTests

5.2 直接运行

构建产物为calculator-server-0.0.1-SNAPSHOT.jar，运行：

java -jar target/calculator-server-0.0.1-SNAPSHOT.jar

5.3 Docker 容器化

项目根目录提供 Dockerfile，采用多阶段构建：

# 构建镜像 docker build -t calculator-mcp-service . # 运行容器 docker run -p 8080:8080 calculator-mcp-service

从 Dockerfile 源码可见其构建策略：

• 构建阶段：maven:3.9.9-eclipse-temurin-24-noble镜像，先COPY pom.xml并执行mvn dependency:go-offline预下载依赖（该层可被 Docker 缓存，pom 不变则无需重复下载），再复制src执行mvn clean package -DskipTests；
• 运行阶段：eclipse-temurin:24-jdk-alpine精简镜像，仅复制产物并重命名为application.jar，EXPOSE 8080后以java -jar /app/application.jar启动。

容器启动后可通过http://localhost:8080访问服务。

六、使用 MCP Inspector 联调计算器工具

MCP Inspector 是官方调试工具，可用来列出工具并手动执行，验证服务端行为。操作步骤如下：

1. 启动 Inspector（新终端窗口）：

   npx @modelcontextprotocol/inspector

2. 打开 Web UI：点击应用打印的 URL（通常为http://localhost:6274）；
3. 配置连接：
   • 传输类型选择SSE；
   • URL 填服务端 SSE 端点：http://localhost:8080/sse；
   • 点击Connect；
4. 执行工具：
   • 点击List Tools查看全部计算器操作；
   • 选中工具并点击Run Tool执行一次调用。

上述界面效果见文章开头的截图（该截图来自示例目录 images/tool.png，展示 Inspector 中已列出的计算器工具）。

七、辅助端点与启动信息

除 MCP 工具外，服务还提供两个 HTTP 辅助端点（见 HealthController.java）：

• GET /health：返回status（UP）、timestamp、service名称以及calculatorService是否可用的状态，可用于容器健康检查；
• GET /info：返回服务版本、MCP 工具端点/v1/tools及全部 9 个工具的描述清单，便于快速核对服务能力。

同时，StartupConfig.java 通过CommandLineRunner在启动时打印欢迎横幅与用法信息，其欢迎语与用法文本可通过配置项calculator.service.welcome、calculator.service.usage覆盖（@Value带默认值）。GlobalExceptionHandler.java 则统一处理IllegalArgumentException（返回 400Invalid_Input）与通用异常（返回 500Internal_Error），保证错误响应结构一致。

八、LangChain4j 客户端：让 LLM 学会"调用计算器"

示例在客户端包 src/test/java/com/microsoft/mcp/sample/client 中提供 LangChain4j 集成演示：AI 模型通过 MCP 工具调用计算器完成问答。

8.1 前置条件

以仓库当前源码所采用的 Microsoft Foundry（Azure OpenAI v1 兼容端点）方案为例：

1. 创建 Microsoft Foundry 资源并部署一个可用模型（如gpt-5.1）；
2. 设置环境变量：

   export AZURE_OPENAI_ENDPOINT="https://<resource-name>.openai.azure.com" export AZURE_OPENAI_API_KEY="<api-key>" export AZURE_OPENAI_DEPLOYMENT="gpt-5.1"

3. 选择部署前查阅 Microsoft Foundry 模型退役时间表，确认模型仍可用；
4. 确保计算器服务已在localhost:8080运行（SSE 模式）。

说明：仓库中丹麦语翻译版文档记载过一套基于 GitHub Token（GITHUB_TOKEN，搭配langchain4j-github依赖与 phi-4 等模型的旧配置方案）；但当前仓库的英文原版 README 与 pom.xml、LangChain4jClient.java 源码均以 Microsoft Foundry 方案为准，实战请以源码为准。

8.2 模型与传输配置（源码对照）

LangChain4jClient.java 的main方法完整演示了"模型 + MCP 传输 + 工具提供器 + AI 服务"四段式装配：

// 1) 聊天模型：接入 Microsoft Foundry 的 OpenAI v1 兼容端点 String endpoint = System.getenv("AZURE_OPENAI_ENDPOINT"); ChatLanguageModel model = OpenAiOfficialChatModel.builder() .baseUrl(endpoint.replaceAll("/+$", "") + "/openai/v1/") .apiKey(System.getenv("AZURE_OPENAI_API_KEY")) .isAzure(true) .modelName(System.getenv().getOrDefault("AZURE_OPENAI_DEPLOYMENT", "gpt-5.1")) .timeout(Duration.ofSeconds(60)) .build(); // 2) MCP 传输：通过 SSE 连接计算器服务 McpTransport transport = new HttpMcpTransport.Builder() .sseUrl("http://localhost:8080/sse") .timeout(Duration.ofSeconds(60)) .logRequests(true) .logResponses(true) .build(); // 3) MCP 客户端与工具提供器 McpClient mcpClient = new DefaultMcpClient.Builder().transport(transport).build(); ToolProvider toolProvider = McpToolProvider.builder() .mcpClients(List.of(mcpClient)) .build(); // 4) AI 服务装配（接口 Bot 见 Bot.java） Bot bot = AiServices.builder(Bot.class) .chatLanguageModel(model) .toolProvider(toolProvider) .build();

要点解读：

• AZURE_OPENAI_DEPLOYMENT必须与部署时命名的 deployment 完全一致，它可以与底层模型名不同；modelName取不到环境变量时回退为gpt-5.1；
• SSE 传输复用：HttpMcpTransport.Builder.sseUrl(...)指向服务端的/sse端点，并开启请求/响应日志，方便观察工具调用过程；
• 工具声明式注入：McpToolProvider.builder().mcpClients(...)将远端 MCP 工具注册进 LangChain4j，模型即可自主选择调用；
• Bot接口（Bot.java）仅声明String chat(String prompt)，AiServices.builder(Bot.class)会在运行时为其生成带工具能力的实现。

8.3 示例查询

客户端依次发送三类查询，演示模型如何调用工具：

1. 计算两数之和："Calculate the sum of 24.5 and 17.3 using the calculator service"；
2. 求平方根："What's the square root of 144?"；
3. 获取帮助："Show me the help for the calculator service"。

运行后检查控制台输出（尤其是logRequests/logResponses打印的 MCP 报文），可看到模型先"决定"调用哪个工具、构造参数、获得计算结果后再组织自然语言回复的完整链路。最后mcpClient.close()释放连接。

九、常见问题排查

9.1 模型连接类问题（Foundry 方案）

1. 鉴权失败：确认AZURE_OPENAI_API_KEY属于AZURE_OPENAI_ENDPOINT指向的资源；
2. Deployment 不存在：确认AZURE_OPENAI_DEPLOYMENT与 Foundry 中的部署名完全一致；
3. 限流：检查部署配额，按服务返回的时间间隔重试。

9.2 Token 类问题（GitHub 模型历史方案，翻译版文档记载）

1. 403 Forbidden：检查 token 是否具备repo、read:org、gist、user:email等所需 scope；
2. "No API key found"：确认GITHUB_TOKEN环境变量已正确设置（Windows 用set GITHUB_TOKEN=...，macOS/Linux 用export GITHUB_TOKEN=...，永久配置需写入系统环境变量）；
3. 429 限流：GitHub API 有调用频率限制，稍等数分钟重试；
4. Token 过期：GitHub token 会过期，鉴权报错时重新生成并更新环境变量。

十、总结

从本示例可以提炼出 Java 生态构建 MCP 服务的四条核心经验：

1. 零协议代码：spring-ai-starter-mcp-server-webflux+@Tool+MethodToolCallbackProvider即可完成 SSE 服务端与工具注册，专注业务方法本身；
2. 工具即文档：@Tool的 description 与参数签名就是模型理解、调用工具的依据，应写得清晰具体；
3. 调试闭环：MCP Inspector（List Tools / Run Tool）与 LangChain4j 客户端的日志开关（logRequests/logResponses）是验证工具可用性、观察调用链路的两大利器；
4. 传输演进：本示例基于2025-11-25的 HTTP+SSE 旧协议，新建远程服务时应迁移到2026-07-28Streamable HTTP，仓库 01-CoreConcepts/mcp-2026-07-28.md 提供了协议要点参考。

想继续深入，可在仓库中对照 03-GettingStarted/samples/java 下的其他 Java 示例（如 HTTP Streaming、认证相关示例），或前往 03-GettingStarted/11-simple-auth 学习为 MCP 服务添加鉴权的实践。

• 教程
• 文档
• 人工智能