nunki 0.1.0

data/lib/nunki/mcp/transports.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Nunki
+  module MCP
+    module Transports
+      class Stdio
+        MAX_MESSAGE_BYTES = 4_194_304
+
+        def initialize(command:, env: {})
+          @command = validate_command(command)
+          @env = validate_env(env)
+          @request_lock = Mutex.new
+          @write_lock = Mutex.new
+          @buffer = +""
+          @closed = false
+        end
+
+        def protocol_version=(_version); end
+
+        def request(message, timeout:)
+          @request_lock.synchronize do
+            ensure_open
+            write(message)
+            deadline = monotonic + timeout
+            loop do
+              response = read_message(deadline)
+              return response if response["id"] == message["id"]
+              reply_to_server(response) if response["method"] && response.key?("id")
+            end
+          end
+        end
+
+        def notify(message)
+          ensure_open
+          write(message)
+          nil
+        end
+
+        def close
+          return if @closed
+          @closed = true
+          @stdin&.close unless @stdin&.closed?
+          stop_process
+          [@stdout, @stderr].compact.each { |io| io.close unless io.closed? }
+          @stderr_thread&.join(0.2)
+          nil
+        end
+
+        private
+
+        def ensure_open
+          raise Error, "MCP transport is closed" if @closed
+          return if @waiter
+
+          @stdin, @stdout, @stderr, @waiter = Open3.popen3(@env, *@command)
+          @stdin.binmode
+          @stdout.binmode
+          @stderr_thread = Thread.new do
+            loop { break unless @stderr.read(16_384) }
+          rescue IOError
+            nil
+          end
+        rescue SystemCallError => error
+          raise Error, "failed to start MCP server: #{error.message}"
+        end
+
+        def write(message)
+          source = JSON.generate(Protocol.json(message))
+          raise ProtocolError, "MCP message exceeds #{MAX_MESSAGE_BYTES} bytes" if source.bytesize > MAX_MESSAGE_BYTES
+          @write_lock.synchronize do
+            @stdin.write(source, "\n")
+            @stdin.flush
+          end
+        end
+
+        def read_message(deadline)
+          loop do
+            if (newline = @buffer.index("\n"))
+              source = @buffer.slice!(0, newline + 1).delete_suffix("\n").delete_suffix("\r")
+              next if source.empty?
+              return Protocol.object(Protocol.parse(source, "MCP message"), "MCP message")
+            end
+            wait = deadline - monotonic
+            raise Timeout, "MCP request timed out" unless wait.positive? && IO.select([@stdout], nil, nil, wait)
+            chunk = @stdout.read_nonblock(16_384, exception: false)
+            raise Error, "MCP server closed its output" if chunk.nil?
+            next if chunk == :wait_readable
+            @buffer << chunk
+            raise ProtocolError, "MCP message exceeds #{MAX_MESSAGE_BYTES} bytes" if @buffer.bytesize > MAX_MESSAGE_BYTES
+          end
+        end
+
+        def reply_to_server(message)
+          result = message["method"] == "ping" ? {} : nil
+          reply = {"jsonrpc" => "2.0", "id" => message["id"]}
+          if result
+            reply["result"] = result
+          else
+            reply["error"] = {"code" => -32_601, "message" => "Method not found"}
+          end
+          write(reply)
+        end
+
+        def stop_process
+          return unless @waiter
+          return if @waiter.join(0.5)
+          ["TERM", "KILL"].each do |signal|
+            begin
+              signal_process(signal, @waiter.pid)
+            rescue Errno::EINVAL
+              next
+            end
+            return if @waiter.join(0.5)
+          end
+        rescue Errno::ESRCH, Errno::ECHILD
+          nil
+        end
+
+        def signal_process(signal, pid) = Process.kill(signal, pid)
+
+        def validate_command(command)
+          raise ProtocolError, "command must be a non-empty array" unless command.is_a?(Array) && command.any?
+          command.map { |part| Protocol.string(part, "command argument", empty: false, max: 32_768) }.freeze
+        end
+
+        def validate_env(env)
+          raise ProtocolError, "env must be an object" unless env.is_a?(Hash)
+          env.to_h do |key, value|
+            [Protocol.string(key, "environment name", empty: false, max: 1024),
+              Protocol.string(value, "environment value", max: 32_768)]
+          end.freeze
+        end
+
+        def monotonic = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+
+      class HTTP
+        def initialize(url:, headers: {}, **options)
+          @client = Nunki::HTTP::Client.new(endpoint: url, headers: headers, **options)
+          @session_id = nil
+          @protocol_version = nil
+        end
+
+        def protocol_version=(version)
+          @protocol_version = version
+        end
+
+        def request(message, timeout:)
+          matched = nil
+          response = @client.post_json(message, headers: request_headers) do |event, response_headers|
+            @session_id ||= response_headers["mcp-session-id"]
+            matched ||= receive(parse_message(event.data), message["id"])
+          end
+          @session_id ||= response.headers["mcp-session-id"]
+          matched ||= receive(parse_message(response.body), message["id"]) unless response.body.empty?
+          matched ||
+            raise(ProtocolError, "MCP HTTP response did not contain the request id")
+        rescue Nunki::Timeout
+          raise
+        end
+
+        def notify(message)
+          @client.post_json(message, headers: request_headers)
+          nil
+        end
+
+        def close
+          begin
+            @client.delete(headers: request_headers) if @session_id
+          rescue HTTPError => error
+            raise unless error.status == 405
+          ensure
+            @client.cancel
+          end
+          nil
+        end
+
+        private
+
+        def request_headers
+          headers = {"Accept" => "application/json, text/event-stream"}
+          headers["MCP-Session-Id"] = @session_id if @session_id
+          headers["MCP-Protocol-Version"] = @protocol_version if @protocol_version
+          headers
+        end
+
+        def parse_message(source)
+          return nil if source.empty?
+          Protocol.object(Protocol.parse(source, "MCP HTTP response"), "MCP HTTP response")
+        end
+
+        def receive(message, request_id)
+          return unless message
+          raise ProtocolError, "invalid JSON-RPC version" unless message["jsonrpc"] == "2.0"
+          return message if !message.key?("method") && message["id"] == request_id
+          reply_to_server(message) if message["method"] && message.key?("id")
+          nil
+        end
+
+        def reply_to_server(message)
+          result = message["method"] == "ping" ? {} : nil
+          reply = {"jsonrpc" => "2.0", "id" => message["id"]}
+          if result
+            reply["result"] = result
+          else
+            reply["error"] = {"code" => -32_601, "message" => "Method not found"}
+          end
+          @client.post_json(reply, headers: request_headers)
+        end
+      end
+    end
+  end
+end

data/lib/nunki/mcp.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+module Nunki
+  module MCP
+    PROTOCOL_VERSION = "2025-11-25"
+
+    class RemoteError < Error
+      attr_reader :code, :data
+
+      def initialize(code, message, data = nil)
+        @code = code
+        @data = data
+        super(message)
+      end
+    end
+
+    class Client
+      def self.stdio(command:, env: {}, **options)
+        timeout = options.delete(:timeout) || 30
+        dispatch = options.delete(:dispatch) || ->(&block) { block.call }
+        raise ProtocolError, "unknown options: #{options.keys.join(", ")}" unless options.empty?
+        new(Transports::Stdio.new(command: command, env: env), timeout: timeout, dispatch: dispatch)
+      end
+
+      def self.http(url:, headers: {}, **options)
+        timeout = options.delete(:timeout) || 30
+        dispatch = options.delete(:dispatch) || ->(&block) { block.call }
+        options[:read_timeout] ||= timeout
+        options[:retries] = 0 unless options.key?(:retries)
+        new(Transports::HTTP.new(url: url, headers: headers, **options), timeout: timeout, dispatch: dispatch)
+      end
+
+      attr_reader :capabilities, :server_info
+
+      def initialize(transport, timeout:, dispatch:)
+        @transport = transport
+        @timeout = positive_timeout(timeout)
+        raise ProtocolError, "dispatch must respond to call" unless dispatch.respond_to?(:call)
+        @dispatch = dispatch
+        @sequence = 0
+        @request_lock = Mutex.new
+        @state_lock = Mutex.new
+        @state = :created
+        @capabilities = {}.freeze
+        @server_info = {}.freeze
+      end
+
+      def start
+        @dispatch.call do
+          begin_start
+          begin
+            result = request_now("initialize", {
+              protocolVersion: PROTOCOL_VERSION,
+              capabilities: {},
+              clientInfo: {name: "nunki", version: VERSION}
+            }, initializing: true)
+            validate_initialization(result)
+            @transport.protocol_version = PROTOCOL_VERSION
+            @transport.notify(notification("notifications/initialized"))
+            @state_lock.synchronize do
+              raise Error, "MCP client was closed during initialization" unless @state == :starting
+              @state = :started
+            end
+            result
+          rescue StandardError
+            close_after_failed_start
+            raise
+          end
+        end
+      end
+
+      def tools = schedule { list_all("tools/list", "tools", :tools) }
+      def resources = schedule { list_all("resources/list", "resources", :resources) }
+      def prompts = schedule { list_all("prompts/list", "prompts", :prompts) }
+
+      def call_tool(name, arguments)
+        schedule do
+          name = Protocol.string(name, "tool name", empty: false, max: 256)
+          arguments = Protocol.object(arguments, "tool arguments")
+          result = request_now("tools/call", {name: name, arguments: arguments})
+          validate_result_collection(result, "content")
+        end
+      end
+
+      def read_resource(uri)
+        schedule do
+          uri = Protocol.string(uri, "resource URI", empty: false, max: 4096)
+          result = request_now("resources/read", {uri: uri})
+          validate_result_collection(result, "contents")
+        end
+      end
+
+      def get_prompt(name, arguments = {})
+        schedule do
+          name = Protocol.string(name, "prompt name", empty: false, max: 256)
+          arguments = Protocol.object(arguments, "prompt arguments")
+          result = request_now("prompts/get", {name: name, arguments: arguments})
+          validate_result_collection(result, "messages")
+        end
+      end
+
+      def close
+        @dispatch.call do
+          should_close = @state_lock.synchronize do
+            next false if %i[closing closed].include?(@state)
+            @state = :closing
+            true
+          end
+          next nil unless should_close
+          begin
+            @transport.close
+          ensure
+            @state_lock.synchronize { @state = :closed }
+          end
+          nil
+        end
+      end
+
+      private
+
+      def schedule(&block)
+        @dispatch.call do
+          raise Error, "MCP client is not started" unless @state_lock.synchronize { @state == :started }
+          block.call
+        end
+      end
+
+      def begin_start
+        @state_lock.synchronize do
+          raise Error, "MCP client has already started" unless @state == :created
+          @state = :starting
+        end
+      end
+
+      def close_after_failed_start
+        @transport.close
+      rescue StandardError
+        nil
+      ensure
+        @capabilities = {}.freeze
+        @server_info = {}.freeze
+        @state_lock.synchronize { @state = :closed }
+      end
+
+      def request_now(method, params, initializing: false)
+        request_id = nil
+        @request_lock.synchronize do
+          request_id = @sequence += 1
+          message = {"jsonrpc" => "2.0", "id" => request_id, "method" => method, "params" => params}
+          response = Protocol.object(@transport.request(message, timeout: @timeout), "JSON-RPC response")
+          raise ProtocolError, "invalid JSON-RPC version" unless response["jsonrpc"] == "2.0"
+          raise ProtocolError, "mismatched JSON-RPC response id" unless response["id"] == request_id
+          raise_remote(response["error"]) if response["error"]
+          Protocol.deep_freeze(Protocol.object(response["result"], "JSON-RPC result").dup)
+        end
+      rescue Timeout
+        unless initializing
+          begin
+            @transport.notify(notification("notifications/cancelled", requestId: request_id, reason: "request timed out"))
+          rescue StandardError
+            nil
+          end
+        end
+        raise
+      end
+
+      def validate_initialization(result)
+        version = Protocol.string(result["protocolVersion"], "protocol version", empty: false, max: 64)
+        raise ProtocolError, "unsupported MCP protocol version: #{version}" unless version == PROTOCOL_VERSION
+        @capabilities = Protocol.deep_freeze(Protocol.object(result["capabilities"], "server capabilities").dup)
+        @server_info = Protocol.deep_freeze(Protocol.object(result.fetch("serverInfo", {}), "server info").dup)
+      end
+
+      def list_all(method, key, capability)
+        raise ProtocolError, "server does not advertise #{capability}" unless @capabilities.key?(capability.to_s)
+        items = []
+        cursor = nil
+        100.times do
+          result = request_now(method, cursor ? {cursor: cursor} : {})
+          values = Protocol.collection(result[key], key)
+          values.each { |value| items << validate_descriptor(value, capability) }
+          raise ProtocolError, "#{key} list is too large" if items.length > Protocol::MAX_COLLECTION
+          cursor = result["nextCursor"]
+          break unless cursor
+          Protocol.string(cursor, "next cursor", empty: false, max: 4096)
+        end
+        raise ProtocolError, "#{key} pagination exceeds 100 pages" if cursor
+        Protocol.deep_freeze(items)
+      end
+
+      def validate_descriptor(value, capability)
+        value = Protocol.object(value, "#{capability} descriptor").dup
+        key = capability == :resources ? "uri" : "name"
+        Protocol.string(value[key], "#{capability} #{key}", empty: false, max: 4096)
+        Protocol.object(value["inputSchema"], "tool input schema") if capability == :tools
+        value
+      end
+
+      def validate_result_collection(result, key)
+        Protocol.collection(result[key], key).each { |value| Protocol.json(value) }
+        result
+      end
+
+      def raise_remote(error)
+        error = Protocol.object(error, "JSON-RPC error")
+        code = error["code"]
+        raise ProtocolError, "JSON-RPC error code must be an integer" unless code.is_a?(Integer)
+        message = Protocol.string(error["message"], "JSON-RPC error message", empty: false)
+        Protocol.json(error["data"]) if error.key?("data")
+        raise RemoteError.new(code, message, error["data"])
+      end
+
+      def notification(method, **params)
+        message = {"jsonrpc" => "2.0", "method" => method}
+        message["params"] = params unless params.empty?
+        message
+      end
+
+      def positive_timeout(value)
+        raise ProtocolError, "timeout must be positive" unless value.is_a?(Numeric) && value.positive?
+        value
+      end
+    end
+  end
+end
+
+require_relative "mcp/transports"

data/lib/nunki/protocol.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Nunki
+  module Protocol
+    MAX_DEPTH = 32
+    MAX_COLLECTION = 10_000
+    MAX_STRING = 1_048_576
+
+    module_function
+
+    def json(value, depth = 0)
+      raise ProtocolError, "JSON nesting exceeds #{MAX_DEPTH}" if depth > MAX_DEPTH
+
+      case value
+      when nil, true, false, Integer
+        value
+      when Float
+        raise ProtocolError, "JSON number must be finite" unless value.finite?
+      when String
+        string(value, "JSON string")
+      when Array
+        collection(value, "JSON array").each { |item| json(item, depth + 1) }
+      when Hash
+        object(value, "JSON object").each do |key, item|
+          raise ProtocolError, "JSON object keys must be strings or symbols" unless key.is_a?(String) || key.is_a?(Symbol)
+          json(item, depth + 1)
+        end
+      else
+        raise ProtocolError, "unsupported JSON value: #{value.class}"
+      end
+      value
+    end
+
+    def parse(source, name = "response")
+      string(source, name, max: nil)
+      json(JSON.parse(source, max_nesting: MAX_DEPTH))
+    rescue JSON::ParserError => error
+      raise ProtocolError, "invalid #{name}: #{error.message}"
+    end
+
+    def object(value, name)
+      raise ProtocolError, "#{name} must be an object" unless value.is_a?(Hash)
+      raise ProtocolError, "#{name} has too many members" if value.length > MAX_COLLECTION
+      value
+    end
+
+    def collection(value, name)
+      raise ProtocolError, "#{name} must be an array" unless value.is_a?(Array)
+      raise ProtocolError, "#{name} has too many items" if value.length > MAX_COLLECTION
+      value
+    end
+
+    def string(value, name, empty: true, max: MAX_STRING)
+      raise ProtocolError, "#{name} must be a string" unless value.is_a?(String)
+      raise ProtocolError, "#{name} must not be empty" if !empty && value.empty?
+      raise ProtocolError, "#{name} is too large" if max && value.bytesize > max
+      encoded = value.encode(Encoding::UTF_8)
+      raise EncodingError unless encoded.valid_encoding?
+      encoded
+    rescue EncodingError
+      raise ProtocolError, "#{name} must be valid UTF-8"
+    end
+
+    def uint(value, name, positive: false)
+      minimum = positive ? 1 : 0
+      raise ProtocolError, "#{name} must be an integer >= #{minimum}" unless value.is_a?(Integer) && value >= minimum
+      value
+    end
+
+    def deep_freeze(value)
+      case value
+      when Array then value.each { |item| deep_freeze(item) }
+      when Hash then value.each { |key, item| deep_freeze(key); deep_freeze(item) }
+      end
+      value.freeze
+    end
+  end
+end

data/lib/nunki/provider.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Nunki
+  class Provider
+    HTTP_OPTIONS = %i[headers open_timeout read_timeout retries retry_base max_request_bytes max_response_bytes].freeze
+
+    def self.build(kind, endpoint:, api_key: nil, model:, **options)
+      kind = kind.to_s.tr("-", "_").to_sym
+      provider = case kind
+      when :openai, :openai_compatible, :local then Providers::OpenAI
+      when :anthropic then Providers::Anthropic
+      else raise ProtocolError, "unknown provider kind: #{kind}"
+      end
+
+      http_options = options.select { |key, _| HTTP_OPTIONS.include?(key) }
+      provider_options = options.reject { |key, _| HTTP_OPTIONS.include?(key) }
+      headers = http_options.delete(:headers) || {}
+      client = HTTP::Client.new(endpoint: endpoint, headers: headers.merge(provider.headers(api_key)), **http_options)
+      provider.new(client: client, model: model, **provider_options)
+    end
+
+    def initialize(client:, model:, dispatch: ->(&block) { block.call }, context_limit: nil)
+      @client = client
+      @model = Protocol.string(model, "model", empty: false, max: 256)
+      raise ProtocolError, "dispatch must respond to call" unless dispatch.respond_to?(:call)
+      @dispatch = dispatch
+      @context_limit = context_limit && Protocol.uint(context_limit, "context_limit", positive: true)
+      @call_lock = Mutex.new
+    end
+
+    def complete(messages, tools: [], system: nil, max_tokens: 1024, &stream)
+      @dispatch.call do
+        raise Error, "a completion is already in progress" unless @call_lock.try_lock
+        begin
+          perform_complete(prepare(messages, tools, system, max_tokens), &stream)
+        ensure
+          @call_lock.unlock
+        end
+      end
+    end
+
+    def cancel = @client.cancel
+
+    private
+
+    def prepare(messages, tools, system, max_tokens)
+      Context.validate_messages(Protocol.collection(messages, "messages"))
+      tools = validate_tools(Protocol.collection(tools, "tools"))
+      system = Protocol.string(system, "system") if system
+      max_tokens = Protocol.uint(max_tokens, "max_tokens", positive: true)
+      if @context_limit
+        raise ProtocolError, "context_limit must exceed max_tokens" unless @context_limit > max_tokens
+        messages = Context.truncate(messages, max_tokens: @context_limit - max_tokens)
+      end
+      [messages, tools, system, max_tokens]
+    end
+
+    def validate_tools(tools)
+      tools.each do |tool|
+        raise ProtocolError, "tool must be a Nunki::Tool" unless tool.is_a?(Tool)
+        Protocol.string(tool.name, "tool name", empty: false, max: 256)
+        Protocol.string(tool.description, "tool description", max: 16_384)
+        Protocol.json(Protocol.object(tool.input_schema, "tool input schema"))
+      end
+      tools
+    end
+
+    def parse_event(event)
+      Protocol.object(Protocol.parse(event.data, "SSE data"), "SSE data")
+    end
+
+    def response(parts, usage, finish_reason)
+      Response.new(
+        message: Message.new(role: :assistant, content: parts.freeze),
+        usage: Usage.new(input_tokens: usage[0], output_tokens: usage[1]),
+        finish_reason: finish_reason
+      )
+    end
+
+    def text_part(text)
+      Part.new(type: :text, text: text, tool_name: nil, tool_input: nil, tool_use_id: nil)
+    end
+
+    def tool_part(name, input, id)
+      name = Protocol.string(name, "tool name", empty: false, max: 256)
+      id = Protocol.string(id, "tool id", empty: false, max: 1024)
+      input = Protocol.object(input, "tool input")
+      Part.new(type: :tool_use, text: nil, tool_name: name, tool_input: input, tool_use_id: id)
+    end
+  end
+
+  module Providers; end
+end