From db72eb4c328baf6967eb26bc690172b8bee472b0 Mon Sep 17 00:00:00 2001 From: Ondra Pelech Date: Thu, 19 Nov 2026 15:38:23 +0100 Subject: [PATCH 01/31] feat(T8): expose request facts to handlers and gate logs by _meta logLevel Add RequestInfo (protocol version, client capabilities, client info, log level, progress token) and expose it as ServerContext.request. The handler builds it once per request and passes it to the transport's context factory, which replaces the bare progress-token argument. A modern (2026-07-28) request takes all facts from _meta. A legacy request gives only the protocol version (header or _meta) and the progress token, because the server keeps no state from initialize. StreamingServerContext.log now follows the per-request log level of a modern request: it sends notifications/message only at or above _meta logLevel, and none when the request sets no level, as the 2026-07-28 spec requires. Legacy requests keep receiving all messages. --- .../scala/chimp/protocol/Versioning.scala | 1 + .../server/ox/OxServerStdioTransport.scala | 8 +-- .../pekko/PekkoServerStdioTransport.scala | 10 +-- .../server/zio/ZioServerStdioTransport.scala | 8 +-- .../main/scala/chimp/server/McpHandler.scala | 43 ++++++++---- .../scala/chimp/server/ServerContext.scala | 46 ++++++++++--- .../SecuredServerHttpTransport.scala | 2 +- .../SecuredServerStreamingHttpTransport.scala | 5 +- .../transport/ServerStdioTransport.scala | 6 +- .../ServerStreamingHttpTransport.scala | 5 +- .../scala/chimp/server/McpHandlerSpec.scala | 66 +++++++++++++++++++ 11 files changed, 155 insertions(+), 45 deletions(-) diff --git a/core/src/main/scala/chimp/protocol/Versioning.scala b/core/src/main/scala/chimp/protocol/Versioning.scala index 9a5cacb4..280260e0 100644 --- a/core/src/main/scala/chimp/protocol/Versioning.scala +++ b/core/src/main/scala/chimp/protocol/Versioning.scala @@ -18,6 +18,7 @@ object ProtocolMeta: val ProtocolVersionKey: String = "io.modelcontextprotocol/protocolVersion" val ClientInfo: String = "io.modelcontextprotocol/clientInfo" val ClientCapabilities: String = "io.modelcontextprotocol/clientCapabilities" + val LogLevel: String = "io.modelcontextprotocol/logLevel" val ServerInfo: String = "io.modelcontextprotocol/serverInfo" val SubscriptionId: String = "io.modelcontextprotocol/subscriptionId" diff --git a/server-streaming/server-ox/src/main/scala/chimp/server/ox/OxServerStdioTransport.scala b/server-streaming/server-ox/src/main/scala/chimp/server/ox/OxServerStdioTransport.scala index b52e692c..1492d751 100644 --- a/server-streaming/server-ox/src/main/scala/chimp/server/ox/OxServerStdioTransport.scala +++ b/server-streaming/server-ox/src/main/scala/chimp/server/ox/OxServerStdioTransport.scala @@ -1,8 +1,8 @@ package chimp.server.ox -import chimp.protocol.{JSONRPCMessage, ProgressToken} +import chimp.protocol.JSONRPCMessage import chimp.server.transport.ServerStreamingStdioTransport -import chimp.server.{McpHandler, OutboundSink, SinkStreamingServerContext, StreamingMcpServer, StreamingServerContext} +import chimp.server.{McpHandler, OutboundSink, RequestInfo, SinkStreamingServerContext, StreamingMcpServer, StreamingServerContext} import chimp.transport.{StdioFraming, StdioLineReader} import io.circe.syntax.* import io.circe.{parser, Json} @@ -39,8 +39,8 @@ final class OxServerStdioTransport( val sink = new OutboundSink[Identity]: def send(message: JSONRPCMessage): Unit = outbound.send(message.asJson.deepDropNullValues) - val makeContext: Option[ProgressToken] => StreamingServerContext[Identity] = - token => SinkStreamingServerContext(sink, token) + val makeContext: RequestInfo => StreamingServerContext[Identity] = + info => SinkStreamingServerContext(sink, info) reader.lines .filter(_.nonEmpty) diff --git a/server-streaming/server-pekko/src/main/scala/chimp/server/pekko/PekkoServerStdioTransport.scala b/server-streaming/server-pekko/src/main/scala/chimp/server/pekko/PekkoServerStdioTransport.scala index ccc840f1..d181bf86 100644 --- a/server-streaming/server-pekko/src/main/scala/chimp/server/pekko/PekkoServerStdioTransport.scala +++ b/server-streaming/server-pekko/src/main/scala/chimp/server/pekko/PekkoServerStdioTransport.scala @@ -1,8 +1,8 @@ package chimp.server.pekko -import chimp.protocol.{JSONRPCMessage, ProgressToken} +import chimp.protocol.JSONRPCMessage import chimp.server.transport.ServerStreamingStdioTransport -import chimp.server.{McpHandler, OutboundSink, SinkStreamingServerContext, StreamingMcpServer, StreamingServerContext} +import chimp.server.{McpHandler, OutboundSink, RequestInfo, SinkStreamingServerContext, StreamingMcpServer, StreamingServerContext} import chimp.transport.{McpLineTooLongException, StdioFraming} import io.circe.syntax.* import io.circe.{parser, Json} @@ -39,8 +39,8 @@ final class PekkoServerStdioTransport( val sink = new OutboundSink[Future]: def send(message: JSONRPCMessage): Future[Unit] = PekkoOutbound.offer(outbound, message.asJson.deepDropNullValues) - val makeContext: Option[ProgressToken] => StreamingServerContext[Future] = - token => SinkStreamingServerContext(sink, token) + val makeContext: RequestInfo => StreamingServerContext[Future] = + info => SinkStreamingServerContext(sink, info) val reading = StreamConverters .fromInputStream(() => in) @@ -57,7 +57,7 @@ final class PekkoServerStdioTransport( private def handleLine( handler: McpHandler[Future, StreamingServerContext[Future]], - makeContext: Option[ProgressToken] => StreamingServerContext[Future], + makeContext: RequestInfo => StreamingServerContext[Future], outbound: SourceQueueWithComplete[Json], line: String ): Future[Unit] = diff --git a/server-streaming/server-zio/src/main/scala/chimp/server/zio/ZioServerStdioTransport.scala b/server-streaming/server-zio/src/main/scala/chimp/server/zio/ZioServerStdioTransport.scala index dc3710ba..0c7cbefe 100644 --- a/server-streaming/server-zio/src/main/scala/chimp/server/zio/ZioServerStdioTransport.scala +++ b/server-streaming/server-zio/src/main/scala/chimp/server/zio/ZioServerStdioTransport.scala @@ -1,7 +1,7 @@ package chimp.server.zio -import chimp.protocol.{JSONRPCMessage, ProgressToken} -import chimp.server.{McpHandler, OutboundSink, SinkStreamingServerContext, StreamingMcpServer, StreamingServerContext} +import chimp.protocol.JSONRPCMessage +import chimp.server.{McpHandler, OutboundSink, RequestInfo, SinkStreamingServerContext, StreamingMcpServer, StreamingServerContext} import chimp.server.transport.ServerStreamingStdioTransport import chimp.transport.{StdioFraming, StdioLineReader} import io.circe.syntax.* @@ -36,8 +36,8 @@ final class ZioServerStdioTransport( val sink = new OutboundSink[Task]: def send(message: JSONRPCMessage): Task[Unit] = writeLine(message.asJson.deepDropNullValues) - val makeContext: Option[ProgressToken] => StreamingServerContext[Task] = - token => SinkStreamingServerContext(sink, token) + val makeContext: RequestInfo => StreamingServerContext[Task] = + info => SinkStreamingServerContext(sink, info) def loop: Task[Unit] = ZIO diff --git a/server/src/main/scala/chimp/server/McpHandler.scala b/server/src/main/scala/chimp/server/McpHandler.scala index 38b066dc..ebcdf93a 100644 --- a/server/src/main/scala/chimp/server/McpHandler.scala +++ b/server/src/main/scala/chimp/server/McpHandler.scala @@ -63,15 +63,15 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD ) ) - def handleJsonRpc(request: Json, headers: Seq[Header], makeContext: Option[ProgressToken] => C)(using MonadError[F]): F[McpResponse] = + def handleJsonRpc(request: Json, headers: Seq[Header], makeContext: RequestInfo => C)(using MonadError[F]): F[McpResponse] = doHandleJsonRpc(request, headers, makeContext).map: response => logger.debug(s"Request: $request, response: ${response.statusCode}, body: ${response.body.getOrElse(Json.Null)}") response.withNullsDroppedDeep def handleJsonRpc(request: Json, headers: Seq[Header])(using m: MonadError[F], ev: ServerContext[F] <:< C): F[McpResponse] = - handleJsonRpc(request, headers, _ => ev(ServerContext.noop[F])) + handleJsonRpc(request, headers, info => ev(ServerContext[F](info))) - private def doHandleJsonRpc(request: Json, headers: Seq[Header], makeContext: Option[ProgressToken] => C)(using + private def doHandleJsonRpc(request: Json, headers: Seq[Header], makeContext: RequestInfo => C)(using MonadError[F] ): F[McpResponse] = request.as[JSONRPCMessage] match @@ -80,7 +80,10 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD case Right(JSONRPCMessage.Request(_, method, params: Option[Json], id)) => requestRejection(method, params, headers, id) match case Some(rejection) => rejection.unit - case None => dispatch(method, params, id, headers, makeContext, isModernRequest(method, params, headers)) + case None => + val isModern = isModernRequest(method, params, headers) + val info = requestInfo(params, headers, isModern) + dispatch(method, params, id, headers, () => makeContext(info), isModern) case Right(notification: JSONRPCMessage.Notification) => logger.debug(s"Received notification: ${notification.method}") McpResponse.EmptyAcceptResponse.unit @@ -93,7 +96,7 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD params: Option[Json], id: RequestId, headers: Seq[Header], - makeContext: Option[ProgressToken] => C, + makeContext: () => C, isModern: Boolean )(using MonadError[F]): F[McpResponse] = def wrap(cacheHints: Option[CacheHints])(message: JSONRPCMessage): JSONRPCMessage = message match @@ -180,6 +183,23 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD val metaIsModern = metaVersion.exists(version => ProtocolVersion.from(version).forall(_.isModern)) method != "server/discover" && (metaIsModern || headerVersion.flatMap(ProtocolVersion.from).exists(_.isModern)) + /** The facts a handler can read about the request; see [[RequestInfo]]. */ + private def requestInfo(params: Option[Json], headers: Seq[Header], isModern: Boolean): RequestInfo = + val meta = params.flatMap(_.hcursor.downField("_meta").focus).map(_.hcursor) + def fromMeta[A: Decoder](key: String): Option[A] = meta.flatMap(_.get[A](key).toOption) + val headerVersion = headers.collectFirst { case h if h.name.equalsIgnoreCase(ProtocolMeta.ProtocolVersionHeader) => h.value.trim } + val progressToken = fromMeta[ProgressToken]("progressToken") + val protocolVersion = fromMeta[String](ProtocolMeta.ProtocolVersionKey).orElse(headerVersion).flatMap(ProtocolVersion.from) + if isModern then + RequestInfo( + protocolVersion = protocolVersion, + clientCapabilities = fromMeta[ClientCapabilities](ProtocolMeta.ClientCapabilities), + clientInfo = fromMeta[Implementation](ProtocolMeta.ClientInfo), + logLevel = fromMeta[LoggingLevel](ProtocolMeta.LogLevel), + progressToken = progressToken + ) + else RequestInfo(protocolVersion = protocolVersion, progressToken = progressToken) + /** The rejection to send for an invalid request, or `None` if it may be dispatched. Runs no tool logic, so a transport can call it before * deciding how to respond (a modern validation error is a plain-JSON HTTP error, not an SSE stream). */ @@ -289,19 +309,18 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD private def handleDiscover(id: RequestId): JSONRPCMessage.Response = JSONRPCMessage.Response(id = id, result = discoverResult.asJson) - private def handleToolsCall(params: Option[Json], id: RequestId, headers: Seq[Header], makeContext: Option[ProgressToken] => C)(using + private def handleToolsCall(params: Option[Json], id: RequestId, headers: Seq[Header], makeContext: () => C)(using MonadError[F] ): F[JSONRPCMessage] = val name = params.flatMap(_.hcursor.downField("name").as[String].toOption) val arguments = params.flatMap(_.hcursor.downField("arguments").focus).getOrElse(Json.obj()) - val progressToken = params.flatMap(_.hcursor.downField("_meta").downField("progressToken").as[ProgressToken].toOption) name match case Some(name) => toolsByName.get(name) match case Some(tool) => tool.inputDecoder.decodeJson(arguments) match case Right(input) => - val context = makeContext(progressToken) + val context = makeContext() tool .logic(input, context, headers) .map: result => @@ -335,10 +354,10 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD params: Option[Json], id: RequestId, headers: Seq[Header], - makeContext: Option[ProgressToken] => C + makeContext: () => C )(using MonadError[F]): F[JSONRPCMessage] = decodeParams[ReadResourceParams](params, id): params => - val context = makeContext(None) + val context = makeContext() resourcesByUri.get(params.uri) match case Some(resource) => resource.read(context, headers).map(resourceReadResponse(id, params.uri)) case None => @@ -383,13 +402,13 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD params: Option[Json], id: RequestId, headers: Seq[Header], - makeContext: Option[ProgressToken] => C + makeContext: () => C )(using MonadError[F]): F[JSONRPCMessage] = decodeParams[GetPromptParams](params, id): params => promptsByName.get(params.name) match case Some(prompt) => prompt - .logic(params.arguments.getOrElse(Map.empty), makeContext(None), headers) + .logic(params.arguments.getOrElse(Map.empty), makeContext(), headers) .map(promptResult => JSONRPCMessage.Response(id = id, result = promptResult.asJson)) case None => protocolError(id, JSONRPCErrorCodes.InvalidParams.code, s"Unknown prompt: ${params.name}").unit diff --git a/server/src/main/scala/chimp/server/ServerContext.scala b/server/src/main/scala/chimp/server/ServerContext.scala index ebcfa603..3a73c975 100644 --- a/server/src/main/scala/chimp/server/ServerContext.scala +++ b/server/src/main/scala/chimp/server/ServerContext.scala @@ -5,28 +5,52 @@ import io.circe.Json import io.circe.syntax.* import sttp.monad.MonadError -trait ServerContext[F[_]] +/** What a request tells about itself. A modern (2026-07-28+) request carries all of it in `_meta`. A legacy request gives only the protocol + * version (from the `MCP-Protocol-Version` header or `_meta`) and the progress token; the server keeps no state from `initialize`. + */ +final case class RequestInfo( + protocolVersion: Option[ProtocolVersion] = None, + clientCapabilities: Option[ClientCapabilities] = None, + clientInfo: Option[Implementation] = None, + logLevel: Option[LoggingLevel] = None, + progressToken: Option[ProgressToken] = None +): + /** A modern request gets `notifications/message` only at or above its `logLevel`, and none without one. A legacy request gets all. */ + private[server] def allowsLog(level: LoggingLevel): Boolean = + if protocolVersion.exists(_.isModern) then logLevel.exists(minimum => level.ordinal >= minimum.ordinal) else true + +object RequestInfo: + val empty: RequestInfo = RequestInfo() + +trait ServerContext[F[_]]: + def request: RequestInfo object ServerContext: - def noop[F[_]]: ServerContext[F] = new ServerContext[F] {} + def noop[F[_]]: ServerContext[F] = apply(RequestInfo.empty) + + private[server] def apply[F[_]](info: RequestInfo): ServerContext[F] = new ServerContext[F]: + def request: RequestInfo = info /** A context which also gives the principal that the security logic of a [[SecuredMcpServer]] made from the request. */ trait SecuredServerContext[F[_], +P] extends ServerContext[F]: def principal: P object SecuredServerContext: - def apply[F[_], P](value: P): SecuredServerContext[F, P] = new SecuredServerContext[F, P]: + def apply[F[_], P](value: P, info: RequestInfo = RequestInfo.empty): SecuredServerContext[F, P] = new SecuredServerContext[F, P]: def principal: P = value + def request: RequestInfo = info trait StreamingServerContext[F[_]] extends ServerContext[F]: def reportProgress(progress: Double, total: Option[Double] = None, message: Option[String] = None): F[Unit] + + /** Sends `notifications/message`. For a modern request it sends only at or above the request's `logLevel`, and nothing without one. */ def log(level: LoggingLevel, data: Json, logger: Option[String] = None): F[Unit] -private[server] final class SinkStreamingServerContext[F[_]](sink: OutboundSink[F], progressToken: Option[ProgressToken])(using +private[server] final class SinkStreamingServerContext[F[_]](sink: OutboundSink[F], val request: RequestInfo)(using m: MonadError[F] ) extends StreamingServerContext[F]: def reportProgress(progress: Double, total: Option[Double] = None, message: Option[String] = None): F[Unit] = - progressToken match + request.progressToken match case Some(token) => sink.send( JSONRPCMessage.Notification( @@ -37,9 +61,11 @@ private[server] final class SinkStreamingServerContext[F[_]](sink: OutboundSink[ case None => m.unit(()) def log(level: LoggingLevel, data: Json, logger: Option[String] = None): F[Unit] = - sink.send( - JSONRPCMessage.Notification(method = "notifications/message", params = Some(LoggingMessageParams(level, data, logger).asJson)) - ) + if request.allowsLog(level) then + sink.send( + JSONRPCMessage.Notification(method = "notifications/message", params = Some(LoggingMessageParams(level, data, logger).asJson)) + ) + else m.unit(()) /** A context which gives both the principal that the security logic of a [[SecuredMcpServer]] made from the request, and the streaming * capabilities of a [[StreamingServerContext]]. @@ -48,11 +74,11 @@ trait SecuredStreamingServerContext[F[_], +P] extends SecuredServerContext[F, P] private[server] final class SinkSecuredStreamingServerContext[F[_], P]( sink: OutboundSink[F], - progressToken: Option[ProgressToken], + val request: RequestInfo, val principal: P )(using MonadError[F]) extends SecuredStreamingServerContext[F, P]: - private val delegate = SinkStreamingServerContext[F](sink, progressToken) + private val delegate = SinkStreamingServerContext[F](sink, request) def reportProgress(progress: Double, total: Option[Double] = None, message: Option[String] = None): F[Unit] = delegate.reportProgress(progress, total, message) def log(level: LoggingLevel, data: Json, logger: Option[String] = None): F[Unit] = delegate.log(level, data, logger) diff --git a/server/src/main/scala/chimp/server/transport/SecuredServerHttpTransport.scala b/server/src/main/scala/chimp/server/transport/SecuredServerHttpTransport.scala index ebc452f9..a317b178 100644 --- a/server/src/main/scala/chimp/server/transport/SecuredServerHttpTransport.scala +++ b/server/src/main/scala/chimp/server/transport/SecuredServerHttpTransport.scala @@ -35,7 +35,7 @@ final case class SecuredServerHttpTransport[F[_], S, E, P](path: List[String]): val (headers, json) = input given MonadError[F] = me respondToJsonRpc(server.originCheck, headers) { - handler.handleJsonRpc(json, headers, _ => SecuredServerContext[F, P](principal)) + handler.handleJsonRpc(json, headers, info => SecuredServerContext[F, P](principal, info)) }.map(Right(_)) } ) diff --git a/server/src/main/scala/chimp/server/transport/SecuredServerStreamingHttpTransport.scala b/server/src/main/scala/chimp/server/transport/SecuredServerStreamingHttpTransport.scala index 5ba0d740..16d0df5c 100644 --- a/server/src/main/scala/chimp/server/transport/SecuredServerStreamingHttpTransport.scala +++ b/server/src/main/scala/chimp/server/transport/SecuredServerStreamingHttpTransport.scala @@ -1,6 +1,5 @@ package chimp.server.transport -import chimp.protocol.ProgressToken import chimp.server.* import io.circe.Json import sttp.model.Header @@ -46,8 +45,8 @@ final case class SecuredServerStreamingHttpTransport[F[_], Caps, S, E, P]( val (headers, json) = input given MonadError[F] = me respondWithEventStream(server.originCheck, headers, backend, handler.validateRequest(json, headers)) { sink => - val makeContext: Option[ProgressToken] => SecuredStreamingServerContext[F, P] = - token => SinkSecuredStreamingServerContext(sink, token, principal) + val makeContext: RequestInfo => SecuredStreamingServerContext[F, P] = + info => SinkSecuredStreamingServerContext(sink, info, principal) handler.handleJsonRpc(json, headers, makeContext).map(_.body) }.map(_.left.map(Right(_))) } diff --git a/server/src/main/scala/chimp/server/transport/ServerStdioTransport.scala b/server/src/main/scala/chimp/server/transport/ServerStdioTransport.scala index 619b91d2..cd4da85c 100644 --- a/server/src/main/scala/chimp/server/transport/ServerStdioTransport.scala +++ b/server/src/main/scala/chimp/server/transport/ServerStdioTransport.scala @@ -1,6 +1,6 @@ package chimp.server.transport -import chimp.protocol.{JSONRPCMessage, ProgressToken} +import chimp.protocol.JSONRPCMessage import chimp.server.* import chimp.transport.{StdioFraming, StdioLineReader} import io.circe.parser @@ -49,8 +49,8 @@ final class ServerStdioTransport( val sink = new OutboundSink[Identity]: def send(message: JSONRPCMessage): Identity[Unit] = writeLine(message.asJson.deepDropNullValues) - val makeContext: Option[ProgressToken] => StreamingServerContext[Identity] = - token => SinkStreamingServerContext(sink, token) + val makeContext: RequestInfo => StreamingServerContext[Identity] = + info => SinkStreamingServerContext(sink, info) reader.lines .filter(_.nonEmpty) diff --git a/server/src/main/scala/chimp/server/transport/ServerStreamingHttpTransport.scala b/server/src/main/scala/chimp/server/transport/ServerStreamingHttpTransport.scala index d6529d44..cadf6428 100644 --- a/server/src/main/scala/chimp/server/transport/ServerStreamingHttpTransport.scala +++ b/server/src/main/scala/chimp/server/transport/ServerStreamingHttpTransport.scala @@ -1,6 +1,5 @@ package chimp.server.transport -import chimp.protocol.ProgressToken import chimp.server.* import io.circe.Json import sttp.capabilities.Streams @@ -45,8 +44,8 @@ abstract class ServerStreamingHttpTransport[F[_], Caps](path: List[String]) exte val (headers, json) = input given MonadError[F] = me respondWithEventStream(server.originCheck, headers, this, handler.validateRequest(json, headers)) { sink => - val makeContext: Option[ProgressToken] => StreamingServerContext[F] = - token => SinkStreamingServerContext(sink, token) + val makeContext: RequestInfo => StreamingServerContext[F] = + info => SinkStreamingServerContext(sink, info) handler.handleJsonRpc(json, headers, makeContext).map(_.body) } } diff --git a/server/src/test/scala/chimp/server/McpHandlerSpec.scala b/server/src/test/scala/chimp/server/McpHandlerSpec.scala index 5770649d..459a8137 100644 --- a/server/src/test/scala/chimp/server/McpHandlerSpec.scala +++ b/server/src/test/scala/chimp/server/McpHandlerSpec.scala @@ -697,3 +697,69 @@ class McpHandlerSpec extends AnyFlatSpec with Matchers: featureResult("resources/subscribe", Some(params), "n1") match case Error(_, _, error) => error.code shouldBe MethodNotFound.code case _ => fail("Expected Error") + + private val seenRequest = new java.util.concurrent.atomic.AtomicReference(Option.empty[RequestInfo]) + + private val loggingTool = tool("logs") + .input[EchoInput] + .streamingServerLogic[Identity]: (_, ctx, _) => + seenRequest.set(Some(ctx.request)) + LoggingLevel.values.foreach(level => ctx.log(level, Json.fromString(level.toString))) + ToolResult.text("logged") + + private val streamingHandler = + McpHandler[Identity, StreamingServerContext[Identity]](McpServer[Identity]().streaming.addStreamingTool(loggingTool)) + + private def callLoggingTool(meta: Json, headers: Seq[Header] = Seq.empty): (McpResponse, List[LoggingLevel]) = + val sent = scala.collection.mutable.ListBuffer.empty[JSONRPCMessage] + val sink = new OutboundSink[Identity]: + def send(message: JSONRPCMessage): Unit = sent += message + val params = Json.obj("name" -> Json.fromString("logs"), "arguments" -> Json.obj("message" -> Json.fromString("hi")), "_meta" -> meta) + val req: JSONRPCMessage = Request(method = "tools/call", params = Some(params), id = RequestId("log")) + val response = streamingHandler.handleJsonRpc(req.asJson, headers, info => SinkStreamingServerContext(sink, info)) + val levels = sent.toList.collect { case Notification(_, "notifications/message", Some(p)) => + p.as[LoggingMessageParams].toOption.get.level + } + (response, levels) + + private def modernToolMeta(extra: (String, Json)*): Json = + Json.obj( + (ProtocolMeta.ProtocolVersionKey -> Json.fromString("2026-07-28")) +: + (ProtocolMeta.ClientCapabilities -> Json.obj("sampling" -> Json.obj())) +: + extra* + ) + + it should "give a handler the facts of a modern request" in: + val clientInfo = Json.obj("name" -> Json.fromString("cli"), "version" -> Json.fromString("1.2")) + val meta = modernToolMeta( + ProtocolMeta.ClientInfo -> clientInfo, + ProtocolMeta.LogLevel -> Json.fromString("warning"), + "progressToken" -> Json.fromString("p1") + ) + callLoggingTool(meta)._1.statusCode shouldBe sttp.model.StatusCode.Ok + seenRequest.get() shouldBe Some( + RequestInfo( + protocolVersion = Some(ProtocolVersion.V2026_07_28), + clientCapabilities = Some(ClientCapabilities(sampling = Some(Json.obj()))), + clientInfo = Some(Implementation("cli", "1.2")), + logLevel = Some(LoggingLevel.Warning), + progressToken = Some(ProgressToken("p1")) + ) + ) + + it should "give a handler only the protocol version and progress token of a legacy request" in: + val meta = Json.obj("progressToken" -> Json.fromString("p2"), ProtocolMeta.LogLevel -> Json.fromString("debug")) + callLoggingTool(meta, Seq(Header(ProtocolMeta.ProtocolVersionHeader, "2025-11-25")))._1.statusCode shouldBe sttp.model.StatusCode.Ok + seenRequest.get() shouldBe Some( + RequestInfo(protocolVersion = Some(ProtocolVersion.V2025_11_25), progressToken = Some(ProgressToken("p2"))) + ) + + it should "send no log messages for a modern request without a logLevel" in: + callLoggingTool(modernToolMeta())._2 shouldBe Nil + + it should "send only log messages at or above the logLevel of a modern request" in: + callLoggingTool(modernToolMeta(ProtocolMeta.LogLevel -> Json.fromString("error")))._2 shouldBe + List(LoggingLevel.Error, LoggingLevel.Critical, LoggingLevel.Alert, LoggingLevel.Emergency) + + it should "send all log messages for a legacy request" in: + callLoggingTool(Json.obj())._2 shouldBe LoggingLevel.values.toList From 075616384e1ec9bacda75d1bbc7aff759c0b2520 Mon Sep 17 00:00:00 2001 From: Ondra Pelech Date: Thu, 19 Nov 2026 15:39:24 +0100 Subject: [PATCH 02/31] feat(T8): let plain tool, prompt and resource logic read the server context Add serverLogicWithContext to tools, prompts, resources and resource templates. The logic receives the ServerContext, so it can read the request facts (protocol version, client capabilities, client info, log level) without a streaming server. Until now only streaming tools got a context. --- .../src/main/scala/chimp/server/Prompt.scala | 6 ++++ .../main/scala/chimp/server/Resource.scala | 12 +++++++ server/src/main/scala/chimp/server/Tool.scala | 4 +++ .../scala/chimp/server/McpHandlerSpec.scala | 34 +++++++++++++++++++ 4 files changed, 56 insertions(+) diff --git a/server/src/main/scala/chimp/server/Prompt.scala b/server/src/main/scala/chimp/server/Prompt.scala index fa3264ca..5ad4eec0 100644 --- a/server/src/main/scala/chimp/server/Prompt.scala +++ b/server/src/main/scala/chimp/server/Prompt.scala @@ -38,6 +38,12 @@ case class PartialPrompt( ): ServerPrompt[F, ServerContext[F]] = ServerPrompt(definition, (args, _, headers) => logic(args, headers)) + /** Attaches effectful logic, with access to the [[ServerContext]], which gives the facts of the request. */ + def serverLogicWithContext[F[_]]( + logic: (Map[String, String], ServerContext[F], Seq[Header]) => F[GetPromptResult] + ): ServerPrompt[F, ServerContext[F]] = + ServerPrompt(definition, logic) + /** Attaches effectful logic, with access to the principal; usable only on a [[SecuredMcpServer]]. */ def securedServerLogic[F[_], P]( logic: (Map[String, String], P, Seq[Header]) => F[GetPromptResult] diff --git a/server/src/main/scala/chimp/server/Resource.scala b/server/src/main/scala/chimp/server/Resource.scala index ad645a61..57d001b9 100644 --- a/server/src/main/scala/chimp/server/Resource.scala +++ b/server/src/main/scala/chimp/server/Resource.scala @@ -54,6 +54,12 @@ case class PartialResource( ): ServerResource[F, ServerContext[F]] = ServerResource(definition, (_, headers) => logic(headers)) + /** Attaches effectful logic, with access to the [[ServerContext]], which gives the facts of the request. */ + def serverLogicWithContext[F[_]]( + logic: (ServerContext[F], Seq[Header]) => F[Either[ResourceError, List[ResourceContents]]] + ): ServerResource[F, ServerContext[F]] = + ServerResource(definition, logic) + /** Attaches effectful logic, with access to the principal; usable only on a [[SecuredMcpServer]]. */ def securedServerLogic[F[_], P]( logic: (P, Seq[Header]) => F[Either[ResourceError, List[ResourceContents]]] @@ -120,6 +126,12 @@ case class PartialResourceTemplate( ): ServerResourceTemplate[F, ServerContext[F]] = ServerResourceTemplate(definition, UriTemplate.compile(uriTemplate), (vars, uri, _, headers) => logic(vars, uri, headers)) + /** Attaches effectful logic reading a matched URI, with access to the [[ServerContext]], which gives the facts of the request. */ + def serverLogicWithContext[F[_]]( + logic: (Map[String, String], String, ServerContext[F], Seq[Header]) => F[Either[ResourceError, List[ResourceContents]]] + ): ServerResourceTemplate[F, ServerContext[F]] = + ServerResourceTemplate(definition, UriTemplate.compile(uriTemplate), logic) + /** Attaches effectful logic, with access to the principal; usable only on a [[SecuredMcpServer]]. */ def securedServerLogic[F[_], P]( logic: (Map[String, String], String, P, Seq[Header]) => F[Either[ResourceError, List[ResourceContents]]] diff --git a/server/src/main/scala/chimp/server/Tool.scala b/server/src/main/scala/chimp/server/Tool.scala index e6aecd3b..8f3937e9 100644 --- a/server/src/main/scala/chimp/server/Tool.scala +++ b/server/src/main/scala/chimp/server/Tool.scala @@ -103,6 +103,10 @@ case class Tool[I, O]( def serverLogic[F[_]](logic: (I, Seq[Header]) => F[ToolResult[O]]): ServerTool[I, O, F, ServerContext[F]] = ServerTool(name, description, inputSchema, inputDecoder, outputSchema, annotations, (input, _, headers) => logic(input, headers)) + /** Attaches effectful logic, with access to the [[ServerContext]], which gives the facts of the request. */ + def serverLogicWithContext[F[_]](logic: (I, ServerContext[F], Seq[Header]) => F[ToolResult[O]]): ServerTool[I, O, F, ServerContext[F]] = + ServerTool(name, description, inputSchema, inputDecoder, outputSchema, annotations, logic) + /** Attaches effectful logic, with access to the principal; usable only on a [[SecuredMcpServer]]. */ def securedServerLogic[F[_], P](logic: (I, P, Seq[Header]) => F[ToolResult[O]]): ServerTool[I, O, F, SecuredServerContext[F, P]] = ServerTool( diff --git a/server/src/test/scala/chimp/server/McpHandlerSpec.scala b/server/src/test/scala/chimp/server/McpHandlerSpec.scala index 459a8137..34a26e1b 100644 --- a/server/src/test/scala/chimp/server/McpHandlerSpec.scala +++ b/server/src/test/scala/chimp/server/McpHandlerSpec.scala @@ -763,3 +763,37 @@ class McpHandlerSpec extends AnyFlatSpec with Matchers: it should "send all log messages for a legacy request" in: callLoggingTool(Json.obj())._2 shouldBe LoggingLevel.values.toList + + private def describe(ctx: ServerContext[Identity]): String = + s"${ctx.request.protocolVersion.map(_.name).getOrElse("-")} ${ctx.request.clientInfo.map(_.name).getOrElse("-")}" + + private val contextServer = McpServer[Identity]() + .addTool(tool("ctx").input[EchoInput].serverLogicWithContext[Identity]((_, ctx, _) => ToolResult.text(describe(ctx)))) + .addPrompt( + prompt("ctx").serverLogicWithContext[Identity]((_, ctx, _) => + GetPromptResult(messages = List(PromptMessage(Role.User, ToolContent.Text(text = describe(ctx))))) + ) + ) + .addResource( + resource("test://ctx").serverLogicWithContext[Identity]((ctx, _) => Right(List(ResourceContents.Text("test://ctx", describe(ctx))))) + ) + .addResourceTemplate( + resourceTemplate("test://ctx/{id}") + .serverLogicWithContext[Identity]((_, uri, ctx, _) => Right(List(ResourceContents.Text(uri, describe(ctx))))) + ) + + it should "give the request facts to tool, prompt, resource and resource template logic" in: + val meta = Json.obj( + "_meta" -> modernToolMeta(ProtocolMeta.ClientInfo -> Json.obj("name" -> Json.fromString("cli"), "version" -> Json.fromString("1"))) + ) + val calls = List( + "tools/call" -> Json.obj("name" -> Json.fromString("ctx"), "arguments" -> Json.obj("message" -> Json.fromString("hi"))), + "prompts/get" -> Json.obj("name" -> Json.fromString("ctx")), + "resources/read" -> Json.obj("uri" -> Json.fromString("test://ctx")), + "resources/read" -> Json.obj("uri" -> Json.fromString("test://ctx/1")) + ) + for (method, params) <- calls do + val req: JSONRPCMessage = Request(method = method, params = Some(params.deepMerge(meta)), id = RequestId("ctx")) + val body = extractJsonFromResponse(McpHandler(contextServer).handleJsonRpc(req.asJson, Seq.empty)) + withClue(s"$method $params"): + body.noSpaces should include("2026-07-28 cli") From 26b89cab923b87858277f0485c371ed4873525b7 Mon Sep 17 00:00:00 2001 From: Ondra Pelech Date: Thu, 19 Nov 2026 15:42:17 +0100 Subject: [PATCH 03/31] feat(T8): reject modern tool calls missing a required client capability A tool can now declare the client capabilities it needs with withRequiredClientCapabilities. When a modern (2026-07-28) tools/call targets such a tool and _meta clientCapabilities does not declare them, the request fails before any logic runs with -32021 MissingRequiredClientCapability, HTTP 400, and data.requiredCapabilities set to the tool's requirement, as the schema requires. The check runs in requestRejection, so a streaming transport answers with plain JSON and not an SSE stream. Capabilities are compared key by key, recursively for nested objects. Legacy requests carry no capabilities, so they are not checked. --- .../scala/chimp/protocol/Versioning.scala | 8 +++ .../main/scala/chimp/server/McpHandler.scala | 27 ++++++- server/src/main/scala/chimp/server/Tool.scala | 72 +++++++++++-------- .../scala/chimp/server/McpHandlerSpec.scala | 49 +++++++++++++ 4 files changed, 123 insertions(+), 33 deletions(-) diff --git a/core/src/main/scala/chimp/protocol/Versioning.scala b/core/src/main/scala/chimp/protocol/Versioning.scala index 280260e0..7600a3c6 100644 --- a/core/src/main/scala/chimp/protocol/Versioning.scala +++ b/core/src/main/scala/chimp/protocol/Versioning.scala @@ -30,6 +30,14 @@ object ProtocolMeta: data = Some(Json.obj("requested" -> requested.asJson, "supported" -> supported.asJson)) ) + /** A `MissingRequiredClientCapability` error (`-32021`) naming the capabilities the client must declare to make the request. */ + def missingClientCapabilityError(required: ClientCapabilities): JSONRPCErrorObject = + JSONRPCErrorObject( + code = JSONRPCErrorCodes.MissingRequiredClientCapability.code, + message = "Missing required client capability", + data = Some(Json.obj("requiredCapabilities" -> required.asJson.deepDropNullValues)) + ) + /** The type of a modern (2026-07-28+) result: `complete` for a finished result, `incomplete` for one that needs another round trip (MRTR * input-required). */ diff --git a/server/src/main/scala/chimp/server/McpHandler.scala b/server/src/main/scala/chimp/server/McpHandler.scala index ebcdf93a..86508012 100644 --- a/server/src/main/scala/chimp/server/McpHandler.scala +++ b/server/src/main/scala/chimp/server/McpHandler.scala @@ -251,10 +251,31 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD ) else if !modernMethods.contains(method) then Some(jsonError(id, StatusCode.NotFound, JSONRPCErrorCodes.MethodNotFound.code, s"Method not found: $method")) - else if headers.exists(_.name.equalsIgnoreCase("Host")) then + else // SEP-2243 standard request headers only apply over HTTP (identified by the Host header); stdio carries no such headers - headerValidationError(method, params, headers, id) - else None + val headerError = Option.when(headers.exists(_.name.equalsIgnoreCase("Host")))(headerValidationError(method, params, headers, id)) + headerError.flatten.orElse(missingCapabilityError(method, params, meta, id)) + + /** A `-32021` with HTTP 400 when `tools/call` names a tool whose required client capabilities the request's `_meta` does not declare. */ + private def missingCapabilityError(method: String, params: Option[Json], meta: Option[Json], id: RequestId): Option[McpResponse] = + val declared = meta.flatMap(_.hcursor.downField(ProtocolMeta.ClientCapabilities).focus).getOrElse(Json.obj()) + val required = Option + .when(method == "tools/call")(params.flatMap(_.hcursor.get[String]("name").toOption)) + .flatten + .flatMap(toolsByName.get) + .flatMap(_.requiredClientCapabilities) + required + .filterNot(capabilities => declares(declared, capabilities.asJson.deepDropNullValues)) + .map: capabilities => + val envelope: JSONRPCMessage = JSONRPCMessage.Error(id = id, error = ProtocolMeta.missingClientCapabilityError(capabilities)) + logger.debug(s"Modern request rejected (id=$id): missing client capabilities ${capabilities.asJson.noSpaces}") + McpResponse.JsonError(StatusCode.BadRequest, envelope.asJson) + + /** Whether `declared` has every key of `required`, recursively for nested objects. */ + private def declares(declared: Json, required: Json): Boolean = + required.asObject.forall(_.toList.forall { (key, value) => + declared.asObject.flatMap(_(key)).exists(declaredValue => value.asObject.forall(_ => declares(declaredValue, value))) + }) // SEP-2243: the body field that the `Mcp-Name` header must mirror, per method private val nameFields: Map[String, String] = Map("tools/call" -> "name", "prompts/get" -> "name", "resources/read" -> "uri") diff --git a/server/src/main/scala/chimp/server/Tool.scala b/server/src/main/scala/chimp/server/Tool.scala index 8f3937e9..ca68baef 100644 --- a/server/src/main/scala/chimp/server/Tool.scala +++ b/server/src/main/scala/chimp/server/Tool.scala @@ -1,6 +1,6 @@ package chimp.server -import chimp.protocol.{ResourceContents, ToolContent} +import chimp.protocol.{ClientCapabilities, ResourceContents, ToolContent} import io.circe.syntax.* import io.circe.{Decoder, Encoder, Json} import sttp.model.Header @@ -66,7 +66,8 @@ def tool(name: String): PartialTool = case class PartialTool( name: String, description: Option[String] = None, - annotations: Option[ToolAnnotations] = None + annotations: Option[ToolAnnotations] = None, + requiredClientCapabilities: Option[ClientCapabilities] = None ): def description(desc: String): PartialTool = copy(description = Some(desc)) @@ -74,13 +75,35 @@ case class PartialTool( def withAnnotations(ann: ToolAnnotations): PartialTool = copy(annotations = Some(ann)) + /** Declares the client capabilities a call needs. A modern (2026-07-28+) request whose `_meta` does not declare them fails with `-32021` + * (MissingRequiredClientCapability) before the logic runs. + */ + def withRequiredClientCapabilities(capabilities: ClientCapabilities): PartialTool = + copy(requiredClientCapabilities = Some(capabilities)) + /** Fixes the input type, deriving its JSON Schema and decoder from the given instances. */ def input[I: Schema: Decoder]: Tool[I, NoStructuredOutput] = - Tool[I, NoStructuredOutput](name, description, ToolSchema.Derived(summon[Schema[I]]), summon[Decoder[I]], None, annotations) + Tool[I, NoStructuredOutput]( + name, + description, + ToolSchema.Derived(summon[Schema[I]]), + summon[Decoder[I]], + None, + annotations, + requiredClientCapabilities + ) /** Fixes the input as raw JSON, validated against the given JSON Schema. */ def inputJson(schema: Json): Tool[Json, NoStructuredOutput] = - Tool[Json, NoStructuredOutput](name, description, ToolSchema.Raw(schema), summon[Decoder[Json]], None, annotations) + Tool[Json, NoStructuredOutput]( + name, + description, + ToolSchema.Raw(schema), + summon[Decoder[Json]], + None, + annotations, + requiredClientCapabilities + ) /** A tool with a known input type `I` and structured output type `O`, ready to be given its handling logic. */ case class Tool[I, O]( @@ -89,60 +112,45 @@ case class Tool[I, O]( inputSchema: ToolSchema, inputDecoder: Decoder[I], outputSchema: Option[ToolSchema], - annotations: Option[ToolAnnotations] + annotations: Option[ToolAnnotations], + requiredClientCapabilities: Option[ClientCapabilities] = None ): /** Fixes the structured output type, deriving its JSON Schema from the given instance. */ def output[O2: Schema]: Tool[I, O2] = - Tool[I, O2](name, description, inputSchema, inputDecoder, Some(ToolSchema.Derived(summon[Schema[O2]])), annotations) + copy(outputSchema = Some(ToolSchema.Derived(summon[Schema[O2]]))) /** Fixes the structured output as raw JSON, described by the given JSON Schema. */ def outputJson(schema: Json): Tool[I, Json] = - Tool[I, Json](name, description, inputSchema, inputDecoder, Some(ToolSchema.Raw(schema)), annotations) + copy(outputSchema = Some(ToolSchema.Raw(schema))) /** Attaches effectful logic, with access to the request headers. */ def serverLogic[F[_]](logic: (I, Seq[Header]) => F[ToolResult[O]]): ServerTool[I, O, F, ServerContext[F]] = - ServerTool(name, description, inputSchema, inputDecoder, outputSchema, annotations, (input, _, headers) => logic(input, headers)) + serverTool((input, _, headers) => logic(input, headers)) /** Attaches effectful logic, with access to the [[ServerContext]], which gives the facts of the request. */ def serverLogicWithContext[F[_]](logic: (I, ServerContext[F], Seq[Header]) => F[ToolResult[O]]): ServerTool[I, O, F, ServerContext[F]] = - ServerTool(name, description, inputSchema, inputDecoder, outputSchema, annotations, logic) + serverTool(logic) /** Attaches effectful logic, with access to the principal; usable only on a [[SecuredMcpServer]]. */ def securedServerLogic[F[_], P](logic: (I, P, Seq[Header]) => F[ToolResult[O]]): ServerTool[I, O, F, SecuredServerContext[F, P]] = - ServerTool( - name, - description, - inputSchema, - inputDecoder, - outputSchema, - annotations, - (input, context, headers) => logic(input, context.principal, headers) - ) + serverTool((input, context, headers) => logic(input, context.principal, headers)) /** Attaches effectful logic with access to the [[StreamingServerContext]]; usable only on a streaming server. */ def streamingServerLogic[F[_]]( logic: (I, StreamingServerContext[F], Seq[Header]) => F[ToolResult[O]] ): ServerTool[I, O, F, StreamingServerContext[F]] = - ServerTool(name, description, inputSchema, inputDecoder, outputSchema, annotations, logic) + serverTool(logic) /** Attaches effectful logic with access to the principal and the [[StreamingServerContext]]; usable only on a secured streaming server. */ def securedStreamingServerLogic[F[_], P]( logic: (I, P, StreamingServerContext[F], Seq[Header]) => F[ToolResult[O]] ): ServerTool[I, O, F, SecuredStreamingServerContext[F, P]] = - ServerTool( - name, - description, - inputSchema, - inputDecoder, - outputSchema, - annotations, - (input, context, headers) => logic(input, context.principal, context, headers) - ) + serverTool((input, context, headers) => logic(input, context.principal, context, headers)) /** Attaches synchronous logic that also receives the request headers. */ def handleWithHeaders(logic: (I, Seq[Header]) => ToolResult[O]): ServerTool[I, O, Identity, ServerContext[Identity]] = - ServerTool(name, description, inputSchema, inputDecoder, outputSchema, annotations, (i, _, headers) => logic(i, headers)) + serverTool((i, _, headers) => logic(i, headers)) /** Attaches synchronous logic over just the decoded input. */ def handle(logic: I => ToolResult[O]): ServerTool[I, O, Identity, ServerContext[Identity]] = @@ -152,6 +160,9 @@ case class Tool[I, O]( def handleSecured[P](logic: (I, P) => ToolResult[O]): ServerTool[I, O, Identity, SecuredServerContext[Identity, P]] = securedServerLogic[Identity, P]((i, principal, _) => logic(i, principal)) + private def serverTool[F[_], C <: ServerContext[F]](logic: (I, C, Seq[Header]) => F[ToolResult[O]]): ServerTool[I, O, F, C] = + ServerTool(name, description, inputSchema, inputDecoder, outputSchema, annotations, logic, requiredClientCapabilities) + /** A fully-defined tool: its metadata plus the logic handling a call, in effect `F` with context `C`. */ case class ServerTool[I, O, F[_], -C <: ServerContext[F]]( name: String, @@ -160,5 +171,6 @@ case class ServerTool[I, O, F[_], -C <: ServerContext[F]]( inputDecoder: Decoder[I], outputSchema: Option[ToolSchema], annotations: Option[ToolAnnotations], - logic: (I, C, Seq[Header]) => F[ToolResult[O]] + logic: (I, C, Seq[Header]) => F[ToolResult[O]], + requiredClientCapabilities: Option[ClientCapabilities] = None ) diff --git a/server/src/test/scala/chimp/server/McpHandlerSpec.scala b/server/src/test/scala/chimp/server/McpHandlerSpec.scala index 34a26e1b..736fc8f3 100644 --- a/server/src/test/scala/chimp/server/McpHandlerSpec.scala +++ b/server/src/test/scala/chimp/server/McpHandlerSpec.scala @@ -797,3 +797,52 @@ class McpHandlerSpec extends AnyFlatSpec with Matchers: val body = extractJsonFromResponse(McpHandler(contextServer).handleJsonRpc(req.asJson, Seq.empty)) withClue(s"$method $params"): body.noSpaces should include("2026-07-28 cli") + + private val samplingTool = tool("needs_sampling") + .withRequiredClientCapabilities(ClientCapabilities(sampling = Some(Json.obj()))) + .input[EchoInput] + .handle(in => ToolResult.text(in.message)) + + private val capabilityHandler = McpHandler(McpServer[Identity]().addTool(samplingTool)) + + private def samplingToolCall(meta: Json): Json = + val params = Json.obj("name" -> Json.fromString("needs_sampling"), "arguments" -> Json.obj("message" -> Json.fromString("hi"))) + val req: JSONRPCMessage = + Request(method = "tools/call", params = Some(params.deepMerge(Json.obj("_meta" -> meta))), id = RequestId("cap")) + req.asJson + + private def callSamplingTool(meta: Json): McpResponse = capabilityHandler.handleJsonRpc(samplingToolCall(meta), Seq.empty) + + it should "reject a modern call of a tool that needs an undeclared client capability with -32021 and HTTP 400" in: + val meta = Json.obj(ProtocolMeta.ProtocolVersionKey -> Json.fromString("2026-07-28"), ProtocolMeta.ClientCapabilities -> Json.obj()) + val response = callSamplingTool(meta) + response.statusCode shouldBe sttp.model.StatusCode.BadRequest + capabilityHandler.validateRequest(samplingToolCall(meta), Seq.empty).map(_.statusCode) shouldBe Some(sttp.model.StatusCode.BadRequest) + extractJsonFromResponse(response).as[JSONRPCMessage].getOrElse(fail("decode")) match + case Error(_, id, err) => + id shouldBe RequestId("cap") + err.code shouldBe MissingRequiredClientCapability.code + err.data.flatMap(_.hcursor.downField("requiredCapabilities").focus) shouldBe Some(Json.obj("sampling" -> Json.obj())) + case other => fail(s"Expected Error, got $other") + + it should "serve a modern call of a tool whose required client capabilities are declared" in: + callSamplingTool(modernToolMeta()).statusCode shouldBe sttp.model.StatusCode.Ok + + it should "serve a legacy call of a tool that needs a client capability" in: + callSamplingTool(Json.obj()).statusCode shouldBe sttp.model.StatusCode.Ok + + it should "check nested required client capabilities key by key" in: + val formTool = tool("needs_form") + .withRequiredClientCapabilities(ClientCapabilities(elicitation = Some(Json.obj("form" -> Json.obj())))) + .input[EchoInput] + .handle(in => ToolResult.text(in.message)) + val formHandler = McpHandler(McpServer[Identity]().addTool(formTool)) + def call(declared: Json): sttp.model.StatusCode = + val meta = Json.obj(ProtocolMeta.ProtocolVersionKey -> Json.fromString("2026-07-28"), ProtocolMeta.ClientCapabilities -> declared) + val params = + Json.obj("name" -> Json.fromString("needs_form"), "arguments" -> Json.obj("message" -> Json.fromString("hi")), "_meta" -> meta) + val req: JSONRPCMessage = Request(method = "tools/call", params = Some(params), id = RequestId("form")) + formHandler.handleJsonRpc(req.asJson, Seq.empty).statusCode + call(Json.obj("elicitation" -> Json.obj())) shouldBe sttp.model.StatusCode.BadRequest + call(Json.obj("elicitation" -> Json.obj("url" -> Json.obj()))) shouldBe sttp.model.StatusCode.BadRequest + call(Json.obj("elicitation" -> Json.obj("form" -> Json.obj(), "url" -> Json.obj()))) shouldBe sttp.model.StatusCode.Ok From 68199c5dd8532b034fa9328dfaec24028801f54d Mon Sep 17 00:00:00 2001 From: Ondra Pelech Date: Thu, 19 Nov 2026 15:47:23 +0100 Subject: [PATCH 04/31] fix(T8): accept JSON-RPC request ids beyond the Int range RequestId decoded numeric ids only as Int. A request with a larger id (for example a millisecond timestamp, which the conformance harness sends) failed to decode as a request and was taken for a notification, so the server answered with an empty response. RequestId now also holds a Long; small numbers still decode as Int, so existing ids compare equal. --- core/src/main/scala/chimp/protocol/Ids.scala | 9 +++++---- server/src/test/scala/chimp/server/McpHandlerSpec.scala | 6 ++++++ 2 files changed, 11 insertions(+), 4 deletions(-) diff --git a/core/src/main/scala/chimp/protocol/Ids.scala b/core/src/main/scala/chimp/protocol/Ids.scala index 13803dc9..77b476b1 100644 --- a/core/src/main/scala/chimp/protocol/Ids.scala +++ b/core/src/main/scala/chimp/protocol/Ids.scala @@ -2,15 +2,16 @@ package chimp.protocol import io.circe.{Codec, Decoder, Encoder, Json} -opaque type RequestId = String | Int +opaque type RequestId = String | Int | Long object RequestId: - def apply(value: String | Int): RequestId = value - def unapply(id: RequestId): Option[String | Int] = Some(id) + def apply(value: String | Int | Long): RequestId = value + def unapply(id: RequestId): Option[String | Int | Long] = Some(id) given encoder: Encoder[RequestId] = Encoder.instance: case s: String => Json.fromString(s) case i: Int => Json.fromInt(i) + case l: Long => Json.fromLong(l) given decoder: Decoder[RequestId] = Decoder.instance: c => - c.as[String].map(RequestId(_)).orElse(c.as[Int].map(RequestId(_))) + c.as[String].map(RequestId(_)).orElse(c.as[Int].map(RequestId(_))).orElse(c.as[Long].map(RequestId(_))) given codec: Codec[RequestId] = Codec.from(decoder, encoder) opaque type ProgressToken = String | Int diff --git a/server/src/test/scala/chimp/server/McpHandlerSpec.scala b/server/src/test/scala/chimp/server/McpHandlerSpec.scala index 736fc8f3..5aec5a43 100644 --- a/server/src/test/scala/chimp/server/McpHandlerSpec.scala +++ b/server/src/test/scala/chimp/server/McpHandlerSpec.scala @@ -846,3 +846,9 @@ class McpHandlerSpec extends AnyFlatSpec with Matchers: call(Json.obj("elicitation" -> Json.obj())) shouldBe sttp.model.StatusCode.BadRequest call(Json.obj("elicitation" -> Json.obj("url" -> Json.obj()))) shouldBe sttp.model.StatusCode.BadRequest call(Json.obj("elicitation" -> Json.obj("form" -> Json.obj(), "url" -> Json.obj()))) shouldBe sttp.model.StatusCode.Ok + + it should "serve a request whose numeric id is beyond the Int range and echo the id" in: + val json = parseJson("""{"jsonrpc":"2.0","id":1763561090000,"method":"tools/list"}""") + extractJsonFromResponse(handler.handleJsonRpc(json, Seq.empty)).hcursor.downField("id").focus shouldBe Some( + Json.fromLong(1763561090000L) + ) From 33eb72a9446f6312b3fbf170c488369a703354a5 Mon Sep 17 00:00:00 2001 From: Ondra Pelech Date: Thu, 19 Nov 2026 15:47:57 +0100 Subject: [PATCH 05/31] feat(T8): add test_missing_capability and test_logging_tool conformance fixtures The server-stateless scenario (2026-07-28) calls test_missing_capability without declaring sampling and expects -32021 with HTTP 400, and calls test_logging_tool without a logLevel and expects no notifications/message. test_missing_capability declares sampling as a required client capability; test_logging_tool logs once at every level and relies on the per-request log gate. Both checks now pass. The scenario stays in the baseline, because it also covers subscriptions/listen and other later work. --- .../scala/chimp/conformance/server/Main.scala | 27 +++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/server-conformance/src/main/scala/chimp/conformance/server/Main.scala b/server-conformance/src/main/scala/chimp/conformance/server/Main.scala index 848ed73b..f287803f 100644 --- a/server-conformance/src/main/scala/chimp/conformance/server/Main.scala +++ b/server-conformance/src/main/scala/chimp/conformance/server/Main.scala @@ -132,6 +132,19 @@ object Main: ctx.log(LoggingLevel.Info, Json.fromString("Tool execution completed")) ToolResult.text("logging complete") + private val missingCapabilityTool = tool("test_missing_capability") + .description("Needs the sampling client capability") + .withRequiredClientCapabilities(ClientCapabilities(sampling = Some(Json.obj()))) + .input[NoInput] + .handle(_ => ToolResult.text("sampling capability declared")) + + private val perRequestLoggingTool = tool("test_logging_tool") + .description("Emits a log notification at each level; a modern request gets only those at or above its _meta logLevel") + .input[NoInput] + .streamingServerLogic[Identity]: (_, ctx, _) => + LoggingLevel.values.foreach(level => ctx.log(level, Json.fromString(s"$level message"))) + ToolResult.text("logging complete") + private val staticText = resource("test://static-text") .name("static-text") .mimeType("text/plain") @@ -184,7 +197,17 @@ object Main: .handle(_ => GetPromptResult(messages = List(PromptMessage(Role.User, ToolContent.Image(data = pngData, mimeType = "image/png"))))) private val server = McpServer[Identity](name = "chimp-conformance-server", version = "0.1.0") - .addTools(addNumbers, simpleText, errorTool, imageTool, audioTool, mixedTool, embeddedResourceTool, jsonSchemaTool) + .addTools( + addNumbers, + simpleText, + errorTool, + imageTool, + audioTool, + mixedTool, + embeddedResourceTool, + jsonSchemaTool, + missingCapabilityTool + ) .addResources(staticText, staticBinary) .addResourceTemplate(dataTemplate) .addPrompts(simplePrompt, argsPrompt, embeddedResourcePrompt, imagePrompt) @@ -192,7 +215,7 @@ object Main: .withLoggingLevel(_ => ()) .withSubscriptions(ResourceSubscriptions[Identity](_ => (), _ => ())) - private val streamingServer = server.streaming.addStreamingTools(progressTool, loggingTool) + private val streamingServer = server.streaming.addStreamingTools(progressTool, loggingTool, perRequestLoggingTool) def main(args: Array[String]): Unit = val requestedPort = args From ebcdb7f68c450193f70b7c740bd774c25f0626ce Mon Sep 17 00:00:00 2001 From: Ondra Pelech Date: Thu, 19 Nov 2026 15:49:30 +0100 Subject: [PATCH 06/31] docs(T8): document request facts, per-request log level and -32021 Describe ctx.request (RequestInfo) and which facts a modern and a legacy request give, serverLogicWithContext, the logLevel gate on ctx.log for modern requests, and withRequiredClientCapabilities with its -32021 rejection. Add -32021 to the table of modern request errors. --- docs/server/capabilities.md | 39 +++++++++++++++++++++++++++++++++++-- 1 file changed, 37 insertions(+), 2 deletions(-) diff --git a/docs/server/capabilities.md b/docs/server/capabilities.md index 092db3d1..733a2ef9 100644 --- a/docs/server/capabilities.md +++ b/docs/server/capabilities.md @@ -1,9 +1,9 @@ # Server capabilities -Most tools just answer a request, so `serverLogic`/`handle` expose no context. A tool that needs to **push to the client while it runs** uses `streamingServerLogic`, which receives a `StreamingServerContext[F]`: +Most tools just answer a request, so `serverLogic`/`handle` expose no context. Use `serverLogicWithContext` to read the facts of the request (see [request facts](#request-facts)). A tool that needs to **push to the client while it runs** uses `streamingServerLogic`, which receives a `StreamingServerContext[F]`: - `reportProgress` — [progress](https://modelcontextprotocol.io/specification/2025-11-25/basic/utilities/progress) notifications, auto-wired to the request's progress token. -- `log` — [logging](https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/logging) notifications. +- `log` — [logging](https://modelcontextprotocol.io/specification/2025-11-25/server/utilities/logging) notifications. For a modern (`2026-07-28`) request, chimp sends a message only when its level is at or above the [per-request log level](https://modelcontextprotocol.io/specification/2026-07-28/server/utilities/logging#per-request-log-level) in `_meta` (`io.modelcontextprotocol/logLevel`). If the request sets no level, chimp sends no messages. For a legacy request, chimp sends all messages; use `.withLoggingLevel` to receive `logging/setLevel`. ```{note} Pushing to the client requires an open stream, so a `streamingServerLogic` tool is registered with `addStreamingTool` on a `StreamingMcpServer`, and will not compile on the plain request/response endpoint. @@ -45,5 +45,40 @@ A request is **modern** when its `_meta` or its `MCP-Protocol-Version` header de | the `MCP-Protocol-Version` header and `_meta` declare different versions | `-32020` HeaderMismatch | `400` | | `Mcp-Method` / `Mcp-Name` header missing or different from the body (HTTP only) | `-32020` HeaderMismatch | `400` | | removed method (`initialize`, `ping`, `logging/setLevel`, `resources/subscribe`, `resources/unsubscribe`) or unknown method | `-32601` MethodNotFound | `404` | +| `tools/call` of a tool whose required client capabilities `_meta` does not declare | `-32021` MissingRequiredClientCapability | `400` | Over HTTP, a modern request must carry the SEP-2243 standard headers: `Mcp-Method` with the body's `method`, and `Mcp-Name` with `params.name` on `tools/call` and `prompts/get`, or `params.uri` on `resources/read`. Header names are case-insensitive, values are case-sensitive, and surrounding whitespace is ignored. chimp's own client sends these headers and the `_meta` when you give it a modern protocol version — see [client transport](../client/transport.md). + +## Request facts + +Each handler can read the facts of its request from `ctx.request`, a `RequestInfo`: + +- `protocolVersion` — the protocol version of the request. +- `clientCapabilities` and `clientInfo` — what the client declares in `_meta`. +- `logLevel` — the per-request log level from `_meta`. +- `progressToken` — the progress token from `_meta`. + +A modern request carries all of these in `_meta`. The server keeps no state between requests, so a legacy request gives only the protocol version (from the `MCP-Protocol-Version` header or `_meta`) and the progress token. The other facts are `None`. + +`serverLogicWithContext` gives the context to tools, prompts, resources and resource templates on every server. `streamingServerLogic` and `securedStreamingServerLogic` give it too, because `StreamingServerContext` is a `ServerContext`. + +A tool that needs a client capability declares it with `withRequiredClientCapabilities`. If a modern request does not declare all of these capabilities in `_meta`, chimp rejects it before the logic runs, with `-32021` (MissingRequiredClientCapability), HTTP `400`, and the capabilities in `data.requiredCapabilities`. chimp compares the capabilities key by key, also in nested objects. A legacy request has no per-request capabilities, so chimp does not check it. + +```scala mdoc:compile-only +import chimp.server.* +import chimp.protocol.ClientCapabilities +import io.circe.{Codec, Json} +import sttp.shared.Identity +import sttp.tapir.* + +case class AskInput(question: String) derives Codec, Schema + +val ask = tool("ask") + .withRequiredClientCapabilities(ClientCapabilities(sampling = Some(Json.obj()))) + .input[AskInput] + .serverLogicWithContext[Identity]: (in, ctx, _) => + val client = ctx.request.clientInfo.fold("unknown client")(_.name) + ToolResult.text(s"$client asked: ${in.question}") + +val server = McpServer[Identity]().addTool(ask) +``` From 178aef7eef8f3c833035b65fd5af1a81dd0e6dcf Mon Sep 17 00:00:00 2001 From: Ondra Pelech Date: Thu, 19 Nov 2026 16:05:04 +0100 Subject: [PATCH 07/31] test(T8): expect no log notifications for modern requests without a log level The shared streaming tests run with a legacy client (Pekko) and with a modern 2026-07-28 client (ZIO, Ox). The modern client sends no _meta logLevel yet, so under the per-request log level rule it must receive no notifications/message. Each spec now states its client protocol version, and the log tests expect the messages for a legacy client and none for a modern one. This covers the log gate end to end over HTTP on all three backends. --- .../chimp/server/ox/OxMcpServerHttpSpec.scala | 9 +++++---- .../server/pekko/PekkoMcpServerHttpSpec.scala | 3 ++- .../chimp/server/zio/ZioMcpServerHttpSpec.scala | 9 +++++---- .../chimp/server/McpServerStreamingTests.scala | 15 +++++++++++---- .../server/SecuredMcpServerStreamingTests.scala | 16 +++++++++++----- 5 files changed, 34 insertions(+), 18 deletions(-) diff --git a/server-streaming/server-ox/src/test/scala/chimp/server/ox/OxMcpServerHttpSpec.scala b/server-streaming/server-ox/src/test/scala/chimp/server/ox/OxMcpServerHttpSpec.scala index d958c82d..317c9423 100644 --- a/server-streaming/server-ox/src/test/scala/chimp/server/ox/OxMcpServerHttpSpec.scala +++ b/server-streaming/server-ox/src/test/scala/chimp/server/ox/OxMcpServerHttpSpec.scala @@ -40,6 +40,7 @@ class OxMcpServerHttpSpec with SecuredMcpServerStreamingTests[Identity] with SyncToFuture: private val clientInfo = Implementation("chimp-server-test", "0.0.1") + override protected val clientProtocolVersion: ProtocolVersion = ProtocolVersion.Latest override protected def withServer(server: McpServer[Identity])(test: McpClient[Identity] => Identity[Assertion]): Future[Assertion] = withStreamingServer(server.streaming)(test) @@ -50,8 +51,8 @@ class OxMcpServerHttpSpec withHttpServer(OxServerHttpTransport(List("mcp")).serve(server)): (port, backend, ox) => given Ox = ox val transport = - OxClientHttpTransport(backend, uri"http://localhost:$port/mcp", ProtocolVersion.Latest, ClientTransport.defaultTimeout) - try test(McpClient.bidirectional(transport, clientInfo, protocolVersion = ProtocolVersion.Latest)) + OxClientHttpTransport(backend, uri"http://localhost:$port/mcp", clientProtocolVersion, ClientTransport.defaultTimeout) + try test(McpClient.bidirectional(transport, clientInfo, protocolVersion = clientProtocolVersion)) finally transport.close() override protected def withSecuredServer( @@ -77,11 +78,11 @@ class OxMcpServerHttpSpec val transport = OxClientHttpTransport( backend, uri"http://localhost:$port/mcp", - ProtocolVersion.Latest, + clientProtocolVersion, ClientTransport.defaultTimeout, headers = List(Header.authorization("Bearer", token)) ) - try test(McpClient.bidirectional(transport, clientInfo, protocolVersion = ProtocolVersion.Latest)) + try test(McpClient.bidirectional(transport, clientInfo, protocolVersion = clientProtocolVersion)) finally transport.close() // 2026-07-28 requests over raw HTTP: chimp's client does not write the modern `_meta` or the SEP-2243 headers yet diff --git a/server-streaming/server-pekko/src/test/scala/chimp/server/pekko/PekkoMcpServerHttpSpec.scala b/server-streaming/server-pekko/src/test/scala/chimp/server/pekko/PekkoMcpServerHttpSpec.scala index f3c09448..e80782bf 100644 --- a/server-streaming/server-pekko/src/test/scala/chimp/server/pekko/PekkoMcpServerHttpSpec.scala +++ b/server-streaming/server-pekko/src/test/scala/chimp/server/pekko/PekkoMcpServerHttpSpec.scala @@ -2,7 +2,7 @@ package chimp.server.pekko import chimp.client.transport.pekko.PekkoClientHttpTransport import chimp.client.{BidirectionalMcpClient, McpClient} -import chimp.protocol.Implementation +import chimp.protocol.{Implementation, ProtocolVersion} import chimp.server.transport.SecuredServerStreamingHttpTransport import chimp.server.{ McpServer, @@ -34,6 +34,7 @@ class PekkoMcpServerHttpSpec with SecuredMcpServerStreamingTests[Future] with PekkoToFuture: private val clientInfo = Implementation("chimp-server-test", "0.0.1") + override protected val clientProtocolVersion: ProtocolVersion = ProtocolVersion.LatestLegacy override protected def withServer(server: McpServer[Future])(test: McpClient[Future] => Future[Assertion]): Future[Assertion] = withStreamingServer(server.streaming)(test) diff --git a/server-streaming/server-zio/src/test/scala/chimp/server/zio/ZioMcpServerHttpSpec.scala b/server-streaming/server-zio/src/test/scala/chimp/server/zio/ZioMcpServerHttpSpec.scala index a500fa28..251b88c3 100644 --- a/server-streaming/server-zio/src/test/scala/chimp/server/zio/ZioMcpServerHttpSpec.scala +++ b/server-streaming/server-zio/src/test/scala/chimp/server/zio/ZioMcpServerHttpSpec.scala @@ -35,6 +35,7 @@ class ZioMcpServerHttpSpec with SecuredMcpServerStreamingTests[Task] with ZioToFuture: private val clientInfo = Implementation("chimp-server-test", "0.0.1") + override protected val clientProtocolVersion: ProtocolVersion = ProtocolVersion.Latest override protected def withServer(server: McpServer[Task])(test: McpClient[Task] => Task[Assertion]): Future[Assertion] = withStreamingServer(server.streaming)(test) @@ -43,14 +44,14 @@ class ZioMcpServerHttpSpec server: StreamingMcpServer[Task] )(test: BidirectionalMcpClient[Task] => Task[Assertion]): Future[Assertion] = withHttpServer(ZioServerHttpTransport(List("mcp")).serve(server), Nil): transport => - McpClient.bidirectional(transport, clientInfo, protocolVersion = ProtocolVersion.Latest).flatMap(test) + McpClient.bidirectional(transport, clientInfo, protocolVersion = clientProtocolVersion).flatMap(test) override protected def withSecuredServer( server: SecuredMcpServer[Task, String, String, User], token: String )(test: McpClient[Task] => Task[Assertion]): Future[Assertion] = withHttpServer(server.endpoint(List("mcp")), List(Header.authorization("Bearer", token))): transport => - McpClient(transport, clientInfo, ProtocolVersion.Latest).flatMap(test) + McpClient(transport, clientInfo, clientProtocolVersion).flatMap(test) override protected def withSecuredStreamingServer( server: SecuredStreamingMcpServer[Task, String, String, User], @@ -58,7 +59,7 @@ class ZioMcpServerHttpSpec )(test: BidirectionalMcpClient[Task] => Task[Assertion]): Future[Assertion] = val endpoint = SecuredServerStreamingHttpTransport(List("mcp"), ZioServerHttpTransport(List("mcp"))).serve(server) withHttpServer(endpoint, List(Header.authorization("Bearer", token))): transport => - McpClient.bidirectional(transport, clientInfo, protocolVersion = ProtocolVersion.Latest).flatMap(test) + McpClient.bidirectional(transport, clientInfo, protocolVersion = clientProtocolVersion).flatMap(test) private def withHttpServer( endpoint: ServerEndpoint[ZioStreams & WebSockets, Task], @@ -74,7 +75,7 @@ class ZioMcpServerHttpSpec .scoped( backend, uri"http://localhost:$port/mcp", - ProtocolVersion.Latest, + clientProtocolVersion, ClientTransport.defaultTimeout, headers = headers ) diff --git a/server/src/test/scala/chimp/server/McpServerStreamingTests.scala b/server/src/test/scala/chimp/server/McpServerStreamingTests.scala index da568d64..5c60540a 100644 --- a/server/src/test/scala/chimp/server/McpServerStreamingTests.scala +++ b/server/src/test/scala/chimp/server/McpServerStreamingTests.scala @@ -19,6 +19,9 @@ trait McpServerStreamingTests[F[_]] extends AsyncFlatSpec with Matchers: protected def withStreamingServer(server: StreamingMcpServer[F])(test: BidirectionalMcpClient[F] => F[Assertion]): Future[Assertion] + /** The protocol version of the spec's client. A modern client sets no `_meta` logLevel, so it must get no log notifications. */ + protected def clientProtocolVersion: ProtocolVersion + private case class NoInput() derives Codec, Schema protected def streamingServer: StreamingMcpServer[F] = @@ -36,7 +39,7 @@ trait McpServerStreamingTests[F[_]] extends AsyncFlatSpec with Matchers: yield ToolResult.text("done") ) - "a streaming MCP server" should "deliver log notifications emitted during a tool call" in + "a streaming MCP server" should "deliver log notifications emitted during a tool call, but none to a modern request without a log level" in withStreamingServer(streamingServer): client => val messages = ConcurrentLinkedQueue[Json]() val listener: ServerNotification => F[Unit] = { @@ -47,6 +50,10 @@ trait McpServerStreamingTests[F[_]] extends AsyncFlatSpec with Matchers: .onServerNotification(notification => listener(notification)) .flatMap(_ => client.callTool("noisy", Json.obj())) .flatMap: result => - waitUntil(messages.size >= 3).map: _ => - result.content shouldBe List(ToolContent.Text("text", "done")) - messages.asScala.toList shouldBe List(Json.fromString("one"), Json.fromString("two"), Json.fromString("three")) + val expected = + if clientProtocolVersion.isModern then Nil else List(Json.fromString("one"), Json.fromString("two"), Json.fromString("three")) + waitUntil(messages.size >= expected.size) + .flatMap(_ => sleep(50)) + .map: _ => + result.content shouldBe List(ToolContent.Text("text", "done")) + messages.asScala.toList shouldBe expected diff --git a/server/src/test/scala/chimp/server/SecuredMcpServerStreamingTests.scala b/server/src/test/scala/chimp/server/SecuredMcpServerStreamingTests.scala index 750f7202..17080f71 100644 --- a/server/src/test/scala/chimp/server/SecuredMcpServerStreamingTests.scala +++ b/server/src/test/scala/chimp/server/SecuredMcpServerStreamingTests.scala @@ -23,6 +23,9 @@ trait SecuredMcpServerTestFixtures[F[_]]: trait SecuredMcpServerStreamingTests[F[_]] extends AsyncFlatSpec with Matchers with RecoverMethods with SecuredMcpServerTestFixtures[F]: this: ToFuture[F] => + /** The protocol version of the spec's client. A modern client sets no `_meta` logLevel, so it must get no log notifications. */ + protected def clientProtocolVersion: ProtocolVersion + /** @param token * The bearer token the client authenticates with; defaults to [[validToken]] so most tests need not pass it. */ @@ -83,11 +86,14 @@ trait SecuredMcpServerStreamingTests[F[_]] extends AsyncFlatSpec with Matchers w .onServerNotification(notification => listener(notification)) .flatMap(_ => client.callTool("whoAmI", Json.obj())) .flatMap: result => - waitUntil(messages.size >= 1).map: _ => - result.content shouldBe List(ToolContent.Text("text", "employee@example.com")) - messages.asScala.toList shouldBe List(Json.fromString("employee@example.com")) - - "a secured streaming MCP server" should "give the principal to a streaming tool, and deliver its log notifications" in + val expected = if clientProtocolVersion.isModern then Nil else List(Json.fromString("employee@example.com")) + waitUntil(messages.size >= expected.size) + .flatMap(_ => sleep(50)) + .map: _ => + result.content shouldBe List(ToolContent.Text("text", "employee@example.com")) + messages.asScala.toList shouldBe expected + + "a secured streaming MCP server" should "give the principal to a streaming tool, and deliver its log notifications (none to a modern request without a log level)" in withSecuredStreamingServer(securedStreamingServer)(assertWhoAmIDeliversPrincipal) it should "give the principal to a streaming tool when the security logic is effectful" in From 345050ac09fecb7c00c49b6c082a388ab2c7dbf7 Mon Sep 17 00:00:00 2001 From: Ondra Pelech Date: Thu, 19 Nov 2026 17:06:27 +0100 Subject: [PATCH 08/31] feat(T8): validate server/discover like other modern requests server/discover was the era-agnostic bootstrap and skipped all checks. A discover that declares a version (in _meta or in the MCP-Protocol-Version header) is now a modern request and gets the same checks: -32602 for missing _meta keys, -32022 with the supported and requested versions for an unsupported version, -32020 for a header that differs from _meta, and the SEP-2243 Mcp-Method check, all with HTTP 400. A discover with no version, or a legacy one, is still answered, so a probing client can discover the server. Two ordering fixes follow the conformance harness: a header/_meta version mismatch is now reported (-32020) before an unsupported _meta version (-32022), and a modern HTTP request without the MCP-Protocol-Version header fails with -32020. --- docs/server/capabilities.md | 4 +- .../main/scala/chimp/server/McpHandler.scala | 24 ++++---- .../scala/chimp/server/McpHandlerSpec.scala | 60 ++++++++++++++++++- 3 files changed, 75 insertions(+), 13 deletions(-) diff --git a/docs/server/capabilities.md b/docs/server/capabilities.md index 733a2ef9..be4b790b 100644 --- a/docs/server/capabilities.md +++ b/docs/server/capabilities.md @@ -36,13 +36,13 @@ chimp is **dual-era**: it speaks the legacy handshake revisions (`2025-11-25` an The server answers `server/discover` automatically with its supported versions, capabilities and identity (`serverInfo` in `_meta`), so a client can learn them in one request without connecting. A request that declares a protocol version the server does not support is rejected with an `UnsupportedProtocolVersion` error (`-32022`) listing the supported versions, per the [versioning compatibility matrix](https://modelcontextprotocol.io/specification/2026-07-28/basic/versioning#compatibility-matrix). No configuration is required for any of this. -A request is **modern** when its `_meta` or its `MCP-Protocol-Version` header declares `2026-07-28`. A legacy client that writes a legacy version into `_meta` stays on the legacy rules. chimp checks every modern request before any tool logic runs, and answers a failed check with a plain JSON error and its own HTTP status: +A request is **modern** when its `_meta` or its `MCP-Protocol-Version` header declares `2026-07-28`. A legacy client that writes a legacy version into `_meta` stays on the legacy rules. chimp checks every modern request, `server/discover` included, before any tool logic runs, and answers a failed check with a plain JSON error and its own HTTP status. A `server/discover` that declares no version (or a legacy version) gets no checks, so any client can discover the server: | Problem | JSON-RPC error | HTTP status | |---|---|---| | unsupported protocol version | `-32022` UnsupportedProtocolVersion | `400` | | `_meta` has no `protocolVersion` or no `clientCapabilities` | `-32602` InvalidParams | `400` | -| the `MCP-Protocol-Version` header and `_meta` declare different versions | `-32020` HeaderMismatch | `400` | +| the `MCP-Protocol-Version` header is missing (HTTP only), or it and `_meta` declare different versions | `-32020` HeaderMismatch | `400` | | `Mcp-Method` / `Mcp-Name` header missing or different from the body (HTTP only) | `-32020` HeaderMismatch | `400` | | removed method (`initialize`, `ping`, `logging/setLevel`, `resources/subscribe`, `resources/unsubscribe`) or unknown method | `-32601` MethodNotFound | `404` | | `tools/call` of a tool whose required client capabilities `_meta` does not declare | `-32021` MissingRequiredClientCapability | `400` | diff --git a/server/src/main/scala/chimp/server/McpHandler.scala b/server/src/main/scala/chimp/server/McpHandler.scala index 86508012..fd598d48 100644 --- a/server/src/main/scala/chimp/server/McpHandler.scala +++ b/server/src/main/scala/chimp/server/McpHandler.scala @@ -81,7 +81,7 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD requestRejection(method, params, headers, id) match case Some(rejection) => rejection.unit case None => - val isModern = isModernRequest(method, params, headers) + val isModern = isModernRequest(params, headers) val info = requestInfo(params, headers, isModern) dispatch(method, params, id, headers, () => makeContext(info), isModern) case Right(notification: JSONRPCMessage.Notification) => @@ -155,9 +155,10 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD private def jsonResponse(message: JSONRPCMessage): McpResponse = McpResponse.JsonResponse(message.asJson) - // request methods a 2026-07-28 client may call (server/discover is handled separately as the era-agnostic bootstrap) + // request methods a 2026-07-28 client may call private val modernMethods: Set[String] = Set( + "server/discover", "tools/list", "tools/call", "resources/list", @@ -175,13 +176,13 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD /** Whether the request follows the modern (2026-07-28) rules: it declares a modern version in `_meta` or via the `MCP-Protocol-Version` * header. A known legacy version in `_meta` keeps the legacy rules; an unknown one is treated as modern, so it gets the modern `-32022` - * with HTTP 400. `server/discover` is the era-agnostic bootstrap and is never treated as modern here. + * with HTTP 400. A `server/discover` that declares no version stays legacy, so a probing client can still discover the server. */ - private def isModernRequest(method: String, params: Option[Json], headers: Seq[Header]): Boolean = + private def isModernRequest(params: Option[Json], headers: Seq[Header]): Boolean = val metaVersion = params.flatMap(_.hcursor.downField("_meta").downField(ProtocolMeta.ProtocolVersionKey).as[String].toOption) val headerVersion = headers.collectFirst { case h if h.name.equalsIgnoreCase(ProtocolMeta.ProtocolVersionHeader) => h.value.trim } val metaIsModern = metaVersion.exists(version => ProtocolVersion.from(version).forall(_.isModern)) - method != "server/discover" && (metaIsModern || headerVersion.flatMap(ProtocolVersion.from).exists(_.isModern)) + metaIsModern || headerVersion.flatMap(ProtocolVersion.from).exists(_.isModern) /** The facts a handler can read about the request; see [[RequestInfo]]. */ private def requestInfo(params: Option[Json], headers: Seq[Header], isModern: Boolean): RequestInfo = @@ -207,7 +208,7 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD val meta = params.flatMap(_.hcursor.downField("_meta").focus) val metaVersion = meta.flatMap(_.hcursor.get[String](ProtocolMeta.ProtocolVersionKey).toOption) val headerVersion = headers.collectFirst { case h if h.name.equalsIgnoreCase(ProtocolMeta.ProtocolVersionHeader) => h.value.trim } - if isModernRequest(method, params, headers) then modernRejection(method, params, meta, metaVersion, headerVersion, headers, id) + if isModernRequest(params, headers) then modernRejection(method, params, meta, metaVersion, headerVersion, headers, id) else metaVersion match case Some(version) if ProtocolVersion.from(version).isEmpty => @@ -235,12 +236,15 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD id: RequestId ): Option[McpResponse] = val declared = metaVersion.orElse(headerVersion) - if declared.exists(version => ProtocolVersion.from(version).isEmpty) then + val overHttp = headers.exists(_.name.equalsIgnoreCase("Host")) + if overHttp && headerVersion.isEmpty then + Some(jsonError(id, StatusCode.BadRequest, JSONRPCErrorCodes.HeaderMismatch.code, "Missing MCP-Protocol-Version header")) + else if headerVersion.isDefined && metaVersion.isDefined && headerVersion != metaVersion then + Some(jsonError(id, StatusCode.BadRequest, JSONRPCErrorCodes.HeaderMismatch.code, "MCP-Protocol-Version header does not match _meta")) + else if declared.exists(version => ProtocolVersion.from(version).isEmpty) then val envelope: JSONRPCMessage = JSONRPCMessage.Error(id = id, error = ProtocolMeta.unsupportedVersionError(declared.get, ProtocolVersion.supported.map(_.name))) Some(McpResponse.JsonError(StatusCode.BadRequest, envelope.asJson)) - else if headerVersion.isDefined && metaVersion.isDefined && headerVersion != metaVersion then - Some(jsonError(id, StatusCode.BadRequest, JSONRPCErrorCodes.HeaderMismatch.code, "MCP-Protocol-Version header does not match _meta")) else if metaVersion.isEmpty then Some( jsonError(id, StatusCode.BadRequest, JSONRPCErrorCodes.InvalidParams.code, s"Missing ${ProtocolMeta.ProtocolVersionKey} in _meta") @@ -253,7 +257,7 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD Some(jsonError(id, StatusCode.NotFound, JSONRPCErrorCodes.MethodNotFound.code, s"Method not found: $method")) else // SEP-2243 standard request headers only apply over HTTP (identified by the Host header); stdio carries no such headers - val headerError = Option.when(headers.exists(_.name.equalsIgnoreCase("Host")))(headerValidationError(method, params, headers, id)) + val headerError = Option.when(overHttp)(headerValidationError(method, params, headers, id)) headerError.flatten.orElse(missingCapabilityError(method, params, meta, id)) /** A `-32021` with HTTP 400 when `tools/call` names a tool whose required client capabilities the request's `_meta` does not declare. */ diff --git a/server/src/test/scala/chimp/server/McpHandlerSpec.scala b/server/src/test/scala/chimp/server/McpHandlerSpec.scala index 5aec5a43..e2b51d03 100644 --- a/server/src/test/scala/chimp/server/McpHandlerSpec.scala +++ b/server/src/test/scala/chimp/server/McpHandlerSpec.scala @@ -178,7 +178,7 @@ class McpHandlerSpec extends AnyFlatSpec with Matchers: private def modernHttpCall(method: String, params: Json, extraHeaders: (String, String)*): McpResponse = val req: JSONRPCMessage = Request(method = method, params = Some(params.deepMerge(Json.obj(modernMeta))), id = RequestId("h")) - val headers = Header("Host", "localhost") +: extraHeaders.map(Header(_, _)) + val headers = Header("Host", "localhost") +: Header(ProtocolMeta.ProtocolVersionHeader, "2026-07-28") +: extraHeaders.map(Header(_, _)) headersHandler.handleJsonRpc(req.asJson, headers) private def shouldBeHeaderMismatch(response: McpResponse): org.scalatest.Assertion = @@ -852,3 +852,61 @@ class McpHandlerSpec extends AnyFlatSpec with Matchers: extractJsonFromResponse(handler.handleJsonRpc(json, Seq.empty)).hcursor.downField("id").focus shouldBe Some( Json.fromLong(1763561090000L) ) + + private def discoverOverHttp(meta: Option[Json], versionHeader: Option[String], extraHeaders: (String, String)*): McpResponse = + val req: JSONRPCMessage = Request(method = "server/discover", params = meta.map(m => Json.obj("_meta" -> m)), id = RequestId("dv")) + val headers = (("Host" -> "localhost") +: ("Mcp-Method" -> "server/discover") +: extraHeaders) ++ + versionHeader.map(ProtocolMeta.ProtocolVersionHeader -> _) + handler.handleJsonRpc(req.asJson, headers.map(Header(_, _))) + + private def errorOf(response: McpResponse): JSONRPCErrorObject = + extractJsonFromResponse(response).as[JSONRPCMessage].getOrElse(fail("decode")) match + case Error(_, _, err) => err + case other => fail(s"Expected Error, got $other") + + private def discoverMeta(version: String = "2026-07-28"): Json = + Json.obj(ProtocolMeta.ProtocolVersionKey -> Json.fromString(version), ProtocolMeta.ClientCapabilities -> Json.obj()) + + it should "answer a modern server/discover whose _meta and header are valid" in: + val response = discoverOverHttp(Some(discoverMeta()), Some("2026-07-28")) + response.statusCode shouldBe sttp.model.StatusCode.Ok + extractJsonFromResponse(response).as[JSONRPCMessage].getOrElse(fail("decode")) match + case Response(_, _, result) => result.as[DiscoverResult].isRight shouldBe true + case other => fail(s"Expected Response, got $other") + + it should "answer a server/discover that declares no protocol version, or a legacy one" in: + discoverOverHttp(None, None).statusCode shouldBe sttp.model.StatusCode.Ok + discoverOverHttp(None, Some("2025-11-25")).statusCode shouldBe sttp.model.StatusCode.Ok + + it should "reject a modern server/discover with missing _meta keys with -32602 and HTTP 400" in: + val missingCapabilities = Json.obj(ProtocolMeta.ProtocolVersionKey -> Json.fromString("2026-07-28")) + val missingVersion = Json.obj(ProtocolMeta.ClientCapabilities -> Json.obj()) + for meta <- List(None, Some(missingCapabilities), Some(missingVersion)) do + val response = discoverOverHttp(meta, Some("2026-07-28")) + withClue(meta): + response.statusCode shouldBe sttp.model.StatusCode.BadRequest + errorOf(response).code shouldBe InvalidParams.code + + it should "reject a server/discover with an unsupported protocol version with -32022, the supported and the requested versions" in: + val response = discoverOverHttp(Some(discoverMeta("v999.0.0")), Some("v999.0.0")) + response.statusCode shouldBe sttp.model.StatusCode.BadRequest + val err = errorOf(response) + err.code shouldBe UnsupportedProtocolVersion.code + err.data.flatMap(_.hcursor.get[List[String]]("supported").toOption) shouldBe Some(ProtocolVersion.supported.map(_.name)) + err.data.flatMap(_.hcursor.get[String]("requested").toOption) shouldBe Some("v999.0.0") + + it should "reject a modern request whose MCP-Protocol-Version header differs from _meta with -32020, even for an unsupported _meta version" in: + val response = discoverOverHttp(Some(discoverMeta("v999.0.0")), Some("2026-07-28")) + response.statusCode shouldBe sttp.model.StatusCode.BadRequest + errorOf(response).code shouldBe HeaderMismatch.code + + it should "reject a modern HTTP request without the MCP-Protocol-Version header with -32020 and HTTP 400" in: + val response = discoverOverHttp(Some(discoverMeta()), None) + response.statusCode shouldBe sttp.model.StatusCode.BadRequest + errorOf(response).code shouldBe HeaderMismatch.code + + it should "reject a modern server/discover over HTTP with a mismatched Mcp-Method header with -32020" in: + val req: JSONRPCMessage = Request(method = "server/discover", params = Some(Json.obj("_meta" -> discoverMeta())), id = RequestId("dm")) + val headers = + Seq(Header("Host", "localhost"), Header(ProtocolMeta.ProtocolVersionHeader, "2026-07-28"), Header("Mcp-Method", "tools/list")) + errorOf(handler.handleJsonRpc(req.asJson, headers)).code shouldBe HeaderMismatch.code From ade71f1bcd869fee22fab678b49fb25fe2582f73 Mon Sep 17 00:00:00 2001 From: Ondra Pelech Date: Thu, 19 Nov 2026 16:24:18 +0100 Subject: [PATCH 09/31] feat(T16): add a notification publisher and subscriptions/listen handling NotificationPublisher lets application code publish tools, prompts and resources list changes and resource updates from any thread. Servers take it with withPublisher. A handler for a transport that can hold a stream open accepts a modern subscriptions/listen request, acknowledges the subset of the filter it honours, tags every message with the subscription id, and ends it with a successful listen result when the publisher closes. Modern discover advertises listChanged and resources.subscribe only when the server can publish them; legacy initialize is unchanged. Without a streaming transport, subscriptions/listen stays -32601. --- .../main/scala/chimp/server/McpHandler.scala | 60 ++++-- .../main/scala/chimp/server/McpServer.scala | 36 +++- .../chimp/server/NotificationPublisher.scala | 148 ++++++++++++++ .../server/NotificationPublisherSpec.scala | 185 ++++++++++++++++++ 4 files changed, 414 insertions(+), 15 deletions(-) create mode 100644 server/src/main/scala/chimp/server/NotificationPublisher.scala create mode 100644 server/src/test/scala/chimp/server/NotificationPublisherSpec.scala diff --git a/server/src/main/scala/chimp/server/McpHandler.scala b/server/src/main/scala/chimp/server/McpHandler.scala index fd598d48..8d6f6aff 100644 --- a/server/src/main/scala/chimp/server/McpHandler.scala +++ b/server/src/main/scala/chimp/server/McpHandler.scala @@ -30,8 +30,13 @@ enum McpResponse: case JsonError(status, json) => JsonError(status, json.deepDropNullValues) case EmptyAcceptResponse => this -private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerDef[F, C]): +/** @param canListen + * Whether the transport can hold a `subscriptions/listen` stream open. Without it the server neither serves `subscriptions/listen` nor + * advertises the capabilities which need it. + */ +private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerDef[F, C], canListen: Boolean = false): private val logger = LoggerFactory.getLogger(classOf[McpHandler[?, ?]]) + private val listenPublisher = server.publisher.filter(_ => canListen) private val toolsByName = server.tools.map(tool => tool.name -> tool).toMap private val promptsByName = server.prompts.map(prompt => prompt.definition.name -> prompt).toMap private val resourcesByUri = server.resources.map(resource => resource.definition.uri -> resource).toMap @@ -141,6 +146,8 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD handleComplete(params, id).map(wrap(None)).map(jsonResponse) case "logging/setLevel" if server.loggingLevel.isDefined => handleSetLoggingLevel(params, id).map(jsonResponse) + case "subscriptions/listen" if listenPublisher.isDefined => + jsonResponse(protocolError(id, JSONRPCErrorCodes.InvalidParams.code, "Invalid or missing params")).unit case other => jsonResponse(protocolError(id, JSONRPCErrorCodes.MethodNotFound.code, s"Unknown method: $other")).unit @@ -167,7 +174,7 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD "prompts/list", "prompts/get", "completion/complete" - ) + ) ++ listenPublisher.map(_ => "subscriptions/listen") private def jsonError(id: RequestId, status: StatusCode, code: Int, message: String, data: Option[Json] = None): McpResponse = logger.debug(s"Modern request rejected (id=$id, http=${status.code}, code=$code): $message") @@ -302,18 +309,47 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD private val serverInfoJson: Json = serverImplementation.asJson private val serverInfoMeta: Json = Json.obj(ProtocolMeta.ServerInfo -> serverInfoJson) - private val serverCapabilities: ServerCapabilities = ServerCapabilities( - logging = Option.when(server.loggingLevel.isDefined)(Json.obj()), - completions = Option.when(server.completion.isDefined)(Json.obj()), - prompts = Option.when(hasPrompts)(ServerPromptsCapability(listChanged = Some(false))), - resources = - Option.when(hasResources)(ServerResourcesCapability(subscribe = Some(server.subscriptions.isDefined), listChanged = Some(false))), - tools = Option.when(server.tools.nonEmpty)(ServerToolsCapability(listChanged = Some(false))) - ) + /** A legacy client gets no list changes (there is no stream for them) and subscribes with `resources/subscribe`. A modern client gets + * them on a `subscriptions/listen` stream, which also replaces `resources/subscribe`. + */ + private def serverCapabilities(modern: Boolean): ServerCapabilities = + val listChanged = Some(modern && listenPublisher.isDefined) + ServerCapabilities( + logging = Option.when(server.loggingLevel.isDefined)(Json.obj()), + completions = Option.when(server.completion.isDefined)(Json.obj()), + prompts = Option.when(hasPrompts)(ServerPromptsCapability(listChanged = listChanged)), + resources = Option.when(hasResources)( + ServerResourcesCapability( + subscribe = if modern then listChanged else Some(server.subscriptions.isDefined), + listChanged = listChanged + ) + ), + tools = Option.when(server.tools.nonEmpty)(ServerToolsCapability(listChanged = listChanged)) + ) + + /** The `subscriptions/listen` request which this server serves on a stream, with the subset of its filter that the server honours; `None` + * for any other request, and for a request which [[validateRequest]] rejects. + */ + def listenRequest(request: Json, headers: Seq[Header]): Option[ListenRequest] = + for + publisher <- listenPublisher + case JSONRPCMessage.Request(_, "subscriptions/listen", params, id) <- request.as[JSONRPCMessage].toOption + if isModernRequest(params, headers) && requestRejection("subscriptions/listen", params, headers, id).isEmpty + listen <- params.flatMap(_.as[SubscriptionsListenParams].toOption) + yield ListenRequest(id, honoured(listen.notifications), publisher) + + private def honoured(requested: SubscriptionFilter): SubscriptionFilter = + def flag(value: Option[Boolean], supported: Boolean) = Option.when(supported && value.contains(true))(true) + SubscriptionFilter( + promptsListChanged = flag(requested.promptsListChanged, hasPrompts), + resourceSubscriptions = requested.resourceSubscriptions.filter(_ => hasResources), + resourcesListChanged = flag(requested.resourcesListChanged, hasResources), + toolsListChanged = flag(requested.toolsListChanged, server.tools.nonEmpty) + ) private val discoverResult: DiscoverResult = DiscoverResult( supportedVersions = ProtocolVersion.supported.map(_.name), - capabilities = serverCapabilities, + capabilities = serverCapabilities(modern = true), ttlMs = CacheHints.Default.ttlMs, cacheScope = CacheHints.Default.cacheScope, instructions = server.instructions, @@ -325,7 +361,7 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD val negotiated = requested.map(ProtocolVersion.negotiate).getOrElse(ProtocolVersion.LatestLegacy) val result = InitializeResult( protocolVersion = negotiated.name, - capabilities = serverCapabilities, + capabilities = serverCapabilities(modern = false), serverInfo = serverImplementation, instructions = server.instructions ) diff --git a/server/src/main/scala/chimp/server/McpServer.scala b/server/src/main/scala/chimp/server/McpServer.scala index c994f3d6..71e753fe 100644 --- a/server/src/main/scala/chimp/server/McpServer.scala +++ b/server/src/main/scala/chimp/server/McpServer.scala @@ -31,6 +31,7 @@ sealed trait McpServerDef[F[_], C <: ServerContext[F]]: def completion: Option[CompletionHandler[F]] def loggingLevel: Option[SetLoggingLevelHandler[F]] def subscriptions: Option[ResourceSubscriptions[F]] + def publisher: Option[NotificationPublisher] case class McpServer[F[_]]( name: String = "Chimp MCP server", @@ -44,7 +45,8 @@ case class McpServer[F[_]]( resourceTemplates: List[ServerResourceTemplate[F, ServerContext[F]]] = Nil, completion: Option[CompletionHandler[F]] = None, loggingLevel: Option[SetLoggingLevelHandler[F]] = None, - subscriptions: Option[ResourceSubscriptions[F]] = None + subscriptions: Option[ResourceSubscriptions[F]] = None, + publisher: Option[NotificationPublisher] = None ) extends McpServerDef[F, ServerContext[F]]: def name(value: String): McpServer[F] = copy(name = value) @@ -94,6 +96,12 @@ case class McpServer[F[_]]( def withSubscriptions(handler: ResourceSubscriptions[F]): McpServer[F] = copy(subscriptions = Some(handler)) + /** Sends the list changes and resource updates that `publisher` publishes to the clients on a `subscriptions/listen` stream. Needs a + * streaming transport; a server on the sync HTTP transport answers `subscriptions/listen` with `-32601`. + */ + def withPublisher(publisher: NotificationPublisher): McpServer[F] = + copy(publisher = Some(publisher)) + def endpoint(path: List[String]): ServerEndpoint[Any, F] = ServerHttpTransport(path).serve(this) /** Adds the security input, the error output which describes a rejection, and the logic which validates the security input and makes the @@ -123,7 +131,8 @@ case class McpServer[F[_]]( resourceTemplates, completion, loggingLevel, - subscriptions + subscriptions, + publisher ) case class StreamingMcpServer[F[_]]( @@ -138,7 +147,8 @@ case class StreamingMcpServer[F[_]]( resourceTemplates: List[ServerResourceTemplate[F, StreamingServerContext[F]]] = Nil, completion: Option[CompletionHandler[F]] = None, loggingLevel: Option[SetLoggingLevelHandler[F]] = None, - subscriptions: Option[ResourceSubscriptions[F]] = None + subscriptions: Option[ResourceSubscriptions[F]] = None, + publisher: Option[NotificationPublisher] = None ) extends McpServerDef[F, StreamingServerContext[F]]: def name(value: String): StreamingMcpServer[F] = copy(name = value) @@ -194,6 +204,12 @@ case class StreamingMcpServer[F[_]]( def withSubscriptions(handler: ResourceSubscriptions[F]): StreamingMcpServer[F] = copy(subscriptions = Some(handler)) + /** Sends the list changes and resource updates that `publisher` publishes to the clients on a `subscriptions/listen` stream. Needs a + * streaming transport; a server on the sync HTTP transport answers `subscriptions/listen` with `-32601`. + */ + def withPublisher(publisher: NotificationPublisher): StreamingMcpServer[F] = + copy(publisher = Some(publisher)) + /** An [[McpServer]] with security logic, which runs before the server handles an MCP message. The result of the security logic, the * principal, is given to the logic of the tools, prompts, and resources which are added to this server. Tools, prompts, and resources of * the initial server, which do not need the principal, are kept. @@ -223,6 +239,7 @@ case class SecuredMcpServer[F[_], S, E, P]( def completion: Option[CompletionHandler[F]] = server.completion def loggingLevel: Option[SetLoggingLevelHandler[F]] = server.loggingLevel def subscriptions: Option[ResourceSubscriptions[F]] = server.subscriptions + def publisher: Option[NotificationPublisher] = server.publisher def tools: List[ServerTool[?, ?, F, SecuredServerContext[F, P]]] = mergeBy(server.tools, securedTools)(_.name) @@ -288,6 +305,12 @@ case class SecuredMcpServer[F[_], S, E, P]( def withSubscriptions(handler: ResourceSubscriptions[F]): SecuredMcpServer[F, S, E, P] = copy(server = server.withSubscriptions(handler)) + /** Sends the list changes and resource updates that `publisher` publishes to the clients on a `subscriptions/listen` stream. Needs a + * streaming transport; a server on the sync HTTP transport answers `subscriptions/listen` with `-32601`. + */ + def withPublisher(publisher: NotificationPublisher): SecuredMcpServer[F, S, E, P] = + copy(server = server.withPublisher(publisher)) + def endpoint(path: List[String]): ServerEndpoint[Any, F] = SecuredServerHttpTransport[F, S, E, P](path).serve(this) def streaming: SecuredStreamingMcpServer[F, S, E, P] = SecuredStreamingMcpServer(this) @@ -310,6 +333,7 @@ case class SecuredStreamingMcpServer[F[_], S, E, P]( def completion: Option[CompletionHandler[F]] = server.completion def loggingLevel: Option[SetLoggingLevelHandler[F]] = server.loggingLevel def subscriptions: Option[ResourceSubscriptions[F]] = server.subscriptions + def publisher: Option[NotificationPublisher] = server.publisher def securityInput: EndpointInput[S] = server.securityInput def errorOutput: EndpointOutput[E] = server.errorOutput @@ -375,3 +399,9 @@ case class SecuredStreamingMcpServer[F[_], S, E, P]( def withSubscriptions(handler: ResourceSubscriptions[F]): SecuredStreamingMcpServer[F, S, E, P] = copy(server = server.withSubscriptions(handler)) + + /** Sends the list changes and resource updates that `publisher` publishes to the clients on a `subscriptions/listen` stream. Needs a + * streaming transport; a server on the sync HTTP transport answers `subscriptions/listen` with `-32601`. + */ + def withPublisher(publisher: NotificationPublisher): SecuredStreamingMcpServer[F, S, E, P] = + copy(server = server.withPublisher(publisher)) diff --git a/server/src/main/scala/chimp/server/NotificationPublisher.scala b/server/src/main/scala/chimp/server/NotificationPublisher.scala new file mode 100644 index 00000000..2fc5c869 --- /dev/null +++ b/server/src/main/scala/chimp/server/NotificationPublisher.scala @@ -0,0 +1,148 @@ +package chimp.server + +import chimp.protocol.* +import io.circe.Json +import io.circe.syntax.* + +import java.util.concurrent.ConcurrentHashMap +import java.util.concurrent.atomic.{AtomicBoolean, AtomicLong} +import scala.jdk.CollectionConverters.* + +/** Publishes list changes and resource updates to the clients which hold a `subscriptions/listen` stream (2026-07-28) open. Give it to a + * server with `withPublisher`. A streaming server then advertises `listChanged` for its tools, prompts and resources, and `subscribe` for + * its resources. + * + * The methods are thread-safe and can be called from any part of the application. Each one returns after it has put the notification on + * every open subscription which asked for it. + */ +final class NotificationPublisher: + private val subscriptions = ConcurrentHashMap[Long, Subscription]() + private val nextKey = AtomicLong() + private val closed = AtomicBoolean(false) + + /** Sends `notifications/tools/list_changed`. */ + def toolsListChanged(): Unit = publish(ServerEvent.ToolsListChanged) + + /** Sends `notifications/prompts/list_changed`. */ + def promptsListChanged(): Unit = publish(ServerEvent.PromptsListChanged) + + /** Sends `notifications/resources/list_changed`. */ + def resourcesListChanged(): Unit = publish(ServerEvent.ResourcesListChanged) + + /** Sends `notifications/resources/updated` to the subscriptions which listed `uri`. */ + def resourceUpdated(uri: String): Unit = publish(ServerEvent.ResourceUpdated(uri)) + + /** Ends each open subscription with a successful `subscriptions/listen` result, for example when the server shuts down. A subscription + * opened after this ends at once. + */ + def close(): Unit = + closed.set(true) + subscriptions.values.asScala.toList.foreach(_.end()) + + private def publish(event: ServerEvent): Unit = subscriptions.values.asScala.foreach(_.deliver(event)) + + private[server] def openSubscriptions: Int = subscriptions.size + + private[server] def open(id: RequestId, filter: SubscriptionFilter, output: SubscriptionOutput): Subscription = + val key = nextKey.getAndIncrement() + val subscription = Subscription(id, filter, output, () => { val _ = subscriptions.remove(key) }) + subscription.acknowledge() + subscriptions.put(key, subscription) + if closed.get then subscription.end() + subscription + +/** Where the messages of one subscription go. Each transport supplies its own. */ +private[server] trait SubscriptionOutput: + def send(message: Json): Unit + + /** Called after the server sent the final `subscriptions/listen` result. */ + def close(): Unit + +private[server] enum ServerEvent: + case ToolsListChanged, PromptsListChanged, ResourcesListChanged + case ResourceUpdated(uri: String) + + def accepted(filter: SubscriptionFilter): Boolean = this match + case ToolsListChanged => filter.toolsListChanged.contains(true) + case PromptsListChanged => filter.promptsListChanged.contains(true) + case ResourcesListChanged => filter.resourcesListChanged.contains(true) + case ResourceUpdated(uri) => filter.resourceSubscriptions.exists(_.contains(uri)) + + def notification(meta: Json): JSONRPCMessage.Notification = this match + case ToolsListChanged => JSONRPCMessage.Notification(method = "notifications/tools/list_changed", params = Some(meta)) + case PromptsListChanged => JSONRPCMessage.Notification(method = "notifications/prompts/list_changed", params = Some(meta)) + case ResourcesListChanged => JSONRPCMessage.Notification(method = "notifications/resources/list_changed", params = Some(meta)) + case ResourceUpdated(uri) => + JSONRPCMessage.Notification(method = "notifications/resources/updated", params = Some(meta.deepMerge(Json.obj("uri" -> uri.asJson)))) + +/** One `subscriptions/listen` stream. Every message on it carries the id of the listen request in `_meta`. */ +private[server] final class Subscription( + val id: RequestId, + filter: SubscriptionFilter, + output: SubscriptionOutput, + unregister: () => Unit +): + private val active = AtomicBoolean(true) + private val meta: Map[String, Json] = Map(ProtocolMeta.SubscriptionId -> id.asJson) + private val metaParams: Json = Json.obj("_meta" -> meta.asJson) + + def isActive: Boolean = active.get + + def acknowledge(): Unit = + send( + JSONRPCMessage.Notification( + method = "notifications/subscriptions/acknowledged", + params = Some(SubscriptionsAcknowledgedParams(filter, Some(meta)).asJson) + ) + ) + + def deliver(event: ServerEvent): Unit = + if active.get && event.accepted(filter) then send(event.notification(metaParams)) + + /** Ends the subscription because the client ended it; sends nothing. */ + def cancel(): Unit = + if active.compareAndSet(true, false) then unregister() + + /** Ends the subscription on the server's initiative, with a successful `subscriptions/listen` result. */ + def end(): Unit = + if active.compareAndSet(true, false) then + unregister() + send(JSONRPCMessage.Response(id = id, result = SubscriptionsListenResult(_meta = Some(meta)).asJson)) + output.close() + + private def send(message: JSONRPCMessage): Unit = output.send(message.asJson.deepDropNullValues) + +/** A `subscriptions/listen` request which the server accepted, with the subset of the filter it honours. */ +private[server] final case class ListenRequest(id: RequestId, filter: SubscriptionFilter, publisher: NotificationPublisher): + def open(output: SubscriptionOutput): Subscription = publisher.open(id, filter, output) + +/** The subscriptions of one stdio connection. They share its single output and are told apart by the subscription id. */ +private[server] final class StdioSubscriptions(write: Json => Unit): + private val open = ConcurrentHashMap[RequestId, Subscription]() + + def listen(request: ListenRequest): Unit = + val output = new SubscriptionOutput: + def send(message: Json): Unit = write(message) + def close(): Unit = + val _ = open.values.removeIf(!_.isActive) + write( + (JSONRPCMessage.Notification( + method = "notifications/cancelled", + params = Some(CancelledParams(request.id).asJson) + ): JSONRPCMessage).asJson.deepDropNullValues + ) + val subscription = request.open(output) + if subscription.isActive then + val _ = open.put(request.id, subscription) + + /** Ends the subscription which a `notifications/cancelled` from the client names; ignores any other message. */ + def cancel(message: Json): Unit = + message.as[JSONRPCMessage] match + case Right(JSONRPCMessage.Notification(_, "notifications/cancelled", Some(params))) => + params.as[CancelledParams].toOption.flatMap(cancelled => Option(open.remove(cancelled.requestId))).foreach(_.cancel()) + case _ => () + + /** Ends each open subscription of the connection, for example when its input ends. */ + def endAll(): Unit = + open.values.asScala.toList.foreach(_.end()) + open.clear() diff --git a/server/src/test/scala/chimp/server/NotificationPublisherSpec.scala b/server/src/test/scala/chimp/server/NotificationPublisherSpec.scala new file mode 100644 index 00000000..c35931e4 --- /dev/null +++ b/server/src/test/scala/chimp/server/NotificationPublisherSpec.scala @@ -0,0 +1,185 @@ +package chimp.server + +import chimp.protocol.* +import io.circe.Json +import io.circe.syntax.* +import org.scalatest.flatspec.AnyFlatSpec +import org.scalatest.matchers.should.Matchers +import sttp.model.StatusCode +import sttp.monad.{IdentityMonad, MonadError} +import sttp.shared.Identity +import sttp.tapir.Schema + +import scala.collection.mutable.ListBuffer + +class NotificationPublisherSpec extends AnyFlatSpec with Matchers: + private given MonadError[Identity] = IdentityMonad + + private case class NoInput() derives io.circe.Codec, Schema + + private val noop = tool("noop").input[NoInput].handle(_ => ToolResult.text("ok")) + private val textResource = resource("test://a").name("a").handle(() => Right(Nil)) + private val greet = prompt("greet").handle(_ => GetPromptResult(messages = Nil)) + + private def fullServer(publisher: NotificationPublisher): StreamingMcpServer[Identity] = + McpServer[Identity]() + .addTool(noop) + .addResource(textResource) + .addPrompt(greet) + .withSubscriptions(ResourceSubscriptions[Identity](_ => (), _ => ())) + .withPublisher(publisher) + .streaming + + private val modernMeta: Json = + Json.obj(ProtocolMeta.ProtocolVersionKey -> "2026-07-28".asJson, ProtocolMeta.ClientCapabilities -> Json.obj()) + + private def request(method: String, id: RequestId, params: Json): Json = + (JSONRPCMessage.Request(method = method, params = Some(params), id = id): JSONRPCMessage).asJson + + private def listen(id: RequestId, filter: Json): Json = + request("subscriptions/listen", id, Json.obj("notifications" -> filter, "_meta" -> modernMeta)) + + private def capabilities(handler: McpHandler[Identity, ?], method: String): ServerCapabilities = + val params = if method == "initialize" then Json.obj("protocolVersion" -> "2025-11-25".asJson) else Json.obj() + handler + .handleJsonRpc(request(method, RequestId(1), params), Nil, _ => ???) + .body + .get + .hcursor + .downField("result") + .get[ServerCapabilities]("capabilities") + .toOption + .get + + private class RecordingOutput extends SubscriptionOutput: + val messages: ListBuffer[Json] = ListBuffer.empty + var closed = false + def send(message: Json): Unit = messages += message + def close(): Unit = closed = true + def methods: List[Option[String]] = messages.toList.map(_.hcursor.get[String]("method").toOption) + + private def subscriptionId(message: Json): Option[Json] = + message.hcursor.downField("params").downField("_meta").downField(ProtocolMeta.SubscriptionId).focus + + "a server with a publisher on a streaming transport" should "advertise list changes and subscribe to modern clients only" in: + val handler = McpHandler(fullServer(NotificationPublisher()), canListen = true) + val modern = capabilities(handler, "server/discover") + modern.tools.flatMap(_.listChanged) shouldBe Some(true) + modern.prompts.flatMap(_.listChanged) shouldBe Some(true) + modern.resources.flatMap(_.listChanged) shouldBe Some(true) + modern.resources.flatMap(_.subscribe) shouldBe Some(true) + val legacy = capabilities(handler, "initialize") + legacy.tools.flatMap(_.listChanged) shouldBe Some(false) + legacy.resources.flatMap(_.subscribe) shouldBe Some(true) + + it should "acknowledge only the notification types it can send" in: + val handler = McpHandler(McpServer[Identity]().addTool(noop).withPublisher(NotificationPublisher()).streaming, canListen = true) + val filter = + Json.obj("toolsListChanged" -> true.asJson, "promptsListChanged" -> true.asJson, "resourceSubscriptions" -> List("x").asJson) + val accepted = handler.listenRequest(listen(RequestId(7), filter), Nil) + accepted.map(_.id) shouldBe Some(RequestId(7)) + accepted.map(_.filter) shouldBe Some(SubscriptionFilter(toolsListChanged = Some(true))) + + it should "not take a legacy subscriptions/listen request as a subscription" in: + val handler = McpHandler(fullServer(NotificationPublisher()), canListen = true) + val legacyListen = request("subscriptions/listen", RequestId(1), Json.obj("notifications" -> Json.obj())) + handler.listenRequest(legacyListen, Nil) shouldBe None + + "a server with a publisher on the sync HTTP transport" should "advertise no list changes and answer subscriptions/listen with -32601" in: + val handler = McpHandler(fullServer(NotificationPublisher())) + val modern = capabilities(handler, "server/discover") + modern.tools.flatMap(_.listChanged) shouldBe Some(false) + modern.resources.flatMap(_.subscribe) shouldBe Some(false) + val listenRequest = listen(RequestId(1), Json.obj("toolsListChanged" -> true.asJson)) + handler.listenRequest(listenRequest, Nil) shouldBe None + val response = handler.handleJsonRpc(listenRequest, Nil, _ => ???) + response.statusCode shouldBe StatusCode.NotFound + response.body.flatMap(_.hcursor.downField("error").get[Int]("code").toOption) shouldBe Some(JSONRPCErrorCodes.MethodNotFound.code) + + "a subscription" should "start with the acknowledgement and carry the subscription id on every message" in: + val publisher = NotificationPublisher() + val output = RecordingOutput() + val _ = publisher.open(RequestId(3), SubscriptionFilter(toolsListChanged = Some(true)), output) + publisher.toolsListChanged() + output.methods shouldBe List(Some("notifications/subscriptions/acknowledged"), Some("notifications/tools/list_changed")) + output.messages.toList.map(subscriptionId) shouldBe List.fill(2)(Some(3.asJson)) + output.messages.head.hcursor.downField("params").get[SubscriptionFilter]("notifications") shouldBe + Right(SubscriptionFilter(toolsListChanged = Some(true))) + + it should "send only the notification types and resource URIs the filter names" in: + val publisher = NotificationPublisher() + val output = RecordingOutput() + val _ = publisher.open(RequestId("s"), SubscriptionFilter(resourceSubscriptions = Some(List("test://a"))), output) + publisher.toolsListChanged() + publisher.promptsListChanged() + publisher.resourcesListChanged() + publisher.resourceUpdated("test://b") + publisher.resourceUpdated("test://a") + output.methods.drop(1) shouldBe List(Some("notifications/resources/updated")) + output.messages.last.hcursor.downField("params").get[String]("uri") shouldBe Right("test://a") + + it should "keep several subscriptions apart" in: + val publisher = NotificationPublisher() + val tools = RecordingOutput() + val prompts = RecordingOutput() + val _ = publisher.open(RequestId(1), SubscriptionFilter(toolsListChanged = Some(true)), tools) + val _ = publisher.open(RequestId(2), SubscriptionFilter(promptsListChanged = Some(true), toolsListChanged = Some(true)), prompts) + publisher.promptsListChanged() + publisher.toolsListChanged() + tools.methods.drop(1) shouldBe List(Some("notifications/tools/list_changed")) + tools.messages.toList.map(subscriptionId).distinct shouldBe List(Some(1.asJson)) + prompts.methods.drop(1) shouldBe List(Some("notifications/prompts/list_changed"), Some("notifications/tools/list_changed")) + prompts.messages.toList.map(subscriptionId).distinct shouldBe List(Some(2.asJson)) + + it should "get nothing more after the client cancels it" in: + val publisher = NotificationPublisher() + val output = RecordingOutput() + val subscription = publisher.open(RequestId(1), SubscriptionFilter(toolsListChanged = Some(true)), output) + subscription.cancel() + publisher.toolsListChanged() + publisher.close() + output.methods shouldBe List(Some("notifications/subscriptions/acknowledged")) + output.closed shouldBe false + publisher.openSubscriptions shouldBe 0 + + it should "end with a successful listen result when the publisher closes" in: + val publisher = NotificationPublisher() + val output = RecordingOutput() + val _ = publisher.open(RequestId(5), SubscriptionFilter(toolsListChanged = Some(true)), output) + publisher.close() + publisher.toolsListChanged() + val result = output.messages.last + result.hcursor.get[Int]("id") shouldBe Right(5) + result.hcursor.downField("result").get[String]("resultType") shouldBe Right("complete") + result.hcursor.downField("result").downField("_meta").downField(ProtocolMeta.SubscriptionId).focus shouldBe Some(5.asJson) + output.messages.size shouldBe 2 + output.closed shouldBe true + publisher.openSubscriptions shouldBe 0 + + it should "end at once when it opens after the publisher closed" in: + val publisher = NotificationPublisher() + publisher.close() + val output = RecordingOutput() + val _ = publisher.open(RequestId(1), SubscriptionFilter(), output) + output.messages.size shouldBe 2 + output.closed shouldBe true + + "stdio subscriptions" should "end on the client's notifications/cancelled, and send the result and notifications/cancelled at shutdown" in: + val publisher = NotificationPublisher() + val written = ListBuffer.empty[Json] + val stdio = StdioSubscriptions(written += _) + val filter = SubscriptionFilter(toolsListChanged = Some(true)) + stdio.listen(ListenRequest(RequestId(1), filter, publisher)) + stdio.listen(ListenRequest(RequestId(2), filter, publisher)) + stdio.cancel( + (JSONRPCMessage + .Notification(method = "notifications/cancelled", params = Some(Json.obj("requestId" -> 1.asJson))): JSONRPCMessage).asJson + ) + publisher.toolsListChanged() + stdio.endAll() + val tail = written.toList.drop(2) + tail.map(subscriptionId) shouldBe List(Some(2.asJson), None, None) + tail(1).hcursor.get[Int]("id") shouldBe Right(2) + tail(2).hcursor.get[String]("method") shouldBe Right("notifications/cancelled") + tail(2).hcursor.downField("params").get[Int]("requestId") shouldBe Right(2) + publisher.openSubscriptions shouldBe 0 From 9923d42c6b7d62145a506cee11484fac5a343886 Mon Sep 17 00:00:00 2001 From: Ondra Pelech Date: Thu, 19 Nov 2026 16:41:54 +0100 Subject: [PATCH 10/31] feat(T16): serve subscriptions/listen streams over streaming HTTP The streaming HTTP transports answer an accepted subscriptions/listen request with an SSE stream that stays open: the acknowledgement first, then the publisher's notifications that the filter asks for. ZIO, Ox and Pekko each deliver into their own stream and cancel the subscription when the client closes the stream. A subscription is registered before it is acknowledged, and gets no notification before the acknowledgement, so an event published right after the client sees the acknowledgement is not lost. Shared HTTP tests run on all three backends. --- .../server/ox/OxServerHttpTransport.scala | 13 +- .../chimp/server/ox/OxMcpServerHttpSpec.scala | 7 + .../pekko/PekkoServerHttpTransport.scala | 15 +- .../server/pekko/PekkoMcpServerHttpSpec.scala | 14 +- .../server/zio/ZioServerHttpTransport.scala | 20 ++- .../server/zio/ZioMcpServerHttpSpec.scala | 11 ++ .../chimp/server/NotificationPublisher.scala | 21 +-- .../transport/JsonRpcHttpResponses.scala | 13 +- .../SecuredServerStreamingHttpTransport.scala | 10 +- .../ServerStreamingHttpTransport.scala | 15 +- .../McpServerSubscriptionHttpTests.scala | 136 ++++++++++++++++++ 11 files changed, 253 insertions(+), 22 deletions(-) create mode 100644 server/src/test/scala/chimp/server/McpServerSubscriptionHttpTests.scala diff --git a/server-streaming/server-ox/src/main/scala/chimp/server/ox/OxServerHttpTransport.scala b/server-streaming/server-ox/src/main/scala/chimp/server/ox/OxServerHttpTransport.scala index c997361d..b6d4823b 100644 --- a/server-streaming/server-ox/src/main/scala/chimp/server/ox/OxServerHttpTransport.scala +++ b/server-streaming/server-ox/src/main/scala/chimp/server/ox/OxServerHttpTransport.scala @@ -1,7 +1,7 @@ package chimp.server.ox import chimp.protocol.JSONRPCMessage -import chimp.server.OutboundSink +import chimp.server.{ListenRequest, OutboundSink, SubscriptionOutput} import chimp.server.transport.ServerStreamingHttpTransport import io.circe.Json import io.circe.syntax.* @@ -32,3 +32,14 @@ final class OxServerHttpTransport(path: List[String]) extends ServerStreamingHtt try handle(sink).foreach(outbound.send) finally outbound.done() outbound.foreach(json => emit(ServerSentEvent(data = Some(json.noSpaces)))) + + private[server] def subscriptionStream(listen: ListenRequest): Flow[ServerSentEvent] = + Flow.usingEmit: emit => + val outbound = Channel.unlimited[Json] + val subscription = listen.open(new SubscriptionOutput: + def send(message: Json): Unit = + val _ = outbound.sendOrClosed(message) + def close(): Unit = + val _ = outbound.doneOrClosed()) + try outbound.foreach(json => emit(ServerSentEvent(data = Some(json.noSpaces)))) + finally subscription.cancel() diff --git a/server-streaming/server-ox/src/test/scala/chimp/server/ox/OxMcpServerHttpSpec.scala b/server-streaming/server-ox/src/test/scala/chimp/server/ox/OxMcpServerHttpSpec.scala index 317c9423..5a6fc7e8 100644 --- a/server-streaming/server-ox/src/test/scala/chimp/server/ox/OxMcpServerHttpSpec.scala +++ b/server-streaming/server-ox/src/test/scala/chimp/server/ox/OxMcpServerHttpSpec.scala @@ -9,6 +9,7 @@ import chimp.server.{ tool, McpServer, McpServerStreamingTests, + McpServerSubscriptionHttpTests, McpServerTests, SecuredMcpServer, SecuredMcpServerStreamingTests, @@ -31,11 +32,13 @@ import sttp.tapir.Schema import sttp.tapir.server.netty.sync.{NettySyncServer, OxStreams} import sttp.tapir.server.ServerEndpoint +import java.net.URI import scala.concurrent.Future class OxMcpServerHttpSpec extends McpServerTests[Identity] with McpServerStreamingTests[Identity] + with McpServerSubscriptionHttpTests[Identity] with SecuredMcpServerTests[Identity] with SecuredMcpServerStreamingTests[Identity] with SyncToFuture: @@ -55,6 +58,10 @@ class OxMcpServerHttpSpec try test(McpClient.bidirectional(transport, clientInfo, protocolVersion = clientProtocolVersion)) finally transport.close() + override protected def withStreamingHttpEndpoint(server: StreamingMcpServer[Identity])(test: URI => Assertion): Future[Assertion] = + withHttpServer(OxServerHttpTransport(List("mcp")).serve(server)): (port, _, _) => + test(URI.create(s"http://localhost:$port/mcp")) + override protected def withSecuredServer( server: SecuredMcpServer[Identity, String, String, User], token: String diff --git a/server-streaming/server-pekko/src/main/scala/chimp/server/pekko/PekkoServerHttpTransport.scala b/server-streaming/server-pekko/src/main/scala/chimp/server/pekko/PekkoServerHttpTransport.scala index 99f42d20..b1df7a5c 100644 --- a/server-streaming/server-pekko/src/main/scala/chimp/server/pekko/PekkoServerHttpTransport.scala +++ b/server-streaming/server-pekko/src/main/scala/chimp/server/pekko/PekkoServerHttpTransport.scala @@ -1,7 +1,7 @@ package chimp.server.pekko import chimp.protocol.JSONRPCMessage -import chimp.server.OutboundSink +import chimp.server.{ListenRequest, OutboundSink, SubscriptionOutput} import chimp.server.transport.ServerStreamingHttpTransport import io.circe.Json import io.circe.syntax.* @@ -57,3 +57,16 @@ final class PekkoServerHttpTransport( queue.complete() NotUsed .map(json => ServerSentEvent(data = Some(json.noSpaces))) + + private[server] def subscriptionStream(listen: ListenRequest): EventStream = + Source + .queue[Json](outboundBufferSize, OverflowStrategy.backpressure, maxConcurrentSends) + .mapMaterializedValue: queue => + listen.open(new SubscriptionOutput: + def send(message: Json): Unit = + val _ = PekkoOutbound.offer(queue, message) + def close(): Unit = queue.complete()) + .watchTermination(): (subscription, done) => + done.onComplete(_ => subscription.cancel()) + NotUsed + .map(json => ServerSentEvent(data = Some(json.noSpaces))) diff --git a/server-streaming/server-pekko/src/test/scala/chimp/server/pekko/PekkoMcpServerHttpSpec.scala b/server-streaming/server-pekko/src/test/scala/chimp/server/pekko/PekkoMcpServerHttpSpec.scala index e80782bf..d5066ccb 100644 --- a/server-streaming/server-pekko/src/test/scala/chimp/server/pekko/PekkoMcpServerHttpSpec.scala +++ b/server-streaming/server-pekko/src/test/scala/chimp/server/pekko/PekkoMcpServerHttpSpec.scala @@ -7,6 +7,7 @@ import chimp.server.transport.SecuredServerStreamingHttpTransport import chimp.server.{ McpServer, McpServerStreamingTests, + McpServerSubscriptionHttpTests, McpServerTests, SecuredMcpServer, SecuredMcpServerStreamingTests, @@ -24,12 +25,14 @@ import sttp.model.Uri.UriContext import sttp.tapir.server.pekkohttp.PekkoHttpServerInterpreter import sttp.tapir.server.ServerEndpoint +import java.net.URI import scala.concurrent.duration.DurationInt -import scala.concurrent.{ExecutionContext, Future} +import scala.concurrent.{blocking, ExecutionContext, Future} class PekkoMcpServerHttpSpec extends McpServerTests[Future] with McpServerStreamingTests[Future] + with McpServerSubscriptionHttpTests[Future] with SecuredMcpServerTests[Future] with SecuredMcpServerStreamingTests[Future] with PekkoToFuture: @@ -45,6 +48,15 @@ class PekkoMcpServerHttpSpec withHttpServer(PekkoServerHttpTransport(List("mcp")).serve(server), Nil): transport => McpClient.bidirectional(transport, clientInfo).flatMap(test) + override protected def withStreamingHttpEndpoint(server: StreamingMcpServer[Future])(test: URI => Assertion): Future[Assertion] = + given ExecutionContext = actorSystem.dispatcher + Http() + .newServerAt("localhost", 0) + .bind(PekkoHttpServerInterpreter().toRoute(PekkoServerHttpTransport(List("mcp")).serve(server))) + .flatMap: binding => + Future(blocking(test(URI.create(s"http://localhost:${binding.localAddress.getPort}/mcp")))) + .transformWith(result => binding.terminate(5.seconds).transform(_ => result)) + override protected def withSecuredServer( server: SecuredMcpServer[Future, String, String, User], token: String diff --git a/server-streaming/server-zio/src/main/scala/chimp/server/zio/ZioServerHttpTransport.scala b/server-streaming/server-zio/src/main/scala/chimp/server/zio/ZioServerHttpTransport.scala index 9b2c4d6e..43b68f5d 100644 --- a/server-streaming/server-zio/src/main/scala/chimp/server/zio/ZioServerHttpTransport.scala +++ b/server-streaming/server-zio/src/main/scala/chimp/server/zio/ZioServerHttpTransport.scala @@ -1,7 +1,7 @@ package chimp.server.zio import chimp.protocol.JSONRPCMessage -import chimp.server.OutboundSink +import chimp.server.{ListenRequest, OutboundSink, SubscriptionOutput} import chimp.server.transport.ServerStreamingHttpTransport import io.circe.Json import io.circe.syntax.* @@ -10,7 +10,7 @@ import sttp.model.sse.ServerSentEvent import sttp.tapir.* import sttp.tapir.ztapir.ZioServerSentEvents import zio.stream.{Stream, ZStream} -import zio.{Queue, Task, ZIO} +import zio.{Queue, Task, Unsafe, ZIO} import java.nio.charset.StandardCharsets @@ -42,6 +42,22 @@ final class ZioServerHttpTransport(path: List[String]) extends ServerStreamingHt } } + private[server] def subscriptionStream(listen: ListenRequest): EventStream = + ZStream.unwrapScoped { + for + queue <- ZIO.acquireRelease(Queue.unbounded[Outbound])(_.shutdown) + runtime <- ZIO.runtime[Any] + output = new SubscriptionOutput: + def send(message: Json): Unit = offer(Outbound.Message(message)) + def close(): Unit = offer(Outbound.Close) + private def offer(outbound: Outbound): Unit = + Unsafe.unsafe { implicit unsafe => + val _ = runtime.unsafe.run(queue.offer(outbound)) + } + _ <- ZIO.acquireRelease(ZIO.succeed(listen.open(output)))(subscription => ZIO.succeed(subscription.cancel())) + yield ZStream.fromQueue(queue).collectWhile { case Outbound.Message(json) => ServerSentEvent(data = Some(json.noSpaces)) } + } + private enum Outbound: case Message(json: Json) case Close diff --git a/server-streaming/server-zio/src/test/scala/chimp/server/zio/ZioMcpServerHttpSpec.scala b/server-streaming/server-zio/src/test/scala/chimp/server/zio/ZioMcpServerHttpSpec.scala index 251b88c3..9a2eb2e3 100644 --- a/server-streaming/server-zio/src/test/scala/chimp/server/zio/ZioMcpServerHttpSpec.scala +++ b/server-streaming/server-zio/src/test/scala/chimp/server/zio/ZioMcpServerHttpSpec.scala @@ -8,6 +8,7 @@ import chimp.server.transport.SecuredServerStreamingHttpTransport import chimp.server.{ McpServer, McpServerStreamingTests, + McpServerSubscriptionHttpTests, McpServerTests, SecuredMcpServer, SecuredMcpServerStreamingTests, @@ -26,11 +27,13 @@ import sttp.tapir.server.ServerEndpoint import zio.http.Server import zio.{Scope, Task, ZIO} +import java.net.URI import scala.concurrent.Future class ZioMcpServerHttpSpec extends McpServerTests[Task] with McpServerStreamingTests[Task] + with McpServerSubscriptionHttpTests[Task] with SecuredMcpServerTests[Task] with SecuredMcpServerStreamingTests[Task] with ZioToFuture: @@ -46,6 +49,14 @@ class ZioMcpServerHttpSpec withHttpServer(ZioServerHttpTransport(List("mcp")).serve(server), Nil): transport => McpClient.bidirectional(transport, clientInfo, protocolVersion = clientProtocolVersion).flatMap(test) + override protected def withStreamingHttpEndpoint(server: StreamingMcpServer[Task])(test: URI => Assertion): Future[Assertion] = + toFuture: + val routes = ZioHttpInterpreter().toHttp(ZioServerHttpTransport(List("mcp")).serve(server)) + (for + port <- Server.install(routes) + result <- ZIO.attemptBlocking(test(URI.create(s"http://localhost:$port/mcp"))) + yield result).provide(Server.defaultWithPort(0)) + override protected def withSecuredServer( server: SecuredMcpServer[Task, String, String, User], token: String diff --git a/server/src/main/scala/chimp/server/NotificationPublisher.scala b/server/src/main/scala/chimp/server/NotificationPublisher.scala index 2fc5c869..0eb25833 100644 --- a/server/src/main/scala/chimp/server/NotificationPublisher.scala +++ b/server/src/main/scala/chimp/server/NotificationPublisher.scala @@ -46,8 +46,8 @@ final class NotificationPublisher: private[server] def open(id: RequestId, filter: SubscriptionFilter, output: SubscriptionOutput): Subscription = val key = nextKey.getAndIncrement() val subscription = Subscription(id, filter, output, () => { val _ = subscriptions.remove(key) }) + val _ = subscriptions.put(key, subscription) subscription.acknowledge() - subscriptions.put(key, subscription) if closed.get then subscription.end() subscription @@ -83,28 +83,31 @@ private[server] final class Subscription( unregister: () => Unit ): private val active = AtomicBoolean(true) + private val acknowledged = AtomicBoolean(false) private val meta: Map[String, Json] = Map(ProtocolMeta.SubscriptionId -> id.asJson) private val metaParams: Json = Json.obj("_meta" -> meta.asJson) def isActive: Boolean = active.get - def acknowledge(): Unit = - send( - JSONRPCMessage.Notification( - method = "notifications/subscriptions/acknowledged", - params = Some(SubscriptionsAcknowledgedParams(filter, Some(meta)).asJson) + def acknowledge(): Unit = synchronized: + if active.get then + send( + JSONRPCMessage.Notification( + method = "notifications/subscriptions/acknowledged", + params = Some(SubscriptionsAcknowledgedParams(filter, Some(meta)).asJson) + ) ) - ) + acknowledged.set(true) def deliver(event: ServerEvent): Unit = - if active.get && event.accepted(filter) then send(event.notification(metaParams)) + if acknowledged.get && active.get && event.accepted(filter) then send(event.notification(metaParams)) /** Ends the subscription because the client ended it; sends nothing. */ def cancel(): Unit = if active.compareAndSet(true, false) then unregister() /** Ends the subscription on the server's initiative, with a successful `subscriptions/listen` result. */ - def end(): Unit = + def end(): Unit = synchronized: if active.compareAndSet(true, false) then unregister() send(JSONRPCMessage.Response(id = id, result = SubscriptionsListenResult(_meta = Some(meta)).asJson)) diff --git a/server/src/main/scala/chimp/server/transport/JsonRpcHttpResponses.scala b/server/src/main/scala/chimp/server/transport/JsonRpcHttpResponses.scala index 929f3ad2..82112502 100644 --- a/server/src/main/scala/chimp/server/transport/JsonRpcHttpResponses.scala +++ b/server/src/main/scala/chimp/server/transport/JsonRpcHttpResponses.scala @@ -1,6 +1,6 @@ package chimp.server.transport -import chimp.server.{McpResponse, OriginCheck, OutboundSink} +import chimp.server.{ListenRequest, McpResponse, OriginCheck, OutboundSink} import io.circe.Json import sttp.model.{Header, HeaderNames, StatusCode} import sttp.monad.MonadError @@ -26,16 +26,21 @@ private[transport] type JsonRejection = (StatusCode, Json) private[transport] val jsonRejectionOutput: EndpointOutput[JsonRejection] = statusCode.and(jsonBody[Json]) /** Checks the origin, then validates the request with `rejection` (runs no tool logic). A rejection - for example a modern validation error - - * is returned on the left, to be sent as a plain JSON error with its own HTTP status; otherwise `handle` runs inside a 200 event stream. + * is returned on the left, to be sent as a plain JSON error with its own HTTP status. An accepted `subscriptions/listen` request gets a + * 200 subscription stream, which stays open until one side ends it; any other request runs `handle` inside a 200 event stream. */ private[transport] def respondWithEventStream[F[_], Caps]( originCheck: OriginCheck, headers: Seq[Header], backend: ServerStreamingHttpTransport[F, Caps], - rejection: => Option[McpResponse] + rejection: => Option[McpResponse], + listen: => Option[ListenRequest] )(handle: OutboundSink[F] => F[Option[Json]])(using m: MonadError[F]): F[Either[JsonRejection, (StatusCode, backend.EventStream)]] = if !originAllowed(originCheck, headers) then m.unit(Right((StatusCode.Forbidden, backend.emptyStream))) else rejection match case Some(response) => m.unit(Left((response.statusCode, response.body.getOrElse(Json.Null)))) - case None => backend.eventStream(handle).map(events => Right((StatusCode.Ok, events))) + case None => + listen match + case Some(request) => m.unit(Right((StatusCode.Ok, backend.subscriptionStream(request)))) + case None => backend.eventStream(handle).map(events => Right((StatusCode.Ok, events))) diff --git a/server/src/main/scala/chimp/server/transport/SecuredServerStreamingHttpTransport.scala b/server/src/main/scala/chimp/server/transport/SecuredServerStreamingHttpTransport.scala index 16d0df5c..5291100a 100644 --- a/server/src/main/scala/chimp/server/transport/SecuredServerStreamingHttpTransport.scala +++ b/server/src/main/scala/chimp/server/transport/SecuredServerStreamingHttpTransport.scala @@ -27,7 +27,7 @@ final case class SecuredServerStreamingHttpTransport[F[_], Caps, S, E, P]( backend: ServerStreamingHttpTransport[F, Caps] ): def serve(server: SecuredStreamingMcpServer[F, S, E, P]): ServerEndpoint[Caps, F] = - val handler = new McpHandler[F, SecuredStreamingServerContext[F, P]](server) + val handler = new McpHandler[F, SecuredStreamingServerContext[F, P]](server, canListen = true) val mcpEndpoint = endpoint.post .securityIn(server.securityInput) .in(path.foldLeft(emptyInput)((inputSoFar, pathComponent) => inputSoFar / pathComponent)) @@ -44,7 +44,13 @@ final case class SecuredServerStreamingHttpTransport[F[_], Caps, S, E, P]( me => { (principal: P) => (input: (Seq[Header], Json)) => val (headers, json) = input given MonadError[F] = me - respondWithEventStream(server.originCheck, headers, backend, handler.validateRequest(json, headers)) { sink => + respondWithEventStream( + server.originCheck, + headers, + backend, + handler.validateRequest(json, headers), + handler.listenRequest(json, headers) + ) { sink => val makeContext: RequestInfo => SecuredStreamingServerContext[F, P] = info => SinkSecuredStreamingServerContext(sink, info, principal) handler.handleJsonRpc(json, headers, makeContext).map(_.body) diff --git a/server/src/main/scala/chimp/server/transport/ServerStreamingHttpTransport.scala b/server/src/main/scala/chimp/server/transport/ServerStreamingHttpTransport.scala index cadf6428..a50ff117 100644 --- a/server/src/main/scala/chimp/server/transport/ServerStreamingHttpTransport.scala +++ b/server/src/main/scala/chimp/server/transport/ServerStreamingHttpTransport.scala @@ -28,8 +28,13 @@ abstract class ServerStreamingHttpTransport[F[_], Caps](path: List[String]) exte def emptyStream: EventStream def eventStream(handle: OutboundSink[F] => F[Option[Json]]): F[EventStream] + /** The stream of an accepted `subscriptions/listen` request. It opens the subscription when the stream starts, and cancels it when the + * client closes the stream. The server ends it by closing the subscription's output. + */ + private[server] def subscriptionStream(listen: ListenRequest): EventStream + final def serve(server: StreamingMcpServer[F]): ServerEndpoint[Caps, F] = - val handler = new McpHandler[F, StreamingServerContext[F]](server) + val handler = new McpHandler[F, StreamingServerContext[F]](server, canListen = true) val endpoint = sttp.tapir.endpoint.post .in(path.foldLeft(emptyInput)((inputSoFar, pathComponent) => inputSoFar / pathComponent)) .in(extractFromRequest(_.headers)) @@ -43,7 +48,13 @@ abstract class ServerStreamingHttpTransport[F[_], Caps](path: List[String]) exte me => { (input: (Seq[Header], Json)) => val (headers, json) = input given MonadError[F] = me - respondWithEventStream(server.originCheck, headers, this, handler.validateRequest(json, headers)) { sink => + respondWithEventStream( + server.originCheck, + headers, + this, + handler.validateRequest(json, headers), + handler.listenRequest(json, headers) + ) { sink => val makeContext: RequestInfo => StreamingServerContext[F] = info => SinkStreamingServerContext(sink, info) handler.handleJsonRpc(json, headers, makeContext).map(_.body) diff --git a/server/src/test/scala/chimp/server/McpServerSubscriptionHttpTests.scala b/server/src/test/scala/chimp/server/McpServerSubscriptionHttpTests.scala new file mode 100644 index 00000000..dd801177 --- /dev/null +++ b/server/src/test/scala/chimp/server/McpServerSubscriptionHttpTests.scala @@ -0,0 +1,136 @@ +package chimp.server + +import chimp.protocol.ProtocolMeta +import io.circe.syntax.* +import io.circe.{parser, Codec, Json} +import org.scalatest.Assertion +import org.scalatest.flatspec.AsyncFlatSpec +import org.scalatest.matchers.should.Matchers +import sttp.tapir.Schema + +import java.net.URI +import java.net.http.{HttpClient, HttpRequest, HttpResponse} +import java.util.concurrent.{LinkedBlockingQueue, TimeUnit} +import scala.concurrent.Future +import scala.jdk.CollectionConverters.* +import scala.util.Try + +/** `subscriptions/listen` over Streamable HTTP. Uses a plain HTTP client, because chimp's client does not listen yet. */ +trait McpServerSubscriptionHttpTests[F[_]] extends AsyncFlatSpec with Matchers: + this: ToFuture[F] => + + /** Serves `server` on a streaming HTTP endpoint and runs the blocking `test` with the endpoint's URI. */ + protected def withStreamingHttpEndpoint(server: StreamingMcpServer[F])(test: URI => Assertion): Future[Assertion] + + private case class NoInput() derives Codec, Schema + + private def listeningServer(publisher: NotificationPublisher): StreamingMcpServer[F] = + StreamingMcpServer[F]() + .addTool(tool("noop").input[NoInput].serverLogic[F]((_, _) => monad.unit(ToolResult.text("ok")))) + .addResource(resource("test://a").name("a").serverLogic[F](_ => monad.unit(Right(Nil)))) + .withPublisher(publisher) + + private val httpClient = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build() + + private final class SseStream(response: HttpResponse[java.util.stream.Stream[String]]): + private val messages = LinkedBlockingQueue[Option[Json]]() + private val reader = Thread: () => + try + response + .body() + .iterator() + .asScala + .collect { case s"data:$data" => parser.parse(data.trim).toOption } + .flatten + .foreach(json => messages.put(Some(json))) + catch case _: Exception => () + finally messages.put(None) + reader.setDaemon(true) + reader.start() + + def status: Int = response.statusCode() + + /** The next message, or `None` when the stream ended. */ + def next(): Option[Json] = Option(messages.poll(10, TimeUnit.SECONDS)).getOrElse(fail("No message on the stream within 10 seconds")) + + def close(): Unit = Try(response.body().close()).getOrElse(()) + + private def listen(uri: URI, id: Json, filter: Json): SseStream = + val meta = Json.obj(ProtocolMeta.ProtocolVersionKey -> "2026-07-28".asJson, ProtocolMeta.ClientCapabilities -> Json.obj()) + val body = Json.obj( + "jsonrpc" -> "2.0".asJson, + "id" -> id, + "method" -> "subscriptions/listen".asJson, + "params" -> Json.obj("notifications" -> filter, "_meta" -> meta) + ) + val request = HttpRequest + .newBuilder(uri) + .header("Content-Type", "application/json") + .header("Accept", "application/json, text/event-stream") + .header(ProtocolMeta.ProtocolVersionHeader, "2026-07-28") + .header("Mcp-Method", "subscriptions/listen") + .POST(HttpRequest.BodyPublishers.ofString(body.noSpaces)) + .build() + SseStream(httpClient.send(request, HttpResponse.BodyHandlers.ofLines())) + + private def method(message: Option[Json]): Option[String] = message.flatMap(_.hcursor.get[String]("method").toOption) + + private def subscriptionId(message: Option[Json]): Option[Json] = + message.flatMap(_.hcursor.downField("params").downField("_meta").downField(ProtocolMeta.SubscriptionId).focus) + + private def eventually(condition: => Boolean): Boolean = + Iterator.continually { Thread.sleep(20); condition }.take(250).exists(identity) + + "a streaming HTTP server" should "acknowledge a subscription first and send it only the requested notifications" in: + val publisher = NotificationPublisher() + withStreamingHttpEndpoint(listeningServer(publisher)): uri => + val filter = Json.obj( + "toolsListChanged" -> true.asJson, + "promptsListChanged" -> true.asJson, + "resourceSubscriptions" -> List("test://a").asJson + ) + val stream = listen(uri, 11.asJson, filter) + try + stream.status shouldBe 200 + val ack = stream.next() + method(ack) shouldBe Some("notifications/subscriptions/acknowledged") + ack.flatMap(_.hcursor.downField("params").downField("notifications").focus) shouldBe + Some(Json.obj("resourceSubscriptions" -> List("test://a").asJson, "toolsListChanged" -> true.asJson)) + publisher.promptsListChanged() + publisher.resourcesListChanged() + publisher.resourceUpdated("test://b") + publisher.resourceUpdated("test://a") + publisher.toolsListChanged() + val updated = stream.next() + val toolsChanged = stream.next() + method(updated) shouldBe Some("notifications/resources/updated") + updated.flatMap(_.hcursor.downField("params").get[String]("uri").toOption) shouldBe Some("test://a") + method(toolsChanged) shouldBe Some("notifications/tools/list_changed") + List(ack, updated, toolsChanged).map(subscriptionId) shouldBe List.fill(3)(Some(11.asJson)) + finally stream.close() + + it should "stop publishing to a subscription when the client closes its stream" in: + val publisher = NotificationPublisher() + withStreamingHttpEndpoint(listeningServer(publisher)): uri => + val stream = listen(uri, 1.asJson, Json.obj("toolsListChanged" -> true.asJson)) + method(stream.next()) shouldBe Some("notifications/subscriptions/acknowledged") + publisher.openSubscriptions shouldBe 1 + stream.close() + eventually { publisher.toolsListChanged(); publisher.openSubscriptions == 0 } shouldBe true + + it should "end every subscription with a successful listen result when the publisher closes" in: + val publisher = NotificationPublisher() + withStreamingHttpEndpoint(listeningServer(publisher)): uri => + val first = listen(uri, 1.asJson, Json.obj("toolsListChanged" -> true.asJson)) + val second = listen(uri, "second".asJson, Json.obj("resourcesListChanged" -> true.asJson)) + try + List(first.next(), second.next()).map(subscriptionId) shouldBe List(Some(1.asJson), Some("second".asJson)) + publisher.close() + val results = List(first.next(), second.next()) + results.map(_.flatMap(_.hcursor.downField("id").focus)) shouldBe List(Some(1.asJson), Some("second".asJson)) + results.map(_.flatMap(_.hcursor.downField("result").downField("_meta").downField(ProtocolMeta.SubscriptionId).focus)) shouldBe + List(Some(1.asJson), Some("second".asJson)) + List(first.next(), second.next()) shouldBe List(None, None) + finally + first.close() + second.close() From d8d6f603c8b1505c8c66a4b478bf2c9d7e68932c Mon Sep 17 00:00:00 2001 From: Ondra Pelech Date: Thu, 19 Nov 2026 16:43:51 +0100 Subject: [PATCH 11/31] feat(T16): serve subscriptions/listen over stdio All subscriptions of a stdio connection share its output and are told apart by the subscription id. The client ends one with notifications/cancelled naming the listen request. When the input ends, the server ends each open subscription with a successful listen result followed by notifications/cancelled. The sync, Ox, ZIO and Pekko stdio transports share this logic; the ZIO transport now serialises its writes, because notifications can arrive from other threads. --- .../server/ox/OxServerStdioTransport.scala | 29 +++++--- .../pekko/PekkoServerStdioTransport.scala | 26 +++++-- .../server/zio/ZioServerStdioTransport.scala | 28 ++++++-- .../chimp/server/NotificationPublisher.scala | 14 +++- .../transport/ServerStdioTransport.scala | 19 ++++-- .../server/NotificationPublisherSpec.scala | 2 +- .../server/ServerStdioTransportTests.scala | 67 +++++++++++++++++-- 7 files changed, 152 insertions(+), 33 deletions(-) diff --git a/server-streaming/server-ox/src/main/scala/chimp/server/ox/OxServerStdioTransport.scala b/server-streaming/server-ox/src/main/scala/chimp/server/ox/OxServerStdioTransport.scala index 1492d751..5142983b 100644 --- a/server-streaming/server-ox/src/main/scala/chimp/server/ox/OxServerStdioTransport.scala +++ b/server-streaming/server-ox/src/main/scala/chimp/server/ox/OxServerStdioTransport.scala @@ -2,7 +2,15 @@ package chimp.server.ox import chimp.protocol.JSONRPCMessage import chimp.server.transport.ServerStreamingStdioTransport -import chimp.server.{McpHandler, OutboundSink, RequestInfo, SinkStreamingServerContext, StreamingMcpServer, StreamingServerContext} +import chimp.server.{ + McpHandler, + OutboundSink, + RequestInfo, + SinkStreamingServerContext, + StdioSubscriptions, + StreamingMcpServer, + StreamingServerContext +} import chimp.transport.{StdioFraming, StdioLineReader} import io.circe.syntax.* import io.circe.{parser, Json} @@ -24,7 +32,7 @@ final class OxServerStdioTransport( def serve(server: StreamingMcpServer[Identity]): Unit = given MonadError[Identity] = IdentityMonad - val handler = new McpHandler[Identity, StreamingServerContext[Identity]](server) + val handler = new McpHandler[Identity, StreamingServerContext[Identity]](server, canListen = true) val reader = StdioLineReader(in, maxLineLength) val writer = BufferedWriter(OutputStreamWriter(out, StandardCharsets.UTF_8)) @@ -42,12 +50,17 @@ final class OxServerStdioTransport( val makeContext: RequestInfo => StreamingServerContext[Identity] = info => SinkStreamingServerContext(sink, info) - reader.lines - .filter(_.nonEmpty) - .foreach: line => - parser.parse(line) match - case Right(json) => handler.handleJsonRpc(json, Nil, makeContext).body.foreach(outbound.send) - case Left(error) => log.warn(s"Failed to parse JSON-RPC line: ${error.getMessage}; raw: $line") + val subscriptions = StdioSubscriptions(handler, json => { val _ = outbound.sendOrClosed(json) }) + + try + reader.lines + .filter(_.nonEmpty) + .foreach: line => + parser.parse(line) match + case Right(json) => + if !subscriptions.accept(json) then handler.handleJsonRpc(json, Nil, makeContext).body.foreach(outbound.send) + case Left(error) => log.warn(s"Failed to parse JSON-RPC line: ${error.getMessage}; raw: $line") + finally subscriptions.endAll() outbound.done() writerFork.join() diff --git a/server-streaming/server-pekko/src/main/scala/chimp/server/pekko/PekkoServerStdioTransport.scala b/server-streaming/server-pekko/src/main/scala/chimp/server/pekko/PekkoServerStdioTransport.scala index d181bf86..734bb927 100644 --- a/server-streaming/server-pekko/src/main/scala/chimp/server/pekko/PekkoServerStdioTransport.scala +++ b/server-streaming/server-pekko/src/main/scala/chimp/server/pekko/PekkoServerStdioTransport.scala @@ -2,7 +2,15 @@ package chimp.server.pekko import chimp.protocol.JSONRPCMessage import chimp.server.transport.ServerStreamingStdioTransport -import chimp.server.{McpHandler, OutboundSink, RequestInfo, SinkStreamingServerContext, StreamingMcpServer, StreamingServerContext} +import chimp.server.{ + McpHandler, + OutboundSink, + RequestInfo, + SinkStreamingServerContext, + StdioSubscriptions, + StreamingMcpServer, + StreamingServerContext +} import chimp.transport.{McpLineTooLongException, StdioFraming} import io.circe.syntax.* import io.circe.{parser, Json} @@ -28,7 +36,7 @@ final class PekkoServerStdioTransport( private given MonadError[Future] = FutureMonad() def serve(server: StreamingMcpServer[Future]): Future[Unit] = - val handler = new McpHandler[Future, StreamingServerContext[Future]](server) + val handler = new McpHandler[Future, StreamingServerContext[Future]](server, canListen = true) val (outbound, writing) = Source .queue[Json](PekkoOutbound.defaultBufferSize, OverflowStrategy.backpressure, PekkoOutbound.defaultMaxConcurrentSends) @@ -42,30 +50,36 @@ final class PekkoServerStdioTransport( val makeContext: RequestInfo => StreamingServerContext[Future] = info => SinkStreamingServerContext(sink, info) + val subscriptions = StdioSubscriptions(handler, json => { val _ = PekkoOutbound.offer(outbound, json) }) + val reading = StreamConverters .fromInputStream(() => in) .via(Framing.delimiter(ByteString("\n"), maximumFrameLength = maxLineLength, allowTruncation = true)) .mapError { case _: Framing.FramingException => McpLineTooLongException(maxLineLength) } .map(_.utf8String.trim) .filter(_.nonEmpty) - .mapAsync(1)(line => handleLine(handler, makeContext, outbound, line)) + .mapAsync(1)(line => handleLine(handler, subscriptions, makeContext, outbound, line)) .runWith(Sink.ignore) reading.transformWith: result => + subscriptions.endAll() outbound.complete() writing.transform(_ => result.map(_ => ())) private def handleLine( handler: McpHandler[Future, StreamingServerContext[Future]], + subscriptions: StdioSubscriptions, makeContext: RequestInfo => StreamingServerContext[Future], outbound: SourceQueueWithComplete[Json], line: String ): Future[Unit] = parser.parse(line) match case Right(json) => - handler - .handleJsonRpc(json, Nil, makeContext) - .flatMap(response => response.body.fold(Future.unit)(body => PekkoOutbound.offer(outbound, body))) + if subscriptions.accept(json) then Future.unit + else + handler + .handleJsonRpc(json, Nil, makeContext) + .flatMap(response => response.body.fold(Future.unit)(body => PekkoOutbound.offer(outbound, body))) case Left(error) => log.warn(s"Failed to parse JSON-RPC line: ${error.getMessage}; raw: $line") Future.unit diff --git a/server-streaming/server-zio/src/main/scala/chimp/server/zio/ZioServerStdioTransport.scala b/server-streaming/server-zio/src/main/scala/chimp/server/zio/ZioServerStdioTransport.scala index 0c7cbefe..12aadfd6 100644 --- a/server-streaming/server-zio/src/main/scala/chimp/server/zio/ZioServerStdioTransport.scala +++ b/server-streaming/server-zio/src/main/scala/chimp/server/zio/ZioServerStdioTransport.scala @@ -1,7 +1,15 @@ package chimp.server.zio import chimp.protocol.JSONRPCMessage -import chimp.server.{McpHandler, OutboundSink, RequestInfo, SinkStreamingServerContext, StreamingMcpServer, StreamingServerContext} +import chimp.server.{ + McpHandler, + OutboundSink, + RequestInfo, + SinkStreamingServerContext, + StdioSubscriptions, + StreamingMcpServer, + StreamingServerContext +} import chimp.server.transport.ServerStreamingStdioTransport import chimp.transport.{StdioFraming, StdioLineReader} import io.circe.syntax.* @@ -23,16 +31,20 @@ final class ZioServerStdioTransport( private given MonadError[Task] = new RIOMonadError[Any] def serve(server: StreamingMcpServer[Task]): Task[Unit] = - val handler = new McpHandler[Task, StreamingServerContext[Task]](server) + val handler = new McpHandler[Task, StreamingServerContext[Task]](server, canListen = true) val reader = StdioLineReader(in, maxLineLength) val writer = BufferedWriter(OutputStreamWriter(out, StandardCharsets.UTF_8)) - def writeLine(json: Json): Task[Unit] = - ZIO.attemptBlocking: + def write(json: Json): Unit = + writer.synchronized: writer.write(json.noSpaces) writer.newLine() writer.flush() + def writeLine(json: Json): Task[Unit] = ZIO.attemptBlocking(write(json)) + + val subscriptions = StdioSubscriptions(handler, write) + val sink = new OutboundSink[Task]: def send(message: JSONRPCMessage): Task[Unit] = writeLine(message.asJson.deepDropNullValues) @@ -50,9 +62,13 @@ final class ZioServerStdioTransport( else parser.parse(line) match case Right(json) => - handler.handleJsonRpc(json, Nil, makeContext).flatMap(response => ZIO.foreachDiscard(response.body)(writeLine)) + ZIO + .attemptBlocking(subscriptions.accept(json)) + .flatMap: accepted => + if accepted then ZIO.unit + else handler.handleJsonRpc(json, Nil, makeContext).flatMap(response => ZIO.foreachDiscard(response.body)(writeLine)) case Left(error) => ZIO.succeed(log.warn(s"Failed to parse JSON-RPC line: ${error.getMessage}; raw: $line")) handled *> loop - loop + loop.ensuring(ZIO.attemptBlocking(subscriptions.endAll()).ignore) diff --git a/server/src/main/scala/chimp/server/NotificationPublisher.scala b/server/src/main/scala/chimp/server/NotificationPublisher.scala index 0eb25833..9eb2a28b 100644 --- a/server/src/main/scala/chimp/server/NotificationPublisher.scala +++ b/server/src/main/scala/chimp/server/NotificationPublisher.scala @@ -120,9 +120,21 @@ private[server] final case class ListenRequest(id: RequestId, filter: Subscripti def open(output: SubscriptionOutput): Subscription = publisher.open(id, filter, output) /** The subscriptions of one stdio connection. They share its single output and are told apart by the subscription id. */ -private[server] final class StdioSubscriptions(write: Json => Unit): +private[server] final class StdioSubscriptions(handler: McpHandler[?, ?], write: Json => Unit): private val open = ConcurrentHashMap[RequestId, Subscription]() + /** Opens a subscription if `message` is a `subscriptions/listen` request which the server accepts, and then gives `true`. Otherwise ends + * the subscription which a `notifications/cancelled` names, and gives `false`: the server handles the message as usual. + */ + def accept(message: Json): Boolean = + handler.listenRequest(message, Nil) match + case Some(request) => + listen(request) + true + case None => + cancel(message) + false + def listen(request: ListenRequest): Unit = val output = new SubscriptionOutput: def send(message: Json): Unit = write(message) diff --git a/server/src/main/scala/chimp/server/transport/ServerStdioTransport.scala b/server/src/main/scala/chimp/server/transport/ServerStdioTransport.scala index cd4da85c..87176c51 100644 --- a/server/src/main/scala/chimp/server/transport/ServerStdioTransport.scala +++ b/server/src/main/scala/chimp/server/transport/ServerStdioTransport.scala @@ -36,7 +36,7 @@ final class ServerStdioTransport( def serve(server: StreamingMcpServer[Identity]): Unit = given MonadError[Identity] = IdentityMonad - val handler = new McpHandler[Identity, StreamingServerContext[Identity]](server) + val handler = new McpHandler[Identity, StreamingServerContext[Identity]](server, canListen = true) val reader = StdioLineReader(in, maxLineLength) val writer = BufferedWriter(OutputStreamWriter(out, StandardCharsets.UTF_8)) @@ -52,9 +52,14 @@ final class ServerStdioTransport( val makeContext: RequestInfo => StreamingServerContext[Identity] = info => SinkStreamingServerContext(sink, info) - reader.lines - .filter(_.nonEmpty) - .foreach: line => - parser.parse(line) match - case Right(json) => handler.handleJsonRpc(json, Nil, makeContext).body.foreach(writeLine) - case Left(error) => log.warn(s"Failed to parse JSON-RPC line: ${error.getMessage}; raw: $line") + val subscriptions = StdioSubscriptions(handler, writeLine) + + try + reader.lines + .filter(_.nonEmpty) + .foreach: line => + parser.parse(line) match + case Right(json) => + if !subscriptions.accept(json) then handler.handleJsonRpc(json, Nil, makeContext).body.foreach(writeLine) + case Left(error) => log.warn(s"Failed to parse JSON-RPC line: ${error.getMessage}; raw: $line") + finally subscriptions.endAll() diff --git a/server/src/test/scala/chimp/server/NotificationPublisherSpec.scala b/server/src/test/scala/chimp/server/NotificationPublisherSpec.scala index c35931e4..e3ca557d 100644 --- a/server/src/test/scala/chimp/server/NotificationPublisherSpec.scala +++ b/server/src/test/scala/chimp/server/NotificationPublisherSpec.scala @@ -167,7 +167,7 @@ class NotificationPublisherSpec extends AnyFlatSpec with Matchers: "stdio subscriptions" should "end on the client's notifications/cancelled, and send the result and notifications/cancelled at shutdown" in: val publisher = NotificationPublisher() val written = ListBuffer.empty[Json] - val stdio = StdioSubscriptions(written += _) + val stdio = StdioSubscriptions(McpHandler(McpServer[Identity]()), written += _) val filter = SubscriptionFilter(toolsListChanged = Some(true)) stdio.listen(ListenRequest(RequestId(1), filter, publisher)) stdio.listen(ListenRequest(RequestId(2), filter, publisher)) diff --git a/server/src/test/scala/chimp/server/ServerStdioTransportTests.scala b/server/src/test/scala/chimp/server/ServerStdioTransportTests.scala index 34321d8c..1f63c9fb 100644 --- a/server/src/test/scala/chimp/server/ServerStdioTransportTests.scala +++ b/server/src/test/scala/chimp/server/ServerStdioTransportTests.scala @@ -1,6 +1,6 @@ package chimp.server -import chimp.protocol.{JSONRPCErrorCodes, LoggingLevel} +import chimp.protocol.{JSONRPCErrorCodes, LoggingLevel, ProtocolMeta} import chimp.transport.{McpLineTooLongException, StdioFraming} import io.circe.{parser, Codec, Json} import org.scalatest.flatspec.AnyFlatSpec @@ -30,9 +30,10 @@ trait ServerStdioTransportTests[F[_]] extends AnyFlatSpec with Matchers: private case class EchoInput(message: String) derives Codec, Schema private case class NoInput() derives Codec, Schema - private def server: StreamingMcpServer[F] = + private def server(publisher: NotificationPublisher): StreamingMcpServer[F] = StreamingMcpServer[F]() .withLoggingLevel(_ => monad.unit(())) + .withPublisher(publisher) .addTool(tool("echo").input[EchoInput].serverLogic[F]((in, _) => monad.unit(ToolResult.text(in.message)))) .addStreamingTool( tool("noisy") @@ -46,7 +47,12 @@ trait ServerStdioTransportTests[F[_]] extends AnyFlatSpec with Matchers: } ) - protected class StdioSession(toServer: PipedOutputStream, fromServer: PipedInputStream, val served: Future[Unit]): + protected class StdioSession( + toServer: PipedOutputStream, + fromServer: PipedInputStream, + val served: Future[Unit], + val publisher: NotificationPublisher + ): private val writer = BufferedWriter(OutputStreamWriter(toServer, StandardCharsets.UTF_8)) private val reader = BufferedReader(InputStreamReader(fromServer, StandardCharsets.UTF_8)) @@ -69,7 +75,8 @@ trait ServerStdioTransportTests[F[_]] extends AnyFlatSpec with Matchers: val fromServer = PipedInputStream() val serverOut = PipedOutputStream(fromServer) - val session = StdioSession(toServer, fromServer, runStdioServer(server, serverIn, serverOut, maxLineLength)) + val publisher = NotificationPublisher() + val session = StdioSession(toServer, fromServer, runStdioServer(server(publisher), serverIn, serverOut, maxLineLength), publisher) try body(session) finally session.closeInput() @@ -125,3 +132,55 @@ trait ServerStdioTransportTests[F[_]] extends AnyFlatSpec with Matchers: val failure = intercept[McpLineTooLongException](Await.result(session.served, 10.seconds)) failure.maxLineLength shouldBe 1024 } + + private val modernMeta = """{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}""" + + private def listen(id: Int, filter: String): String = + s"""{"jsonrpc":"2.0","id":$id,"method":"subscriptions/listen","params":{"notifications":$filter,"_meta":$modernMeta}}""" + + private def subscriptionId(message: Json): Option[Int] = + message.hcursor.downField("params").downField("_meta").get[Int](ProtocolMeta.SubscriptionId).toOption + + private def method(message: Json): Option[String] = message.hcursor.get[String]("method").toOption + + private def echo(session: StdioSession, id: Int): Json = + session.send(s"""{"jsonrpc":"2.0","id":$id,"method":"tools/call","params":{"name":"echo","arguments":{"message":"m"}}}""") + session.readResponse() + + it should "keep several subscriptions on one channel apart, and end one on notifications/cancelled" in withStdioServer() { session => + session.send(listen(21, """{"toolsListChanged":true}""")) + val first = session.readResponse() + session.send(listen(22, """{"toolsListChanged":true,"promptsListChanged":true}""")) + val second = session.readResponse() + List(first, second).map(method) shouldBe List.fill(2)(Some("notifications/subscriptions/acknowledged")) + List(first, second).map(subscriptionId) shouldBe List(Some(21), Some(22)) + second.hcursor.downField("params").downField("notifications").focus shouldBe parser.parse("""{"toolsListChanged":true}""").toOption + + session.publisher.toolsListChanged() + val changes = List(session.readResponse(), session.readResponse()) + changes.map(method) shouldBe List.fill(2)(Some("notifications/tools/list_changed")) + changes.flatMap(subscriptionId).sorted shouldBe List(21, 22) + + session.send("""{"jsonrpc":"2.0","method":"notifications/cancelled","params":{"requestId":21}}""") + echo(session, 23).hcursor.get[Int]("id") shouldBe Right(23) + session.publisher.toolsListChanged() + subscriptionId(session.readResponse()) shouldBe Some(22) + echo(session, 24).hcursor.get[Int]("id") shouldBe Right(24) + } + + it should "end open subscriptions with a listen result and notifications/cancelled when its input ends" in withStdioServer() { session => + session.send(listen(31, """{"toolsListChanged":true}""")) + method(session.readResponse()) shouldBe Some("notifications/subscriptions/acknowledged") + session.closeInput() + + val result = session.readResponse() + result.hcursor.get[Int]("id") shouldBe Right(31) + result.hcursor.downField("result").get[String]("resultType") shouldBe Right("complete") + result.hcursor.downField("result").downField("_meta").get[Int](ProtocolMeta.SubscriptionId) shouldBe Right(31) + val cancelled = session.readResponse() + method(cancelled) shouldBe Some("notifications/cancelled") + cancelled.hcursor.downField("params").get[Int]("requestId") shouldBe Right(31) + + Await.result(session.served, 10.seconds) + session.publisher.openSubscriptions shouldBe 0 + } From 4ec45562c6a4720784b09e23d658cbbbab1038f2 Mon Sep 17 00:00:00 2001 From: Ondra Pelech Date: Thu, 19 Nov 2026 16:44:49 +0100 Subject: [PATCH 12/31] feat(T16): add test_trigger_tool_change and test_trigger_prompt_change conformance fixtures The conformance server publishes tools and prompts list changes from the two fixture tools and closes its subscriptions on shutdown. The five subscriptions/listen checks of server-stateless now pass. The scenario stays in the baseline: only http-server-no-independent-requests-on-stream still fails, because it needs the test_streaming_elicitation tool (T14). --- conformance-baseline-2026-07-28.yml | 3 ++- .../scala/chimp/conformance/server/Main.scala | 23 ++++++++++++++++++- 2 files changed, 24 insertions(+), 2 deletions(-) diff --git a/conformance-baseline-2026-07-28.yml b/conformance-baseline-2026-07-28.yml index 70e5f7bc..aabc6c8b 100644 --- a/conformance-baseline-2026-07-28.yml +++ b/conformance-baseline-2026-07-28.yml @@ -23,7 +23,8 @@ server: - input-required-result-request-state - input-required-result-result-type - input-required-result-tampered-state - # full stateless lifecycle (needs subscription serving) + # full stateless lifecycle: only http-server-no-independent-requests-on-stream fails, it needs the + # test_streaming_elicitation tool (multi-round-trip requests) — T14, https://github.com/softwaremill/chimp/issues/252 - server-stateless # x-mcp-header custom headers in the tool DSL — T13, https://github.com/softwaremill/chimp/issues/251 - http-custom-header-server-validation diff --git a/server-conformance/src/main/scala/chimp/conformance/server/Main.scala b/server-conformance/src/main/scala/chimp/conformance/server/Main.scala index f287803f..2a74a839 100644 --- a/server-conformance/src/main/scala/chimp/conformance/server/Main.scala +++ b/server-conformance/src/main/scala/chimp/conformance/server/Main.scala @@ -145,6 +145,22 @@ object Main: LoggingLevel.values.foreach(level => ctx.log(level, Json.fromString(s"$level message"))) ToolResult.text("logging complete") + private val publisher = NotificationPublisher() + + private val triggerToolChange = tool("test_trigger_tool_change") + .description("Publishes a tools list change to the open subscriptions") + .input[NoInput] + .handle: _ => + publisher.toolsListChanged() + ToolResult.text("tools list change published") + + private val triggerPromptChange = tool("test_trigger_prompt_change") + .description("Publishes a prompts list change to the open subscriptions") + .input[NoInput] + .handle: _ => + publisher.promptsListChanged() + ToolResult.text("prompts list change published") + private val staticText = resource("test://static-text") .name("static-text") .mimeType("text/plain") @@ -206,7 +222,9 @@ object Main: mixedTool, embeddedResourceTool, jsonSchemaTool, - missingCapabilityTool + missingCapabilityTool, + triggerToolChange, + triggerPromptChange ) .addResources(staticText, staticBinary) .addResourceTemplate(dataTemplate) @@ -214,6 +232,7 @@ object Main: .withCompletion((_, _, _) => Completion(values = List("alpha", "beta"))) .withLoggingLevel(_ => ()) .withSubscriptions(ResourceSubscriptions[Identity](_ => (), _ => ())) + .withPublisher(publisher) private val streamingServer = server.streaming.addStreamingTools(progressTool, loggingTool, perRequestLoggingTool) @@ -225,6 +244,8 @@ object Main: val endpoint = OxServerHttpTransport(List("mcp")).serve(streamingServer) + val _ = sys.addShutdownHook(publisher.close()) + supervised: val binding = NettySyncServer().port(requestedPort).addEndpoint(endpoint).start() println(s"http://127.0.0.1:${binding.port}/mcp") From 51da456fcabe71b198aba837f645ab6fa5b0d472 Mon Sep 17 00:00:00 2001 From: Ondra Pelech Date: Thu, 19 Nov 2026 16:46:22 +0100 Subject: [PATCH 13/31] docs(T16): document the notification publisher and subscriptions/listen capabilities.md explains how to publish list changes and resource updates, which capabilities follow from a publisher, the listen stream rules over HTTP and stdio, and that a streaming transport is needed. resources.md points modern clients to the resourceSubscriptions filter. --- docs/server/capabilities.md | 49 ++++++++++++++++++++++++++++++++++++- docs/server/resources.md | 1 + 2 files changed, 49 insertions(+), 1 deletion(-) diff --git a/docs/server/capabilities.md b/docs/server/capabilities.md index be4b790b..bddadd8d 100644 --- a/docs/server/capabilities.md +++ b/docs/server/capabilities.md @@ -28,7 +28,7 @@ val work = tool("work") val server = StreamingMcpServer[Identity]().addStreamingTool(work) ``` -Server-wide capabilities are enabled by registering a handler — only what you wire up is advertised: `.withCompletion`, `.withLoggingLevel`, `.withSubscriptions`. `.withLoggingLevel` and `.withSubscriptions` serve only legacy clients: `2026-07-28` removed `logging/setLevel` and `resources/{,un}subscribe`, so a modern client gets a `404` for them (see below). +Server-wide capabilities are enabled by registering a handler — only what you wire up is advertised: `.withCompletion`, `.withLoggingLevel`, `.withSubscriptions`, `.withPublisher`. `.withLoggingLevel` and `.withSubscriptions` serve only legacy clients: `2026-07-28` removed `logging/setLevel` and `resources/{,un}subscribe`, so a modern client gets a `404` for them (see below). `.withPublisher` serves only modern clients (see [publishing list changes and resource updates](#publishing-list-changes-and-resource-updates)). ## Protocol versions @@ -45,6 +45,7 @@ A request is **modern** when its `_meta` or its `MCP-Protocol-Version` header de | the `MCP-Protocol-Version` header is missing (HTTP only), or it and `_meta` declare different versions | `-32020` HeaderMismatch | `400` | | `Mcp-Method` / `Mcp-Name` header missing or different from the body (HTTP only) | `-32020` HeaderMismatch | `400` | | removed method (`initialize`, `ping`, `logging/setLevel`, `resources/subscribe`, `resources/unsubscribe`) or unknown method | `-32601` MethodNotFound | `404` | +| `subscriptions/listen` on a server without a publisher, or on the sync HTTP transport | `-32601` MethodNotFound | `404` | | `tools/call` of a tool whose required client capabilities `_meta` does not declare | `-32021` MissingRequiredClientCapability | `400` | Over HTTP, a modern request must carry the SEP-2243 standard headers: `Mcp-Method` with the body's `method`, and `Mcp-Name` with `params.name` on `tools/call` and `prompts/get`, or `params.uri` on `resources/read`. Header names are case-insensitive, values are case-sensitive, and surrounding whitespace is ignored. chimp's own client sends these headers and the `_meta` when you give it a modern protocol version — see [client transport](../client/transport.md). @@ -82,3 +83,49 @@ val ask = tool("ask") val server = McpServer[Identity]().addTool(ask) ``` + +## Publishing list changes and resource updates + +A server tells its clients that its tools, prompts or resources changed, or that a resource was updated, through a `NotificationPublisher`. Create one, give it to the server with `.withPublisher`, and call it from any part of your application, not only from a tool: + +- `toolsListChanged()`, `promptsListChanged()`, `resourcesListChanged()` — send the list-changed notification of that list. +- `resourceUpdated(uri)` — send `notifications/resources/updated` for one resource URI. +- `close()` — end all open subscriptions, for example when the server shuts down. + +The methods are thread-safe and return `Unit`, not an effect. In an effect system, wrap the call, for example `ZIO.succeed(publisher.toolsListChanged())`. + +```scala mdoc:compile-only +import chimp.server.* +import chimp.server.ox.OxServerHttpTransport +import io.circe.Codec +import sttp.shared.Identity +import sttp.tapir.* + +case class NoteInput(text: String) derives Codec, Schema + +val publisher = NotificationPublisher() + +val addNote = tool("add_note") + .input[NoteInput] + .handle: _ => + publisher.resourcesListChanged() + ToolResult.text("note added") + +val server = McpServer[Identity]().addTool(addNote).withPublisher(publisher).streaming +val endpoint = OxServerHttpTransport(List("mcp")).serve(server) +``` + +A `2026-07-28` client receives these notifications on a [`subscriptions/listen`](https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/subscriptions) stream: + +- With a publisher, `server/discover` advertises `listChanged` for tools, prompts and resources, and `subscribe` for resources. The capability of a list is there only when the server has that feature, for example `prompts` only when the server has prompts. The `initialize` result for legacy clients does not change: it advertises no list changes, and `subscribe` only for `.withSubscriptions`. +- The first message on the stream is `notifications/subscriptions/acknowledged`. Its filter is the part of the requested filter that the server honours. The server sends no other notification types. +- Each message on the stream carries the id of the listen request in `_meta`, under `io.modelcontextprotocol/subscriptionId`. +- `notifications/resources/updated` goes only to the streams which list the URI in `resourceSubscriptions`. +- Progress and log notifications do not go on a listen stream. They stay on the stream of their request. +- Over HTTP, a subscription ends when the client closes the stream. The server notices a closed stream at the latest when it next sends on it. +- Over stdio, all subscriptions share the one channel. The client ends one with `notifications/cancelled` that names the listen request. When the input ends, the server ends each open subscription. +- When the server ends a subscription (on `close()`, or at the end of the stdio input), it sends a successful `subscriptions/listen` result with the subscription id. Over stdio, it then sends `notifications/cancelled` for the listen request. + +```{note} +A listen stream needs a streaming transport. On the sync HTTP transport (`McpServer.endpoint`), the server answers `subscriptions/listen` with `-32601` and advertises no list changes. +``` diff --git a/docs/server/resources.md b/docs/server/resources.md index 9333a777..6a6239c4 100644 --- a/docs/server/resources.md +++ b/docs/server/resources.md @@ -8,6 +8,7 @@ - `serverLogic` — effectful read logic, with the request headers. - `handleSecured` (synchronous) or `securedServerLogic` (effectful) — logic that also receives the principal made by the server's security logic; usable only on a secured server — see [transport security](transport.md). - Register with `.addResource` / `.addResourceTemplate`. Subscriptions are wired with `.withSubscriptions`; they serve legacy clients only, as `2026-07-28` removed `resources/{,un}subscribe` (see [protocol versions in server capabilities](capabilities.md)). +- On `2026-07-28`, a client subscribes to resources with the `resourceSubscriptions` filter of `subscriptions/listen`, which replaces `resources/subscribe`. Send the updates with `NotificationPublisher.resourceUpdated(uri)`; the server sends each update only to the streams which list its URI (see [publishing list changes and resource updates](capabilities.md#publishing-list-changes-and-resource-updates)). ```scala mdoc:compile-only import chimp.server.* From 3c82336ec0536dda3f69c3bb4408f912cc35a92d Mon Sep 17 00:00:00 2001 From: Ondra Pelech Date: Thu, 19 Nov 2026 17:24:49 +0100 Subject: [PATCH 14/31] fix(T14): send resultType input_required and allow a state-only InputRequiredResult The 2026-07-28 schema names the MRTR result type input_required, not incomplete, and makes inputRequests optional (an input-required result needs at least one of inputRequests or requestState). --- core/src/main/scala/chimp/protocol/Mrtr.scala | 4 ++-- core/src/main/scala/chimp/protocol/Versioning.scala | 12 ++++++------ .../protocol/Schema20260728ConformanceSpec.scala | 3 ++- 3 files changed, 10 insertions(+), 9 deletions(-) diff --git a/core/src/main/scala/chimp/protocol/Mrtr.scala b/core/src/main/scala/chimp/protocol/Mrtr.scala index a85fcc47..11e24a4c 100644 --- a/core/src/main/scala/chimp/protocol/Mrtr.scala +++ b/core/src/main/scala/chimp/protocol/Mrtr.scala @@ -49,8 +49,8 @@ object InputResponse: * opaque `requestState` the client echoes back on its response, and the modern result envelope fields. */ final case class InputRequiredResult( - inputRequests: Map[String, InputRequest], + inputRequests: Option[Map[String, InputRequest]] = None, requestState: Option[String] = None, - resultType: ResultType = ResultType.Incomplete, + resultType: ResultType = ResultType.InputRequired, _meta: Option[Map[String, Json]] = None ) derives io.circe.Codec diff --git a/core/src/main/scala/chimp/protocol/Versioning.scala b/core/src/main/scala/chimp/protocol/Versioning.scala index 7600a3c6..5b031a6f 100644 --- a/core/src/main/scala/chimp/protocol/Versioning.scala +++ b/core/src/main/scala/chimp/protocol/Versioning.scala @@ -38,19 +38,19 @@ object ProtocolMeta: data = Some(Json.obj("requiredCapabilities" -> required.asJson.deepDropNullValues)) ) -/** The type of a modern (2026-07-28+) result: `complete` for a finished result, `incomplete` for one that needs another round trip (MRTR - * input-required). +/** The type of a modern (2026-07-28+) result: `complete` for a finished result, `input_required` for one that needs another round trip + * (MRTR). */ enum ResultType(val name: String): case Complete extends ResultType("complete") - case Incomplete extends ResultType("incomplete") + case InputRequired extends ResultType("input_required") object ResultType: given Encoder[ResultType] = Encoder.instance(resultType => Json.fromString(resultType.name)) given Decoder[ResultType] = Decoder.decodeString.emap: - case "complete" => Right(Complete) - case "incomplete" => Right(Incomplete) - case other => Left(s"Unknown result type: $other") + case "complete" => Right(Complete) + case "input_required" => Right(InputRequired) + case other => Left(s"Unknown result type: $other") /** Whether a cached response may be shared across authorization contexts (`Public`) or not (`Private`). */ enum CacheScope: diff --git a/core/src/test/scala/chimp/protocol/Schema20260728ConformanceSpec.scala b/core/src/test/scala/chimp/protocol/Schema20260728ConformanceSpec.scala index 59792796..121cd394 100644 --- a/core/src/test/scala/chimp/protocol/Schema20260728ConformanceSpec.scala +++ b/core/src/test/scala/chimp/protocol/Schema20260728ConformanceSpec.scala @@ -90,8 +90,9 @@ class Schema20260728ConformanceSpec extends SchemaConformance: ) validate( "InputRequiredResult", - InputRequiredResult(inputRequests = Map("name" -> request), requestState = Some("state-1")) + InputRequiredResult(inputRequests = Some(Map("name" -> request)), requestState = Some("state-1")) ) + InputRequiredResult(requestState = Some("state-1")).asJson.hcursor.get[String]("resultType") shouldBe Right("input_required") it should "produce CallToolRequestParams carrying inputResponses and requestState that match the spec schema" in: validate( From 161d0193bb36bfc782dc82a19eb6a87441d62189 Mon Sep 17 00:00:00 2001 From: Ondra Pelech Date: Thu, 19 Nov 2026 17:30:21 +0100 Subject: [PATCH 15/31] feat(T14): let tools, prompts and resources end with an input-required outcome A tools/call, prompts/get or resources/read handler can now return InputRequired (keyed form/URL elicitation, sampling and roots requests, plus an optional opaque request state) instead of its result. The client gets resultType input_required; on the retry the handler reads the answers and the state from RequestInfo. The server enforces the MRTR rules so handlers do not have to: an outcome always has requests or a state (by construction); an input request the client has no capability for fails with -32021, the missing requiredCapabilities and HTTP 400; malformed inputResponses or requestState fail with -32602 and HTTP 400 before the handler runs; unknown answer keys are ignored; an outcome on a legacy request becomes an internal error naming protocol version 2026-07-28. --- .../scala/chimp/server/InputRequired.scala | 66 +++++ .../main/scala/chimp/server/McpHandler.scala | 159 ++++++++---- .../src/main/scala/chimp/server/Prompt.scala | 16 +- .../main/scala/chimp/server/Resource.scala | 36 +-- .../scala/chimp/server/ServerContext.scala | 17 +- server/src/main/scala/chimp/server/Tool.scala | 30 ++- .../server/McpHandlerInputRequiredSpec.scala | 226 ++++++++++++++++++ 7 files changed, 471 insertions(+), 79 deletions(-) create mode 100644 server/src/main/scala/chimp/server/InputRequired.scala create mode 100644 server/src/test/scala/chimp/server/McpHandlerInputRequiredSpec.scala diff --git a/server/src/main/scala/chimp/server/InputRequired.scala b/server/src/main/scala/chimp/server/InputRequired.scala new file mode 100644 index 00000000..639ac43d --- /dev/null +++ b/server/src/main/scala/chimp/server/InputRequired.scala @@ -0,0 +1,66 @@ +package chimp.server + +import chimp.protocol.* +import io.circe.Json + +/** The outcome of a tool, prompt or resource handler which needs input from the client before it can finish (multi round-trip requests, + * 2026-07-28). The client answers each request under its key, echoes the request state, and retries the same request; the handler reads + * the answers from [[RequestInfo.inputResponses]] and the state from [[RequestInfo.requestState]]. It always carries at least one input + * request or a request state. + */ +final case class InputRequired private (requests: Map[String, InputRequest], requestState: Option[String]): + /** Adds an input request under `key`; a request already under `key` is replaced. */ + def and(key: String, request: InputRequest): InputRequired = copy(requests = requests + (key -> request)) + + /** Sets the opaque state which the client echoes on its retry. */ + def withRequestState(state: String): InputRequired = copy(requestState = Some(state)) + +object InputRequired: + def apply(first: (String, InputRequest), rest: (String, InputRequest)*): InputRequired = + new InputRequired((first +: rest).toMap, None) + + /** An outcome without input requests: the client retries at once, with `state`. */ + def withRequestState(state: String): InputRequired = new InputRequired(Map.empty, Some(state)) + + /** Asks the user to fill in a form described by a JSON Schema; the client must declare the `elicitation` (form) capability. */ + def elicitForm(message: String, requestedSchema: Json): InputRequest = + InputRequest.Elicit(ElicitRequest(params = ElicitParams.Form(message, requestedSchema))) + + /** Asks the user to complete an interaction at `url`, out of band; the client must declare the `elicitation.url` capability. */ + def elicitUrl(message: String, url: String): InputRequest = + InputRequest.Elicit(ElicitRequest(params = ElicitParams.Url(message, url))) + + /** Asks the client to sample its LLM; the client must declare the `sampling` capability. */ + def sample(params: CreateMessageParams): InputRequest = InputRequest.Sampling(CreateMessageRequest(params = params)) + + /** Asks the client for its roots; the client must declare the `roots` capability. */ + val listRoots: InputRequest = InputRequest.Roots(ListRootsRequest()) + + /** The client capabilities which `request` needs. */ + private def capabilitiesFor(request: InputRequest): ClientCapabilities = request match + case InputRequest.Sampling(_) => ClientCapabilities(sampling = Some(Json.obj())) + case InputRequest.Roots(_) => ClientCapabilities(roots = Some(ClientRootsCapability())) + case InputRequest.Elicit(ElicitRequest(_, _: ElicitParams.Form)) => + ClientCapabilities(elicitation = Some(Json.obj("form" -> Json.obj()))) + case InputRequest.Elicit(ElicitRequest(_, _: ElicitParams.Url)) => ClientCapabilities(elicitation = Some(Json.obj("url" -> Json.obj()))) + + /** Whether `declared` covers what `request` needs. An empty `elicitation` object means form mode only, as in 2025-11-25. */ + private[server] def isDeclared(request: InputRequest, declared: ClientCapabilities): Boolean = + def elicitationHas(mode: String, emptyMeans: Boolean): Boolean = + declared.elicitation.flatMap(_.asObject).exists(modes => modes.contains(mode) || (modes.isEmpty && emptyMeans)) + request match + case InputRequest.Sampling(_) => declared.sampling.isDefined + case InputRequest.Roots(_) => declared.roots.isDefined + case InputRequest.Elicit(ElicitRequest(_, _: ElicitParams.Form)) => elicitationHas("form", emptyMeans = true) + case InputRequest.Elicit(ElicitRequest(_, _: ElicitParams.Url)) => elicitationHas("url", emptyMeans = false) + + /** The client capabilities which `requests` need together, as `requiredCapabilities` of a `-32021` error names them. */ + private[server] def requiredCapabilities(requests: Iterable[InputRequest]): ClientCapabilities = + requests + .map(capabilitiesFor) + .foldLeft(ClientCapabilities()): (all, one) => + ClientCapabilities( + roots = all.roots.orElse(one.roots), + sampling = all.sampling.orElse(one.sampling), + elicitation = (all.elicitation ++ one.elicitation).reduceOption(_.deepMerge(_)) + ) diff --git a/server/src/main/scala/chimp/server/McpHandler.scala b/server/src/main/scala/chimp/server/McpHandler.scala index 8d6f6aff..2e1ebbd1 100644 --- a/server/src/main/scala/chimp/server/McpHandler.scala +++ b/server/src/main/scala/chimp/server/McpHandler.scala @@ -108,6 +108,8 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD case JSONRPCMessage.Response(jsonrpc, rid, result) if isModern => JSONRPCMessage.Response(jsonrpc, rid, modernResult(result, cacheHints)) case other => other + def reply(cacheHints: Option[CacheHints])(reply: Reply): McpResponse = + reply.fold(identity, message => jsonResponse(wrap(cacheHints)(message))) val cacheHints = Some(CacheHints.Default) method match case "initialize" => @@ -119,7 +121,7 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD case "tools/list" => jsonResponse(wrap(cacheHints)(JSONRPCMessage.Response(id = id, result = ListToolsResponse(toolDefinitions).asJson))).unit case "tools/call" => - handleToolsCall(params, id, headers, makeContext).map(wrap(None)).map(jsonResponse) + handleToolsCall(params, id, headers, makeContext, isModern).map(reply(None)) case "resources/list" if hasResources => jsonResponse( wrap(cacheHints)(JSONRPCMessage.Response(id = id, result = ListResourcesResult(server.resources.map(_.definition)).asJson)) @@ -131,7 +133,7 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD ) ).unit case "resources/read" if hasResources => - handleResourcesRead(params, id, headers, makeContext).map(wrap(cacheHints)).map(jsonResponse) + handleResourcesRead(params, id, headers, makeContext, isModern).map(reply(cacheHints)) case "resources/subscribe" if server.subscriptions.isDefined => handleSubscribe(params, id, subscribe = true).map(jsonResponse) case "resources/unsubscribe" if server.subscriptions.isDefined => @@ -141,7 +143,7 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD wrap(cacheHints)(JSONRPCMessage.Response(id = id, result = ListPromptsResult(server.prompts.map(_.definition)).asJson)) ).unit case "prompts/get" if hasPrompts => - handlePromptsGet(params, id, headers, makeContext).map(wrap(None)).map(jsonResponse) + handlePromptsGet(params, id, headers, makeContext, isModern).map(reply(None)) case "completion/complete" if server.completion.isDefined => handleComplete(params, id).map(wrap(None)).map(jsonResponse) case "logging/setLevel" if server.loggingLevel.isDefined => @@ -151,10 +153,13 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD case other => jsonResponse(protocolError(id, JSONRPCErrorCodes.MethodNotFound.code, s"Unknown method: $other")).unit + /** Adds the modern envelope fields to a result. An input-required result already names its type and is never cached. */ private def modernResult(result: Json, cacheHints: Option[CacheHints]): Json = val meta = result.hcursor.downField("_meta").focus.getOrElse(Json.obj()).deepMerge(serverInfoMeta) - val enriched = result.deepMerge(Json.obj("resultType" -> ResultType.Complete.asJson, "_meta" -> meta)) - cacheHints.fold(enriched)(hints => enriched.deepMerge(hints.asJson)) + if result.hcursor.get[ResultType]("resultType").contains(ResultType.InputRequired) then result.deepMerge(Json.obj("_meta" -> meta)) + else + val enriched = result.deepMerge(Json.obj("resultType" -> ResultType.Complete.asJson, "_meta" -> meta)) + cacheHints.fold(enriched)(hints => enriched.deepMerge(hints.asJson)) private def protocolError(id: RequestId, code: Int, message: String, data: Option[Json] = None): JSONRPCMessage.Error = logger.debug(s"Protocol error (id=$id, code=$code): $message") @@ -162,6 +167,33 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD private def jsonResponse(message: JSONRPCMessage): McpResponse = McpResponse.JsonResponse(message.asJson) + /** The reply of a handler which may end with [[InputRequired]]: a JSON-RPC message, or a response with its own HTTP status. */ + private type Reply = Either[McpResponse, JSONRPCMessage] + + /** Applies the server-enforced input-required rules: only a modern request can get it, and only for the input requests which the client + * declared the capabilities for (otherwise a `-32021` with HTTP 400). + */ + private def inputRequiredReply(id: RequestId, outcome: InputRequired, info: RequestInfo, isModern: Boolean): Reply = + if !isModern then + Right( + protocolError( + id, + JSONRPCErrorCodes.InternalError.code, + s"The handler asked for client input, which needs protocol version ${ProtocolVersion.V2026_07_28.name} or later" + ) + ) + else + val declared = info.clientCapabilities.getOrElse(ClientCapabilities()) + val undeclared = outcome.requests.values.filterNot(InputRequired.isDeclared(_, declared)) + if undeclared.nonEmpty then + val required = InputRequired.requiredCapabilities(undeclared) + logger.debug(s"Input required rejected (id=$id): missing client capabilities ${required.asJson.deepDropNullValues.noSpaces}") + val envelope: JSONRPCMessage = JSONRPCMessage.Error(id = id, error = ProtocolMeta.missingClientCapabilityError(required)) + Left(McpResponse.JsonError(StatusCode.BadRequest, envelope.asJson)) + else + val result = InputRequiredResult(Option.when(outcome.requests.nonEmpty)(outcome.requests), outcome.requestState) + Right(JSONRPCMessage.Response(id = id, result = result.asJson)) + // request methods a 2026-07-28 client may call private val modernMethods: Set[String] = Set( @@ -204,7 +236,9 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD clientCapabilities = fromMeta[ClientCapabilities](ProtocolMeta.ClientCapabilities), clientInfo = fromMeta[Implementation](ProtocolMeta.ClientInfo), logLevel = fromMeta[LoggingLevel](ProtocolMeta.LogLevel), - progressToken = progressToken + progressToken = progressToken, + inputResponses = params.flatMap(_.hcursor.get[Map[String, InputResponse]]("inputResponses").toOption).getOrElse(Map.empty), + requestState = params.flatMap(_.hcursor.get[String]("requestState").toOption) ) else RequestInfo(protocolVersion = protocolVersion, progressToken = progressToken) @@ -265,7 +299,21 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD else // SEP-2243 standard request headers only apply over HTTP (identified by the Host header); stdio carries no such headers val headerError = Option.when(overHttp)(headerValidationError(method, params, headers, id)) - headerError.flatten.orElse(missingCapabilityError(method, params, meta, id)) + headerError.flatten.orElse(missingCapabilityError(method, params, meta, id)).orElse(inputResponsesError(method, params, id)) + + // the requests which can end with an input-required result and so carry `inputResponses` and `requestState` on a retry + private val inputRequiredMethods: Set[String] = Set("tools/call", "prompts/get", "resources/read") + + /** A `-32602` with HTTP 400 when a retry's `inputResponses` is not an object of input responses, or its `requestState` not a string. */ + private def inputResponsesError(method: String, params: Option[Json], id: RequestId): Option[McpResponse] = + def invalid(message: String) = Some(jsonError(id, StatusCode.BadRequest, JSONRPCErrorCodes.InvalidParams.code, message)) + val cursor = params.filter(_ => inputRequiredMethods.contains(method)).map(_.hcursor) + val responses = cursor.flatMap(_.downField("inputResponses").focus).map(_.as[Map[String, InputResponse]]) + val state = cursor.flatMap(_.downField("requestState").focus) + responses match + case Some(Left(failure)) => invalid(s"Invalid inputResponses: ${failure.getMessage}") + case _ if state.exists(json => !json.isString) => invalid("Invalid requestState: expected a string") + case _ => None /** A `-32021` with HTTP 400 when `tools/call` names a tool whose required client capabilities the request's `_meta` does not declare. */ private def missingCapabilityError(method: String, params: Option[Json], meta: Option[Json], id: RequestId): Option[McpResponse] = @@ -370,9 +418,9 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD private def handleDiscover(id: RequestId): JSONRPCMessage.Response = JSONRPCMessage.Response(id = id, result = discoverResult.asJson) - private def handleToolsCall(params: Option[Json], id: RequestId, headers: Seq[Header], makeContext: () => C)(using + private def handleToolsCall(params: Option[Json], id: RequestId, headers: Seq[Header], makeContext: () => C, isModern: Boolean)(using MonadError[F] - ): F[JSONRPCMessage] = + ): F[Reply] = val name = params.flatMap(_.hcursor.downField("name").as[String].toOption) val arguments = params.flatMap(_.hcursor.downField("arguments").focus).getOrElse(Json.obj()) name match @@ -384,18 +432,23 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD val context = makeContext() tool .logic(input, context, headers) - .map: result => - toolCallResponse(id, result) + .map: + case outcome: InputRequired => inputRequiredReply(id, outcome, context.request, isModern) + case result: ToolResult[?] => Right(toolCallResponse(id, result)) case Left(decodingError) => val snippet = arguments.noSpaces.take(200) - protocolError( - id, - JSONRPCErrorCodes.InvalidParams.code, - s"Invalid arguments: ${decodingError.getMessage}. Input: $snippet" - ).unit - case None => protocolError(id, JSONRPCErrorCodes.MethodNotFound.code, s"Unknown tool: $name").unit + failed( + protocolError( + id, + JSONRPCErrorCodes.InvalidParams.code, + s"Invalid arguments: ${decodingError.getMessage}. Input: $snippet" + ) + ) + case None => failed(protocolError(id, JSONRPCErrorCodes.MethodNotFound.code, s"Unknown tool: $name")) case None => - protocolError(id, JSONRPCErrorCodes.InvalidParams.code, "Missing tool name").unit + failed(protocolError(id, JSONRPCErrorCodes.InvalidParams.code, "Missing tool name")) + + private def failed(error: JSONRPCMessage)(using MonadError[F]): F[Reply] = (Right(error): Reply).unit private def toolCallResponse(id: RequestId, result: ToolResult[?]): JSONRPCMessage = // for backwards compatibility, structured output is serialized into a text block, unless the tool returned content of its own @@ -415,24 +468,33 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD params: Option[Json], id: RequestId, headers: Seq[Header], - makeContext: () => C - )(using MonadError[F]): F[JSONRPCMessage] = - decodeParams[ReadResourceParams](params, id): params => + makeContext: () => C, + isModern: Boolean + )(using MonadError[F]): F[Reply] = + decodeReplyParams[ReadResourceParams](params, id): params => val context = makeContext() + val respond = resourceReadReply(id, params.uri, context.request, isModern) resourcesByUri.get(params.uri) match - case Some(resource) => resource.read(context, headers).map(resourceReadResponse(id, params.uri)) + case Some(resource) => resource.read(context, headers).map(respond) case None => server.resourceTemplates.iterator .map(template => (template, template.matcher.matchUri(params.uri))) .collectFirst { case (template, Some(vars)) => template.read(vars, params.uri, context, headers) } match - case Some(result) => result.map(resourceReadResponse(id, params.uri)) + case Some(result) => result.map(respond) case None => - protocolError( - id, - JSONRPCErrorCodes.ResourceNotFound.code, - s"Resource not found: ${params.uri}", - Some(Json.obj("uri" -> Json.fromString(params.uri))) - ).unit + failed( + protocolError( + id, + JSONRPCErrorCodes.ResourceNotFound.code, + s"Resource not found: ${params.uri}", + Some(Json.obj("uri" -> Json.fromString(params.uri))) + ) + ) + + private def decodeReplyParams[P: Decoder](params: Option[Json], id: RequestId)(f: P => F[Reply])(using MonadError[F]): F[Reply] = + params.flatMap(_.as[P].toOption) match + case Some(params) => f(params) + case None => failed(protocolError(id, JSONRPCErrorCodes.InvalidParams.code, "Invalid or missing params")) private def decodeParams[P: Decoder](params: Option[Json], id: RequestId)(f: P => F[JSONRPCMessage])(using MonadError[F] @@ -441,15 +503,20 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD case Some(params) => f(params) case None => protocolError(id, JSONRPCErrorCodes.InvalidParams.code, "Invalid or missing params").unit - private def resourceReadResponse(id: RequestId, uri: String)(result: Either[ResourceError, List[ResourceContents]]): JSONRPCMessage = - result match - case Right(contents) => JSONRPCMessage.Response(id = id, result = ReadResourceResult(contents).asJson) - case Left(error) => - protocolError( - id, - JSONRPCErrorCodes.ResourceNotFound.code, - error.message, - error.uri.orElse(Some(uri)).map(uri => Json.obj("uri" -> Json.fromString(uri))) + private def resourceReadReply(id: RequestId, uri: String, info: RequestInfo, isModern: Boolean)( + outcome: Either[ResourceError, List[ResourceContents]] | InputRequired + ): Reply = + outcome match + case required: InputRequired => inputRequiredReply(id, required, info, isModern) + case Right(contents) => Right(JSONRPCMessage.Response(id = id, result = ReadResourceResult(contents).asJson)) + case Left(error) => + Right( + protocolError( + id, + JSONRPCErrorCodes.ResourceNotFound.code, + error.message, + error.uri.orElse(Some(uri)).map(uri => Json.obj("uri" -> Json.fromString(uri))) + ) ) private def handleSubscribe(params: Option[Json], id: RequestId, subscribe: Boolean)(using MonadError[F]): F[JSONRPCMessage] = @@ -463,15 +530,19 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD params: Option[Json], id: RequestId, headers: Seq[Header], - makeContext: () => C - )(using MonadError[F]): F[JSONRPCMessage] = - decodeParams[GetPromptParams](params, id): params => + makeContext: () => C, + isModern: Boolean + )(using MonadError[F]): F[Reply] = + decodeReplyParams[GetPromptParams](params, id): params => promptsByName.get(params.name) match case Some(prompt) => + val context = makeContext() prompt - .logic(params.arguments.getOrElse(Map.empty), makeContext(), headers) - .map(promptResult => JSONRPCMessage.Response(id = id, result = promptResult.asJson)) - case None => protocolError(id, JSONRPCErrorCodes.InvalidParams.code, s"Unknown prompt: ${params.name}").unit + .logic(params.arguments.getOrElse(Map.empty), context, headers) + .map: + case outcome: InputRequired => inputRequiredReply(id, outcome, context.request, isModern) + case result: GetPromptResult => Right(JSONRPCMessage.Response(id = id, result = result.asJson)) + case None => failed(protocolError(id, JSONRPCErrorCodes.InvalidParams.code, s"Unknown prompt: ${params.name}")) private def handleComplete(params: Option[Json], id: RequestId)(using MonadError[F]): F[JSONRPCMessage] = val handler = server.completion.get diff --git a/server/src/main/scala/chimp/server/Prompt.scala b/server/src/main/scala/chimp/server/Prompt.scala index 5ad4eec0..7eda74f5 100644 --- a/server/src/main/scala/chimp/server/Prompt.scala +++ b/server/src/main/scala/chimp/server/Prompt.scala @@ -7,7 +7,9 @@ import sttp.shared.Identity /** Starts defining a prompt with the given name. */ def prompt(name: String): PartialPrompt = PartialPrompt(name) -/** A prompt being defined, before its logic is attached. */ +/** A prompt being defined, before its logic is attached. The logic ends with a [[GetPromptResult]], or with [[InputRequired]] to ask the + * client for input first. + */ case class PartialPrompt( name: String, title: Option[String] = None, @@ -34,25 +36,25 @@ case class PartialPrompt( /** Attaches effectful logic, with access to the request headers, producing the prompt's messages. */ def serverLogic[F[_]]( - logic: (Map[String, String], Seq[Header]) => F[GetPromptResult] + logic: (Map[String, String], Seq[Header]) => F[GetPromptResult | InputRequired] ): ServerPrompt[F, ServerContext[F]] = ServerPrompt(definition, (args, _, headers) => logic(args, headers)) /** Attaches effectful logic, with access to the [[ServerContext]], which gives the facts of the request. */ def serverLogicWithContext[F[_]]( - logic: (Map[String, String], ServerContext[F], Seq[Header]) => F[GetPromptResult] + logic: (Map[String, String], ServerContext[F], Seq[Header]) => F[GetPromptResult | InputRequired] ): ServerPrompt[F, ServerContext[F]] = ServerPrompt(definition, logic) /** Attaches effectful logic, with access to the principal; usable only on a [[SecuredMcpServer]]. */ def securedServerLogic[F[_], P]( - logic: (Map[String, String], P, Seq[Header]) => F[GetPromptResult] + logic: (Map[String, String], P, Seq[Header]) => F[GetPromptResult | InputRequired] ): ServerPrompt[F, SecuredServerContext[F, P]] = ServerPrompt(definition, (args, context, headers) => logic(args, context.principal, headers)) /** Attaches synchronous logic that also receives the request headers. */ def handleWithHeaders( - logic: (Map[String, String], Seq[Header]) => GetPromptResult + logic: (Map[String, String], Seq[Header]) => GetPromptResult | InputRequired ): ServerPrompt[Identity, ServerContext[Identity]] = serverLogic[Identity](logic) @@ -62,7 +64,7 @@ case class PartialPrompt( /** Attaches synchronous logic over the supplied argument values and the principal; usable only on a [[SecuredMcpServer]]. */ def handleSecured[P]( - logic: (Map[String, String], P) => GetPromptResult + logic: (Map[String, String], P) => GetPromptResult | InputRequired ): ServerPrompt[Identity, SecuredServerContext[Identity, P]] = securedServerLogic[Identity, P]((args, principal, _) => logic(args, principal)) @@ -74,5 +76,5 @@ end PartialPrompt /** A fully-defined prompt: its metadata plus the logic producing its messages. */ case class ServerPrompt[F[_], -C <: ServerContext[F]]( definition: Prompt, - logic: (Map[String, String], C, Seq[Header]) => F[GetPromptResult] + logic: (Map[String, String], C, Seq[Header]) => F[GetPromptResult | InputRequired] ) diff --git a/server/src/main/scala/chimp/server/Resource.scala b/server/src/main/scala/chimp/server/Resource.scala index 57d001b9..e44725c8 100644 --- a/server/src/main/scala/chimp/server/Resource.scala +++ b/server/src/main/scala/chimp/server/Resource.scala @@ -16,7 +16,9 @@ def resource(uri: String): PartialResource = PartialResource(uri) /** Starts defining a resource template whose URI carries `{variable}` placeholders. */ def resourceTemplate(uriTemplate: String): PartialResourceTemplate = PartialResourceTemplate(uriTemplate) -/** A resource being defined, before its read logic is attached. */ +/** A resource being defined, before its read logic is attached. The logic ends with the contents (or an error), or with [[InputRequired]] + * to ask the client for input first. + */ case class PartialResource( uri: String, name: Option[String] = None, @@ -50,35 +52,37 @@ case class PartialResource( /** Attaches effectful logic, with access to the request headers, producing the resource's contents (or an error). */ def serverLogic[F[_]]( - logic: Seq[Header] => F[Either[ResourceError, List[ResourceContents]]] + logic: Seq[Header] => F[Either[ResourceError, List[ResourceContents]] | InputRequired] ): ServerResource[F, ServerContext[F]] = ServerResource(definition, (_, headers) => logic(headers)) /** Attaches effectful logic, with access to the [[ServerContext]], which gives the facts of the request. */ def serverLogicWithContext[F[_]]( - logic: (ServerContext[F], Seq[Header]) => F[Either[ResourceError, List[ResourceContents]]] + logic: (ServerContext[F], Seq[Header]) => F[Either[ResourceError, List[ResourceContents]] | InputRequired] ): ServerResource[F, ServerContext[F]] = ServerResource(definition, logic) /** Attaches effectful logic, with access to the principal; usable only on a [[SecuredMcpServer]]. */ def securedServerLogic[F[_], P]( - logic: (P, Seq[Header]) => F[Either[ResourceError, List[ResourceContents]]] + logic: (P, Seq[Header]) => F[Either[ResourceError, List[ResourceContents]] | InputRequired] ): ServerResource[F, SecuredServerContext[F, P]] = ServerResource(definition, (context, headers) => logic(context.principal, headers)) /** Attaches synchronous logic that also receives the request headers. */ def handleWithHeaders( - logic: Seq[Header] => Either[ResourceError, List[ResourceContents]] + logic: Seq[Header] => Either[ResourceError, List[ResourceContents]] | InputRequired ): ServerResource[Identity, ServerContext[Identity]] = serverLogic[Identity](logic) /** Attaches synchronous logic producing the resource's contents (or an error). */ - def handle(logic: () => Either[ResourceError, List[ResourceContents]]): ServerResource[Identity, ServerContext[Identity]] = + def handle( + logic: () => Either[ResourceError, List[ResourceContents]] | InputRequired + ): ServerResource[Identity, ServerContext[Identity]] = handleWithHeaders(_ => logic()) /** Attaches synchronous logic over the principal; usable only on a [[SecuredMcpServer]]. */ def handleSecured[P]( - logic: P => Either[ResourceError, List[ResourceContents]] + logic: P => Either[ResourceError, List[ResourceContents]] | InputRequired ): ServerResource[Identity, SecuredServerContext[Identity, P]] = securedServerLogic[Identity, P]((principal, _) => logic(principal)) @@ -89,7 +93,7 @@ end PartialResource /** A fully-defined resource: its metadata plus the logic reading its contents. */ case class ServerResource[F[_], -C <: ServerContext[F]]( definition: Resource, - read: (C, Seq[Header]) => F[Either[ResourceError, List[ResourceContents]]] + read: (C, Seq[Header]) => F[Either[ResourceError, List[ResourceContents]] | InputRequired] ) /** A resource template being defined, before its read logic is attached. */ @@ -122,19 +126,21 @@ case class PartialResourceTemplate( /** Attaches effectful logic reading a matched URI; receives the extracted variables, the full URI, and the request headers. */ def serverLogic[F[_]]( - logic: (Map[String, String], String, Seq[Header]) => F[Either[ResourceError, List[ResourceContents]]] + logic: (Map[String, String], String, Seq[Header]) => F[Either[ResourceError, List[ResourceContents]] | InputRequired] ): ServerResourceTemplate[F, ServerContext[F]] = ServerResourceTemplate(definition, UriTemplate.compile(uriTemplate), (vars, uri, _, headers) => logic(vars, uri, headers)) /** Attaches effectful logic reading a matched URI, with access to the [[ServerContext]], which gives the facts of the request. */ def serverLogicWithContext[F[_]]( - logic: (Map[String, String], String, ServerContext[F], Seq[Header]) => F[Either[ResourceError, List[ResourceContents]]] + logic: (Map[String, String], String, ServerContext[F], Seq[Header]) => F[ + Either[ResourceError, List[ResourceContents]] | InputRequired + ] ): ServerResourceTemplate[F, ServerContext[F]] = ServerResourceTemplate(definition, UriTemplate.compile(uriTemplate), logic) /** Attaches effectful logic, with access to the principal; usable only on a [[SecuredMcpServer]]. */ def securedServerLogic[F[_], P]( - logic: (Map[String, String], String, P, Seq[Header]) => F[Either[ResourceError, List[ResourceContents]]] + logic: (Map[String, String], String, P, Seq[Header]) => F[Either[ResourceError, List[ResourceContents]] | InputRequired] ): ServerResourceTemplate[F, SecuredServerContext[F, P]] = ServerResourceTemplate( definition, @@ -144,19 +150,19 @@ case class PartialResourceTemplate( /** Attaches synchronous logic that also receives the request headers. */ def handleWithHeaders( - logic: (Map[String, String], String, Seq[Header]) => Either[ResourceError, List[ResourceContents]] + logic: (Map[String, String], String, Seq[Header]) => Either[ResourceError, List[ResourceContents]] | InputRequired ): ServerResourceTemplate[Identity, ServerContext[Identity]] = serverLogic[Identity](logic) /** Attaches synchronous logic receiving the extracted variables and the full URI. */ def handle( - logic: (Map[String, String], String) => Either[ResourceError, List[ResourceContents]] + logic: (Map[String, String], String) => Either[ResourceError, List[ResourceContents]] | InputRequired ): ServerResourceTemplate[Identity, ServerContext[Identity]] = handleWithHeaders((vars, uri, _) => logic(vars, uri)) /** Attaches synchronous logic over the extracted variables, the full URI, and the principal; usable only on a [[SecuredMcpServer]]. */ def handleSecured[P]( - logic: (Map[String, String], String, P) => Either[ResourceError, List[ResourceContents]] + logic: (Map[String, String], String, P) => Either[ResourceError, List[ResourceContents]] | InputRequired ): ServerResourceTemplate[Identity, SecuredServerContext[Identity, P]] = securedServerLogic[Identity, P]((vars, uri, principal, _) => logic(vars, uri, principal)) @@ -169,7 +175,7 @@ end PartialResourceTemplate case class ServerResourceTemplate[F[_], -C <: ServerContext[F]]( definition: ResourceTemplate, matcher: UriTemplate, - read: (Map[String, String], String, C, Seq[Header]) => F[Either[ResourceError, List[ResourceContents]]] + read: (Map[String, String], String, C, Seq[Header]) => F[Either[ResourceError, List[ResourceContents]] | InputRequired] ) /** A compiled URI template that matches concrete URIs and extracts their `{variable}` values. */ diff --git a/server/src/main/scala/chimp/server/ServerContext.scala b/server/src/main/scala/chimp/server/ServerContext.scala index 3a73c975..06bcd3e8 100644 --- a/server/src/main/scala/chimp/server/ServerContext.scala +++ b/server/src/main/scala/chimp/server/ServerContext.scala @@ -5,7 +5,8 @@ import io.circe.Json import io.circe.syntax.* import sttp.monad.MonadError -/** What a request tells about itself. A modern (2026-07-28+) request carries all of it in `_meta`. A legacy request gives only the protocol +/** What a request tells about itself. A modern (2026-07-28+) request carries all of it in `_meta`, and a retry of an [[InputRequired]] + * outcome also carries the client's answers (`inputResponses`) and the echoed `requestState`. A legacy request gives only the protocol * version (from the `MCP-Protocol-Version` header or `_meta`) and the progress token; the server keeps no state from `initialize`. */ final case class RequestInfo( @@ -13,8 +14,20 @@ final case class RequestInfo( clientCapabilities: Option[ClientCapabilities] = None, clientInfo: Option[Implementation] = None, logLevel: Option[LoggingLevel] = None, - progressToken: Option[ProgressToken] = None + progressToken: Option[ProgressToken] = None, + inputResponses: Map[String, InputResponse] = Map.empty, + requestState: Option[String] = None ): + /** The client's answer to the form or URL elicitation asked under `key`, if the retry carries one. */ + def elicitResult(key: String): Option[ElicitResult] = inputResponses.get(key).collect { case InputResponse.Elicit(result) => result } + + /** The client's answer to the sampling request asked under `key`, if the retry carries one. */ + def samplingResult(key: String): Option[CreateMessageResult] = + inputResponses.get(key).collect { case InputResponse.Sampling(result) => result } + + /** The client's answer to the roots request asked under `key`, if the retry carries one. */ + def rootsResult(key: String): Option[ListRootsResult] = inputResponses.get(key).collect { case InputResponse.Roots(result) => result } + /** A modern request gets `notifications/message` only at or above its `logLevel`, and none without one. A legacy request gets all. */ private[server] def allowsLog(level: LoggingLevel): Boolean = if protocolVersion.exists(_.isModern) then logLevel.exists(minimum => level.ordinal >= minimum.ordinal) else true diff --git a/server/src/main/scala/chimp/server/Tool.scala b/server/src/main/scala/chimp/server/Tool.scala index ca68baef..870f6d51 100644 --- a/server/src/main/scala/chimp/server/Tool.scala +++ b/server/src/main/scala/chimp/server/Tool.scala @@ -105,7 +105,9 @@ case class PartialTool( requiredClientCapabilities ) -/** A tool with a known input type `I` and structured output type `O`, ready to be given its handling logic. */ +/** A tool with a known input type `I` and structured output type `O`, ready to be given its handling logic. The logic ends with a + * [[ToolResult]], or with [[InputRequired]] to ask the client for input first. + */ case class Tool[I, O]( name: String, description: Option[String], @@ -124,43 +126,49 @@ case class Tool[I, O]( copy(outputSchema = Some(ToolSchema.Raw(schema))) /** Attaches effectful logic, with access to the request headers. */ - def serverLogic[F[_]](logic: (I, Seq[Header]) => F[ToolResult[O]]): ServerTool[I, O, F, ServerContext[F]] = + def serverLogic[F[_]](logic: (I, Seq[Header]) => F[ToolResult[O] | InputRequired]): ServerTool[I, O, F, ServerContext[F]] = serverTool((input, _, headers) => logic(input, headers)) /** Attaches effectful logic, with access to the [[ServerContext]], which gives the facts of the request. */ - def serverLogicWithContext[F[_]](logic: (I, ServerContext[F], Seq[Header]) => F[ToolResult[O]]): ServerTool[I, O, F, ServerContext[F]] = + def serverLogicWithContext[F[_]]( + logic: (I, ServerContext[F], Seq[Header]) => F[ToolResult[O] | InputRequired] + ): ServerTool[I, O, F, ServerContext[F]] = serverTool(logic) /** Attaches effectful logic, with access to the principal; usable only on a [[SecuredMcpServer]]. */ - def securedServerLogic[F[_], P](logic: (I, P, Seq[Header]) => F[ToolResult[O]]): ServerTool[I, O, F, SecuredServerContext[F, P]] = + def securedServerLogic[F[_], P]( + logic: (I, P, Seq[Header]) => F[ToolResult[O] | InputRequired] + ): ServerTool[I, O, F, SecuredServerContext[F, P]] = serverTool((input, context, headers) => logic(input, context.principal, headers)) /** Attaches effectful logic with access to the [[StreamingServerContext]]; usable only on a streaming server. */ def streamingServerLogic[F[_]]( - logic: (I, StreamingServerContext[F], Seq[Header]) => F[ToolResult[O]] + logic: (I, StreamingServerContext[F], Seq[Header]) => F[ToolResult[O] | InputRequired] ): ServerTool[I, O, F, StreamingServerContext[F]] = serverTool(logic) /** Attaches effectful logic with access to the principal and the [[StreamingServerContext]]; usable only on a secured streaming server. */ def securedStreamingServerLogic[F[_], P]( - logic: (I, P, StreamingServerContext[F], Seq[Header]) => F[ToolResult[O]] + logic: (I, P, StreamingServerContext[F], Seq[Header]) => F[ToolResult[O] | InputRequired] ): ServerTool[I, O, F, SecuredStreamingServerContext[F, P]] = serverTool((input, context, headers) => logic(input, context.principal, context, headers)) /** Attaches synchronous logic that also receives the request headers. */ - def handleWithHeaders(logic: (I, Seq[Header]) => ToolResult[O]): ServerTool[I, O, Identity, ServerContext[Identity]] = + def handleWithHeaders(logic: (I, Seq[Header]) => ToolResult[O] | InputRequired): ServerTool[I, O, Identity, ServerContext[Identity]] = serverTool((i, _, headers) => logic(i, headers)) /** Attaches synchronous logic over just the decoded input. */ - def handle(logic: I => ToolResult[O]): ServerTool[I, O, Identity, ServerContext[Identity]] = + def handle(logic: I => ToolResult[O] | InputRequired): ServerTool[I, O, Identity, ServerContext[Identity]] = handleWithHeaders((i, _) => logic(i)) /** Attaches synchronous logic over the decoded input and the principal; usable only on a [[SecuredMcpServer]]. */ - def handleSecured[P](logic: (I, P) => ToolResult[O]): ServerTool[I, O, Identity, SecuredServerContext[Identity, P]] = + def handleSecured[P](logic: (I, P) => ToolResult[O] | InputRequired): ServerTool[I, O, Identity, SecuredServerContext[Identity, P]] = securedServerLogic[Identity, P]((i, principal, _) => logic(i, principal)) - private def serverTool[F[_], C <: ServerContext[F]](logic: (I, C, Seq[Header]) => F[ToolResult[O]]): ServerTool[I, O, F, C] = + private def serverTool[F[_], C <: ServerContext[F]]( + logic: (I, C, Seq[Header]) => F[ToolResult[O] | InputRequired] + ): ServerTool[I, O, F, C] = ServerTool(name, description, inputSchema, inputDecoder, outputSchema, annotations, logic, requiredClientCapabilities) /** A fully-defined tool: its metadata plus the logic handling a call, in effect `F` with context `C`. */ @@ -171,6 +179,6 @@ case class ServerTool[I, O, F[_], -C <: ServerContext[F]]( inputDecoder: Decoder[I], outputSchema: Option[ToolSchema], annotations: Option[ToolAnnotations], - logic: (I, C, Seq[Header]) => F[ToolResult[O]], + logic: (I, C, Seq[Header]) => F[ToolResult[O] | InputRequired], requiredClientCapabilities: Option[ClientCapabilities] = None ) diff --git a/server/src/test/scala/chimp/server/McpHandlerInputRequiredSpec.scala b/server/src/test/scala/chimp/server/McpHandlerInputRequiredSpec.scala new file mode 100644 index 00000000..d47afba8 --- /dev/null +++ b/server/src/test/scala/chimp/server/McpHandlerInputRequiredSpec.scala @@ -0,0 +1,226 @@ +package chimp.server + +import chimp.protocol.* +import io.circe.* +import io.circe.syntax.* +import org.scalatest.flatspec.AnyFlatSpec +import org.scalatest.matchers.should.Matchers +import sttp.model.StatusCode +import sttp.monad.{IdentityMonad, MonadError} +import sttp.shared.Identity +import sttp.tapir.Schema + +class McpHandlerInputRequiredSpec extends AnyFlatSpec with Matchers: + import JSONRPCMessage.* + + given MonadError[Identity] = IdentityMonad + + case class NoInput() derives Schema, Codec + + private val nameSchema = Json.obj("type" -> "object".asJson, "properties" -> Json.obj("name" -> Json.obj("type" -> "string".asJson))) + + private def name(ctx: ServerContext[Identity], key: String): Option[String] = + ctx.request.elicitResult(key).flatMap(_.content).flatMap(_.get("name")).flatMap(_.asString) + + private val greetTool = tool("greet") + .input[NoInput] + .serverLogicWithContext[Identity]: (_, ctx, _) => + name(ctx, "user_name") match + case Some(name) => ToolResult.text(s"Hello, $name!") + case None => InputRequired("user_name" -> InputRequired.elicitForm("What is your name?", nameSchema)) + + private val twoRoundsTool = tool("two_rounds") + .input[NoInput] + .serverLogicWithContext[Identity]: (_, ctx, _) => + (ctx.request.requestState, name(ctx, "first"), name(ctx, "second")) match + case (Some("round-2"), _, Some(second)) => ToolResult.text(s"done: $second") + case (Some("round-1"), Some(_), _) => + InputRequired("second" -> InputRequired.elicitForm("Second?", nameSchema)).withRequestState("round-2") + case _ => InputRequired("first" -> InputRequired.elicitForm("First?", nameSchema)).withRequestState("round-1") + + private val samplingParams = CreateMessageParams(List(SamplingMessage(Role.User, ToolContent.Text(text = "Hi?"))), maxTokens = 10) + + private val askAllTool = tool("ask_all") + .input[NoInput] + .handle: _ => + InputRequired( + "form" -> InputRequired.elicitForm("Name?", nameSchema), + "url" -> InputRequired.elicitUrl("Sign in", "https://example.com/login"), + "sample" -> InputRequired.sample(samplingParams), + "roots" -> InputRequired.listRoots + ) + + private val adaptiveTool = tool("adaptive") + .input[NoInput] + .serverLogicWithContext[Identity]: (_, ctx, _) => + if ctx.request.clientCapabilities.exists(_.sampling.isDefined) then InputRequired("q" -> InputRequired.sample(samplingParams)) + else InputRequired("q" -> InputRequired.elicitForm("Name?", nameSchema)) + + private val stateOnlyTool = tool("state_only") + .input[NoInput] + .serverLogicWithContext[Identity]: (_, ctx, _) => + ctx.request.requestState.fold(InputRequired.withRequestState("again"))(state => ToolResult.text(s"state $state")) + + private val greetPrompt = prompt("greet") + .serverLogicWithContext[Identity]: (_, ctx, _) => + name(ctx, "user_name") match + case Some(name) => GetPromptResult(messages = List(PromptMessage(Role.User, ToolContent.Text(text = s"Hello, $name")))) + case None => InputRequired("user_name" -> InputRequired.elicitForm("Name?", nameSchema)) + + private val rootsResource = resource("test://roots") + .serverLogicWithContext[Identity]: (ctx, _) => + ctx.request.rootsResult("roots") match + case Some(roots) => Right(List(ResourceContents.Text("test://roots", roots.roots.map(_.uri).mkString(",")))) + case None => InputRequired("roots" -> InputRequired.listRoots) + + private val rootsTemplate = resourceTemplate("test://roots/{id}") + .serverLogicWithContext[Identity]: (_, uri, ctx, _) => + ctx.request.rootsResult("roots") match + case Some(roots) => Right(List(ResourceContents.Text(uri, roots.roots.map(_.uri).mkString(",")))) + case None => InputRequired("roots" -> InputRequired.listRoots) + + private val handler = McpHandler( + McpServer[Identity]() + .addTools(greetTool, twoRoundsTool, askAllTool, adaptiveTool, stateOnlyTool) + .addPrompt(greetPrompt) + .addResource(rootsResource) + .addResourceTemplate(rootsTemplate) + ) + + private val allCapabilities = + Json.obj("sampling" -> Json.obj(), "roots" -> Json.obj(), "elicitation" -> Json.obj("form" -> Json.obj(), "url" -> Json.obj())) + + private def call(method: String, params: Json, capabilities: Json = allCapabilities, modern: Boolean = true): McpResponse = + val meta = + if modern then Json.obj(ProtocolMeta.ProtocolVersionKey -> "2026-07-28".asJson, ProtocolMeta.ClientCapabilities -> capabilities) + else Json.obj() + val request: JSONRPCMessage = Request(method = method, params = Some(params.deepMerge(Json.obj("_meta" -> meta))), id = RequestId("r")) + handler.handleJsonRpc(request.asJson, Seq.empty) + + private def callTool(tool: String, extra: (String, Json)*): McpResponse = + call("tools/call", Json.obj(("name" -> tool.asJson) +: ("arguments" -> Json.obj()) +: extra*)) + + private def bodyOf(response: McpResponse): Json = response.body.getOrElse(fail("Expected a body")) + + private def resultOf(response: McpResponse): Json = + bodyOf(response).as[JSONRPCMessage].getOrElse(fail("decode")) match + case Response(_, _, result) => result + case other => fail(s"Expected Response, got $other") + + private def errorOf(response: McpResponse): JSONRPCErrorObject = + bodyOf(response).as[JSONRPCMessage].getOrElse(fail("decode")) match + case Error(_, _, error) => error + case other => fail(s"Expected Error, got $other") + + private def nameAnswer(value: String): Json = ElicitResult(ElicitAction.Accept, Some(Map("name" -> value.asJson))).asJson + + private def textOf(result: Json): Option[String] = result.hcursor.downField("content").downArray.get[String]("text").toOption + + "An input-required outcome" should "reach a modern client as resultType input_required with its keyed input requests" in: + val response = callTool("greet") + response.statusCode shouldBe StatusCode.Ok + val result = resultOf(response) + result.hcursor.get[String]("resultType") shouldBe Right("input_required") + result.hcursor.downField("inputRequests").downField("user_name").get[String]("method") shouldBe Right("elicitation/create") + result.hcursor.downField("_meta").downField(ProtocolMeta.ServerInfo).succeeded shouldBe true + result.hcursor.downField("requestState").succeeded shouldBe false + result.hcursor.downField("ttlMs").succeeded shouldBe false + + it should "let the handler read the answer on the retry, and ignore keys it did not ask for" in: + val responses = Json.obj("user_name" -> nameAnswer("Alice"), "unexpected" -> nameAnswer("Mallory")) + val result = resultOf(callTool("greet", "inputResponses" -> responses)) + result.hcursor.get[String]("resultType") shouldBe Right("complete") + textOf(result) shouldBe Some("Hello, Alice!") + + it should "let the handler ask again when the retry lacks an answer it needs" in: + val result = resultOf(callTool("greet", "inputResponses" -> Json.obj("wrong_key" -> nameAnswer("Alice")))) + result.hcursor.get[String]("resultType") shouldBe Right("input_required") + + it should "carry the request state across several rounds" in: + val first = resultOf(callTool("two_rounds")) + first.hcursor.get[String]("requestState") shouldBe Right("round-1") + val second = + resultOf(callTool("two_rounds", "inputResponses" -> Json.obj("first" -> nameAnswer("a")), "requestState" -> "round-1".asJson)) + second.hcursor.get[String]("requestState") shouldBe Right("round-2") + second.hcursor.downField("inputRequests").keys.map(_.toList) shouldBe Some(List("second")) + val third = + resultOf(callTool("two_rounds", "inputResponses" -> Json.obj("second" -> nameAnswer("b")), "requestState" -> "round-2".asJson)) + textOf(third) shouldBe Some("done: b") + + it should "carry only a request state when the handler asks for no input" in: + val result = resultOf(callTool("state_only")) + result.hcursor.get[String]("requestState") shouldBe Right("again") + result.hcursor.downField("inputRequests").succeeded shouldBe false + textOf(resultOf(callTool("state_only", "requestState" -> "again".asJson))) shouldBe Some("state again") + + it should "encode form, URL, sampling and roots requests as the schema defines them" in: + val requests = resultOf(callTool("ask_all")).hcursor.downField("inputRequests") + requests.downField("form").downField("params").get[String]("message") shouldBe Right("Name?") + requests.downField("url").downField("params").get[String]("mode") shouldBe Right("url") + requests.downField("sample").get[String]("method") shouldBe Right("sampling/createMessage") + requests.downField("roots").get[String]("method") shouldBe Right("roots/list") + + it should "let the handler choose what to ask for from the client capabilities" in: + def asked(capabilities: Json) = + call("tools/call", Json.obj("name" -> "adaptive".asJson), capabilities).body.flatMap( + _.hcursor.downField("result").downField("inputRequests").downField("q").get[String]("method").toOption + ) + asked(Json.obj("sampling" -> Json.obj())) shouldBe Some("sampling/createMessage") + asked(Json.obj("elicitation" -> Json.obj())) shouldBe Some("elicitation/create") + + it should "be possible for prompts, resources and resource templates" in: + resultOf(call("prompts/get", Json.obj("name" -> "greet".asJson))).hcursor.get[String]("resultType") shouldBe Right("input_required") + for uri <- List("test://roots", "test://roots/1") do + withClue(uri): + val first = resultOf(call("resources/read", Json.obj("uri" -> uri.asJson))) + first.hcursor.get[String]("resultType") shouldBe Right("input_required") + first.hcursor.downField("ttlMs").succeeded shouldBe false + val roots = ListRootsResult(List(Root("file:///a"))).asJson + val retry = call("resources/read", Json.obj("uri" -> uri.asJson, "inputResponses" -> Json.obj("roots" -> roots))) + resultOf(retry).hcursor.downField("contents").downArray.get[String]("text") shouldBe Right("file:///a") + val promptRetry = call("prompts/get", Json.obj("name" -> "greet".asJson, "inputResponses" -> Json.obj("user_name" -> nameAnswer("Bo")))) + resultOf(promptRetry).hcursor.downField("messages").downArray.downField("content").get[String]("text") shouldBe Right("Hello, Bo") + + it should "fail with -32021, the missing capabilities and HTTP 400 when the client did not declare what an input request needs" in: + val cases = List( + Json.obj() -> Json.obj( + "sampling" -> Json.obj(), + "roots" -> Json.obj(), + "elicitation" -> Json.obj("form" -> Json.obj(), "url" -> Json.obj()) + ), + Json.obj("sampling" -> Json.obj(), "roots" -> Json.obj(), "elicitation" -> Json.obj()) -> Json.obj( + "elicitation" -> Json.obj("url" -> Json.obj()) + ), + Json.obj("sampling" -> Json.obj(), "roots" -> Json.obj(), "elicitation" -> Json.obj("url" -> Json.obj())) -> Json.obj( + "elicitation" -> Json.obj("form" -> Json.obj()) + ) + ) + for (declared, missing) <- cases do + withClue(declared.noSpaces): + val response = call("tools/call", Json.obj("name" -> "ask_all".asJson), declared) + response.statusCode shouldBe StatusCode.BadRequest + val error = errorOf(response) + error.code shouldBe JSONRPCErrorCodes.MissingRequiredClientCapability.code + error.data.flatMap(_.hcursor.downField("requiredCapabilities").focus) shouldBe Some(missing) + + it should "fail with -32602 and HTTP 400 when inputResponses or requestState is malformed, before the handler runs" in: + val malformed = List( + "inputResponses" -> 12345.asJson, + "inputResponses" -> Json.Null, + "inputResponses" -> Json.arr(), + "inputResponses" -> Json.obj("user_name" -> 12345.asJson), + "inputResponses" -> Json.obj("user_name" -> Json.obj("action" -> "maybe".asJson)), + "requestState" -> 1.asJson + ) + for field <- malformed do + withClue(field): + val response = callTool("greet", field) + response.statusCode shouldBe StatusCode.BadRequest + errorOf(response).code shouldBe JSONRPCErrorCodes.InvalidParams.code + + it should "become an internal error naming the required protocol version on a legacy request" in: + val response = call("tools/call", Json.obj("name" -> "greet".asJson, "arguments" -> Json.obj()), modern = false) + response.statusCode shouldBe StatusCode.Ok + val error = errorOf(response) + error.code shouldBe JSONRPCErrorCodes.InternalError.code + error.message should include("2026-07-28") From 673cb2973011c4c545a9cd5357023c6ffe343ae9 Mon Sep 17 00:00:00 2001 From: Ondra Pelech Date: Thu, 19 Nov 2026 17:49:05 +0100 Subject: [PATCH 16/31] feat(T14): answer an early HTTP error of a streaming call as plain JSON A streaming HTTP server opened the 200 event stream before the handler ran, so a -32021 for an input request the client has no capability for could only travel inside it. The backends (Ox, ZIO, Pekko) now start the handler and wait for its first message: if the handler ends with an error that has its own HTTP status before it sends anything, that error goes as a plain application/json response with that status; otherwise the stream carries the messages and the response as before. --- .../server/ox/OxServerHttpTransport.scala | 52 +++++++--- .../chimp/server/ox/OxMcpServerHttpSpec.scala | 2 + .../chimp/server/pekko/PekkoOutbound.scala | 5 +- .../pekko/PekkoServerHttpTransport.scala | 58 +++++++---- .../server/pekko/PekkoMcpServerHttpSpec.scala | 2 + .../server/zio/ZioServerHttpTransport.scala | 45 +++++---- .../server/zio/ZioMcpServerHttpSpec.scala | 2 + .../transport/JsonRpcHttpResponses.scala | 14 ++- .../SecuredServerStreamingHttpTransport.scala | 2 +- .../ServerStreamingHttpTransport.scala | 12 ++- .../McpServerInputRequiredHttpTests.scala | 99 +++++++++++++++++++ 11 files changed, 230 insertions(+), 63 deletions(-) create mode 100644 server/src/test/scala/chimp/server/McpServerInputRequiredHttpTests.scala diff --git a/server-streaming/server-ox/src/main/scala/chimp/server/ox/OxServerHttpTransport.scala b/server-streaming/server-ox/src/main/scala/chimp/server/ox/OxServerHttpTransport.scala index b6d4823b..77e9f5c5 100644 --- a/server-streaming/server-ox/src/main/scala/chimp/server/ox/OxServerHttpTransport.scala +++ b/server-streaming/server-ox/src/main/scala/chimp/server/ox/OxServerHttpTransport.scala @@ -1,19 +1,25 @@ package chimp.server.ox import chimp.protocol.JSONRPCMessage -import chimp.server.{ListenRequest, OutboundSink, SubscriptionOutput} -import chimp.server.transport.ServerStreamingHttpTransport +import chimp.server.{ListenRequest, McpResponse, OutboundSink, SubscriptionOutput} +import chimp.server.transport.{plainJsonError, ServerStreamingHttpTransport} import io.circe.Json import io.circe.syntax.* import ox.* -import ox.channels.Channel +import org.slf4j.LoggerFactory +import ox.channels.{Channel, ChannelClosed} import ox.flow.Flow +import sttp.model.StatusCode import sttp.model.sse.ServerSentEvent import sttp.shared.Identity import sttp.tapir.StreamBodyIO import sttp.tapir.server.netty.sync.{serverSentEventsBody, OxStreams} +import scala.util.control.NonFatal + final class OxServerHttpTransport(path: List[String]) extends ServerStreamingHttpTransport[Identity, OxStreams](path): + private val log = LoggerFactory.getLogger(classOf[OxServerHttpTransport]) + val streams: OxStreams = OxStreams type EventStream = Flow[ServerSentEvent] @@ -22,16 +28,36 @@ final class OxServerHttpTransport(path: List[String]) extends ServerStreamingHtt val emptyStream: EventStream = Flow.empty - def eventStream(handle: OutboundSink[Identity] => Option[Json]): Flow[ServerSentEvent] = - Flow.usingEmit: emit => - supervised: - val outbound = Channel.buffered[Json](64) - val sink = new OutboundSink[Identity]: - def send(message: JSONRPCMessage): Unit = outbound.send(message.asJson.deepDropNullValues) - forkDiscard: - try handle(sink).foreach(outbound.send) - finally outbound.done() - outbound.foreach(json => emit(ServerSentEvent(data = Some(json.noSpaces)))) + def eventStream(handle: OutboundSink[Identity] => McpResponse): Either[(StatusCode, Json), Flow[ServerSentEvent]] = + val outbound = Channel.buffered[Outbound](64) + val sink = new OutboundSink[Identity]: + def send(message: JSONRPCMessage): Unit = outbound.sendOrClosed(Outbound.Message(message.asJson.deepDropNullValues)).discard + val worker = oxThreadFactory.newThread: () => + try outbound.sendOrClosed(Outbound.Final(handle(sink))).discard + catch case NonFatal(e) => log.warn("Failed to handle the JSON-RPC message", e) + finally outbound.doneOrClosed().discard + worker.start() + + def stream(first: Outbound | ChannelClosed): Flow[ServerSentEvent] = + Flow.usingEmit: emit => + def emitBody(item: Outbound | ChannelClosed): Unit = item match + case Outbound.Message(json) => emit(ServerSentEvent(data = Some(json.noSpaces))) + case Outbound.Final(response) => response.body.foreach(json => emit(ServerSentEvent(data = Some(json.noSpaces)))) + case _: ChannelClosed => () + try + emitBody(first) + outbound.foreach(emitBody) + finally + outbound.doneOrClosed().discard + worker.interrupt() + + outbound.receiveOrClosed() match + case first @ Outbound.Final(response) => plainJsonError(response).toLeft(stream(first)) + case first => Right(stream(first)) + + private enum Outbound: + case Message(json: Json) + case Final(response: McpResponse) private[server] def subscriptionStream(listen: ListenRequest): Flow[ServerSentEvent] = Flow.usingEmit: emit => diff --git a/server-streaming/server-ox/src/test/scala/chimp/server/ox/OxMcpServerHttpSpec.scala b/server-streaming/server-ox/src/test/scala/chimp/server/ox/OxMcpServerHttpSpec.scala index 5a6fc7e8..4c52d7a1 100644 --- a/server-streaming/server-ox/src/test/scala/chimp/server/ox/OxMcpServerHttpSpec.scala +++ b/server-streaming/server-ox/src/test/scala/chimp/server/ox/OxMcpServerHttpSpec.scala @@ -8,6 +8,7 @@ import chimp.server.transport.SecuredServerStreamingHttpTransport import chimp.server.{ tool, McpServer, + McpServerInputRequiredHttpTests, McpServerStreamingTests, McpServerSubscriptionHttpTests, McpServerTests, @@ -39,6 +40,7 @@ class OxMcpServerHttpSpec extends McpServerTests[Identity] with McpServerStreamingTests[Identity] with McpServerSubscriptionHttpTests[Identity] + with McpServerInputRequiredHttpTests[Identity] with SecuredMcpServerTests[Identity] with SecuredMcpServerStreamingTests[Identity] with SyncToFuture: diff --git a/server-streaming/server-pekko/src/main/scala/chimp/server/pekko/PekkoOutbound.scala b/server-streaming/server-pekko/src/main/scala/chimp/server/pekko/PekkoOutbound.scala index e3189bb7..738f0aea 100644 --- a/server-streaming/server-pekko/src/main/scala/chimp/server/pekko/PekkoOutbound.scala +++ b/server-streaming/server-pekko/src/main/scala/chimp/server/pekko/PekkoOutbound.scala @@ -1,6 +1,5 @@ package chimp.server.pekko -import io.circe.Json import org.apache.pekko.stream.QueueOfferResult import org.apache.pekko.stream.scaladsl.SourceQueueWithComplete import org.slf4j.LoggerFactory @@ -13,8 +12,8 @@ private[pekko] object PekkoOutbound: val defaultBufferSize: Int = 64 val defaultMaxConcurrentSends: Int = 64 - def offer(queue: SourceQueueWithComplete[Json], json: Json)(using ExecutionContext): Future[Unit] = - queue.offer(json).flatMap { + def offer[A](queue: SourceQueueWithComplete[A], message: A)(using ExecutionContext): Future[Unit] = + queue.offer(message).flatMap { case QueueOfferResult.Enqueued => Future.unit case QueueOfferResult.Dropped => diff --git a/server-streaming/server-pekko/src/main/scala/chimp/server/pekko/PekkoServerHttpTransport.scala b/server-streaming/server-pekko/src/main/scala/chimp/server/pekko/PekkoServerHttpTransport.scala index b1df7a5c..fdd15226 100644 --- a/server-streaming/server-pekko/src/main/scala/chimp/server/pekko/PekkoServerHttpTransport.scala +++ b/server-streaming/server-pekko/src/main/scala/chimp/server/pekko/PekkoServerHttpTransport.scala @@ -1,15 +1,16 @@ package chimp.server.pekko import chimp.protocol.JSONRPCMessage -import chimp.server.{ListenRequest, OutboundSink, SubscriptionOutput} -import chimp.server.transport.ServerStreamingHttpTransport +import chimp.server.{ListenRequest, McpResponse, OutboundSink, SubscriptionOutput} +import chimp.server.transport.{plainJsonError, ServerStreamingHttpTransport} import io.circe.Json import io.circe.syntax.* import org.apache.pekko.NotUsed -import org.apache.pekko.stream.scaladsl.Source +import org.apache.pekko.stream.scaladsl.{Sink, Source} import org.apache.pekko.stream.{Materializer, OverflowStrategy} import org.slf4j.LoggerFactory import sttp.capabilities.pekko.PekkoStreams +import sttp.model.StatusCode import sttp.model.sse.ServerSentEvent import sttp.tapir.server.pekkohttp.PekkoServerSentEvents import sttp.tapir.{streamTextBody, CodecFormat, StreamBodyIO} @@ -39,24 +40,35 @@ final class PekkoServerHttpTransport( val emptyStream: EventStream = Source.empty[ServerSentEvent] - def eventStream(handle: OutboundSink[Future] => Future[Option[Json]]): Future[EventStream] = - Future.successful: - Source - .queue[Json](outboundBufferSize, OverflowStrategy.backpressure, maxConcurrentSends) - .mapMaterializedValue: queue => - val sink = new OutboundSink[Future]: - def send(message: JSONRPCMessage): Future[Unit] = PekkoOutbound.offer(queue, message.asJson.deepDropNullValues) - Try(handle(sink)) - .fold(Future.failed, identity) - .onComplete: - case Success(response) => - val lastMessage = response.fold(Future.unit)(json => PekkoOutbound.offer(queue, json)) - lastMessage.onComplete(_ => queue.complete()) - case Failure(t) => - log.warn("Failed to handle the JSON-RPC message", t) - queue.complete() - NotUsed - .map(json => ServerSentEvent(data = Some(json.noSpaces))) + def eventStream(handle: OutboundSink[Future] => Future[McpResponse]): Future[Either[(StatusCode, Json), EventStream]] = + val (queue, outbound) = + Source.queue[Outbound](outboundBufferSize, OverflowStrategy.backpressure, maxConcurrentSends).preMaterialize() + val sink = new OutboundSink[Future]: + def send(message: JSONRPCMessage): Future[Unit] = PekkoOutbound.offer(queue, Outbound.Message(message.asJson.deepDropNullValues)) + Try(handle(sink)) + .fold(Future.failed, identity) + .onComplete: + case Success(response) => PekkoOutbound.offer(queue, Outbound.Final(response)).onComplete(_ => queue.complete()) + case Failure(t) => + log.warn("Failed to handle the JSON-RPC message", t) + queue.complete() + outbound + .prefixAndTail(1) + .runWith(Sink.head) + .map: (first, rest) => + val stream = (Source(first) ++ rest) + .mapConcat: + case Outbound.Message(json) => List(json) + case Outbound.Final(response) => response.body.toList + .map(json => ServerSentEvent(data = Some(json.noSpaces))) + first.headOption match + case Some(Outbound.Final(response)) => + plainJsonError(response) match + case Some(error) => + val _ = rest.runWith(Sink.ignore) + Left(error) + case None => Right(stream) + case _ => Right(stream) private[server] def subscriptionStream(listen: ListenRequest): EventStream = Source @@ -70,3 +82,7 @@ final class PekkoServerHttpTransport( done.onComplete(_ => subscription.cancel()) NotUsed .map(json => ServerSentEvent(data = Some(json.noSpaces))) + + private enum Outbound: + case Message(json: Json) + case Final(response: McpResponse) diff --git a/server-streaming/server-pekko/src/test/scala/chimp/server/pekko/PekkoMcpServerHttpSpec.scala b/server-streaming/server-pekko/src/test/scala/chimp/server/pekko/PekkoMcpServerHttpSpec.scala index d5066ccb..9ecf4080 100644 --- a/server-streaming/server-pekko/src/test/scala/chimp/server/pekko/PekkoMcpServerHttpSpec.scala +++ b/server-streaming/server-pekko/src/test/scala/chimp/server/pekko/PekkoMcpServerHttpSpec.scala @@ -6,6 +6,7 @@ import chimp.protocol.{Implementation, ProtocolVersion} import chimp.server.transport.SecuredServerStreamingHttpTransport import chimp.server.{ McpServer, + McpServerInputRequiredHttpTests, McpServerStreamingTests, McpServerSubscriptionHttpTests, McpServerTests, @@ -33,6 +34,7 @@ class PekkoMcpServerHttpSpec extends McpServerTests[Future] with McpServerStreamingTests[Future] with McpServerSubscriptionHttpTests[Future] + with McpServerInputRequiredHttpTests[Future] with SecuredMcpServerTests[Future] with SecuredMcpServerStreamingTests[Future] with PekkoToFuture: diff --git a/server-streaming/server-zio/src/main/scala/chimp/server/zio/ZioServerHttpTransport.scala b/server-streaming/server-zio/src/main/scala/chimp/server/zio/ZioServerHttpTransport.scala index 43b68f5d..27766bb2 100644 --- a/server-streaming/server-zio/src/main/scala/chimp/server/zio/ZioServerHttpTransport.scala +++ b/server-streaming/server-zio/src/main/scala/chimp/server/zio/ZioServerHttpTransport.scala @@ -1,11 +1,12 @@ package chimp.server.zio import chimp.protocol.JSONRPCMessage -import chimp.server.{ListenRequest, OutboundSink, SubscriptionOutput} -import chimp.server.transport.ServerStreamingHttpTransport +import chimp.server.{ListenRequest, McpResponse, OutboundSink, SubscriptionOutput} +import chimp.server.transport.{plainJsonError, ServerStreamingHttpTransport} import io.circe.Json import io.circe.syntax.* import sttp.capabilities.zio.ZioStreams +import sttp.model.StatusCode import sttp.model.sse.ServerSentEvent import sttp.tapir.* import sttp.tapir.ztapir.ZioServerSentEvents @@ -25,22 +26,29 @@ final class ZioServerHttpTransport(path: List[String]) extends ServerStreamingHt val emptyStream: EventStream = ZStream.empty - def eventStream(handle: OutboundSink[Task] => Task[Option[Json]]): Task[EventStream] = - ZIO.succeed { - ZStream.unwrapScoped { - for - queue <- Queue.unbounded[Outbound] - sink = new OutboundSink[Task]: - def send(message: JSONRPCMessage): Task[Unit] = - queue.offer(Outbound.Message(message.asJson)).unit - _ <- handle(sink) - .flatMap(response => ZIO.foreachDiscard(response)(json => queue.offer(Outbound.Message(json)))) - .ensuring(queue.offer(Outbound.Close)) - .catchAllCause(_ => ZIO.unit) - .forkScoped - yield ZStream.fromQueue(queue).collectWhile { case Outbound.Message(json) => ServerSentEvent(data = Some(json.noSpaces)) } - } - } + def eventStream(handle: OutboundSink[Task] => Task[McpResponse]): Task[Either[(StatusCode, Json), EventStream]] = + for + queue <- Queue.unbounded[Outbound] + sink = new OutboundSink[Task]: + def send(message: JSONRPCMessage): Task[Unit] = + queue.offer(Outbound.Message(message.asJson)).unit + worker <- handle(sink) + .flatMap(response => queue.offer(Outbound.Final(response))) + .catchAllCause(cause => ZIO.logWarningCause("Failed to handle the JSON-RPC message", cause)) + .ensuring(queue.offer(Outbound.Close)) + .forkDaemon + first <- queue.take + yield + val stream = (ZStream.succeed(first) ++ ZStream.fromQueue(queue)) + .collectWhile: + case Outbound.Message(json) => Some(json) + case Outbound.Final(response) => response.body + .collectSome + .map(json => ServerSentEvent(data = Some(json.noSpaces))) + .ensuring(worker.interrupt) + first match + case Outbound.Final(response) => plainJsonError(response).toLeft(stream) + case _ => Right(stream) private[server] def subscriptionStream(listen: ListenRequest): EventStream = ZStream.unwrapScoped { @@ -60,4 +68,5 @@ final class ZioServerHttpTransport(path: List[String]) extends ServerStreamingHt private enum Outbound: case Message(json: Json) + case Final(response: McpResponse) case Close diff --git a/server-streaming/server-zio/src/test/scala/chimp/server/zio/ZioMcpServerHttpSpec.scala b/server-streaming/server-zio/src/test/scala/chimp/server/zio/ZioMcpServerHttpSpec.scala index 9a2eb2e3..b35b8460 100644 --- a/server-streaming/server-zio/src/test/scala/chimp/server/zio/ZioMcpServerHttpSpec.scala +++ b/server-streaming/server-zio/src/test/scala/chimp/server/zio/ZioMcpServerHttpSpec.scala @@ -7,6 +7,7 @@ import chimp.protocol.{Implementation, ProtocolVersion} import chimp.server.transport.SecuredServerStreamingHttpTransport import chimp.server.{ McpServer, + McpServerInputRequiredHttpTests, McpServerStreamingTests, McpServerSubscriptionHttpTests, McpServerTests, @@ -34,6 +35,7 @@ class ZioMcpServerHttpSpec extends McpServerTests[Task] with McpServerStreamingTests[Task] with McpServerSubscriptionHttpTests[Task] + with McpServerInputRequiredHttpTests[Task] with SecuredMcpServerTests[Task] with SecuredMcpServerStreamingTests[Task] with ZioToFuture: diff --git a/server/src/main/scala/chimp/server/transport/JsonRpcHttpResponses.scala b/server/src/main/scala/chimp/server/transport/JsonRpcHttpResponses.scala index 82112502..9fa7ae6c 100644 --- a/server/src/main/scala/chimp/server/transport/JsonRpcHttpResponses.scala +++ b/server/src/main/scala/chimp/server/transport/JsonRpcHttpResponses.scala @@ -27,7 +27,8 @@ private[transport] val jsonRejectionOutput: EndpointOutput[JsonRejection] = stat /** Checks the origin, then validates the request with `rejection` (runs no tool logic). A rejection - for example a modern validation error - * is returned on the left, to be sent as a plain JSON error with its own HTTP status. An accepted `subscriptions/listen` request gets a - * 200 subscription stream, which stays open until one side ends it; any other request runs `handle` inside a 200 event stream. + * 200 subscription stream, which stays open until one side ends it; any other request runs `handle`, see + * [[ServerStreamingHttpTransport.eventStream]]. */ private[transport] def respondWithEventStream[F[_], Caps]( originCheck: OriginCheck, @@ -35,7 +36,7 @@ private[transport] def respondWithEventStream[F[_], Caps]( backend: ServerStreamingHttpTransport[F, Caps], rejection: => Option[McpResponse], listen: => Option[ListenRequest] -)(handle: OutboundSink[F] => F[Option[Json]])(using m: MonadError[F]): F[Either[JsonRejection, (StatusCode, backend.EventStream)]] = +)(handle: OutboundSink[F] => F[McpResponse])(using m: MonadError[F]): F[Either[JsonRejection, (StatusCode, backend.EventStream)]] = if !originAllowed(originCheck, headers) then m.unit(Right((StatusCode.Forbidden, backend.emptyStream))) else rejection match @@ -43,4 +44,11 @@ private[transport] def respondWithEventStream[F[_], Caps]( case None => listen match case Some(request) => m.unit(Right((StatusCode.Ok, backend.subscriptionStream(request)))) - case None => backend.eventStream(handle).map(events => Right((StatusCode.Ok, events))) + case None => backend.eventStream(handle).map(_.map(events => (StatusCode.Ok, events))) + +/** The plain JSON error to send instead of an event stream, when the handler ends with an error which has its own HTTP status (for example + * a `-32021`) before it sends any message. + */ +private[server] def plainJsonError(response: McpResponse): Option[(StatusCode, Json)] = response match + case McpResponse.JsonError(status, json) => Some((status, json)) + case _ => None diff --git a/server/src/main/scala/chimp/server/transport/SecuredServerStreamingHttpTransport.scala b/server/src/main/scala/chimp/server/transport/SecuredServerStreamingHttpTransport.scala index 5291100a..641c466a 100644 --- a/server/src/main/scala/chimp/server/transport/SecuredServerStreamingHttpTransport.scala +++ b/server/src/main/scala/chimp/server/transport/SecuredServerStreamingHttpTransport.scala @@ -53,7 +53,7 @@ final case class SecuredServerStreamingHttpTransport[F[_], Caps, S, E, P]( ) { sink => val makeContext: RequestInfo => SecuredStreamingServerContext[F, P] = info => SinkSecuredStreamingServerContext(sink, info, principal) - handler.handleJsonRpc(json, headers, makeContext).map(_.body) + handler.handleJsonRpc(json, headers, makeContext) }.map(_.left.map(Right(_))) } ) diff --git a/server/src/main/scala/chimp/server/transport/ServerStreamingHttpTransport.scala b/server/src/main/scala/chimp/server/transport/ServerStreamingHttpTransport.scala index a50ff117..ef10ea48 100644 --- a/server/src/main/scala/chimp/server/transport/ServerStreamingHttpTransport.scala +++ b/server/src/main/scala/chimp/server/transport/ServerStreamingHttpTransport.scala @@ -3,9 +3,8 @@ package chimp.server.transport import chimp.server.* import io.circe.Json import sttp.capabilities.Streams -import sttp.model.Header +import sttp.model.{Header, StatusCode} import sttp.monad.MonadError -import sttp.monad.syntax.* import sttp.tapir.* import sttp.tapir.json.circe.* import sttp.tapir.server.ServerEndpoint @@ -26,7 +25,12 @@ abstract class ServerStreamingHttpTransport[F[_], Caps](path: List[String]) exte type EventStream def sseBody: StreamBodyIO[streams.BinaryStream, EventStream, Caps] def emptyStream: EventStream - def eventStream(handle: OutboundSink[F] => F[Option[Json]]): F[EventStream] + + /** Runs `handle`, which sends its messages to the sink and ends with the response. If it ends with an error which has its own HTTP status + * (see [[plainJsonError]]) before it sends any message, that error is returned on the left, to be sent as plain JSON. Otherwise the + * messages and then the response's body go on a 200 event stream. + */ + def eventStream(handle: OutboundSink[F] => F[McpResponse]): F[Either[(StatusCode, Json), EventStream]] /** The stream of an accepted `subscriptions/listen` request. It opens the subscription when the stream starts, and cancels it when the * client closes the stream. The server ends it by closing the subscription's output. @@ -57,7 +61,7 @@ abstract class ServerStreamingHttpTransport[F[_], Caps](path: List[String]) exte ) { sink => val makeContext: RequestInfo => StreamingServerContext[F] = info => SinkStreamingServerContext(sink, info) - handler.handleJsonRpc(json, headers, makeContext).map(_.body) + handler.handleJsonRpc(json, headers, makeContext) } } ) diff --git a/server/src/test/scala/chimp/server/McpServerInputRequiredHttpTests.scala b/server/src/test/scala/chimp/server/McpServerInputRequiredHttpTests.scala new file mode 100644 index 00000000..a6456bfa --- /dev/null +++ b/server/src/test/scala/chimp/server/McpServerInputRequiredHttpTests.scala @@ -0,0 +1,99 @@ +package chimp.server + +import chimp.protocol.* +import io.circe.syntax.* +import io.circe.{parser, Codec, Json} +import org.scalatest.Assertion +import org.scalatest.flatspec.AsyncFlatSpec +import org.scalatest.matchers.should.Matchers +import sttp.monad.syntax.* +import sttp.tapir.Schema + +import java.net.URI +import java.net.http.{HttpClient, HttpRequest, HttpResponse} +import scala.concurrent.Future + +/** Input-required outcomes over Streamable HTTP, where an error with its own HTTP status must not hide in a 200 event stream. */ +trait McpServerInputRequiredHttpTests[F[_]] extends AsyncFlatSpec with Matchers: + this: ToFuture[F] => + + /** Serves `server` on a streaming HTTP endpoint and runs the blocking `test` with the endpoint's URI. */ + protected def withStreamingHttpEndpoint(server: StreamingMcpServer[F])(test: URI => Assertion): Future[Assertion] + + private case class NoInput() derives Codec, Schema + + private val sampling = InputRequired.sample( + CreateMessageParams(List(SamplingMessage(Role.User, ToolContent.Text(text = "Capital of France?"))), maxTokens = 10) + ) + + private val inputRequiredServer: StreamingMcpServer[F] = + StreamingMcpServer[F]() + .addTool( + tool("ask") + .input[NoInput] + .serverLogicWithContext[F]((_, ctx, _) => + monad.unit(ctx.request.samplingResult("q").fold(InputRequired("q" -> sampling))(_ => ToolResult.text("answered"))) + ) + ) + .addStreamingTool( + tool("progress_then_ask") + .input[NoInput] + .streamingServerLogic[F]((_, ctx, _) => ctx.reportProgress(50, Some(100)).map(_ => InputRequired("q" -> sampling))) + ) + + private val httpClient = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build() + + private def callTool(uri: URI, name: String, capabilities: Json): HttpResponse[String] = + val meta = Json.obj( + ProtocolMeta.ProtocolVersionKey -> "2026-07-28".asJson, + ProtocolMeta.ClientCapabilities -> capabilities, + "progressToken" -> "p".asJson + ) + val body = Json.obj( + "jsonrpc" -> "2.0".asJson, + "id" -> 1.asJson, + "method" -> "tools/call".asJson, + "params" -> Json.obj("name" -> name.asJson, "arguments" -> Json.obj(), "_meta" -> meta) + ) + val request = HttpRequest + .newBuilder(uri) + .header("Content-Type", "application/json") + .header("Accept", "application/json, text/event-stream") + .header(ProtocolMeta.ProtocolVersionHeader, "2026-07-28") + .header("Mcp-Method", "tools/call") + .header("Mcp-Name", name) + .POST(HttpRequest.BodyPublishers.ofString(body.noSpaces)) + .build() + httpClient.send(request, HttpResponse.BodyHandlers.ofString()) + + private def contentType(response: HttpResponse[String]): String = response.headers().firstValue("Content-Type").orElse("") + + private def events(response: HttpResponse[String]): List[Json] = + response.body().linesIterator.collect { case s"data:$data" => parser.parse(data.trim).toOption }.flatten.toList + + "a streaming HTTP server" should "send an input-required result on the event stream" in: + withStreamingHttpEndpoint(inputRequiredServer): uri => + val response = callTool(uri, "ask", Json.obj("sampling" -> Json.obj())) + response.statusCode() shouldBe 200 + contentType(response) should include("text/event-stream") + val result = events(response).flatMap(_.hcursor.downField("result").focus) + result.map(_.hcursor.get[String]("resultType")) shouldBe List(Right("input_required")) + result.map(_.hcursor.downField("inputRequests").downField("q").get[String]("method")) shouldBe List(Right("sampling/createMessage")) + + it should "answer an input request the client has no capability for with a plain JSON -32021 and HTTP 400" in: + withStreamingHttpEndpoint(inputRequiredServer): uri => + val response = callTool(uri, "ask", Json.obj()) + response.statusCode() shouldBe 400 + contentType(response) should include("application/json") + val error = parser.parse(response.body()).toOption.flatMap(_.hcursor.downField("error").focus) + error.flatMap(_.hcursor.get[Int]("code").toOption) shouldBe Some(JSONRPCErrorCodes.MissingRequiredClientCapability.code) + error.flatMap(_.hcursor.downField("data").downField("requiredCapabilities").focus) shouldBe Some(Json.obj("sampling" -> Json.obj())) + + it should "end an event stream which already carries a message with the -32021" in: + withStreamingHttpEndpoint(inputRequiredServer): uri => + val response = callTool(uri, "progress_then_ask", Json.obj()) + response.statusCode() shouldBe 200 + val messages = events(response) + messages.map(_.hcursor.get[String]("method").toOption) shouldBe List(Some("notifications/progress"), None) + messages.lastOption.flatMap(_.hcursor.downField("error").get[Int]("code").toOption) shouldBe + Some(JSONRPCErrorCodes.MissingRequiredClientCapability.code) From 87f0c375b1f3c9abfcf754ba8b83062e72007222 Mon Sep 17 00:00:00 2001 From: Ondra Pelech Date: Thu, 19 Nov 2026 17:51:34 +0100 Subject: [PATCH 17/31] test(T14): cover input-required outcomes over stdio and sync HTTP The stdio servers (sync, Ox, ZIO, Pekko) answer an input-required call, its retry and a -32021; the sync HTTP endpoint sends the -32021 with HTTP 400. --- .../server/ServerStdioTransportTests.scala | 23 +++++++++++++ .../chimp/server/SyncHttpMcpServerSpec.scala | 32 ++++++++++++++++++- 2 files changed, 54 insertions(+), 1 deletion(-) diff --git a/server/src/test/scala/chimp/server/ServerStdioTransportTests.scala b/server/src/test/scala/chimp/server/ServerStdioTransportTests.scala index 1f63c9fb..86e33d02 100644 --- a/server/src/test/scala/chimp/server/ServerStdioTransportTests.scala +++ b/server/src/test/scala/chimp/server/ServerStdioTransportTests.scala @@ -35,6 +35,13 @@ trait ServerStdioTransportTests[F[_]] extends AnyFlatSpec with Matchers: .withLoggingLevel(_ => monad.unit(())) .withPublisher(publisher) .addTool(tool("echo").input[EchoInput].serverLogic[F]((in, _) => monad.unit(ToolResult.text(in.message)))) + .addTool( + tool("ask") + .input[NoInput] + .serverLogicWithContext[F]((_, ctx, _) => + monad.unit(ctx.request.rootsResult("roots").fold(InputRequired("roots" -> InputRequired.listRoots))(_ => ToolResult.text("ok"))) + ) + ) .addStreamingTool( tool("noisy") .input[NoInput] @@ -184,3 +191,19 @@ trait ServerStdioTransportTests[F[_]] extends AnyFlatSpec with Matchers: Await.result(session.served, 10.seconds) session.publisher.openSubscriptions shouldBe 0 } + + private def ask(id: Int, capabilities: String, extra: String = ""): String = + val meta = s"""{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":$capabilities}""" + s"""{"jsonrpc":"2.0","id":$id,"method":"tools/call","params":{"name":"ask","arguments":{}$extra,"_meta":$meta}}""" + + it should "answer an input-required tool call, its retry, and an input request the client has no capability for" in withStdioServer() { + session => + session.send(ask(41, """{"roots":{}}""")) + session.readResponse().hcursor.downField("result").get[String]("resultType") shouldBe Right("input_required") + session.send(ask(42, """{"roots":{}}""", ""","inputResponses":{"roots":{"roots":[]}}""")) + session.readResponse().hcursor.downField("result").downField("content").downN(0).get[String]("text") shouldBe Right("ok") + session.send(ask(43, "{}")) + val error = session.readResponse() + error.hcursor.get[Int]("id") shouldBe Right(43) + error.hcursor.downField("error").get[Int]("code") shouldBe Right(JSONRPCErrorCodes.MissingRequiredClientCapability.code) + } diff --git a/server/src/test/scala/chimp/server/SyncHttpMcpServerSpec.scala b/server/src/test/scala/chimp/server/SyncHttpMcpServerSpec.scala index 8238a81e..255aa239 100644 --- a/server/src/test/scala/chimp/server/SyncHttpMcpServerSpec.scala +++ b/server/src/test/scala/chimp/server/SyncHttpMcpServerSpec.scala @@ -2,11 +2,15 @@ package chimp.server import chimp.client.McpClient import chimp.client.transport.ClientHttpTransport -import chimp.protocol.Implementation +import chimp.protocol.{Implementation, ProtocolMeta} +import io.circe.syntax.* +import io.circe.{parser, Codec, Json} import org.scalatest.Assertion import ox.supervised import sttp.client4.* +import sttp.model.StatusCode import sttp.shared.Identity +import sttp.tapir.Schema import sttp.tapir.server.netty.sync.NettySyncServer import scala.concurrent.Future @@ -26,3 +30,29 @@ class SyncHttpMcpServerSpec extends McpServerTests[Identity] with SyncToFuture: finally transport.close() finally backend.close() finally binding.stop() + + private case class NoInput() derives Codec, Schema + + "Sync HTTP transport" should "answer an input request the client has no capability for with HTTP 400 and -32021" in: + val server = McpServer[Identity]().addTool(tool("ask").input[NoInput].handle(_ => InputRequired("roots" -> InputRequired.listRoots))) + toFuture: + supervised: + val binding = NettySyncServer().port(0).addEndpoint(server.endpoint(List("mcp"))).start() + try + val backend = DefaultSyncBackend() + try + val meta = Json.obj(ProtocolMeta.ProtocolVersionKey -> "2026-07-28".asJson, ProtocolMeta.ClientCapabilities -> Json.obj()) + val params = Json.obj("name" -> "ask".asJson, "arguments" -> Json.obj(), "_meta" -> meta) + val body = Json.obj("jsonrpc" -> "2.0".asJson, "id" -> 1.asJson, "method" -> "tools/call".asJson, "params" -> params) + val response = basicRequest + .post(uri"http://localhost:${binding.port}/mcp") + .headers(Map("Content-Type" -> "application/json", "MCP-Protocol-Version" -> "2026-07-28", "Mcp-Method" -> "tools/call")) + .header("Mcp-Name", "ask") + .body(body.noSpaces) + .send(backend) + response.code shouldBe StatusCode.BadRequest + parser.parse(response.body.fold(identity, identity)).flatMap(_.hcursor.downField("error").get[Int]("code")) shouldBe Right( + -32021 + ) + finally backend.close() + finally binding.stop() From e0cfb444ed8f96f61e45f77917cfcd4bd080f742 Mon Sep 17 00:00:00 2001 From: Ondra Pelech Date: Thu, 19 Nov 2026 17:52:53 +0100 Subject: [PATCH 18/31] feat(T14): add the input-required conformance fixtures The conformance server now offers the MRTR fixture tools (elicitation, sampling, list_roots, multiple_inputs, multi_round, capabilities, test_streaming_elicitation) and the prompt test_input_required_result_prompt. test_missing_capability gets its real behaviour: it asks for sampling, so a client without that capability gets -32021 with HTTP 400. Eleven input-required scenarios and server-stateless leave the 2026-07-28 baseline; request-state and tampered-state stay until the request-state helper lands. --- conformance-baseline-2026-07-28.yml | 15 +-- .../scala/chimp/conformance/server/Main.scala | 109 +++++++++++++++++- 2 files changed, 105 insertions(+), 19 deletions(-) diff --git a/conformance-baseline-2026-07-28.yml b/conformance-baseline-2026-07-28.yml index aabc6c8b..717f710b 100644 --- a/conformance-baseline-2026-07-28.yml +++ b/conformance-baseline-2026-07-28.yml @@ -12,26 +12,13 @@ server: - tasks-request-state-removal - tasks-required-task-error - tasks-wire-fields - # server-to-client input requests during tools/call — T5, https://github.com/softwaremill/chimp/issues/243 - - input-required-result-basic-elicitation - - input-required-result-basic-list-roots - - input-required-result-basic-sampling - - input-required-result-capability-check - - input-required-result-multiple-input-requests - - input-required-result-multi-round - - input-required-result-non-tool-request + # an integrity-protected requestState — T14 request-state helper, https://github.com/softwaremill/chimp/issues/252 - input-required-result-request-state - - input-required-result-result-type - input-required-result-tampered-state - # full stateless lifecycle: only http-server-no-independent-requests-on-stream fails, it needs the - # test_streaming_elicitation tool (multi-round-trip requests) — T14, https://github.com/softwaremill/chimp/issues/252 - - server-stateless # x-mcp-header custom headers in the tool DSL — T13, https://github.com/softwaremill/chimp/issues/251 - http-custom-header-server-validation # the harness records a failure in a non-primary run of these scenarios (the primary run passes) - sep-2164-resource-not-found - - input-required-result-missing-input-response - - input-required-result-ignore-extra-params client: # OAuth client flows — chimp's client has no full OAuth support yet - auth/authorization-server-migration diff --git a/server-conformance/src/main/scala/chimp/conformance/server/Main.scala b/server-conformance/src/main/scala/chimp/conformance/server/Main.scala index 2a74a839..8a7ab7e6 100644 --- a/server-conformance/src/main/scala/chimp/conformance/server/Main.scala +++ b/server-conformance/src/main/scala/chimp/conformance/server/Main.scala @@ -132,11 +132,96 @@ object Main: ctx.log(LoggingLevel.Info, Json.fromString("Tool execution completed")) ToolResult.text("logging complete") + private def stringSchema(property: String): Json = + Json.obj( + "type" -> Json.fromString("object"), + "properties" -> Json.obj(property -> Json.obj("type" -> Json.fromString("string"))), + "required" -> Json.arr(Json.fromString(property)) + ) + + private def answer(ctx: ServerContext[Identity], key: String, property: String): Option[String] = + ctx.request.elicitResult(key).flatMap(_.content).flatMap(_.get(property)).flatMap(_.asString) + + private def samplingText(ctx: ServerContext[Identity], key: String): Option[String] = + ctx.request.samplingResult(key).map(_.content).collect { case ToolContent.Text(_, text, _, _) => text } + + private def sampling(text: String, maxTokens: Int): InputRequest = + InputRequired.sample(CreateMessageParams(List(SamplingMessage(Role.User, ToolContent.Text(text = text))), maxTokens)) + + private val askName = InputRequired.elicitForm("What is your name?", stringSchema("name")) + private val missingCapabilityTool = tool("test_missing_capability") - .description("Needs the sampling client capability") - .withRequiredClientCapabilities(ClientCapabilities(sampling = Some(Json.obj()))) + .description("Asks the client for sampling, so a client without that capability gets -32021") .input[NoInput] - .handle(_ => ToolResult.text("sampling capability declared")) + .serverLogicWithContext[Identity]: (_, ctx, _) => + samplingText(ctx, "sample").fold(InputRequired("sample" -> sampling("Say hello", 10)))(text => ToolResult.text(text)) + + private val elicitationTool = tool("test_input_required_result_elicitation") + .description("Asks for the user's name with a form elicitation, then greets them") + .input[NoInput] + .serverLogicWithContext[Identity]: (_, ctx, _) => + answer(ctx, "user_name", "name").fold(InputRequired("user_name" -> askName))(name => ToolResult.text(s"Hello, $name!")) + + private val samplingTool = tool("test_input_required_result_sampling") + .description("Asks the client's LLM a question, then returns its answer") + .input[NoInput] + .serverLogicWithContext[Identity]: (_, ctx, _) => + samplingText(ctx, "capital_question") + .fold(InputRequired("capital_question" -> sampling("What is the capital of France?", 100)))(text => ToolResult.text(text)) + + private val listRootsTool = tool("test_input_required_result_list_roots") + .description("Asks the client for its roots, then lists them") + .input[NoInput] + .serverLogicWithContext[Identity]: (_, ctx, _) => + ctx.request + .rootsResult("client_roots") + .fold(InputRequired("client_roots" -> InputRequired.listRoots))(result => + ToolResult.text(s"Roots: ${result.roots.map(_.uri).mkString(", ")}") + ) + + private val multipleInputsTool = tool("test_input_required_result_multiple_inputs") + .description("Asks for a form, a sampling and the roots at once") + .input[NoInput] + .serverLogicWithContext[Identity]: (_, ctx, _) => + (answer(ctx, "user_name", "name"), samplingText(ctx, "greeting"), ctx.request.rootsResult("client_roots")) match + case (Some(name), Some(greeting), Some(roots)) => + ToolResult.text(s"$greeting, $name! Roots: ${roots.roots.map(_.uri).mkString(", ")}") + case _ => + InputRequired( + "user_name" -> askName, + "greeting" -> sampling("Generate a greeting", 50), + "client_roots" -> InputRequired.listRoots + ).withRequestState("multiple-inputs") + + private val multiRoundTool = tool("test_input_required_result_multi_round") + .description("Asks for the user's name, then for their favourite colour, in two rounds") + .input[NoInput] + .serverLogicWithContext[Identity]: (_, ctx, _) => + val step1 = InputRequired("step1" -> InputRequired.elicitForm("Step 1: What is your name?", stringSchema("name"))) + val step2 = InputRequired("step2" -> InputRequired.elicitForm("Step 2: What is your favorite color?", stringSchema("color"))) + ctx.request.requestState match + case Some(s"round-2:$name") => + answer(ctx, "step2", "color").fold(step2.withRequestState(s"round-2:$name"))(color => ToolResult.text(s"$name likes $color")) + case Some("round-1") => + answer(ctx, "step1", "name").fold(step1.withRequestState("round-1"))(name => step2.withRequestState(s"round-2:$name")) + case _ => step1.withRequestState("round-1") + + private val capabilitiesTool = tool("test_input_required_result_capabilities") + .description("Asks only for what the client declared: sampling, else a form, else its roots") + .input[NoInput] + .serverLogicWithContext[Identity]: (_, ctx, _) => + val capabilities = ctx.request.clientCapabilities.getOrElse(ClientCapabilities()) + if capabilities.sampling.isDefined then InputRequired("question" -> sampling("Say hello", 10)) + else if capabilities.elicitation.isDefined then InputRequired("user_name" -> askName) + else if capabilities.roots.isDefined then InputRequired("client_roots" -> InputRequired.listRoots) + else ToolResult.text("The client declared no capability to ask with") + + private val streamingElicitationTool = tool("test_streaming_elicitation") + .description("Reports progress on the response stream, then asks for the user's name") + .input[NoInput] + .streamingServerLogic[Identity]: (_, ctx, _) => + ctx.reportProgress(50.0, Some(100.0)) + answer(ctx, "user_name", "name").fold(InputRequired("user_name" -> askName))(name => ToolResult.text(s"Hello, $name!")) private val perRequestLoggingTool = tool("test_logging_tool") .description("Emits a log notification at each level; a modern request gets only those at or above its _meta logLevel") @@ -208,6 +293,13 @@ object Main: ) ) + private val inputRequiredPrompt = prompt("test_input_required_result_prompt") + .description("Asks for the context to use before it builds the prompt") + .serverLogicWithContext[Identity]: (_, ctx, _) => + answer(ctx, "user_context", "context").fold( + InputRequired("user_context" -> InputRequired.elicitForm("What context should the prompt use?", stringSchema("context"))) + )(context => GetPromptResult(messages = List(PromptMessage(Role.User, ToolContent.Text(text = s"Use this context: $context"))))) + private val imagePrompt = prompt("test_prompt_with_image") .description("A prompt with an image") .handle(_ => GetPromptResult(messages = List(PromptMessage(Role.User, ToolContent.Image(data = pngData, mimeType = "image/png"))))) @@ -223,18 +315,25 @@ object Main: embeddedResourceTool, jsonSchemaTool, missingCapabilityTool, + elicitationTool, + samplingTool, + listRootsTool, + multipleInputsTool, + multiRoundTool, + capabilitiesTool, triggerToolChange, triggerPromptChange ) .addResources(staticText, staticBinary) .addResourceTemplate(dataTemplate) - .addPrompts(simplePrompt, argsPrompt, embeddedResourcePrompt, imagePrompt) + .addPrompts(simplePrompt, argsPrompt, embeddedResourcePrompt, imagePrompt, inputRequiredPrompt) .withCompletion((_, _, _) => Completion(values = List("alpha", "beta"))) .withLoggingLevel(_ => ()) .withSubscriptions(ResourceSubscriptions[Identity](_ => (), _ => ())) .withPublisher(publisher) - private val streamingServer = server.streaming.addStreamingTools(progressTool, loggingTool, perRequestLoggingTool) + private val streamingServer = + server.streaming.addStreamingTools(progressTool, loggingTool, perRequestLoggingTool, streamingElicitationTool) def main(args: Array[String]): Unit = val requestedPort = args From 4ad32691135a698f6afc5866212b9134cc0adeba Mon Sep 17 00:00:00 2001 From: Ondra Pelech Date: Thu, 19 Nov 2026 17:53:46 +0100 Subject: [PATCH 19/31] docs(T14): document asking the client for input A new page explains how a handler asks for input with InputRequired, reads the answers and the request state on the retry, asks again for a missing answer, chooses by client capabilities, and which rules chimp enforces. The tools, prompts, resources and capabilities pages point to it. --- docs/index.md | 1 + docs/server/capabilities.md | 1 + docs/server/mrtr.md | 70 +++++++++++++++++++++++++++++++++++++ docs/server/prompts.md | 2 ++ docs/server/resources.md | 2 ++ docs/server/tools.md | 2 ++ 6 files changed, 78 insertions(+) create mode 100644 docs/server/mrtr.md diff --git a/docs/index.md b/docs/index.md index 15040596..85f1ecee 100644 --- a/docs/index.md +++ b/docs/index.md @@ -15,6 +15,7 @@ and [sttp](https://github.com/softwaremill/sttp), supporting the variety of the server/prompts server/resources server/capabilities + server/mrtr server/examples .. toctree:: diff --git a/docs/server/capabilities.md b/docs/server/capabilities.md index bddadd8d..ec6df093 100644 --- a/docs/server/capabilities.md +++ b/docs/server/capabilities.md @@ -58,6 +58,7 @@ Each handler can read the facts of its request from `ctx.request`, a `RequestInf - `clientCapabilities` and `clientInfo` — what the client declares in `_meta`. - `logLevel` — the per-request log level from `_meta`. - `progressToken` — the progress token from `_meta`. +- `inputResponses` and `requestState` — on the retry of an input-required outcome, the answers of the client and the echoed state (see [asking the client for input](mrtr.md)). A modern request carries all of these in `_meta`. The server keeps no state between requests, so a legacy request gives only the protocol version (from the `MCP-Protocol-Version` header or `_meta`) and the progress token. The other facts are `None`. diff --git a/docs/server/mrtr.md b/docs/server/mrtr.md new file mode 100644 index 00000000..e22187fd --- /dev/null +++ b/docs/server/mrtr.md @@ -0,0 +1,70 @@ +# Asking the client for input + +In protocol version `2026-07-28`, a server does not send requests to the client while it handles a request. Instead, a handler can end a `tools/call`, `prompts/get` or `resources/read` with an **input-required** outcome. The client gets the input that the handler asks for, and then sends the same request again with the answers. The server keeps no state between the two requests. This is the [multi round-trip requests](https://modelcontextprotocol.io/specification/2026-07-28/basic/patterns/mrtr) (MRTR) pattern. + +## Requesting input + +A tool, prompt or resource handler returns `InputRequired` instead of its result. `InputRequired` names each input request with a key that the handler chooses: + +| Input request | What the client does | Client capability that it needs | +|---|---|---| +| `InputRequired.elicitForm(message, schema)` | asks the user to fill in a form | `elicitation` (form mode) | +| `InputRequired.elicitUrl(message, url)` | asks the user to open a URL | `elicitation.url` | +| `InputRequired.sample(params)` | samples its LLM | `sampling` | +| `InputRequired.listRoots` | sends its roots | `roots` | + +On the retry, the handler reads the answers under the same keys from `ctx.request`: `elicitResult(key)`, `samplingResult(key)` and `rootsResult(key)`. A handler that never returns `InputRequired` works as before. + +```scala mdoc:compile-only +import chimp.server.* +import io.circe.{Codec, Json} +import sttp.shared.Identity +import sttp.tapir.* + +case class NoInput() derives Codec, Schema + +val nameSchema = Json.obj( + "type" -> Json.fromString("object"), + "properties" -> Json.obj("name" -> Json.obj("type" -> Json.fromString("string"))) +) + +val greet = tool("greet") + .input[NoInput] + .serverLogicWithContext[Identity]: (_, ctx, _) => + ctx.request.elicitResult("user_name").flatMap(_.content).flatMap(_.get("name")).flatMap(_.asString) match + case Some(name) => ToolResult.text(s"Hello, $name!") + case None => InputRequired("user_name" -> InputRequired.elicitForm("What is your name?", nameSchema)) +``` + +Prompts and resources use the same `InputRequired` from their `serverLogicWithContext`. + +### Several rounds and the request state + +A handler can ask again on the retry, as many times as it needs. To remember what happened in the earlier rounds, it attaches a **request state** with `.withRequestState(state)`. The client sends the state back without a change on its retry, and the handler reads it from `ctx.request.requestState`. `InputRequired.withRequestState(state)` makes an outcome that has a state and no input requests: the client then retries at once. + +```{warning} +The request state goes through the client, so treat it as input from an attacker. If the state controls authorization, resource access or business logic, protect its integrity, and reject a state that you cannot verify. +``` + +### Missing answers + +If the retry does not have an answer that the handler needs, return a new `InputRequired` that asks for it again. Do not fail the request. The client can omit an answer, or send it under a different key. Keys that the handler did not ask for are ignored. + +### Client capabilities + +A handler can read `ctx.request.clientCapabilities` and ask only for what the client supports. For example, it can ask for sampling when the client declares `sampling`, and for a form if not. + +## Rules that chimp enforces + +chimp applies these rules, so a handler does not have to: + +| Problem | Result | +|---|---| +| an input request that needs a capability which the client did not declare | `-32021` MissingRequiredClientCapability with `data.requiredCapabilities`, HTTP `400` | +| `inputResponses` is not an object, or one of its values is not a sampling, roots or elicitation result | `-32602` InvalidParams, HTTP `400`; the handler does not run | +| `requestState` is not a string | `-32602` InvalidParams, HTTP `400`; the handler does not run | +| `InputRequired` on a legacy (`2025-11-25` or earlier) request | `-32603` InternalError which names protocol version `2026-07-28` | + +An `InputRequired` always has at least one input request or a request state. Only `tools/call`, `prompts/get` and `resources/read` can end with it. + +On a streaming HTTP server, chimp opens the event stream when the handler sends its first message. If the handler ends with the `-32021` before it sends a message, chimp sends a plain JSON error with HTTP `400`. If the handler already sent a message, for example a progress notification, the `-32021` is the last message on the event stream. diff --git a/docs/server/prompts.md b/docs/server/prompts.md index 0e818c17..a8ba0a90 100644 --- a/docs/server/prompts.md +++ b/docs/server/prompts.md @@ -24,3 +24,5 @@ val endpoint = McpServer(prompts = List(greeting)).endpoint(List("mcp")) ``` Prompt messages reuse the `ToolContent` content types, so they can embed images (`ToolContent.Image`) and resources (`ToolContent.ResourceContent`) just like tool results. + +A prompt can also ask the client for input before it returns its messages: see [asking the client for input](mrtr.md). diff --git a/docs/server/resources.md b/docs/server/resources.md index 6a6239c4..41ba8783 100644 --- a/docs/server/resources.md +++ b/docs/server/resources.md @@ -27,3 +27,5 @@ val endpoint = McpServer(resources = List(readme), resourceTemplates = List(item ``` Returning `Left(ResourceError(...))` (or reading an unknown URI) responds with a JSON-RPC error carrying the offending `uri`. + +A resource can also ask the client for input before it returns its contents: see [asking the client for input](mrtr.md). diff --git a/docs/server/tools.md b/docs/server/tools.md index 656d7dcd..e1e69e5e 100644 --- a/docs/server/tools.md +++ b/docs/server/tools.md @@ -53,3 +53,5 @@ val adder = tool("adder") The output type carries into the logic, which returns a `ToolResult[SumOutput]`; `ToolResult.error` is accepted whatever the output type. A result with structured output but no content is also sent as serialized JSON text, as the spec recommends. + +A tool can also ask the client for input before it returns its result: see [asking the client for input](mrtr.md). From 2480074dc8ff8ff854ca8a3d9176c9859e945fe8 Mon Sep 17 00:00:00 2001 From: Ondra Pelech Date: Thu, 19 Nov 2026 18:07:15 +0100 Subject: [PATCH 20/31] feat(T14): sign and verify the request state with an HMAC-SHA256 signer A server configured with withRequestStateSigner signs the request state of each InputRequired outcome with HMAC-SHA256 under the owner's secret, together with an expiry and the identity of the request (method, tool or prompt name or resource URI, a digest of the arguments, and on a secured server the principal). On the retry the server verifies the state with a constant-time comparison before the handler runs, and the handler sees the original state. A changed, expired or foreign state fails with -32602 and HTTP 400, and the handler does not run. --- .../scala/chimp/server/InputRequired.scala | 2 + .../main/scala/chimp/server/McpHandler.scala | 113 +++++++++++------- .../main/scala/chimp/server/McpServer.scala | 48 +++++++- .../chimp/server/RequestStateSigner.scala | 69 +++++++++++ .../server/McpHandlerRequestStateSpec.scala | 109 +++++++++++++++++ 5 files changed, 296 insertions(+), 45 deletions(-) create mode 100644 server/src/main/scala/chimp/server/RequestStateSigner.scala create mode 100644 server/src/test/scala/chimp/server/McpHandlerRequestStateSpec.scala diff --git a/server/src/main/scala/chimp/server/InputRequired.scala b/server/src/main/scala/chimp/server/InputRequired.scala index 639ac43d..d5b0c9f6 100644 --- a/server/src/main/scala/chimp/server/InputRequired.scala +++ b/server/src/main/scala/chimp/server/InputRequired.scala @@ -15,6 +15,8 @@ final case class InputRequired private (requests: Map[String, InputRequest], req /** Sets the opaque state which the client echoes on its retry. */ def withRequestState(state: String): InputRequired = copy(requestState = Some(state)) + private[server] def mapRequestState(f: String => String): InputRequired = copy(requestState = requestState.map(f)) + object InputRequired: def apply(first: (String, InputRequest), rest: (String, InputRequest)*): InputRequired = new InputRequired((first +: rest).toMap, None) diff --git a/server/src/main/scala/chimp/server/McpHandler.scala b/server/src/main/scala/chimp/server/McpHandler.scala index 2e1ebbd1..1b9a4902 100644 --- a/server/src/main/scala/chimp/server/McpHandler.scala +++ b/server/src/main/scala/chimp/server/McpHandler.scala @@ -88,7 +88,7 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD case None => val isModern = isModernRequest(params, headers) val info = requestInfo(params, headers, isModern) - dispatch(method, params, id, headers, () => makeContext(info), isModern) + dispatch(method, params, id, headers, info, makeContext, isModern) case Right(notification: JSONRPCMessage.Notification) => logger.debug(s"Received notification: ${notification.method}") McpResponse.EmptyAcceptResponse.unit @@ -101,7 +101,8 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD params: Option[Json], id: RequestId, headers: Seq[Header], - makeContext: () => C, + info: RequestInfo, + makeContext: RequestInfo => C, isModern: Boolean )(using MonadError[F]): F[McpResponse] = def wrap(cacheHints: Option[CacheHints])(message: JSONRPCMessage): JSONRPCMessage = message match @@ -121,7 +122,7 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD case "tools/list" => jsonResponse(wrap(cacheHints)(JSONRPCMessage.Response(id = id, result = ListToolsResponse(toolDefinitions).asJson))).unit case "tools/call" => - handleToolsCall(params, id, headers, makeContext, isModern).map(reply(None)) + handleToolsCall(params, id, headers, info, makeContext, isModern).map(reply(None)) case "resources/list" if hasResources => jsonResponse( wrap(cacheHints)(JSONRPCMessage.Response(id = id, result = ListResourcesResult(server.resources.map(_.definition)).asJson)) @@ -133,7 +134,7 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD ) ).unit case "resources/read" if hasResources => - handleResourcesRead(params, id, headers, makeContext, isModern).map(reply(cacheHints)) + handleResourcesRead(params, id, headers, info, makeContext, isModern).map(reply(cacheHints)) case "resources/subscribe" if server.subscriptions.isDefined => handleSubscribe(params, id, subscribe = true).map(jsonResponse) case "resources/unsubscribe" if server.subscriptions.isDefined => @@ -143,7 +144,7 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD wrap(cacheHints)(JSONRPCMessage.Response(id = id, result = ListPromptsResult(server.prompts.map(_.definition)).asJson)) ).unit case "prompts/get" if hasPrompts => - handlePromptsGet(params, id, headers, makeContext, isModern).map(reply(None)) + handlePromptsGet(params, id, headers, info, makeContext, isModern).map(reply(None)) case "completion/complete" if server.completion.isDefined => handleComplete(params, id).map(wrap(None)).map(jsonResponse) case "logging/setLevel" if server.loggingLevel.isDefined => @@ -418,9 +419,14 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD private def handleDiscover(id: RequestId): JSONRPCMessage.Response = JSONRPCMessage.Response(id = id, result = discoverResult.asJson) - private def handleToolsCall(params: Option[Json], id: RequestId, headers: Seq[Header], makeContext: () => C, isModern: Boolean)(using - MonadError[F] - ): F[Reply] = + private def handleToolsCall( + params: Option[Json], + id: RequestId, + headers: Seq[Header], + info: RequestInfo, + makeContext: RequestInfo => C, + isModern: Boolean + )(using MonadError[F]): F[Reply] = val name = params.flatMap(_.hcursor.downField("name").as[String].toOption) val arguments = params.flatMap(_.hcursor.downField("arguments").focus).getOrElse(Json.obj()) name match @@ -429,12 +435,12 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD case Some(tool) => tool.inputDecoder.decodeJson(arguments) match case Right(input) => - val context = makeContext() - tool - .logic(input, context, headers) - .map: - case outcome: InputRequired => inputRequiredReply(id, outcome, context.request, isModern) - case result: ToolResult[?] => Right(toolCallResponse(id, result)) + withContext(id, "tools/call", name, arguments, info, makeContext): (context, sign) => + tool + .logic(input, context, headers) + .map: + case outcome: InputRequired => inputRequiredReply(id, sign(outcome), context.request, isModern) + case result: ToolResult[?] => Right(toolCallResponse(id, result)) case Left(decodingError) => val snippet = arguments.noSpaces.take(200) failed( @@ -450,6 +456,28 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD private def failed(error: JSONRPCMessage)(using MonadError[F]): F[Reply] = (Right(error): Reply).unit + /** Runs `run` with the handler's context, and with how to sign the request state of its outcome. With a [[RequestStateSigner]], the + * request state of a retry is verified first, and the handler sees the original state; a state which fails verification is a `-32602` + * with HTTP 400, and the handler does not run. + */ + private def withContext(id: RequestId, method: String, target: String, arguments: Json, info: RequestInfo, makeContext: RequestInfo => C)( + run: (C, InputRequired => InputRequired) => F[Reply] + )(using MonadError[F]): F[Reply] = + server.requestStateSigner match + case None => run(makeContext(info), identity) + case Some(signer) => + val context = makeContext(info) + val owner = server.requestStateOwner(context) + val request = Json.arr(method.asJson, target.asJson, RequestStateSigner.digest(arguments).asJson, owner.asJson) + val sign: InputRequired => InputRequired = _.mapRequestState(signer.sign(_, request)) + info.requestState.map(signer.verify(_, request)) match + case None => run(context, sign) + case Some(Right(state)) => run(makeContext(info.copy(requestState = Some(state))), sign) + case Some(Left(problem)) => + (Left( + jsonError(id, StatusCode.BadRequest, JSONRPCErrorCodes.InvalidParams.code, s"Invalid requestState: $problem") + ): Reply).unit + private def toolCallResponse(id: RequestId, result: ToolResult[?]): JSONRPCMessage = // for backwards compatibility, structured output is serialized into a text block, unless the tool returned content of its own val content = result.structuredContent match @@ -468,28 +496,29 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD params: Option[Json], id: RequestId, headers: Seq[Header], - makeContext: () => C, + info: RequestInfo, + makeContext: RequestInfo => C, isModern: Boolean )(using MonadError[F]): F[Reply] = decodeReplyParams[ReadResourceParams](params, id): params => - val context = makeContext() - val respond = resourceReadReply(id, params.uri, context.request, isModern) - resourcesByUri.get(params.uri) match - case Some(resource) => resource.read(context, headers).map(respond) - case None => - server.resourceTemplates.iterator - .map(template => (template, template.matcher.matchUri(params.uri))) - .collectFirst { case (template, Some(vars)) => template.read(vars, params.uri, context, headers) } match - case Some(result) => result.map(respond) - case None => - failed( - protocolError( - id, - JSONRPCErrorCodes.ResourceNotFound.code, - s"Resource not found: ${params.uri}", - Some(Json.obj("uri" -> Json.fromString(params.uri))) + withContext(id, "resources/read", params.uri, Json.obj(), info, makeContext): (context, sign) => + val respond = resourceReadReply(id, params.uri, context.request, isModern, sign) + resourcesByUri.get(params.uri) match + case Some(resource) => resource.read(context, headers).map(respond) + case None => + server.resourceTemplates.iterator + .map(template => (template, template.matcher.matchUri(params.uri))) + .collectFirst { case (template, Some(vars)) => template.read(vars, params.uri, context, headers) } match + case Some(result) => result.map(respond) + case None => + failed( + protocolError( + id, + JSONRPCErrorCodes.ResourceNotFound.code, + s"Resource not found: ${params.uri}", + Some(Json.obj("uri" -> Json.fromString(params.uri))) + ) ) - ) private def decodeReplyParams[P: Decoder](params: Option[Json], id: RequestId)(f: P => F[Reply])(using MonadError[F]): F[Reply] = params.flatMap(_.as[P].toOption) match @@ -503,11 +532,11 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD case Some(params) => f(params) case None => protocolError(id, JSONRPCErrorCodes.InvalidParams.code, "Invalid or missing params").unit - private def resourceReadReply(id: RequestId, uri: String, info: RequestInfo, isModern: Boolean)( + private def resourceReadReply(id: RequestId, uri: String, info: RequestInfo, isModern: Boolean, sign: InputRequired => InputRequired)( outcome: Either[ResourceError, List[ResourceContents]] | InputRequired ): Reply = outcome match - case required: InputRequired => inputRequiredReply(id, required, info, isModern) + case required: InputRequired => inputRequiredReply(id, sign(required), info, isModern) case Right(contents) => Right(JSONRPCMessage.Response(id = id, result = ReadResourceResult(contents).asJson)) case Left(error) => Right( @@ -530,18 +559,20 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD params: Option[Json], id: RequestId, headers: Seq[Header], - makeContext: () => C, + info: RequestInfo, + makeContext: RequestInfo => C, isModern: Boolean )(using MonadError[F]): F[Reply] = decodeReplyParams[GetPromptParams](params, id): params => promptsByName.get(params.name) match case Some(prompt) => - val context = makeContext() - prompt - .logic(params.arguments.getOrElse(Map.empty), context, headers) - .map: - case outcome: InputRequired => inputRequiredReply(id, outcome, context.request, isModern) - case result: GetPromptResult => Right(JSONRPCMessage.Response(id = id, result = result.asJson)) + val arguments = params.arguments.getOrElse(Map.empty) + withContext(id, "prompts/get", params.name, arguments.asJson, info, makeContext): (context, sign) => + prompt + .logic(arguments, context, headers) + .map: + case outcome: InputRequired => inputRequiredReply(id, sign(outcome), context.request, isModern) + case result: GetPromptResult => Right(JSONRPCMessage.Response(id = id, result = result.asJson)) case None => failed(protocolError(id, JSONRPCErrorCodes.InvalidParams.code, s"Unknown prompt: ${params.name}")) private def handleComplete(params: Option[Json], id: RequestId)(using MonadError[F]): F[JSONRPCMessage] = diff --git a/server/src/main/scala/chimp/server/McpServer.scala b/server/src/main/scala/chimp/server/McpServer.scala index 71e753fe..c09f58d4 100644 --- a/server/src/main/scala/chimp/server/McpServer.scala +++ b/server/src/main/scala/chimp/server/McpServer.scala @@ -32,6 +32,10 @@ sealed trait McpServerDef[F[_], C <: ServerContext[F]]: def loggingLevel: Option[SetLoggingLevelHandler[F]] def subscriptions: Option[ResourceSubscriptions[F]] def publisher: Option[NotificationPublisher] + def requestStateSigner: Option[RequestStateSigner] + + /** Who a request state belongs to, besides its request: the principal on a secured server. */ + private[server] def requestStateOwner(context: C): Option[String] = None case class McpServer[F[_]]( name: String = "Chimp MCP server", @@ -46,7 +50,8 @@ case class McpServer[F[_]]( completion: Option[CompletionHandler[F]] = None, loggingLevel: Option[SetLoggingLevelHandler[F]] = None, subscriptions: Option[ResourceSubscriptions[F]] = None, - publisher: Option[NotificationPublisher] = None + publisher: Option[NotificationPublisher] = None, + requestStateSigner: Option[RequestStateSigner] = None ) extends McpServerDef[F, ServerContext[F]]: def name(value: String): McpServer[F] = copy(name = value) @@ -102,6 +107,12 @@ case class McpServer[F[_]]( def withPublisher(publisher: NotificationPublisher): McpServer[F] = copy(publisher = Some(publisher)) + /** Signs the request state of each [[InputRequired]] outcome, and verifies it on the retry before the handler runs; see + * [[RequestStateSigner]]. + */ + def withRequestStateSigner(signer: RequestStateSigner): McpServer[F] = + copy(requestStateSigner = Some(signer)) + def endpoint(path: List[String]): ServerEndpoint[Any, F] = ServerHttpTransport(path).serve(this) /** Adds the security input, the error output which describes a rejection, and the logic which validates the security input and makes the @@ -132,7 +143,8 @@ case class McpServer[F[_]]( completion, loggingLevel, subscriptions, - publisher + publisher, + requestStateSigner ) case class StreamingMcpServer[F[_]]( @@ -148,7 +160,8 @@ case class StreamingMcpServer[F[_]]( completion: Option[CompletionHandler[F]] = None, loggingLevel: Option[SetLoggingLevelHandler[F]] = None, subscriptions: Option[ResourceSubscriptions[F]] = None, - publisher: Option[NotificationPublisher] = None + publisher: Option[NotificationPublisher] = None, + requestStateSigner: Option[RequestStateSigner] = None ) extends McpServerDef[F, StreamingServerContext[F]]: def name(value: String): StreamingMcpServer[F] = copy(name = value) @@ -210,6 +223,12 @@ case class StreamingMcpServer[F[_]]( def withPublisher(publisher: NotificationPublisher): StreamingMcpServer[F] = copy(publisher = Some(publisher)) + /** Signs the request state of each [[InputRequired]] outcome, and verifies it on the retry before the handler runs; see + * [[RequestStateSigner]]. + */ + def withRequestStateSigner(signer: RequestStateSigner): StreamingMcpServer[F] = + copy(requestStateSigner = Some(signer)) + /** An [[McpServer]] with security logic, which runs before the server handles an MCP message. The result of the security logic, the * principal, is given to the logic of the tools, prompts, and resources which are added to this server. Tools, prompts, and resources of * the initial server, which do not need the principal, are kept. @@ -229,7 +248,8 @@ case class SecuredMcpServer[F[_], S, E, P]( securedTools: List[ServerTool[?, ?, F, SecuredServerContext[F, P]]] = Nil, securedPrompts: List[ServerPrompt[F, SecuredServerContext[F, P]]] = Nil, securedResources: List[ServerResource[F, SecuredServerContext[F, P]]] = Nil, - securedResourceTemplates: List[ServerResourceTemplate[F, SecuredServerContext[F, P]]] = Nil + securedResourceTemplates: List[ServerResourceTemplate[F, SecuredServerContext[F, P]]] = Nil, + requestStatePrincipal: Option[P => String] = None ) extends McpServerDef[F, SecuredServerContext[F, P]]: def name: String = server.name def version: String = server.version @@ -240,6 +260,10 @@ case class SecuredMcpServer[F[_], S, E, P]( def loggingLevel: Option[SetLoggingLevelHandler[F]] = server.loggingLevel def subscriptions: Option[ResourceSubscriptions[F]] = server.subscriptions def publisher: Option[NotificationPublisher] = server.publisher + def requestStateSigner: Option[RequestStateSigner] = server.requestStateSigner + + private[server] override def requestStateOwner(context: SecuredServerContext[F, P]): Option[String] = + requestStatePrincipal.map(_(context.principal)) def tools: List[ServerTool[?, ?, F, SecuredServerContext[F, P]]] = mergeBy(server.tools, securedTools)(_.name) @@ -311,6 +335,12 @@ case class SecuredMcpServer[F[_], S, E, P]( def withPublisher(publisher: NotificationPublisher): SecuredMcpServer[F, S, E, P] = copy(server = server.withPublisher(publisher)) + /** Signs the request state of each [[InputRequired]] outcome, and verifies it on the retry before the handler runs; see + * [[RequestStateSigner]]. A state also belongs to the principal which `principalId` identifies, and fails for any other principal. + */ + def withRequestStateSigner(signer: RequestStateSigner, principalId: P => String): SecuredMcpServer[F, S, E, P] = + copy(server = server.withRequestStateSigner(signer), requestStatePrincipal = Some(principalId)) + def endpoint(path: List[String]): ServerEndpoint[Any, F] = SecuredServerHttpTransport[F, S, E, P](path).serve(this) def streaming: SecuredStreamingMcpServer[F, S, E, P] = SecuredStreamingMcpServer(this) @@ -334,6 +364,10 @@ case class SecuredStreamingMcpServer[F[_], S, E, P]( def loggingLevel: Option[SetLoggingLevelHandler[F]] = server.loggingLevel def subscriptions: Option[ResourceSubscriptions[F]] = server.subscriptions def publisher: Option[NotificationPublisher] = server.publisher + def requestStateSigner: Option[RequestStateSigner] = server.requestStateSigner + + private[server] override def requestStateOwner(context: SecuredStreamingServerContext[F, P]): Option[String] = + server.requestStateOwner(context) def securityInput: EndpointInput[S] = server.securityInput def errorOutput: EndpointOutput[E] = server.errorOutput @@ -405,3 +439,9 @@ case class SecuredStreamingMcpServer[F[_], S, E, P]( */ def withPublisher(publisher: NotificationPublisher): SecuredStreamingMcpServer[F, S, E, P] = copy(server = server.withPublisher(publisher)) + + /** Signs the request state of each [[InputRequired]] outcome, and verifies it on the retry before the handler runs; see + * [[RequestStateSigner]]. A state also belongs to the principal which `principalId` identifies, and fails for any other principal. + */ + def withRequestStateSigner(signer: RequestStateSigner, principalId: P => String): SecuredStreamingMcpServer[F, S, E, P] = + copy(server = server.withRequestStateSigner(signer, principalId)) diff --git a/server/src/main/scala/chimp/server/RequestStateSigner.scala b/server/src/main/scala/chimp/server/RequestStateSigner.scala new file mode 100644 index 00000000..597a7a0f --- /dev/null +++ b/server/src/main/scala/chimp/server/RequestStateSigner.scala @@ -0,0 +1,69 @@ +package chimp.server + +import io.circe.syntax.* +import io.circe.{parser, Json} + +import java.nio.charset.StandardCharsets.UTF_8 +import java.security.MessageDigest +import java.time.Clock +import java.util.Base64 +import javax.crypto.Mac +import javax.crypto.spec.SecretKeySpec +import scala.concurrent.duration.* +import scala.util.Try + +/** Protects the integrity of the request state of [[InputRequired]] outcomes. A server with a signer signs each request state with + * HMAC-SHA256, together with an expiry and the identity of the request (its method, its tool or prompt name or resource URI, a digest of + * its arguments, and on a secured server the principal). On a retry, the server verifies the state before the handler runs, and gives the + * handler the original state. A state which was changed, has expired, or belongs to another request or principal fails with `-32602`. + * + * The client can read the state, so do not put secrets in it. Within its lifetime, a state can be used again on the same request. + */ +final class RequestStateSigner private (secret: Array[Byte], ttl: FiniteDuration, clock: Clock): + private val encoder = Base64.getUrlEncoder.withoutPadding() + private val decoder = Base64.getUrlDecoder + + private def mac(data: String): Array[Byte] = + val hmac = Mac.getInstance("HmacSHA256") + hmac.init(SecretKeySpec(secret, "HmacSHA256")) + hmac.doFinal(data.getBytes(UTF_8)) + + private[server] def sign(state: String, request: Json): String = + val expiresAt = clock.millis() + ttl.toMillis + val body = + encoder.encodeToString(Json.obj("state" -> state.asJson, "exp" -> expiresAt.asJson, "req" -> request).noSpaces.getBytes(UTF_8)) + s"$body.${encoder.encodeToString(mac(body))}" + + /** The original state, or why `signed` fails verification for `request`. */ + private[server] def verify(signed: String, request: Json): Either[String, String] = + signed.split('.') match + case Array(body, signature) if Try(decoder.decode(signature)).toOption.exists(MessageDigest.isEqual(_, mac(body))) => + val payload = Try(String(decoder.decode(body), UTF_8)).toOption.flatMap(parser.parse(_).toOption).map(_.hcursor) + val fields = + for + c <- payload + state <- c.get[String]("state").toOption + expiresAt <- c.get[Long]("exp").toOption + issuedFor <- c.get[Json]("req").toOption + yield (state, expiresAt, issuedFor) + fields match + case Some((_, expiresAt, _)) if expiresAt <= clock.millis() => Left("the request state has expired") + case Some((_, _, issuedFor)) if issuedFor != request => Left("the request state belongs to another request") + case Some((state, _, _)) => Right(state) + case None => Left("the request state is malformed") + case _ => Left("the request state failed the integrity check") + +object RequestStateSigner: + /** @param secret + * The HMAC key, at least 32 bytes. Keep it secret, and use the same one on all instances of the server. + * @param ttl + * How long a request state stays valid. + */ + def apply(secret: Array[Byte], ttl: FiniteDuration = 10.minutes, clock: Clock = Clock.systemUTC()): RequestStateSigner = + require(secret.length >= 32, s"The request state secret must have at least 32 bytes, got ${secret.length}") + new RequestStateSigner(secret.clone(), ttl, clock) + + /** A digest of a request's salient parameters, so a state can be bound to them without carrying them. */ + private[server] def digest(json: Json): String = + val bytes = json.printWith(io.circe.Printer.noSpacesSortKeys).getBytes(UTF_8) + Base64.getUrlEncoder.withoutPadding().encodeToString(MessageDigest.getInstance("SHA-256").digest(bytes)) diff --git a/server/src/test/scala/chimp/server/McpHandlerRequestStateSpec.scala b/server/src/test/scala/chimp/server/McpHandlerRequestStateSpec.scala new file mode 100644 index 00000000..e1643eb6 --- /dev/null +++ b/server/src/test/scala/chimp/server/McpHandlerRequestStateSpec.scala @@ -0,0 +1,109 @@ +package chimp.server + +import chimp.protocol.* +import io.circe.* +import io.circe.syntax.* +import org.scalatest.flatspec.AnyFlatSpec +import org.scalatest.matchers.should.Matchers +import sttp.model.StatusCode +import sttp.monad.{IdentityMonad, MonadError} +import sttp.shared.Identity +import sttp.tapir.Schema + +import java.time.{Clock, Instant, ZoneId, ZoneOffset} +import java.util.concurrent.atomic.{AtomicInteger, AtomicLong} +import scala.concurrent.duration.* + +class McpHandlerRequestStateSpec extends AnyFlatSpec with Matchers: + import JSONRPCMessage.* + + given MonadError[Identity] = IdentityMonad + + case class CountInput(count: Int) derives Codec, Schema + + private final class SettableClock(millis: AtomicLong) extends Clock: + def getZone: ZoneId = ZoneOffset.UTC + override def withZone(zone: ZoneId): Clock = this + def instant(): Instant = Instant.ofEpochMilli(millis.get()) + + private val now = AtomicLong(1_000_000L) + private val signer = RequestStateSigner(Array.fill[Byte](32)(7), ttl = 1.minute, clock = SettableClock(now)) + private val runs = AtomicInteger(0) + + private def stateful(name: String) = tool(name) + .input[CountInput] + .serverLogicWithContext[Identity]: (in, ctx, _) => + runs.incrementAndGet() + ctx.request.requestState match + case Some(state) => ToolResult.text(s"state $state") + case None => InputRequired.withRequestState(s"count=${in.count}") + + private val handler = McpHandler(McpServer[Identity]().addTools(stateful("a"), stateful("b")).withRequestStateSigner(signer)) + + private val securedHandler = + val secured = McpServer[Identity]() + .serverSecurityLogicPure[Unit, Unit, String](sttp.tapir.emptyInput, sttp.tapir.emptyOutput)(_ => Right("ignored")) + .addTool(stateful("a")) + .withRequestStateSigner(signer, principal => principal) + McpHandler[Identity, SecuredServerContext[Identity, String]](secured) + + private def request(tool: String, count: Int, state: Option[String]): Json = + val meta = Json.obj(ProtocolMeta.ProtocolVersionKey -> "2026-07-28".asJson, ProtocolMeta.ClientCapabilities -> Json.obj()) + val params = Json.obj("name" -> tool.asJson, "arguments" -> Json.obj("count" -> count.asJson), "_meta" -> meta) + val message: JSONRPCMessage = + Request( + method = "tools/call", + params = Some(params.deepMerge(Json.obj("requestState" -> state.asJson)).dropNullValues), + id = RequestId("r") + ) + message.asJson + + private def call(tool: String, count: Int = 1, state: Option[String] = None): McpResponse = + handler.handleJsonRpc(request(tool, count, state), Seq.empty) + + private def callAs(principal: String, state: Option[String] = None): McpResponse = + securedHandler.handleJsonRpc(request("a", 1, state), Seq.empty, info => SecuredServerContext[Identity, String](principal, info)) + + private def result(response: McpResponse): Json = + response.body.flatMap(_.hcursor.downField("result").focus).getOrElse(fail(s"Expected a result, got ${response.body}")) + + private def stateOf(response: McpResponse): String = result(response).hcursor.get[String]("requestState").getOrElse(fail("No state")) + + private def textOf(response: McpResponse): Option[String] = + result(response).hcursor.downField("content").downArray.get[String]("text").toOption + + private def shouldBeRejected(call: => McpResponse): org.scalatest.Assertion = + val runsBefore = runs.get() + val response = call + response.statusCode shouldBe StatusCode.BadRequest + response.body.flatMap(_.hcursor.downField("error").get[Int]("code").toOption) shouldBe Some(JSONRPCErrorCodes.InvalidParams.code) + runs.get() shouldBe runsBefore + + "A request state signer" should "sign the state and give the handler the original state on the retry" in: + val signed = stateOf(call("a", count = 3)) + signed should not include "count=3" + textOf(call("a", count = 3, state = Some(signed))) shouldBe Some("state count=3") + + it should "reject a changed state before the handler runs" in: + val signed = stateOf(call("a")) + shouldBeRejected(call("a", state = Some(signed + "-TAMPERED"))) + shouldBeRejected(call("a", state = Some("x" + signed.drop(1)))) + shouldBeRejected(call("a", state = Some("count=1"))) + + it should "reject an expired state" in: + val signed = stateOf(call("a")) + now.addAndGet(2.minutes.toMillis) + shouldBeRejected(call("a", state = Some(signed))) + + it should "reject a state of another tool, or of other arguments" in: + val signed = stateOf(call("a", count = 1)) + shouldBeRejected(call("b", count = 1, state = Some(signed))) + shouldBeRejected(call("a", count = 2, state = Some(signed))) + + it should "reject a state of another principal on a secured server" in: + val signed = stateOf(callAs("alice")) + textOf(callAs("alice", Some(signed))) shouldBe Some("state count=1") + shouldBeRejected(callAs("bob", Some(signed))) + + it should "need a secret of at least 32 bytes" in: + an[IllegalArgumentException] should be thrownBy RequestStateSigner(Array.fill[Byte](31)(1)) From 57d3c2d19966beb6196d0cb2ec82c314fc663516 Mon Sep 17 00:00:00 2001 From: Ondra Pelech Date: Thu, 19 Nov 2026 18:07:55 +0100 Subject: [PATCH 21/31] feat(T14): add the request-state conformance fixtures The conformance server signs its request states with a random per-process secret, and offers test_input_required_result_request_state and test_input_required_result_tampered_state. Both scenarios pass and leave the 2026-07-28 baseline. --- conformance-baseline-2026-07-28.yml | 3 -- .../scala/chimp/conformance/server/Main.scala | 35 +++++++++++++++++++ 2 files changed, 35 insertions(+), 3 deletions(-) diff --git a/conformance-baseline-2026-07-28.yml b/conformance-baseline-2026-07-28.yml index 717f710b..5c9a2f8a 100644 --- a/conformance-baseline-2026-07-28.yml +++ b/conformance-baseline-2026-07-28.yml @@ -12,9 +12,6 @@ server: - tasks-request-state-removal - tasks-required-task-error - tasks-wire-fields - # an integrity-protected requestState — T14 request-state helper, https://github.com/softwaremill/chimp/issues/252 - - input-required-result-request-state - - input-required-result-tampered-state # x-mcp-header custom headers in the tool DSL — T13, https://github.com/softwaremill/chimp/issues/251 - http-custom-header-server-validation # the harness records a failure in a non-primary run of these scenarios (the primary run passes) diff --git a/server-conformance/src/main/scala/chimp/conformance/server/Main.scala b/server-conformance/src/main/scala/chimp/conformance/server/Main.scala index 8a7ab7e6..8b8798a0 100644 --- a/server-conformance/src/main/scala/chimp/conformance/server/Main.scala +++ b/server-conformance/src/main/scala/chimp/conformance/server/Main.scala @@ -10,6 +10,7 @@ import sttp.shared.Identity import sttp.tapir.Schema import sttp.tapir.server.netty.sync.NettySyncServer +import java.security.SecureRandom import java.util.Base64 import scala.concurrent.duration.* @@ -216,6 +217,32 @@ object Main: else if capabilities.roots.isDefined then InputRequired("client_roots" -> InputRequired.listRoots) else ToolResult.text("The client declared no capability to ask with") + private val askConfirmation = + InputRequired.elicitForm( + "Please confirm", + Json.obj( + "type" -> Json.fromString("object"), + "properties" -> Json.obj("ok" -> Json.obj("type" -> Json.fromString("boolean"))), + "required" -> Json.arr(Json.fromString("ok")) + ) + ) + + private def confirmed(ctx: ServerContext[Identity]): Boolean = + ctx.request.elicitResult("confirm").flatMap(_.content).flatMap(_.get("ok")).flatMap(_.asBoolean).contains(true) + + private def confirmationTool(name: String, description: String) = tool(name) + .description(description) + .input[NoInput] + .serverLogicWithContext[Identity]: (_, ctx, _) => + if ctx.request.requestState.contains("awaiting-confirmation") && confirmed(ctx) then ToolResult.text("state-ok: confirmed") + else InputRequired("confirm" -> askConfirmation).withRequestState("awaiting-confirmation") + + private val requestStateTool = + confirmationTool("test_input_required_result_request_state", "Asks for a confirmation and checks the signed request state on the retry") + + private val tamperedStateTool = + confirmationTool("test_input_required_result_tampered_state", "Asks for a confirmation; a retry with a changed request state fails") + private val streamingElicitationTool = tool("test_streaming_elicitation") .description("Reports progress on the response stream, then asks for the user's name") .input[NoInput] @@ -232,6 +259,11 @@ object Main: private val publisher = NotificationPublisher() + private val requestStateSecret: Array[Byte] = + val secret = new Array[Byte](32) + SecureRandom().nextBytes(secret) + secret + private val triggerToolChange = tool("test_trigger_tool_change") .description("Publishes a tools list change to the open subscriptions") .input[NoInput] @@ -321,6 +353,8 @@ object Main: multipleInputsTool, multiRoundTool, capabilitiesTool, + requestStateTool, + tamperedStateTool, triggerToolChange, triggerPromptChange ) @@ -331,6 +365,7 @@ object Main: .withLoggingLevel(_ => ()) .withSubscriptions(ResourceSubscriptions[Identity](_ => (), _ => ())) .withPublisher(publisher) + .withRequestStateSigner(RequestStateSigner(requestStateSecret)) private val streamingServer = server.streaming.addStreamingTools(progressTool, loggingTool, perRequestLoggingTool, streamingElicitationTool) From 5b0e8a7c587fe939acec2a3a991a503b4c84cef6 Mon Sep 17 00:00:00 2001 From: Ondra Pelech Date: Thu, 19 Nov 2026 18:08:27 +0100 Subject: [PATCH 22/31] docs(T14): document the request state signer Explains how to give a server a RequestStateSigner, what the signature covers, how a failed verification is answered, and the security notes: secret size and storage, rotation, no confidentiality, no single use. --- docs/server/mrtr.md | 33 ++++++++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-) diff --git a/docs/server/mrtr.md b/docs/server/mrtr.md index e22187fd..f9020171 100644 --- a/docs/server/mrtr.md +++ b/docs/server/mrtr.md @@ -43,7 +43,7 @@ Prompts and resources use the same `InputRequired` from their `serverLogicWithCo A handler can ask again on the retry, as many times as it needs. To remember what happened in the earlier rounds, it attaches a **request state** with `.withRequestState(state)`. The client sends the state back without a change on its retry, and the handler reads it from `ctx.request.requestState`. `InputRequired.withRequestState(state)` makes an outcome that has a state and no input requests: the client then retries at once. ```{warning} -The request state goes through the client, so treat it as input from an attacker. If the state controls authorization, resource access or business logic, protect its integrity, and reject a state that you cannot verify. +The request state goes through the client, so treat it as input from an attacker. If the state controls authorization, resource access or business logic, protect its integrity with a [request state signer](#protecting-the-request-state). ``` ### Missing answers @@ -68,3 +68,34 @@ chimp applies these rules, so a handler does not have to: An `InputRequired` always has at least one input request or a request state. Only `tools/call`, `prompts/get` and `resources/read` can end with it. On a streaming HTTP server, chimp opens the event stream when the handler sends its first message. If the handler ends with the `-32021` before it sends a message, chimp sends a plain JSON error with HTTP `400`. If the handler already sent a message, for example a progress notification, the `-32021` is the last message on the event stream. + +## Protecting the request state + +Give the server a `RequestStateSigner` to protect the integrity of all request states: + +```scala mdoc:compile-only +import chimp.server.* +import sttp.shared.Identity +import scala.concurrent.duration.* + +val secret: Array[Byte] = sys.env("MCP_REQUEST_STATE_SECRET").getBytes("UTF-8") + +val server = McpServer[Identity]() + .withRequestStateSigner(RequestStateSigner(secret, ttl = 5.minutes)) +``` + +The handler code does not change. When a handler returns a request state, chimp signs it with HMAC-SHA256. The signature also covers: + +- an expiry, after the `ttl` (10 minutes by default), +- the method, the tool or prompt name or the resource URI, and a digest of the arguments of the request, +- on a secured server, the principal: use `withRequestStateSigner(signer, principalId)`, where `principalId` gives a stable identifier of the principal. + +On the retry, chimp verifies the state before the handler runs, and gives the handler the original state. If the state was changed, has expired, or belongs to another request or principal, chimp sends `-32602` InvalidParams with HTTP `400`, and the handler does not run. + +Security notes: + +- The secret must have at least 32 bytes. Keep it in a secret store, not in the code. All instances of the server must use the same secret, or a retry can fail on a different instance. +- When you change the secret, all request states that are in progress become invalid. The clients must start these requests again. +- The signer protects the integrity of the state, not its confidentiality. The client can read the state, so do not put secrets in it. +- The signer does not make a state single-use. Within its lifetime, the client can send the same state again on the same request. If an action must occur only one time, record it on the server. + From bf7ee20ee637b07243d8eda7b013b169a14fafb3 Mon Sep 17 00:00:00 2001 From: Ondra Pelech Date: Thu, 19 Nov 2026 18:27:08 +0100 Subject: [PATCH 23/31] feat(T13): mark tool input properties with x-mcp-header Tool.withMcpHeader marks an input property, given by its name or by a chain of properties keys, so the generated inputSchema carries the x-mcp-header annotation. It works for derived and raw JSON schemas. The tool builder checks the spec constraints when the tool is built: inputJson, input and withMcpHeader throw IllegalArgumentException, as the tool name check does, for an empty name, a name outside the HTTP token syntax or with control characters, a duplicate name (ignoring case), a property that is not string, integer or boolean, and a property not reachable from the root through properties keys only. McpHeaders also holds the Base64 sentinel decoding and the header and argument comparison, which the server uses in the next step. --- .../main/scala/chimp/server/McpHandler.scala | 10 +- .../main/scala/chimp/server/McpHeaders.scala | 169 ++++++++++++++++++ server/src/main/scala/chimp/server/Tool.scala | 24 ++- .../chimp/server/McpHeaderToolSpec.scala | 114 ++++++++++++ 4 files changed, 306 insertions(+), 11 deletions(-) create mode 100644 server/src/main/scala/chimp/server/McpHeaders.scala create mode 100644 server/src/test/scala/chimp/server/McpHeaderToolSpec.scala diff --git a/server/src/main/scala/chimp/server/McpHandler.scala b/server/src/main/scala/chimp/server/McpHandler.scala index 1b9a4902..dd9172b0 100644 --- a/server/src/main/scala/chimp/server/McpHandler.scala +++ b/server/src/main/scala/chimp/server/McpHandler.scala @@ -4,11 +4,9 @@ import chimp.protocol.* import io.circe.* import io.circe.syntax.* import org.slf4j.LoggerFactory -import sttp.apispec.circe.* import sttp.model.{Header, StatusCode} import sttp.monad.MonadError import sttp.monad.syntax.* -import sttp.tapir.docs.apispec.schema.TapirSchemaToJsonSchema enum McpResponse: case JsonResponse(json: Json) @@ -44,17 +42,13 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD private val hasPrompts = server.prompts.nonEmpty private val toolDefinitions = server.tools.map(toolToDefinition) - private def toJsonSchema(toolSchema: ToolSchema): Json = toolSchema match - case ToolSchema.Derived(schema) => - val base = TapirSchemaToJsonSchema(schema, markOptionsAsNullable = false) - (if server.showJsonSchemaMetadata then base else base.copy($schema = None)).asJson - case ToolSchema.Raw(json) => json + private def toJsonSchema(toolSchema: ToolSchema): Json = McpHeaders.render(toolSchema, server.showJsonSchemaMetadata) private def toolToDefinition(tool: ServerTool[?, ?, F, C]): ToolDefinition = ToolDefinition( name = tool.name, description = tool.description, - inputSchema = toJsonSchema(tool.inputSchema), + inputSchema = McpHeaders.annotated(toJsonSchema(tool.inputSchema), tool.mcpHeaders).getOrElse(toJsonSchema(tool.inputSchema)), outputSchema = tool.outputSchema.map(toJsonSchema), annotations = tool.annotations .map(annotation => diff --git a/server/src/main/scala/chimp/server/McpHeaders.scala b/server/src/main/scala/chimp/server/McpHeaders.scala new file mode 100644 index 00000000..a762ff0e --- /dev/null +++ b/server/src/main/scala/chimp/server/McpHeaders.scala @@ -0,0 +1,169 @@ +package chimp.server + +import io.circe.syntax.* +import io.circe.{Json, JsonObject} +import sttp.apispec.circe.* +import sttp.tapir.docs.apispec.schema.TapirSchemaToJsonSchema + +import java.nio.ByteBuffer +import java.nio.charset.{CodingErrorAction, StandardCharsets} +import java.util.{Base64, Locale} +import scala.util.Try + +/** A tool input property mirrored into the `Mcp-Param-{name}` HTTP header. + * + * @param path + * The chain of `properties` keys from the input schema root to the property. + * @param name + * The `x-mcp-header` value: the name part of the header. + */ +case class McpHeader(path: List[String], name: String) + +/** The `x-mcp-header` schema extension and the Base64 sentinel form of header values. */ +private[server] object McpHeaders: + val Key = "x-mcp-header" + val ParamPrefix = "Mcp-Param-" + + private val SentinelPrefix = "=?base64?" + private val SentinelSuffix = "?=" + private val Base64Alphabet = "^[A-Za-z0-9+/]*={0,2}$".r + private val PrimitiveTypes = Set("string", "integer", "boolean") + private val TokenSymbols = "!#$%&'*+-.^_`|~".toSet + private val SchemaMaps = Set("properties", "patternProperties", "$defs", "definitions", "dependentSchemas") + private val NonSchemaValues = Set("default", "examples", "example", "const", "enum", Key) + + def render(schema: ToolSchema, showMetadata: Boolean): Json = schema match + case ToolSchema.Derived(schema) => + val base = TapirSchemaToJsonSchema(schema, markOptionsAsNullable = false) + (if showMetadata then base else base.copy($schema = None)).asJson + case ToolSchema.Raw(json) => json + + /** The input schema with every header in `headers` added as an `x-mcp-header` annotation. */ + def annotated(schema: Json, headers: List[McpHeader]): Either[String, Json] = + headers.foldLeft[Either[String, Json]](Right(schema))((acc, header) => acc.flatMap(annotate(_, header))) + + private def annotate(schema: Json, header: McpHeader): Either[String, Json] = + def at(json: Json, path: List[String]): Option[Json] = path match + case Nil => json.asObject.map(node => Json.fromJsonObject(node.add(Key, header.name.asJson))) + case key :: rest => + for + node <- json.asObject + properties <- node("properties").flatMap(_.asObject) + child <- properties(key) + updated <- at(child, rest) + yield Json.fromJsonObject(node.add("properties", Json.fromJsonObject(properties.add(key, updated)))) + Option + .when(header.path.nonEmpty)(at(schema, header.path)) + .flatten + .toRight(s"no input property at ${header.path.mkString(".")} reachable through properties keys only") + + /** The violations of the `x-mcp-header` constraints in the input schema. */ + def problems(schema: Json): List[String] = + val found = annotations(schema) + val names = found.flatMap((_, node) => node(Key).flatMap(_.asString)) + val duplicates = names + .groupBy(_.toLowerCase(Locale.ROOT)) + .values + .collect { case same if same.size > 1 => s"x-mcp-header '${same.head}' is used more than once (names are case-insensitive)" } + found.flatMap(problem) ++ duplicates + + /** The headers which the input schema declares, from annotations on properties reachable through `properties` keys only. */ + def params(schema: Json): List[McpHeader] = + for + (path, node) <- annotations(schema) + name <- node(Key).flatMap(_.asString) + propertyPath <- propertyPath(path) + yield McpHeader(propertyPath, name) + + private def problem(path: List[String], node: JsonObject): Option[String] = + val location = path.mkString("#/", "/", "") + def invalid(reason: String) = Some(s"x-mcp-header at $location $reason") + node(Key).flatMap(_.asString) match + case None => invalid("must be a string") + case Some(name) if name.isEmpty => invalid("must not be empty") + case Some(name) if name.exists(Character.isISOControl) => invalid("must not contain control characters") + case Some(name) if !name.forall(isTokenChar) => invalid(s"must be an HTTP token, got '$name'") + case Some(_) if propertyPath(path).isEmpty => invalid("must be on a property reachable through properties keys only") + case Some(_) if !node("type").exists(isPrimitiveType) => invalid("must be on a string, integer or boolean property") + case Some(_) => None + + private def isTokenChar(c: Char): Boolean = (c < 128 && c.isLetterOrDigit) || TokenSymbols.contains(c) + + private def isPrimitiveType(json: Json): Boolean = + json.asString.exists(PrimitiveTypes.contains) || + json.asArray + .flatMap(_.flatMap(_.asString).filterNot(_ == "null").toList match + case single :: Nil => Some(PrimitiveTypes.contains(single)) + case _ => None) + .contains(true) + + private def propertyPath(path: List[String]): Option[List[String]] = + val steps = path.grouped(2).toList + Option.when(path.nonEmpty && path.length % 2 == 0 && steps.forall(_.head == "properties"))(steps.map(_(1))) + + /** Every schema node carrying `x-mcp-header`, with its path from the root as JSON keys (array indices as strings). */ + private def annotations(schema: Json): List[(List[String], JsonObject)] = + def walk(json: Json, path: List[String]): List[(List[String], JsonObject)] = + json.asObject.toList.flatMap: node => + val own = node(Key).map(_ => (path, node)).toList + val nested = node.toList.flatMap: + case (key, _) if NonSchemaValues.contains(key) => Nil + case (key, value) if SchemaMaps.contains(key) => + value.asObject.toList.flatMap(_.toList.flatMap((name, sub) => walk(sub, path ++ List(key, name)))) + case (key, value) => + value.asArray match + case Some(items) => items.toList.zipWithIndex.flatMap((item, i) => walk(item, path ++ List(key, i.toString))) + case None => walk(value, path :+ key) + own ++ nested + walk(schema, Nil) + + /** Decodes a header value which may use the Base64 sentinel form `=?base64?...?=`; a value without the full wrapper is literal. */ + def decode(value: String): Either[String, String] = + val wrapped = + value.length >= SentinelPrefix.length + SentinelSuffix.length && value.startsWith(SentinelPrefix) && value.endsWith(SentinelSuffix) + if value.exists(c => (c < ' ' && c != '\t') || c > '~') then Left("contains invalid characters") + else if !wrapped then Right(value) + else + val encoded = value.substring(SentinelPrefix.length, value.length - SentinelSuffix.length) + val bytes = Option + .when(encoded.length % 4 == 0 && Base64Alphabet.matches(encoded))(Try(Base64.getDecoder.decode(encoded)).toOption) + .flatten + bytes.toRight("is not valid Base64").flatMap(utf8) + + private def utf8(bytes: Array[Byte]): Either[String, String] = + val decoder = + StandardCharsets.UTF_8.newDecoder().onMalformedInput(CodingErrorAction.REPORT).onUnmappableCharacter(CodingErrorAction.REPORT) + Try(decoder.decode(ByteBuffer.wrap(bytes)).toString).toOption.toRight("is not valid UTF-8 after Base64 decoding") + + /** Whether a decoded header value equals the argument: numbers compare numerically, booleans as `true`/`false`, strings literally. */ + def matches(header: String, argument: Json): Boolean = + argument.fold( + jsonNull = false, + jsonBoolean = _.toString == header, + jsonNumber = number => Try(BigDecimal(header)).toOption.exists(value => number.toBigDecimal.exists(_.compare(value) == 0)), + jsonString = _ == header, + jsonArray = _ => false, + jsonObject = _ => false + ) + + /** The `-32020` message for the first `Mcp-Param-*` header of `params` which does not mirror its argument. A null or absent argument + * expects no header. + */ + def mismatch(params: List[McpHeader], arguments: Option[Json], header: String => Option[String]): Option[String] = + params.iterator + .map: param => + val name = ParamPrefix + param.name + val argument = param.path.foldLeft(arguments)((json, key) => json.flatMap(_.asObject).flatMap(_(key))).filterNot(_.isNull) + (argument, header(name).map(decode)) match + case (None, None) => None + case (Some(_), None) => Some(s"$name header missing for an argument present in the body") + case (_, Some(Left(problem))) => Some(s"$name header $problem") + case (None, Some(Right(_))) => Some(s"$name header present, but the argument is absent from the body") + case (Some(value), Some(Right(h))) => Option.unless(matches(h, value))(s"$name header does not match the argument") + .collectFirst { case Some(message) => message } + + /** Throws [[IllegalArgumentException]] when the tool's input schema breaks the `x-mcp-header` constraints. */ + def validate(tool: String, schema: ToolSchema, headers: List[McpHeader]): Unit = + val annotated = McpHeaders.annotated(render(schema, showMetadata = false), headers) + val found = annotated.fold(List(_), problems) + require(found.isEmpty, s"Tool $tool has an invalid x-mcp-header: ${found.mkString("; ")}") diff --git a/server/src/main/scala/chimp/server/Tool.scala b/server/src/main/scala/chimp/server/Tool.scala index 870f6d51..f211c514 100644 --- a/server/src/main/scala/chimp/server/Tool.scala +++ b/server/src/main/scala/chimp/server/Tool.scala @@ -83,6 +83,7 @@ case class PartialTool( /** Fixes the input type, deriving its JSON Schema and decoder from the given instances. */ def input[I: Schema: Decoder]: Tool[I, NoStructuredOutput] = + McpHeaders.validate(name, ToolSchema.Derived(summon[Schema[I]]), Nil) Tool[I, NoStructuredOutput]( name, description, @@ -95,6 +96,7 @@ case class PartialTool( /** Fixes the input as raw JSON, validated against the given JSON Schema. */ def inputJson(schema: Json): Tool[Json, NoStructuredOutput] = + McpHeaders.validate(name, ToolSchema.Raw(schema), Nil) Tool[Json, NoStructuredOutput]( name, description, @@ -115,8 +117,23 @@ case class Tool[I, O]( inputDecoder: Decoder[I], outputSchema: Option[ToolSchema], annotations: Option[ToolAnnotations], - requiredClientCapabilities: Option[ClientCapabilities] = None + requiredClientCapabilities: Option[ClientCapabilities] = None, + mcpHeaders: List[McpHeader] = Nil ): + /** Marks the top-level input property `property` with `x-mcp-header`, so that a client mirrors its value into the `Mcp-Param-{header}` + * HTTP header and the server checks that the header matches the argument. Throws [[IllegalArgumentException]] when the annotation breaks + * the spec constraints. + */ + def withMcpHeader(property: String, header: String): Tool[I, O] = withMcpHeader(List(property), header) + + /** Marks the input property at `path`, a chain of `properties` keys from the schema root, with `x-mcp-header`, as the single-property + * overload does. + */ + def withMcpHeader(path: List[String], header: String): Tool[I, O] = + val headers = mcpHeaders :+ McpHeader(path, header) + McpHeaders.validate(name, inputSchema, headers) + copy(mcpHeaders = headers) + /** Fixes the structured output type, deriving its JSON Schema from the given instance. */ def output[O2: Schema]: Tool[I, O2] = copy(outputSchema = Some(ToolSchema.Derived(summon[Schema[O2]]))) @@ -169,7 +186,7 @@ case class Tool[I, O]( private def serverTool[F[_], C <: ServerContext[F]]( logic: (I, C, Seq[Header]) => F[ToolResult[O] | InputRequired] ): ServerTool[I, O, F, C] = - ServerTool(name, description, inputSchema, inputDecoder, outputSchema, annotations, logic, requiredClientCapabilities) + ServerTool(name, description, inputSchema, inputDecoder, outputSchema, annotations, logic, requiredClientCapabilities, mcpHeaders) /** A fully-defined tool: its metadata plus the logic handling a call, in effect `F` with context `C`. */ case class ServerTool[I, O, F[_], -C <: ServerContext[F]]( @@ -180,5 +197,6 @@ case class ServerTool[I, O, F[_], -C <: ServerContext[F]]( outputSchema: Option[ToolSchema], annotations: Option[ToolAnnotations], logic: (I, C, Seq[Header]) => F[ToolResult[O] | InputRequired], - requiredClientCapabilities: Option[ClientCapabilities] = None + requiredClientCapabilities: Option[ClientCapabilities] = None, + mcpHeaders: List[McpHeader] = Nil ) diff --git a/server/src/test/scala/chimp/server/McpHeaderToolSpec.scala b/server/src/test/scala/chimp/server/McpHeaderToolSpec.scala new file mode 100644 index 00000000..c3c33c32 --- /dev/null +++ b/server/src/test/scala/chimp/server/McpHeaderToolSpec.scala @@ -0,0 +1,114 @@ +package chimp.server + +import chimp.protocol.{JSONRPCMessage, RequestId} +import io.circe.parser.parse +import io.circe.syntax.* +import io.circe.{Codec, Json} +import org.scalatest.flatspec.AnyFlatSpec +import org.scalatest.matchers.should.Matchers +import sttp.monad.{IdentityMonad, MonadError} +import sttp.shared.Identity +import sttp.tapir.Schema + +class McpHeaderToolSpec extends AnyFlatSpec with Matchers: + case class Inner(zone: String) derives Schema, Codec + case class Query(region: String, limit: Int, dryRun: Boolean, ratio: Double, tags: List[String], inner: Inner) derives Schema, Codec + + private def json(text: String): Json = parse(text).fold(throw _, identity) + + private def rawTool(properties: String, extra: String = "") = + tool("raw").inputJson(json(s"""{"type": "object", "properties": $properties $extra}""")) + + private given MonadError[Identity] = IdentityMonad + + private def inputSchema(tool: Tool[?, NoStructuredOutput]): Json = + val handler = McpHandler(McpServer(tools = List(tool.handle(_ => ToolResult.text("ok"))))) + val request: JSONRPCMessage = JSONRPCMessage.Request(method = "tools/list", id = RequestId("1")) + val tools = handler.handleJsonRpc(request.asJson, Nil).body.flatMap(_.hcursor.downField("result").downField("tools").focus) + tools.flatMap(_.hcursor.downArray.downField("inputSchema").focus).getOrElse(fail("no input schema")) + + "withMcpHeader" should "annotate a property of a schema derived from a case class" in: + val annotated = tool("derived").input[Query].withMcpHeader("region", "Region").withMcpHeader("limit", "Limit") + val schema = inputSchema(annotated) + schema.hcursor.downField("properties").downField("region").get[String]("x-mcp-header") shouldBe Right("Region") + schema.hcursor.downField("properties").downField("limit").get[String]("x-mcp-header") shouldBe Right("Limit") + McpHeaders.params(schema) should contain theSameElementsAs List(McpHeader(List("region"), "Region"), McpHeader(List("limit"), "Limit")) + + it should "annotate a nested property of a raw JSON schema" in: + val annotated = + rawTool("""{"location": {"type": "object", "properties": {"region": {"type": "string"}}}}""") + .withMcpHeader(List("location", "region"), "Region") + val schema = inputSchema(annotated) + schema.hcursor + .downField("properties") + .downField("location") + .downField("properties") + .downField("region") + .get[String]( + "x-mcp-header" + ) shouldBe Right("Region") + + it should "keep an annotation already present in a raw JSON schema" in: + val schema = inputSchema(rawTool("""{"region": {"type": ["string", "null"], "x-mcp-header": "Region"}}""")) + McpHeaders.params(schema) shouldBe List(McpHeader(List("region"), "Region")) + + it should "reject a header name which breaks the spec constraints" in: + val base = tool("derived").input[Query] + for name <- List("", "Bad Name", "Bad:Name", "Line\nBreak", "Ctrl\u0001", "Région") do + withClue(name): + an[IllegalArgumentException] should be thrownBy base.withMcpHeader("region", name) + + it should "reject a header name used twice in one tool, regardless of case" in: + an[IllegalArgumentException] should be thrownBy + tool("derived").input[Query].withMcpHeader("region", "Region").withMcpHeader("limit", "REGION") + + it should "reject a property whose type is not string, integer or boolean" in: + for property <- List("ratio", "tags", "inner") do + withClue(property): + an[IllegalArgumentException] should be thrownBy tool("derived").input[Query].withMcpHeader(property, "Header") + tool("derived").input[Query].withMcpHeader("dryRun", "Dry-Run").mcpHeaders shouldBe List(McpHeader(List("dryRun"), "Dry-Run")) + + it should "reject a property which does not exist or is not reachable through properties keys only" in: + an[IllegalArgumentException] should be thrownBy tool("derived").input[Query].withMcpHeader("missing", "Header") + an[IllegalArgumentException] should be thrownBy tool("derived").input[Query].withMcpHeader(List("inner", "zone"), "Zone") + an[IllegalArgumentException] should be thrownBy tool("derived").input[Query].withMcpHeader(Nil, "Header") + + "inputJson" should "reject an annotation which is not reachable through properties keys only" in: + an[IllegalArgumentException] should be thrownBy + rawTool("""{"tags": {"type": "array", "items": {"type": "string", "x-mcp-header": "Tag"}}}""") + an[IllegalArgumentException] should be thrownBy + rawTool("""{"a": {"type": "string"}}""", """, "anyOf": [{"properties": {"a": {"type": "string", "x-mcp-header": "A"}}}]""") + an[IllegalArgumentException] should be thrownBy + rawTool("""{"a": {"$ref": "#/$defs/A"}}""", """, "$defs": {"A": {"type": "string", "x-mcp-header": "A"}}""") + + it should "reject an annotation with an invalid value or on an invalid type" in: + an[IllegalArgumentException] should be thrownBy rawTool("""{"a": {"type": "string", "x-mcp-header": 1}}""") + an[IllegalArgumentException] should be thrownBy rawTool("""{"a": {"type": "number", "x-mcp-header": "A"}}""") + an[IllegalArgumentException] should be thrownBy rawTool("""{"a": {"x-mcp-header": "A"}}""") + an[IllegalArgumentException] should be thrownBy + rawTool("""{"a": {"type": "string", "x-mcp-header": "A"}, "b": {"type": "integer", "x-mcp-header": "a"}}""") + + it should "not treat a property named x-mcp-header or a default value as an annotation" in: + noException should be thrownBy rawTool("""{"x-mcp-header": {"type": "object", "default": {"x-mcp-header": 1}}}""") + + "McpHeaders.decode" should "decode the Base64 sentinel form and keep any other value literal" in: + McpHeaders.decode("=?base64?SGVsbG8=?=") shouldBe Right("Hello") + McpHeaders.decode("=?base64?SGVsbG8sIOS4lueVjA==?=") shouldBe Right("Hello, 世界") + McpHeaders.decode("=?base64??=") shouldBe Right("") + McpHeaders.decode("SGVsbG8=") shouldBe Right("SGVsbG8=") + McpHeaders.decode("=?base64?SGVsbG8=") shouldBe Right("=?base64?SGVsbG8=") + McpHeaders.decode("SGVsbG8=?=") shouldBe Right("SGVsbG8=?=") + + it should "reject a malformed sentinel or invalid characters" in: + for value <- List("=?base64?SGVsbG8?=", "=?base64?SGVs!!!bG8=?=", "=?base64?S===?=", "=?base64?/w==?=", "café", "a\u0000b") do + withClue(value)(McpHeaders.decode(value).isLeft shouldBe true) + + "McpHeaders.matches" should "compare numbers numerically and other values literally" in: + McpHeaders.matches("42.0", Json.fromInt(42)) shouldBe true + McpHeaders.matches("4.2e1", Json.fromInt(42)) shouldBe true + McpHeaders.matches("43", Json.fromInt(42)) shouldBe false + McpHeaders.matches("x", Json.fromInt(42)) shouldBe false + McpHeaders.matches("true", Json.True) shouldBe true + McpHeaders.matches("True", Json.True) shouldBe false + McpHeaders.matches("us-west1", Json.fromString("us-west1")) shouldBe true + McpHeaders.matches("US-WEST1", Json.fromString("us-west1")) shouldBe false From ba531f57234bd1a547417734b9a8c307c622abe4 Mon Sep 17 00:00:00 2001 From: Ondra Pelech Date: Thu, 19 Nov 2026 18:30:11 +0100 Subject: [PATCH 24/31] feat(T13): validate Mcp-Param headers and Base64 sentinel values A modern tools/call over HTTP must mirror every argument that its tool marks with x-mcp-header in the Mcp-Param-{name} header. The server rejects with -32020 and HTTP 400 a header that is missing for a present argument, present for a null or absent argument, malformed, or does not match: numbers compare numerically, other values literally. Mcp-Param headers that match no annotated property are ignored. Mcp-Name and Mcp-Param values in the Base64 sentinel form are decoded before the comparison; a malformed sentinel or a value with invalid characters is a -32020. Legacy requests and stdio are unaffected. --- .../main/scala/chimp/server/McpHandler.scala | 27 ++++++--- .../scala/chimp/server/McpHandlerSpec.scala | 57 +++++++++++++++++++ 2 files changed, 76 insertions(+), 8 deletions(-) diff --git a/server/src/main/scala/chimp/server/McpHandler.scala b/server/src/main/scala/chimp/server/McpHandler.scala index dd9172b0..63d7a7b1 100644 --- a/server/src/main/scala/chimp/server/McpHandler.scala +++ b/server/src/main/scala/chimp/server/McpHandler.scala @@ -334,19 +334,30 @@ private[server] class McpHandler[F[_], C <: ServerContext[F]](server: McpServerD // SEP-2243: the body field that the `Mcp-Name` header must mirror, per method private val nameFields: Map[String, String] = Map("tools/call" -> "name", "prompts/get" -> "name", "resources/read" -> "uri") - /** SEP-2243 standard request headers: `Mcp-Method` must equal the body method, and `Mcp-Name` must equal the method's name-shaped body - * field ([[nameFields]]); values are case-sensitive, surrounding whitespace is ignored. A missing or mismatched header is a `-32020` - * HeaderMismatch with HTTP 400. + private val headerParams: Map[String, List[McpHeader]] = + toolDefinitions.map(definition => definition.name -> McpHeaders.params(definition.inputSchema)).toMap + + /** SEP-2243 request headers: `Mcp-Method` must equal the body method, `Mcp-Name` the method's name-shaped body field ([[nameFields]]), + * and on `tools/call` each `Mcp-Param-{name}` the argument its tool marks with `x-mcp-header`. Values are case-sensitive, surrounding + * whitespace is ignored, and `Mcp-Name` and `Mcp-Param-*` values are compared after decoding the Base64 sentinel form. A missing, + * malformed or mismatched header is a `-32020` HeaderMismatch with HTTP 400. */ private def headerValidationError(method: String, params: Option[Json], headers: Seq[Header], id: RequestId): Option[McpResponse] = def header(name: String): Option[String] = headers.collectFirst { case h if h.name.equalsIgnoreCase(name) => h.value.trim } - def mismatch(message: String) = Some(jsonError(id, StatusCode.BadRequest, JSONRPCErrorCodes.HeaderMismatch.code, message)) val nameField = nameFields.get(method) val bodyName = nameField.flatMap(field => params.flatMap(_.hcursor.get[String](field).toOption)) - if !header("Mcp-Method").contains(method) then mismatch("Mcp-Method header missing or does not match the request method") - else if bodyName.exists(name => !header("Mcp-Name").contains(name)) then - mismatch(s"Mcp-Name header missing or does not match params.${nameField.getOrElse("name")}") - else None + val nameError = bodyName.flatMap: name => + header("Mcp-Name").map(McpHeaders.decode) match + case None => Some("Mcp-Name header missing") + case Some(Left(problem)) => Some(s"Mcp-Name header $problem") + case Some(Right(value)) if value != name => Some(s"Mcp-Name header does not match params.${nameField.getOrElse("name")}") + case Some(Right(_)) => None + val toolHeaders = Option.when(method == "tools/call")(bodyName.flatMap(headerParams.get)).flatten.getOrElse(Nil) + val arguments = params.flatMap(_.hcursor.downField("arguments").focus) + val message = + if !header("Mcp-Method").contains(method) then Some("Mcp-Method header missing or does not match the request method") + else nameError.orElse(McpHeaders.mismatch(toolHeaders, arguments, header)) + message.map(jsonError(id, StatusCode.BadRequest, JSONRPCErrorCodes.HeaderMismatch.code, _)) private val serverImplementation: Implementation = Implementation(server.name, server.version) private val serverInfoJson: Json = serverImplementation.asJson diff --git a/server/src/test/scala/chimp/server/McpHandlerSpec.scala b/server/src/test/scala/chimp/server/McpHandlerSpec.scala index e2b51d03..b3feabc2 100644 --- a/server/src/test/scala/chimp/server/McpHandlerSpec.scala +++ b/server/src/test/scala/chimp/server/McpHandlerSpec.scala @@ -211,6 +211,63 @@ class McpHandlerSpec extends AnyFlatSpec with Matchers: response.statusCode shouldBe sttp.model.StatusCode.Ok extractJsonFromResponse(response).as[JSONRPCMessage].getOrElse(fail("decode")) shouldBe a[Response] + it should "decode a Base64 sentinel Mcp-Name before comparing it, and reject a malformed one with -32020" in: + val params = Json.obj("name" -> Json.fromString("echo"), "arguments" -> Json.obj("message" -> Json.fromString("hi"))) + val encoded = "=?base64?ZWNobw==?=" + modernHttpCall("tools/call", params, "Mcp-Method" -> "tools/call", "Mcp-Name" -> encoded).statusCode shouldBe sttp.model.StatusCode.Ok + shouldBeHeaderMismatch(modernHttpCall("tools/call", params, "Mcp-Method" -> "tools/call", "Mcp-Name" -> "=?base64?ZWNobw?=")) + shouldBeHeaderMismatch(modernHttpCall("tools/call", params, "Mcp-Method" -> "tools/call", "Mcp-Name" -> "=?base64?d3Jvbmc=?=")) + + case class RegionInput(region: String, limit: Option[Int], dryRun: Option[Boolean]) derives Schema, Codec + + private val regionTool = tool("region") + .input[RegionInput] + .withMcpHeader("region", "Region") + .withMcpHeader("limit", "Limit") + .withMcpHeader("dryRun", "Dry-Run") + .handle(in => ToolResult.text(in.region)) + private val customHeadersHandler = McpHandler(McpServer(tools = List(regionTool))) + + private def regionCall(arguments: Json, headers: (String, String)*): McpResponse = + val params = Json.obj("name" -> Json.fromString("region"), "arguments" -> arguments).deepMerge(Json.obj(modernMeta)) + val req: JSONRPCMessage = Request(method = "tools/call", params = Some(params), id = RequestId("c")) + val standard = Seq("Host" -> "localhost", ProtocolMeta.ProtocolVersionHeader -> "2026-07-28", "Mcp-Method" -> "tools/call") + customHeadersHandler.handleJsonRpc(req.asJson, (standard ++ (("Mcp-Name" -> "region") +: headers)).map(Header(_, _))) + + private def shouldBeServed(response: McpResponse): org.scalatest.Assertion = + response.statusCode shouldBe sttp.model.StatusCode.Ok + extractJsonFromResponse(response).as[JSONRPCMessage].getOrElse(fail("decode")) shouldBe a[Response] + + it should "serve a tools/call whose Mcp-Param headers match the arguments" in: + val arguments = Json.obj("region" -> Json.fromString("us-west1"), "limit" -> Json.fromInt(42), "dryRun" -> Json.True) + shouldBeServed(regionCall(arguments, "mcp-param-region" -> " us-west1 ", "Mcp-Param-Limit" -> "42.0", "MCP-PARAM-DRY-RUN" -> "true")) + shouldBeServed( + regionCall(arguments, "Mcp-Param-Region" -> "=?base64?dXMtd2VzdDE=?=", "Mcp-Param-Limit" -> "42", "Mcp-Param-Dry-Run" -> "true") + ) + + it should "expect no Mcp-Param header for a null or absent argument, and ignore unknown Mcp-Param headers" in: + shouldBeServed(regionCall(Json.obj("region" -> Json.fromString("eu"), "limit" -> Json.Null), "Mcp-Param-Region" -> "eu")) + shouldBeServed(regionCall(Json.obj("region" -> Json.fromString("eu")), "Mcp-Param-Region" -> "eu", "Mcp-Param-Other" -> "x")) + + it should "reject a tools/call whose Mcp-Param headers are missing, malformed or do not match the arguments with -32020" in: + val arguments = Json.obj("region" -> Json.fromString("Hello"), "limit" -> Json.fromInt(42)) + val matching = List("Mcp-Param-Region" -> "Hello", "Mcp-Param-Limit" -> "42") + shouldBeServed(regionCall(arguments, matching*)) + shouldBeHeaderMismatch(regionCall(arguments, "Mcp-Param-Limit" -> "42")) + shouldBeHeaderMismatch(regionCall(arguments, "Mcp-Param-Region" -> "hello", "Mcp-Param-Limit" -> "42")) + shouldBeHeaderMismatch(regionCall(arguments, "Mcp-Param-Region" -> "Hello", "Mcp-Param-Limit" -> "43")) + shouldBeHeaderMismatch(regionCall(arguments, "Mcp-Param-Region" -> "=?base64?SGVsbG8?=", "Mcp-Param-Limit" -> "42")) + shouldBeHeaderMismatch(regionCall(arguments, "Mcp-Param-Region" -> "=?base64?SGVs!!!bG8=?=", "Mcp-Param-Limit" -> "42")) + shouldBeHeaderMismatch(regionCall(arguments, "Mcp-Param-Region" -> "SGVsbG8=", "Mcp-Param-Limit" -> "42")) + shouldBeHeaderMismatch(regionCall(arguments, matching :+ ("Mcp-Param-Dry-Run" -> "true")*)) + + it should "not check Mcp-Param headers on a legacy request or a modern request without HTTP" in: + val params = Json.obj("name" -> Json.fromString("region"), "arguments" -> Json.obj("region" -> Json.fromString("eu"))) + val legacy: JSONRPCMessage = Request(method = "tools/call", params = Some(params), id = RequestId("l")) + shouldBeServed(customHeadersHandler.handleJsonRpc(legacy.asJson, Seq(Header("Host", "localhost"), Header("Mcp-Param-Region", "x")))) + val stdio: JSONRPCMessage = Request(method = "tools/call", params = Some(params.deepMerge(Json.obj(modernMeta))), id = RequestId("s")) + shouldBeServed(customHeadersHandler.handleJsonRpc(stdio.asJson, Seq.empty)) + it should "serve a classic initialize with no modern protocol version rather than rejecting it with -32022" in: val req: JSONRPCMessage = Request(method = "initialize", id = RequestId("legacy-init")) val respJson = extractJsonFromResponse(handler.handleJsonRpc(req.asJson, Seq.empty)) From 177c3849faf89f5657c857cb09d3477154de2cde Mon Sep 17 00:00:00 2001 From: Ondra Pelech Date: Thu, 19 Nov 2026 18:42:06 +0100 Subject: [PATCH 25/31] test(T13): check request headers on the ZIO, Ox and Pekko HTTP servers A shared trait runs the x-mcp-header and Base64 sentinel cases over raw HTTP against the plain and the streaming transport, and the ZIO, Ox and Pekko specs mix it in. A rejection must be a plain JSON -32020 with HTTP 400, also on the streaming transport. --- .../chimp/server/ox/OxMcpServerHttpSpec.scala | 6 ++ .../server/pekko/PekkoMcpServerHttpSpec.scala | 10 +- .../server/zio/ZioMcpServerHttpSpec.scala | 10 +- .../server/McpServerHeaderHttpTests.scala | 98 +++++++++++++++++++ 4 files changed, 122 insertions(+), 2 deletions(-) create mode 100644 server/src/test/scala/chimp/server/McpServerHeaderHttpTests.scala diff --git a/server-streaming/server-ox/src/test/scala/chimp/server/ox/OxMcpServerHttpSpec.scala b/server-streaming/server-ox/src/test/scala/chimp/server/ox/OxMcpServerHttpSpec.scala index 4c52d7a1..6eeeea24 100644 --- a/server-streaming/server-ox/src/test/scala/chimp/server/ox/OxMcpServerHttpSpec.scala +++ b/server-streaming/server-ox/src/test/scala/chimp/server/ox/OxMcpServerHttpSpec.scala @@ -8,6 +8,7 @@ import chimp.server.transport.SecuredServerStreamingHttpTransport import chimp.server.{ tool, McpServer, + McpServerHeaderHttpTests, McpServerInputRequiredHttpTests, McpServerStreamingTests, McpServerSubscriptionHttpTests, @@ -41,6 +42,7 @@ class OxMcpServerHttpSpec with McpServerStreamingTests[Identity] with McpServerSubscriptionHttpTests[Identity] with McpServerInputRequiredHttpTests[Identity] + with McpServerHeaderHttpTests[Identity] with SecuredMcpServerTests[Identity] with SecuredMcpServerStreamingTests[Identity] with SyncToFuture: @@ -64,6 +66,10 @@ class OxMcpServerHttpSpec withHttpServer(OxServerHttpTransport(List("mcp")).serve(server)): (port, _, _) => test(URI.create(s"http://localhost:$port/mcp")) + override protected def withHttpEndpoint(server: McpServer[Identity])(test: URI => Assertion): Future[Assertion] = + withHttpServer(server.endpoint(List("mcp"))): (port, _, _) => + test(URI.create(s"http://localhost:$port/mcp")) + override protected def withSecuredServer( server: SecuredMcpServer[Identity, String, String, User], token: String diff --git a/server-streaming/server-pekko/src/test/scala/chimp/server/pekko/PekkoMcpServerHttpSpec.scala b/server-streaming/server-pekko/src/test/scala/chimp/server/pekko/PekkoMcpServerHttpSpec.scala index 9ecf4080..141674e5 100644 --- a/server-streaming/server-pekko/src/test/scala/chimp/server/pekko/PekkoMcpServerHttpSpec.scala +++ b/server-streaming/server-pekko/src/test/scala/chimp/server/pekko/PekkoMcpServerHttpSpec.scala @@ -6,6 +6,7 @@ import chimp.protocol.{Implementation, ProtocolVersion} import chimp.server.transport.SecuredServerStreamingHttpTransport import chimp.server.{ McpServer, + McpServerHeaderHttpTests, McpServerInputRequiredHttpTests, McpServerStreamingTests, McpServerSubscriptionHttpTests, @@ -35,6 +36,7 @@ class PekkoMcpServerHttpSpec with McpServerStreamingTests[Future] with McpServerSubscriptionHttpTests[Future] with McpServerInputRequiredHttpTests[Future] + with McpServerHeaderHttpTests[Future] with SecuredMcpServerTests[Future] with SecuredMcpServerStreamingTests[Future] with PekkoToFuture: @@ -51,10 +53,16 @@ class PekkoMcpServerHttpSpec McpClient.bidirectional(transport, clientInfo).flatMap(test) override protected def withStreamingHttpEndpoint(server: StreamingMcpServer[Future])(test: URI => Assertion): Future[Assertion] = + withEndpointUri(PekkoServerHttpTransport(List("mcp")).serve(server))(test) + + override protected def withHttpEndpoint(server: McpServer[Future])(test: URI => Assertion): Future[Assertion] = + withEndpointUri(server.endpoint(List("mcp")))(test) + + private def withEndpointUri(endpoint: ServerEndpoint[PekkoStreams & WebSockets, Future])(test: URI => Assertion): Future[Assertion] = given ExecutionContext = actorSystem.dispatcher Http() .newServerAt("localhost", 0) - .bind(PekkoHttpServerInterpreter().toRoute(PekkoServerHttpTransport(List("mcp")).serve(server))) + .bind(PekkoHttpServerInterpreter().toRoute(endpoint)) .flatMap: binding => Future(blocking(test(URI.create(s"http://localhost:${binding.localAddress.getPort}/mcp")))) .transformWith(result => binding.terminate(5.seconds).transform(_ => result)) diff --git a/server-streaming/server-zio/src/test/scala/chimp/server/zio/ZioMcpServerHttpSpec.scala b/server-streaming/server-zio/src/test/scala/chimp/server/zio/ZioMcpServerHttpSpec.scala index b35b8460..d369e38c 100644 --- a/server-streaming/server-zio/src/test/scala/chimp/server/zio/ZioMcpServerHttpSpec.scala +++ b/server-streaming/server-zio/src/test/scala/chimp/server/zio/ZioMcpServerHttpSpec.scala @@ -7,6 +7,7 @@ import chimp.protocol.{Implementation, ProtocolVersion} import chimp.server.transport.SecuredServerStreamingHttpTransport import chimp.server.{ McpServer, + McpServerHeaderHttpTests, McpServerInputRequiredHttpTests, McpServerStreamingTests, McpServerSubscriptionHttpTests, @@ -36,6 +37,7 @@ class ZioMcpServerHttpSpec with McpServerStreamingTests[Task] with McpServerSubscriptionHttpTests[Task] with McpServerInputRequiredHttpTests[Task] + with McpServerHeaderHttpTests[Task] with SecuredMcpServerTests[Task] with SecuredMcpServerStreamingTests[Task] with ZioToFuture: @@ -52,8 +54,14 @@ class ZioMcpServerHttpSpec McpClient.bidirectional(transport, clientInfo, protocolVersion = clientProtocolVersion).flatMap(test) override protected def withStreamingHttpEndpoint(server: StreamingMcpServer[Task])(test: URI => Assertion): Future[Assertion] = + withEndpointUri(ZioServerHttpTransport(List("mcp")).serve(server))(test) + + override protected def withHttpEndpoint(server: McpServer[Task])(test: URI => Assertion): Future[Assertion] = + withEndpointUri(server.endpoint(List("mcp")))(test) + + private def withEndpointUri(endpoint: ServerEndpoint[ZioStreams & WebSockets, Task])(test: URI => Assertion): Future[Assertion] = toFuture: - val routes = ZioHttpInterpreter().toHttp(ZioServerHttpTransport(List("mcp")).serve(server)) + val routes = ZioHttpInterpreter().toHttp(endpoint) (for port <- Server.install(routes) result <- ZIO.attemptBlocking(test(URI.create(s"http://localhost:$port/mcp"))) diff --git a/server/src/test/scala/chimp/server/McpServerHeaderHttpTests.scala b/server/src/test/scala/chimp/server/McpServerHeaderHttpTests.scala new file mode 100644 index 00000000..33ea2995 --- /dev/null +++ b/server/src/test/scala/chimp/server/McpServerHeaderHttpTests.scala @@ -0,0 +1,98 @@ +package chimp.server + +import chimp.protocol.* +import io.circe.syntax.* +import io.circe.{parser, Codec, Json} +import org.scalatest.Assertion +import org.scalatest.flatspec.AsyncFlatSpec +import org.scalatest.matchers.should.Matchers +import sttp.tapir.Schema + +import java.net.URI +import java.net.http.{HttpClient, HttpRequest, HttpResponse} +import scala.concurrent.Future + +/** Standard and `x-mcp-header` custom request headers of 2026-07-28 requests, on the plain and the streaming HTTP transports. */ +trait McpServerHeaderHttpTests[F[_]] extends AsyncFlatSpec with Matchers: + this: ToFuture[F] => + + /** Serves `server` on a plain HTTP endpoint and runs the blocking `test` with the endpoint's URI. */ + protected def withHttpEndpoint(server: McpServer[F])(test: URI => Assertion): Future[Assertion] + + /** Serves `server` on a streaming HTTP endpoint and runs the blocking `test` with the endpoint's URI. */ + protected def withStreamingHttpEndpoint(server: StreamingMcpServer[F])(test: URI => Assertion): Future[Assertion] + + private case class RegionInput(region: String, limit: Option[Int]) derives Codec, Schema + + private val headerServer: McpServer[F] = + McpServer[F]().addTool( + tool("region") + .input[RegionInput] + .withMcpHeader("region", "Region") + .withMcpHeader("limit", "Limit") + .serverLogic[F]((in, _) => monad.unit(ToolResult.text(s"region ${in.region}"))) + ) + + private val httpClient = HttpClient.newBuilder().version(HttpClient.Version.HTTP_1_1).build() + + private def post(uri: URI, method: String, params: Json, headers: (String, String)*): HttpResponse[String] = + val meta = Json.obj(ProtocolMeta.ProtocolVersionKey -> "2026-07-28".asJson, ProtocolMeta.ClientCapabilities -> Json.obj()) + val body = Json.obj( + "jsonrpc" -> "2.0".asJson, + "id" -> 1.asJson, + "method" -> method.asJson, + "params" -> params.deepMerge(Json.obj("_meta" -> meta)) + ) + val request = headers + .foldLeft(HttpRequest.newBuilder(uri))((builder, header) => builder.header(header._1, header._2)) + .header("Content-Type", "application/json") + .header("Accept", "application/json, text/event-stream") + .header(ProtocolMeta.ProtocolVersionHeader, "2026-07-28") + .header("Mcp-Method", method) + .POST(HttpRequest.BodyPublishers.ofString(body.noSpaces)) + .build() + httpClient.send(request, HttpResponse.BodyHandlers.ofString()) + + private def callRegion(uri: URI, arguments: Json, headers: (String, String)*): HttpResponse[String] = + post(uri, "tools/call", Json.obj("name" -> "region".asJson, "arguments" -> arguments), ("Mcp-Name" -> "region") +: headers*) + + private def shouldBeServed(response: HttpResponse[String], text: String): Assertion = + response.statusCode() shouldBe 200 + response.body() should include(text) + response.body() should not include "\"error\"" + + private def shouldBeHeaderMismatch(response: HttpResponse[String]): Assertion = + response.statusCode() shouldBe 400 + response.headers().firstValue("Content-Type").orElse("") should startWith("application/json") + parser.parse(response.body()).flatMap(_.hcursor.downField("error").get[Int]("code")) shouldBe Right( + JSONRPCErrorCodes.HeaderMismatch.code + ) + + private def headerTests(transport: String, serve: McpServer[F] => (URI => Assertion) => Future[Assertion]): Unit = + it should s"list the x-mcp-header annotations in the input schema ($transport)" in: + serve(headerServer): uri => + val response = post(uri, "tools/list", Json.obj()) + response.statusCode() shouldBe 200 + response.body() should include("\"x-mcp-header\":\"Region\"") + + it should s"serve a tools/call whose Mcp-Param headers match the arguments, decoding Base64 ($transport)" in: + serve(headerServer): uri => + val arguments = Json.obj("region" -> "Hello".asJson, "limit" -> 42.asJson) + shouldBeServed(callRegion(uri, arguments, "Mcp-Param-Region" -> "=?base64?SGVsbG8=?=", "mcp-param-limit" -> "42.0"), "region Hello") + + it should s"reject a tools/call with a missing, malformed or mismatched Mcp-Param header with -32020 and HTTP 400 ($transport)" in: + serve(headerServer): uri => + val arguments = Json.obj("region" -> "Hello".asJson) + shouldBeHeaderMismatch(callRegion(uri, arguments)) + shouldBeHeaderMismatch(callRegion(uri, arguments, "Mcp-Param-Region" -> "=?base64?SGVsbG8?=")) + shouldBeHeaderMismatch(callRegion(uri, arguments, "Mcp-Param-Region" -> "Bye")) + + it should s"reject a tools/call whose Base64 Mcp-Name does not match the body with -32020 and HTTP 400 ($transport)" in: + serve(headerServer): uri => + val params = Json.obj("name" -> "region".asJson, "arguments" -> Json.obj("region" -> "eu".asJson)) + shouldBeServed(post(uri, "tools/call", params, "Mcp-Name" -> "=?base64?cmVnaW9u?=", "Mcp-Param-Region" -> "eu"), "region eu") + shouldBeHeaderMismatch(post(uri, "tools/call", params, "Mcp-Name" -> "=?base64?b3RoZXI=?=", "Mcp-Param-Region" -> "eu")) + + behavior of "an HTTP server checking request headers" + headerTests("plain", server => withHttpEndpoint(server)) + headerTests("streaming", server => withStreamingHttpEndpoint(server.streaming)) From 38197cbdb6d8ba21350885ce538c8a7e9dac2cb5 Mon Sep 17 00:00:00 2001 From: Ondra Pelech Date: Thu, 19 Nov 2026 18:43:38 +0100 Subject: [PATCH 26/31] feat(T13): offer an x-mcp-header tool on the conformance server The http-custom-header-server-validation scenario needs a tool with a string property marked x-mcp-header. With test_custom_header it passes (10/10), so its entry leaves the 2026-07-28 baseline. --- conformance-baseline-2026-07-28.yml | 2 -- .../src/main/scala/chimp/conformance/server/Main.scala | 10 +++++++++- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/conformance-baseline-2026-07-28.yml b/conformance-baseline-2026-07-28.yml index 5c9a2f8a..8d9c6775 100644 --- a/conformance-baseline-2026-07-28.yml +++ b/conformance-baseline-2026-07-28.yml @@ -12,8 +12,6 @@ server: - tasks-request-state-removal - tasks-required-task-error - tasks-wire-fields - # x-mcp-header custom headers in the tool DSL — T13, https://github.com/softwaremill/chimp/issues/251 - - http-custom-header-server-validation # the harness records a failure in a non-primary run of these scenarios (the primary run passes) - sep-2164-resource-not-found client: diff --git a/server-conformance/src/main/scala/chimp/conformance/server/Main.scala b/server-conformance/src/main/scala/chimp/conformance/server/Main.scala index 8b8798a0..ee27c071 100644 --- a/server-conformance/src/main/scala/chimp/conformance/server/Main.scala +++ b/server-conformance/src/main/scala/chimp/conformance/server/Main.scala @@ -18,6 +18,7 @@ object Main: private case class AddNumbersInput(a: Double, b: Double) derives Codec, Schema private case class NoInput() derives Codec, Schema + private case class RegionInput(region: String) derives Codec, Schema private def base64Resource(path: String): String = val stream = getClass.getResourceAsStream(path) @@ -106,6 +107,12 @@ object Main: |}""".stripMargin ).toOption.get + private val customHeaderTool = tool("test_custom_header") + .description("Mirrors its region argument into the Mcp-Param-Region header") + .input[RegionInput] + .withMcpHeader("region", "Region") + .handle(in => ToolResult.text(s"region: ${in.region}")) + private val jsonSchemaTool = tool("json_schema_2020_12_tool") .description("Advertises a JSON Schema 2020-12 input schema") .inputJson(jsonSchema2020) @@ -356,7 +363,8 @@ object Main: requestStateTool, tamperedStateTool, triggerToolChange, - triggerPromptChange + triggerPromptChange, + customHeaderTool ) .addResources(staticText, staticBinary) .addResourceTemplate(dataTemplate) From 249020e096d913c8349b7058906458a335d6fad1 Mon Sep 17 00:00:00 2001 From: Ondra Pelech Date: Thu, 19 Nov 2026 18:44:33 +0100 Subject: [PATCH 27/31] docs(T13): document x-mcp-header and the request header checks tools.md shows how to mark an input property with withMcpHeader, the constraints the builder enforces, and a warning not to mark sensitive parameters. capabilities.md (the protocol version page) adds the Mcp-Param rules, the Base64 sentinel decoding and the -32020 row. --- docs/server/capabilities.md | 11 +++++++++++ docs/server/tools.md | 33 +++++++++++++++++++++++++++++++++ 2 files changed, 44 insertions(+) diff --git a/docs/server/capabilities.md b/docs/server/capabilities.md index ec6df093..27f6b7f7 100644 --- a/docs/server/capabilities.md +++ b/docs/server/capabilities.md @@ -44,12 +44,23 @@ A request is **modern** when its `_meta` or its `MCP-Protocol-Version` header de | `_meta` has no `protocolVersion` or no `clientCapabilities` | `-32602` InvalidParams | `400` | | the `MCP-Protocol-Version` header is missing (HTTP only), or it and `_meta` declare different versions | `-32020` HeaderMismatch | `400` | | `Mcp-Method` / `Mcp-Name` header missing or different from the body (HTTP only) | `-32020` HeaderMismatch | `400` | +| `tools/call` with an `Mcp-Param-{name}` header missing, malformed or different from its argument (HTTP only) | `-32020` HeaderMismatch | `400` | | removed method (`initialize`, `ping`, `logging/setLevel`, `resources/subscribe`, `resources/unsubscribe`) or unknown method | `-32601` MethodNotFound | `404` | | `subscriptions/listen` on a server without a publisher, or on the sync HTTP transport | `-32601` MethodNotFound | `404` | | `tools/call` of a tool whose required client capabilities `_meta` does not declare | `-32021` MissingRequiredClientCapability | `400` | Over HTTP, a modern request must carry the SEP-2243 standard headers: `Mcp-Method` with the body's `method`, and `Mcp-Name` with `params.name` on `tools/call` and `prompts/get`, or `params.uri` on `resources/read`. Header names are case-insensitive, values are case-sensitive, and surrounding whitespace is ignored. chimp's own client sends these headers and the `_meta` when you give it a modern protocol version — see [client transport](../client/transport.md). +A modern `tools/call` over HTTP must also carry an `Mcp-Param-{name}` header for each argument that the tool marks with [`x-mcp-header`](tools.md#mirroring-arguments-into-http-headers). The server compares each header with its argument: + +- An argument that is present needs its header. An argument that is `null` or absent needs no header, and a header for it is a mismatch. +- Integers are compared numerically, so `42.0` in the header equals `42` in the body. Booleans are `true` or `false`, and strings are compared literally. +- `Mcp-Param-*` headers that match no marked argument are ignored. + +`Mcp-Name` and `Mcp-Param-*` values can use the Base64 sentinel form `=?base64?{value}?=`, which carries the UTF-8 bytes of the value. The server decodes a value in this form before the comparison. A sentinel with invalid Base64 (bad padding, characters outside the alphabet) or invalid UTF-8, and a value with characters that are not visible ASCII, space or tab, are a `-32020`. A value without the complete wrapper is compared literally. + +Legacy requests and stdio get none of these header checks. + ## Request facts Each handler can read the facts of its request from `ctx.request`, a `RequestInfo`: diff --git a/docs/server/tools.md b/docs/server/tools.md index e1e69e5e..8f8bec97 100644 --- a/docs/server/tools.md +++ b/docs/server/tools.md @@ -55,3 +55,36 @@ The output type carries into the logic, which returns a `ToolResult[SumOutput]`; result with structured output but no content is also sent as serialized JSON text, as the spec recommends. A tool can also ask the client for input before it returns its result: see [asking the client for input](mrtr.md). + +## Mirroring arguments into HTTP headers + +A tool can mark an input property with [`x-mcp-header`](https://modelcontextprotocol.io/specification/2026-07-28/server/tools#x-mcp-header). A `2026-07-28` client on Streamable HTTP then also sends the argument in the `Mcp-Param-{name}` header, so that load balancers, proxies and gateways can route on it without reading the body. Use `withMcpHeader` with the property name, or with the chain of property names to a nested property: + +```scala mdoc:compile-only +import chimp.server.* +import io.circe.Codec +import sttp.tapir.* + +case class QueryInput(region: String, query: String) derives Codec, Schema + +val executeSql = tool("execute_sql") + .description("Executes SQL in a region") + .input[QueryInput] + .withMcpHeader("region", "Region") + .handle(in => ToolResult.text(s"Ran in ${in.region}: ${in.query}")) +``` + +The `inputSchema` of the tool then has `"x-mcp-header": "Region"` on the `region` property. `withMcpHeader` works the same for a raw JSON Schema given to `.inputJson(schema)`, and an `x-mcp-header` which is already in a raw JSON Schema is kept. + +The server checks the `Mcp-Param-*` headers against the arguments, and rejects a mismatch with `-32020` — see [protocol versions](capabilities.md#protocol-versions). + +The tool builder (`input`, `inputJson` and `withMcpHeader`) throws an `IllegalArgumentException` when an annotation breaks a constraint of the spec: + +- The header name is empty, is not an HTTP token (letters, digits and ``!#$%&'*+-.^_`|~``), or has control characters. +- Two properties of one tool use the same header name, ignoring case. +- The property type is not `string`, `integer` or `boolean`. A `number` property is not permitted. +- The property is not reachable from the schema root through `properties` keys only. For example, it is in `items`, in `anyOf`, or behind a `$ref`. A nested case class gets a `$ref` in a derived schema, so mark only the top-level fields of a derived schema, or use a raw JSON Schema. + +```{warning} +Do not mark sensitive parameters, such as passwords, tokens or personal data, with `x-mcp-header`. HTTP headers are often written to logs and are visible to every intermediary on the way to the server. +``` From b4336aabf2035251e5a98f05512f650819bd6fcb Mon Sep 17 00:00:00 2001 From: Ondra Pelech Date: Thu, 19 Nov 2026 20:51:05 +0100 Subject: [PATCH 28/31] feat(T10): stateless client lifecycle for 2026-07-28 The client now owns the protocol version: McpClient sets it on the transport through the new ClientTransport.setProtocolVersion, and the HTTP transports lose their protocolVersion parameter. A stateless request names its version in _meta, so the MCP-Protocol-Version header always equals it; legacy requests use the version from initialize. At 2026-07-28 the client: - sends server/discover instead of initialize, and reads serverInfo from _meta, a top-level field, or falls back to "unknown" - stamps protocol version, client info, client capabilities and the new logLevel option into every request's _meta - retries once on -32022 with the newest common stateless version and keeps it; with no common version it fails with McpUnsupportedProtocolVersionException naming both lists - treats a missing resultType as complete and fails on unknown and input_required results (no multi round-trip support yet) - offers discover() and protocolVersion, and rejects the operations the stateless wire removed (ping, setLoggingLevel, subscribe, unsubscribe, progress, roots list_changed) At a legacy version the logLevel option sends logging/setLevel once after initialize. HTTP transports return a JSON-RPC error in the body of an HTTP error response as the response, and the streaming ones open no GET stream at a stateless version. The conformance client handles request-metadata and json-schema-ref-no-deref; both, and json-schema-2020-12-preservation, leave the 2026-07-28 baseline. --- .../scala/chimp/conformance/client/Main.scala | 12 +- .../transport/ox/OxClientHttpTransport.scala | 33 +- .../pekko/PekkoClientHttpTransport.scala | 40 +- .../PekkoMcpClientHttpIntegrationSpec.scala | 3 +- .../zio/ZioClientHttpTransport.scala | 42 ++- .../zio/ZioMcpClientHttpIntegrationSpec.scala | 3 +- .../main/scala/chimp/client/McpClient.scala | 64 ++-- .../chimp/client/McpClientException.scala | 9 +- .../scala/chimp/client/McpClientImpl.scala | 342 +++++++++++------- .../transport/ClientHttpTransport.scala | 73 +++- .../client/transport/ClientTransport.scala | 8 +- .../chimp/client/CapabilityHandlerSpec.scala | 2 +- .../client/ClientHttpTransportSpec.scala | 33 ++ .../scala/chimp/client/McpClientSpec.scala | 38 +- .../chimp/client/McpClientStatelessSpec.scala | 222 ++++++++++++ conformance-baseline-2026-07-28.yml | 5 +- docs/client/protocol.md | 70 ++++ docs/client/transport.md | 9 +- docs/index.md | 1 + .../chimp/server/ox/OxMcpServerHttpSpec.scala | 17 +- .../server/pekko/PekkoMcpServerHttpSpec.scala | 8 +- .../server/zio/ZioMcpServerHttpSpec.scala | 9 +- .../server/McpServerStreamingTests.scala | 20 +- 23 files changed, 819 insertions(+), 244 deletions(-) create mode 100644 client/src/test/scala/chimp/client/McpClientStatelessSpec.scala create mode 100644 docs/client/protocol.md diff --git a/client-conformance/src/main/scala/chimp/conformance/client/Main.scala b/client-conformance/src/main/scala/chimp/conformance/client/Main.scala index 93003db5..8892cfc3 100644 --- a/client-conformance/src/main/scala/chimp/conformance/client/Main.scala +++ b/client-conformance/src/main/scala/chimp/conformance/client/Main.scala @@ -37,16 +37,22 @@ object Main: .getOrElse(ProtocolVersion.Latest) val backend = DefaultSyncBackend() - val transport = ClientHttpTransport[Identity](backend, serverUrl, protocolVersion) + val transport = ClientHttpTransport[Identity](backend, serverUrl) val rc: Int = try scenario match - case "initialize" => + case "initialize" | "request-metadata" => val client = McpClient[Identity](transport, clientInfo, protocolVersion) client.close() 0 + case "json-schema-ref-no-deref" => + val client = McpClient[Identity](transport, clientInfo, protocolVersion) + val _ = client.listTools() + client.close() + 0 + case "tools_call" => val client = McpClient[Identity](transport, clientInfo, protocolVersion) val _ = client.callTool( @@ -66,7 +72,7 @@ object Main: case "elicitation-sep1034-client-defaults" => supervised: - val oxTransport = OxClientHttpTransport(backend, serverUrl, protocolVersion) + val oxTransport = OxClientHttpTransport(backend, serverUrl) val handler = (req: ElicitRequest) => val requestedSchema = req.params match case ElicitParams.Form(_, schema, _, _) => schema diff --git a/client-streaming/client-ox/src/main/scala/chimp/client/transport/ox/OxClientHttpTransport.scala b/client-streaming/client-ox/src/main/scala/chimp/client/transport/ox/OxClientHttpTransport.scala index 7ad6fe88..51aae35b 100644 --- a/client-streaming/client-ox/src/main/scala/chimp/client/transport/ox/OxClientHttpTransport.scala +++ b/client-streaming/client-ox/src/main/scala/chimp/client/transport/ox/OxClientHttpTransport.scala @@ -18,13 +18,13 @@ import sttp.shared.Identity import java.io.{BufferedReader, InputStream, InputStreamReader} import java.nio.charset.StandardCharsets +import java.util.concurrent.atomic.AtomicReference import java.util.concurrent.{ConcurrentHashMap, CountDownLatch} import scala.concurrent.duration.{FiniteDuration, *} final class OxClientHttpTransport private ( backend: SyncBackend, uri: Uri, - protocolVersion: ProtocolVersion, timeout: FiniteDuration, headers: Seq[Header], pending: SyncPendingRequests, @@ -53,9 +53,12 @@ final class OxClientHttpTransport private ( id private val state: ActorRef[State] = Actor.create(new State) + private val protocolVersion = AtomicReference(ClientHttpTransport.DefaultProtocolVersion) given monad: MonadError[Identity] = IdentityMonad + override def setProtocolVersion(version: ProtocolVersion): Identity[Unit] = protocolVersion.set(version) + override def send(msg: JSONRPCMessage): Identity[Option[JSONRPCMessage]] = if state.ask(_.closing) then throw McpTransportException("HTTP transport is closed") msg match @@ -75,7 +78,7 @@ final class OxClientHttpTransport private ( case Some(id) => try drainBody( - ClientHttpTransport.baseDeleteRequest(uri, protocolVersion, id, headers).response(asInputStreamUnsafe).send(backend) + ClientHttpTransport.baseDeleteRequest(uri, protocolVersion.get(), id, headers).response(asInputStreamUnsafe).send(backend) ) catch case _: Exception => () case None => () @@ -90,6 +93,10 @@ final class OxClientHttpTransport private ( case Right(HttpOutcome.NoBody) => drainBody(response) throw McpProtocolException("Server returned 202 Accepted for a Request") + case Right(HttpOutcome.ErrorBody(status)) => + ClientHttpTransport.errorResponse(request, status, collectAnyBody(response)) match + case Right(error) => Some(error) + case Left(err) => throw err case Right(HttpOutcome.JsonBody) => val message = decode(collectBody(response)) routeMessage(message) @@ -107,14 +114,18 @@ final class OxClientHttpTransport private ( case Left(err) => throw err case Right(HttpOutcome.NoBody) => drainBody(response); None case Right(HttpOutcome.JsonBody) => drainBody(response); None - case Right(HttpOutcome.SseBody) => + case Right(HttpOutcome.ErrorBody(status)) => + ClientHttpTransport.errorResponse(msg, status, collectAnyBody(response)) match + case Right(_) => None + case Left(err) => throw err + case Right(HttpOutcome.SseBody) => response.body match case Right(stream) => forkSseDrain(stream, None); None case Left(_) => None private def post(msg: JSONRPCMessage): Response[Either[String, InputStream]] = ClientHttpTransport - .basePostRequest(uri, protocolVersion, state.ask(_.sessionId), msg, headers) + .basePostRequest(uri, protocolVersion.get(), state.ask(_.sessionId), msg, headers) .response(asInputStreamUnsafe) .send(backend) @@ -129,6 +140,13 @@ final class OxClientHttpTransport private ( finally closeQuietly(stream) case Left(err) => throw McpProtocolException(s"HTTP 200 with non-stream body: $err") + private def collectAnyBody(response: Response[Either[String, InputStream]]): String = + response.body match + case Right(stream) => + try String(stream.readAllBytes(), StandardCharsets.UTF_8) + finally closeQuietly(stream) + case Left(body) => body + private def drainBody(response: Response[Either[String, InputStream]]): Unit = response.body match case Right(stream) => @@ -162,6 +180,9 @@ final class OxClientHttpTransport private ( private def getListenerLoop(): Unit = sessionReady.await() + if !protocolVersion.get().isModern then getListenerRetries() + + private def getListenerRetries(): Unit = val onFailure: (Int, Either[Throwable, Unit]) => Unit = (_, result) => result match case Left(t) => if !state.ask(_.closing) then log.warn(s"GET SSE listener error: ${t.getMessage}") @@ -175,7 +196,7 @@ final class OxClientHttpTransport private ( private def openGetSseStream(lastEvent: Option[String]): Option[InputStream] = val response = ClientHttpTransport - .baseGetRequest(uri, protocolVersion, state.ask(_.sessionId), lastEvent, headers) + .baseGetRequest(uri, protocolVersion.get(), state.ask(_.sessionId), lastEvent, headers) .response(asInputStreamUnsafe) .send(backend) response.code match @@ -237,14 +258,12 @@ object OxClientHttpTransport: def apply( backend: SyncBackend, uri: Uri, - protocolVersion: ProtocolVersion = ProtocolVersion.LatestLegacy, timeout: FiniteDuration = ClientTransport.defaultTimeout, headers: Seq[Header] = Nil )(using Ox): OxClientHttpTransport = val transport = new OxClientHttpTransport( backend, uri, - protocolVersion, timeout, headers, SyncPendingRequests(), diff --git a/client-streaming/client-pekko/src/main/scala/chimp/client/transport/pekko/PekkoClientHttpTransport.scala b/client-streaming/client-pekko/src/main/scala/chimp/client/transport/pekko/PekkoClientHttpTransport.scala index 755c051f..a61d7ee9 100644 --- a/client-streaming/client-pekko/src/main/scala/chimp/client/transport/pekko/PekkoClientHttpTransport.scala +++ b/client-streaming/client-pekko/src/main/scala/chimp/client/transport/pekko/PekkoClientHttpTransport.scala @@ -17,6 +17,7 @@ import sttp.model.sse.ServerSentEvent import sttp.model.{Header, StatusCode, Uri} import sttp.monad.MonadError +import java.util.concurrent.atomic.AtomicReference import scala.concurrent.duration.{DurationInt, FiniteDuration} import scala.concurrent.{ExecutionContext, Future, Promise} import scala.util.Success @@ -25,7 +26,6 @@ import scala.util.control.NonFatal final class PekkoClientHttpTransport private ( backend: StreamBackend[Future, PekkoStreams], uri: Uri, - protocolVersion: ProtocolVersion, timeout: FiniteDuration, headers: Seq[Header], reconnectSettings: RestartSettings, @@ -37,6 +37,10 @@ final class PekkoClientHttpTransport private ( private given ExecutionContext = mat.executionContext + private val protocolVersion = AtomicReference(ClientHttpTransport.DefaultProtocolVersion) + + override def setProtocolVersion(version: ProtocolVersion): Future[Unit] = Future.successful(protocolVersion.set(version)) + private final class State: var sessionId: Option[String] = None var incoming: JSONRPCMessage => Future[Unit] = _ => Future.unit @@ -132,7 +136,7 @@ final class PekkoClientHttpTransport private ( private def deleteSession(id: String): Future[Unit] = ClientHttpTransport - .baseDeleteRequest(uri, protocolVersion, id, headers) + .baseDeleteRequest(uri, protocolVersion.get(), id, headers) .response(asStreamUnsafe(PekkoStreams)) .send(backend) .flatMap(drainBody) @@ -149,6 +153,10 @@ final class PekkoClientHttpTransport private ( Future.failed(err) case Right(HttpOutcome.NoBody) => drainBody(response).flatMap(_ => Future.failed(McpProtocolException("Server returned 202 Accepted for a Request"))) + case Right(HttpOutcome.ErrorBody(status)) => + collectAnyBody(response).flatMap(body => + Future.fromTry(ClientHttpTransport.errorResponse(request, status, body).toTry).map(Some(_)) + ) case Right(HttpOutcome.JsonBody) => for body <- collectBody(response) @@ -170,10 +178,14 @@ final class PekkoClientHttpTransport private ( case Left(err: McpSessionNotFoundException) => state.tell(_.sessionId = None) Future.failed(err) - case Left(err) => Future.failed(err) - case Right(HttpOutcome.NoBody) => drainBody(response).map(_ => None) - case Right(HttpOutcome.JsonBody) => drainBody(response).map(_ => None) - case Right(HttpOutcome.SseBody) => + case Left(err) => Future.failed(err) + case Right(HttpOutcome.NoBody) => drainBody(response).map(_ => None) + case Right(HttpOutcome.JsonBody) => drainBody(response).map(_ => None) + case Right(HttpOutcome.ErrorBody(status)) => + collectAnyBody(response).flatMap(body => + Future.fromTry(ClientHttpTransport.errorResponse(msg, status, body).toTry).map(_ => None) + ) + case Right(HttpOutcome.SseBody) => response.body match case Left(_) => Future.successful(None) case Right(stream) => @@ -185,7 +197,7 @@ final class PekkoClientHttpTransport private ( .ask(_.sessionId) .flatMap: session => ClientHttpTransport - .basePostRequest(uri, protocolVersion, session, msg, headers) + .basePostRequest(uri, protocolVersion.get(), session, msg, headers) .response(asStreamUnsafe(PekkoStreams)) .send(backend) @@ -201,6 +213,11 @@ final class PekkoClientHttpTransport private ( case Left(err) => Future.failed(McpProtocolException(s"HTTP 200 with non-stream body: $err")) case Right(stream) => stream.runFold(ByteString.empty)(_ ++ _).map(_.utf8String) + private def collectAnyBody(response: Response[Either[String, Source[ByteString, Any]]]): Future[String] = + response.body match + case Left(body) => Future.successful(body) + case Right(stream) => stream.runFold(ByteString.empty)(_ ++ _).map(_.utf8String) + private def drainBody(response: Response[Either[String, Source[ByteString, Any]]]): Future[Unit] = response.body match case Left(_) => Future.unit @@ -237,7 +254,8 @@ final class PekkoClientHttpTransport private ( val listener = sessionReady.future .flatMap(_ => state.ask(_.closing)) .flatMap: - case true => Future.unit + case true => Future.unit + case false if protocolVersion.get().isModern => Future.unit case false => state.ask(_.nextStream(None)).flatMap(stream => drainSse(stream, () => state.ask(!_.closing))) listener.failed.foreach(t => log.warn(s"GET SSE listener failed: ${t.getMessage}")) @@ -298,7 +316,7 @@ final class PekkoClientHttpTransport private ( .ask(_.sessionId) .flatMap: session => ClientHttpTransport - .baseGetRequest(uri, protocolVersion, session, lastEventId, headers) + .baseGetRequest(uri, protocolVersion.get(), session, lastEventId, headers) .response(asStreamUnsafe(PekkoStreams)) .send(backend) .flatMap: response => @@ -342,8 +360,6 @@ object PekkoClientHttpTransport: * The sttp backend used to send HTTP requests; must support Pekko streams. * @param uri * The MCP endpoint URI. - * @param protocolVersion - * Protocol version advertised via the `MCP-Protocol-Version` header; defaults to the latest version supported by chimp. * @param timeout * How long to wait for a response to a request sent to the server. * @param reconnectSettings @@ -354,7 +370,6 @@ object PekkoClientHttpTransport: def apply( backend: StreamBackend[Future, PekkoStreams], uri: Uri, - protocolVersion: ProtocolVersion = ProtocolVersion.LatestLegacy, timeout: FiniteDuration = ClientTransport.defaultTimeout, reconnectSettings: RestartSettings = defaultReconnectSettings, headers: Seq[Header] = Nil @@ -362,7 +377,6 @@ object PekkoClientHttpTransport: val transport = new PekkoClientHttpTransport( backend, uri, - protocolVersion, timeout, headers, reconnectSettings, diff --git a/client-streaming/client-pekko/src/test/scala/chimp/client/transport/pekko/PekkoMcpClientHttpIntegrationSpec.scala b/client-streaming/client-pekko/src/test/scala/chimp/client/transport/pekko/PekkoMcpClientHttpIntegrationSpec.scala index e17830e9..fdd65714 100644 --- a/client-streaming/client-pekko/src/test/scala/chimp/client/transport/pekko/PekkoMcpClientHttpIntegrationSpec.scala +++ b/client-streaming/client-pekko/src/test/scala/chimp/client/transport/pekko/PekkoMcpClientHttpIntegrationSpec.scala @@ -2,7 +2,6 @@ package chimp.client.transport.pekko import chimp.client.integration.McpClientStreamingHttpIntegrationSpec import chimp.client.transport.ClientBidirectionalTransport -import chimp.protocol.ProtocolVersion import sttp.capabilities.pekko.PekkoStreams import sttp.client4.StreamBackend import sttp.client4.pekkohttp.PekkoHttpBackend @@ -22,5 +21,5 @@ class PekkoMcpClientHttpIntegrationSpec override def usingBidirectionalTransport[A](b: StreamBackend[Future, PekkoStreams], uri: Uri, timeout: FiniteDuration)( use: ClientBidirectionalTransport[Future] => Future[A] ): Future[A] = - val transport = PekkoClientHttpTransport(b, uri, ProtocolVersion.LatestLegacy, timeout) + val transport = PekkoClientHttpTransport(b, uri, timeout) monad.ensure2(use(transport), transport.close()) diff --git a/client-streaming/client-zio/src/main/scala/chimp/client/transport/zio/ZioClientHttpTransport.scala b/client-streaming/client-zio/src/main/scala/chimp/client/transport/zio/ZioClientHttpTransport.scala index 022aef1a..4bef045d 100644 --- a/client-streaming/client-zio/src/main/scala/chimp/client/transport/zio/ZioClientHttpTransport.scala +++ b/client-streaming/client-zio/src/main/scala/chimp/client/transport/zio/ZioClientHttpTransport.scala @@ -18,7 +18,7 @@ import scala.concurrent.duration.FiniteDuration final class ZioClientHttpTransport private ( backend: StreamBackend[Task, ZioStreams], uri: Uri, - protocolVersion: ProtocolVersion, + protocolVersion: Ref[ProtocolVersion], timeout: FiniteDuration, headers: Seq[Header], reconnectSchedule: Schedule[Any, Any, Any], @@ -35,6 +35,8 @@ final class ZioClientHttpTransport private ( override given monad: MonadError[Task] = backend.monad + override def setProtocolVersion(version: ProtocolVersion): Task[Unit] = protocolVersion.set(version) + override def send(msg: JSONRPCMessage): Task[Option[JSONRPCMessage]] = msg match case request: JSONRPCMessage.Request => @@ -54,10 +56,12 @@ final class ZioClientHttpTransport private ( .getAndSet(None) .flatMap: case Some(id) => - ClientHttpTransport - .baseDeleteRequest(uri, protocolVersion, id, headers) - .response(asStreamUnsafe(ZioStreams)) - .send(backend) + protocolVersion.get + .flatMap: version => + ClientHttpTransport + .baseDeleteRequest(uri, version, id, headers) + .response(asStreamUnsafe(ZioStreams)) + .send(backend) .flatMap(drainBody) .ignore case None => ZIO.unit @@ -74,6 +78,8 @@ final class ZioClientHttpTransport private ( ZIO.fail(err) case Right(HttpOutcome.NoBody) => drainBody(resp) *> ZIO.fail(McpProtocolException("Server returned 202 Accepted for a Request")) + case Right(HttpOutcome.ErrorBody(status)) => + collectAnyBody(resp).flatMap(body => ZIO.fromEither(ClientHttpTransport.errorResponse(request, status, body)).map(Some(_))) case Right(HttpOutcome.JsonBody) => for body <- collectBody(resp) @@ -97,13 +103,15 @@ final class ZioClientHttpTransport private ( drainBody(response).as(None) case Right(HttpOutcome.JsonBody) => drainBody(response).as(None) + case Right(HttpOutcome.ErrorBody(status)) => + collectAnyBody(response).flatMap(body => ZIO.fromEither(ClientHttpTransport.errorResponse(msg, status, body)).as(None)) case Right(HttpOutcome.SseBody) => forkSseDrain(response, None).as(None) private def post(msg: JSONRPCMessage): Task[Response[Either[String, Stream[Throwable, Byte]]]] = - sessionRef.get.flatMap: session => + (sessionRef.get <*> protocolVersion.get).flatMap: (session, version) => ClientHttpTransport - .basePostRequest(uri, protocolVersion, session, msg, headers) + .basePostRequest(uri, version, session, msg, headers) .response(asStreamUnsafe(ZioStreams)) .send(backend) @@ -118,6 +126,11 @@ final class ZioClientHttpTransport private ( case Left(err) => ZIO.fail(McpProtocolException(s"HTTP 200 with non-stream body: $err")) case Right(stream) => stream.via(ZPipeline.utf8Decode).runCollect.map(_.mkString) + private def collectAnyBody(response: Response[Either[String, Stream[Throwable, Byte]]]): Task[String] = + response.body match + case Left(body) => ZIO.succeed(body) + case Right(stream) => stream.via(ZPipeline.utf8Decode).runCollect.map(_.mkString) + private def drainBody(response: Response[Either[String, Stream[Throwable, Byte]]]): Task[Unit] = response.body match case Left(_) => ZIO.unit @@ -179,9 +192,10 @@ final class ZioClientHttpTransport private ( closingRef.get.map(closing => if !closing then log.warn(message)) private[zio] def startGetSseListener: Task[Unit] = - val listener = sessionReady.await *> openGetSseStream(None).flatMap: + val listen = openGetSseStream(None).flatMap: case None => ZIO.unit case Some(stream) => streamWithResume(stream, lastEventId, closingRef.get.map(!_)) + val listener = sessionReady.await *> protocolVersion.get.flatMap(version => listen.unless(version.isModern).unit) listener.catchAll(t => warnUnlessClosing(s"GET listener failed: ${t.getMessage}")).forkIn(scope).unit private def streamWithResume( @@ -229,9 +243,9 @@ final class ZioClientHttpTransport private ( .runDrain private def openGetSseStream(lastEventId: Option[String]): Task[Option[Stream[Throwable, Byte]]] = - sessionRef.get.flatMap: session => + (sessionRef.get <*> protocolVersion.get).flatMap: (session, version) => ClientHttpTransport - .baseGetRequest(uri, protocolVersion, session, lastEventId, headers) + .baseGetRequest(uri, version, session, lastEventId, headers) .response(asStreamUnsafe(ZioStreams)) .send(backend) .flatMap: response => @@ -272,7 +286,6 @@ object ZioClientHttpTransport: def apply( backend: StreamBackend[Task, ZioStreams], uri: Uri, - protocolVersion: ProtocolVersion = ProtocolVersion.LatestLegacy, timeout: FiniteDuration = ClientTransport.defaultTimeout, reconnectSchedule: Schedule[Any, Any, Any] = defaultReconnectSchedule, headers: Seq[Header] = Nil @@ -285,6 +298,7 @@ object ZioClientHttpTransport: incomingRef <- Ref.make[JSONRPCMessage => Task[Unit]](_ => ZIO.unit) lastEventId <- Ref.make(Option.empty[String]) closingRef <- Ref.make(false) + protocolVersion <- Ref.make(ClientHttpTransport.DefaultProtocolVersion) transport = new ZioClientHttpTransport( backend, uri, @@ -306,19 +320,17 @@ object ZioClientHttpTransport: def scoped( backend: StreamBackend[Task, ZioStreams], uri: Uri, - protocolVersion: ProtocolVersion = ProtocolVersion.LatestLegacy, timeout: FiniteDuration = ClientTransport.defaultTimeout, reconnectSchedule: Schedule[Any, Any, Any] = defaultReconnectSchedule, headers: Seq[Header] = Nil ): ZIO[Scope, Throwable, ZioClientHttpTransport] = - ZIO.acquireRelease(apply(backend, uri, protocolVersion, timeout, reconnectSchedule, headers))(_.close().ignore) + ZIO.acquireRelease(apply(backend, uri, timeout, reconnectSchedule, headers))(_.close().ignore) def layer( backend: StreamBackend[Task, ZioStreams], uri: Uri, - protocolVersion: ProtocolVersion = ProtocolVersion.LatestLegacy, timeout: FiniteDuration = ClientTransport.defaultTimeout, reconnectSchedule: Schedule[Any, Any, Any] = defaultReconnectSchedule, headers: Seq[Header] = Nil ): ZLayer[Any, Throwable, ZioClientHttpTransport] = - ZLayer.scoped(scoped(backend, uri, protocolVersion, timeout, reconnectSchedule, headers)) + ZLayer.scoped(scoped(backend, uri, timeout, reconnectSchedule, headers)) diff --git a/client-streaming/client-zio/src/test/scala/chimp/client/transport/zio/ZioMcpClientHttpIntegrationSpec.scala b/client-streaming/client-zio/src/test/scala/chimp/client/transport/zio/ZioMcpClientHttpIntegrationSpec.scala index a2b09627..c4480ba5 100644 --- a/client-streaming/client-zio/src/test/scala/chimp/client/transport/zio/ZioMcpClientHttpIntegrationSpec.scala +++ b/client-streaming/client-zio/src/test/scala/chimp/client/transport/zio/ZioMcpClientHttpIntegrationSpec.scala @@ -2,7 +2,6 @@ package chimp.client.transport.zio import chimp.client.integration.McpClientStreamingHttpIntegrationSpec import chimp.client.transport.ClientBidirectionalTransport -import chimp.protocol.ProtocolVersion import sttp.capabilities.zio.ZioStreams import sttp.client4.StreamBackend import sttp.client4.httpclient.zio.HttpClientZioBackend @@ -20,4 +19,4 @@ class ZioMcpClientHttpIntegrationSpec extends McpClientStreamingHttpIntegrationS override def usingBidirectionalTransport[A](b: StreamBackend[Task, ZioStreams], uri: Uri, timeout: FiniteDuration)( use: ClientBidirectionalTransport[Task] => Task[A] ): Task[A] = - ZIO.scoped(ZioClientHttpTransport.scoped(b, uri, ProtocolVersion.LatestLegacy, timeout).flatMap(use)) + ZIO.scoped(ZioClientHttpTransport.scoped(b, uri, timeout).flatMap(use)) diff --git a/client/src/main/scala/chimp/client/McpClient.scala b/client/src/main/scala/chimp/client/McpClient.scala index 76b4cb32..abbe1d8c 100644 --- a/client/src/main/scala/chimp/client/McpClient.scala +++ b/client/src/main/scala/chimp/client/McpClient.scala @@ -5,7 +5,8 @@ import chimp.client.transport.{ClientBidirectionalTransport, ClientTransport} import chimp.protocol.* import io.circe.Json -/** A Model Context Protocol (MCP) client that has completed the initialization handshake with a server. +/** A Model Context Protocol (MCP) client that is connected to a server: at a legacy protocol version it has completed the `initialize` + * handshake, at a stateless version (2026-07-28) it has called `server/discover`. * * Exposes the server's advertised capabilities and identity, and provides methods for sending client-initiated requests and notifications * over the underlying [[chimp.client.transport.ClientTransport]]. @@ -14,16 +15,26 @@ import io.circe.Json * [[BidirectionalMcpClient]] instead. */ trait McpClient[F[_]]: - /** Sends a `ping` request to the server. */ + /** The protocol version that the client uses. At a stateless version it can change once, when the server rejects the version with + * `-32022` and the client retries with a version from the server's list. + */ + def protocolVersion: ProtocolVersion + + /** Sends `server/discover` and returns the server's versions, capabilities and instructions. Only at a stateless version. */ + def discover(): F[DiscoverResult] + + /** Sends a `ping` request to the server. Only at a legacy version. */ def ping(): F[Unit] /** Closes the underlying transport and releases any resources held by this client. */ def close(): F[Unit] - /** Capabilities advertised by the server during the initialization handshake. */ + /** Capabilities advertised by the server in the `initialize` or `server/discover` result. */ def serverCapabilities: ServerCapabilities - /** Server implementation name and version, received during the initialization handshake. */ + /** Server implementation name and version, from the `initialize` or `server/discover` result. If a stateless server does not send it, + * both values are `unknown`. + */ def serverInfo: Implementation /** Lists tools exposed by the server. @@ -78,10 +89,12 @@ trait McpClient[F[_]]: /** Requests completion suggestions for an argument of a prompt or resource template reference. */ def complete(ref: CompleteRef, argument: CompleteArgument): F[CompleteResult] - /** Sets the minimum severity level for log messages the server should forward to this client. */ + /** Sets the minimum severity level for log messages the server should forward to this client. Only at a legacy version; at a stateless + * version use the `logLevel` option of the client. + */ def setLoggingLevel(level: LoggingLevel): F[Unit] - /** Sends a progress notification for a previously issued request that advertised a progress token. + /** Sends a progress notification for a previously issued request that advertised a progress token. Only at a legacy version. * * @param token * The progress token associated with the in-flight request. @@ -100,45 +113,49 @@ trait McpClient[F[_]]: */ trait BidirectionalMcpClient[F[_]] extends McpClient[F]: /** Subscribes to updates for the resource identified by the given URI. The server will emit `resources/updated` notifications, which can - * be observed via [[onServerNotification]]. + * be observed via [[onServerNotification]]. Only at a legacy version. */ def subscribeResource(uri: String): F[Unit] - /** Cancels a subscription previously created with [[subscribeResource]]. */ + /** Cancels a subscription previously created with [[subscribeResource]]. Only at a legacy version. */ def unsubscribeResource(uri: String): F[Unit] - /** Notifies the server that the list of roots exposed by this client has changed. */ + /** Notifies the server that the list of roots exposed by this client has changed. Only at a legacy version. */ def sendRootsListChanged(): F[Unit] /** Registers a listener for notifications pushed by the server (e.g. resource updates, tool/prompt list changes, log messages). */ def onServerNotification(listener: ServerNotificationListener[F]): F[Unit] object McpClient: - /** Creates an unidirectional [[McpClient]] over the given [[chimp.client.transport.ClientTransport]] and performs the initialization - * handshake with the server. + /** Creates an unidirectional [[McpClient]] over the given [[chimp.client.transport.ClientTransport]] and connects it to the server. * * @param transport * The transport carrying JSON-RPC messages between client and server. * @param clientInfo - * Implementation name and version advertised to the server during initialization. + * Implementation name and version sent to the server. * @param protocolVersion - * Protocol version proposed during initialization; defaults to the latest version supported by chimp. + * The protocol version of the client; the client gives it to the transport. A legacy version runs the `initialize` handshake, a + * stateless version (2026-07-28) calls `server/discover`. Defaults to the latest legacy version. + * @param logLevel + * The minimum level of the log messages the server sends. At a stateless version every request carries it in `_meta`; at a legacy + * version the client sends `logging/setLevel` once after `initialize`. Without it the server sends no log messages. */ def apply[F[_]]( transport: ClientTransport[F], clientInfo: Implementation, - protocolVersion: ProtocolVersion = ProtocolVersion.LatestLegacy + protocolVersion: ProtocolVersion = ProtocolVersion.LatestLegacy, + logLevel: Option[LoggingLevel] = None ): F[McpClient[F]] = - McpClientImpl.create(transport, clientInfo, protocolVersion) + McpClientImpl.create(transport, clientInfo, protocolVersion, logLevel) - /** Creates a [[BidirectionalMcpClient]] over the given [[chimp.client.transport.ClientBidirectionalTransport]] and performs the - * initialization handshake. The optional handlers determine which client capabilities (roots, sampling, elicitation) are advertised to - * the server; only capabilities backed by a handler are enabled. + /** Creates a [[BidirectionalMcpClient]] over the given [[chimp.client.transport.ClientBidirectionalTransport]] and connects it to the + * server. The optional handlers determine which client capabilities (roots, sampling, elicitation) are advertised to the server; only + * capabilities backed by a handler are enabled. * * @param transport * The bidirectional transport carrying JSON-RPC messages in both directions. * @param clientInfo - * Implementation name and version advertised to the server during initialization. + * Implementation name and version sent to the server. * @param rootsHandler * Optional handler invoked when the server requests the client's roots; enables the `roots` capability when provided. * @param samplingHandler @@ -146,7 +163,9 @@ object McpClient: * @param elicitationHandler * Optional handler invoked when the server requests user input via elicitation; enables the `elicitation` capability when provided. * @param protocolVersion - * Protocol version proposed during initialization; defaults to the latest version supported by chimp. + * The protocol version of the client, see [[apply]]. + * @param logLevel + * The minimum level of the log messages the server sends, see [[apply]]. */ def bidirectional[F[_]]( transport: ClientBidirectionalTransport[F], @@ -154,6 +173,7 @@ object McpClient: rootsHandler: Option[() => F[ListRootsResult]] = None, samplingHandler: Option[CreateMessageRequest => F[CreateMessageResult]] = None, elicitationHandler: Option[ElicitRequest => F[ElicitResult]] = None, - protocolVersion: ProtocolVersion = ProtocolVersion.LatestLegacy + protocolVersion: ProtocolVersion = ProtocolVersion.LatestLegacy, + logLevel: Option[LoggingLevel] = None ): F[BidirectionalMcpClient[F]] = - McpClientImpl.createBidirectional(transport, clientInfo, protocolVersion, rootsHandler, samplingHandler, elicitationHandler) + McpClientImpl.createBidirectional(transport, clientInfo, protocolVersion, logLevel, rootsHandler, samplingHandler, elicitationHandler) diff --git a/client/src/main/scala/chimp/client/McpClientException.scala b/client/src/main/scala/chimp/client/McpClientException.scala index 961d877d..cbbdf93e 100644 --- a/client/src/main/scala/chimp/client/McpClientException.scala +++ b/client/src/main/scala/chimp/client/McpClientException.scala @@ -9,6 +9,13 @@ final class McpAuthorizationException(message: String, val statusCode: Int) exte final class McpSessionNotFoundException(sessionId: String) extends McpTransportException(s"Server reported session-id $sessionId as not found") -final class McpProtocolException(message: String) extends McpTransportException(message) +class McpProtocolException(message: String) extends McpTransportException(message) + +/** The server and chimp share no protocol version. Both version lists are part of the message. */ +final class McpUnsupportedProtocolVersionException(val serverVersions: List[String], val clientVersions: List[String]) + extends McpProtocolException( + s"The server and the client share no protocol version: the server supports ${serverVersions.mkString(", ")}, " + + s"the client supports ${clientVersions.mkString(", ")}" + ) final class McpTimeoutException(requestId: RequestId) extends RuntimeException(s"Request $requestId timed out") diff --git a/client/src/main/scala/chimp/client/McpClientImpl.scala b/client/src/main/scala/chimp/client/McpClientImpl.scala index ccc4aee6..150a8c6d 100644 --- a/client/src/main/scala/chimp/client/McpClientImpl.scala +++ b/client/src/main/scala/chimp/client/McpClientImpl.scala @@ -16,17 +16,18 @@ object McpClientImpl: transport: ClientTransport[F], clientInfo: Implementation, protocolVersion: ProtocolVersion, + logLevel: Option[LoggingLevel], correlator: Correlator = UUIDCorrelator() ): F[McpClient[F]] = given MonadError[F] = transport.monad - val clientCapabilities = ClientCapabilities() - connect(transport, clientInfo, protocolVersion, clientCapabilities, correlator).map: server => - new Impl[F](transport, clientInfo, protocolVersion, clientCapabilities, correlator, server) + val requests = Requests(transport, clientInfo, ClientCapabilities(), logLevel, correlator, protocolVersion) + connect(requests).map(server => new Impl[F](transport, requests, server)) def createBidirectional[F[_]]( transport: ClientBidirectionalTransport[F], clientInfo: Implementation, protocolVersion: ProtocolVersion, + logLevel: Option[LoggingLevel], rootsHandler: Option[() => F[ListRootsResult]], samplingHandler: Option[CreateMessageRequest => F[CreateMessageResult]], elicitationHandler: Option[ElicitRequest => F[ElicitResult]], @@ -38,6 +39,7 @@ object McpClientImpl: sampling = samplingHandler.map(_ => Json.obj()), elicitation = elicitationHandler.map(_ => Json.obj()) ) + val requests = Requests(transport, clientInfo, clientCapabilities, logLevel, correlator, protocolVersion) val serverNotificationListeners = AtomicReference[List[ServerNotificationListener[F]]](Nil) val serverInitiatedRequestHandlers = buildServerInitiatedRequestHandlers(rootsHandler, samplingHandler, elicitationHandler) val incomingHandler = buildIncomingHandler(transport, serverInitiatedRequestHandlers, serverNotificationListeners) @@ -45,106 +47,175 @@ object McpClientImpl: transport .onIncoming(incomingHandler) .flatMap: _ => - connect(transport, clientInfo, protocolVersion, clientCapabilities, correlator).map: server => - new BidirectionalImpl[F]( - transport, - clientInfo, - protocolVersion, - clientCapabilities, - correlator, - server, - serverNotificationListeners - ) + connect(requests).map: server => + new BidirectionalImpl[F](transport, requests, server, serverNotificationListeners) /** What the client learns about the server when it connects. */ private final case class ConnectedServer(capabilities: ServerCapabilities, serverInfo: Implementation) - /** Legacy versions run the `initialize` handshake; a modern (2026-07-28) version has no handshake and asks `server/discover` instead. */ - private def connect[F[_]]( - transport: ClientTransport[F], - clientInfo: Implementation, - protocolVersion: ProtocolVersion, - clientCapabilities: ClientCapabilities, - correlator: Correlator - ): F[ConnectedServer] = - given MonadError[F] = transport.monad - if protocolVersion.isModern then - discover(transport, requestMeta(protocolVersion, clientInfo, clientCapabilities), protocolVersion, correlator) - else - initialize(transport, clientInfo, protocolVersion, clientCapabilities, correlator).map(result => - ConnectedServer(result.capabilities, result.serverInfo) + /** Legacy versions run the `initialize` handshake; a stateless (2026-07-28) version has no handshake and asks `server/discover`. */ + private def connect[F[_]](requests: Requests[F]): F[ConnectedServer] = + given MonadError[F] = requests.monad + requests.transport + .setProtocolVersion(requests.protocolVersion) + .flatMap: _ => + if requests.protocolVersion.isModern then discoverServer(requests) + else initialize(requests) + + /** A discover result that does not list the client's version switches to the newest common stateless version, or fails. */ + private def discoverServer[F[_]](requests: Requests[F]): F[ConnectedServer] = + given monad: MonadError[F] = requests.monad + requests + .discover() + .flatMap: discovered => + val supported = discovered.result.supportedVersions + if supported.contains(requests.protocolVersion.name) then monad.unit(discovered.server) + else + retryVersion(supported) match + case Some(next) => requests.useVersion(next).flatMap(_ => requests.discover()).map(_.server) + case None => monad.error(McpUnsupportedProtocolVersionException(supported, statelessVersions)) + + /** Sends requests and turns their responses into results. On the stateless wire it stamps `_meta` on every request, and on `-32022` it + * retries once with a version that both sides support. + */ + private final class Requests[F[_]]( + val transport: ClientTransport[F], + val clientInfo: Implementation, + val clientCapabilities: ClientCapabilities, + val logLevel: Option[LoggingLevel], + correlator: Correlator, + initialVersion: ProtocolVersion + ): + given monad: MonadError[F] = transport.monad + + private val version = AtomicReference(initialVersion) + + def protocolVersion: ProtocolVersion = version.get() + + def useVersion(next: ProtocolVersion): F[Unit] = + monad.eval(version.set(next)).flatMap(_ => transport.setProtocolVersion(next)) + + def nextId(): RequestId = correlator.nextId() + + def send[R: Decoder](method: String, params: Option[Json]): F[R] = + sendForResult(method, params).flatMap(decode[R](method, _)) + + def discover(): F[Discovered] = + sendForResult("server/discover", None).flatMap: result => + decode[DiscoverResult]("server/discover", result).map(discovered => Discovered(discovered, serverInfoOf(result, discovered))) + + def notify(method: String, params: Option[Json]): F[Unit] = + transport.send(JSONRPCMessage.Notification(method = method, params = params)).map(_ => ()) + + private def sendForResult(method: String, params: Option[Json]): F[Json] = + val sentWith = protocolVersion + attempt(method, params, sentWith).flatMap: + case Right(result) => monad.unit(result) + case Left(supported) => + retryVersion(supported) match + case None => monad.error(McpUnsupportedProtocolVersionException(supported, statelessVersions)) + case Some(next) => + useVersion(next) + .flatMap(_ => attempt(method, params, next)) + .flatMap: + case Right(result) => monad.unit(result) + case Left(supported) => monad.error(McpUnsupportedProtocolVersionException(supported, statelessVersions)) + + /** `Left` holds the versions a `-32022` error names. */ + private def attempt(method: String, params: Option[Json], sentWith: ProtocolVersion): F[Either[List[String], Json]] = + val request = JSONRPCMessage.Request(method = method, params = stamp(params, sentWith), id = nextId()) + transport + .send(request) + .flatMap: + case Some(JSONRPCMessage.Response(_, _, result)) => + checkResultType(method, result).map(Right(_)) + case Some(JSONRPCMessage.Error(_, _, error)) + if sentWith.isModern && error.code == JSONRPCErrorCodes.UnsupportedProtocolVersion.code => + monad.unit(Left(error.data.flatMap(_.hcursor.get[List[String]]("supported").toOption).getOrElse(Nil))) + case Some(JSONRPCMessage.Error(_, _, error)) => + monad.error(McpProtocolException(s"$method failed: ${error.code} ${error.message}")) + case Some(other) => + monad.error(McpProtocolException(s"Unexpected response to $method: $other")) + case None => + monad.error(McpProtocolException(s"No response received for request $method")) + + private def stamp(params: Option[Json], sentWith: ProtocolVersion): Option[Json] = + if sentWith.isModern then Some(params.getOrElse(Json.obj()).deepMerge(Json.obj("_meta" -> requestMeta(sentWith)))) + else params + + /** The `_meta` that every stateless request carries in place of the `initialize` handshake. */ + private def requestMeta(sentWith: ProtocolVersion): Json = + Json.fromFields( + List( + ProtocolMeta.ProtocolVersionKey -> sentWith.name.asJson, + ProtocolMeta.ClientCapabilities -> clientCapabilities.asJson.deepDropNullValues, + ProtocolMeta.ClientInfo -> clientInfo.asJson.deepDropNullValues + ) ++ logLevel.map(level => ProtocolMeta.LogLevel -> level.asJson) ) - /** The `_meta` that every modern (2026-07-28) request carries in place of the `initialize` handshake. */ - private def requestMeta(protocolVersion: ProtocolVersion, clientInfo: Implementation, clientCapabilities: ClientCapabilities): Json = - Json.obj( - ProtocolMeta.ProtocolVersionKey -> protocolVersion.name.asJson, - ProtocolMeta.ClientCapabilities -> clientCapabilities.asJson.deepDropNullValues, - ProtocolMeta.ClientInfo -> clientInfo.asJson.deepDropNullValues - ) + private def checkResultType(method: String, result: Json): F[Json] = + result.hcursor.downField("resultType").focus match + case None => monad.unit(result) + case Some(resultType) if resultType.asString.contains(ResultType.Complete.name) => monad.unit(result) + case Some(resultType) if resultType.asString.contains(ResultType.InputRequired.name) => + monad.error( + McpProtocolException(s"$method returned an input_required result; the client does not support multi round-trip requests yet") + ) + case Some(resultType) => monad.error(McpProtocolException(s"$method returned an unknown resultType: ${resultType.noSpaces}")) - private def discover[F[_]]( - transport: ClientTransport[F], - meta: Json, - protocolVersion: ProtocolVersion, - correlator: Correlator - ): F[ConnectedServer] = - given monad: MonadError[F] = transport.monad - val request = JSONRPCMessage.Request(method = "server/discover", params = Some(Json.obj("_meta" -> meta)), id = correlator.nextId()) - transport - .send(request) - .flatMap: - case Some(JSONRPCMessage.Response(_, _, result)) => - result.as[DiscoverResult] match - case Right(discovered) if !discovered.supportedVersions.contains(protocolVersion.name) => - monad.error( - McpProtocolException( - s"Server does not support protocol version '${protocolVersion.name}', " + - s"it supports: ${discovered.supportedVersions.mkString(", ")}" - ) - ) - case Right(discovered) => - discovered._meta.flatMap(_.get(ProtocolMeta.ServerInfo)).map(_.as[Implementation]) match - case Some(Right(serverInfo)) => monad.unit(ConnectedServer(discovered.capabilities, serverInfo)) - case _ => monad.error(McpProtocolException(s"server/discover result has no valid ${ProtocolMeta.ServerInfo} in _meta")) - case Left(error) => - monad.error(McpProtocolException(s"Failed to decode DiscoverResult: ${error.getMessage}")) - case Some(JSONRPCMessage.Error(_, _, error)) => - monad.error(McpProtocolException(s"server/discover failed: ${error.code} ${error.message}")) - case Some(other) => - monad.error(McpProtocolException(s"Unexpected response to server/discover: $other")) - case None => - monad.error(McpProtocolException("No response received for server/discover")) + private def decode[R: Decoder](method: String, result: Json): F[R] = + result.as[R] match + case Right(response) => monad.unit(response) + case Left(error) => monad.error(McpProtocolException(s"Failed to decode $method result: ${error.getMessage}")) - private def initialize[F[_]]( - transport: ClientTransport[F], - clientInfo: Implementation, - protocolVersion: ProtocolVersion, - clientCapabilities: ClientCapabilities, - correlator: Correlator - ): F[InitializeResult] = - given monad: MonadError[F] = transport.monad + private val statelessVersions: List[String] = ProtocolVersion.supported.filter(_.isModern).map(_.name) + + /** The newest stateless version that chimp shares with a server's `supported` list. */ + private def retryVersion(supported: List[String]): Option[ProtocolVersion] = + supported.flatMap(ProtocolVersion.from).filter(_.isModern).maxOption + + private final case class Discovered(result: DiscoverResult, serverInfo: Implementation): + def server: ConnectedServer = ConnectedServer(result.capabilities, serverInfo) + + /** The spec puts `serverInfo` in `_meta`; a top-level `serverInfo` is also accepted. A server MAY omit it. */ + private def serverInfoOf(result: Json, discovered: DiscoverResult): Implementation = + discovered._meta + .flatMap(_.get(ProtocolMeta.ServerInfo)) + .orElse(result.hcursor.downField("serverInfo").focus) + .flatMap(_.as[Implementation].toOption) + .getOrElse(UnknownServer) + + private val UnknownServer: Implementation = Implementation(name = "unknown", version = "unknown") + + private def initialize[F[_]](requests: Requests[F]): F[ConnectedServer] = + given monad: MonadError[F] = requests.monad val params = InitializeParams( - protocolVersion = protocolVersion, - capabilities = clientCapabilities, - clientInfo = clientInfo + protocolVersion = requests.protocolVersion, + capabilities = requests.clientCapabilities, + clientInfo = requests.clientInfo ) - val request = JSONRPCMessage.Request(method = "initialize", params = Some(params.asJson), id = correlator.nextId()) - transport + val request = JSONRPCMessage.Request(method = "initialize", params = Some(params.asJson), id = requests.nextId()) + requests.transport .send(request) .flatMap: case Some(JSONRPCMessage.Response(_, _, result)) => result.as[InitializeResult] match - case Right(initResult) if ProtocolVersion.from(initResult.protocolVersion).isDefined => - val notification = JSONRPCMessage.Notification(method = "notifications/initialized") - transport.send(notification).map(_ => initResult) case Right(initResult) => - monad.error( - McpProtocolException( - s"Server responded with unsupported protocol version '${initResult.protocolVersion}', " + - s"client supports: ${ProtocolVersion.values.toList.map(_.name).sorted.mkString(", ")}" - ) - ) + ProtocolVersion.from(initResult.protocolVersion).filterNot(_.isModern) match + case Some(negotiated) => + val server = ConnectedServer(initResult.capabilities, initResult.serverInfo) + requests + .useVersion(negotiated) + .flatMap(_ => requests.notify("notifications/initialized", None)) + .flatMap(_ => applyLegacyLogLevel(requests, server)) + .map(_ => server) + case None => + monad.error( + McpProtocolException( + s"Server responded with unsupported protocol version '${initResult.protocolVersion}', " + + s"client supports: ${ProtocolVersion.values.toList.filterNot(_.isModern).map(_.name).sorted.mkString(", ")}" + ) + ) case Left(error) => monad.error(McpProtocolException(s"Failed to decode InitializeResult: ${error.getMessage}")) case Some(JSONRPCMessage.Error(_, _, error)) => @@ -154,6 +225,14 @@ object McpClientImpl: case None => monad.error(McpProtocolException("No response received for initialize")) + /** A legacy version has no per-request log level, so the client sets it once with `logging/setLevel`. */ + private def applyLegacyLogLevel[F[_]](requests: Requests[F], server: ConnectedServer): F[Unit] = + given MonadError[F] = requests.monad + requests.logLevel match + case Some(level) if server.capabilities.logging.isDefined => + requests.send[Json]("logging/setLevel", Some(SetLevelParams(level = level).asJson)).map(_ => ()) + case _ => requests.monad.unit(()) + private def buildServerInitiatedRequestHandlers[F[_]]( rootsHandler: Option[() => F[ListRootsResult]], samplingHandler: Option[CreateMessageRequest => F[CreateMessageResult]], @@ -217,10 +296,7 @@ object McpClientImpl: private class Impl[F[_]]( protected val transport: ClientTransport[F], - protected val clientInfo: Implementation, - protected val protocolVersion: ProtocolVersion, - protected val clientCapabilities: ClientCapabilities, - protected val correlator: Correlator, + protected val requests: Requests[F], server: ConnectedServer ) extends McpClient[F]: protected given MonadError[F] = transport.monad @@ -229,107 +305,99 @@ object McpClientImpl: override val serverCapabilities: ServerCapabilities = server.capabilities override val serverInfo: Implementation = server.serverInfo - // a modern (2026-07-28) request carries the protocol version, client capabilities and client info in its own _meta - private val modernMeta: Option[Json] = - Option.when(protocolVersion.isModern)(Json.obj("_meta" -> requestMeta(protocolVersion, clientInfo, clientCapabilities))) + override def protocolVersion: ProtocolVersion = requests.protocolVersion - override def ping(): F[Unit] = sendRequest[Json]("ping", None).map(_ => ()) + override def discover(): F[DiscoverResult] = + requireStateless("server/discover")(requests.discover().map(_.result)) + + override def ping(): F[Unit] = requireLegacy("ping")(requests.send[Json]("ping", None).map(_ => ())) override def close(): F[Unit] = transport.close() override def listTools(cursor: Option[Cursor]): F[ListToolsResponse] = requireServerCapability("tools/list", _.tools.isDefined): val params = cursor.map(c => ListToolsParams(cursor = Some(c)).asJson) - sendRequest[ListToolsResponse]("tools/list", params) + requests.send[ListToolsResponse]("tools/list", params) override def callTool(name: String, arguments: Json): F[CallToolResult] = requireServerCapability("tools/call", _.tools.isDefined): val params = CallToolParams(name = name, arguments = arguments).asJson - sendRequest[CallToolResult]("tools/call", Some(params)) + requests.send[CallToolResult]("tools/call", Some(params)) override def listPrompts(cursor: Option[Cursor]): F[ListPromptsResult] = requireServerCapability("prompts/list", _.prompts.isDefined): val params = cursor.map(c => ListPromptsParams(cursor = Some(c)).asJson) - sendRequest[ListPromptsResult]("prompts/list", params) + requests.send[ListPromptsResult]("prompts/list", params) override def getPrompt(name: String, arguments: Map[String, String]): F[GetPromptResult] = requireServerCapability("prompts/get", _.prompts.isDefined): val params = GetPromptParams(name = name, arguments = if arguments.isEmpty then None else Some(arguments)).asJson - sendRequest[GetPromptResult]("prompts/get", Some(params)) + requests.send[GetPromptResult]("prompts/get", Some(params)) override def listResources(cursor: Option[Cursor]): F[ListResourcesResult] = requireServerCapability("resources/list", _.resources.isDefined): val params = cursor.map(c => ListResourcesParams(cursor = Some(c)).asJson) - sendRequest[ListResourcesResult]("resources/list", params) + requests.send[ListResourcesResult]("resources/list", params) override def listResourceTemplates(cursor: Option[Cursor]): F[ListResourceTemplatesResult] = requireServerCapability("resources/templates/list", _.resources.isDefined): val params = cursor.map(c => ListResourceTemplatesParams(cursor = Some(c)).asJson) - sendRequest[ListResourceTemplatesResult]("resources/templates/list", params) + requests.send[ListResourceTemplatesResult]("resources/templates/list", params) override def readResource(uri: String): F[ReadResourceResult] = requireServerCapability("resources/read", _.resources.isDefined): - sendRequest[ReadResourceResult]("resources/read", Some(ReadResourceParams(uri = uri).asJson)) + requests.send[ReadResourceResult]("resources/read", Some(ReadResourceParams(uri = uri).asJson)) override def complete(ref: CompleteRef, argument: CompleteArgument): F[CompleteResult] = requireServerCapability("completion/complete", _.completions.isDefined): val params = CompleteParams(ref = ref, argument = argument).asJson - sendRequest[CompleteResult]("completion/complete", Some(params)) + requests.send[CompleteResult]("completion/complete", Some(params)) override def setLoggingLevel(level: LoggingLevel): F[Unit] = - requireServerCapability("logging/setLevel", _.logging.isDefined): - sendRequest[Json]("logging/setLevel", Some(SetLevelParams(level = level).asJson)).map(_ => ()) + requireLegacy("logging/setLevel"): + requireServerCapability("logging/setLevel", _.logging.isDefined): + requests.send[Json]("logging/setLevel", Some(SetLevelParams(level = level).asJson)).map(_ => ()) override def sendProgress(token: ProgressToken, progress: Double, total: Option[Double], message: Option[String]): F[Unit] = - val params = ProgressParams(progressToken = token, progress = progress, total = total, message = message).asJson - sendNotification("notifications/progress", Some(params)) + requireLegacy("notifications/progress"): + val params = ProgressParams(progressToken = token, progress = progress, total = total, message = message).asJson + requests.notify("notifications/progress", Some(params)) protected def requireServerCapability[A](method: String, present: ServerCapabilities => Boolean)(action: => F[A]): F[A] = if present(serverCapabilities) then action else monad.error(McpProtocolException(s"Server did not negotiate the capability required for $method")) - protected def sendRequest[R: Decoder](method: String, params: Option[Json]): F[R] = - val stamped = modernMeta.fold(params)(meta => Some(params.getOrElse(Json.obj()).deepMerge(meta))) - val request = JSONRPCMessage.Request(method = method, params = stamped, id = correlator.nextId()) - transport - .send(request) - .flatMap: - case Some(JSONRPCMessage.Response(_, _, result)) => - result.as[R] match - case Right(response) => monad.unit(response) - case Left(error) => monad.error(McpProtocolException(s"Failed to decode $method result: ${error.getMessage}")) - case Some(JSONRPCMessage.Error(_, _, error)) => - monad.error(McpProtocolException(s"$method failed: ${error.code} ${error.message}")) - case Some(other) => - monad.error(McpProtocolException(s"Unexpected response to $method: $other")) - case None => - monad.error(McpProtocolException(s"No response received for request $method")) + /** Operations that the stateless (2026-07-28) wire removed. */ + protected def requireLegacy[A](method: String)(action: => F[A]): F[A] = + if protocolVersion.isModern then + monad.error(McpProtocolException(s"$method is not available at protocol version ${protocolVersion.name}, only at legacy versions")) + else action - protected def sendNotification(method: String, params: Option[Json]): F[Unit] = - val notification = JSONRPCMessage.Notification(method = method, params = params) - transport.send(notification).map(_ => ()) + private def requireStateless[A](method: String)(action: => F[A]): F[A] = + if protocolVersion.isModern then action + else monad.error(McpProtocolException(s"$method is not available at legacy protocol version ${protocolVersion.name}")) private final class BidirectionalImpl[F[_]]( bidiTransport: ClientBidirectionalTransport[F], - clientInfo: Implementation, - protocolVersion: ProtocolVersion, - clientCapabilities: ClientCapabilities, - correlator: Correlator, + requests: Requests[F], server: ConnectedServer, serverNotificationListeners: AtomicReference[List[ServerNotificationListener[F]]] - ) extends Impl[F](bidiTransport, clientInfo, protocolVersion, clientCapabilities, correlator, server) + ) extends Impl[F](bidiTransport, requests, server) with BidirectionalMcpClient[F]: override def subscribeResource(uri: String): F[Unit] = - requireServerCapability("resources/subscribe", _.resources.flatMap(_.subscribe).getOrElse(false)): - sendRequest[Json]("resources/subscribe", Some(SubscribeParams(uri = uri).asJson)).map(_ => ()) + requireLegacy("resources/subscribe"): + requireServerCapability("resources/subscribe", _.resources.flatMap(_.subscribe).getOrElse(false)): + requests.send[Json]("resources/subscribe", Some(SubscribeParams(uri = uri).asJson)).map(_ => ()) override def unsubscribeResource(uri: String): F[Unit] = - requireServerCapability("resources/unsubscribe", _.resources.flatMap(_.subscribe).getOrElse(false)): - sendRequest[Json]("resources/unsubscribe", Some(UnsubscribeParams(uri = uri).asJson)).map(_ => ()) + requireLegacy("resources/unsubscribe"): + requireServerCapability("resources/unsubscribe", _.resources.flatMap(_.subscribe).getOrElse(false)): + requests.send[Json]("resources/unsubscribe", Some(UnsubscribeParams(uri = uri).asJson)).map(_ => ()) override def sendRootsListChanged(): F[Unit] = - sendNotification("notifications/roots/list_changed", None) + requireLegacy("notifications/roots/list_changed"): + requests.notify("notifications/roots/list_changed", None) override def onServerNotification(listener: ServerNotificationListener[F]): F[Unit] = val _ = serverNotificationListeners.updateAndGet(listeners => listeners :+ listener) diff --git a/client/src/main/scala/chimp/client/transport/ClientHttpTransport.scala b/client/src/main/scala/chimp/client/transport/ClientHttpTransport.scala index c460371c..aa277a97 100644 --- a/client/src/main/scala/chimp/client/transport/ClientHttpTransport.scala +++ b/client/src/main/scala/chimp/client/transport/ClientHttpTransport.scala @@ -2,7 +2,7 @@ package chimp.client.transport import chimp.client.transport.ClientHttpTransport.HttpOutcome import chimp.client.{McpAuthorizationException, McpProtocolException, McpSessionNotFoundException, McpTransportException} -import chimp.protocol.{JSONRPCMessage, ProtocolVersion} +import chimp.protocol.{JSONRPCErrorObject, JSONRPCMessage, ProtocolMeta, ProtocolVersion} import sttp.client4.{basicRequest, Backend, Request, Response} import sttp.model.sse.ServerSentEvent import sttp.model.{Header, MediaType, StatusCode, Uri} @@ -18,44 +18,48 @@ import scala.util.chaining.* * The sttp backend used to send HTTP requests. * @param uri * The MCP endpoint URI. - * @param protocolVersion - * Protocol version advertised via the `MCP-Protocol-Version` header; defaults to the latest version supported by chimp. * @param headers * Extra headers sent with each request to the server. */ final class ClientHttpTransport[F[_]]( backend: Backend[F], uri: Uri, - protocolVersion: ProtocolVersion = ProtocolVersion.LatestLegacy, headers: Seq[Header] = Nil ) extends ClientTransport[F]: given monad: MonadError[F] = backend.monad private val sessionId = AtomicReference[Option[String]](None) + private val protocolVersion = AtomicReference(ClientHttpTransport.DefaultProtocolVersion) + + override def setProtocolVersion(version: ProtocolVersion): F[Unit] = monad.eval(protocolVersion.set(version)) override def send(msg: JSONRPCMessage): F[Option[JSONRPCMessage]] = ClientHttpTransport - .basePostRequest(uri, protocolVersion, sessionId.get(), msg, headers) + .basePostRequest(uri, protocolVersion.get(), sessionId.get(), msg, headers) .send(backend) - .flatMap(interpret) + .flatMap(interpret(msg, _)) - private def interpret(response: Response[Either[String, String]]): F[Option[JSONRPCMessage]] = + private def interpret(msg: JSONRPCMessage, response: Response[Either[String, String]]): F[Option[JSONRPCMessage]] = response.header("Mcp-Session-Id").foreach(s => sessionId.set(Some(s))) ClientHttpTransport.resolveResponse(response, sessionId.get()) match case Left(error: McpSessionNotFoundException) => sessionId.set(None) monad.error(error) - case Left(error) => monad.error(error) - case Right(HttpOutcome.NoBody) => monad.unit(None) - case Right(kind) => + case Left(error) => monad.error(error) + case Right(HttpOutcome.NoBody) => monad.unit(None) + case Right(HttpOutcome.ErrorBody(status)) => + ClientHttpTransport.errorResponse(msg, status, response.body.fold(identity, identity)) match + case Right(error) => monad.unit(Some(error)) + case Left(error) => monad.error(error) + case Right(kind) => response.body match case Left(err) => monad.error(McpTransportException(s"HTTP 200 with empty body: $err")) case Right(body) => val payload = kind match case HttpOutcome.JsonBody => if body.isEmpty then None else Some(body) case HttpOutcome.SseBody => ClientHttpTransport.extractSingleSseData(body) - case HttpOutcome.NoBody => None + case _ => None payload match case None => monad.unit(None) case Some(json) => @@ -69,13 +73,17 @@ final class ClientHttpTransport[F[_]]( case None => monad.unit(()) case Some(id) => sessionId.set(None) - ClientHttpTransport.baseDeleteRequest(uri, protocolVersion, id, headers).send(backend).map(_ => ()) + ClientHttpTransport.baseDeleteRequest(uri, protocolVersion.get(), id, headers).send(backend).map(_ => ()) object ClientHttpTransport: enum HttpOutcome: case NoBody case JsonBody case SseBody + case ErrorBody(status: StatusCode) + + /** The version an HTTP transport sends until the client sets one. */ + private[transport] val DefaultProtocolVersion: ProtocolVersion = ProtocolVersion.LatestLegacy private[transport] val AcceptHeader: String = s"${MediaType.ApplicationJson.toString}, ${MediaType.TextEventStream.toString}" @@ -92,6 +100,12 @@ object ClientHttpTransport: Header("Mcp-Method", method) :: name.map(Header("Mcp-Name", _)).toList case _ => Nil + /** A stateless request names its version in `_meta`; the `MCP-Protocol-Version` header always equals it. */ + private def metaVersion(msg: JSONRPCMessage): Option[String] = msg match + case JSONRPCMessage.Request(_, _, Some(params), _) => + params.hcursor.downField("_meta").get[String](ProtocolMeta.ProtocolVersionKey).toOption + case _ => None + private[transport] def basePostRequest( uri: Uri, protocolVersion: ProtocolVersion, @@ -99,13 +113,15 @@ object ClientHttpTransport: msg: JSONRPCMessage, headers: Seq[Header] ): Request[Either[String, String]] = + val version = metaVersion(msg).getOrElse(protocolVersion.name) + val stateless = ProtocolVersion.from(version).exists(_.isModern) basicRequest .post(uri) .headers(headers*) .header("Content-Type", MediaType.ApplicationJson.toString) .header("Accept", AcceptHeader) - .header("MCP-Protocol-Version", protocolVersion.name) - .headers((if protocolVersion.isModern then standardRequestHeaders(msg) else Nil)*) + .header(ProtocolMeta.ProtocolVersionHeader, version) + .headers((if stateless then standardRequestHeaders(msg) else Nil)*) .body(ClientTransport.encode(msg)) .pipe { request => sessionId match @@ -151,11 +167,30 @@ object ClientHttpTransport: case StatusCode.Accepted => Right(HttpOutcome.NoBody) case StatusCode.Unauthorized => Left(McpAuthorizationException("Authorization required", StatusCode.Unauthorized.code)) case StatusCode.Forbidden => Left(McpAuthorizationException("Forbidden", StatusCode.Forbidden.code)) - case StatusCode.NotFound => - currentSession match - case Some(id) => Left(McpSessionNotFoundException(id)) - case None => Left(McpTransportException("404 Not Found")) - case other => Left(McpTransportException(s"Unexpected HTTP response: ${other.code}")) + case StatusCode.NotFound if currentSession.isDefined => Left(McpSessionNotFoundException(currentSession.getOrElse(""))) + case other => Right(HttpOutcome.ErrorBody(other)) + + /** A request that fails with an HTTP error can carry a JSON-RPC error in the body, e.g. `-32022` with HTTP 400. That error is the + * response to the request; any other body fails with [[McpTransportException]]. + */ + private[transport] def errorResponse( + msg: JSONRPCMessage, + status: StatusCode, + body: String + ): Either[McpTransportException, JSONRPCMessage.Error] = + val error: Option[JSONRPCMessage.Error] = msg match + case request: JSONRPCMessage.Request => + io.circe.parser + .parse(body) + .flatMap(_.hcursor.downField("error").as[JSONRPCErrorObject]) + .toOption + .map(error => new JSONRPCMessage.Error(id = request.id, error = error)) + case _ => None + error.toRight(unexpectedStatus(status)) + + private def unexpectedStatus(status: StatusCode): McpTransportException = + if status == StatusCode.NotFound then McpTransportException("404 Not Found") + else McpTransportException(s"Unexpected HTTP response: ${status.code}") private def isSseResponse(response: Response[?]): Boolean = response diff --git a/client/src/main/scala/chimp/client/transport/ClientTransport.scala b/client/src/main/scala/chimp/client/transport/ClientTransport.scala index 2d18e2ae..d7dd7c22 100644 --- a/client/src/main/scala/chimp/client/transport/ClientTransport.scala +++ b/client/src/main/scala/chimp/client/transport/ClientTransport.scala @@ -1,10 +1,11 @@ package chimp.client.transport -import chimp.protocol.JSONRPCMessage +import chimp.protocol.{JSONRPCMessage, ProtocolVersion} import io.circe.parser import io.circe.syntax.* import sttp.monad.MonadError +import scala.annotation.unused import scala.concurrent.duration.{DurationInt, FiniteDuration} /** A unidirectional MCP transport: the client sends a [[chimp.protocol.JSONRPCMessage]] and optionally receives a response back. For @@ -15,6 +16,11 @@ trait ClientTransport[F[_]]: def send(msg: JSONRPCMessage): F[Option[JSONRPCMessage]] def close(): F[Unit] + /** The client calls this before its first request and each time its protocol version changes. HTTP transports send the version in the + * `MCP-Protocol-Version` header; a transport that does not need the version ignores it. + */ + def setProtocolVersion(@unused version: ProtocolVersion): F[Unit] = monad.unit(()) + /** A bidirectional MCP transport that, in addition to [[ClientTransport.send]] calls, allows the server to push messages to the client. * Incoming messages are delivered to the registered handler via [[onIncoming]]. Used by [[chimp.client.BidirectionalMcpClient]]. */ diff --git a/client/src/test/scala/chimp/client/CapabilityHandlerSpec.scala b/client/src/test/scala/chimp/client/CapabilityHandlerSpec.scala index 556a547b..d5b82655 100644 --- a/client/src/test/scala/chimp/client/CapabilityHandlerSpec.scala +++ b/client/src/test/scala/chimp/client/CapabilityHandlerSpec.scala @@ -13,7 +13,7 @@ class CapabilityHandlerSpec extends AnyFlatSpec with Matchers: private def planInitResponse(transport: InMemoryTransport): Unit = val initResult = InitializeResult( - protocolVersion = ProtocolVersion.Latest.name, + protocolVersion = ProtocolVersion.LatestLegacy.name, capabilities = ServerCapabilities(), serverInfo = Implementation(name = "s", version = "1") ) diff --git a/client/src/test/scala/chimp/client/ClientHttpTransportSpec.scala b/client/src/test/scala/chimp/client/ClientHttpTransportSpec.scala index 3f478cde..4de9d2db 100644 --- a/client/src/test/scala/chimp/client/ClientHttpTransportSpec.scala +++ b/client/src/test/scala/chimp/client/ClientHttpTransportSpec.scala @@ -68,3 +68,36 @@ class ClientHttpTransportSpec extends AnyFlatSpec with Matchers: val request = backend.allInteractions.map { case (request, _) => request }.head request.headers.filter(_.is("Accept")) shouldBe List(Header("Accept", "application/json, text/event-stream")) request.header("MCP-Protocol-Version") shouldBe Some(ProtocolVersion.LatestLegacy.name) + + it should "send the version that the client sets in MCP-Protocol-Version, and the _meta version of a request that has one" in: + val body = (JSONRPCMessage.Response(id = RequestId(1), result = Json.obj()): JSONRPCMessage).asJson.noSpaces + val backend = RecordingBackend(SyncBackendStub.whenAnyRequest.thenRespondAdjust(body, StatusCode.Ok)) + val transport = ClientHttpTransport[Identity](backend, mcpUri) + transport.setProtocolVersion(ProtocolVersion.V2025_06_18) + val _ = transport.send(JSONRPCMessage.Request(method = "tools/list", id = RequestId(1))) + val meta = Json.obj("_meta" -> Json.obj(ProtocolMeta.ProtocolVersionKey -> "2026-07-28".asJson)) + val _ = transport.send(JSONRPCMessage.Request(method = "tools/list", params = Some(meta), id = RequestId(2))) + + val requests = backend.allInteractions.map { case (request, _) => request } + requests.map(_.header("MCP-Protocol-Version")) shouldBe List(Some("2025-06-18"), Some("2026-07-28")) + requests.map(_.header("Mcp-Method")) shouldBe List(None, Some("tools/list")) + + it should "return the JSON-RPC error in the body of an HTTP error response as the response to the request" in: + val error = Json.obj( + "jsonrpc" -> "2.0".asJson, + "id" -> Json.Null, + "error" -> ProtocolMeta.unsupportedVersionError("2026-07-28", List("2026-07-28")).asJson + ) + val backend = SyncBackendStub.whenAnyRequest.thenRespondAdjust(error.noSpaces, StatusCode.BadRequest) + val transport = ClientHttpTransport[Identity](backend, mcpUri) + transport.send(JSONRPCMessage.Request(method = "x", id = RequestId(7))) match + case Some(JSONRPCMessage.Error(_, id, error)) => + id shouldBe RequestId(7) + error.code shouldBe JSONRPCErrorCodes.UnsupportedProtocolVersion.code + case other => fail(s"Expected an Error, got: $other") + + it should "fail with McpTransportException on an HTTP error response without a JSON-RPC error" in: + val backend = SyncBackendStub.whenAnyRequest.thenRespondAdjust("Method Not Allowed", StatusCode.MethodNotAllowed) + val transport = ClientHttpTransport[Identity](backend, mcpUri) + val ex = intercept[McpTransportException](transport.send(JSONRPCMessage.Request(method = "x", id = RequestId(1)))) + ex.getMessage should include("405") diff --git a/client/src/test/scala/chimp/client/McpClientSpec.scala b/client/src/test/scala/chimp/client/McpClientSpec.scala index 92419666..e8c148a1 100644 --- a/client/src/test/scala/chimp/client/McpClientSpec.scala +++ b/client/src/test/scala/chimp/client/McpClientSpec.scala @@ -101,7 +101,7 @@ class McpClientSpec extends AnyFlatSpec with Matchers: .thenRespondAdjust(callEnvelope) val client = - McpClient[Identity](ClientHttpTransport[Identity](backend, mcpUri, ProtocolVersion.Latest), clientInfo, ProtocolVersion.Latest) + McpClient[Identity](ClientHttpTransport[Identity](backend, mcpUri), clientInfo, ProtocolVersion.Latest) client.serverInfo.name shouldBe "modern-server" client.callTool("echo", io.circe.Json.obj()).isError shouldBe false @@ -121,6 +121,36 @@ class McpClientSpec extends AnyFlatSpec with Matchers: it should "fail construction when a discovered server does not support the client's modern version" in: val backend = SyncBackendStub.whenAnyRequest.thenRespondAdjust(discoverEnvelope(List("2025-11-25"))) - val t = ClientHttpTransport[Identity](backend, mcpUri, ProtocolVersion.Latest) - val ex = intercept[McpProtocolException](McpClient[Identity](t, clientInfo, ProtocolVersion.Latest)) - ex.getMessage should include("does not support protocol version '2026-07-28'") + val t = ClientHttpTransport[Identity](backend, mcpUri) + val ex = intercept[McpUnsupportedProtocolVersionException](McpClient[Identity](t, clientInfo, ProtocolVersion.Latest)) + ex.serverVersions shouldBe List("2025-11-25") + ex.clientVersions shouldBe List("2026-07-28") + + it should "retry over HTTP after a -32022 error in the body of an HTTP 400, with the header equal to _meta" in: + val sent = java.util.concurrent.ConcurrentLinkedQueue[GenericRequest[?, ?]]() + val rejected = java.util.concurrent.atomic.AtomicBoolean(false) + val rejection = io.circe.Json.obj( + "jsonrpc" -> "2.0".asJson, + "id" -> io.circe.Json.Null, + "error" -> ProtocolMeta.unsupportedVersionError("2026-07-28", List("2026-07-28")).asJson + ) + val backend = SyncBackendStub + .whenRequestMatches(request => sent.add(request) && !rejected.getAndSet(true)) + .thenRespondAdjust(rejection.noSpaces, StatusCode.BadRequest) + .whenAnyRequest + .thenRespondAdjust(discoverEnvelope(List("2026-07-28"))) + + val client = McpClient[Identity](ClientHttpTransport[Identity](backend, mcpUri), clientInfo, ProtocolVersion.Latest) + client.serverInfo.name shouldBe "modern-server" + val requests = sent.toArray(Array.empty[GenericRequest[?, ?]]).toList + requests should have size 2 + requests.foreach: request => + val metaVersion = request.body match + case StringBody(s, _, _) => + io.circe.parser + .parse(s) + .toOption + .flatMap(_.hcursor.downField("params").downField("_meta").get[String](ProtocolMeta.ProtocolVersionKey).toOption) + case _ => None + request.header("MCP-Protocol-Version") shouldBe metaVersion + metaVersion shouldBe Some("2026-07-28") diff --git a/client/src/test/scala/chimp/client/McpClientStatelessSpec.scala b/client/src/test/scala/chimp/client/McpClientStatelessSpec.scala new file mode 100644 index 00000000..bae1777c --- /dev/null +++ b/client/src/test/scala/chimp/client/McpClientStatelessSpec.scala @@ -0,0 +1,222 @@ +package chimp.client + +import chimp.protocol.* +import io.circe.Json +import io.circe.syntax.* +import org.scalatest.flatspec.AnyFlatSpec +import org.scalatest.matchers.should.Matchers +import sttp.shared.Identity + +import scala.concurrent.duration.Duration + +class McpClientStatelessSpec extends AnyFlatSpec with Matchers: + + private val clientInfo = Implementation(name = "chimp-test", version = "0.0.1") + private val serverInfo = Implementation(name = "modern-server", version = "2.0") + private val toolsCapability = ServerCapabilities(tools = Some(ServerToolsCapability(listChanged = Some(false)))) + + private def response(result: Json): JSONRPCMessage = JSONRPCMessage.Response(id = RequestId(1), result = result) + + private def discoverResult( + supportedVersions: List[String] = List(ProtocolVersion.Latest.name), + capabilities: ServerCapabilities = toolsCapability + ): Json = + DiscoverResult( + supportedVersions = supportedVersions, + capabilities = capabilities, + ttlMs = Duration.Zero, + cacheScope = CacheScope.Private, + _meta = Some(Map(ProtocolMeta.ServerInfo -> serverInfo.asJson)) + ).asJson.deepDropNullValues + + private def unsupportedVersion(supported: List[String]): JSONRPCMessage = + JSONRPCMessage.Error(id = RequestId(1), error = ProtocolMeta.unsupportedVersionError(ProtocolVersion.Latest.name, supported)) + + private val callResult: Json = CallToolResult(content = List(ToolContent.Text(text = "hi"))).asJson + + private def modernClient(transport: InMemoryTransport, logLevel: Option[LoggingLevel] = None): McpClient[Identity] = + transport.planResponse(response(discoverResult())) + McpClient[Identity](transport, clientInfo, ProtocolVersion.Latest, logLevel) + + private def methods(transport: InMemoryTransport): List[String] = transport.sent.toList.collect: + case JSONRPCMessage.Request(_, method, _, _) => method + case JSONRPCMessage.Notification(_, method, _) => method + + private def metaOf(message: JSONRPCMessage): Option[Json] = message match + case JSONRPCMessage.Request(_, _, params, _) => params.flatMap(_.hcursor.downField("_meta").focus) + case _ => None + + "A stateless client" should "call server/discover instead of initialize, and send no notifications/initialized" in: + val transport = InMemoryTransport() + val client = modernClient(transport) + methods(transport) shouldBe List("server/discover") + client.serverInfo shouldBe serverInfo + client.serverCapabilities shouldBe toolsCapability + client.protocolVersion shouldBe ProtocolVersion.Latest + + it should "put the protocol version, the client info and the client capabilities of its handlers in the _meta of every request" in: + val transport = InMemoryTransport() + transport.planResponse(response(discoverResult())) + transport.planResponse(response(callResult)) + val client = McpClient.bidirectional[Identity]( + transport, + clientInfo, + rootsHandler = Some(() => ListRootsResult(roots = Nil)), + protocolVersion = ProtocolVersion.Latest + ) + val _ = client.callTool("echo", Json.obj()) + val metas = transport.sent.toList.map(metaOf) + metas should have size 2 + all(metas.map(_.flatMap(_.hcursor.get[String](ProtocolMeta.ProtocolVersionKey).toOption))) shouldBe Some("2026-07-28") + all(metas.map(_.flatMap(_.hcursor.downField(ProtocolMeta.ClientInfo).as[Implementation].toOption))) shouldBe Some(clientInfo) + all(metas.map(_.flatMap(_.hcursor.downField(ProtocolMeta.ClientCapabilities).as[ClientCapabilities].toOption))) shouldBe Some( + ClientCapabilities(roots = Some(ClientRootsCapability(listChanged = Some(true)))) + ) + all(metas.map(_.flatMap(_.hcursor.downField(ProtocolMeta.LogLevel).focus))) shouldBe None + + it should "put the log level option in the _meta of every request" in: + val transport = InMemoryTransport() + val client = modernClient(transport, logLevel = Some(LoggingLevel.Warning)) + transport.planResponse(response(callResult)) + val _ = client.callTool("echo", Json.obj()) + all(transport.sent.toList.map(metaOf(_).flatMap(_.hcursor.get[String](ProtocolMeta.LogLevel).toOption))) shouldBe Some("warning") + + it should "keep the _meta fields that a request already has" in: + val transport = InMemoryTransport() + val client = modernClient(transport) + transport.planResponse(response(callResult)) + val _ = client.callTool("echo", Json.obj()) + metaOf(transport.sent.last).flatMap(_.hcursor.get[String](ProtocolMeta.ProtocolVersionKey).toOption) shouldBe Some("2026-07-28") + transport.sent.last match + case JSONRPCMessage.Request(_, _, Some(params), _) => params.hcursor.get[String]("name") shouldBe Right("echo") + case other => fail(s"Expected a request, got $other") + + it should "treat a result without resultType as complete" in: + val transport = InMemoryTransport() + val client = modernClient(transport) + transport.planResponse(response(callResult.mapObject(_.remove("resultType")))) + client.callTool("echo", Json.obj()).content shouldBe List(ToolContent.Text("text", "hi")) + + it should "fail with McpProtocolException on an unknown resultType" in: + val transport = InMemoryTransport() + val client = modernClient(transport) + transport.planResponse(response(callResult.deepMerge(Json.obj("resultType" -> "partial".asJson)))) + val ex = intercept[McpProtocolException](client.callTool("echo", Json.obj())) + ex.getMessage should include("unknown resultType") + + it should "fail with McpProtocolException on an input_required result, as it does not retry yet" in: + val transport = InMemoryTransport() + val client = modernClient(transport) + transport.planResponse(response(Json.obj("resultType" -> "input_required".asJson, "inputRequests" -> Json.obj()))) + val ex = intercept[McpProtocolException](client.callTool("echo", Json.obj())) + ex.getMessage should include("input_required") + + it should "retry once with a common version from the -32022 error, and keep that version" in: + val transport = InMemoryTransport() + val client = modernClient(transport) + transport.planResponse(unsupportedVersion(List("2099-01-01", ProtocolVersion.Latest.name))) + transport.planResponse(response(callResult)) + transport.planResponse(response(callResult)) + val _ = client.callTool("echo", Json.obj()) + val _ = client.callTool("echo", Json.obj()) + methods(transport) shouldBe List("server/discover", "tools/call", "tools/call", "tools/call") + client.protocolVersion shouldBe ProtocolVersion.Latest + + it should "negotiate the version on -32022 during discovery" in: + val transport = InMemoryTransport() + transport.planResponse(unsupportedVersion(List(ProtocolVersion.Latest.name))) + transport.planResponse(response(discoverResult())) + val client = McpClient[Identity](transport, clientInfo, ProtocolVersion.Latest) + methods(transport) shouldBe List("server/discover", "server/discover") + client.serverInfo shouldBe serverInfo + + it should "fail with an error that names both version lists when -32022 offers no common version" in: + val transport = InMemoryTransport() + val client = modernClient(transport) + transport.planResponse(unsupportedVersion(List("2099-01-01", "2025-11-25"))) + val ex = intercept[McpUnsupportedProtocolVersionException](client.callTool("echo", Json.obj())) + ex.serverVersions shouldBe List("2099-01-01", "2025-11-25") + ex.clientVersions shouldBe List("2026-07-28") + ex.getMessage should (include("2099-01-01") and include("2026-07-28")) + methods(transport) shouldBe List("server/discover", "tools/call") + + it should "retry only once" in: + val transport = InMemoryTransport() + val client = modernClient(transport) + transport.planResponse(unsupportedVersion(List(ProtocolVersion.Latest.name))) + transport.planResponse(unsupportedVersion(List(ProtocolVersion.Latest.name))) + val _ = intercept[McpUnsupportedProtocolVersionException](client.callTool("echo", Json.obj())) + methods(transport) shouldBe List("server/discover", "tools/call", "tools/call") + + it should "offer server/discover as an operation" in: + val transport = InMemoryTransport() + val client = modernClient(transport) + transport.planResponse(response(discoverResult().deepMerge(Json.obj("instructions" -> "be nice".asJson)))) + client.discover().instructions shouldBe Some("be nice") + + it should "guard operations with the capabilities from the discover result" in: + val transport = InMemoryTransport() + transport.planResponse(response(discoverResult(capabilities = ServerCapabilities()))) + val client = McpClient[Identity](transport, clientInfo, ProtocolVersion.Latest) + val ex = intercept[McpProtocolException](client.callTool("echo", Json.obj())) + ex.getMessage should include("Server did not negotiate the capability required for tools/call") + methods(transport) shouldBe List("server/discover") + + it should "read serverInfo from the top level of the discover result, or use 'unknown' when there is none" in: + val topLevel = InMemoryTransport() + topLevel.planResponse( + response(discoverResult().mapObject(_.remove("_meta")).deepMerge(Json.obj("serverInfo" -> serverInfo.asJson))) + ) + McpClient[Identity](topLevel, clientInfo, ProtocolVersion.Latest).serverInfo shouldBe serverInfo + + val missing = InMemoryTransport() + missing.planResponse(response(discoverResult().mapObject(_.remove("_meta")))) + McpClient[Identity](missing, clientInfo, ProtocolVersion.Latest).serverInfo shouldBe Implementation("unknown", "unknown") + + it should "reject the legacy-only operations without sending them" in: + val transport = InMemoryTransport() + transport.planResponse(response(discoverResult(capabilities = toolsCapability.copy(logging = Some(Json.obj()))))) + val client = McpClient.bidirectional[Identity](transport, clientInfo, protocolVersion = ProtocolVersion.Latest) + val operations: List[(String, () => Unit)] = List( + "ping" -> (() => client.ping()), + "logging/setLevel" -> (() => client.setLoggingLevel(LoggingLevel.Info)), + "resources/subscribe" -> (() => client.subscribeResource("file:///a")), + "resources/unsubscribe" -> (() => client.unsubscribeResource("file:///a")), + "notifications/progress" -> (() => client.sendProgress(ProgressToken("t"), 1.0)), + "notifications/roots/list_changed" -> (() => client.sendRootsListChanged()) + ) + operations.foreach: (method, operation) => + val ex = intercept[McpProtocolException](operation()) + ex.getMessage should include(method) + methods(transport) shouldBe List("server/discover") + + "A legacy client" should "reject server/discover" in: + val transport = InMemoryTransport() + transport.planResponse(response(legacyInitResult(ServerCapabilities()))) + val client = McpClient[Identity](transport, clientInfo) + val _ = intercept[McpProtocolException](client.discover()) + client.protocolVersion shouldBe ProtocolVersion.LatestLegacy + + it should "use the version that the server negotiates in initialize" in: + val transport = InMemoryTransport() + transport.planResponse(response(legacyInitResult(ServerCapabilities(), ProtocolVersion.V2025_06_18))) + McpClient[Identity](transport, clientInfo).protocolVersion shouldBe ProtocolVersion.V2025_06_18 + + it should "send the log level option once with logging/setLevel after initialize" in: + val transport = InMemoryTransport() + transport.planResponse(response(legacyInitResult(ServerCapabilities(logging = Some(Json.obj()))))) + transport.planResponse(response(Json.obj())) + val _ = McpClient[Identity](transport, clientInfo, logLevel = Some(LoggingLevel.Error)) + methods(transport) shouldBe List("initialize", "notifications/initialized", "logging/setLevel") + transport.sent.last match + case JSONRPCMessage.Request(_, _, Some(params), _) => params.hcursor.get[String]("level") shouldBe Right("error") + case other => fail(s"Expected a request, got $other") + + it should "not send logging/setLevel when the server has no logging capability" in: + val transport = InMemoryTransport() + transport.planResponse(response(legacyInitResult(ServerCapabilities()))) + val _ = McpClient[Identity](transport, clientInfo, logLevel = Some(LoggingLevel.Error)) + methods(transport) shouldBe List("initialize", "notifications/initialized") + + private def legacyInitResult(capabilities: ServerCapabilities, version: ProtocolVersion = ProtocolVersion.LatestLegacy): Json = + InitializeResult(protocolVersion = version.name, capabilities = capabilities, serverInfo = serverInfo).asJson diff --git a/conformance-baseline-2026-07-28.yml b/conformance-baseline-2026-07-28.yml index 8d9c6775..c7d87cfd 100644 --- a/conformance-baseline-2026-07-28.yml +++ b/conformance-baseline-2026-07-28.yml @@ -46,10 +46,7 @@ client: - auth/token-endpoint-auth-none - auth/token-endpoint-auth-post - auth/wif-jwt-bearer - # modern (2026-07-28) client era: stateless lifecycle, request _meta, HTTP headers — T10-T12, #248/#249/#250 + # modern (2026-07-28) client era: HTTP headers from tool arguments — T12, #250; multi round-trip requests — T15 - http-custom-headers - http-invalid-tool-headers - - json-schema-2020-12-preservation - - json-schema-ref-no-deref - - request-metadata - sep-2322-client-request-state diff --git a/docs/client/protocol.md b/docs/client/protocol.md new file mode 100644 index 00000000..d068a8a9 --- /dev/null +++ b/docs/client/protocol.md @@ -0,0 +1,70 @@ +# Protocol versions + +chimp's client speaks the legacy protocol versions (`2025-06-18`, `2025-11-25`) and the stateless version `2026-07-28`. You set the version once, on the client. The client gives it to the transport, so a transport has no version parameter. + +```scala mdoc:compile-only +import chimp.client.* +import chimp.client.transport.ClientHttpTransport +import chimp.protocol.{Implementation, LoggingLevel, ProtocolVersion} +import sttp.client4.DefaultSyncBackend +import sttp.model.Uri.UriContext +import sttp.shared.Identity + +object StatelessClient: + def main(args: Array[String]): Unit = + val backend = DefaultSyncBackend() + val transport = ClientHttpTransport[Identity](backend, uri"http://localhost:8080/mcp") + val client = McpClient[Identity]( + transport, + Implementation("my-client", "0.1.0"), + protocolVersion = ProtocolVersion.Latest, + logLevel = Some(LoggingLevel.Info) + ) + + println(client.discover().supportedVersions) + client.close() +``` + +## Legacy versions + +At a legacy version, the client sends `initialize` and `notifications/initialized`. It then uses the version that the server returns in the `initialize` result. + +## The stateless version + +At `2026-07-28` there is no handshake: + +- The client sends `server/discover` first. `serverCapabilities` and `serverInfo` come from its result. If the result has no `serverInfo`, both of its values are `unknown`. +- Every request carries `_meta` with the protocol version, the client info and the client capabilities. The capabilities come from the handlers that you give to `McpClient.bidirectional`. +- Over HTTP, the `MCP-Protocol-Version` header always equals the version in `_meta`. +- `discover()` sends `server/discover` again and returns the full result. At a legacy version it fails with `McpProtocolException`. + +## Version negotiation + +When a server rejects a request with `-32022` (unsupported protocol version), the client reads the versions in the error. It sends the request again, one time, with the newest version in that list that chimp also supports on the stateless wire. Later requests use that version too; `McpClient.protocolVersion` shows the current version. + +If the two lists have no common version, or the server rejects the second request too, the request fails with `McpUnsupportedProtocolVersionException`. Its message, `serverVersions` and `clientVersions` name both lists. + +Over HTTP, the server sends `-32022` with HTTP 400. The HTTP transports give the JSON-RPC error in the body of an HTTP error response to the client as the response to the request. A body without a JSON-RPC error fails with `McpTransportException`. + +## Results + +A result without `resultType` is complete. A result with an unknown `resultType` fails with `McpProtocolException`. + +A result with `resultType` `input_required` also fails with `McpProtocolException`: the client does not send the request again with the input yet. + +## Operations for legacy versions only + +`2026-07-28` removed these operations. At the stateless version they fail with `McpProtocolException` and the client sends nothing: + +- `ping` +- `setLoggingLevel` +- `subscribeResource`, `unsubscribeResource` +- `sendProgress` +- `sendRootsListChanged` + +## Log level + +The `logLevel` option of `McpClient.apply` and `McpClient.bidirectional` sets the minimum level of the log messages (`notifications/message`) that the server sends: + +- At the stateless version, every request carries the level in `_meta`. Without the option the client sends no level, and the server sends no log messages. +- At a legacy version, the client sends `logging/setLevel` once after `initialize`, if the server has the `logging` capability. diff --git a/docs/client/transport.md b/docs/client/transport.md index d7cc13e0..bf37d07d 100644 --- a/docs/client/transport.md +++ b/docs/client/transport.md @@ -36,12 +36,13 @@ classDiagram ## Protocol versions -The HTTP transports and `McpClient` each take a `protocolVersion`, which defaults to `ProtocolVersion.LatestLegacy` (`2025-11-25`). Give both the same version. +The transports have no protocol version parameter. You set the version on `McpClient`, and the client gives it to the transport (see [Protocol versions](protocol.md)). -- At a legacy version, the client runs the `initialize` handshake. -- At `ProtocolVersion.Latest` (`2026-07-28`), there is no handshake. The client calls `server/discover` to learn the server's capabilities and info, and fails if the server does not support its version. Every request then carries `_meta` with the protocol version, the client capabilities and the client info. The HTTP transports also send the `Mcp-Method` header, and `Mcp-Name` on `tools/call`, `prompts/get` and `resources/read`. +At the stateless version `2026-07-28`, the HTTP transports: -`2026-07-28` removed `ping`, `logging/setLevel` and `resources/{,un}subscribe`, so a modern server answers them with "method not found". +- send `MCP-Protocol-Version` equal to the version in the `_meta` of the request +- send the `Mcp-Method` header, and `Mcp-Name` on `tools/call`, `prompts/get` and `resources/read` +- open no GET stream for server messages ## Streaming integrations diff --git a/docs/index.md b/docs/index.md index 85f1ecee..8534f8ad 100644 --- a/docs/index.md +++ b/docs/index.md @@ -24,6 +24,7 @@ and [sttp](https://github.com/softwaremill/sttp), supporting the variety of the client/quickstart client/transport + client/protocol client/capabilities client/examples ``` diff --git a/server-streaming/server-ox/src/test/scala/chimp/server/ox/OxMcpServerHttpSpec.scala b/server-streaming/server-ox/src/test/scala/chimp/server/ox/OxMcpServerHttpSpec.scala index 6eeeea24..fe7377a0 100644 --- a/server-streaming/server-ox/src/test/scala/chimp/server/ox/OxMcpServerHttpSpec.scala +++ b/server-streaming/server-ox/src/test/scala/chimp/server/ox/OxMcpServerHttpSpec.scala @@ -3,7 +3,7 @@ package chimp.server.ox import chimp.client.transport.{ClientHttpTransport, ClientTransport} import chimp.client.transport.ox.OxClientHttpTransport import chimp.client.{BidirectionalMcpClient, McpClient} -import chimp.protocol.{Implementation, ProtocolMeta, ProtocolVersion} +import chimp.protocol.{Implementation, LoggingLevel, ProtocolMeta, ProtocolVersion} import chimp.server.transport.SecuredServerStreamingHttpTransport import chimp.server.{ tool, @@ -58,10 +58,19 @@ class OxMcpServerHttpSpec withHttpServer(OxServerHttpTransport(List("mcp")).serve(server)): (port, backend, ox) => given Ox = ox val transport = - OxClientHttpTransport(backend, uri"http://localhost:$port/mcp", clientProtocolVersion, ClientTransport.defaultTimeout) + OxClientHttpTransport(backend, uri"http://localhost:$port/mcp", ClientTransport.defaultTimeout) try test(McpClient.bidirectional(transport, clientInfo, protocolVersion = clientProtocolVersion)) finally transport.close() + override protected def withLoggingStreamingServer(server: StreamingMcpServer[Identity], logLevel: LoggingLevel)( + test: BidirectionalMcpClient[Identity] => Identity[Assertion] + ): Future[Assertion] = + withHttpServer(OxServerHttpTransport(List("mcp")).serve(server)): (port, backend, ox) => + given Ox = ox + val transport = OxClientHttpTransport(backend, uri"http://localhost:$port/mcp", ClientTransport.defaultTimeout) + try test(McpClient.bidirectional(transport, clientInfo, protocolVersion = clientProtocolVersion, logLevel = Some(logLevel))) + finally transport.close() + override protected def withStreamingHttpEndpoint(server: StreamingMcpServer[Identity])(test: URI => Assertion): Future[Assertion] = withHttpServer(OxServerHttpTransport(List("mcp")).serve(server)): (port, _, _) => test(URI.create(s"http://localhost:$port/mcp")) @@ -93,15 +102,13 @@ class OxMcpServerHttpSpec val transport = OxClientHttpTransport( backend, uri"http://localhost:$port/mcp", - clientProtocolVersion, ClientTransport.defaultTimeout, headers = List(Header.authorization("Bearer", token)) ) try test(McpClient.bidirectional(transport, clientInfo, protocolVersion = clientProtocolVersion)) finally transport.close() - // 2026-07-28 requests over raw HTTP: chimp's client does not write the modern `_meta` or the SEP-2243 headers yet - // (T10 https://github.com/softwaremill/chimp/issues/248, T12 https://github.com/softwaremill/chimp/issues/250) + // 2026-07-28 requests over raw HTTP, so that a test can leave out what chimp's client always sends private case class EchoInput(message: String) derives Codec, Schema private val modernServer: StreamingMcpServer[Identity] = diff --git a/server-streaming/server-pekko/src/test/scala/chimp/server/pekko/PekkoMcpServerHttpSpec.scala b/server-streaming/server-pekko/src/test/scala/chimp/server/pekko/PekkoMcpServerHttpSpec.scala index 141674e5..c30e4219 100644 --- a/server-streaming/server-pekko/src/test/scala/chimp/server/pekko/PekkoMcpServerHttpSpec.scala +++ b/server-streaming/server-pekko/src/test/scala/chimp/server/pekko/PekkoMcpServerHttpSpec.scala @@ -2,7 +2,7 @@ package chimp.server.pekko import chimp.client.transport.pekko.PekkoClientHttpTransport import chimp.client.{BidirectionalMcpClient, McpClient} -import chimp.protocol.{Implementation, ProtocolVersion} +import chimp.protocol.{Implementation, LoggingLevel, ProtocolVersion} import chimp.server.transport.SecuredServerStreamingHttpTransport import chimp.server.{ McpServer, @@ -52,6 +52,12 @@ class PekkoMcpServerHttpSpec withHttpServer(PekkoServerHttpTransport(List("mcp")).serve(server), Nil): transport => McpClient.bidirectional(transport, clientInfo).flatMap(test) + override protected def withLoggingStreamingServer(server: StreamingMcpServer[Future], logLevel: LoggingLevel)( + test: BidirectionalMcpClient[Future] => Future[Assertion] + ): Future[Assertion] = + withHttpServer(PekkoServerHttpTransport(List("mcp")).serve(server), Nil): transport => + McpClient.bidirectional(transport, clientInfo, logLevel = Some(logLevel)).flatMap(test) + override protected def withStreamingHttpEndpoint(server: StreamingMcpServer[Future])(test: URI => Assertion): Future[Assertion] = withEndpointUri(PekkoServerHttpTransport(List("mcp")).serve(server))(test) diff --git a/server-streaming/server-zio/src/test/scala/chimp/server/zio/ZioMcpServerHttpSpec.scala b/server-streaming/server-zio/src/test/scala/chimp/server/zio/ZioMcpServerHttpSpec.scala index d369e38c..a37acbcd 100644 --- a/server-streaming/server-zio/src/test/scala/chimp/server/zio/ZioMcpServerHttpSpec.scala +++ b/server-streaming/server-zio/src/test/scala/chimp/server/zio/ZioMcpServerHttpSpec.scala @@ -3,7 +3,7 @@ package chimp.server.zio import chimp.client.transport.ClientTransport import chimp.client.transport.zio.ZioClientHttpTransport import chimp.client.{BidirectionalMcpClient, McpClient} -import chimp.protocol.{Implementation, ProtocolVersion} +import chimp.protocol.{Implementation, LoggingLevel, ProtocolVersion} import chimp.server.transport.SecuredServerStreamingHttpTransport import chimp.server.{ McpServer, @@ -53,6 +53,12 @@ class ZioMcpServerHttpSpec withHttpServer(ZioServerHttpTransport(List("mcp")).serve(server), Nil): transport => McpClient.bidirectional(transport, clientInfo, protocolVersion = clientProtocolVersion).flatMap(test) + override protected def withLoggingStreamingServer(server: StreamingMcpServer[Task], logLevel: LoggingLevel)( + test: BidirectionalMcpClient[Task] => Task[Assertion] + ): Future[Assertion] = + withHttpServer(ZioServerHttpTransport(List("mcp")).serve(server), Nil): transport => + McpClient.bidirectional(transport, clientInfo, protocolVersion = clientProtocolVersion, logLevel = Some(logLevel)).flatMap(test) + override protected def withStreamingHttpEndpoint(server: StreamingMcpServer[Task])(test: URI => Assertion): Future[Assertion] = withEndpointUri(ZioServerHttpTransport(List("mcp")).serve(server))(test) @@ -96,7 +102,6 @@ class ZioMcpServerHttpSpec .scoped( backend, uri"http://localhost:$port/mcp", - clientProtocolVersion, ClientTransport.defaultTimeout, headers = headers ) diff --git a/server/src/test/scala/chimp/server/McpServerStreamingTests.scala b/server/src/test/scala/chimp/server/McpServerStreamingTests.scala index 5c60540a..c085e7b7 100644 --- a/server/src/test/scala/chimp/server/McpServerStreamingTests.scala +++ b/server/src/test/scala/chimp/server/McpServerStreamingTests.scala @@ -19,6 +19,11 @@ trait McpServerStreamingTests[F[_]] extends AsyncFlatSpec with Matchers: protected def withStreamingServer(server: StreamingMcpServer[F])(test: BidirectionalMcpClient[F] => F[Assertion]): Future[Assertion] + /** As [[withStreamingServer]], with a client that has the `logLevel` option. */ + protected def withLoggingStreamingServer(server: StreamingMcpServer[F], logLevel: LoggingLevel)( + test: BidirectionalMcpClient[F] => F[Assertion] + ): Future[Assertion] + /** The protocol version of the spec's client. A modern client sets no `_meta` logLevel, so it must get no log notifications. */ protected def clientProtocolVersion: ProtocolVersion @@ -39,7 +44,20 @@ trait McpServerStreamingTests[F[_]] extends AsyncFlatSpec with Matchers: yield ToolResult.text("done") ) - "a streaming MCP server" should "deliver log notifications emitted during a tool call, but none to a modern request without a log level" in + "a streaming MCP server" should "deliver log notifications to a client with the log level option, at a legacy and a modern version" in + withLoggingStreamingServer(streamingServer, LoggingLevel.Info): client => + val messages = ConcurrentLinkedQueue[Json]() + client + .onServerNotification: + case ServerNotification.LoggingMessage(params) => messages.add(params.data); monad.unit(()) + case _ => monad.unit(()) + .flatMap(_ => client.callTool("noisy", Json.obj())) + .flatMap: result => + waitUntil(messages.size >= 3).map: _ => + result.content shouldBe List(ToolContent.Text("text", "done")) + messages.asScala.toList shouldBe List(Json.fromString("one"), Json.fromString("two"), Json.fromString("three")) + + it should "deliver log notifications emitted during a tool call, but none to a modern request without a log level" in withStreamingServer(streamingServer): client => val messages = ConcurrentLinkedQueue[Json]() val listener: ServerNotification => F[Unit] = { From 014bb2e73226544a0198f2039ab370613e31d6f3 Mon Sep 17 00:00:00 2001 From: Ondra Pelech Date: Thu, 19 Nov 2026 21:24:53 +0100 Subject: [PATCH 29/31] feat(T12): client HTTP request headers on the stateless wire At 2026-07-28 every POST of the HTTP transports (sync, ZIO, Ox, Pekko) now carries the request headers that the spec requires: - Mcp-Name in the Base64 sentinel form when the value is not printable ASCII, has leading or trailing whitespace, or looks like the sentinel - Mcp-Param- for each tools/call argument that the tool's input schema marks with x-mcp-header: strings plain or in the sentinel form, booleans as true/false, integers as JSON text, nothing for null A stateless tools/list result loses the tools whose x-mcp-header annotations are invalid (empty, not a string, not an HTTP token, duplicated case-insensitively, on a non string/integer/boolean property or off a plain properties chain); the transport logs a warning and keeps the other tools. Legacy requests and stdio are unchanged. The conformance client handles http-standard-headers, http-custom-headers and http-invalid-tool-headers; the last two leave the 2026-07-28 baseline. --- .../scala/chimp/conformance/client/Main.scala | 31 ++++ .../transport/ox/OxClientHttpTransport.scala | 8 +- .../pekko/PekkoClientHttpTransport.scala | 23 +-- .../zio/ZioClientHttpTransport.scala | 9 +- .../transport/ClientHttpTransport.scala | 32 ++-- .../client/transport/McpRequestHeaders.scala | 152 ++++++++++++++++++ .../scala/chimp/client/McpClientSpec.scala | 66 ++++++++ .../chimp/client/McpRequestHeadersSpec.scala | 64 ++++++++ conformance-baseline-2026-07-28.yml | 4 +- docs/client/transport.md | 19 +++ .../server/McpServerStreamingTests.scala | 28 +++- 11 files changed, 395 insertions(+), 41 deletions(-) create mode 100644 client/src/main/scala/chimp/client/transport/McpRequestHeaders.scala create mode 100644 client/src/test/scala/chimp/client/McpRequestHeadersSpec.scala diff --git a/client-conformance/src/main/scala/chimp/conformance/client/Main.scala b/client-conformance/src/main/scala/chimp/conformance/client/Main.scala index 8892cfc3..4a25b0bf 100644 --- a/client-conformance/src/main/scala/chimp/conformance/client/Main.scala +++ b/client-conformance/src/main/scala/chimp/conformance/client/Main.scala @@ -5,6 +5,7 @@ import chimp.client.transport.ClientHttpTransport import chimp.client.transport.ox.OxClientHttpTransport import chimp.protocol.* import io.circe.Json +import io.circe.parser.parse import ox.supervised import sttp.client4.DefaultSyncBackend import sttp.model.Uri @@ -21,6 +22,15 @@ object Main: .getOrElse(Map.empty) .flatMap((key, prop) => prop.hcursor.downField("default").focus.map(key -> _)) + /** The tool calls that the harness asks for in `MCP_CONFORMANCE_CONTEXT`. */ + private def contextToolCalls: List[(String, Json)] = + sys.env + .get("MCP_CONFORMANCE_CONTEXT") + .flatMap(context => parse(context).toOption) + .flatMap(_.hcursor.downField("toolCalls").as[List[Json]].toOption) + .getOrElse(Nil) + .flatMap(call => call.hcursor.get[String]("name").toOption.map(_ -> call.hcursor.downField("arguments").focus.getOrElse(Json.obj()))) + def main(args: Array[String]): Unit = if args.isEmpty then System.err.println("Usage: chimp-conformance-client ") @@ -47,6 +57,27 @@ object Main: client.close() 0 + case "http-standard-headers" => + val client = McpClient[Identity](transport, clientInfo, protocolVersion) + client.listTools().tools.foreach(tool => client.callTool(tool.name, Json.obj())) + client.listResources().resources.foreach(resource => client.readResource(resource.uri)) + client.listPrompts().prompts.foreach(prompt => client.getPrompt(prompt.name)) + client.close() + 0 + + case "http-custom-headers" => + val client = McpClient[Identity](transport, clientInfo, protocolVersion) + val _ = client.listTools() + contextToolCalls.foreach((name, arguments) => client.callTool(name, arguments)) + client.close() + 0 + + case "http-invalid-tool-headers" => + val client = McpClient[Identity](transport, clientInfo, protocolVersion) + client.listTools().tools.foreach(tool => client.callTool(tool.name, Json.obj())) + client.close() + 0 + case "json-schema-ref-no-deref" => val client = McpClient[Identity](transport, clientInfo, protocolVersion) val _ = client.listTools() diff --git a/client-streaming/client-ox/src/main/scala/chimp/client/transport/ox/OxClientHttpTransport.scala b/client-streaming/client-ox/src/main/scala/chimp/client/transport/ox/OxClientHttpTransport.scala index 51aae35b..650b1c5d 100644 --- a/client-streaming/client-ox/src/main/scala/chimp/client/transport/ox/OxClientHttpTransport.scala +++ b/client-streaming/client-ox/src/main/scala/chimp/client/transport/ox/OxClientHttpTransport.scala @@ -2,7 +2,7 @@ package chimp.client.transport.ox import chimp.client.internal.SyncPendingRequests import chimp.client.transport.ClientHttpTransport.HttpOutcome -import chimp.client.transport.{ClientBidirectionalTransport, ClientHttpTransport, ClientTransport} +import chimp.client.transport.{ClientBidirectionalTransport, ClientHttpTransport, ClientTransport, ToolHeaders} import chimp.client.{McpProtocolException, McpSessionNotFoundException, McpTransportException} import chimp.protocol.{JSONRPCErrorCodes, JSONRPCErrorObject, JSONRPCMessage, ProtocolVersion, RequestId} import org.slf4j.LoggerFactory @@ -54,6 +54,7 @@ final class OxClientHttpTransport private ( private val state: ActorRef[State] = Actor.create(new State) private val protocolVersion = AtomicReference(ClientHttpTransport.DefaultProtocolVersion) + private val toolHeaders = ToolHeaders() given monad: MonadError[Identity] = IdentityMonad @@ -61,12 +62,13 @@ final class OxClientHttpTransport private ( override def send(msg: JSONRPCMessage): Identity[Option[JSONRPCMessage]] = if state.ask(_.closing) then throw McpTransportException("HTTP transport is closed") - msg match + val response = msg match case request: JSONRPCMessage.Request => val await = pending.register(request.id, timeout) try sendRequest(request, await) finally { val _ = pending.complete(request.id, cancelled(request.id)) } case other => sendNonRequest(other) + toolHeaders.filterToolsList(msg, response) override def onIncoming(handler: JSONRPCMessage => Identity[Unit]): Identity[Unit] = state.tell(_.incoming = handler) @@ -125,7 +127,7 @@ final class OxClientHttpTransport private ( private def post(msg: JSONRPCMessage): Response[Either[String, InputStream]] = ClientHttpTransport - .basePostRequest(uri, protocolVersion.get(), state.ask(_.sessionId), msg, headers) + .basePostRequest(uri, protocolVersion.get(), state.ask(_.sessionId), msg, headers, toolHeaders) .response(asInputStreamUnsafe) .send(backend) diff --git a/client-streaming/client-pekko/src/main/scala/chimp/client/transport/pekko/PekkoClientHttpTransport.scala b/client-streaming/client-pekko/src/main/scala/chimp/client/transport/pekko/PekkoClientHttpTransport.scala index a61d7ee9..488899a2 100644 --- a/client-streaming/client-pekko/src/main/scala/chimp/client/transport/pekko/PekkoClientHttpTransport.scala +++ b/client-streaming/client-pekko/src/main/scala/chimp/client/transport/pekko/PekkoClientHttpTransport.scala @@ -2,7 +2,7 @@ package chimp.client.transport.pekko import chimp.client.transport.ClientHttpTransport.HttpOutcome import chimp.client.transport.pekko.internal.{PekkoPendingRequests, StateActor} -import chimp.client.transport.{ClientHttpTransport, ClientStreamingHttpTransport, ClientTransport} +import chimp.client.transport.{ClientHttpTransport, ClientStreamingHttpTransport, ClientTransport, ToolHeaders} import chimp.client.{McpProtocolException, McpSessionNotFoundException, McpTransportException} import chimp.protocol.{JSONRPCErrorCodes, JSONRPCErrorObject, JSONRPCMessage, ProtocolVersion, RequestId} import org.apache.pekko.NotUsed @@ -38,6 +38,7 @@ final class PekkoClientHttpTransport private ( private given ExecutionContext = mat.executionContext private val protocolVersion = AtomicReference(ClientHttpTransport.DefaultProtocolVersion) + private val toolHeaders = ToolHeaders() override def setProtocolVersion(version: ProtocolVersion): Future[Unit] = Future.successful(protocolVersion.set(version)) @@ -104,14 +105,16 @@ final class PekkoClientHttpTransport private ( .ask(_.closing) .flatMap: case true => Future.failed(McpTransportException("HTTP transport is closed")) - case false => - msg match - case request: JSONRPCMessage.Request => - pending - .register(request.id, timeout) - .flatMap(await => sendRequest(request, await)) - .andThen { case _ => pending.complete(request.id, cancelled(request.id)) } - case other => sendNonRequest(other) + case false => sendMessage(msg).map(toolHeaders.filterToolsList(msg, _)) + + private def sendMessage(msg: JSONRPCMessage): Future[Option[JSONRPCMessage]] = + msg match + case request: JSONRPCMessage.Request => + pending + .register(request.id, timeout) + .flatMap(await => sendRequest(request, await)) + .andThen { case _ => pending.complete(request.id, cancelled(request.id)) } + case other => sendNonRequest(other) override def onIncoming(handler: JSONRPCMessage => Future[Unit]): Future[Unit] = state.tell(_.incoming = handler) @@ -197,7 +200,7 @@ final class PekkoClientHttpTransport private ( .ask(_.sessionId) .flatMap: session => ClientHttpTransport - .basePostRequest(uri, protocolVersion.get(), session, msg, headers) + .basePostRequest(uri, protocolVersion.get(), session, msg, headers, toolHeaders) .response(asStreamUnsafe(PekkoStreams)) .send(backend) diff --git a/client-streaming/client-zio/src/main/scala/chimp/client/transport/zio/ZioClientHttpTransport.scala b/client-streaming/client-zio/src/main/scala/chimp/client/transport/zio/ZioClientHttpTransport.scala index 4bef045d..bc0679ac 100644 --- a/client-streaming/client-zio/src/main/scala/chimp/client/transport/zio/ZioClientHttpTransport.scala +++ b/client-streaming/client-zio/src/main/scala/chimp/client/transport/zio/ZioClientHttpTransport.scala @@ -1,7 +1,7 @@ package chimp.client.transport.zio import chimp.client.transport.ClientHttpTransport.HttpOutcome -import chimp.client.transport.{ClientHttpTransport, ClientStreamingHttpTransport, ClientTransport} +import chimp.client.transport.{ClientHttpTransport, ClientStreamingHttpTransport, ClientTransport, ToolHeaders} import chimp.client.{McpProtocolException, McpSessionNotFoundException} import chimp.protocol.{JSONRPCErrorCodes, JSONRPCErrorObject, JSONRPCMessage, ProtocolVersion, RequestId} import org.slf4j.LoggerFactory @@ -37,7 +37,12 @@ final class ZioClientHttpTransport private ( override def setProtocolVersion(version: ProtocolVersion): Task[Unit] = protocolVersion.set(version) + private val toolHeaders = ToolHeaders() + override def send(msg: JSONRPCMessage): Task[Option[JSONRPCMessage]] = + sendMessage(msg).map(toolHeaders.filterToolsList(msg, _)) + + private def sendMessage(msg: JSONRPCMessage): Task[Option[JSONRPCMessage]] = msg match case request: JSONRPCMessage.Request => pending @@ -111,7 +116,7 @@ final class ZioClientHttpTransport private ( private def post(msg: JSONRPCMessage): Task[Response[Either[String, Stream[Throwable, Byte]]]] = (sessionRef.get <*> protocolVersion.get).flatMap: (session, version) => ClientHttpTransport - .basePostRequest(uri, version, session, msg, headers) + .basePostRequest(uri, version, session, msg, headers, toolHeaders) .response(asStreamUnsafe(ZioStreams)) .send(backend) diff --git a/client/src/main/scala/chimp/client/transport/ClientHttpTransport.scala b/client/src/main/scala/chimp/client/transport/ClientHttpTransport.scala index aa277a97..06420a7f 100644 --- a/client/src/main/scala/chimp/client/transport/ClientHttpTransport.scala +++ b/client/src/main/scala/chimp/client/transport/ClientHttpTransport.scala @@ -20,6 +20,9 @@ import scala.util.chaining.* * The MCP endpoint URI. * @param headers * Extra headers sent with each request to the server. + * + * At a stateless protocol version, a `tools/list` result leaves out the tools whose `x-mcp-header` annotations are invalid, and a + * `tools/call` mirrors the annotated arguments of a listed tool into `Mcp-Param-*` headers. */ final class ClientHttpTransport[F[_]]( backend: Backend[F], @@ -31,14 +34,16 @@ final class ClientHttpTransport[F[_]]( private val sessionId = AtomicReference[Option[String]](None) private val protocolVersion = AtomicReference(ClientHttpTransport.DefaultProtocolVersion) + private val toolHeaders = ToolHeaders() override def setProtocolVersion(version: ProtocolVersion): F[Unit] = monad.eval(protocolVersion.set(version)) override def send(msg: JSONRPCMessage): F[Option[JSONRPCMessage]] = ClientHttpTransport - .basePostRequest(uri, protocolVersion.get(), sessionId.get(), msg, headers) + .basePostRequest(uri, protocolVersion.get(), sessionId.get(), msg, headers, toolHeaders) .send(backend) .flatMap(interpret(msg, _)) + .map(toolHeaders.filterToolsList(msg, _)) private def interpret(msg: JSONRPCMessage, response: Response[Either[String, String]]): F[Option[JSONRPCMessage]] = response.header("Mcp-Session-Id").foreach(s => sessionId.set(Some(s))) @@ -88,32 +93,15 @@ object ClientHttpTransport: private[transport] val AcceptHeader: String = s"${MediaType.ApplicationJson.toString}, ${MediaType.TextEventStream.toString}" - // SEP-2243: the body field that the `Mcp-Name` header mirrors, per method - private val nameFields: Map[String, String] = Map("tools/call" -> "name", "prompts/get" -> "name", "resources/read" -> "uri") - - /** SEP-2243 standard request headers (2026-07-28): `Mcp-Method` on every request, and `Mcp-Name` on a request with a name-shaped body - * field. Notifications and responses carry none. - */ - private[transport] def standardRequestHeaders(msg: JSONRPCMessage): List[Header] = msg match - case JSONRPCMessage.Request(_, method, params, _) => - val name = nameFields.get(method).flatMap(field => params.flatMap(_.hcursor.get[String](field).toOption)) - Header("Mcp-Method", method) :: name.map(Header("Mcp-Name", _)).toList - case _ => Nil - - /** A stateless request names its version in `_meta`; the `MCP-Protocol-Version` header always equals it. */ - private def metaVersion(msg: JSONRPCMessage): Option[String] = msg match - case JSONRPCMessage.Request(_, _, Some(params), _) => - params.hcursor.downField("_meta").get[String](ProtocolMeta.ProtocolVersionKey).toOption - case _ => None - private[transport] def basePostRequest( uri: Uri, protocolVersion: ProtocolVersion, sessionId: Option[String], msg: JSONRPCMessage, - headers: Seq[Header] + headers: Seq[Header], + toolHeaders: ToolHeaders ): Request[Either[String, String]] = - val version = metaVersion(msg).getOrElse(protocolVersion.name) + val version = McpRequestHeaders.metaVersion(msg).getOrElse(protocolVersion.name) val stateless = ProtocolVersion.from(version).exists(_.isModern) basicRequest .post(uri) @@ -121,7 +109,7 @@ object ClientHttpTransport: .header("Content-Type", MediaType.ApplicationJson.toString) .header("Accept", AcceptHeader) .header(ProtocolMeta.ProtocolVersionHeader, version) - .headers((if stateless then standardRequestHeaders(msg) else Nil)*) + .headers((if stateless then McpRequestHeaders.standard(msg) ++ toolHeaders.paramHeaders(msg) else Nil)*) .body(ClientTransport.encode(msg)) .pipe { request => sessionId match diff --git a/client/src/main/scala/chimp/client/transport/McpRequestHeaders.scala b/client/src/main/scala/chimp/client/transport/McpRequestHeaders.scala new file mode 100644 index 00000000..9603d157 --- /dev/null +++ b/client/src/main/scala/chimp/client/transport/McpRequestHeaders.scala @@ -0,0 +1,152 @@ +package chimp.client.transport + +import chimp.protocol.{JSONRPCMessage, ProtocolMeta, ProtocolVersion} +import io.circe.Json +import org.slf4j.LoggerFactory +import sttp.model.Header + +import java.nio.charset.StandardCharsets +import java.util.concurrent.atomic.AtomicReference +import java.util.{Base64, Locale} + +/** The request headers of the stateless wire (2026-07-28): `Mcp-Method`, `Mcp-Name` and the `Mcp-Param-*` headers that mirror tool + * arguments annotated with `x-mcp-header`. + */ +private[client] object McpRequestHeaders: + private val Key = "x-mcp-header" + private val ParamPrefix = "Mcp-Param-" + private val PrimitiveTypes = Set("string", "integer", "boolean") + private val TokenSymbols = "!#$%&'*+-.^_`|~".toSet + private val SentinelPrefix = "=?base64?" + private val SentinelSuffix = "?=" + private val SchemaMaps = Set("properties", "patternProperties", "$defs", "definitions", "dependentSchemas") + private val NonSchemaValues = Set("default", "examples", "example", "const", "enum", Key) + + // the body field that the `Mcp-Name` header mirrors, per method + private val nameFields: Map[String, String] = Map("tools/call" -> "name", "prompts/get" -> "name", "resources/read" -> "uri") + + /** The version that a request names in `_meta`. */ + def metaVersion(msg: JSONRPCMessage): Option[String] = msg match + case JSONRPCMessage.Request(_, _, Some(params), _) => + params.hcursor.downField("_meta").get[String](ProtocolMeta.ProtocolVersionKey).toOption + case _ => None + + def isStateless(msg: JSONRPCMessage): Boolean = metaVersion(msg).flatMap(ProtocolVersion.from).exists(_.isModern) + + /** `Mcp-Method` on every request, and `Mcp-Name` on a request with a name-shaped body field. Notifications and responses carry none. */ + def standard(msg: JSONRPCMessage): List[Header] = msg match + case JSONRPCMessage.Request(_, method, params, _) => + val name = nameFields.get(method).flatMap(field => params.flatMap(_.hcursor.get[String](field).toOption)) + Header("Mcp-Method", method) :: name.map(value => Header("Mcp-Name", encode(value))).toList + case _ => Nil + + /** A value goes as it is when it is printable ASCII without leading or trailing spaces and does not look like the sentinel, else in the + * Base64 sentinel form. + */ + def encode(value: String): String = + val sentinelLike = value.startsWith(SentinelPrefix) && value.endsWith(SentinelSuffix) + if value.forall(c => c >= ' ' && c <= '~') && value.trim == value && !sentinelLike then value + else SentinelPrefix + Base64.getEncoder.encodeToString(value.getBytes(StandardCharsets.UTF_8)) + SentinelSuffix + + /** The header value of a tool argument; `null`, arrays and objects have none. */ + def argumentValue(argument: Json): Option[String] = + argument.fold( + jsonNull = None, + jsonBoolean = value => Some(value.toString), + jsonNumber = number => Some(Json.fromJsonNumber(number).noSpaces), + jsonString = value => Some(encode(value)), + jsonArray = _ => None, + jsonObject = _ => None + ) + + /** A tool input property mirrored into the `Mcp-Param-{name}` header. */ + final case class Param(path: List[String], name: String): + def header: String = ParamPrefix + name + + /** The params that a tool's input schema declares, or why its annotations are invalid. */ + def params(inputSchema: Json): Either[List[String], List[Param]] = + val found = annotations(inputSchema, Nil) + val names = found.flatMap((_, node) => node.hcursor.get[String](Key).toOption) + val duplicates = names + .groupBy(_.toLowerCase(Locale.ROOT)) + .values + .toList + .collect: + case same if same.size > 1 => s"x-mcp-header '${same.head}' is used more than once" + val checked = found.map((path, node) => problem(path, node)) + val problems = checked.collect { case Left(problem) => problem } ++ duplicates + if problems.isEmpty then Right(checked.collect { case Right(param) => param }) else Left(problems) + + private def problem(path: List[String], node: Json): Either[String, Param] = + def invalid(reason: String) = Left(s"x-mcp-header at ${path.mkString("#/", "/", "")} $reason") + (node.hcursor.downField(Key).focus.flatMap(_.asString), propertyPath(path)) match + case (None, _) => invalid("is not a string") + case (Some(name), _) if name.isEmpty => invalid("is empty") + case (Some(name), _) if !name.forall(isTokenChar) => invalid(s"is not an HTTP token: '$name'") + case (Some(_), None) => invalid("is not on a property reachable through properties keys only") + case (Some(_), _) if !node.hcursor.downField("type").focus.exists(isPrimitiveType) => + invalid("is not on a string, integer or boolean property") + case (Some(name), Some(properties)) => Right(Param(properties, name)) + + private def propertyPath(path: List[String]): Option[List[String]] = + val steps = path.grouped(2).toList + Option.when(path.nonEmpty && path.length % 2 == 0 && steps.forall(_.head == "properties"))(steps.map(_(1))) + + /** Every schema node that carries `x-mcp-header`, with its path of JSON keys from the root. */ + private def annotations(json: Json, path: List[String]): List[(List[String], Json)] = + json.asObject.toList.flatMap: node => + val own = node(Key).map(_ => (path, json)).toList + val nested = node.toList.flatMap: + case (key, _) if NonSchemaValues.contains(key) => Nil + case (key, value) if SchemaMaps.contains(key) => + value.asObject.toList.flatMap(_.toList.flatMap((name, sub) => annotations(sub, path ++ List(key, name)))) + case (key, value) => + value.asArray match + case Some(items) => items.toList.zipWithIndex.flatMap((item, i) => annotations(item, path ++ List(key, i.toString))) + case None => annotations(value, path :+ key) + own ++ nested + + private def isTokenChar(c: Char): Boolean = (c < 128 && c.isLetterOrDigit) || TokenSymbols.contains(c) + + private def isPrimitiveType(json: Json): Boolean = + json.asString.exists(PrimitiveTypes.contains) || + json.asArray + .map(_.flatMap(_.asString).filterNot(_ == "null").toList) + .exists: + case single :: Nil => PrimitiveTypes.contains(single) + case _ => false + +/** The `x-mcp-header` params of the tools that an HTTP transport has listed on the stateless wire. */ +private[client] final class ToolHeaders: + import McpRequestHeaders.* + + private val log = LoggerFactory.getLogger(classOf[ToolHeaders]) + private val byTool = AtomicReference(Map.empty[String, List[Param]]) + + /** The `Mcp-Param-*` headers of a stateless `tools/call`, for the arguments that are present and not `null`. */ + def paramHeaders(msg: JSONRPCMessage): List[Header] = msg match + case JSONRPCMessage.Request(_, "tools/call", Some(params), _) if isStateless(msg) => + val arguments = params.hcursor.downField("arguments").focus + val toolParams = params.hcursor.get[String]("name").toOption.flatMap(byTool.get().get).getOrElse(Nil) + toolParams.flatMap: param => + val argument = param.path.foldLeft(arguments)((json, key) => json.flatMap(_.asObject).flatMap(_(key))) + argument.flatMap(argumentValue).map(Header(param.header, _)) + case _ => Nil + + /** Drops the tools with invalid `x-mcp-header` annotations from a stateless `tools/list` result, and keeps the params of the others. */ + def filterToolsList(request: JSONRPCMessage, response: Option[JSONRPCMessage]): Option[JSONRPCMessage] = (request, response) match + case (JSONRPCMessage.Request(_, "tools/list", _, _), Some(JSONRPCMessage.Response(jsonrpc, id, result))) if isStateless(request) => + result.hcursor.downField("tools").focus.flatMap(_.asArray) match + case None => response + case Some(tools) => + val kept = tools.filter: tool => + val name = tool.hcursor.get[String]("name").getOrElse("") + params(tool.hcursor.downField("inputSchema").focus.getOrElse(Json.obj())) match + case Right(found) => + val _ = byTool.updateAndGet(_.updated(name, found)) + true + case Left(problems) => + log.warn(s"Ignoring tool '$name' with an invalid x-mcp-header: ${problems.mkString("; ")}") + false + Some(JSONRPCMessage.Response(jsonrpc, id, result.mapObject(_.add("tools", Json.fromValues(kept))))) + case _ => response diff --git a/client/src/test/scala/chimp/client/McpClientSpec.scala b/client/src/test/scala/chimp/client/McpClientSpec.scala index e8c148a1..41f61422 100644 --- a/client/src/test/scala/chimp/client/McpClientSpec.scala +++ b/client/src/test/scala/chimp/client/McpClientSpec.scala @@ -154,3 +154,69 @@ class McpClientSpec extends AnyFlatSpec with Matchers: case _ => None request.header("MCP-Protocol-Version") shouldBe metaVersion metaVersion shouldBe Some("2026-07-28") + + // x-mcp-header: an HTTP client drops tools with invalid annotations and mirrors annotated arguments into Mcp-Param-* headers + private val annotatedTools: io.circe.Json = io.circe.parser + .parse( + """{"tools":[ + |{"name":"weather","inputSchema":{"type":"object","properties":{ + | "region":{"type":"string","x-mcp-header":"Region"},"days":{"type":"integer","x-mcp-header":"Days"}, + | "verbose":{"type":"boolean","x-mcp-header":"Verbose"},"query":{"type":"string"}}}}, + |{"name":"broken","inputSchema":{"type":"object","properties":{"v":{"type":"string","x-mcp-header":"My Region"}}}} + |]}""".stripMargin + ) + .fold(throw _, identity) + + private def toolHeadersBackend(sent: java.util.concurrent.ConcurrentLinkedQueue[GenericRequest[?, ?]], connect: String) = + val call = CallToolResult(content = List(ToolContent.Text(text = "ok"))).asJson + SyncBackendStub + .whenRequestMatches(request => sent.add(request) && (envelopeFor("server/discover", request) || envelopeFor("initialize", request))) + .thenRespondAdjust(connect) + .whenRequestMatches(envelopeFor("tools/list", _)) + .thenRespondAdjust((JSONRPCMessage.Response(id = RequestId(2), result = annotatedTools): JSONRPCMessage).asJson.noSpaces) + .whenRequestMatches(envelopeFor("tools/call", _)) + .thenRespondAdjust((JSONRPCMessage.Response(id = RequestId(3), result = call): JSONRPCMessage).asJson.noSpaces) + .whenAnyRequest + .thenRespondAdjust("", StatusCode.Accepted) + + private val weatherArguments = io.circe.Json.obj( + "region" -> " Zürich".asJson, + "days" -> 3.asJson, + "verbose" -> io.circe.Json.Null, + "query" -> "rain".asJson + ) + + it should "drop tools with invalid x-mcp-header annotations and mirror annotated arguments into Mcp-Param headers" in: + val sent = java.util.concurrent.ConcurrentLinkedQueue[GenericRequest[?, ?]]() + val client = McpClient[Identity]( + ClientHttpTransport[Identity](toolHeadersBackend(sent, discoverEnvelope(List("2026-07-28"))), mcpUri), + clientInfo, + ProtocolVersion.Latest + ) + client.listTools().tools.map(_.name) shouldBe List("weather") + val _ = client.callTool("weather", weatherArguments) + val _ = client.callTool("zürich", io.circe.Json.obj()) + + val calls = sent.toArray(Array.empty[GenericRequest[?, ?]]).toList.filter(envelopeFor("tools/call", _)) + val weather = calls.head + weather.header("Mcp-Name") shouldBe Some("weather") + weather.header("Mcp-Param-Region") shouldBe Some("=?base64?IFrDvHJpY2g=?=") + weather.header("Mcp-Param-Days") shouldBe Some("3") + weather.header("Mcp-Param-Verbose") shouldBe None + weather.headers.map(_.name.toLowerCase).filter(_.startsWith("mcp-param-")).sorted shouldBe List("mcp-param-days", "mcp-param-region") + calls(1).header("Mcp-Name") shouldBe Some("=?base64?esO8cmljaA==?=") + + it should "leave legacy requests unchanged: no tool filtering and no Mcp headers" in: + val sent = java.util.concurrent.ConcurrentLinkedQueue[GenericRequest[?, ?]]() + val initResult = InitializeResult( + protocolVersion = ProtocolVersion.LatestLegacy.name, + capabilities = ServerCapabilities(tools = Some(ServerToolsCapability(listChanged = Some(false)))), + serverInfo = Implementation(name = "legacy-server", version = "1.0") + ) + val connect = (JSONRPCMessage.Response(id = RequestId(1), result = initResult.asJson): JSONRPCMessage).asJson.noSpaces + val client = McpClient[Identity](ClientHttpTransport[Identity](toolHeadersBackend(sent, connect), mcpUri), clientInfo) + client.listTools().tools.map(_.name) shouldBe List("weather", "broken") + val _ = client.callTool("weather", weatherArguments) + + val call = sent.toArray(Array.empty[GenericRequest[?, ?]]).toList.filter(envelopeFor("tools/call", _)).head + call.headers.map(_.name.toLowerCase).filter(name => name.startsWith("mcp-") && name != "mcp-protocol-version") shouldBe Nil diff --git a/client/src/test/scala/chimp/client/McpRequestHeadersSpec.scala b/client/src/test/scala/chimp/client/McpRequestHeadersSpec.scala new file mode 100644 index 00000000..96ba903d --- /dev/null +++ b/client/src/test/scala/chimp/client/McpRequestHeadersSpec.scala @@ -0,0 +1,64 @@ +package chimp.client + +import chimp.client.transport.McpRequestHeaders +import chimp.client.transport.McpRequestHeaders.Param +import io.circe.{parser, Json} +import org.scalatest.flatspec.AnyFlatSpec +import org.scalatest.matchers.should.Matchers + +class McpRequestHeadersSpec extends AnyFlatSpec with Matchers: + + private def schema(properties: String): Json = + parser.parse(s"""{"type":"object","properties":{$properties}}""").fold(throw _, identity) + + "encode" should "keep printable ASCII as it is, internal spaces included" in: + McpRequestHeaders.encode("us west 1") shouldBe "us west 1" + McpRequestHeaders.encode("") shouldBe "" + + it should "use the Base64 sentinel form for non-ASCII, control characters, leading or trailing whitespace and sentinel-like values" in: + McpRequestHeaders.encode("Hello, 世界") shouldBe "=?base64?SGVsbG8sIOS4lueVjA==?=" + McpRequestHeaders.encode(" padded ") shouldBe "=?base64?IHBhZGRlZCA=?=" + McpRequestHeaders.encode("us-west1 ") shouldBe "=?base64?dXMtd2VzdDEg?=" + McpRequestHeaders.encode("line1\nline2") shouldBe "=?base64?bGluZTEKbGluZTI=?=" + McpRequestHeaders.encode("\tindented") shouldBe "=?base64?CWluZGVudGVk?=" + McpRequestHeaders.encode("=?base64?abc?=") shouldBe "=?base64?PT9iYXNlNjQ/YWJjPz0=?=" + + "argumentValue" should "write booleans and integers as text, and give no value for null, arrays and objects" in: + McpRequestHeaders.argumentValue(Json.True) shouldBe Some("true") + McpRequestHeaders.argumentValue(Json.False) shouldBe Some("false") + McpRequestHeaders.argumentValue(Json.fromInt(42)) shouldBe Some("42") + McpRequestHeaders.argumentValue(Json.fromString("é")) shouldBe Some("=?base64?w6k=?=") + McpRequestHeaders.argumentValue(Json.Null) shouldBe None + McpRequestHeaders.argumentValue(Json.arr()) shouldBe None + McpRequestHeaders.argumentValue(Json.obj()) shouldBe None + + "params" should "find the annotated properties, nested ones through properties keys included" in: + val nested = schema( + """"region":{"type":"string","x-mcp-header":"Region"}, + |"limits":{"type":"object","properties":{"max":{"type":["integer","null"],"x-mcp-header":"Max"}}}, + |"query":{"type":"string"}""".stripMargin + ) + McpRequestHeaders.params(nested) shouldBe Right(List(Param(List("region"), "Region"), Param(List("limits", "max"), "Max"))) + + it should "reject empty, non-string, duplicate and non-token header names" in: + val invalid = List( + """"v":{"type":"string","x-mcp-header":""}""", + """"v":{"type":"string","x-mcp-header":7}""", + """"a":{"type":"string","x-mcp-header":"MyField"},"b":{"type":"string","x-mcp-header":"myfield"}""", + """"v":{"type":"string","x-mcp-header":"My Region"}""", + """"v":{"type":"string","x-mcp-header":"Region:Primary"}""", + """"v":{"type":"string","x-mcp-header":"Région"}""", + """"v":{"type":"string","x-mcp-header":"Region\t1"}""" + ) + all(invalid.map(properties => McpRequestHeaders.params(schema(properties)).isLeft)) shouldBe true + + it should "reject annotations on non-primitive or number properties, and off a plain properties chain" in: + val invalid = List( + """"v":{"type":"object","x-mcp-header":"Data"}""", + """"v":{"type":"array","items":{"type":"string"},"x-mcp-header":"Items"}""", + """"v":{"type":"null","x-mcp-header":"Nil"}""", + """"v":{"type":"number","x-mcp-header":"Ratio"}""", + """"v":{"type":"array","items":{"type":"string","x-mcp-header":"Item"}}""", + """"v":{"anyOf":[{"type":"string","x-mcp-header":"Choice"}]}""" + ) + all(invalid.map(properties => McpRequestHeaders.params(schema(properties)).isLeft)) shouldBe true diff --git a/conformance-baseline-2026-07-28.yml b/conformance-baseline-2026-07-28.yml index c7d87cfd..372f0f44 100644 --- a/conformance-baseline-2026-07-28.yml +++ b/conformance-baseline-2026-07-28.yml @@ -46,7 +46,5 @@ client: - auth/token-endpoint-auth-none - auth/token-endpoint-auth-post - auth/wif-jwt-bearer - # modern (2026-07-28) client era: HTTP headers from tool arguments — T12, #250; multi round-trip requests — T15 - - http-custom-headers - - http-invalid-tool-headers + # modern (2026-07-28) client era: multi round-trip requests — T15 - sep-2322-client-request-state diff --git a/docs/client/transport.md b/docs/client/transport.md index bf37d07d..fb8a5465 100644 --- a/docs/client/transport.md +++ b/docs/client/transport.md @@ -42,8 +42,27 @@ At the stateless version `2026-07-28`, the HTTP transports: - send `MCP-Protocol-Version` equal to the version in the `_meta` of the request - send the `Mcp-Method` header, and `Mcp-Name` on `tools/call`, `prompts/get` and `resources/read` +- mirror tool arguments into `Mcp-Param-*` headers (see below) - open no GET stream for server messages +Legacy requests do not get these headers, and the STDIO transports send no headers. + +### Headers from tool arguments + +A tool can mark a property of its input schema with `x-mcp-header`. A `tools/list` result shows the HTTP transport these annotations. When you then call that tool, the transport sends each annotated argument in the header `Mcp-Param-`: + +| Argument | Header value | +|---|---| +| a string of printable ASCII, without leading or trailing whitespace | the string | +| any other string | `=?base64??=` | +| a boolean | `true` or `false` | +| an integer | its JSON text | +| `null`, or no argument | no header | + +`Mcp-Name` uses the same rule for strings. Call `listTools` before `callTool`: the transport knows the annotations of a tool only from a `tools/list` result. + +The transport removes a tool from the `tools/list` result, and logs a warning, when its `x-mcp-header` annotations are invalid: a value that is empty, not a string or not an HTTP token (for example, with spaces, colons, non-ASCII or control characters), the same name on two properties (names are case-insensitive), or an annotation on a property that is not a string, integer or boolean, or that is not reachable through `properties` keys only. The other tools stay in the result. + ## Streaming integrations The streaming transports have concrete implementations per effect system, in separate modules: diff --git a/server/src/test/scala/chimp/server/McpServerStreamingTests.scala b/server/src/test/scala/chimp/server/McpServerStreamingTests.scala index c085e7b7..525447c6 100644 --- a/server/src/test/scala/chimp/server/McpServerStreamingTests.scala +++ b/server/src/test/scala/chimp/server/McpServerStreamingTests.scala @@ -44,7 +44,33 @@ trait McpServerStreamingTests[F[_]] extends AsyncFlatSpec with Matchers: yield ToolResult.text("done") ) - "a streaming MCP server" should "deliver log notifications to a client with the log level option, at a legacy and a modern version" in + private case class RegionInput(region: String, limit: Option[Int]) derives Codec, Schema + + private val headerServer: StreamingMcpServer[F] = + McpServer[F]() + .addTool( + tool("region") + .input[RegionInput] + .withMcpHeader("region", "Region") + .withMcpHeader("limit", "Limit") + .serverLogic[F]((in, _) => monad.unit(ToolResult.text(s"region ${in.region} ${in.limit}"))) + ) + .streaming + + "a streaming MCP server" should "serve a client that mirrors x-mcp-header arguments into Mcp-Param headers, with Base64 values" in + withStreamingServer(headerServer): client => + client + .listTools() + .flatMap(_ => client.callTool("region", Json.obj("region" -> Json.fromString(" Zürich"), "limit" -> Json.fromInt(5)))) + .flatMap: first => + client + .callTool("region", Json.obj("region" -> Json.fromString("eu"), "limit" -> Json.Null)) + .map: second => + List(first, second).map(_.isError) shouldBe List(false, false) + first.content shouldBe List(ToolContent.Text("text", "region Zürich Some(5)")) + second.content shouldBe List(ToolContent.Text("text", "region eu None")) + + it should "deliver log notifications to a client with the log level option, at a legacy and a modern version" in withLoggingStreamingServer(streamingServer, LoggingLevel.Info): client => val messages = ConcurrentLinkedQueue[Json]() client From e2895584a6af5d85c9bce84a50f1daa8900ff12d Mon Sep 17 00:00:00 2001 From: Ondra Pelech Date: Thu, 19 Nov 2026 23:02:43 +0100 Subject: [PATCH 30/31] feat(T11): detect the server era by default McpClient's protocolVersion parameter is now a VersionPolicy: a fixed ProtocolVersion (as before, no detection) or DetectVersion, the new default. Code that passes a ProtocolVersion compiles unchanged. With DetectVersion the first request is server/discover at 2026-07-28, over HTTP and stdio. A discover result or a stateless error (-32020, -32021, -32022) means a modern server: the client uses the stateless wire and negotiates on -32022. Any other outcome (another JSON-RPC error, an HTTP error without a modern body, a failed send, a timeout, a result that is not a discover result) means a legacy server: the client sends initialize at 2025-11-25. A modern server that lists only a common legacy version gets initialize at that version; one that shares no version fails with McpUnsupportedProtocolVersionException naming both lists. The decision is made once per client. The streaming HTTP transports no longer let the response to server/discover start their GET listener, so a legacy server's GET stream opens after initialize, with its session. The ZIO listener is forked interruptibly: ZioClientHttpTransport.scoped acquires the transport uninterruptibly, and a listener that never saw a session kept the scope from closing. Tests cover the compatibility matrix (modern, legacy and dual-era clients against modern, legacy and dual-era servers) and the detection outcomes; the integration tests against the legacy everything server pass with the default policy. --- .../transport/ox/OxClientHttpTransport.scala | 8 +- .../pekko/PekkoClientHttpTransport.scala | 9 +- .../zio/ZioClientHttpTransport.scala | 10 +- .../main/scala/chimp/client/McpClient.scala | 14 +- .../scala/chimp/client/McpClientImpl.scala | 116 +++++++--- .../scala/chimp/client/VersionPolicy.scala | 9 + .../transport/ClientHttpTransport.scala | 7 + .../chimp/client/CapabilityHandlerSpec.scala | 6 +- .../client/McpClientEraDetectionSpec.scala | 201 ++++++++++++++++++ .../scala/chimp/client/McpClientSpec.scala | 6 +- .../chimp/client/McpClientStatelessSpec.scala | 8 +- docs/client/protocol.md | 18 +- docs/client/transport.md | 2 +- .../examples/client/everythingClient.scala | 6 +- .../server/pekko/PekkoMcpServerHttpSpec.scala | 8 +- 15 files changed, 367 insertions(+), 61 deletions(-) create mode 100644 client/src/main/scala/chimp/client/VersionPolicy.scala create mode 100644 client/src/test/scala/chimp/client/McpClientEraDetectionSpec.scala diff --git a/client-streaming/client-ox/src/main/scala/chimp/client/transport/ox/OxClientHttpTransport.scala b/client-streaming/client-ox/src/main/scala/chimp/client/transport/ox/OxClientHttpTransport.scala index 650b1c5d..d569ccd4 100644 --- a/client-streaming/client-ox/src/main/scala/chimp/client/transport/ox/OxClientHttpTransport.scala +++ b/client-streaming/client-ox/src/main/scala/chimp/client/transport/ox/OxClientHttpTransport.scala @@ -88,7 +88,7 @@ final class OxClientHttpTransport private ( private def sendRequest(request: JSONRPCMessage.Request, await: () => JSONRPCMessage): Option[JSONRPCMessage] = val response = post(request) - captureSession(response) + captureSession(response, request) ClientHttpTransport.resolveResponse(response, state.ask(_.sessionId)) match case Left(err: McpSessionNotFoundException) => state.tell(_.sessionId = None); throw err case Left(err) => throw err @@ -110,7 +110,7 @@ final class OxClientHttpTransport private ( private def sendNonRequest(msg: JSONRPCMessage): Option[JSONRPCMessage] = val response = post(msg) - captureSession(response) + captureSession(response, msg) ClientHttpTransport.resolveResponse(response, state.ask(_.sessionId)) match case Left(err: McpSessionNotFoundException) => state.tell(_.sessionId = None); throw err case Left(err) => throw err @@ -131,9 +131,9 @@ final class OxClientHttpTransport private ( .response(asInputStreamUnsafe) .send(backend) - private def captureSession(response: Response[?]): Unit = + private def captureSession(response: Response[?], msg: JSONRPCMessage): Unit = response.header("Mcp-Session-Id").foreach(id => state.tell(_.sessionId = Some(id))) - sessionReady.countDown() + if ClientHttpTransport.readiesGetStream(msg) then sessionReady.countDown() private def collectBody(response: Response[Either[String, InputStream]]): String = response.body match diff --git a/client-streaming/client-pekko/src/main/scala/chimp/client/transport/pekko/PekkoClientHttpTransport.scala b/client-streaming/client-pekko/src/main/scala/chimp/client/transport/pekko/PekkoClientHttpTransport.scala index 488899a2..ccf3c67a 100644 --- a/client-streaming/client-pekko/src/main/scala/chimp/client/transport/pekko/PekkoClientHttpTransport.scala +++ b/client-streaming/client-pekko/src/main/scala/chimp/client/transport/pekko/PekkoClientHttpTransport.scala @@ -147,7 +147,7 @@ final class PekkoClientHttpTransport private ( private def sendRequest(request: JSONRPCMessage.Request, await: () => Future[JSONRPCMessage]): Future[Option[JSONRPCMessage]] = post(request).flatMap: response => - captureSession(response).flatMap: session => + captureSession(response, request).flatMap: session => ClientHttpTransport.resolveResponse(response, session) match case Left(err: McpSessionNotFoundException) => state.tell(_.sessionId = None) @@ -176,7 +176,7 @@ final class PekkoClientHttpTransport private ( private def sendNonRequest(msg: JSONRPCMessage): Future[Option[JSONRPCMessage]] = post(msg).flatMap: response => - captureSession(response).flatMap: session => + captureSession(response, msg).flatMap: session => ClientHttpTransport.resolveResponse(response, session) match case Left(err: McpSessionNotFoundException) => state.tell(_.sessionId = None) @@ -204,11 +204,12 @@ final class PekkoClientHttpTransport private ( .response(asStreamUnsafe(PekkoStreams)) .send(backend) - private def captureSession(response: Response[?]): Future[Option[String]] = + private def captureSession(response: Response[?], msg: JSONRPCMessage): Future[Option[String]] = state .ask(_.captureSessionId(response.header("Mcp-Session-Id"))) .map: session => - val _ = sessionReady.trySuccess(()) + if ClientHttpTransport.readiesGetStream(msg) then + val _ = sessionReady.trySuccess(()) session private def collectBody(response: Response[Either[String, Source[ByteString, Any]]]): Future[String] = diff --git a/client-streaming/client-zio/src/main/scala/chimp/client/transport/zio/ZioClientHttpTransport.scala b/client-streaming/client-zio/src/main/scala/chimp/client/transport/zio/ZioClientHttpTransport.scala index bc0679ac..918a6842 100644 --- a/client-streaming/client-zio/src/main/scala/chimp/client/transport/zio/ZioClientHttpTransport.scala +++ b/client-streaming/client-zio/src/main/scala/chimp/client/transport/zio/ZioClientHttpTransport.scala @@ -74,7 +74,7 @@ final class ZioClientHttpTransport private ( private def sendRequest(request: JSONRPCMessage.Request, await: () => Task[JSONRPCMessage]): Task[Option[JSONRPCMessage]] = post(request).flatMap: resp => - captureSession(resp) *> + captureSession(resp, request) *> sessionRef.get.flatMap: session => ClientHttpTransport.resolveResponse(resp, session) match case Left(err: McpSessionNotFoundException) => @@ -97,7 +97,7 @@ final class ZioClientHttpTransport private ( private def sendNonRequest(msg: JSONRPCMessage): Task[Option[JSONRPCMessage]] = post(msg).flatMap: response => - captureSession(response) *> + captureSession(response, msg) *> sessionRef.get.flatMap: session => ClientHttpTransport.resolveResponse(response, session) match case Left(err: McpSessionNotFoundException) => @@ -120,11 +120,11 @@ final class ZioClientHttpTransport private ( .response(asStreamUnsafe(ZioStreams)) .send(backend) - private def captureSession(response: Response[?]): Task[Unit] = + private def captureSession(response: Response[?], msg: JSONRPCMessage): Task[Unit] = val maybeUpdate = response.header("Mcp-Session-Id") match case Some(id) => sessionRef.set(Some(id)) case None => ZIO.unit - maybeUpdate *> sessionReady.succeed(()).unit + maybeUpdate *> sessionReady.succeed(()).when(ClientHttpTransport.readiesGetStream(msg)).unit private def collectBody(response: Response[Either[String, Stream[Throwable, Byte]]]): Task[String] = response.body match @@ -201,7 +201,7 @@ final class ZioClientHttpTransport private ( case None => ZIO.unit case Some(stream) => streamWithResume(stream, lastEventId, closingRef.get.map(!_)) val listener = sessionReady.await *> protocolVersion.get.flatMap(version => listen.unless(version.isModern).unit) - listener.catchAll(t => warnUnlessClosing(s"GET listener failed: ${t.getMessage}")).forkIn(scope).unit + listener.catchAll(t => warnUnlessClosing(s"GET listener failed: ${t.getMessage}")).interruptible.forkIn(scope).unit private def streamWithResume( stream: Stream[Throwable, Byte], diff --git a/client/src/main/scala/chimp/client/McpClient.scala b/client/src/main/scala/chimp/client/McpClient.scala index abbe1d8c..c4e9d49e 100644 --- a/client/src/main/scala/chimp/client/McpClient.scala +++ b/client/src/main/scala/chimp/client/McpClient.scala @@ -15,8 +15,8 @@ import io.circe.Json * [[BidirectionalMcpClient]] instead. */ trait McpClient[F[_]]: - /** The protocol version that the client uses. At a stateless version it can change once, when the server rejects the version with - * `-32022` and the client retries with a version from the server's list. + /** The protocol version that the client uses: the fixed version, or the detected one. At a stateless version it can change when the + * server rejects the version with `-32022` and the client retries with a version from the server's list. */ def protocolVersion: ProtocolVersion @@ -134,8 +134,10 @@ object McpClient: * @param clientInfo * Implementation name and version sent to the server. * @param protocolVersion - * The protocol version of the client; the client gives it to the transport. A legacy version runs the `initialize` handshake, a - * stateless version (2026-07-28) calls `server/discover`. Defaults to the latest legacy version. + * How the client chooses its protocol version; the client gives the version to the transport. With [[DetectVersion]], the default, the + * client sends `server/discover` first and falls back to `initialize` at the latest legacy version when the server is legacy. A fixed + * [[chimp.protocol.ProtocolVersion]] skips the detection: a legacy version runs the `initialize` handshake, a stateless version + * (2026-07-28) calls `server/discover`. * @param logLevel * The minimum level of the log messages the server sends. At a stateless version every request carries it in `_meta`; at a legacy * version the client sends `logging/setLevel` once after `initialize`. Without it the server sends no log messages. @@ -143,7 +145,7 @@ object McpClient: def apply[F[_]]( transport: ClientTransport[F], clientInfo: Implementation, - protocolVersion: ProtocolVersion = ProtocolVersion.LatestLegacy, + protocolVersion: VersionPolicy = DetectVersion, logLevel: Option[LoggingLevel] = None ): F[McpClient[F]] = McpClientImpl.create(transport, clientInfo, protocolVersion, logLevel) @@ -173,7 +175,7 @@ object McpClient: rootsHandler: Option[() => F[ListRootsResult]] = None, samplingHandler: Option[CreateMessageRequest => F[CreateMessageResult]] = None, elicitationHandler: Option[ElicitRequest => F[ElicitResult]] = None, - protocolVersion: ProtocolVersion = ProtocolVersion.LatestLegacy, + protocolVersion: VersionPolicy = DetectVersion, logLevel: Option[LoggingLevel] = None ): F[BidirectionalMcpClient[F]] = McpClientImpl.createBidirectional(transport, clientInfo, protocolVersion, logLevel, rootsHandler, samplingHandler, elicitationHandler) diff --git a/client/src/main/scala/chimp/client/McpClientImpl.scala b/client/src/main/scala/chimp/client/McpClientImpl.scala index 150a8c6d..bdd68a83 100644 --- a/client/src/main/scala/chimp/client/McpClientImpl.scala +++ b/client/src/main/scala/chimp/client/McpClientImpl.scala @@ -10,23 +10,24 @@ import sttp.monad.MonadError import sttp.monad.syntax.* import java.util.concurrent.atomic.AtomicReference +import scala.util.control.NonFatal object McpClientImpl: def create[F[_]]( transport: ClientTransport[F], clientInfo: Implementation, - protocolVersion: ProtocolVersion, + policy: VersionPolicy, logLevel: Option[LoggingLevel], correlator: Correlator = UUIDCorrelator() ): F[McpClient[F]] = given MonadError[F] = transport.monad - val requests = Requests(transport, clientInfo, ClientCapabilities(), logLevel, correlator, protocolVersion) - connect(requests).map(server => new Impl[F](transport, requests, server)) + val requests = Requests(transport, clientInfo, ClientCapabilities(), logLevel, correlator, initialVersion(policy)) + connect(requests, policy).map(server => new Impl[F](transport, requests, server)) def createBidirectional[F[_]]( transport: ClientBidirectionalTransport[F], clientInfo: Implementation, - protocolVersion: ProtocolVersion, + policy: VersionPolicy, logLevel: Option[LoggingLevel], rootsHandler: Option[() => F[ListRootsResult]], samplingHandler: Option[CreateMessageRequest => F[CreateMessageResult]], @@ -39,7 +40,7 @@ object McpClientImpl: sampling = samplingHandler.map(_ => Json.obj()), elicitation = elicitationHandler.map(_ => Json.obj()) ) - val requests = Requests(transport, clientInfo, clientCapabilities, logLevel, correlator, protocolVersion) + val requests = Requests(transport, clientInfo, clientCapabilities, logLevel, correlator, initialVersion(policy)) val serverNotificationListeners = AtomicReference[List[ServerNotificationListener[F]]](Nil) val serverInitiatedRequestHandlers = buildServerInitiatedRequestHandlers(rootsHandler, samplingHandler, elicitationHandler) val incomingHandler = buildIncomingHandler(transport, serverInitiatedRequestHandlers, serverNotificationListeners) @@ -47,33 +48,76 @@ object McpClientImpl: transport .onIncoming(incomingHandler) .flatMap: _ => - connect(requests).map: server => + connect(requests, policy).map: server => new BidirectionalImpl[F](transport, requests, server, serverNotificationListeners) /** What the client learns about the server when it connects. */ private final case class ConnectedServer(capabilities: ServerCapabilities, serverInfo: Implementation) + private def initialVersion(policy: VersionPolicy): ProtocolVersion = policy match + case DetectVersion => ProtocolVersion.Latest + case version: ProtocolVersion => version + /** Legacy versions run the `initialize` handshake; a stateless (2026-07-28) version has no handshake and asks `server/discover`. */ - private def connect[F[_]](requests: Requests[F]): F[ConnectedServer] = + private def connect[F[_]](requests: Requests[F], policy: VersionPolicy): F[ConnectedServer] = given MonadError[F] = requests.monad - requests.transport - .setProtocolVersion(requests.protocolVersion) + requests + .useVersion(requests.protocolVersion) .flatMap: _ => - if requests.protocolVersion.isModern then discoverServer(requests) - else initialize(requests) + policy match + case DetectVersion => detect(requests) + case version: ProtocolVersion if version.isModern => requests.discover().flatMap(useDiscovered(requests, _)) + case _: ProtocolVersion => initialize(requests) - /** A discover result that does not list the client's version switches to the newest common stateless version, or fails. */ - private def discoverServer[F[_]](requests: Requests[F]): F[ConnectedServer] = + /** The first request is `server/discover`. A discover result or a stateless error (`-32020`, `-32021`, `-32022`) means a modern server; + * any other outcome, a failed send included, means a legacy server, and the client sends `initialize` at the latest legacy version. + */ + private def detect[F[_]](requests: Requests[F]): F[ConnectedServer] = given monad: MonadError[F] = requests.monad requests - .discover() - .flatMap: discovered => - val supported = discovered.result.supportedVersions - if supported.contains(requests.protocolVersion.name) then monad.unit(discovered.server) - else + .probe("server/discover") + .flatMap: + case Some(Right(result)) => + discoveredOf(result) match + case Some(discovered) if retryVersion(discovered.result.supportedVersions).isDefined => useDiscovered(requests, discovered) + case Some(discovered) => fallBack(requests, discovered.result.supportedVersions) + case None => legacy(requests) + case Some(Left(error)) if error.code == JSONRPCErrorCodes.UnsupportedProtocolVersion.code => + val supported = supportedOf(error) retryVersion(supported) match - case Some(next) => requests.useVersion(next).flatMap(_ => requests.discover()).map(_.server) - case None => monad.error(McpUnsupportedProtocolVersionException(supported, statelessVersions)) + case Some(next) => + requests.useVersion(next).flatMap(_ => requests.discover(negotiate = false)).flatMap(useDiscovered(requests, _)) + case None => fallBack(requests, supported) + case Some(Left(error)) if StatelessErrors.contains(error.code) => + monad.error(McpProtocolException(s"server/discover failed: ${error.code} ${error.message}")) + case _ => legacy(requests) + + private def legacy[F[_]](requests: Requests[F]): F[ConnectedServer] = + given MonadError[F] = requests.monad + requests.useVersion(ProtocolVersion.LatestLegacy).flatMap(_ => initialize(requests)) + + /** A modern server that lists no common stateless version: `initialize` at the newest common legacy version, or fail. */ + private def fallBack[F[_]](requests: Requests[F], supported: List[String]): F[ConnectedServer] = + given monad: MonadError[F] = requests.monad + supported.flatMap(ProtocolVersion.from).filterNot(_.isModern).maxOption match + case Some(legacy) => requests.useVersion(legacy).flatMap(_ => initialize(requests)) + case None => monad.error(McpUnsupportedProtocolVersionException(supported, ProtocolVersion.supported.map(_.name))) + + private val StatelessErrors: Set[Int] = Set( + JSONRPCErrorCodes.HeaderMismatch.code, + JSONRPCErrorCodes.MissingRequiredClientCapability.code, + JSONRPCErrorCodes.UnsupportedProtocolVersion.code + ) + + /** A discover result that does not list the client's version switches to the newest common stateless version, or fails. */ + private def useDiscovered[F[_]](requests: Requests[F], discovered: Discovered): F[ConnectedServer] = + given monad: MonadError[F] = requests.monad + val supported = discovered.result.supportedVersions + if supported.contains(requests.protocolVersion.name) then monad.unit(discovered.server) + else + retryVersion(supported) match + case Some(next) => requests.useVersion(next).flatMap(_ => requests.discover(negotiate = false)).map(_.server) + case None => monad.error(McpUnsupportedProtocolVersionException(supported, statelessVersions)) /** Sends requests and turns their responses into results. On the stateless wire it stamps `_meta` on every request, and on `-32022` it * retries once with a version that both sides support. @@ -100,19 +144,32 @@ object McpClientImpl: def send[R: Decoder](method: String, params: Option[Json]): F[R] = sendForResult(method, params).flatMap(decode[R](method, _)) - def discover(): F[Discovered] = - sendForResult("server/discover", None).flatMap: result => - decode[DiscoverResult]("server/discover", result).map(discovered => Discovered(discovered, serverInfoOf(result, discovered))) + def discover(negotiate: Boolean = true): F[Discovered] = + sendForResult("server/discover", None, negotiate).flatMap(discovered) + + private def discovered(result: Json): F[Discovered] = + decode[DiscoverResult]("server/discover", result).map(discovered => Discovered(discovered, serverInfoOf(result, discovered))) + + /** One request with no version negotiation: the result or the error, or `None` when the send fails or brings no response. */ + def probe(method: String): F[Option[Either[JSONRPCErrorObject, Json]]] = + val request = JSONRPCMessage.Request(method = method, params = stamp(None, protocolVersion), id = nextId()) + transport + .send(request) + .flatMap: + case Some(JSONRPCMessage.Response(_, _, result)) => checkResultType(method, result).map(result => Some(Right(result))) + case Some(JSONRPCMessage.Error(_, _, error)) => monad.unit(Some(Left(error))) + case _ => monad.unit(None) + .handleError { case NonFatal(_) => monad.unit(None) } def notify(method: String, params: Option[Json]): F[Unit] = transport.send(JSONRPCMessage.Notification(method = method, params = params)).map(_ => ()) - private def sendForResult(method: String, params: Option[Json]): F[Json] = + private def sendForResult(method: String, params: Option[Json], negotiate: Boolean = true): F[Json] = val sentWith = protocolVersion attempt(method, params, sentWith).flatMap: case Right(result) => monad.unit(result) case Left(supported) => - retryVersion(supported) match + retryVersion(supported).filter(_ => negotiate) match case None => monad.error(McpUnsupportedProtocolVersionException(supported, statelessVersions)) case Some(next) => useVersion(next) @@ -131,7 +188,7 @@ object McpClientImpl: checkResultType(method, result).map(Right(_)) case Some(JSONRPCMessage.Error(_, _, error)) if sentWith.isModern && error.code == JSONRPCErrorCodes.UnsupportedProtocolVersion.code => - monad.unit(Left(error.data.flatMap(_.hcursor.get[List[String]]("supported").toOption).getOrElse(Nil))) + monad.unit(Left(supportedOf(error))) case Some(JSONRPCMessage.Error(_, _, error)) => monad.error(McpProtocolException(s"$method failed: ${error.code} ${error.message}")) case Some(other) => @@ -168,12 +225,19 @@ object McpClientImpl: case Right(response) => monad.unit(response) case Left(error) => monad.error(McpProtocolException(s"Failed to decode $method result: ${error.getMessage}")) + /** The versions that a `-32022` error names. */ + private def supportedOf(error: JSONRPCErrorObject): List[String] = + error.data.flatMap(_.hcursor.get[List[String]]("supported").toOption).getOrElse(Nil) + private val statelessVersions: List[String] = ProtocolVersion.supported.filter(_.isModern).map(_.name) /** The newest stateless version that chimp shares with a server's `supported` list. */ private def retryVersion(supported: List[String]): Option[ProtocolVersion] = supported.flatMap(ProtocolVersion.from).filter(_.isModern).maxOption + private def discoveredOf(result: Json): Option[Discovered] = + result.as[DiscoverResult].toOption.map(discovered => Discovered(discovered, serverInfoOf(result, discovered))) + private final case class Discovered(result: DiscoverResult, serverInfo: Implementation): def server: ConnectedServer = ConnectedServer(result.capabilities, serverInfo) diff --git a/client/src/main/scala/chimp/client/VersionPolicy.scala b/client/src/main/scala/chimp/client/VersionPolicy.scala new file mode 100644 index 00000000..1fc71113 --- /dev/null +++ b/client/src/main/scala/chimp/client/VersionPolicy.scala @@ -0,0 +1,9 @@ +package chimp.client + +import chimp.protocol.ProtocolVersion + +/** Makes a client detect the era of the server: it sends `server/discover` first, and sends `initialize` when the server is legacy. */ +case object DetectVersion + +/** How a client chooses its protocol version: a fixed [[chimp.protocol.ProtocolVersion]], with no detection, or [[DetectVersion]]. */ +type VersionPolicy = ProtocolVersion | DetectVersion.type diff --git a/client/src/main/scala/chimp/client/transport/ClientHttpTransport.scala b/client/src/main/scala/chimp/client/transport/ClientHttpTransport.scala index 06420a7f..3c55d976 100644 --- a/client/src/main/scala/chimp/client/transport/ClientHttpTransport.scala +++ b/client/src/main/scala/chimp/client/transport/ClientHttpTransport.scala @@ -87,6 +87,13 @@ object ClientHttpTransport: case SseBody case ErrorBody(status: StatusCode) + /** Whether the response to `msg` lets a streaming transport open its GET stream. The response to `server/discover` does not: with era + * detection the client sends it before it knows the era, and before a legacy server gives a session. + */ + private[transport] def readiesGetStream(msg: JSONRPCMessage): Boolean = msg match + case JSONRPCMessage.Request(_, "server/discover", _, _) => false + case _ => true + /** The version an HTTP transport sends until the client sets one. */ private[transport] val DefaultProtocolVersion: ProtocolVersion = ProtocolVersion.LatestLegacy diff --git a/client/src/test/scala/chimp/client/CapabilityHandlerSpec.scala b/client/src/test/scala/chimp/client/CapabilityHandlerSpec.scala index d5b82655..7978849c 100644 --- a/client/src/test/scala/chimp/client/CapabilityHandlerSpec.scala +++ b/client/src/test/scala/chimp/client/CapabilityHandlerSpec.scala @@ -25,6 +25,7 @@ class CapabilityHandlerSpec extends AnyFlatSpec with Matchers: val _ = McpClient.bidirectional[Identity]( transport, clientInfo, + protocolVersion = ProtocolVersion.LatestLegacy, rootsHandler = Some(() => ListRootsResult(roots = List(Root(uri = "file:///x", name = Some("x"))))) ) @@ -42,7 +43,7 @@ class CapabilityHandlerSpec extends AnyFlatSpec with Matchers: it should "respond with MethodNotFound for capabilities the client didn't opt into" in: val transport = InMemoryTransport() planInitResponse(transport) - val _ = McpClient.bidirectional[Identity](transport, clientInfo) + val _ = McpClient.bidirectional[Identity](transport, clientInfo, protocolVersion = ProtocolVersion.LatestLegacy) val request: JSONRPCMessage = JSONRPCMessage.Request(method = "sampling/createMessage", id = RequestId("server-2")) transport.simulateIncoming(request) @@ -54,7 +55,7 @@ class CapabilityHandlerSpec extends AnyFlatSpec with Matchers: it should "deliver incoming notifications to registered listeners" in: val transport = InMemoryTransport() planInitResponse(transport) - val client = McpClient.bidirectional[Identity](transport, clientInfo) + val client = McpClient.bidirectional[Identity](transport, clientInfo, protocolVersion = ProtocolVersion.LatestLegacy) var received: Option[ServerNotification] = None val listener: ServerNotificationListener[Identity] = n => { received = Some(n); () } val _ = client.onServerNotification(listener) @@ -71,6 +72,7 @@ class CapabilityHandlerSpec extends AnyFlatSpec with Matchers: val _ = McpClient.bidirectional[Identity]( transport, clientInfo, + protocolVersion = ProtocolVersion.LatestLegacy, rootsHandler = Some(() => ListRootsResult(roots = Nil)), elicitationHandler = Some((_: ElicitRequest) => ElicitResult(action = ElicitAction.Cancel)) ) diff --git a/client/src/test/scala/chimp/client/McpClientEraDetectionSpec.scala b/client/src/test/scala/chimp/client/McpClientEraDetectionSpec.scala new file mode 100644 index 00000000..bbae0177 --- /dev/null +++ b/client/src/test/scala/chimp/client/McpClientEraDetectionSpec.scala @@ -0,0 +1,201 @@ +package chimp.client + +import chimp.client.transport.ClientTransport +import chimp.protocol.* +import io.circe.Json +import io.circe.syntax.* +import org.scalatest.flatspec.AnyFlatSpec +import org.scalatest.matchers.should.Matchers +import sttp.monad.{IdentityMonad, MonadError} +import sttp.shared.Identity + +import scala.collection.mutable +import scala.concurrent.duration.Duration + +class McpClientEraDetectionSpec extends AnyFlatSpec with Matchers: + + private val clientInfo = Implementation(name = "chimp-test", version = "0.0.1") + private val tools = ServerCapabilities(tools = Some(ServerToolsCapability(listChanged = Some(false)))) + + /** A transport whose server answers each request with `answer`; a `Left` fails the send, as a transport error does. */ + private final class ScriptedServer(answer: JSONRPCMessage.Request => Either[Throwable, JSONRPCMessage]) extends ClientTransport[Identity]: + given monad: MonadError[Identity] = IdentityMonad + val methods: mutable.ListBuffer[String] = mutable.ListBuffer.empty + val versions: mutable.ListBuffer[ProtocolVersion] = mutable.ListBuffer.empty + + override def send(msg: JSONRPCMessage): Identity[Option[JSONRPCMessage]] = msg match + case request: JSONRPCMessage.Request => + methods += request.method + answer(request).fold(throw _, Some(_)) + case JSONRPCMessage.Notification(_, method, _) => + methods += method + None + case _ => None + + override def close(): Identity[Unit] = () + + override def setProtocolVersion(version: ProtocolVersion): Identity[Unit] = versions += version + + private def result(request: JSONRPCMessage.Request, json: Json): Either[Throwable, JSONRPCMessage] = + Right(JSONRPCMessage.Response(id = request.id, result = json)) + + private def error(request: JSONRPCMessage.Request, error: JSONRPCErrorObject): Either[Throwable, JSONRPCMessage] = + Right(JSONRPCMessage.Error(id = request.id, error = error)) + + private def methodNotFound(request: JSONRPCMessage.Request) = + error(request, JSONRPCErrorObject(JSONRPCErrorCodes.MethodNotFound.code, s"Method not found: ${request.method}")) + + private def discoverResult(supported: List[ProtocolVersion]): Json = + DiscoverResult( + supportedVersions = supported.map(_.name), + capabilities = tools, + ttlMs = Duration.Zero, + cacheScope = CacheScope.Private, + _meta = Some(Map(ProtocolMeta.ServerInfo -> Implementation("modern", "1").asJson)) + ).asJson.deepDropNullValues + + private def initializeResult(version: ProtocolVersion): Json = + InitializeResult(protocolVersion = version.name, capabilities = tools, serverInfo = Implementation("legacy", "1")).asJson + + private def stateless(request: JSONRPCMessage.Request): Boolean = + request.params.flatMap(_.hcursor.downField("_meta").get[String](ProtocolMeta.ProtocolVersionKey).toOption).isDefined + + private val callResult = CallToolResult(content = List(ToolContent.Text(text = "ok"))).asJson + + /** Serves only 2026-07-28: it has no `initialize`, and it rejects a request without `_meta`. */ + private def modernServer = ScriptedServer: request => + request.method match + case "server/discover" => result(request, discoverResult(List(ProtocolVersion.Latest))) + case "initialize" => methodNotFound(request) + case _ if stateless(request) => result(request, callResult) + case _ => error(request, JSONRPCErrorObject(JSONRPCErrorCodes.InvalidRequest.code, "no _meta")) + + /** Serves only 2025-11-25: `server/discover` is an unknown method. */ + private def legacyServer = ScriptedServer: request => + request.method match + case "initialize" => result(request, initializeResult(ProtocolVersion.LatestLegacy)) + case "tools/call" => result(request, callResult) + case _ => methodNotFound(request) + + /** Serves both eras. */ + private def dualServer = ScriptedServer: request => + request.method match + case "server/discover" => result(request, discoverResult(List(ProtocolVersion.Latest, ProtocolVersion.LatestLegacy))) + case "initialize" => result(request, initializeResult(ProtocolVersion.LatestLegacy)) + case _ => result(request, callResult) + + private val modernClient: VersionPolicy = ProtocolVersion.Latest + private val legacyClient: VersionPolicy = ProtocolVersion.LatestLegacy + private val dualClient: VersionPolicy = DetectVersion + + private def connect(server: ScriptedServer, policy: VersionPolicy): McpClient[Identity] = + McpClient[Identity](server, clientInfo, policy) + + "The compatibility matrix" should "connect a modern client to a modern server on the stateless wire" in: + val server = modernServer + connect(server, modernClient).protocolVersion shouldBe ProtocolVersion.Latest + server.methods.toList shouldBe List("server/discover") + + it should "fail a modern client against a legacy server" in: + val ex = intercept[McpProtocolException](connect(legacyServer, modernClient)) + ex.getMessage should include("server/discover failed") + + it should "fail a legacy client against a modern server as today" in: + val ex = intercept[McpProtocolException](connect(modernServer, legacyClient)) + ex.getMessage should include("Initialize failed") + + it should "connect a legacy client to a legacy server with initialize" in: + val server = legacyServer + connect(server, legacyClient).protocolVersion shouldBe ProtocolVersion.LatestLegacy + server.methods.toList shouldBe List("initialize", "notifications/initialized") + + it should "connect a dual-era client to a modern server on the stateless wire" in: + val server = modernServer + val client = connect(server, dualClient) + client.protocolVersion shouldBe ProtocolVersion.Latest + client.callTool("echo", Json.obj()).isError shouldBe false + server.methods.toList shouldBe List("server/discover", "tools/call") + + it should "connect a dual-era client to a legacy server with initialize at the latest legacy version, and decide only once" in: + val server = legacyServer + val client = connect(server, dualClient) + client.protocolVersion shouldBe ProtocolVersion.LatestLegacy + client.callTool("echo", Json.obj()).isError shouldBe false + client.callTool("echo", Json.obj()).isError shouldBe false + server.methods.toList shouldBe List("server/discover", "initialize", "notifications/initialized", "tools/call", "tools/call") + server.versions.last shouldBe ProtocolVersion.LatestLegacy + + it should "connect a dual-era client to a dual-era server on the stateless wire" in: + val server = dualServer + connect(server, dualClient).protocolVersion shouldBe ProtocolVersion.Latest + server.methods.toList shouldBe List("server/discover") + + it should "connect fixed-version clients to a dual-era server at their version" in: + connect(dualServer, modernClient).protocolVersion shouldBe ProtocolVersion.Latest + connect(dualServer, legacyClient).protocolVersion shouldBe ProtocolVersion.LatestLegacy + + "Era detection" should "decide legacy on a failed send, such as an HTTP 400, 404 or 405 without a modern error, or a timeout" in: + val failures = List(McpTransportException("Unexpected HTTP response: 405"), McpTimeoutException(RequestId(1))) + failures.foreach: failure => + val server = ScriptedServer: request => + request.method match + case "server/discover" => Left(failure) + case _ => result(request, initializeResult(ProtocolVersion.LatestLegacy)) + connect(server, dualClient).protocolVersion shouldBe ProtocolVersion.LatestLegacy + server.methods.toList shouldBe List("server/discover", "initialize", "notifications/initialized") + + it should "decide legacy on any error that is not a modern one" in: + val server = ScriptedServer: request => + request.method match + case "server/discover" => error(request, JSONRPCErrorObject(-32000, "Bad Request: Server not initialized")) + case _ => result(request, initializeResult(ProtocolVersion.LatestLegacy)) + connect(server, dualClient).protocolVersion shouldBe ProtocolVersion.LatestLegacy + + it should "decide legacy on a result that is not a discover result" in: + val server = ScriptedServer: request => + request.method match + case "server/discover" => result(request, Json.obj("ok" -> Json.True)) + case _ => result(request, initializeResult(ProtocolVersion.LatestLegacy)) + connect(server, dualClient).protocolVersion shouldBe ProtocolVersion.LatestLegacy + + it should "decide modern on -32022 and retry discover with a common stateless version" in: + val discovers = java.util.concurrent.atomic.AtomicInteger() + val server = ScriptedServer: request => + request.method match + case "server/discover" if discovers.incrementAndGet() == 1 => + error(request, ProtocolMeta.unsupportedVersionError("2026-07-28", List("2026-07-28"))) + case "server/discover" => result(request, discoverResult(List(ProtocolVersion.Latest))) + case _ => methodNotFound(request) + connect(server, dualClient).protocolVersion shouldBe ProtocolVersion.Latest + server.methods.toList shouldBe List("server/discover", "server/discover") + + it should "fall back to initialize when -32022 offers only a common legacy version" in: + val server = ScriptedServer: request => + request.method match + case "server/discover" => error(request, ProtocolMeta.unsupportedVersionError("2026-07-28", List("2099-01-01", "2025-06-18"))) + case _ => result(request, initializeResult(ProtocolVersion.V2025_06_18)) + connect(server, dualClient).protocolVersion shouldBe ProtocolVersion.V2025_06_18 + server.methods.toList shouldBe List("server/discover", "initialize", "notifications/initialized") + + it should "fail with both version lists when a modern server shares no version" in: + val server = ScriptedServer: request => + error(request, ProtocolMeta.unsupportedVersionError("2026-07-28", List("2099-01-01"))) + val ex = intercept[McpUnsupportedProtocolVersionException](connect(server, dualClient)) + ex.serverVersions shouldBe List("2099-01-01") + ex.clientVersions shouldBe ProtocolVersion.supported.map(_.name) + server.methods.toList shouldBe List("server/discover") + + it should "not fall back on another modern error" in: + val server = ScriptedServer: request => + error(request, ProtocolMeta.missingClientCapabilityError(ClientCapabilities(sampling = Some(Json.obj())))) + val ex = intercept[McpProtocolException](connect(server, dualClient)) + ex.getMessage should include("-32021") + server.methods.toList shouldBe List("server/discover") + + it should "fail as today when a legacy server rejects initialize" in: + val server = ScriptedServer: request => + request.method match + case "initialize" => error(request, JSONRPCErrorObject(JSONRPCErrorCodes.InvalidParams.code, "bad version")) + case _ => methodNotFound(request) + val ex = intercept[McpProtocolException](connect(server, dualClient)) + ex.getMessage should include("Initialize failed") diff --git a/client/src/test/scala/chimp/client/McpClientSpec.scala b/client/src/test/scala/chimp/client/McpClientSpec.scala index 41f61422..4357605b 100644 --- a/client/src/test/scala/chimp/client/McpClientSpec.scala +++ b/client/src/test/scala/chimp/client/McpClientSpec.scala @@ -214,7 +214,11 @@ class McpClientSpec extends AnyFlatSpec with Matchers: serverInfo = Implementation(name = "legacy-server", version = "1.0") ) val connect = (JSONRPCMessage.Response(id = RequestId(1), result = initResult.asJson): JSONRPCMessage).asJson.noSpaces - val client = McpClient[Identity](ClientHttpTransport[Identity](toolHeadersBackend(sent, connect), mcpUri), clientInfo) + val client = McpClient[Identity]( + ClientHttpTransport[Identity](toolHeadersBackend(sent, connect), mcpUri), + clientInfo, + ProtocolVersion.LatestLegacy + ) client.listTools().tools.map(_.name) shouldBe List("weather", "broken") val _ = client.callTool("weather", weatherArguments) diff --git a/client/src/test/scala/chimp/client/McpClientStatelessSpec.scala b/client/src/test/scala/chimp/client/McpClientStatelessSpec.scala index bae1777c..3dffe67b 100644 --- a/client/src/test/scala/chimp/client/McpClientStatelessSpec.scala +++ b/client/src/test/scala/chimp/client/McpClientStatelessSpec.scala @@ -193,20 +193,20 @@ class McpClientStatelessSpec extends AnyFlatSpec with Matchers: "A legacy client" should "reject server/discover" in: val transport = InMemoryTransport() transport.planResponse(response(legacyInitResult(ServerCapabilities()))) - val client = McpClient[Identity](transport, clientInfo) + val client = McpClient[Identity](transport, clientInfo, ProtocolVersion.LatestLegacy) val _ = intercept[McpProtocolException](client.discover()) client.protocolVersion shouldBe ProtocolVersion.LatestLegacy it should "use the version that the server negotiates in initialize" in: val transport = InMemoryTransport() transport.planResponse(response(legacyInitResult(ServerCapabilities(), ProtocolVersion.V2025_06_18))) - McpClient[Identity](transport, clientInfo).protocolVersion shouldBe ProtocolVersion.V2025_06_18 + McpClient[Identity](transport, clientInfo, ProtocolVersion.LatestLegacy).protocolVersion shouldBe ProtocolVersion.V2025_06_18 it should "send the log level option once with logging/setLevel after initialize" in: val transport = InMemoryTransport() transport.planResponse(response(legacyInitResult(ServerCapabilities(logging = Some(Json.obj()))))) transport.planResponse(response(Json.obj())) - val _ = McpClient[Identity](transport, clientInfo, logLevel = Some(LoggingLevel.Error)) + val _ = McpClient[Identity](transport, clientInfo, ProtocolVersion.LatestLegacy, Some(LoggingLevel.Error)) methods(transport) shouldBe List("initialize", "notifications/initialized", "logging/setLevel") transport.sent.last match case JSONRPCMessage.Request(_, _, Some(params), _) => params.hcursor.get[String]("level") shouldBe Right("error") @@ -215,7 +215,7 @@ class McpClientStatelessSpec extends AnyFlatSpec with Matchers: it should "not send logging/setLevel when the server has no logging capability" in: val transport = InMemoryTransport() transport.planResponse(response(legacyInitResult(ServerCapabilities()))) - val _ = McpClient[Identity](transport, clientInfo, logLevel = Some(LoggingLevel.Error)) + val _ = McpClient[Identity](transport, clientInfo, ProtocolVersion.LatestLegacy, Some(LoggingLevel.Error)) methods(transport) shouldBe List("initialize", "notifications/initialized") private def legacyInitResult(capabilities: ServerCapabilities, version: ProtocolVersion = ProtocolVersion.LatestLegacy): Json = diff --git a/docs/client/protocol.md b/docs/client/protocol.md index d068a8a9..b83b1478 100644 --- a/docs/client/protocol.md +++ b/docs/client/protocol.md @@ -1,6 +1,9 @@ # Protocol versions -chimp's client speaks the legacy protocol versions (`2025-06-18`, `2025-11-25`) and the stateless version `2026-07-28`. You set the version once, on the client. The client gives it to the transport, so a transport has no version parameter. +chimp's client speaks the legacy protocol versions (`2025-06-18`, `2025-11-25`) and the stateless version `2026-07-28`. The `protocolVersion` parameter of `McpClient.apply` and `McpClient.bidirectional` sets the version policy, once, on the client. The client gives the version to the transport, so a transport has no version parameter. + +- `DetectVersion`, the default: the client detects the era of the server (see below). +- A fixed `ProtocolVersion`: the client uses that version and does no detection. Pin a version when you know the server, or to skip the detection request. ```scala mdoc:compile-only import chimp.client.* @@ -25,6 +28,19 @@ object StatelessClient: client.close() ``` +## Era detection + +With `DetectVersion`, the first request of the client is `server/discover` at `2026-07-28`, over HTTP and over STDIO: + +- A `server/discover` result, or a `2026-07-28` error (`-32020`, `-32021` or `-32022`), means that the server is modern. The client uses the stateless wire and negotiates the version on `-32022` (see [Version negotiation](#version-negotiation)). +- Any other outcome means that the server is legacy: another JSON-RPC error, an HTTP error (for example 400, 404 or 405) whose body is not a `2026-07-28` error, a failed send, or a timeout. The client then sends `initialize` with the latest legacy version, `2025-11-25`. + +The decision does not depend on one specific error code. The client makes it once, when it connects, and keeps it for its lifetime. `McpClient.protocolVersion` shows the result. + +If a modern server lists no stateless version that chimp supports, but a common legacy version, the client sends `initialize` with that version. If the server shares no version with chimp, the client fails with `McpUnsupportedProtocolVersionException`, which names both version lists. If a legacy server rejects `initialize`, the client fails as with a fixed legacy version. + +A legacy STDIO server that does not answer an unknown request makes the client wait for the timeout of the transport before it sends `initialize`. For such a server, pin a legacy version. + ## Legacy versions At a legacy version, the client sends `initialize` and `notifications/initialized`. It then uses the version that the server returns in the `initialize` result. diff --git a/docs/client/transport.md b/docs/client/transport.md index fb8a5465..47315455 100644 --- a/docs/client/transport.md +++ b/docs/client/transport.md @@ -36,7 +36,7 @@ classDiagram ## Protocol versions -The transports have no protocol version parameter. You set the version on `McpClient`, and the client gives it to the transport (see [Protocol versions](protocol.md)). +The transports have no protocol version parameter. You set the version policy on `McpClient`, and the client gives the version to the transport (see [Protocol versions](protocol.md)). By default the client detects the era of the server. At the stateless version `2026-07-28`, the HTTP transports: diff --git a/examples/src/main/scala/examples/client/everythingClient.scala b/examples/src/main/scala/examples/client/everythingClient.scala index fa857ce9..7319009a 100644 --- a/examples/src/main/scala/examples/client/everythingClient.scala +++ b/examples/src/main/scala/examples/client/everythingClient.scala @@ -18,11 +18,7 @@ import sttp.shared.Identity @main def everythingClient(): Unit = val backend = DefaultSyncBackend() val transport = ClientHttpTransport[Identity](backend, uri"http://localhost:3001/mcp") - val client = McpClient[Identity]( - transport, - clientInfo = Implementation(name = "chimp-everything-client", version = "0.1.0"), - protocolVersion = ProtocolVersion.Latest - ) + val client = McpClient[Identity](transport, clientInfo = Implementation(name = "chimp-everything-client", version = "0.1.0")) try println(s"Connected to ${client.serverInfo.name} ${client.serverInfo.version}") diff --git a/server-streaming/server-pekko/src/test/scala/chimp/server/pekko/PekkoMcpServerHttpSpec.scala b/server-streaming/server-pekko/src/test/scala/chimp/server/pekko/PekkoMcpServerHttpSpec.scala index c30e4219..b8fd1cd5 100644 --- a/server-streaming/server-pekko/src/test/scala/chimp/server/pekko/PekkoMcpServerHttpSpec.scala +++ b/server-streaming/server-pekko/src/test/scala/chimp/server/pekko/PekkoMcpServerHttpSpec.scala @@ -50,7 +50,7 @@ class PekkoMcpServerHttpSpec server: StreamingMcpServer[Future] )(test: BidirectionalMcpClient[Future] => Future[Assertion]): Future[Assertion] = withHttpServer(PekkoServerHttpTransport(List("mcp")).serve(server), Nil): transport => - McpClient.bidirectional(transport, clientInfo).flatMap(test) + McpClient.bidirectional(transport, clientInfo, protocolVersion = clientProtocolVersion).flatMap(test) override protected def withLoggingStreamingServer(server: StreamingMcpServer[Future], logLevel: LoggingLevel)( test: BidirectionalMcpClient[Future] => Future[Assertion] @@ -86,7 +86,11 @@ class PekkoMcpServerHttpSpec )(test: BidirectionalMcpClient[Future] => Future[Assertion]): Future[Assertion] = val endpoint = SecuredServerStreamingHttpTransport(List("mcp"), PekkoServerHttpTransport(List("mcp"))).serve(server) withHttpServer(endpoint, List(Header.authorization("Bearer", token))): transport => - McpClient.bidirectional(transport, clientInfo).flatMap(test) + McpClient.bidirectional(transport, clientInfo, protocolVersion = clientProtocolVersion).flatMap(test) + + "A client with the default version policy" should "detect a chimp server as a 2026-07-28 server" in: + withHttpServer(PekkoServerHttpTransport(List("mcp")).serve(McpServer[Future]().streaming), Nil): transport => + McpClient(transport, clientInfo).map(_.protocolVersion shouldBe ProtocolVersion.Latest) private def withHttpServer( endpoint: ServerEndpoint[PekkoStreams & WebSockets, Future], From 0654f6b19f3ed8363749f11f64c7c419f90ce4ba Mon Sep 17 00:00:00 2001 From: Ondra Pelech Date: Thu, 19 Nov 2026 23:19:35 +0100 Subject: [PATCH 31/31] fix(T16): deliver events published right after a subscription is acknowledged A subscription sent its acknowledgement first and set its acknowledged flag after. Over stdio the acknowledgement is written and flushed at once, so a client could read it and publish before the flag was set; the event was then dropped. This made the stdio subscription test wait forever for a tools/list_changed notification. Delivery now takes the same lock as the acknowledgement and the final result: an event published while the acknowledgement is on its way waits for it, and no notification follows the final result. A unit test publishes from another thread while the acknowledgement is being sent, which fails without the fix. The stdio tests now read the server output on their own thread and fail after 10 seconds instead of blocking in readLine. --- .../chimp/server/NotificationPublisher.scala | 5 ++++- .../server/NotificationPublisherSpec.scala | 21 +++++++++++++++++++ .../server/ServerStdioTransportTests.scala | 17 ++++++++++++++- 3 files changed, 41 insertions(+), 2 deletions(-) diff --git a/server/src/main/scala/chimp/server/NotificationPublisher.scala b/server/src/main/scala/chimp/server/NotificationPublisher.scala index 9eb2a28b..9b18d23f 100644 --- a/server/src/main/scala/chimp/server/NotificationPublisher.scala +++ b/server/src/main/scala/chimp/server/NotificationPublisher.scala @@ -99,7 +99,10 @@ private[server] final class Subscription( ) acknowledged.set(true) - def deliver(event: ServerEvent): Unit = + /** Holds the lock of [[acknowledge]], so an event published while the acknowledgement is on its way waits for it, instead of being + * dropped. + */ + def deliver(event: ServerEvent): Unit = synchronized: if acknowledged.get && active.get && event.accepted(filter) then send(event.notification(metaParams)) /** Ends the subscription because the client ended it; sends nothing. */ diff --git a/server/src/test/scala/chimp/server/NotificationPublisherSpec.scala b/server/src/test/scala/chimp/server/NotificationPublisherSpec.scala index e3ca557d..cc52be8d 100644 --- a/server/src/test/scala/chimp/server/NotificationPublisherSpec.scala +++ b/server/src/test/scala/chimp/server/NotificationPublisherSpec.scala @@ -10,7 +10,10 @@ import sttp.monad.{IdentityMonad, MonadError} import sttp.shared.Identity import sttp.tapir.Schema +import java.util.concurrent.ConcurrentLinkedQueue +import java.util.concurrent.atomic.AtomicReference import scala.collection.mutable.ListBuffer +import scala.jdk.CollectionConverters.* class NotificationPublisherSpec extends AnyFlatSpec with Matchers: private given MonadError[Identity] = IdentityMonad @@ -106,6 +109,24 @@ class NotificationPublisherSpec extends AnyFlatSpec with Matchers: output.messages.head.hcursor.downField("params").get[SubscriptionFilter]("notifications") shouldBe Right(SubscriptionFilter(toolsListChanged = Some(true))) + it should "deliver an event which the client publishes as soon as it sees the acknowledgement" in: + val publisher = NotificationPublisher() + val received = ConcurrentLinkedQueue[Json]() + val client = AtomicReference(Option.empty[Thread]) + val output = new SubscriptionOutput: + def send(message: Json): Unit = + val _ = received.add(message) + if client.get.isEmpty then + val reacting = Thread(() => publisher.toolsListChanged()) + client.set(Some(reacting)) + reacting.start() + while reacting.isAlive && reacting.getState != Thread.State.BLOCKED do Thread.onSpinWait() + def close(): Unit = () + val _ = publisher.open(RequestId(1), SubscriptionFilter(toolsListChanged = Some(true)), output) + client.get.foreach(_.join(5000)) + received.asScala.toList.map(_.hcursor.get[String]("method").toOption) shouldBe + List(Some("notifications/subscriptions/acknowledged"), Some("notifications/tools/list_changed")) + it should "send only the notification types and resource URIs the filter names" in: val publisher = NotificationPublisher() val output = RecordingOutput() diff --git a/server/src/test/scala/chimp/server/ServerStdioTransportTests.scala b/server/src/test/scala/chimp/server/ServerStdioTransportTests.scala index 1f63c9fb..40fc3251 100644 --- a/server/src/test/scala/chimp/server/ServerStdioTransportTests.scala +++ b/server/src/test/scala/chimp/server/ServerStdioTransportTests.scala @@ -11,6 +11,7 @@ import sttp.tapir.Schema import java.io.{ BufferedReader, BufferedWriter, + IOException, InputStream, InputStreamReader, OutputStream, @@ -19,6 +20,7 @@ import java.io.{ PipedOutputStream } import java.nio.charset.StandardCharsets +import java.util.concurrent.{LinkedBlockingQueue, TimeUnit} import scala.concurrent.duration.DurationInt import scala.concurrent.{Await, Future} @@ -67,7 +69,20 @@ trait ServerStdioTransportTests[F[_]] extends AnyFlatSpec with Matchers: def closeInput(): Unit = writer.close() - def readResponse(): Json = parser.parse(reader.readLine()).toOption.get + private val lines = LinkedBlockingQueue[Option[String]]() + private val readerThread = Thread: () => + try Iterator.continually(reader.readLine()).takeWhile(_ != null).foreach(line => lines.put(Some(line))) + catch case _: IOException => () + finally lines.put(None) + readerThread.setDaemon(true) + readerThread.start() + + /** The next line from the server; fails instead of blocking when no line comes within 10 seconds. */ + def readResponse(): Json = + Option(lines.poll(10, TimeUnit.SECONDS)) match + case Some(Some(line)) => parser.parse(line).toOption.get + case Some(None) => fail("The server closed its output") + case None => fail("No line from the server within 10 seconds") private def withStdioServer[A](maxLineLength: Int = StdioFraming.defaultMaxLineLength)(body: StdioSession => A): A = val toServer = PipedOutputStream()