ruby-utcp 1.1.0

data/examples/servers/mcp_stdio_server.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "json"
+
+$stdout.sync = true
+
+ARGF.each_line do |line|
+  message = JSON.parse(line)
+  next unless message.key?("id")
+
+  result = case message["method"]
+           when "initialize"
+             {
+               protocolVersion: message.dig("params", "protocolVersion") || "2025-06-18",
+               capabilities: { tools: {}, resources: {} },
+               serverInfo: { name: "ruby-example", version: "1.0.0" }
+             }
+           when "tools/list"
+             {
+               tools: [{
+                 name: "echo",
+                 description: "Echo a message",
+                 inputSchema: {
+                   type: "object",
+                   properties: { message: { type: "string" } },
+                   required: ["message"]
+                 }
+               }]
+             }
+           when "tools/call"
+             text = message.dig("params", "arguments", "message").to_s
+             { content: [{ type: "text", text: JSON.generate(echo: text) }] }
+           when "resources/list"
+             { resources: [{ name: "welcome", uri: "memory://welcome", description: "Welcome text" }] }
+           when "resources/read"
+             { contents: [{ uri: "memory://welcome", mimeType: "text/plain", text: "Hello from MCP" }] }
+           else
+             {}
+           end
+  puts JSON.generate(jsonrpc: "2.0", id: message["id"], result: result)
+rescue JSON::ParserError => error
+  warn error.message
+end

data/examples/servers/requirements-grpc.txt

@@ -0,0 +1,2 @@
+grpcio>=1.83.1,<2
+grpcio-tools>=1.83.1,<2

data/examples/servers/sse_server.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "http_helpers"
+
+port = Integer(ENV.fetch("PORT", "8081"))
+base = "http://localhost:#{port}"
+
+ExampleHTTP.server(port) do |server|
+  server.mount_proc("/utcp") do |_request, response|
+    ExampleHTTP.json(response, {
+      utcp_version: "1.1.0",
+      tools: [{
+        name: "watch",
+        tool_call_template: {
+          call_template_type: "sse",
+          url: "#{base}/watch",
+          event_type: "update"
+        }
+      }]
+    })
+  end
+
+  server.mount_proc("/watch") do |request, response|
+    topic = request.query["topic"] || "events"
+    response.status = 200
+    response["Content-Type"] = "text/event-stream"
+    response["Cache-Control"] = "no-cache"
+    response.chunked = true
+    response.body = proc do |output|
+      3.times do |index|
+        output.write("id: #{index + 1}\nevent: update\ndata: #{JSON.generate(topic: topic, number: index + 1)}\n\n")
+        sleep 0.2
+      end
+    end
+  end
+end

data/examples/servers/streamable_http_server.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "http_helpers"
+
+port = Integer(ENV.fetch("PORT", "8082"))
+base = "http://localhost:#{port}"
+
+ExampleHTTP.server(port) do |server|
+  server.mount_proc("/utcp") do |_request, response|
+    ExampleHTTP.json(response, {
+      utcp_version: "1.1.0",
+      tools: [{
+        name: "tokens",
+        tool_call_template: {
+          call_template_type: "streamable_http",
+          url: "#{base}/tokens",
+          http_method: "POST",
+          content_type: "application/json",
+          body_field: "body",
+          chunk_size: 32,
+          timeout: 60_000
+        }
+      }]
+    })
+  end
+
+  server.mount_proc("/tokens") do |request, response|
+    prompt = ExampleHTTP.request_json(request)["prompt"].to_s
+    response.status = 200
+    response["Content-Type"] = "application/x-ndjson"
+    response.chunked = true
+    response.body = proc do |output|
+      prompt.split.each_with_index do |token, index|
+        output.write(JSON.generate(index: index, token: token) + "\n")
+        sleep 0.15
+      end
+    end
+  end
+end

data/examples/servers/tcp_server.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "json"
+require "socket"
+
+port = Integer(ENV.fetch("PORT", "9000"))
+
+def read_exact(socket, length)
+  value = +"".b
+  value << socket.readpartial(length - value.bytesize) while value.bytesize < length
+  value
+end
+
+def read_message(socket)
+  length = read_exact(socket, 4).unpack1("N")
+  read_exact(socket, length)
+end
+
+def write_message(socket, value)
+  bytes = value.to_s.b
+  socket.write([bytes.bytesize].pack("N") + bytes)
+end
+
+manual = {
+  utcp_version: "1.1.0",
+  tools: [{
+    name: "echo",
+    tool_call_template: {
+      call_template_type: "tcp",
+      host: "localhost",
+      port: port,
+      framing_strategy: "length_prefix",
+      length_prefix_bytes: 4,
+      length_prefix_endian: "big",
+      request_data_format: "json",
+      response_byte_format: "utf-8"
+    }
+  }]
+}
+
+server = TCPServer.new("127.0.0.1", port)
+warn "Listening on tcp://127.0.0.1:#{port}"
+loop do
+  socket = server.accept
+  Thread.new(socket) do |client|
+    request = JSON.parse(read_message(client))
+    response = if request["type"] == "utcp"
+                 JSON.generate(manual)
+               else
+                 "Hello over TCP: #{request["message"]}"
+               end
+    write_message(client, response)
+  rescue EOFError, IOError, SystemCallError, JSON::ParserError
+    nil
+  ensure
+    client.close unless client.closed?
+  end
+end

data/examples/servers/udp_server.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "json"
+require "socket"
+
+port = Integer(ENV.fetch("PORT", "9001"))
+socket = UDPSocket.new
+socket.bind("127.0.0.1", port)
+warn "Listening on udp://127.0.0.1:#{port}"
+
+manual = {
+  utcp_version: "1.1.0",
+  tools: [{
+    name: "echo",
+    tool_call_template: {
+      call_template_type: "udp",
+      host: "localhost",
+      port: port,
+      number_of_response_datagrams: 1,
+      request_data_format: "json",
+      response_byte_format: "utf-8"
+    }
+  }]
+}
+
+loop do
+  bytes, sender = socket.recvfrom(65_535)
+  request = JSON.parse(bytes)
+  response = request["type"] == "utcp" ? JSON.generate(manual) : "Hello over UDP: #{request["message"]}"
+  socket.send(response, 0, sender[3], sender[1])
+rescue JSON::ParserError => error
+  warn error.message
+end

data/examples/servers/webrtc_server.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "json"
+require "utcp"
+gem "webrtc-ruby", ">= 1.0.0"
+require "webrtc"
+require_relative "http_helpers"
+
+WebRTC.init
+port = Integer(ENV.fetch("PORT", "8084"))
+peers = {}
+peers_mutex = Mutex.new
+
+def wait_for_ice(peer, timeout = 5)
+  mutex = Mutex.new
+  condition = ConditionVariable.new
+  complete = peer.ice_gathering_state == :complete
+  peer.on_ice_gathering_state_change do
+    mutex.synchronize do
+      complete = peer.ice_gathering_state == :complete
+      condition.broadcast if complete
+    end
+  end
+  deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+  mutex.synchronize do
+    until complete
+      remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      break unless remaining.positive?
+      condition.wait(mutex, remaining)
+    end
+  end
+end
+
+ExampleHTTP.server(port) do |server|
+  server.mount_proc("/connect") do |request, response|
+    payload = ExampleHTTP.request_json(request)
+    candidates = []
+    peer = WebRTC::RTCPeerConnection.new
+    peer.on_ice_candidate { |candidate| candidates << candidate if candidate }
+    peer.on_data_channel do |channel|
+      channel.on_message do |event|
+        envelope = JSON.parse(event.data)
+        result = envelope.dig("args", "message") if envelope["tool"] == "echo"
+        channel.send_text(JSON.generate(id: envelope["id"], result: result))
+      rescue JSON::ParserError
+        nil
+      end
+    end
+
+    offer = WebRTC::RTCSessionDescription.new(type: :offer, sdp: payload.fetch("sdp"))
+    peer.set_remote_description(offer).await
+    answer = peer.create_answer.await
+    peer.set_local_description(answer).await
+    wait_for_ice(peer)
+    peers_mutex.synchronize { peers[payload.fetch("peer_id")] = peer }
+    ExampleHTTP.json(response, {
+      sdp: peer.local_description.sdp,
+      candidates: candidates.map(&:to_h),
+      tools: [{ name: "echo", description: "Echo over a WebRTC DataChannel" }]
+    })
+  rescue StandardError => error
+    ExampleHTTP.json(response, { error: error.message }, status: 500)
+  end
+
+  server.mount_proc("/candidate") do |request, response|
+    payload = ExampleHTTP.request_json(request)
+    peer = peers_mutex.synchronize { peers[payload["peer_id"]] }
+    if peer
+      candidate = WebRTC::RTCIceCandidate.new(UTCP::Utils.symbolize_keys(payload.fetch("candidate")))
+      peer.add_ice_candidate(candidate).await
+      ExampleHTTP.json(response, { ok: true })
+    else
+      ExampleHTTP.json(response, { error: "unknown peer" }, status: 404)
+    end
+  rescue StandardError => error
+    ExampleHTTP.json(response, { error: error.message }, status: 400)
+  end
+end

data/examples/servers/websocket_server.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "base64"
+require "digest/sha1"
+require "json"
+require "socket"
+
+GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
+port = Integer(ENV.fetch("PORT", "8083"))
+endpoint = "ws://localhost:#{port}/utcp"
+
+def read_exact(socket, length)
+  value = +"".b
+  value << socket.readpartial(length - value.bytesize) while value.bytesize < length
+  value
+end
+
+def read_frame(socket)
+  first, second = read_exact(socket, 2).unpack("CC")
+  opcode = first & 0x0F
+  length = second & 0x7F
+  length = read_exact(socket, 2).unpack1("n") if length == 126
+  length = read_exact(socket, 8).unpack1("Q>") if length == 127
+  mask = (second & 0x80).zero? ? nil : read_exact(socket, 4)
+  payload = read_exact(socket, length)
+  if mask
+    payload = payload.bytes.each_with_index.map { |byte, index| byte ^ mask.getbyte(index % 4) }.pack("C*")
+  end
+  [opcode, payload]
+end
+
+def write_frame(socket, payload, opcode = 0x1)
+  bytes = payload.to_s.b
+  header = [0x80 | opcode].pack("C")
+  header << if bytes.bytesize < 126
+              [bytes.bytesize].pack("C")
+            elsif bytes.bytesize <= 65_535
+              [126, bytes.bytesize].pack("Cn")
+            else
+              [127, bytes.bytesize].pack("CQ>")
+            end
+  socket.write(header + bytes)
+end
+
+server = TCPServer.new("127.0.0.1", port)
+warn "Listening on #{endpoint}"
+
+loop do
+  socket = server.accept
+  Thread.new(socket) do |client|
+    header = +""
+    header << client.readpartial(1024) until header.include?("\r\n\r\n")
+    headers = header.split("\r\n").drop(1).each_with_object({}) do |line, values|
+      name, value = line.split(":", 2)
+      values[name.downcase] = value.to_s.strip
+    end
+    accept = Base64.strict_encode64(Digest::SHA1.digest(headers.fetch("sec-websocket-key") + GUID))
+    response = +"HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: #{accept}\r\n"
+    response << "Sec-WebSocket-Protocol: #{headers["sec-websocket-protocol"]}\r\n" if headers["sec-websocket-protocol"]
+    client.write(response + "\r\n")
+
+    loop do
+      opcode, bytes = read_frame(client)
+      break if opcode == 0x8
+      if opcode == 0x9
+        write_frame(client, bytes, 0xA)
+        next
+      end
+      message = JSON.parse(bytes)
+      if message["type"] == "utcp"
+        write_frame(client, JSON.generate(
+          utcp_version: "1.1.0",
+          tools: [{
+            name: "echo",
+            tool_call_template: {
+              call_template_type: "websocket",
+              url: endpoint,
+              protocol: "utcp-v1",
+              response_format: "json"
+            }
+          }]
+        ))
+      else
+        write_frame(client, JSON.generate(echo: message["message"]))
+      end
+    end
+  rescue EOFError, IOError, SystemCallError, JSON::ParserError
+    nil
+  ensure
+    client.close unless client.closed?
+  end
+end

data/examples/sse.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "utcp"
+
+# The discovery URL returns JSON; the discovered tool template points to an SSE endpoint.
+client = UTCP::Client.create(config: {
+  manual_call_templates: [{
+    name: "events",
+    call_template_type: "sse",
+    url: ENV.fetch("UTCP_SSE_MANUAL", "http://localhost:8081/utcp")
+  }]
+})
+
+client.call_tool_streaming("events.watch", topic: "builds") do |event|
+  puts "event: #{event.inspect}"
+end

data/examples/streamable_http.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "utcp"
+
+# Supports NDJSON, JSON Sequence, JSON, and arbitrary binary chunks.
+client = UTCP::Client.create(config: {
+  manual_call_templates: [{
+    name: "generator",
+    call_template_type: "streamable_http",
+    url: ENV.fetch("UTCP_STREAM_MANUAL", "http://localhost:8082/utcp"),
+    http_method: "GET",
+    chunk_size: 4096,
+    timeout: 60_000
+  }]
+})
+
+client.call_tool_streaming("generator.tokens", body: { prompt: "Hello from Ruby" }) { |chunk| puts chunk.inspect }

data/examples/tcp.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "utcp"
+
+# The server answers the framed discovery message {"type":"utcp"} with a manual.
+client = UTCP::Client.create(config: {
+  manual_call_templates: [{
+    name: "tcp_service",
+    call_template_type: "tcp",
+    host: ENV.fetch("UTCP_TCP_HOST", "localhost"),
+    port: Integer(ENV.fetch("UTCP_TCP_PORT", "9000")),
+    framing_strategy: "length_prefix",
+    length_prefix_bytes: 4,
+    length_prefix_endian: "big",
+    request_data_format: "json",
+    response_byte_format: "utf-8"
+  }]
+})
+
+puts client.call_tool("tcp_service.echo", message: "Hello over TCP")

data/examples/text.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "json"
+require "utcp"
+
+manual = {
+  utcp_version: "1.1.0",
+  manual_version: "1.0.0",
+  tools: [{
+    name: "motd",
+    description: "Return a static message",
+    tool_call_template: {
+      call_template_type: "text",
+      content: "Hello from a text UTCP tool"
+    }
+  }]
+}
+
+client = UTCP::Client.create(config: {
+  manual_call_templates: [{ name: "static", call_template_type: "text", content: JSON.generate(manual) }]
+})
+
+puts client.call_tool("static.motd")

data/examples/udp.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require "utcp"
+
+# The server answers {"type":"utcp"} with one manual datagram.
+client = UTCP::Client.create(config: {
+  manual_call_templates: [{
+    name: "udp_service",
+    call_template_type: "udp",
+    host: ENV.fetch("UTCP_UDP_HOST", "localhost"),
+    port: Integer(ENV.fetch("UTCP_UDP_PORT", "9001")),
+    number_of_response_datagrams: 1,
+    request_data_format: "json",
+    response_byte_format: "utf-8"
+  }]
+})
+
+puts client.call_tool("udp_service.echo", message: "Hello over UDP")

data/examples/webrtc.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "utcp"
+
+# Requires Ruby 3.1+, `gem "webrtc-ruby"`, and libdatachannel.
+# POST /connect exchanges SDP and returns {sdp, candidates, tools}; /candidate accepts ICE.
+client = UTCP::Client.create(config: {
+  manual_call_templates: [{
+    name: "rtc",
+    call_template_type: "webrtc",
+    signaling_server: ENV.fetch("UTCP_WEBRTC_SIGNALING", "http://localhost:8084"),
+    peer_id: ENV.fetch("UTCP_WEBRTC_PEER_ID", "ruby-client"),
+    data_channel_name: "utcp",
+    ice_servers: [{ urls: "stun:stun.l.google.com:19302" }]
+  }]
+})
+
+puts client.call_tool("rtc.echo", message: "Hello over WebRTC").inspect
+client.close

data/examples/websocket.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "utcp"
+
+# The server first answers {"type":"utcp"} with a manual, then handles tool messages.
+client = UTCP::Client.create(config: {
+  manual_call_templates: [{
+    name: "realtime",
+    call_template_type: "websocket",
+    url: ENV.fetch("UTCP_WEBSOCKET_URL", "ws://localhost:8083/utcp"),
+    protocol: "utcp-v1",
+    keep_alive: true,
+    response_format: "json"
+  }]
+})
+
+puts client.call_tool("realtime.echo", message: "Hello over WebSocket").inspect

data/lib/ruby-utcp.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require_relative "utcp"
+