feature: MCP server support (wvlet.uni.mcp) — build MCP tools from Scala traits on JVM/JS/Native

[xerial]

Why

Make uni the easiest way to write MCP (Model Context Protocol) servers in Scala. Uni RPC already had every ingredient — Surface method metadata, Weaver codecs, and the transport-neutral RPCDispatcher (already reused by the Electron IPC transport) — so MCP is mostly a thin JSON-RPC 2.0 stdio layer on top. Cross-platform is the differentiator: a Scala Native single binary (no JVM, instant startup) or a Node-runnable script is a better MCP-server install story than JVM-based SDKs.

Plan: plans/2026-07-20-uni-mcp.md

What

One expression turns a service trait into an MCP server:

MCPServer().withName("weather").withTools[WeatherService](impl).serveStdio()

• wvlet.uni.mcp (inside the uni module — no new sbt module, zero new dependencies):
  • MCPServer: initialize/ping/tools-list/tools-call over newline-delimited JSON-RPC 2.0 (protocol 2025-06-18, also accepts 2025-03-26). tools/call synthesizes a uni Request and reuses the shared RPCDispatcher, exactly like the Electron transport, so decoding/defaults/errors behave identically to uni RPC. Tool execution failures are isError: true results; malformed arguments are -32602 protocol errors. Fails fast at withTools on name collisions, invalid tool names, and non-encodable types.
  • JsonSchema: Surface→JSON Schema derivation for tool inputSchema (Option/default → optional, Seq/Map/case-class nesting, recursion guard). @description annotation for tool/param descriptions (Surface captures no Scaladoc).
  • StdioTransport per platform: JVM/Native block on System.in; JS is event-loop driven via process.stdin and re-routes logging to stderr (the default JS handler writes to stdout, which would corrupt the protocol stream).
• RPC-layer fixes surfaced by this work:
  • RPCRouter no longer exposes synthetic methods (f$default$1, …) as routes.
  • MethodCodec.decodeParams now takes the service instance so method-argument default values (compiled as instance methods on the trait) are applied; previously omitting a defaulted RPC parameter failed with "Missing required parameter".
• Docs: docs/mcp/index.md — "Build Your Own MCP Server (stdio)" startup guide (project setup → trait → packaging per platform → .mcp.json registration → MCP Inspector), registered in both sidebars.

Tests

• MCPServerTest + JsonSchemaTest run on JVM, Scala.js, and Scala Native (21 tests each): handshake/version negotiation, tools/list schema shape, sync + Rx tool calls, default parameters, error taxonomy (-32700/-32601/-32602 vs isError), id echoing, notifications.
• StdioTransportTest (JVM): scripted end-to-end stdio session through the real transport loop.
• Full uniJVM/test suite green (348 tests); pnpm docs:build passes.

Deferred (follow-ups): resources/prompts (via plugin ExtensionPoints), HTTP transport, structuredContent/outputSchema, listChanged, pagination.

🤖 Generated with Claude Code

https://claude.ai/code/session_01X28nzmwNHfxNC8c1GnHqBM

[gemini-code-assist]

Code Review

This pull request introduces cross-platform support for building Model Context Protocol (MCP) servers in Scala across JVM, Scala.js, and Scala Native, utilizing a JSON-RPC 2.0 stdio transport layer and automatic JSON Schema derivation for tool inputs. The review feedback focuses on robust stdio handling: preventing double-quoted string results by inspecting tool return types, processing remaining buffer data on stream end in Node.js, and redirecting standard output to standard error on JVM and Native platforms to prevent protocol corruption from accidental print statements.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

Pass the tool instance to toolCallResponse so that the return type can be inspected to unwrap JSON-encoded string results.

          .map(response => Some(toolCallResponse(id, response, tool)))

[gemini-code-assist]

When a tool returns a String (or Rx[String]), the RPC dispatcher encodes it as a JSON string (e.g., "value" with literal quotes). Passing this directly to toolResult causes the MCP client to receive a double-quoted string. To avoid unnecessary serialization-deserialization roundtrips, we should inspect the return type and extract the string directly from the parsed JSON value of the response if available, rather than converting it to a string and parsing it again.

  private def toolCallResponse(id: JSONValue, response: Response, tool: MCPTool): String =
    val isSuccess = response
      .header(HttpHeader.XRPCStatus)
      .contains(RPCStatus.SUCCESS_S0.code.toString)
    if isSuccess then
      val method = tool.route.codec.method
      val isString = method.returnType.rawType == classOf[String] ||
        (classOf[Rx[?]].isAssignableFrom(method.returnType.rawType) &&
          method.returnType.typeArgs.headOption.exists(_.rawType == classOf[String]))
      val text = if isString then
        response.contentAsJson match
          case JSONString(s) => s
          case _ => response.contentAsString.getOrElse("null")
      else
        response.contentAsString.getOrElse("null")
      JsonRpc.resultResponse(id, toolResult(text, isError = false))

References

1. Avoid unnecessary serialization-deserialization roundtrips when processing JSON values. If a JSON value is already parsed, use a method that can directly decode from the JSONValue instead of converting it to a string and then parsing it again.

[gemini-code-assist]

If the client closes the stdin stream without a trailing newline on the last message, the remaining buffer content will be ignored because the data event listener only processes lines ending with \n. We should listen to the end event and process any remaining data in the buffer.

    stdin.on("data", onData)
    val onEnd: js.Function0[Unit] = () =>
      val line = buffer.trim
      if line.nonEmpty then
        dispatchLine(handle, line)
    stdin.on("end", onEnd)

[gemini-code-assist]

To prevent accidental println or standard output writes from user code or third-party libraries from corrupting the MCP JSON-RPC stdio stream, we can redirect System.out to System.err during serve, while keeping a private reference to the original stdout stream for protocol responses.

private[mcp] object StdioTransport extends LogSupport:
  private val writeLock = new Object
  private val outStream = System.out

  def serve(handle: String => Rx[Option[String]]): Unit =
    System.setOut(System.err)
    try
      val reader = new BufferedReader(new InputStreamReader(System.in, StandardCharsets.UTF_8))
      var line   = reader.readLine()
      while line != null do
        val message = line.trim
        if message.nonEmpty then
          dispatchLine(handle, message)
        line = reader.readLine()
    finally
      System.setOut(outStream)

[gemini-code-assist]

Use the captured outStream to write protocol responses to the real standard output.

  private def writeLine(message: String): Unit = writeLock.synchronized {
    outStream.println(message)
    outStream.flush()
  }

[gemini-code-assist]

To prevent accidental println or standard output writes from user code or third-party libraries from corrupting the MCP JSON-RPC stdio stream, we can redirect System.out to System.err during serve, while keeping a private reference to the original stdout stream for protocol responses.

private[mcp] object StdioTransport extends LogSupport:
  private val writeLock = new Object
  private val outStream = System.out

  def serve(handle: String => Rx[Option[String]]): Unit =
    System.setOut(System.err)
    try
      val reader = new BufferedReader(new InputStreamReader(System.in, StandardCharsets.UTF_8))
      var line   = reader.readLine()
      while line != null do
        val message = line.trim
        if message.nonEmpty then
          dispatchLine(handle, message)
        line = reader.readLine()
    finally
      System.setOut(outStream)

[gemini-code-assist]

Use the captured outStream to write protocol responses to the real standard output.

  private def writeLine(message: String): Unit = writeLock.synchronized {
    outStream.println(message)
    outStream.flush()
  }

[xerial]

Thanks for the review! All four suggestions are addressed in e0fa34c/450f45e:

• String results: now unwrapped to plain text before building the MCP content (with a test pinning escape handling).
• Node stdin end: a final unterminated line is now flushed and dispatched.
• JVM/Native stdout protection: serve captures the real stdout for protocol responses and points System.out at stderr while serving (restored on exit); also applied on Scala.js for symmetry.