快速开始

面向服务端开发者

在本教程中，我们将构建一个简单的MCP天气服务端，并将其连接到主机Claude for Desktop。我们将从基本设置开始，然后逐步深入到更复杂的用例。

我们将构建什么

许多LLM目前没有获取天气预报和恶劣天气警报的能力。让我们使用MCP来解决这个问题！

我们将构建一个暴露两个工具的服务端：get-alerts和get-forecast。然后我们将服务端连接到MCP主机（在本例中为Claude for Desktop）：

服务端可以连接到任何客户端。我们在这里选择Claude for Desktop是为了简单起见，但我们也有关于构建自己的客户端的指南，以及其他客户端的列表。

为什么选择Claude for Desktop而不是Claude.ai？

因为服务端是本地运行的，MCP目前只支持桌面主机。远程主机正在积极开发中。

MCP核心概念

MCP服务端可以提供三种主要类型的功能：

资源：客户端可以读取的文件类数据（如API响应或文件内容）
工具：LLM可以调用的函数（需用户批准）
提示：帮助用户完成特定任务的预写模板

本教程将主要关注工具。

Python

让我们开始构建我们的天气服务端！你可以在这里找到我们将构建的完整代码。

预备知识

本快速入门假设你熟悉：

Python
像Claude这样的LLM

系统要求

已安装Python 3.10或更高版本。
你必须使用Python MCP SDK 1.2.0或更高版本。

设置你的环境

首先，让我们安装uv并设置我们的Python项目和环境：

MacOS/Linux


    curl -LsSf https://astral.sh/uv/install.sh | sh

确保之后重新启动终端，以确保uv命令被识别。

现在，让我们创建并设置我们的项目：

MacOS/Linux


# 为我们的项目创建一个新目录
uv init weather
cd weather
 
# 创建虚拟环境并激活它
uv venv
source .venv/bin/activate
 
# 安装依赖项
uv add "mcp[cli]" httpx
 
# 创建我们的服务端文件
touch weather.py

现在让我们深入构建你的服务端。

构建你的服务端

导入包并设置实例

将这些添加到weather.py的顶部：


 
    from typing import Any
    import httpx
    from mcp.server.fastmcp import FastMCP
    
    # 初始化FastMCP服务端
    mcp = FastMCP("weather")
    
    # 常量
    NWS_API_BASE = "https://api.weather.gov"
    USER_AGENT = "weather-app/1.0"

FastMCP类使用Python类型提示和文档字符串自动生成工具定义，使得创建和维护MCP工具变得容易。

辅助函数

接下来，让我们添加用于查询和格式化来自国家气象局API的数据的辅助函数：


 
    async def make_nws_request(url: str) -> dict[str, Any] | None:
        """向NWS API发出请求并进行适当的错误处理。"""
        headers = {
            "User-Agent": USER_AGENT,
            "Accept": "application/geo+json"
        }
        async with httpx.AsyncClient() as client:
            try:
                response = await client.get(url, headers=headers, timeout=30.0)
                response.raise_for_status()
                return response.json()
            except Exception:
                return None
    
    def format_alert(feature: dict) -> str:
    """Format an alert feature into a readable string."""
    props = feature["properties"]
    return f"""
Event: {props.get('event', 'Unknown')}
Area: {props.get('areaDesc', 'Unknown')}
Severity: {props.get('severity', 'Unknown')}
Description: {props.get('description', 'No description available')}
Instructions: {props.get('instruction', 'No specific instructions provided')}
"""

实现工具执行

工具执行处理程序负责实际执行每个工具的逻辑。让我们添加它：


 
    @mcp.tool()
    async def get_alerts(state: str) -> str:
        """获取美国州的天气警报。
    
        参数:
            state: 两个字母的美国州代码（例如CA, NY）
        """
        url = f"{NWS_API_BASE}/alerts/active/area/{state}"
        data = await make_nws_request(url)
    
        if not data or "features" not in data:
            return "无法获取警报或未找到警报。"
    
        if not data["features"]:
            return "该州没有活跃的警报。"
    
        alerts = [format_alert(feature) for feature in data["features"]]
        return "\n---\n".join(alerts)
    
    @mcp.tool()
    async def get_forecast(latitude: float, longitude: float) -> str:
        """获取某个位置的天气预报。
    
        参数:
            latitude: 位置的纬度
            longitude: 位置的经度
        """
        # 首先获取预测网格端点
        points_url = f"{NWS_API_BASE}/points/{latitude},{longitude}"
        points_data = await make_nws_request(points_url)
    
        if not points_data:
            return "无法获取该位置的预测数据。"
    
        # 从points响应中获取预测URL
        forecast_url = points_data["properties"]["forecast"]
        forecast_data = await make_nws_request(forecast_url)
    
        if not forecast_data:
            return "无法获取详细预测。"
    
        # 将时间段格式化为可读的预测
        periods = forecast_data["properties"]["periods"]
    forecasts = []
    for period in periods[:5]:  # Only show next 5 periods
        forecast = f"""
{period['name']}:
Temperature: {period['temperature']}°{period['temperatureUnit']}
Wind: {period['windSpeed']} {period['windDirection']}
Forecast: {period['detailedForecast']}
"""
            forecasts.append(forecast)
    
        return "\n---\n".join(forecasts)

运行服务端

最后，让我们初始化并运行服务端：


 
    if __name__ == "__main__":
        # 初始化并运行服务端
        mcp.run(transport='stdio')

你的服务端完成了！运行uv run weather.py以确认一切正常。

现在让我们从现有的MCP主机Claude for Desktop测试你的服务端。

使用Claude for Desktop测试你的服务端

Claude for Desktop尚未在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 ：

MacOS/Linux


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

然后你将在mcpServers键中添加你的服务端。只有在至少正确配置了一个服务端的情况下，MCP UI元素才会在Claude for Desktop中显示。

在这种情况下，我们将添加我们的单个天气服务端，如下所示：

MacOS/Linux


{
    "mcpServers": {
        "weather": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather",
                "run",
                "weather.py"
            ]
        }
    }
}

你可能需要在command字段中输入uv可执行文件的完整路径。你可以通过在MacOS/Linux上运行which uv或在Windows上运行where uv来获取此路径。

确保你传入服务端的绝对路径。

这告诉Claude for Desktop：

有一个名为“weather”的MCP服务端
通过运行uv --directory /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather run weather.py来启动它

保存文件，并重新启动Claude for Desktop。

Node

让我们开始构建我们的天气服务端！你可以在这里找到我们将构建的完整代码。

预备知识

本快速入门假设你熟悉：

TypeScript
像Claude这样的LLM

系统要求

对于TypeScript，请确保你已安装最新版本的Node。

设置你的环境

首先，如果你还没有安装Node.js和npm，请先安装它们。你可以从nodejs.org 下载它们。验证你的Node.js安装：


node --version
npm --version

对于本教程，你需要Node.js 16或更高版本。

现在，让我们创建并设置我们的项目：

MacOS/Linux


# 为我们的项目创建一个新目录
md weather
cd weather
 
# 初始化一个新的npm项目
npm init -y
 
# 安装依赖项
npm install @modelcontextprotocol/sdk zod
npm install -D @types/node typescript
 
# 创建我们的文件
md src
new-item src\index.ts

更新你的package.json以添加type: "module"和一个构建脚本：

package.json


{
  "type": "module",
  "bin": {
    "weather": "./build/index.js"
  },
  "scripts": {
    "build": "tsc && chmod 755 build/index.js"
  },
  "files": [
    "build"
  ]
}

在你的项目根目录下创建一个tsconfig.json：

tsconfig.json


{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

现在让我们深入构建你的服务端。

构建你的服务端

导入包并设置实例

将这些添加到src/index.ts的顶部：


import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
 
const NWS_API_BASE = "https://api.weather.gov";
const USER_AGENT = "weather-app/1.0";
 
// 创建服务端实例
const server = new McpServer({
  name: "weather",
  version: "1.0.0",
});

辅助函数

接下来，让我们添加用于查询和格式化来自国家气象局API的数据的辅助函数：


// 用于向NWS API发出请求的辅助函数
async function makeNWSRequest<T>(url: string): Promise<T | null> {
  const headers = {
    "User-Agent": USER_AGENT,
    Accept: "application/geo+json",
  };
 
  try {
    const response = await fetch(url, { headers });
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return (await response.json()) as T;
  } catch (error) {
    console.error("Error making NWS request:", error);
    return null;
  }
}
 
interface AlertFeature {
  properties: {
    event?: string;
    areaDesc?: string;
    severity?: string;
    status?: string;
    headline?: string;
  };
}
 
// 格式化警报数据
function formatAlert(feature: AlertFeature): string {
  const props = feature.properties;
  return [
    `Event: ${props.event || "Unknown"}`,
    `Area: ${props.areaDesc || "Unknown"}`,
    `Severity: ${props.severity || "Unknown"}`,
    `Status: ${props.status || "Unknown"}`,
    `Headline: ${props.headline || "No headline"}`,
    "---",
  ].join("\n");
}
 
interface ForecastPeriod {
  name?: string;
  temperature?: number;
  temperatureUnit?: string;
  windSpeed?: string;
  windDirection?: string;
  shortForecast?: string;
}
 
interface AlertsResponse {
  features: AlertFeature[];
}
 
interface PointsResponse {
  properties: {
    forecast?: string;
  };
}
 
interface ForecastResponse {
  properties: {
    periods: ForecastPeriod[];
  };
}

实现工具执行

工具执行处理程序负责实际执行每个工具的逻辑。让我们添加它：


// 注册天气工具
server.tool(
  "get-alerts",
  "Get weather alerts for a state",
  {
    state: z.string().length(2).describe("两个字母的州代码（例如CA, NY）"),
  },
  async ({ state }) => {
    const stateCode = state.toUpperCase();
    const alertsUrl = `${NWS_API_BASE}/alerts?area=${stateCode}`;
    const alertsData = await makeNWSRequest<AlertsResponse>(alertsUrl);
 
    if (!alertsData) {
      return {
        content: [
          {
            type: "text",
            text: "无法获取警报数据",
          },
        ],
      };
    }
 
    const features = alertsData.features || [];
    if (features.length === 0) {
      return {
        content: [
          {
            type: "text",
            text: `${stateCode}没有活跃的警报`,
          },
        ],
      };
    }
 
    const formattedAlerts = features.map(formatAlert);
    const alertsText = `${stateCode}的活跃警报:\n\n${formattedAlerts.join("\n")}`;
 
    return {
      content: [
        {
          type: "text",
          text: alertsText,
        },
      ],
    };
  },
);
 
server.tool(
  "get-forecast",
  "Get weather forecast for a location",
  {
    latitude: z.number().min(-90).max(90).describe("位置的纬度"),
    longitude: z.number().min(-180).max(180).describe("位置的经度"),
  },
  async ({ latitude, longitude }) => {
    // 获取网格点数据
    const pointsUrl = `${NWS_API_BASE}/points/${latitude.toFixed(4)},${longitude.toFixed(4)}`;
    const pointsData = await makeNWSRequest<PointsResponse>(pointsUrl);
 
    if (!pointsData) {
      return {
        content: [
          {
            type: "text",
            text: `无法获取坐标${latitude}, ${longitude}的网格点数据。该位置可能不受NWS API支持（仅支持美国位置）。`,
          },
        ],
      };
    }
 
    const forecastUrl = pointsData.properties?.forecast;
    if (!forecastUrl) {
      return {
        content: [
          {
            type: "text",
            text: "无法从网格点数据获取预测URL",
          },
        ],
      };
    }
 
    // 获取预测数据
    const forecastData = await makeNWSRequest<ForecastResponse>(forecastUrl);
    if (!forecastData) {
      return {
        content: [
          {
            type: "text",
            text: "无法获取预测数据",
          },
        ],
      };
    }
 
    const periods = forecastData.properties?.periods || [];
    if (periods.length === 0) {
      return {
        content: [
          {
            type: "text",
            text: "没有可用的预测时间段",
          },
        ],
      };
    }
 
    // 格式化预测时间段
    const formattedForecast = periods.map((period: ForecastPeriod) =>
      [
        `${period.name || "Unknown"}:`,
        `Temperature: ${period.temperature || "Unknown"}°${period.temperatureUnit || "F"}`,
        `Wind: ${period.windSpeed || "Unknown"} ${period.windDirection || ""}`,
        `${period.shortForecast || "No forecast available"}`,
        "---",
      ].join("\n"),
    );
 
    const forecastText = `${latitude}, ${longitude}的预测:\n\n${formattedForecast.join("\n")}`;
 
    return {
      content: [
        {
          type: "text",
          text: forecastText,
        },
      ],
    };
  },
);

运行服务端

最后，实现主函数以运行服务端：


async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Weather MCP Server running on stdio");
}
 
main().catch((error) => {
  console.error("main()中的致命错误:", error);
  process.exit(1);
});

确保运行npm run build以构建你的服务端！这是让你的服务端连接的重要步骤。

现在让我们从现有的MCP主机Claude for Desktop测试你的服务端。

使用Claude for Desktop测试你的服务端

Claude for Desktop尚未在Linux上提供。Linux用户可以继续构建客户端教程，以构建一个连接到我们刚刚构建的服务端的MCP客户端。

首先，确保你已经安装了Claude for Desktop。你可以在这里安装最新版本。如果你已经安装了Claude for Desktop，请确保它已更新到最新版本。

例如，如果你安装了VS Code ：

MacOS/Linux


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

然后你将在mcpServers键中添加你的服务端。只有在至少正确配置了一个服务端的情况下，MCP UI元素才会在Claude for Desktop中显示。

在这种情况下，我们将添加我们的单个天气服务端，如下所示：

MacOS/Linux


{
    "mcpServers": {
        "weather": {
            "command": "node",
            "args": [
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/index.js"
            ]
        }
    }
}

这告诉Claude for Desktop：

有一个名为“weather”的MCP服务端
通过运行node /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/index.js来启动它

保存文件，并重新启动Claude for Desktop。

Java

这是一个基于Spring AI MCP自动配置和Boot Starters的快速入门演示。要了解如何手动创建同步和异步MCP服务端，请参阅Java SDK Server文档。

让我们开始构建我们的天气服务端！你可以在这里找到我们将构建的完整代码。

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

系统要求

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

设置你的环境

使用Spring Initizer 来引导项目。

你需要添加以下依赖项：

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>

然后通过设置应用程序属性来配置你的应用程序：

application.properties

application.yml


spring.main.bannerMode=off
logging.pattern.console=

服务端配置属性文档中列出了所有可用的属性。

现在让我们深入构建你的服务端。

构建你的服务端

天气服务

让我们实现一个WeatherService.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 = "获取特定纬度/经度的天气预报")
    public String getWeatherForecastByLocation(
        double latitude,   // 纬度坐标
        double longitude   // 经度坐标
    ) {
        // 返回详细的天气预报，包括：
        // - 温度及单位
        // - 风速和方向
        // - 详细的预报描述
    }
    
    @Tool(description = "获取美国州的天气警报")
    public String getAlerts(
        @ToolParam(description = "两个字母的美国州代码（例如CA, NY") String state)
    ) {
        // 返回活跃的警报，包括：
        // - 事件类型
        // - 受影响区域
        // - 严重性
        // - 描述
        // - 安全指示
    }
 
    // ......
}

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

自动配置将自动将这些工具注册到MCP服务端。

创建你的Boot应用程序


@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

这将在target文件夹中生成一个mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar文件。

现在让我们从现有的MCP主机Claude for Desktop测试你的服务端。

使用Claude for Desktop测试你的服务端

Claude for Desktop尚未在Linux上提供。

首先，确保你已经安装了Claude for Desktop。你可以在这里安装最新版本。如果你已经安装了Claude for Desktop，请确保它已更新到最新版本。

例如，如果你安装了VS Code ：

MacOS/Linux


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

然后你将在mcpServers键中添加你的服务端。只有在至少正确配置了一个服务端的情况下，MCP UI元素才会在Claude for Desktop中显示。

在这种情况下，我们将添加我们的单个天气服务端，如下所示：

MacOS/Linux


{
  "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"
      ]
    }
  }
}

确保你传入服务端的绝对路径。

这告诉Claude for Desktop：

有一个名为“my-weather-server”的MCP服务端
通过运行java -jar /ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar来启动它

保存文件，并重新启动Claude for Desktop。

使用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客户端Boot Starter

使用spring-ai-mcp-client-spring-boot-starter依赖项创建一个新的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 Desktop配置：


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

当你启动客户端应用程序时，自动配置将从claude_desktop_config.json自动创建MCP客户端。

更多信息，请参阅MCP客户端Boot Starters 参考文档。

Kotlin

让我们开始构建我们的天气服务端！你可以在这里找到我们将构建的完整代码。

预备知识

本快速入门假设你熟悉以下内容：

Kotlin
像Claude这样的LLM

系统要求

已安装Java 17或更高版本。

设置你的环境

首先，如果你还没有安装java和gradle，请先安装它们。你可以从Oracle JDK官方网站下载java。验证你的java安装：


java --version

现在，让我们创建并设置你的项目：

MacOS/Linux


# 为我们的项目创建一个新目录
mkdir weather
cd weather
 
# 初始化一个新的Kotlin项目
gradle init

运行gradle init后，你将看到创建项目的选项。选择Application作为项目类型，Kotlin作为编程语言，Java 17作为Java版本。

或者，你可以使用IntelliJ IDEA项目向导创建一个Kotlin应用程序。

创建项目后，添加以下依赖项：

build.gradle.kts


val mcpVersion = "0.3.0"
val slf4jVersion = "2.0.9"
val ktorVersion = "3.1.1"
 
dependencies {
    implementation("io.modelcontextprotocol:kotlin-sdk:$mcpVersion")
    implementation("org.slf4j:slf4j-nop:$slf4jVersion")
    implementation("io.ktor:ktor-client-content-negotiation:$ktorVersion")
    implementation("io.ktor:ktor-serialization-kotlinx-json:$ktorVersion")
}

同时，将以下插件添加到你的构建脚本中：

build.gradle.kts


plugins {
    kotlin("plugin.serialization") version "your_version_of_kotlin"
    id("com.github.johnrengelman.shadow") version "8.1.1"
}

现在让我们深入构建你的服务端。

构建你的服务端

设置实例

添加一个服务端初始化函数：


// 运行MCP服务端的主函数
fun `run mcp server`() {
    // 使用基本实现创建MCP服务端实例
    val server = Server(
        Implementation(
            name = "weather", // 工具名称为“weather”
            version = "1.0.0" // 实现的版本
        ),
        ServerOptions(
            capabilities = ServerCapabilities(tools = ServerCapabilities.Tools(listChanged = true))
        )
    )
 
    // 使用标准IO创建服务端通信的传输
    val transport = StdioServerTransport(
        System.`in`.asInput(),
        System.out.asSink().buffered()
    )
 
    runBlocking {
        server.connect(transport)
        val done = Job()
        server.onCloseCallback = {
            done.complete()
        }
        done.join()
    }
}

天气API辅助函数

接下来，让我们添加用于查询和转换来自国家气象局API的响应的函数和数据类：


// 扩展函数，用于获取给定纬度和经度的预测信息
suspend fun HttpClient.getForecast(latitude: Double, longitude: Double): List<String> {
    val points = this.get("/points/$latitude,$longitude").body<Points>()
    val forecast = this.get(points.properties.forecast).body<Forecast>()
    return forecast.properties.periods.map { period ->
        """
            ${period.name}:
            温度: ${period.temperature} ${period.temperatureUnit}
            风: ${period.windSpeed} ${period.windDirection}
            预测: ${period.detailedForecast}
        """.trimIndent()
    }
}
 
// 扩展函数，用于获取给定州的天气警报
suspend fun HttpClient.getAlerts(state: String): List<String> {
    val alerts = this.get("/alerts/active/area/$state").body<Alert>()
    return alerts.features.map { feature ->
        """
            事件: ${feature.properties.event}
            区域: ${feature.properties.areaDesc}
            严重性: ${feature.properties.severity}
            描述: ${feature.properties.description}
            指示: ${feature.properties.instruction}
        """.trimIndent()
    }
}
 
@Serializable
data class Points(
    val properties: Properties
) {
    @Serializable
    data class Properties(val forecast: String)
}
 
@Serializable
data class Forecast(
    val properties: Properties
) {
    @Serializable
    data class Properties(val periods: List<Period>)
 
    @Serializable
    data class Period(
        val number: Int, val name: String, val startTime: String, val endTime: String,
        val isDaytime: Boolean, val temperature: Int, val temperatureUnit: String,
        val temperatureTrend: String, val probabilityOfPrecipitation: JsonObject,
        val windSpeed: String, val windDirection: String,
        val shortForecast: String, val detailedForecast: String,
    )
}
 
@Serializable
data class Alert(
    val features: List<Feature>
) {
    @Serializable
    data class Feature(
        val properties: Properties
    )
 
    @Serializable
    data class Properties(
        val event: String, val areaDesc: String, val severity: String,
        val description: String, val instruction: String?,
    )
}

实现工具执行

工具执行处理程序负责实际执行每个工具的逻辑。让我们添加它：


// 创建一个带有默认请求配置和JSON内容协商的HTTP客户端
val httpClient = HttpClient {
    defaultRequest {
    url("https://api.weather.gov")
    headers {
        append("Accept", "application/geo+json")
        append("User-Agent", "WeatherApiClient/1.0")
    }
    contentType(ContentType.Application.Json)
    }
    // 安装内容协商插件以进行JSON序列化/反序列化
    install(ContentNegotiation) { json(Json { ignoreUnknownKeys = true }) }
}
 
// 注册一个工具以按州获取天气警报
server.addTool(
    name = "get_alerts",
    description = """
        获取美国州的天气警报。输入是两个字母的美国州代码（例如CA, NY）
    """.trimIndent(),
    inputSchema = Tool.Input(
        properties = JsonObject(
            mapOf(
                "state" to JsonObject(
                    mapOf(
                        "type" to JsonPrimitive("string"),
                        "description" to JsonPrimitive("两个字母的美国州代码（例如CA, NY)")
                    )
                ),
            )
        ),
        required = listOf("state")
    )
) { request ->
    val state = request.arguments["state"]?.jsonPrimitive?.content
    if (state == null) {
        return@addTool CallToolResult(
            content = listOf(TextContent("需要'state'参数。"))
    }
 
    val alerts = httpClient.getAlerts(state)
 
    CallToolResult(content = alerts.map { TextContent(it) })
}
 
// 注册一个工具以按纬度和经度获取天气预报
server.addTool(
    name = "get_forecast",
    description = """
        获取特定纬度/经度的天气预报
    """.trimIndent(),
    inputSchema = Tool.Input(
        properties = JsonObject(
            mapOf(
                "latitude" to JsonObject(mapOf("type" to JsonPrimitive("number"))),
                "longitude" to JsonObject(mapOf("type" to JsonPrimitive("number"))),
            )
        ),
        required = listOf("latitude", "longitude")
    )
) { request ->
    val latitude = request.arguments["latitude"]?.jsonPrimitive?.doubleOrNull
    val longitude = request.arguments["longitude"]?.jsonPrimitive?.doubleOrNull
    if (latitude == null || longitude == null) {
        return@addTool CallToolResult(
            content = listOf(TextContent("需要'latitude'和'longitude'参数。"))
    }
 
    val forecast = httpClient.getForecast(latitude, longitude)
 
    CallToolResult(content = forecast.map { TextContent(it) })
}

运行服务端

最后，实现主函数以运行服务端：


fun main() = `run mcp server`()

确保运行./gradlew build来构建你的服务端。这是让你的服务端连接的重要步骤。

现在让我们从现有的MCP主机Claude for Desktop测试你的服务端。

使用Claude for Desktop测试你的服务端

Claude for Desktop尚未在Linux上提供。Linux用户可以继续构建客户端教程，以构建一个连接到我们刚刚构建的服务端的MCP客户端。

首先，确保你已经安装了Claude for Desktop。你可以在这里安装最新版本。如果你已经安装了Claude for Desktop，请确保它已更新到最新版本。

例如，如果你安装了VS Code ：

MacOS/Linux


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

然后你将在mcpServers键中添加你的服务端。只有在至少正确配置了一个服务端的情况下，MCP UI元素才会在Claude for Desktop中显示。

在这种情况下，我们将添加我们的单个天气服务端，如下所示：

MacOS/Linux


{
    "mcpServers": {
        "weather": {
            "command": "java",
            "args": [
                "-jar",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/libs/weather-0.1.0-all.jar"
            ]
        }
    }
}

这告诉Claude for Desktop：

有一个名为“weather”的MCP服务端
通过运行java -jar /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/libs/weather-0.1.0-all.jar来启动它

保存文件，并重新启动Claude for Desktop。

使用命令测试

让我们确保Claude for Desktop能够识别我们在weather服务端中暴露的两个工具。你可以通过查找锤子图标来做到这一点：

点击锤子图标后，你应该看到列出的两个工具：

如果你的服务端没有被Claude for Desktop识别，请继续故障排除部分以获取调试提示。

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

萨克拉门托的天气如何？
德克萨斯州有哪些活跃的天气警报？

由于这是美国国家气象局服务，查询仅适用于美国位置。

幕后发生了什么

当你提出问题时：

客户端将你的问题发送给Claude
Claude分析可用的工具并决定使用哪个工具
客户端通过MCP服务端执行所选工具
结果被发送回Claude
Claude制定自然语言响应
响应显示给你！

故障排除

Claude for Desktop集成问题

从Claude for Desktop获取日志

与MCP相关的Claude.app日志写入~/Library/Logs/Claude中的日志文件：

mcp.log将包含有关MCP连接和连接失败的一般日志。
名为mcp-server-SERVERNAME.log的文件将包含来自命名服务端的错误（stderr）日志。

你可以运行以下命令列出最近的日志并跟随任何新的日志：


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

服务端未在Claude中显示

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

工具调用静默失败

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

检查Claude的日志以查找错误
验证你的服务端构建和运行没有错误
尝试重新启动Claude for Desktop

这些都不起作用。我该怎么办？

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

天气API问题

错误：无法检索网格点数据

这通常意味着：

坐标在美国以外
NWS API出现问题
你被限速

修复：

验证你使用的是美国坐标
在请求之间添加小延迟
检查NWS API状态页面

错误：没有活跃的警报用于[STATE]

这不是错误 - 这只是意味着该州当前没有天气警报。尝试不同的州或在恶劣天气期间检查。

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

下一步

学习如何构建你自己的MCP客户端，可以连接到你的服务端构建客户端查看我们的官方MCP服务端和实现的图库示例服务端学习如何有效调试MCP服务端和集成调试指南学习如何使用像Claude这样的LLM来加速你的MCP开发使用LLM构建MCP

面向服务端开发者

​ 我们将构建什么

​ MCP核心概念

Python

预备知识

系统要求

设置你的环境

MacOS/Linux

Windows

MacOS/Linux

Windows

构建你的服务端

导入包并设置实例

辅助函数

实现工具执行

运行服务端

使用Claude for Desktop测试你的服务端

MacOS/Linux

Windows

MacOS/Linux

Windows

Node

预备知识

系统要求

设置你的环境

MacOS/Linux

Windows

构建你的服务端

导入包并设置实例

辅助函数

实现工具执行

运行服务端

使用Claude for Desktop测试你的服务端

MacOS/Linux

Windows

MacOS/Linux

Windows

Java

系统要求

设置你的环境

Maven

Gradle

构建你的服务端

天气服务

创建你的Boot应用程序

运行服务端

使用Claude for Desktop测试你的服务端

MacOS/Linux

Windows

MacOS/Linux

Windows

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

手动创建MCP客户端

使用MCP客户端Boot Starter

更多Java MCP服务端示例

Kotlin

预备知识

系统要求

设置你的环境

MacOS/Linux

Windows

build.gradle.kts

build.gradle

build.gradle.kts

build.gradle

构建你的服务端

设置实例

天气API辅助函数

实现工具执行

运行服务端

使用Claude for Desktop测试你的服务端

MacOS/Linux

Windows

MacOS/Linux

Windows

使用命令测试

​ 幕后发生了什么

​ 故障排除

​ 下一步

我们将构建什么

MCP核心概念

幕后发生了什么

故障排除

下一步