Aigent MCP Server

Kotlin MCP气象服务器

该项目演示了如何在Kotlin构建一个模型上下文协议（MCP）服务器，该服务器通过使用美国国家气象局（weather.gov）API提供与天气相关的工具。该服务器支持STDIO和HTTP传输层，利用Kotlin MCP SDK公开天气预报和警报工具。

有关MCP SDK和协议的更多信息，请参阅 MCP文件.

先决条件

• Java 21或更高版本
• Gradle（或项目提供的Gradle包装器）
• 对MCP概念的基本理解
• 对Kotlin和Kotlin生态系统的基本了解（如kotlinx序列化、协程、ktor）

特性

该项目提供：

• 用Kotlin构建的轻量级MCP服务器
• STDIO传输 -用于标准输入/输出通信
• HTTP传输 -用于使用Ktor进行基于REST API的通信
• 两种天气工具：

- 天气预报工具 (get_forecast)-返回温度、风信息等详细信息，以及给定纬度/经度的详细预报 - 天气警报工具 (get_alerts)-返回美国特定州的活动天气警报

建设项目

使用Gradle包装器构建应用程序：

./gradlew clean build

这将：

• 编译Kotlin源代码
• 运行测试
• 在以下位置创建一个包含所有依赖项的影子JAR build/libs/weather-stdio-server-0.1.0-all.jar

影子JAR包含所有依赖项，可以独立运行而不需要类路径。

运行MCP服务器

该项目支持两种传输模式：STDIO和HTTP。

STDIO传输

STDIO服务器通过标准输入/输出流进行通信，这是标准的MCP传输方法。

启动STDIO服务器

java -jar build/libs/weather-stdio-server-0.1.0-all.jar

或者直接使用main类：

java -cp build/libs/weather-stdio-server-0.1.0-all.jar io.modelcontextprotocol.sample.server.MainKt

服务器将启动并等待stdin/stdout上的MCP协议消息。

将MCP客户端连接到STDIO服务器

使用Kotlin MCP客户端：

示例客户端实现可以在中找到 src/test/kotlin/io/modelcontextprotocol/sample/client/ClientStdio.kt客户端通过标准输入/输出连接到服务器进程：

val process = ProcessBuilder("java", "-jar", "./build/libs/weather-stdio-server-0.1.0-all.jar")
    .start()

val transport = StdioClientTransport(
    input = process.inputStream.asSource().buffered(),
    output = process.outputStream.asSink().buffered(),
)

val client = Client(
    clientInfo = Implementation(name = "weather", version = "1.0.0"),
)

client.connect(transport)

使用克劳德桌面：

要与Claude Desktop集成，请将以下配置添加到您的Claude Desktop设置文件中（通常位于 ~/Library/Application Support/Claude/claude_desktop_config.json 在macOS或 %APPDATA%\Claude\claude_desktop_config.json 在Windows上）：

{
  "mcpServers": {
    "weather": {
      "command": "java",
      "args": [
        "-jar",
        "/absolute/path/to/weather-stdio-server-0.1.0-all.jar"
      ]
    }
  }
}

\[！注意\] 替换 /absolute/path/to/weather-stdio-server-0.1.0-all.jar 使用构建的JAR文件的实际绝对路径。

添加配置后，重新启动Claude Desktop。天气工具将在您的克劳德对话中提供。

HTTP传输

HTTP服务器使用HTTP上的JSON-RPC为MCP协议通信提供REST API端点。

启动HTTP服务器

java -cp build/libs/weather-stdio-server-0.1.0-all.jar io.modelcontextprotocol.sample.server.HttpMainKt --port 8080

或者使用默认端口（8080）：

java -cp build/libs/weather-stdio-server-0.1.0-all.jar io.modelcontextprotocol.sample.server.HttpMainKt

服务器将启动并显示：

Starting MCP HTTP server on port 8080
Health check: http://localhost:8080/health
MCP endpoint: http://localhost:8080/mcp
Use POST requests with JSON-RPC format to interact with the server

HTTP服务器端点

• GET /health -健康检查端点
• POST /mcp -主MCP JSON-RPC端点

将MCP客户端连接到HTTP服务器

HTTP服务器接受JSON-RPC请求。以下是如何与它交互：

1.初始化连接：

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {
        "name": "test-client",
        "version": "1.0.0"
      }
    }
  }'

2.列出可用工具：

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list"
  }'

3.调用一个工具（例如：获取预测）：

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_forecast",
      "arguments": {
        "latitude": 38.5816,
        "longitude": -121.4944
      }
    }
  }'

4.调用工具（例如：获取警报）：

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "get_alerts",
      "arguments": {
        "state": "CA"
      }
    }
  }'

使用Kotlin HTTP客户端：

您还可以使用Kotlin MCP SDK创建基于HTTP的MCP客户端。客户端将向 /mcp 带有JSON-RPC格式消息的端点。

工具详细信息

天气预报工具(get_forecast)

使用以下命令获取特定纬度和经度的天气预报 weather.gov API

参数：

• latitude （数字，必填）-纬度坐标
• longitude （数字，必填）-经度坐标

退货：

• 详细的预报信息，包括温度、风速、风向和详细的预报文本

天气警报工具(get_alerts)

检索美国某个州的活动天气警报。

参数：

• state （字符串，必填）-两个字母的美国州代码（例如，“CA”、“NY”、“TX”）

退货：

• 活动天气警报列表，包括事件类型、区域描述、严重程度、描述和说明

项目结构

src/
├── main/
│   └── kotlin/
│       └── io/modelcontextprotocol/sample/server/
│           ├── main.kt              # STDIO server entry point
│           ├── HttpMain.kt          # HTTP server entry point
│           ├── McpWeatherServer.kt  # STDIO server implementation
│           ├── McpHttpServer.kt     # HTTP server implementation
│           └── WeatherApi.kt        # Weather API client
└── test/
    └── kotlin/
        └── io/modelcontextprotocol/sample/client/
            └── ClientStdio.kt       # Sample STDIO client

其他资源

• MCP规范
• Kotlin MCP SDK
• Ktor文件
• Kotlinx序列化
• 美国国家气象局API