iZhenius/aigent-mcp-server

Kotlin MCP Weather Server

This project demonstrates how to build a Model Context Protocol (MCP) server in Kotlin that provides weather-related tools by consuming the National Weather Service (weather.gov) API. The server supports both STDIO and HTTP transport layers, leveraging the Kotlin MCP SDK to expose weather forecast and alert tools.

For more information about the MCP SDK and protocol, please refer to the MCP documentation.

Prerequisites

• Java 21 or later
• Gradle (or the Gradle wrapper provided with the project)
• Basic understanding of MCP concepts
• Basic understanding of Kotlin and Kotlin ecosystems (such as kotlinx-serialization, coroutines, ktor)

Features

The project provides:

• A lightweight MCP server built with Kotlin
• STDIO transport - for standard input/output communication
• HTTP transport - for REST API-based communication using Ktor
• Two weather tools:
  • Weather Forecast Tool (get_forecast) - returns details such as temperature, wind information, and a detailed forecast for a given latitude/longitude
  • Weather Alerts Tool (get_alerts) - returns active weather alerts for a given US state

Building the Project

Use the Gradle wrapper to build the application:

./gradlew clean build

This will:

• Compile the Kotlin source code
• Run tests
• Create a shadow JAR with all dependencies at build/libs/weather-stdio-server-0.1.0-all.jar

The shadow JAR contains all dependencies and can be run standalone without requiring a classpath.

Running the MCP Server

The project supports two transport modes: STDIO and HTTP.

STDIO Transport

The STDIO server communicates via standard input/output streams, which is the standard MCP transport method.

Starting the STDIO Server

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

Or using the main class directly:

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

The server will start and wait for MCP protocol messages on stdin/stdout.

Connecting an MCP Client to STDIO Server

Using Kotlin MCP Client:

A sample client implementation can be found in src/test/kotlin/io/modelcontextprotocol/sample/client/ClientStdio.kt. The client connects to the server process via standard input/output:

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)

Using Claude Desktop:

To integrate with Claude Desktop, add the following configuration to your Claude Desktop settings file (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

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

[!NOTE] Replace /absolute/path/to/weather-stdio-server-0.1.0-all.jar with the actual absolute path to your built JAR file.

After adding the configuration, restart Claude Desktop. The weather tools will be available in your Claude conversations.

HTTP Transport

The HTTP server provides a REST API endpoint for MCP protocol communication using JSON-RPC over HTTP.

Starting the HTTP Server

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

Or with default port (8080):

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

The server will start and display:

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 Server Endpoints

• GET /health - Health check endpoint
• POST /mcp - Main MCP JSON-RPC endpoint

Connecting an MCP Client to HTTP Server

The HTTP server accepts JSON-RPC requests. Here's how to interact with it:

1. Initialize the connection:

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. List available tools:

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

3. Call a tool (example: get forecast):

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. Call a tool (example: get alerts):

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"
      }
    }
  }'

Using a Kotlin HTTP Client:

You can also create an HTTP-based MCP client using the Kotlin MCP SDK. The client would send HTTP POST requests to the /mcp endpoint with JSON-RPC formatted messages.

Tool Details

Weather Forecast Tool (get_forecast)

Fetches the weather forecast for a specific latitude and longitude using the weather.gov API.

Parameters:

• latitude (number, required) - Latitude coordinate
• longitude (number, required) - Longitude coordinate

Returns:

• Detailed forecast information including temperature, wind speed, wind direction, and detailed forecast text

Weather Alerts Tool (get_alerts)

Retrieves active weather alerts for a US state.

Parameters:

• state (string, required) - Two-letter US state code (e.g., "CA", "NY", "TX")

Returns:

• List of active weather alerts including event type, area description, severity, description, and instructions

Project Structure

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

Additional Resources

• MCP Specification
• Kotlin MCP SDK
• Ktor Documentation
• Kotlinx Serialization
• National Weather Service API