Java 天气服务器开发

更多信息，请参阅 MCP Server Boot Starter 参考文档。对于手动 MCP 服务器实现，请参考 MCP Server Java SDK 文档。

➡️ 系统要求

• 已安装 Java 17 或更高版本
• Spring Boot 3.3.x 或更高版本

➡️ 设置你的环境

使用 Spring Initializr 来引导项目。

你需要添加以下依赖项：

Maven

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

      <dependency>
          <groupId>org.springframework</groupId>
          <artifactId>spring-web</artifactId>
      </dependency>
</dependencies>

Gradle

dependencies {
  implementation platform("org.springframework.ai:spring-ai-mcp-server-spring-boot-starter")
  implementation platform("org.springframework:spring-web")   
}

开始构建

让我们实现一个 WeatheService.java ，它使用 REST 客户端来查询国家气象服务 API 的数据：

@Service
public class WeatherService {

	private final RestClient restClient;

	public WeatherService() {
		this.restClient = RestClient.builder()
			.baseUrl("https://api.weather.gov")
			.defaultHeader("Accept", "application/geo+json")
			.defaultHeader("User-Agent", "WeatherApiClient/1.0 (your@email.com)")
			.build();
	}

  @Tool(description = "Get weather forecast for a specific latitude/longitude")
  public String getWeatherForecastByLocation(
      double latitude,   // Latitude coordinate
      double longitude   // Longitude coordinate
  ) {
      // Returns detailed forecast including:
      // - Temperature and unit
      // - Wind speed and direction
      // - Detailed forecast description
  }
	
  @Tool(description = "Get weather alerts for a US state")
  public String getAlerts(
      @ToolParam(description = "Two-letter US state code (e.g. CA, NY") String state)
  ) {
      // Returns active alerts including:
      // - Event type
      // - Affected area
      // - Severity
      // - Description
      // - Safety instructions
  }

  // ......
}

@Service 注解将自动注册服务到您的应用程序上下文中。Spring AI @Tool 注解使创建和维护 MCP 工具变得容易。自动配置将自动将这些工具注册到 MCP 服务器。

创建你的启动应用程序

@SpringBootApplication
public class McpServerApplication {

	public static void main(String[] args) {
		SpringApplication.run(McpServerApplication.class, args);
	}

	@Bean
	public ToolCallbackProvider weatherTools(WeatherService weatherService) {
		return  MethodToolCallbackProvider.builder().toolObjects(weatherService).build();
	}
}

使用 MethodToolCallbackProvider 工具将 @Tools 转换为 MCP 服务器使用的可操作回调。

运行服务器

./mvnw clean install

这将在目标文件夹内生成一个 mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar 文件。现在让我们从现有的MCP主机Claude for Desktop测试您的服务器。

测试你的服务器

温馨提示

Claude桌面端目前尚未在 Linux 上提供。Linux 用户可以继续参阅构建客户端教程，以构建一个连接到我们刚刚构建的服务器的 MCP 客户端。

首先，确保你已经安装了 Claude for Desktop。你可以在这里安装最新版本。如果你已经有 Claude for Desktop，确保它更新到最新版本。我们需要为你想要使用的任何 MCP 服务器配置 Claude for Desktop。为此，打开你的 Claude for Desktop 应用程序配置文件，路径为 ~/Library/Application Support/Claude/claude_desktop_config.json，使用文本编辑器打开。如果文件不存在，请确保创建该文件。举个例子，如果你安装了 VS Code：

Linux/MacOS

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows

code $env:AppData\Claude\claude_desktop_config.json

然后你将在 mcpServers 键中添加你的服务器。只有在至少一个服务器正确配置的情况下，MCP UI 元素才会在 Claude 桌面版中显示。 在这种情况下，我们将以如下方式添加我们的单个天气服务器：

Linux/MacOS

{
  "mcpServers": {
    "spring-ai-mcp-weather": {
      "command": "java",
      "args": [
        "-Dspring.ai.mcp.server.stdio=true",
        "-jar",
        "/ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar"
      ]
    }
  }
}

Windows

{
  "mcpServers": {
    "spring-ai-mcp-weather": {
      "command": "java",
      "args": [
        "-Dspring.ai.mcp.server.transport=STDIO",
        "-jar",
        "C:\\ABSOLUTE\\PATH\\TO\\PARENT\\FOLDER\\weather\\mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar"
      ]
    }
  }
}

这告诉桌面版 Claude：

1. 有一个名为“天气”的 MCP 服务器。
2. 通过运行 java -jar /ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar 启动它。

保存文件，并重启桌面版 Claude。

用 Java 客户端测试你的服务器

手动创建一个 MCP 客户端 使用 McpClient 连接到服务器：

var stdioParams = ServerParameters.builder("java")
  .args("-jar", "/ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar")
  .build();

var stdioTransport = new StdioClientTransport(stdioParams);

var mcpClient = McpClient.sync(stdioTransport).build();

mcpClient.initialize();

ListToolsResult toolsList = mcpClient.listTools();

CallToolResult weather = mcpClient.callTool(
  new CallToolRequest("getWeatherForecastByLocation",
      Map.of("latitude", "47.6062", "longitude", "-122.3321")));

CallToolResult alert = mcpClient.callTool(
  new CallToolRequest("getAlerts", Map.of("state", "NY")));

mcpClient.closeGracefully();

使用MCP客户端启动器

使用spring-ai-mcp-client-spring-boot-starter依赖创建一个新的启动器应用程序：

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

并将 spring.ai.mcp.client.stdio.servers-configuration 属性设置为指向您的 claude_desktop_config.json。您可以重用现有的 Anthropic Destop 配置：

spring.ai.mcp.client.stdio.servers-configuration=file:PATH/TO/claude_desktop_config.json

当您启动客户端应用程序时，自动配置会根据 claude_desktop_config.json 自动创建 MCP 客户端。有关更多信息，请参阅 MCP 客户端启动器参考文档。

更多 Java MCP 服务器示例

starter-webflux-server 演示了如何使用 SSE 传输创建 MCP 服务器。它展示了如何使用 Spring Boot 的自动配置功能定义和注册 MCP 工具、资源和提示。

使用命令进行测试

让我们确保 Claude for Desktop 正在获取我们在天气服务器中暴露的两个工具。您可以通过寻找锤子图标来做到这一点：

点击锤子图标后，您应该可以看到两个工具列出。

如果您的服务器无法被Claude for Desktop识别，请前往故障排除部分获取调试提示。

如果锤子图标已经出现，您现在可以通过在Claude for Desktop中运行以下命令来测试您的服务器：

• Sacramento的天气如何？
• Texas的天气警报有哪些？

提示

由于这是美国国家气象局，因此查询只适用于美国地区。

发生了什么

当你提问时： 客户端将你的问题发送给Claude

1. Claude分析可用的工具并决定使用哪个工具
2. 客户端通过MCP服务器执行所选工具
3. 结果被发送回Claude
4. Claude形成自然语言回应
5. 回应显示给你！

故障排除

Claude 桌面端故障排除

• 从 Claude for Desktop 获取日志

Claude.app 相关的 MCP 日志文件保存在 ~/Library/Logs/Claude 目录下：

• mcp.log - 包含关于 MCP 连接和连接失败的一般日志信息
• mcp-server-服务器名称.log - 包含指定服务器的错误（stderr）日志

你可以运行以下命令来查看最近的日志并实时跟踪新日志：

# 检查 Claude 的错误日志
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

• 服务器未在 Claude 中显示

1. 检查你的 claude_desktop_config.json 文件语法
2. 确保项目路径是绝对路径而不是相对路径
3. 完全重启 Claude for Desktop

• 工具调用静默失败

如果 Claude 尝试使用工具但失败了：

1. 检查 Claude 的错误日志
2. 验证你的服务器构建和运行时没有错误
3. 尝试重启 Claude for Desktop

• 以上方法都不起作用，我该怎么办？

请参考我们的调试指南以获取更好的调试工具和更详细的指导。

Weather API 故障排除

• 错误：无法获取网格点数据

这通常意味着以下情况之一：

1. 坐标位置在美国境外
2. NWS API 服务出现问题
3. 你遇到了请求频率限制

• 解决方案：

• 验证你使用的是美国境内的坐标

• 在请求之间添加短暂延迟

• 检查 NWS API 状态页面

• 错误：[州名] 没有活动警报

这不是真正的错误 - 它只是表示该州目前没有天气警报。可以尝试查看其他州，或在恶劣天气期间再次检查。

提示

有关更高级的故障排除，请查看我们关于调试MCP的指南。

Next Steps

💻

客户端开发

学习如何开发自己的 MCP 客户端应用

→

📚

服务器示例

探索更多 MCP 服务器示例和用例

→

🔧

调试指南

学习如何调试和排除 MCP 服务器问题

→

🤖

用 LLM 构建 MCP

了解如何将大语言模型与 MCP 集成

→