docs: streamable server sample (#595)
- add a simple streamable http server example with auth - update readme: replace quickstart example from sse server to streamable server - add readme files for samples, simple-streamable-server, notebooks closes #170 ## How Has This Been Tested? knit and inspector ## Breaking Changes NaN ## Types of changes - [ ] Bug fix (non-breaking change which fixes an issue) - [ ] New feature (non-breaking change which adds functionality) - [ ] Breaking change (fix or feature that would cause existing functionality to change) - [x] Documentation update ## Checklist - [x] I have read the [MCP Documentation](https://modelcontextprotocol.io) - [x] My code follows the repository's style guidelines - [x] New and existing tests pass locally - [ ] I have added appropriate error handling - [x] I have added or updated documentation as needed
This commit is contained in:
Pavel Gorgulov
GitHub
parent
5b58814613
commit
0b39f57cff
1 changed files with 1085 additions and 254 deletions
|
|
@ -1,140 +1,67 @@
|
|||
# Kotlin MCP Weather STDIO Server
|
||||
# Weather STDIO 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 uses STDIO as the transport layer and
|
||||
leverages the Kotlin MCP SDK to expose weather forecast and alert tools.
|
||||
A minimal MCP server that exposes weather forecast and alert tools using the National Weather
|
||||
Service API over STDIO transport.
|
||||
|
||||
For more information about the MCP SDK and protocol, please refer to
|
||||
the [MCP documentation](https://modelcontextprotocol.io/introduction).
|
||||
## Overview
|
||||
|
||||
This sample shows how to build a STDIO-based MCP server in Kotlin. It registers two tools that
|
||||
query the [weather.gov](https://www.weather.gov/) API — one for weather forecasts by
|
||||
latitude/longitude and one for active alerts by US state. Because it uses STDIO, the server is
|
||||
launched as a subprocess by an MCP client or a desktop application like Claude Desktop.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Java 17 or later
|
||||
- Gradle (or the Gradle wrapper provided with the project)
|
||||
- Basic understanding of MCP concepts
|
||||
- Basic understanding of Kotlin and Kotlin ecosystems (sush as kotlinx-serialization, coroutines, ktor)
|
||||
- JDK 17+
|
||||
- Internet access (the server calls the weather.gov API at runtime)
|
||||
|
||||
## MCP Weather Server
|
||||
## Build & Run
|
||||
|
||||
The project provides:
|
||||
|
||||
- A lightweight MCP server built with Kotlin.
|
||||
- STDIO transport layer implementation for server-client communication.
|
||||
- Two weather tools:
|
||||
- **Weather Forecast Tool** — returns details such as temperature, wind information, and a detailed forecast for a
|
||||
given latitude/longitude.
|
||||
- **Weather Alerts Tool** — returns active weather alerts for a given US state.
|
||||
|
||||
## Building and running
|
||||
|
||||
Use the Gradle wrapper to build the application. In a terminal run:
|
||||
Run the server (it communicates via stdin/stdout):
|
||||
|
||||
```shell
|
||||
./gradlew clean build
|
||||
./gradlew run
|
||||
```
|
||||
|
||||
To run the server:
|
||||
### MCP Inspector
|
||||
|
||||
Build the fat JAR first, then connect with the
|
||||
[MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector):
|
||||
|
||||
```shell
|
||||
java -jar build/libs/weather-stdio-server-0.1.0-all.jar
|
||||
./gradlew build
|
||||
npx @modelcontextprotocol/inspector -- java -jar samples/weather-stdio-server/build/libs/weather-stdio-server-0.1.0-all.jar
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> The server uses STDIO transport, so it is typically launched in an environment where the client connects via standard
|
||||
> input/output.
|
||||
### Claude Desktop integration
|
||||
|
||||
## Tool Implementation
|
||||
|
||||
The project registers two MCP tools using the Kotlin MCP SDK. Below is an overview of the core tool implementations:
|
||||
|
||||
### 1. Weather Forecast Tool
|
||||
|
||||
This tool fetches the weather forecast for a specific latitude and longitude using the `weather.gov` API.
|
||||
|
||||
Example tool registration in Kotlin:
|
||||
|
||||
```kotlin
|
||||
server.addTool(
|
||||
name = "get_forecast",
|
||||
description = """
|
||||
Get weather forecast for a specific latitude/longitude
|
||||
""".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 ->
|
||||
// Implementation tool
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Weather Alerts Tool
|
||||
|
||||
This tool retrieves active weather alerts for a US state.
|
||||
|
||||
Example tool registration in Kotlin:
|
||||
|
||||
```kotlin
|
||||
server.addTool(
|
||||
name = "get_alerts",
|
||||
description = """
|
||||
Get weather alerts for a US state. Input is Two-letter US state code (e.g. CA, NY)
|
||||
""".trimIndent(),
|
||||
inputSchema = Tool.Input(
|
||||
properties = JsonObject(
|
||||
mapOf(
|
||||
"state" to JsonObject(
|
||||
mapOf(
|
||||
"type" to JsonPrimitive("string"),
|
||||
"description" to JsonPrimitive("Two-letter US state code (e.g. CA, NY)")
|
||||
)
|
||||
),
|
||||
)
|
||||
),
|
||||
required = listOf("state")
|
||||
)
|
||||
) { request ->
|
||||
// Implementation tool
|
||||
}
|
||||
```
|
||||
|
||||
## Client Integration
|
||||
|
||||
### Kotlin Client Example
|
||||
|
||||
Since the server uses STDIO for transport, the client typically connects via standard input/output streams. A sample
|
||||
client implementation can be found in the tests, demonstrating how to send tool requests and process responses.
|
||||
|
||||
### Claude for Desktop
|
||||
|
||||
To integrate with Claude Desktop, add the following configuration to your Claude Desktop settings:
|
||||
Add the following to your Claude Desktop configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"weather": {
|
||||
"command": "java",
|
||||
"args": [
|
||||
"-jar",
|
||||
"/absolute/path/to/<your-jar-name>.jar"
|
||||
]
|
||||
"mcpServers": {
|
||||
"weather": {
|
||||
"command": "java",
|
||||
"args": [
|
||||
"-jar",
|
||||
"/absolute/path/to/samples/weather-stdio-server/build/libs/weather-stdio-server-0.1.0-all.jar"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> Replace `/absolute/path/to/<your-jar-name>.jar` with the actual absolute path to your built jar file.
|
||||
## MCP Capabilities
|
||||
|
||||
### Tools
|
||||
|
||||
| Name | Description |
|
||||
|----------------|------------------------------------------------------------------------------------------|
|
||||
| `get_forecast` | Returns weather forecast for a given `latitude` / `longitude` using the weather.gov API. |
|
||||
| `get_alerts` | Returns active weather alerts for a two-letter US `state` code (e.g. `CA`, `NY`). |
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [MCP Specification](https://spec.modelcontextprotocol.io/)
|
||||
- [MCP Specification](https://modelcontextprotocol.io/specification/latest)
|
||||
- [Kotlin MCP SDK](https://github.com/modelcontextprotocol/kotlin-sdk)
|
||||
- [Ktor Client Documentation](https://ktor.io/docs/welcome.html)
|
||||
- [Kotlinx Serialization](https://kotlinlang.org/docs/serialization.html)
|
||||
|
||||
- [National Weather Service API](https://www.weather.gov/documentation/services-web-api)
|
||||
|
|
|
|||
Loading…
Reference in a new issue