-
Notifications
You must be signed in to change notification settings - Fork 245
docs: streamable server sample #595
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
8 commits
Select commit
Hold shift + click to select a range
b93da34
Add simple streamable server implementation with authentication suppo…
devcrocod d6bbd93
Update README.md: Adjust section indentation, update examples, and en…
devcrocod 0b159bf
Add sample READMEs for MCP implementations and improve documentation …
devcrocod bbf034d
Remove trailing slashes from links in sample READMEs for consistency …
devcrocod 43ba297
Simplify Gradle commands in sample READMEs, configure additional CORS…
devcrocod a0526c3
Switch simple-streamable-server from CIO to Netty server engine
devcrocod 176ef85
Update README and simple-streamable-server
devcrocod eba395b
Include `simple-streamable-server` in GitHub Actions workflows
devcrocod File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,55 @@ | ||
| # Kotlin MCP SDK Samples | ||
|
|
||
| Runnable projects demonstrating MCP server and client implementations with the | ||
| [Kotlin MCP SDK](https://github.com/modelcontextprotocol/kotlin-sdk). | ||
| For background on the protocol itself, see the [MCP documentation](https://modelcontextprotocol.io/introduction). | ||
|
|
||
| ## Overview | ||
|
|
||
| | Sample | Type | Transport | MCP Features | | ||
| |--------------------------------------------------------|-------------------|-----------------|------------------------------------| | ||
| | [simple-streamable-server](./simple-streamable-server) | Server | Streamable HTTP | Tools, Resources, Prompts, Logging | | ||
| | [kotlin-mcp-server](./kotlin-mcp-server) | Server | STDIO, SSE | Tools, Resources, Prompts | | ||
| | [weather-stdio-server](./weather-stdio-server) | Server | STDIO | Tools | | ||
| | [kotlin-mcp-client](./kotlin-mcp-client) | Client | STDIO | Tool discovery & invocation | | ||
| | [notebooks](./notebooks) | Client (Notebook) | Streamable HTTP | Tool discovery & invocation | | ||
|
|
||
| ## Getting Started | ||
|
|
||
| - **Building a server?** Start with [simple-streamable-server](./simple-streamable-server) — it | ||
| uses the recommended Streamable HTTP transport and covers tools, resources, prompts, and logging. | ||
| - **Building a client?** Open the [notebooks](./notebooks) sample for a step-by-step walkthrough, | ||
| or see [kotlin-mcp-client](./kotlin-mcp-client) for a full CLI client with Anthropic API | ||
| integration. | ||
|
|
||
| ## Samples | ||
|
|
||
| ### Simple Streamable HTTP Server | ||
|
|
||
| A minimal Streamable HTTP server with optional Bearer token authentication. Demonstrates tools | ||
| (`greet`, `multi-greet`), a prompt template, a resource, and server-to-client logging notifications. | ||
| [Read more →](./simple-streamable-server) | ||
|
|
||
| ### Kotlin MCP Server | ||
|
|
||
| A multi-transport server supporting STDIO, SSE (plain), and SSE (Ktor plugin). Useful for exploring | ||
| different transport modes side by side. | ||
| [Read more →](./kotlin-mcp-server) | ||
|
|
||
| ### Weather STDIO Server | ||
|
|
||
| A focused STDIO server that exposes weather forecast and alert tools backed by the weather.gov API. | ||
| Includes Claude Desktop integration instructions. | ||
| [Read more →](./weather-stdio-server) | ||
|
|
||
| ### Kotlin MCP Client | ||
|
|
||
| An interactive CLI client that connects to any MCP server over STDIO and routes queries through | ||
| Anthropic's Claude API, bridging MCP tools with LLM conversations. | ||
| [Read more →](./kotlin-mcp-client) | ||
|
|
||
| ### MCP Client Notebook | ||
|
|
||
| A Kotlin notebook that connects to a remote MCP server via Streamable HTTP and demonstrates ping, | ||
| tool listing, and tool invocation — all in an interactive cell-by-cell format. | ||
| [Read more →](./notebooks) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,69 +1,50 @@ | ||
| # Kotlin MCP Client | ||
|
|
||
| This project demonstrates how to build a Model Context Protocol (MCP) client in Kotlin that interacts with an MCP server | ||
| via a STDIO transport layer while leveraging Anthropic's API for natural language processing. The client uses the MCP | ||
| Kotlin SDK to communicate with an MCP server that exposes various tools, and it uses Anthropic's API to process user | ||
| queries and integrate tool responses into the conversation. | ||
|
|
||
| For more information about the MCP SDK and protocol, please refer to | ||
| the [MCP documentation](https://modelcontextprotocol.io/introduction). | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| - **Java 17 or later** | ||
| - **Gradle** (or the Gradle wrapper provided with the project) | ||
| - An Anthropic API key set in your environment variable `ANTHROPIC_API_KEY` | ||
| - Basic understanding of MCP concepts and Kotlin programming | ||
| An interactive CLI client that connects to any MCP server over STDIO and pipes queries through | ||
| Anthropic's Claude API. | ||
|
|
||
| ## Overview | ||
|
|
||
| The client application performs the following tasks: | ||
| This sample demonstrates a complete MCP client workflow: launching an MCP server as a subprocess, | ||
| discovering its tools, converting them to Anthropic's tool format, and running an interactive chat | ||
| loop where Claude can call server tools on behalf of the user. | ||
|
kpavlov marked this conversation as resolved.
|
||
|
|
||
| - **Connecting to an MCP server** — | ||
| launches an MCP server process (implemented in JavaScript, Python, or Java) using STDIO transport. | ||
| It connects to the server, retrieves available tools, and converts them to Anthropic’s tool format. | ||
| - **Processing queries** — | ||
| accepts user queries, sends them to Anthropic’s API along with the registered tools, and handles responses. | ||
| If the response indicates a tool should be called, it invokes the corresponding MCP tool and continues the | ||
| conversation based on the tool’s result. | ||
| - **Interactive chat loop** — | ||
| runs an interactive command-line loop, allowing users to continuously submit queries and receive responses. | ||
| ## Prerequisites | ||
|
|
||
| ## Building and Running | ||
| - JDK 17+ | ||
| - An `ANTHROPIC_API_KEY` environment variable set with a valid Anthropic API key | ||
| - An MCP server script to connect to (`.js`, `.py`, or `.jar`) | ||
|
|
||
| Use the Gradle wrapper to build the application. In a terminal, run: | ||
| ## Build & Run | ||
|
|
||
| ```shell | ||
| ./gradlew clean build | ||
| ``` | ||
| Run the client, passing the path to an MCP server: | ||
|
|
||
| To run the client, execute the jar file and provide the path to your MCP server script. | ||
| ```shell | ||
| # Connect to a JVM server | ||
| ./gradlew run --args="path/to/server.jar" | ||
|
|
||
| To run the client with any MCP server: | ||
| # Connect to a Python server | ||
| ./gradlew run --args="path/to/server.py" | ||
|
|
||
| ```shell | ||
| java -jar build/libs/<your-jar-name>.jar path/to/server.jar # jvm server | ||
| java -jar build/libs/<your-jar-name>.jar path/to/server.py # python server | ||
| java -jar build/libs/<your-jar-name>.jar path/to/build/index.js # node server | ||
| # Connect to a Node.js server | ||
| ./gradlew run --args="path/to/build/index.js" | ||
| ``` | ||
|
devcrocod marked this conversation as resolved.
|
||
|
|
||
| > [!NOTE] | ||
| > The client uses STDIO transport, so it launches the MCP server as a separate process. | ||
| > The client uses STDIO transport, so it launches the MCP server as a subprocess. | ||
| > Ensure the server script is executable and is a valid `.js`, `.py`, or `.jar` file. | ||
|
|
||
| ## Configuration for Anthropic | ||
| ## MCP Capabilities | ||
|
|
||
| Ensure your Anthropic API key is available in your environment: | ||
|
|
||
| ```shell | ||
| export ANTHROPIC_API_KEY=your_anthropic_api_key_here | ||
| ``` | ||
| From the **client** perspective, this sample demonstrates: | ||
|
|
||
| The client uses `AnthropicOkHttpClient.fromEnv()` to automatically load the API key from `ANTHROPIC_API_KEY` and | ||
| `ANTHROPIC_AUTH_TOKEN` environment variables. | ||
| - **Tool discovery** — lists tools from the connected server and converts them to Anthropic's tool | ||
| format. | ||
| - **Tool invocation** — when Claude's response requests a tool call, the client invokes the | ||
| corresponding MCP tool and feeds the result back into the conversation. | ||
|
|
||
| ## Additional Resources | ||
|
|
||
| - [MCP Specification](https://spec.modelcontextprotocol.io/) | ||
| - [MCP Specification](https://modelcontextprotocol.io/specification/latest) | ||
| - [Kotlin MCP SDK](https://github.com/modelcontextprotocol/kotlin-sdk) | ||
| - [Anthropic Java SDK](https://github.com/anthropics/anthropic-sdk-java/tree/main) | ||
| - [Anthropic Java SDK](https://github.com/anthropics/anthropic-sdk-java) | ||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
👍🏻