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,93 +1,85 @@
|
|||
# MCP Kotlin Server Sample
|
||||
# Kotlin MCP Server
|
||||
|
||||
A sample implementation of an MCP (Model Context Protocol) server in Kotlin that demonstrates different server
|
||||
configurations and transport methods.
|
||||
A sample MCP server demonstrating multiple transport modes: STDIO, SSE (plain), and SSE (Ktor
|
||||
plugin).
|
||||
|
||||
## Features
|
||||
> **Note:** The SSE transport modes are provided for backward compatibility. For new projects,
|
||||
> consider using the [simple-streamable-server](../simple-streamable-server) sample, which uses the
|
||||
> recommended Streamable HTTP transport.
|
||||
|
||||
- Multiple server operation modes:
|
||||
- Standard I/O server
|
||||
- SSE (Server-Sent Events) server with plain configuration
|
||||
- SSE server using Ktor plugin
|
||||
- Built-in capabilities for:
|
||||
- Prompts management
|
||||
- Resources handling
|
||||
- Tools integration
|
||||
## Overview
|
||||
|
||||
## Getting Started
|
||||
This sample registers a prompt, a tool, and a resource, then lets you choose how to expose them.
|
||||
STDIO mode is the default and is best for process-based clients. The two SSE modes show how to
|
||||
serve MCP over HTTP using either a manual Ktor routing setup or the built-in `mcp { }` Ktor plugin.
|
||||
|
||||
### Running the Server
|
||||
## Prerequisites
|
||||
|
||||
The server defaults [STDIO transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio).
|
||||
- JDK 17+
|
||||
- [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) (optional, for testing)
|
||||
|
||||
You can customize the behavior using command-line arguments.
|
||||
Logs are printed to [./build/stdout.log](./build/stdout.log)
|
||||
## Build & Run
|
||||
|
||||
#### Standard I/O mode (STDIO):
|
||||
|
||||
```bash
|
||||
./gradlew clean build
|
||||
```
|
||||
Use the [MCP inspector](https://modelcontextprotocol.io/docs/tools/inspector)
|
||||
to connect to MCP via STDIO (Click the "▶️ Connect" button):
|
||||
### STDIO mode (default)
|
||||
|
||||
```shell
|
||||
npx @modelcontextprotocol/inspector --config mcp-inspector-config.json --server stdio-server
|
||||
./gradlew run
|
||||
```
|
||||
|
||||
#### SSE with plain configuration:
|
||||
Or explicitly:
|
||||
|
||||
**NB!: 🐞 This configuration may not work ATM**
|
||||
|
||||
```bash
|
||||
./gradlew run --args="--sse-server 3001"
|
||||
```
|
||||
or
|
||||
```shell
|
||||
./gradlew clean build
|
||||
java -jar ./build/libs/kotlin-mcp-server-0.1.0-all.jar --sse-server 3001
|
||||
./gradlew run --args="--stdio"
|
||||
```
|
||||
|
||||
Use the [MCP inspector](https://modelcontextprotocol.io/docs/tools/inspector)
|
||||
to connect to `http://localhost:3002/` via SSE Transport (Click the "▶️ Connect" button):
|
||||
Connect with the MCP Inspector:
|
||||
|
||||
```shell
|
||||
npx @modelcontextprotocol/inspector --config mcp-inspector-config.json --server sse-server
|
||||
npx @modelcontextprotocol/inspector --config samples/kotlin-mcp-server/mcp-inspector-config.json --server stdio-server
|
||||
```
|
||||
|
||||
#### SSE with Ktor plugin:
|
||||
### SSE with Ktor plugin
|
||||
|
||||
```bash
|
||||
```shell
|
||||
./gradlew run --args="--sse-server-ktor 3002"
|
||||
```
|
||||
or
|
||||
|
||||
Connect with the MCP Inspector:
|
||||
|
||||
```shell
|
||||
./gradlew clean build
|
||||
java -jar ./build/libs/kotlin-mcp-server-0.1.0-all.jar --sse-server-ktor 3002
|
||||
npx @modelcontextprotocol/inspector --config samples/kotlin-mcp-server/mcp-inspector-config.json --server sse-ktor-server
|
||||
```
|
||||
|
||||
Use the [MCP inspector](https://modelcontextprotocol.io/docs/tools/inspector)
|
||||
to connect to `http://localhost:3002/` via SSE transport (Click the "▶️ Connect" button):
|
||||
### SSE with plain configuration
|
||||
|
||||
> **Known issue:** This mode may not work correctly at this time.
|
||||
|
||||
```shell
|
||||
npx @modelcontextprotocol/inspector --config mcp-inspector-config.json --server sse-ktor-server
|
||||
./gradlew run --args="--sse-server 3001"
|
||||
```
|
||||
|
||||
## Server Capabilities
|
||||
Connect with the MCP Inspector:
|
||||
|
||||
- **Prompts**: Supports prompt management with list change notifications
|
||||
- **Resources**: Includes subscription support and list change notifications
|
||||
- **Tools**: Supports tool management with list change notifications
|
||||
```shell
|
||||
npx @modelcontextprotocol/inspector --config samples/kotlin-mcp-server/mcp-inspector-config.json --server sse-server
|
||||
```
|
||||
|
||||
## Implementation Details
|
||||
## MCP Capabilities
|
||||
|
||||
The server is implemented using:
|
||||
- Ktor for HTTP server functionality (SSE modes)
|
||||
- Kotlin coroutines for asynchronous operations
|
||||
- SSE for real-time communication in web contexts
|
||||
- Standard I/O for command-line interface and process-based communication
|
||||
### Tools
|
||||
|
||||
## Example Capabilities
|
||||
| Name | Description |
|
||||
|-------------------|------------------------------------------------------|
|
||||
| `kotlin-sdk-tool` | A test tool that returns a "Hello, world!" greeting. |
|
||||
|
||||
The sample server demonstrates:
|
||||
- **Prompt**: "Kotlin Developer" - helps develop small Kotlin applications with a configurable project name
|
||||
- **Tool**: "kotlin-sdk-tool" - a simple test tool that returns a greeting
|
||||
- **Resource**: "Web Search" - a placeholder resource demonstrating resource handling
|
||||
### Prompts
|
||||
|
||||
| Name | Description |
|
||||
|--------------------|------------------------------------------------------------------------------------|
|
||||
| `Kotlin Developer` | Generates a prompt to develop a small Kotlin application for a given project name. |
|
||||
|
||||
### Resources
|
||||
|
||||
| Name | URI | Description |
|
||||
|--------------|-----------------------|---------------------------------------------------------|
|
||||
| `Web Search` | `https://search.com/` | A placeholder resource demonstrating resource handling. |
|
||||
|
|
|
|||
Loading…
Reference in a new issue