Adds 'instructions' string to the Server and propagates to the InitializeResult #290

jclyne · 2025-09-25T15:15:50Z

Motivation and Context

The schema for the InitializeResult contains an optional 'instructions' string

How Has This Been Tested?

Its relatively simple change with unit tests included

Breaking Changes

No, field is optional and defaults to null

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)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

Additional context

The instructions string is included in the schema for for version "2025-03-26"

The instructions in the Server class are given as a provider function with the result of the provider propagated to the underlying ServerSession. As the ServerSession change is meant to allow for a 'Singleton scoped' server class, this provides the ability to dynamically modify the instructions at the server level but have them be immutable per session.

This also refactors the serverInfo and instructions properties to be protected. This Server class is open and meant to be overridden, there is no harm in having these immutable properties available to subclasses.

This adds the serverInstructions to the client as returned from the InitializeResult. This is used to verify the response in the Server tests.

Copilot

Pull Request Overview

This PR implements the optional instructions field from the MCP schema version "2025-03-26" by adding it to the Server constructor and propagating it through to the InitializeResult.

Added instructions parameter to Server constructor with default value of null
Updated InitializeResult data class to include optional instructions field
Added comprehensive test coverage for the new functionality

Reviewed Changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
kotlin-sdk-core/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/types.kt	Added instructions field to InitializeResult data class with documentation
kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/Server.kt	Updated Server constructor to accept instructions parameter and pass it to InitializeResult
kotlin-sdk-core/src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/TypesTest.kt	Added comprehensive tests for InitializeResult with and without instructions
kotlin-sdk-test/src/jvmTest/kotlin/io/modelcontextprotocol/kotlin/sdk/server/ServerTest.kt	Added tests for Server constructor with instructions parameter variants
kotlin-sdk-core/api/kotlin-sdk-core.api	Updated API signatures to reflect new InitializeResult structure
kotlin-sdk-server/api/kotlin-sdk-server.api	Updated API signatures to reflect new Server constructor

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

Copilot

Pull Request Overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

kpavlov

Thank you @jclyne
I have one question about testing, but overall looks good to me

kpavlov · 2025-09-28T11:43:08Z

kotlin-sdk-test/src/jvmTest/kotlin/io/modelcontextprotocol/kotlin/sdk/server/ServerTest.kt

    }
+
+    @Test
+    fun `Server constructor should accept instructions parameter`() = runTest {


Thank you for the test!
One question: Is it possible to verify in the test that the server has received the instructions string?
Also, the test could be parametrized

The serverInstructions were added to the client as a property that can be verified in these tests.

kpavlov · 2025-09-28T11:45:33Z

kotlin-sdk-core/src/commonTest/kotlin/io/modelcontextprotocol/kotlin/sdk/TypesTest.kt

+        val json = McpJson.encodeToString(result)
+        val decoded = McpJson.decodeFromString<InitializeResult>(json)


nit: I think we should introduce some serialization helper for tests like this, like here

This would probably be applicable to all the tests in this file, so I would prefer to leave it to a different PR if that's ok

I agree with both statements

…ons' into support-for-mcp-server-instructions

# Conflicts: # kotlin-sdk-server/api/kotlin-sdk-server.api # kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/Server.kt

…ation to the ServerTests (addresses PR feedback)

…sourced dynamically for each session if desired

Copilot

Pull Request Overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated 4 comments.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

kotlin-sdk-client/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/Client.kt

README.md

Copilot

Pull Request Overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated no new comments.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

kpavlov

LGTM

kyeotic · 2025-09-30T23:13:49Z

@kpavlov We also need this for parity with FastMCP python servers. Any chance you can ballpark an ETA for this getting merged/released?

devcrocod

Thank you for your contribution!

I have a question regarding the api design, could you please take a look?
Everything else looks good to me!

devcrocod · 2025-10-02T09:35:00Z

kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/Server.kt

+public open class Server(
+    protected val serverInfo: Implementation,
+    protected val options: ServerOptions,
+    protected val instructionsProvider: (() -> String)? = null,


Why is this implemented as a lambda and not just a string?

This is allowing the instructions to potentially be dynamically loaded from a database or string server. With the change to the ServerSession, the Server seems to take more of a Singleton scope vs a Server per stream. The idea is that the Server has a provider method for the string which it evaluates as a string value for the ServerSession.

~~Its possible to add an additional constructor that just takes a static string and converts it to a lamda, but that is trivial for the caller.~~

I went ahead and added an alternative constructor that takes a static string

devcrocod · 2025-10-02T09:45:35Z

Hi @jclyne
We recently added ServerSession, which still requires some improvements.
Soon we plan to estimate the timeline for a stable release.

In the meantime, next week we’d like to set up snapshot releases

jclyne · 2025-10-02T16:16:01Z

Hi @jclyne We recently added ServerSession, which still requires some improvements. Soon we plan to estimate the timeline for a stable release.

In the meantime, next week we’d like to set up snapshot releases

Thanks @devcrocod! I would like to get this in the snapshot release if at all possible.

Adds Instructions to the server and propagates to the InitializeResult

f5f24fa

Copilot AI review requested due to automatic review settings September 25, 2025 15:15

Copilot AI reviewed Sep 25, 2025

View reviewed changes

Adds documentation updates for examples

574c435

jclyne requested a review from Copilot September 25, 2025 15:21

Copilot AI reviewed Sep 25, 2025

View reviewed changes

jclyne added 4 commits September 26, 2025 12:41

refactors the serverInfo and instructions to protected

0d8253e

Adds Instructions to the server and propagates to the InitializeResult

c0249a5

Adds documentation updates for examples

b8a5945

refactors the serverInfo and instructions to protected

6a95a59

kpavlov force-pushed the support-for-mcp-server-instructions branch from 0d8253e to 6a95a59 Compare September 28, 2025 03:36

kpavlov reviewed Sep 28, 2025

View reviewed changes

kpavlov added enhancement New feature or request question Further information is requested labels Sep 28, 2025

jclyne added 5 commits September 29, 2025 12:09

Merge remote-tracking branch 'origin/support-for-mcp-server-instructi…

4b7674f

…ons' into support-for-mcp-server-instructions

Merge branch 'main' into support-for-mcp-server-instructions

1a714d7

# Conflicts: # kotlin-sdk-server/api/kotlin-sdk-server.api # kotlin-sdk-server/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/server/Server.kt

Added the returned serverInstructions to the client and added verific…

74aeaff

…ation to the ServerTests (addresses PR feedback)

Modifies top level Server instructions to be a provider so it can be …

3e682ec

…sourced dynamically for each session if desired

updates client API to add serverInstructions

083ff48

jclyne requested a review from Copilot September 29, 2025 18:42

Copilot AI reviewed Sep 29, 2025

View reviewed changes

kotlin-sdk-client/src/commonMain/kotlin/io/modelcontextprotocol/kotlin/sdk/client/Client.kt Outdated Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

README.md Outdated Show resolved Hide resolved

Fixes documentation inconsistencies

b05a196

jclyne requested a review from Copilot September 29, 2025 18:56

Copilot AI reviewed Sep 29, 2025

View reviewed changes

jclyne requested a review from kpavlov September 29, 2025 21:09

kpavlov previously approved these changes Sep 29, 2025

View reviewed changes

kpavlov requested a review from devcrocod September 29, 2025 21:28

Merge branch 'main' into support-for-mcp-server-instructions

99555d2

devcrocod requested changes Oct 2, 2025

View reviewed changes

Adds alternative constructor that takes a static instructions string

8600054

jclyne dismissed kpavlov’s stale review via 8600054 October 2, 2025 16:37

jclyne requested review from kpavlov and devcrocod October 2, 2025 16:40

jclyne mentioned this pull request Oct 2, 2025

Adds support for mcp server instructions cashapp/misk#3430

Open

3 tasks

		val json = McpJson.encodeToString(result)
		val decoded = McpJson.decodeFromString<InitializeResult>(json)

Adds 'instructions' string to the Server and propagates to the InitializeResult #290

Are you sure you want to change the base?

Adds 'instructions' string to the Server and propagates to the InitializeResult #290

Conversation

jclyne commented Sep 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

kpavlov left a comment

Choose a reason for hiding this comment

Uh oh!

kpavlov Sep 28, 2025

Choose a reason for hiding this comment

Uh oh!

jclyne Sep 29, 2025

Choose a reason for hiding this comment

Uh oh!

kpavlov Sep 28, 2025

Choose a reason for hiding this comment

Uh oh!

jclyne Sep 29, 2025

Choose a reason for hiding this comment

Uh oh!

devcrocod Oct 2, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

kpavlov left a comment

Choose a reason for hiding this comment

Uh oh!

kyeotic commented Sep 30, 2025

Uh oh!

devcrocod left a comment

Choose a reason for hiding this comment

Uh oh!

devcrocod Oct 2, 2025

Choose a reason for hiding this comment

Uh oh!

jclyne Oct 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

devcrocod commented Oct 2, 2025

Uh oh!

jclyne commented Oct 2, 2025

Uh oh!

Uh oh!

jclyne commented Sep 25, 2025 •

edited

Loading

jclyne Oct 2, 2025 •

edited

Loading