Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ import io.modelcontextprotocol.kotlin.sdk.client.CacheMode
import io.modelcontextprotocol.kotlin.sdk.client.Client
import io.modelcontextprotocol.kotlin.sdk.client.ClientOptions
import io.modelcontextprotocol.kotlin.sdk.client.InMemoryResponseCacheStore
import io.modelcontextprotocol.kotlin.sdk.client.ResponseCacheStore
import io.modelcontextprotocol.kotlin.sdk.client.VersionNegotiationMode
import io.modelcontextprotocol.kotlin.sdk.server.Server
import io.modelcontextprotocol.kotlin.sdk.server.ServerOptions
Expand Down Expand Up @@ -169,8 +170,112 @@ class ResponseCacheTest {
fixture.client.close()
}

@Test
fun `clients sharing a store each get their own server's listing`() = runBlocking {
val store = InMemoryResponseCacheStore()
val alphaClient = cachingClient(store)
val bravoClient = cachingClient(store)
connectSession(alphaClient, cacheServer("alpha-server"), tool = "alpha", scope = CacheScope.Public)
connectSession(bravoClient, cacheServer("bravo-server"), tool = "bravo", scope = CacheScope.Public)

alphaClient.listTools().tools.single().name shouldBe "alpha"
bravoClient.listTools().tools.single().name shouldBe "bravo"
alphaClient.close()
bravoClient.close()
}

@Test
fun `a private entry is not served to another client sharing the store`() = runBlocking {
val store = InMemoryResponseCacheStore()
val alice = cachingClient(store)
val bob = cachingClient(store)
connectSession(alice, cacheServer(), tool = "alice-private", scope = CacheScope.Private)
connectSession(bob, cacheServer(), tool = "bob-private", scope = CacheScope.Private)

alice.listTools().tools.single().name shouldBe "alice-private"
bob.listTools().tools.single().name shouldBe "bob-private"
alice.close()
bob.close()
}

@Test
fun `a reconnect to another server does not serve the previous server's listing`() = runBlocking {
val client = cachingClient(InMemoryResponseCacheStore())

connectSession(client, cacheServer("first-server"), tool = "first", scope = CacheScope.Public)
client.listTools().tools.single().name shouldBe "first"
client.close()
connectSession(client, cacheServer("second-server"), tool = "second", scope = CacheScope.Public)

client.listTools().tools.single().name shouldBe "second"
client.close()
}

@Test
fun `clients configured with the same partition share entries`() = runBlocking {
val store = InMemoryResponseCacheStore()
val listCalls = AtomicInteger()
val first = cachingClient(store, partition = "cache-server/alice")
val second = cachingClient(store, partition = "cache-server/alice")
connectSession(first, cacheServer(), tool = "echo", scope = CacheScope.Private, listCalls = listCalls)
connectSession(second, cacheServer(), tool = "echo", scope = CacheScope.Private, listCalls = listCalls)

first.listTools()
second.listTools()

listCalls.get() shouldBe 1
first.close()
second.close()
}

private class Fixture(val server: Server, val client: Client, val listCalls: AtomicInteger)

private fun cacheServer(name: String = "cache-server") = Server(
serverInfo = Implementation(name, "1.0"),
options = ServerOptions(
capabilities = ServerCapabilities(tools = ServerCapabilities.Tools(listChanged = true)),
),
)

private fun cachingClient(store: ResponseCacheStore, partition: String = "") = Client(
clientInfo = Implementation("cache-client", "1.0"),
options = ClientOptions(
versionNegotiation = VersionNegotiationMode.Auto,
responseCache = store,
cachePartition = partition,
),
)

private suspend fun connectSession(
client: Client,
server: Server,
tool: String,
scope: CacheScope,
listCalls: AtomicInteger = AtomicInteger(),
) {
val (clientTransport, serverTransport) = ChannelTransport.createLinkedPair()
runBlocking {
launch {
val session = server.createSession(serverTransport)
session.setRequestHandler<ListToolsRequest>(Method.Defined.ToolsList) { _, _ ->
listCalls.incrementAndGet()
ListToolsResult(
tools = listOf(
Tool(
name = tool,
description = "the $tool tool",
inputSchema = ToolSchema(properties = EmptyJsonObject, required = null),
),
),
ttlMs = 60_000,
cacheScope = scope,
)
}
}
launch { client.connect(clientTransport) }
}
}

/** A connected pair whose `tools/list` reports [ttlMs] as how long its listing stays fresh. */
private suspend fun connect(
ttlMs: Long,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,8 @@ import kotlin.coroutines.CoroutineContext
import kotlin.coroutines.cancellation.CancellationException
import kotlin.time.Clock
import kotlin.time.ExperimentalTime
import kotlin.uuid.ExperimentalUuidApi
import kotlin.uuid.Uuid

private val logger = KotlinLogging.logger {}

Expand All @@ -121,9 +123,11 @@ private val logger = KotlinLogging.logger {}
* @property responseCache Where to keep results a server marked reusable. Off by default;
* [InMemoryResponseCacheStore] caches for the lifetime of this client. Consulted only on the
* request-scoped lifecycle, the only one whose results carry caching directives.
* @property cachePartition The authorization context this client fetches under, which
* [CacheScope.Private] entries are confined to. Only meaningful for a store shared across
* principals; the default scopes such entries to this client instance.
* @property cachePartition The namespace this client files cached results under, public and
* [CacheScope.Private] alike. Clients configured with the same partition share entries, so it
* must name both the server and the authorization context, such as the server URL and the
* access token's subject. Empty, the default, confines entries to the current connection:
* neither another client nor this one after a reconnect is served them.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think Kdoc should be shortly
because it's not readable and I don't undestantand how to use this parameter

*/
public class ClientOptions(
public val capabilities: ClientCapabilities = ClientCapabilities(),
Expand Down Expand Up @@ -218,6 +222,8 @@ public open class Client(private val clientInfo: Implementation, options: Client
@OptIn(ExperimentalMcpApi::class)
private val cachePartition: String = options.cachePartition

private val connectionCachePartition: AtomicRef<String> = atomic(cachePartition)

private val roots = atomic(persistentMapOf<String, Root>())

private val _protocolVersion: AtomicRef<String?> = atomic(null)
Expand Down Expand Up @@ -284,9 +290,11 @@ public open class Client(private val clientInfo: Implementation, options: Client
* @param transport The transport to use for communication with the server.
* @throws IllegalStateException If the server's protocol version is not supported.
*/
@OptIn(ExperimentalMcpApi::class)
@OptIn(ExperimentalMcpApi::class, ExperimentalUuidApi::class)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

check experimental UUID in kotlin 2.3

override suspend fun connect(transport: Transport) {
super.connect(transport)
val partition = cachePartition.ifEmpty { Uuid.random().toString() }
connectionCachePartition.value = partition

try {
if (!negotiateRequestScoped(transport)) {
Expand Down Expand Up @@ -489,7 +497,7 @@ public open class Client(private val clientInfo: Implementation, options: Client
) {
return fetch()
}
val key = CacheKey(method = method, paramsKey = paramsKey, partition = cachePartition)
val key = CacheKey(method = method, paramsKey = paramsKey, partition = connectionCachePartition.value)
if (mode == CacheMode.Use) {
store.get(key)?.takeIf { Clock.System.now() < it.expiresAt }?.let {
@Suppress("UNCHECKED_CAST")
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -33,9 +33,9 @@ public enum class CacheMode {
* @property method the JSON-RPC method that produced the result
* @property paramsKey the part of the request that changes the result — a URI for `resources/read`,
* empty for the list methods, whose results depend on nothing else
* @property partition the authorization context the result was fetched under, supplied by the
* caller. A [CacheScope.Private] entry is never served across partitions; empty scopes it to this
* client instance.
* @property partition the namespace the result was filed under, naming one server seen under one
* authorization context: [ClientOptions.cachePartition], or a value unique to the connection that
* fetched it when that is empty. No entry, [CacheScope.Private] or not, is served across partitions.
*/
@ExperimentalMcpApi
public data class CacheKey(val method: String, val paramsKey: String = "", val partition: String = "")
Expand Down Expand Up @@ -80,7 +80,8 @@ public const val MAX_CACHE_TTL_MS: Long = 24L * 60 * 60 * 1000
/**
* A [ResponseCacheStore] holding entries in memory for the lifetime of this instance.
*
* Unbounded, holding one entry per method-and-params combination the client has issued.
* Unbounded: an entry stays until invalidated or cleared, even past its expiry or after the
* connection that filed it closes.
*/
@ExperimentalMcpApi
public class InMemoryResponseCacheStore : ResponseCacheStore {
Expand Down
Loading