manceps 1.0.0

data/lib/manceps/client.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+module Manceps
+  # MCP protocol client supporting tools, resources, prompts, and notifications.
+  class Client
+    attr_reader :session
+
+    def initialize(url_or_command, auth: Auth::None.new, args: nil, env: nil, max_retries: 3, **options)
+      @transport = if args || !url_or_command.match?(%r{\Ahttps?://}i)
+                     Transport::Stdio.new(url_or_command, args: args || [], env: env || {})
+                   else
+                     Transport::StreamableHTTP.new(url_or_command, auth: auth, timeout: options[:timeout])
+                   end
+      @session = Session.new
+      @max_retries = max_retries
+      @backoff = Backoff.new
+      @notification_handlers = Hash.new { |h, k| h[k] = [] }
+      @elicitation_handler = nil
+    end
+
+    def connect
+      attempts = 0
+      begin
+        @transport.open if @transport.respond_to?(:open)
+
+        init_response = @transport.request(
+          JsonRpc.initialize_request(@session.next_id, capabilities: client_capabilities)
+        )
+        handle_rpc_error(init_response)
+        @session.establish(init_response)
+
+        unless Manceps.configuration.supported_versions.include?(@session.protocol_version)
+          server_version = @session.protocol_version
+          disconnect
+          raise ProtocolError.new(
+            "Server negotiated unsupported protocol version: #{server_version}",
+            code: -32_600
+          )
+        end
+
+        @transport.protocol_version = @session.protocol_version if @transport.respond_to?(:protocol_version=)
+
+        @transport.notify(JsonRpc.initialized_notification)
+        @backoff.reset
+        self
+      rescue ConnectionError, TimeoutError
+        attempts += 1
+        @transport.close if @transport.respond_to?(:close)
+        @session.reset
+        raise if attempts > @max_retries
+
+        sleep @backoff.next_delay
+        retry
+      end
+    end
+
+    def disconnect
+      sid = @transport.respond_to?(:session_id) ? @transport.session_id : @session.id
+      @transport.terminate_session(sid) if sid
+      @transport.close
+      @session.reset
+    end
+
+    def connected?
+      @session.active?
+    end
+
+    def reconnect!
+      @transport.close
+      @session.reset
+      connect
+    end
+
+    def ping
+      @transport.notify(JsonRpc.notification('ping'))
+      true
+    rescue ConnectionError, TimeoutError
+      false
+    end
+
+    def tools(force: false) # rubocop:disable Lint/UnusedMethodArgument
+      paginate_with_retry('tools/list', 'tools') { |data| Tool.new(data) }
+    end
+
+    def call_tool(name, **arguments)
+      response = request_with_retry('tools/call', name: name, arguments: arguments)
+      ToolResult.new(response['result'])
+    end
+
+    def call_tool_streaming(name, **arguments, &block)
+      body = JsonRpc.request(@session.next_id, 'tools/call', { name: name, arguments: arguments })
+      wrapped_block = if block
+                        proc do |event|
+                          if event.is_a?(Hash) && event['id'] && event['method']
+                            handle_server_request(event)
+                          else
+                            block.call(event)
+                          end
+                        end
+                      end
+      response = @transport.request_streaming(body, &wrapped_block)
+      handle_rpc_error(response)
+      ToolResult.new(response['result'])
+    end
+
+    def prompts(force: false) # rubocop:disable Lint/UnusedMethodArgument
+      paginate_with_retry('prompts/list', 'prompts') { |data| Prompt.new(data) }
+    end
+
+    def get_prompt(name, **arguments)
+      response = request_with_retry('prompts/get', name: name, arguments: arguments)
+      PromptResult.new(response['result'])
+    end
+
+    def resources(force: false) # rubocop:disable Lint/UnusedMethodArgument
+      paginate_with_retry('resources/list', 'resources') { |data| Resource.new(data) }
+    end
+
+    def resource_templates
+      paginate_with_retry('resources/templates/list', 'resourceTemplates') { |data| ResourceTemplate.new(data) }
+    end
+
+    def read_resource(uri)
+      response = request_with_retry('resources/read', uri: uri)
+      ResourceContents.new(response['result'])
+    end
+
+    def on(method, &block)
+      @notification_handlers[method] << block
+    end
+
+    def subscribe_resource(uri)
+      request('resources/subscribe', uri: uri)
+    end
+
+    def unsubscribe_resource(uri)
+      request('resources/unsubscribe', uri: uri)
+    end
+
+    def cancel_request(request_id, reason: nil)
+      params = { requestId: request_id }
+      params[:reason] = reason if reason
+      @transport.notify(JsonRpc.notification('notifications/cancelled', params))
+    end
+
+    def listen
+      @transport.listen do |message|
+        if message['id'] && message['method']
+          handle_server_request(message)
+        else
+          method = message['method']
+          params = message['params']
+          handlers = @notification_handlers[method]
+          handlers&.each { |h| h.call(params) }
+        end
+      end
+    end
+
+    def on_elicitation(&block)
+      @elicitation_handler = block
+    end
+
+    # --- Tasks (experimental, protocol 2025-11-25) ---
+
+    def tasks
+      response = request('tasks/list')
+      (response.dig('result', 'tasks') || []).map { |data| Task.new(data) }
+    end
+
+    def get_task(task_id)
+      response = request('tasks/get', taskId: task_id)
+      Task.new(response['result'])
+    end
+
+    def cancel_task(task_id) # rubocop:disable Naming/PredicateMethod
+      request('tasks/cancel', taskId: task_id)
+      true
+    end
+
+    def await_task(task_id, interval: 1, timeout: nil)
+      deadline = timeout ? Time.now + timeout : nil
+
+      loop do
+        task = get_task(task_id)
+        return task if task.done?
+
+        if deadline && Time.now >= deadline
+          raise TimeoutError, "Task #{task_id} did not complete within #{timeout} seconds"
+        end
+
+        sleep interval
+      end
+    end
+
+    def self.open(url, **)
+      client = new(url, **)
+      client.connect
+      yield client
+    ensure
+      client&.disconnect
+    end
+
+    MAX_PAGES = 100
+
+    private
+
+    def client_capabilities
+      caps = {}
+      caps['elicitation'] = { 'form' => {} } if @elicitation_handler
+      caps
+    end
+
+    def handle_server_request(request_data)
+      case request_data['method']
+      when 'elicitation/create'
+        return unless @elicitation_handler
+
+        elicitation = Elicitation.new(request_data['params'])
+        result = @elicitation_handler.call(elicitation)
+        response = JsonRpc.response(request_data['id'], result)
+        @transport.notify(response)
+      end
+    end
+
+    def request(method, **params)
+      body = JsonRpc.request(@session.next_id, method, params)
+      response = @transport.request(body)
+      handle_rpc_error(response)
+      response
+    end
+
+    def request_with_retry(method, **params)
+      request(method, **params)
+    rescue SessionExpiredError
+      reconnect!
+      request(method, **params)
+    end
+
+    def paginate(method, items_key, &)
+      results = []
+      cursor = nil
+      pages = 0
+
+      loop do
+        params = cursor ? { cursor: cursor } : {}
+        response = request(method, **params)
+        items = response.dig('result', items_key) || []
+        results.concat(items.map(&))
+
+        cursor = response.dig('result', 'nextCursor')
+        pages += 1
+        break if cursor.nil? || pages >= MAX_PAGES
+      end
+
+      results
+    end
+
+    def paginate_with_retry(method, items_key, &)
+      paginate(method, items_key, &)
+    rescue SessionExpiredError
+      reconnect!
+      paginate(method, items_key, &)
+    end
+
+    def handle_rpc_error(response)
+      return unless response.is_a?(Hash)
+
+      error = response['error'] || response[:error]
+      return unless error
+
+      raise ProtocolError.new(
+        error['message'] || error[:message] || 'Unknown JSON-RPC error',
+        code: error['code'] || error[:code],
+        data: error['data'] || error[:data]
+      )
+    end
+  end
+end

data/lib/manceps/content.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Manceps
+  # A single content item returned by an MCP tool or prompt.
+  class Content
+    attr_reader :type, :text, :data, :mime_type, :uri, :resource
+
+    def initialize(data)
+      @type = data['type']
+      @text = data['text']
+      @data = data['data']        # base64 for image/audio
+      @mime_type = data['mimeType']
+      @uri = data['uri']          # for resource content
+      @resource = data['resource'] # for resource_link type
+    end
+
+    def text?
+      type == 'text'
+    end
+
+    def image?
+      type == 'image'
+    end
+
+    def resource?
+      type == 'resource'
+    end
+
+    def resource_link?
+      type == 'resource_link'
+    end
+  end
+end

data/lib/manceps/elicitation.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Manceps
+  # Server-initiated request for additional user input.
+  class Elicitation
+    attr_reader :id, :message, :requested_schema
+
+    def initialize(data)
+      @id = data['id']
+      @message = data['message']
+      @requested_schema = data['requestedSchema']
+    end
+
+    def self.accept(content)
+      { action: 'accept', content: content }
+    end
+
+    def self.decline
+      { action: 'decline' }
+    end
+
+    def self.cancel
+      { action: 'cancel' }
+    end
+  end
+end

data/lib/manceps/errors.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Manceps
+  class Error < StandardError; end
+
+  class ConnectionError < Error; end
+  class TimeoutError < Error; end
+
+  # JSON-RPC error from the MCP server.
+  class ProtocolError < Error
+    attr_reader :code, :data
+
+    def initialize(message, code: nil, data: nil)
+      @code = code
+      @data = data
+      super(message)
+    end
+  end
+
+  class AuthenticationError < Error; end
+  class SessionExpiredError < Error; end
+
+  # Error raised when a tool invocation fails.
+  class ToolError < Error
+    attr_reader :result
+
+    def initialize(message, result: nil)
+      @result = result
+      super(message)
+    end
+  end
+end

data/lib/manceps/json_rpc.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Manceps
+  # JSON-RPC 2.0 message construction helpers.
+  module JsonRpc
+    module_function
+
+    def request(id, method, params = {})
+      { jsonrpc: '2.0', id: id, method: method, params: params }
+    end
+
+    def notification(method, params = {})
+      { jsonrpc: '2.0', method: method, params: params }
+    end
+
+    def initialize_request(id, client_info: nil, capabilities: {})
+      config = Manceps.configuration
+      info = client_info || { name: config.client_name, version: config.client_version }
+      info[:description] = config.client_description if config.client_description
+
+      request(id, 'initialize', {
+                protocolVersion: config.protocol_version,
+                capabilities: capabilities,
+                clientInfo: info
+              })
+    end
+
+    def response(id, result)
+      { jsonrpc: '2.0', id: id, result: result }
+    end
+
+    def initialized_notification
+      notification('notifications/initialized')
+    end
+
+    def parse_response(data)
+      data = JSON.parse(data, symbolize_names: true) if data.is_a?(String)
+
+      raise ProtocolError, "Invalid JSON-RPC version: #{data[:jsonrpc]}" unless data[:jsonrpc] == '2.0'
+
+      if data[:error]
+        err = data[:error]
+        raise ProtocolError.new(
+          err[:message] || 'Unknown error',
+          code: err[:code],
+          data: err[:data]
+        )
+      end
+
+      data
+    end
+  end
+end

data/lib/manceps/prompt.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Manceps
+  # An MCP prompt definition.
+  class Prompt
+    attr_reader :name, :description, :arguments, :title
+
+    def initialize(data)
+      @name = data['name']
+      @description = data['description']
+      @title = data['title']
+      @arguments = (data['arguments'] || []).map { |a| Argument.new(a) }
+    end
+
+    # A prompt argument definition.
+    class Argument
+      attr_reader :name, :description, :required
+
+      def initialize(data)
+        @name = data['name']
+        @description = data['description']
+        @required = data['required'] || false
+      end
+
+      def required?
+        required
+      end
+    end
+  end
+end

data/lib/manceps/prompt_result.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Manceps
+  # Result of a prompt/get request.
+  class PromptResult
+    attr_reader :description, :messages
+
+    def initialize(data)
+      @description = data['description']
+      @messages = (data['messages'] || []).map { |m| Message.new(m) }
+    end
+
+    # A single message within a prompt result.
+    class Message
+      attr_reader :role, :content
+
+      def initialize(data)
+        @role = data['role']
+        @content = Content.new(data['content']) if data['content']
+      end
+
+      def text
+        content&.text
+      end
+    end
+  end
+end

data/lib/manceps/resource.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Manceps
+  # An MCP resource definition.
+  class Resource
+    attr_reader :uri, :name, :description, :mime_type, :annotations, :title
+
+    def initialize(data)
+      @uri = data['uri']
+      @name = data['name']
+      @description = data['description']
+      @mime_type = data['mimeType']
+      @annotations = data['annotations']
+      @title = data['title']
+    end
+  end
+end

data/lib/manceps/resource_contents.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Manceps
+  # Contents returned from a resource read.
+  class ResourceContents
+    attr_reader :contents
+
+    def initialize(data)
+      @contents = (data['contents'] || []).map { |c| Content.new(c) }
+    end
+
+    def text
+      contents.select(&:text?).map(&:text).join("\n")
+    end
+  end
+end

data/lib/manceps/resource_template.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Manceps
+  # An MCP resource template definition.
+  class ResourceTemplate
+    attr_reader :uri_template, :name, :description, :mime_type, :annotations, :title
+
+    def initialize(data)
+      @uri_template = data['uriTemplate']
+      @name = data['name']
+      @description = data['description']
+      @mime_type = data['mimeType']
+      @annotations = data['annotations']
+      @title = data['title']
+    end
+  end
+end

data/lib/manceps/session.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Manceps
+  # Tracks MCP session state and protocol negotiation.
+  class Session
+    attr_reader :id, :capabilities, :protocol_version, :server_info
+
+    def initialize
+      reset
+    end
+
+    def next_id
+      @request_counter += 1
+    end
+
+    def establish(response)
+      result = response['result'] || response[:result] || {}
+      @id = response['session_id'] || response['sessionId'] ||
+            response[:session_id] || response[:sessionId]
+      @capabilities = result['capabilities'] || result[:capabilities] || {}
+      @protocol_version = result['protocolVersion'] || result[:protocolVersion]
+      @server_info = result['serverInfo'] || result[:serverInfo]
+      @established = true
+    end
+
+    def active?
+      @established
+    end
+
+    def server_supports?(capability)
+      capabilities.key?(capability.to_s) || capabilities.key?(capability.to_sym)
+    end
+
+    def reset
+      @id = nil
+      @capabilities = {}
+      @protocol_version = nil
+      @server_info = nil
+      @request_counter = 0
+      @established = false
+    end
+  end
+end

data/lib/manceps/sse_parser.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Manceps
+  # Parser for Server-Sent Events streams.
+  module SSEParser
+    module_function
+
+    def extract_json(body)
+      return nil if body.nil? || body.strip.empty?
+
+      data_lines = body.each_line.filter_map do |line|
+        line.strip.start_with?('data:') ? line.strip.sub(/\Adata:\s?/, '') : nil
+      end
+
+      return nil if data_lines.empty?
+
+      JSON.parse(data_lines.join, symbolize_names: true)
+    end
+
+    def parse_events(body)
+      return [] if body.nil? || body.strip.empty?
+
+      events = []
+      current = { id: nil, event: nil, data: [] }
+
+      body.each_line do |raw_line|
+        line = raw_line.chomp
+
+        if line.empty?
+          unless current[:data].empty?
+            events << {
+              id: current[:id],
+              event: current[:event],
+              data: current[:data].join("\n")
+            }
+          end
+          current = { id: nil, event: nil, data: [] }
+          next
+        end
+
+        if line.start_with?('id:')
+          current[:id] = line.sub(/\Aid:\s?/, '')
+        elsif line.start_with?('event:')
+          current[:event] = line.sub(/\Aevent:\s?/, '')
+        elsif line.start_with?('data:')
+          current[:data] << line.sub(/\Adata:\s?/, '')
+        end
+      end
+
+      # Flush any trailing event without a final blank line
+      unless current[:data].empty?
+        events << {
+          id: current[:id],
+          event: current[:event],
+          data: current[:data].join("\n")
+        }
+      end
+
+      events
+    end
+  end
+end

data/lib/manceps/task.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Manceps
+  # An MCP task for tracking long-running operations.
+  class Task
+    attr_reader :id, :status, :result, :error, :metadata
+
+    STATUSES = %w[pending running completed failed cancelled].freeze
+
+    def initialize(data)
+      @id = data['id']
+      @status = data['status']
+      @result = data['result']
+      @error = data['error']
+      @metadata = data['metadata'] || data['_meta']
+    end
+
+    def pending?
+      status == 'pending'
+    end
+
+    def running?
+      status == 'running'
+    end
+
+    def completed?
+      status == 'completed'
+    end
+
+    def failed?
+      status == 'failed'
+    end
+
+    def cancelled?
+      status == 'cancelled'
+    end
+
+    def done?
+      completed? || failed? || cancelled?
+    end
+  end
+end