manceps 1.0.0

data/lib/manceps/tool.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Manceps
+  # An MCP tool definition.
+  class Tool
+    attr_reader :name, :description, :input_schema, :output_schema, :annotations, :title
+
+    def initialize(data)
+      @name = data['name']
+      @description = data['description']
+      @title = data['title']
+      @input_schema = data['inputSchema']
+      @output_schema = data['outputSchema']
+      @annotations = data['annotations']
+    end
+
+    def to_h
+      h = { 'name' => name, 'description' => description, 'inputSchema' => input_schema }
+      h['title'] = title if title
+      h['outputSchema'] = output_schema if output_schema
+      h
+    end
+  end
+end

data/lib/manceps/tool_result.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Manceps
+  # Result of a tool invocation.
+  class ToolResult
+    attr_reader :content, :is_error, :structured_content
+
+    def initialize(data)
+      @content = (data['content'] || []).map { |c| Content.new(c) }
+      @is_error = data['isError'] || false
+      @structured_content = data['structuredContent']
+    end
+
+    def error?
+      is_error
+    end
+
+    def text
+      content.select(&:text?).map(&:text).join("\n")
+    end
+
+    def structured?
+      !structured_content.nil?
+    end
+  end
+end

data/lib/manceps/transport/base.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Manceps
+  module Transport
+    # Abstract base class for MCP transports.
+    class Base
+      def request(body)
+        raise NotImplementedError
+      end
+
+      def request_streaming(body, &)
+        raise NotImplementedError
+      end
+
+      def notify(body)
+        raise NotImplementedError
+      end
+
+      def terminate_session(session_id)
+        raise NotImplementedError
+      end
+
+      def close
+        raise NotImplementedError
+      end
+
+      def listen(&)
+        raise NotImplementedError
+      end
+
+      def on_notification(&block)
+        @notification_callback = block
+      end
+    end
+  end
+end

data/lib/manceps/transport/stdio.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'json'
+
+module Manceps
+  module Transport
+    # Stdio transport: communicates with a local subprocess via stdin/stdout.
+    class Stdio < Base
+      def initialize(command, args: [], env: {})
+        super()
+        @command = command
+        @args = args
+        @env = env
+        @stdin = nil
+        @stdout = nil
+        @stderr = nil
+        @wait_thread = nil
+        @mutex = Mutex.new
+        @notification_callback = nil
+      end
+
+      def open
+        close if @wait_thread # Clean up any existing process
+
+        @stdin, @stdout, @stderr, @wait_thread = Open3.popen3(@env, @command, *@args)
+
+        at_exit { close }
+
+        self
+      end
+
+      def request(body)
+        @mutex.synchronize do
+          write_message(body)
+          read_response
+        end
+      end
+
+      def notify(body)
+        @mutex.synchronize do
+          write_message(body)
+        end
+      end
+
+      def terminate_session(_session_id)
+        # No-op for stdio -- session ends when the process exits
+      end
+
+      def listen(&block)
+        raise ConnectionError, 'Stdio transport not open' unless @stdout
+
+        loop do
+          line = @stdout.gets
+          break if line.nil?
+
+          parsed = begin
+            JSON.parse(line)
+          rescue StandardError
+            next
+          end
+          block.call(parsed) if parsed['method']
+        end
+      end
+
+      def close
+        return unless @wait_thread
+
+        begin
+          @stdin&.close
+        rescue StandardError
+          nil
+        end
+
+        if @wait_thread.alive?
+          begin
+            Process.kill('TERM', @wait_thread.pid)
+          rescue StandardError
+            nil
+          end
+
+          unless @wait_thread.join(5)
+            begin
+              Process.kill('KILL', @wait_thread.pid)
+            rescue StandardError
+              nil
+            end
+            begin
+              @wait_thread.join(1)
+            rescue StandardError
+              nil
+            end
+          end
+        end
+
+        begin
+          @stdout&.close
+        rescue StandardError
+          nil
+        end
+        begin
+          @stderr&.close
+        rescue StandardError
+          nil
+        end
+        @stdin = nil
+        @stdout = nil
+        @stderr = nil
+        @wait_thread = nil
+      end
+
+      private
+
+      def write_message(body)
+        raise ConnectionError, 'Stdio transport not open' unless @stdin
+
+        json = JSON.generate(body)
+        @stdin.write("#{json}\n")
+        @stdin.flush
+      rescue Errno::EPIPE
+        raise ConnectionError, 'Process exited unexpectedly'
+      end
+
+      def read_response
+        raise ConnectionError, 'Stdio transport not open' unless @stdout
+
+        loop do
+          line = @stdout.gets
+          raise ConnectionError, 'Process exited unexpectedly' if line.nil?
+
+          parsed = JSON.parse(line)
+
+          return parsed unless parsed['method'] && !parsed.key?('id')
+
+          # This is a server-initiated notification; dispatch and keep reading
+          @notification_callback&.call(parsed)
+        end
+      rescue JSON::ParserError => e
+        raise ProtocolError, "Invalid JSON from process: #{e.message}"
+      end
+    end
+  end
+end

data/lib/manceps/transport/streamable_http.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+require 'httpx'
+require 'json'
+
+module Manceps
+  module Transport
+    # Streamable HTTP transport with persistent connections and SSE support.
+    class StreamableHTTP < Base
+      attr_reader :session_id
+      attr_writer :protocol_version
+
+      def initialize(url, auth:, timeout: nil)
+        super()
+        @url = url
+        @auth = auth
+        @session_id = nil
+        @last_event_id = nil
+        @protocol_version = nil
+
+        timeout_opts = timeout || {
+          connect_timeout: Manceps.configuration.connect_timeout,
+          request_timeout: Manceps.configuration.request_timeout
+        }
+
+        # httpx maintains persistent connections by default —
+        # critical because MCP servers bind Mcp-Session-Id to the TCP connection
+        @http = HTTPX.with(timeout: timeout_opts)
+      end
+
+      def request(body)
+        response = @http.post(@url, headers: base_headers, body: JSON.generate(body))
+        handle_connection_error(response)
+        handle_error_response(response)
+        capture_session_id(response)
+        result = parse_response(response)
+        track_event_ids_from_response(response)
+        result
+      rescue Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EPIPE, Errno::EHOSTUNREACH => e
+        raise ConnectionError, e.message
+      end
+
+      def request_streaming(body, &block)
+        response = @http.post(@url, headers: base_headers, body: JSON.generate(body))
+        handle_connection_error(response)
+        handle_error_response(response)
+        capture_session_id(response)
+
+        content_type = response.content_type&.mime_type.to_s
+
+        if content_type.include?('text/event-stream')
+          events = SSEParser.parse_events(response.body.to_s)
+          track_event_ids(events)
+          final_result = nil
+          events.each do |event|
+            parsed = begin
+              JSON.parse(event[:data])
+            rescue StandardError
+              next
+            end
+            if parsed['result'] || parsed['error']
+              final_result = parsed
+            elsif block
+              block.call(parsed)
+            end
+          end
+          final_result || parse_response(response)
+        else
+          parse_response(response)
+        end
+      end
+
+      def notify(body)
+        response = @http.post(@url, headers: base_headers, body: JSON.generate(body))
+        handle_connection_error(response)
+        handle_error_response(response) unless response.status == 202
+      rescue Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EPIPE, Errno::EHOSTUNREACH => e
+        raise ConnectionError, e.message
+      end
+
+      def terminate_session(session_id)
+        headers = {}
+        headers['mcp-session-id'] = session_id
+        @auth.apply(headers)
+        begin
+          @http.delete(@url, headers: headers)
+        rescue StandardError
+          nil
+        end
+      end
+
+      def listen(&block)
+        headers = base_headers.dup
+        headers.delete('content-type')
+        headers['accept'] = 'text/event-stream'
+
+        response = @http.get(@url, headers: headers)
+        handle_error_response(response)
+
+        content_type = response.content_type&.mime_type.to_s
+        return unless content_type.include?('text/event-stream')
+
+        events = SSEParser.parse_events(response.body.to_s)
+        events.each do |event|
+          parsed = begin
+            JSON.parse(event[:data])
+          rescue StandardError
+            next
+          end
+          block.call(parsed) if parsed['method']
+        end
+      end
+
+      def close
+        @http.close if @http.respond_to?(:close)
+        @session_id = nil
+      end
+
+      private
+
+      def base_headers
+        headers = {
+          'content-type' => 'application/json',
+          '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['last-event-id'] = @last_event_id if @last_event_id
+        @auth.apply(headers)
+        headers
+      end
+
+      def parse_response(response)
+        body = response.body.to_s
+        content_type = response.content_type&.mime_type.to_s
+
+        if content_type.include?('text/event-stream')
+          SSEParser.extract_json(body)
+        else
+          JSON.parse(body)
+        end
+      rescue JSON::ParserError => e
+        raise ProtocolError, "Invalid JSON in response: #{e.message}"
+      end
+
+      def capture_session_id(response)
+        sid = response.headers['mcp-session-id']
+        @session_id = sid if sid
+      end
+
+      def track_event_ids(events)
+        last = events.select { |e| e[:id] }.last
+        @last_event_id = last[:id] if last
+      end
+
+      def track_event_ids_from_response(response)
+        content_type = response.content_type&.mime_type.to_s
+        return unless content_type.include?('text/event-stream')
+
+        events = SSEParser.parse_events(response.body.to_s)
+        track_event_ids(events)
+      end
+
+      def handle_connection_error(response)
+        return unless response.is_a?(HTTPX::ErrorResponse)
+
+        error = response.error
+        case error
+        when HTTPX::TimeoutError
+          raise TimeoutError, error.message
+        else
+          raise ConnectionError, error.message
+        end
+      end
+
+      def handle_error_response(response)
+        return if response.status < 400
+
+        case response.status
+        when 401
+          raise AuthenticationError, "Server returned 401: #{response.body}"
+        when 404
+          raise SessionExpiredError, 'Session expired (404)'
+        else
+          raise ConnectionError, "HTTP #{response.status}: #{response.body}"
+        end
+      end
+    end
+  end
+end

data/lib/manceps/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Manceps
+  VERSION = '1.0.0'
+end

data/lib/manceps.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'uri'
+require 'securerandom'
+
+require 'httpx'
+
+require_relative 'manceps/version'
+require_relative 'manceps/errors'
+require_relative 'manceps/json_rpc'
+require_relative 'manceps/sse_parser'
+require_relative 'manceps/content'
+require_relative 'manceps/tool'
+require_relative 'manceps/tool_result'
+require_relative 'manceps/prompt'
+require_relative 'manceps/prompt_result'
+require_relative 'manceps/resource'
+require_relative 'manceps/resource_template'
+require_relative 'manceps/resource_contents'
+require_relative 'manceps/elicitation'
+require_relative 'manceps/backoff'
+require_relative 'manceps/session'
+require_relative 'manceps/auth/none'
+require_relative 'manceps/auth/bearer'
+require_relative 'manceps/auth/api_key_header'
+require_relative 'manceps/auth/oauth'
+require_relative 'manceps/transport/base'
+require_relative 'manceps/transport/streamable_http'
+require_relative 'manceps/transport/stdio'
+require_relative 'manceps/task'
+require_relative 'manceps/client'
+
+# Ruby client for the Model Context Protocol (MCP).
+module Manceps
+  Configuration = Struct.new(
+    :client_name,
+    :client_version,
+    :client_description,
+    :protocol_version,
+    :supported_versions,
+    :request_timeout,
+    :connect_timeout,
+    keyword_init: true
+  ) do
+    def initialize(**)
+      super
+      self.client_name ||= 'Manceps'
+      self.client_version ||= Manceps::VERSION
+      self.protocol_version ||= '2025-11-25'
+      self.supported_versions ||= %w[2025-11-25 2025-06-18 2025-03-26]
+      self.request_timeout ||= 30
+      self.connect_timeout ||= 10
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+  end
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: manceps
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Obie Fernandez
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: httpx
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: A production-grade MCP client with first-class auth support. Connect
+  to MCP servers over Streamable HTTP or stdio, discover and invoke tools, read resources,
+  and get prompts.
+email:
+- obie@fernandez.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/manceps.rb
+- lib/manceps/auth/api_key_header.rb
+- lib/manceps/auth/bearer.rb
+- lib/manceps/auth/none.rb
+- lib/manceps/auth/oauth.rb
+- lib/manceps/backoff.rb
+- lib/manceps/client.rb
+- lib/manceps/content.rb
+- lib/manceps/elicitation.rb
+- lib/manceps/errors.rb
+- lib/manceps/json_rpc.rb
+- lib/manceps/prompt.rb
+- lib/manceps/prompt_result.rb
+- lib/manceps/resource.rb
+- lib/manceps/resource_contents.rb
+- lib/manceps/resource_template.rb
+- lib/manceps/session.rb
+- lib/manceps/sse_parser.rb
+- lib/manceps/task.rb
+- lib/manceps/tool.rb
+- lib/manceps/tool_result.rb
+- lib/manceps/transport/base.rb
+- lib/manceps/transport/stdio.rb
+- lib/manceps/transport/streamable_http.rb
+- lib/manceps/version.rb
+homepage: https://github.com/zarpay/manceps
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/zarpay/manceps
+  source_code_uri: https://github.com/zarpay/manceps
+  changelog_uri: https://github.com/zarpay/manceps/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Ruby client for the Model Context Protocol (MCP)
+test_files: []