Merge pull request #8 from weishuai8888/main

完善服务开发者快速入门指南

Author: kathy-baixue

content/docs/(get-started)/quick-start/server-developers.mdx

@@ -0,0 +1,249 @@
+---
+title: 服务器开发者
+description: 快速开始 - 服务器开发者
+---
+
+开始构建自己的服务器，以便在Claude中用于Desktop和其他客户端。
+
+在本教程中，我们将构建一个简单的MCP天气服务器，并将其连接到主机Claude for Desktop。我们将从基本设置开始，然后进行更复杂的用例。
+
+## 我们将要干什么
+许多LLM（包括Claude）目前无法获取预报和恶劣天气警报。让我们用MCP解决这个问题。
+
+我们将构建一个server，该server提供两个工具：get-alerts and get-forecast。然后，我们将服务器连接到MCP主机（在本例中使用Claude for Desktop）：
+![ImaImageZoomge](/server-developers-01.png)
+![ImaImageZoomge](/server-developers-02.png)
+
+
+服务可以连接任何客户端。为了简单起见，我们在这里选择了Claude作为桌面，但我们也有关于[建立自己的client](https://mcp.thinkinai.xyz/docs/quick-start/client-developers)建立自己的client的指南，以及[这里的其他客户列表](https://mcp.thinkinai.xyz/docs/example-clients)。
+
+
+```
+为什么选择Claude for DeskTop而不是Claude.ai？
+由于服务器是本地运行的，MCP目前只支持桌面主机。远程主机正在积极开发中。
+```
+
+## MCP核心概念
+MCP服务器可以提供三种主要功能：
+    1. **Resources**：客户端可以读取的类文件数据（如API响应或文件内容）
+    2. **Tools**：LLM可以调用的函数（经用户批准）
+    3. **Prompts**：帮助用户完成特定任务的预先编写的模板
+本教程将主要关注工具。
+
+### 基于Java
+这是一个基于Spring AI MCP自动配置和引导启动器的快速入门演示。要了解如何手动创建同步和异步MCP服务器，请参阅[Java SDK服务器](https://modelcontextprotocol.io/sdk/java/mcp-server)文档。
+
+让我们开始构建一个天气服务！[你可以在这里找到我们将要构建的完整代码](https://github.com/spring-projects/spring-ai-examples/tree/main/model-context-protocol/weather/starter-stdio-server)【MCP官方代码，支持查询美国天气情况】。
+[这里的代码也可以](https://github.com/weishuai8888/spring-ai-examples)【fork官方代码后调整了逻辑，支持查询全世界的天气情况】
+
+有关更多信息，请参阅[MCP Server Boot Starter](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot-starter-docs.html)参考文档。有关手动MCP服务器实现，请参阅[MCP Server Java SDK文档](https://modelcontextprotocol.io/sdk/java/mcp-server)。
+
+#### 系统要求
+~
+    ● 已安装Java 17或更高版本
+    ● [Spring Boot 3.3.x](https://docs.spring.io/spring-boot/installing.html) 或更高版本
+
+#### 设置你的环境变量
+使用 [Spring Initizer](https://start.spring.io) 启动项目。
+
+你需要添加以下的依赖项：
+
+import { Tab, Tabs } from 'fumadocs-ui/components/tabs';
+
+<Tabs items={['Maven', 'Gradle']}>
+    <Tab value="Maven">
+        ```xml
+        <dependencies>
+            <dependency>
+                <groupId>org.springframework.ai</groupId>
+                <artifactId>spring-ai-starter-mcp-server</artifactId>
+            </dependency>
+
+            <dependency>
+                <groupId>org.springframework</groupId>
+                <artifactId>spring-web</artifactId>
+            </dependency>
+        </dependencies>
+        ```
+    </Tab>
+    <Tab value='Gradle'>
+        ```xml
+        dependencies {
+            implementation platform("org.springframework.ai:spring-ai-starter-mcp-server")
+            implementation platform("org.springframework:spring-web")
+        }
+        ```
+    </Tab>
+</Tabs>
+
+然后通过设置应用程序属性来配置应用程序
+
+<Tabs items={['application.yml', 'application.properties']}>
+    <Tab value="application.yml">
+        ```yaml
+        logging:
+          pattern:
+            console:
+        spring:
+          main:
+            banner-mode: off
+        ```
+    </Tab>
+    <Tab value="application.properties">
+        ```properties
+        logging.pattern.console=
+        spring.main.banner-mode=off
+        ```
+    </Tab>
+</Tabs>
+
+[服务器配置属性](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot-starter-docs.html#_configuration_properties)记录了所有可用的属性。现在，让我们开始构建您的服务器。
+
+# 构建你的服务器
+## 天气服务
+让我们实现一个WeatherService.java，它使用 REST 客户端从国家气象局 API 查询数据：
+``` java
+@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 ([email protected])")
+			.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 服务器注册这些工具。
+
+## 创建启动应用程序
+``` java
+@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 服务器使用的可操作回调。
+
+## 运行服务器
+最后，让我们构建服务器：
+```bash
+./mvnw clean install
+```
+这将在文件夹mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar中生成一个文件target。
+
+现在让我们从现有的 MCP 主机 Claude for Desktop 测试您的服务器。
+
+# 使用 Claude for Desktop 测试你的服务器
+Claude for Desktop 尚未在 Linux 上提供。
+
+首先，请确保您已安装 Claude for Desktop。 [您可以在此处安装最新版本](https://www.anthropic.com/app-unavailable-in-region)。如果您已经安装了 Claude for Desktop，[请确保它已更新到最新版本](https://www.anthropic.com/app-unavailable-in-region)。
+
+我们需要为您想要使用的 MCP 服务器配置 Claude for Desktop。为此，请在~/Library/Application Support/Claude/claude_desktop_config.json文本编辑器中打开您的 Claude for Desktop App 配置。如果该文件不存在，请务必创建。
+
+例如，如果你安装了VS Code：
+
+<Tabs items={['MacOS/Linux', '视窗']}>
+    <Tab value="MacOS/Linux">
+        ```shell
+        code ~/Library/Application\ Support/Claude/claude_desktop_config.json
+        ```
+    </Tab>
+    <Tab value="视窗">
+        ```bash
+        code $env:AppData\Claude\claude_desktop_config.json
+        ```
+    </Tab>
+</Tabs>
+
+然后您将在密钥中添加服务器mcpServers。只有至少一台服务器配置正确，MCP UI 元素才会显示在 Claude for Desktop 中。
+
+在这种情况下，我们将像这样添加单个天气服务器：
+<Tabs items={['MacOS/Linux', '视窗']}>
+    <Tab value="MacOS/Linux">
+        ```java
+        {
+            "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"
+                    ]
+                }
+            }
+        }
+        ```
+    </Tab>
+    <Tab value="视窗">
+        ```bash
+        {
+            "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"
+                    ]
+                }
+            }
+        }
+        ```
+    </Tab>
+</Tabs>
+确保传递了服务器的绝对路径。
+
+这告诉 Claude for Desktop：
+
+1. 有一个名为“my-weather-server”的 MCP 服务器
+2. 通过运行来启动它java -jar /ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar
+
+保存文件并重新启动Claude for Desktop。
+
+
+
+
+
+
+
+