html2md_mcp_client 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 34d52357bfe3faf50a85c791fa1414d29eb0ab42d83b80626097b7adf833e124
+  data.tar.gz: 7dfb0223f53396746eaf21a5269ee67484a558b9b73cb3098f6a3e70e68a8f18
+SHA512:
+  metadata.gz: 15e7d4a875fa147807dd36c0e718a1b09416a74851181cf0d3dea2fecc26c4cc769b00aad5e254a0960da224bc9ef817e3b64b60dc9684e10e1148216f53f420
+  data.tar.gz: ac8489cb3eef307458c09610f09dfb13f99f54ea282a7ce14cd630854af819b78d6880e8d1f0b0eedaf6cc7e897b2de5d73ddd735e6e7d34cf1d3337e88210b2

data/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gemspec

data/html2md_mcp_client.gemspec

@@ -0,0 +1,22 @@
+$:.push File.expand_path('../lib', __FILE__)
+require 'html2md_mcp_client/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'html2md_mcp_client'
+  s.version     = Html2mdMcpClient::VERSION
+  s.platform    = Gem::Platform::RUBY
+  s.authors     = ['Searchbird']
+  s.email       = ['dev@searchbird.io']
+  s.homepage    = 'https://github.com/roscom/html2md_mcp_client'
+  s.summary     = 'Ruby client for the Model Context Protocol (MCP)'
+  s.description = 'Connects to MCP servers over HTTP or stdio. Supports tools, resources, and prompts.'
+  s.license     = 'MIT'
+
+  s.required_ruby_version = '>= 2.5'
+
+  s.files       = Dir['lib/**/*'] + %w[Gemfile html2md_mcp_client.gemspec]
+  s.test_files  = Dir['spec/**/*']
+
+  s.add_development_dependency 'rspec', '~> 3.0'
+  s.add_development_dependency 'webmock', '~> 3.0'
+end

data/lib/html2md_mcp_client/client.rb

@@ -0,0 +1,160 @@
+require 'json'
+require 'securerandom'
+
+module Html2mdMcpClient
+  class Client
+    JSONRPC_VERSION = '2.0'.freeze
+    PROTOCOL_VERSION = '2025-03-26'.freeze
+
+    attr_reader :transport, :server_info, :capabilities
+
+    def initialize(transport, client_name: 'html2md_mcp_client', client_version: Html2mdMcpClient::VERSION)
+      @transport = transport
+      @client_name = client_name
+      @client_version = client_version
+      @request_id = 0
+      @connected = false
+      @tools_cache = nil
+    end
+
+    # --- Connection lifecycle ---
+
+    def connect!
+      return self if @connected
+
+      @transport.start if @transport.respond_to?(:start)
+
+      result = request('initialize', {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: { name: @client_name, version: @client_version }
+      })
+
+      @server_info = result['serverInfo']
+      @capabilities = result['capabilities'] || {}
+
+      notify('notifications/initialized')
+      @connected = true
+      self
+    end
+
+    def disconnect!
+      return unless @connected
+      @transport.close
+      @connected = false
+      @tools_cache = nil
+    end
+
+    def connected?
+      @connected
+    end
+
+    # --- Tools ---
+
+    # Returns array of tool definitions: [{ "name" => ..., "description" => ..., "inputSchema" => ... }]
+    def list_tools
+      ensure_connected!
+      @tools_cache ||= begin
+        result = request('tools/list', {})
+        result['tools'] || []
+      end
+    end
+
+    # Call a tool. Returns the content array.
+    # Raises ToolError if the server signals an error.
+    def call_tool(name, arguments = {})
+      ensure_connected!
+      result = request('tools/call', { name: name, arguments: arguments })
+
+      if result['isError']
+        texts = Array(result['content']).select { |c| c['type'] == 'text' }.map { |c| c['text'] }
+        raise ToolError, "Tool '#{name}' error: #{texts.join('; ')}"
+      end
+
+      result['content'] || []
+    end
+
+    # Convenience: call a tool and return joined text content.
+    def tool_text(name, arguments = {})
+      call_tool(name, arguments)
+        .select { |c| c['type'] == 'text' }
+        .map { |c| c['text'] }
+        .join("\n")
+    end
+
+    # Find a tool definition by name. Returns nil if not found.
+    def find_tool(name)
+      list_tools.find { |t| t['name'] == name }
+    end
+
+    # --- Resources ---
+
+    def list_resources
+      ensure_connected!
+      result = request('resources/list', {})
+      result['resources'] || []
+    end
+
+    def read_resource(uri)
+      ensure_connected!
+      result = request('resources/read', { uri: uri })
+      result['contents'] || []
+    end
+
+    # --- Prompts ---
+
+    def list_prompts
+      ensure_connected!
+      result = request('prompts/list', {})
+      result['prompts'] || []
+    end
+
+    def get_prompt(name, arguments = {})
+      ensure_connected!
+      request('prompts/get', { name: name, arguments: arguments })
+    end
+
+    private
+
+    def ensure_connected!
+      raise NotConnectedError, 'Call connect! before making requests' unless @connected
+    end
+
+    def next_id
+      @request_id += 1
+    end
+
+    def request(method, params)
+      payload = {
+        jsonrpc: JSONRPC_VERSION,
+        id: next_id,
+        method: method,
+        params: params
+      }
+
+      response = @transport.send_request(payload)
+      validate_response!(response, payload[:id])
+      response['result']
+    end
+
+    def notify(method, params = {})
+      payload = {
+        jsonrpc: JSONRPC_VERSION,
+        method: method,
+        params: params
+      }
+      @transport.send_notification(payload)
+    end
+
+    def validate_response!(response, expected_id)
+      if response['error']
+        err = response['error']
+        raise ProtocolError, "Server error #{err['code']}: #{err['message']}"
+      end
+
+      unless response['id'] == expected_id
+        raise ProtocolError, "Response ID mismatch: expected #{expected_id}, got #{response['id']}"
+      end
+    end
+  end
+end

data/lib/html2md_mcp_client/errors.rb

@@ -0,0 +1,7 @@
+module Html2mdMcpClient
+  class Error < StandardError; end
+  class ConnectionError < Error; end
+  class ProtocolError < Error; end
+  class ToolError < Error; end
+  class NotConnectedError < Error; end
+end

data/lib/html2md_mcp_client/transport/http.rb

@@ -0,0 +1,83 @@
+require 'net/http'
+require 'json'
+
+module Html2mdMcpClient
+  module Transport
+    class Http
+      attr_reader :session_id
+
+      def initialize(url, headers: {})
+        @uri = URI(url)
+        @headers = headers.merge(
+          'Content-Type' => 'application/json',
+          'Accept' => 'application/json, text/event-stream'
+        )
+        @session_id = nil
+      end
+
+      def send_request(payload)
+        http = build_http
+        post = Net::HTTP::Post.new(@uri.request_uri, request_headers)
+        post.body = payload.to_json
+
+        response = http.request(post)
+        capture_session_id(response)
+
+        unless response.is_a?(Net::HTTPSuccess)
+          raise ConnectionError, "HTTP #{response.code}: #{response.body}"
+        end
+
+        body = response.body.to_s.strip
+
+        if response['content-type']&.include?('text/event-stream')
+          body = parse_sse(body)
+        end
+
+        JSON.parse(body)
+      rescue Errno::ECONNREFUSED, Errno::EHOSTUNREACH, SocketError => e
+        raise ConnectionError, "Cannot connect to #{@uri}: #{e.message}"
+      rescue JSON::ParserError => e
+        raise ProtocolError, "Invalid JSON response: #{e.message}"
+      end
+
+      def send_notification(payload)
+        http = build_http
+        post = Net::HTTP::Post.new(@uri.request_uri, request_headers)
+        post.body = payload.to_json
+        http.request(post)
+      rescue StandardError
+        nil # fire-and-forget
+      end
+
+      def close
+        @session_id = nil
+      end
+
+      private
+
+      def build_http
+        http = Net::HTTP.new(@uri.host, @uri.port)
+        http.use_ssl = (@uri.scheme == 'https')
+        http.open_timeout = 10
+        http.read_timeout = 120
+        http
+      end
+
+      def request_headers
+        h = @headers.dup
+        h['Mcp-Session-Id'] = @session_id if @session_id
+        h
+      end
+
+      def capture_session_id(response)
+        @session_id = response['mcp-session-id'] if response['mcp-session-id']
+      end
+
+      def parse_sse(body)
+        data_lines = body.lines.select { |l| l.start_with?('data:') }
+        return '{}' if data_lines.empty?
+        data_lines.last.sub(/^data:\s*/, '').strip
+      end
+    end
+  end
+end

data/lib/html2md_mcp_client/transport/stdio.rb

@@ -0,0 +1,64 @@
+require 'open3'
+require 'json'
+
+module Html2mdMcpClient
+  module Transport
+    class Stdio
+      def initialize(command, args: [])
+        @command = command
+        @args = args
+        @stdin = nil
+        @stdout = nil
+        @stderr = nil
+        @wait_thread = nil
+      end
+
+      def start
+        @stdin, @stdout, @stderr, @wait_thread = Open3.popen3(@command, *@args)
+      rescue Errno::ENOENT => e
+        raise ConnectionError, "Cannot start '#{@command}': #{e.message}"
+      end
+
+      def send_request(payload)
+        write_line(payload.to_json)
+
+        loop do
+          line = @stdout.gets
+          raise ConnectionError, 'MCP server process terminated' if line.nil?
+
+          line = line.strip
+          next if line.empty?
+
+          begin
+            parsed = JSON.parse(line)
+            return parsed if parsed.key?('id')
+          rescue JSON::ParserError
+            next
+          end
+        end
+      rescue IOError, Errno::EPIPE => e
+        raise ConnectionError, "Lost connection to MCP server: #{e.message}"
+      end
+
+      def send_notification(payload)
+        write_line(payload.to_json)
+      rescue IOError, Errno::EPIPE
+        nil # fire-and-forget
+      end
+
+      def close
+        @stdin&.close rescue nil
+        @stdout&.close rescue nil
+        @stderr&.close rescue nil
+        @wait_thread&.kill rescue nil
+      end
+
+      private
+
+      def write_line(data)
+        @stdin.puts(data)
+        @stdin.flush
+      end
+    end
+  end
+end

data/lib/html2md_mcp_client/version.rb

@@ -0,0 +1,3 @@
+module Html2mdMcpClient
+  VERSION = '0.1.0'.freeze
+end

data/lib/html2md_mcp_client.rb

@@ -0,0 +1,32 @@
+require 'html2md_mcp_client/version'
+require 'html2md_mcp_client/errors'
+require 'html2md_mcp_client/transport/http'
+require 'html2md_mcp_client/transport/stdio'
+require 'html2md_mcp_client/client'
+
+module Html2mdMcpClient
+  # Connect to an MCP server over HTTP.
+  #
+  #   client = Html2mdMcpClient.http("http://localhost:3001/mcp")
+  #   client.connect!
+  #   client.list_tools
+  #   client.call_tool("my_tool", { arg: "value" })
+  #   client.disconnect!
+  #
+  def self.http(url, headers: {}, **opts)
+    transport = Transport::Http.new(url, headers: headers)
+    Client.new(transport, **opts)
+  end
+
+  # Connect to an MCP server over stdio (spawns a subprocess).
+  #
+  #   client = Html2mdMcpClient.stdio("npx", args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"])
+  #   client.connect!
+  #   client.list_tools
+  #   client.disconnect!
+  #
+  def self.stdio(command, args: [], **opts)
+    transport = Transport::Stdio.new(command, args: args)
+    Client.new(transport, **opts)
+  end
+end

data/spec/html2md_mcp_client/client_spec.rb

@@ -0,0 +1,294 @@
+require 'spec_helper'
+
+RSpec.describe Html2mdMcpClient::Client do
+  let(:transport) { instance_double('Transport') }
+  let(:client) { Html2mdMcpClient::Client.new(transport) }
+
+  def stub_connect!
+    allow(transport).to receive(:send_request)
+      .with(hash_including(method: 'initialize'))
+      .and_return(jsonrpc_response(1, initialize_result))
+    allow(transport).to receive(:send_notification)
+    client.connect!
+  end
+
+  describe '#connect!' do
+    it 'performs the initialize handshake' do
+      expect(transport).to receive(:send_request)
+        .with(hash_including(
+          jsonrpc: '2.0',
+          method: 'initialize',
+          params: hash_including(
+            protocolVersion: '2025-03-26',
+            clientInfo: hash_including(name: 'html2md_mcp_client')
+          )
+        ))
+        .and_return(jsonrpc_response(1, initialize_result))
+
+      expect(transport).to receive(:send_notification)
+        .with(hash_including(method: 'notifications/initialized'))
+
+      client.connect!
+    end
+
+    it 'stores server_info and capabilities' do
+      stub_connect!
+      expect(client.server_info).to eq('name' => 'test-server', 'version' => '1.0.0')
+      expect(client.capabilities).to eq('tools' => {})
+    end
+
+    it 'returns self' do
+      stub_connect!
+      expect(client).to be_connected
+    end
+
+    it 'is idempotent when already connected' do
+      stub_connect!
+      expect(transport).not_to receive(:send_request)
+      client.connect!
+    end
+
+    it 'calls start on transport if it responds to start' do
+      transport_with_start = instance_double('StdioTransport', start: nil)
+      c = Html2mdMcpClient::Client.new(transport_with_start)
+
+      allow(transport_with_start).to receive(:send_request)
+        .and_return(jsonrpc_response(1, initialize_result))
+      allow(transport_with_start).to receive(:send_notification)
+
+      expect(transport_with_start).to receive(:start)
+      c.connect!
+    end
+  end
+
+  describe '#disconnect!' do
+    it 'closes the transport' do
+      stub_connect!
+      expect(transport).to receive(:close)
+      client.disconnect!
+      expect(client).not_to be_connected
+    end
+
+    it 'does nothing when not connected' do
+      expect(transport).not_to receive(:close)
+      client.disconnect!
+    end
+
+    it 'clears the tools cache' do
+      stub_connect!
+
+      allow(transport).to receive(:send_request)
+        .with(hash_including(method: 'tools/list'))
+        .and_return(jsonrpc_response(2, { 'tools' => [{ 'name' => 'foo' }] }))
+
+      client.list_tools
+
+      expect(transport).to receive(:close)
+      client.disconnect!
+
+      # Reconnect and verify cache is cleared
+      allow(transport).to receive(:send_request)
+        .with(hash_including(method: 'initialize'))
+        .and_return(jsonrpc_response(3, initialize_result))
+      allow(transport).to receive(:send_notification)
+      client.connect!
+
+      allow(transport).to receive(:send_request)
+        .with(hash_including(method: 'tools/list'))
+        .and_return(jsonrpc_response(4, { 'tools' => [{ 'name' => 'bar' }] }))
+
+      expect(client.list_tools.first['name']).to eq('bar')
+    end
+  end
+
+  describe '#list_tools' do
+    before { stub_connect! }
+
+    it 'returns tool definitions' do
+      tools = [
+        { 'name' => 'html_to_markdown', 'description' => 'Convert HTML to Markdown', 'inputSchema' => {} }
+      ]
+
+      allow(transport).to receive(:send_request)
+        .with(hash_including(method: 'tools/list'))
+        .and_return(jsonrpc_response(2, { 'tools' => tools }))
+
+      expect(client.list_tools).to eq(tools)
+    end
+
+    it 'caches the result' do
+      allow(transport).to receive(:send_request)
+        .with(hash_including(method: 'tools/list'))
+        .once
+        .and_return(jsonrpc_response(2, { 'tools' => [{ 'name' => 'foo' }] }))
+
+      client.list_tools
+      client.list_tools
+    end
+
+    it 'returns empty array when no tools' do
+      allow(transport).to receive(:send_request)
+        .with(hash_including(method: 'tools/list'))
+        .and_return(jsonrpc_response(2, {}))
+
+      expect(client.list_tools).to eq([])
+    end
+
+    it 'raises NotConnectedError when not connected' do
+      new_client = Html2mdMcpClient::Client.new(transport)
+      expect { new_client.list_tools }.to raise_error(Html2mdMcpClient::NotConnectedError)
+    end
+  end
+
+  describe '#call_tool' do
+    before { stub_connect! }
+
+    it 'returns content array' do
+      content = [{ 'type' => 'text', 'text' => '# Hello' }]
+
+      allow(transport).to receive(:send_request)
+        .with(hash_including(method: 'tools/call', params: { name: 'my_tool', arguments: { url: 'http://x.com' } }))
+        .and_return(jsonrpc_response(2, { 'content' => content }))
+
+      expect(client.call_tool('my_tool', { url: 'http://x.com' })).to eq(content)
+    end
+
+    it 'raises ToolError when server signals error' do
+      allow(transport).to receive(:send_request)
+        .with(hash_including(method: 'tools/call'))
+        .and_return(jsonrpc_response(2, {
+          'isError' => true,
+          'content' => [{ 'type' => 'text', 'text' => 'Something went wrong' }]
+        }))
+
+      expect { client.call_tool('bad_tool') }.to raise_error(Html2mdMcpClient::ToolError, /Something went wrong/)
+    end
+
+    it 'returns empty array when no content' do
+      allow(transport).to receive(:send_request)
+        .with(hash_including(method: 'tools/call'))
+        .and_return(jsonrpc_response(2, {}))
+
+      expect(client.call_tool('empty_tool')).to eq([])
+    end
+  end
+
+  describe '#tool_text' do
+    before { stub_connect! }
+
+    it 'returns joined text content' do
+      content = [
+        { 'type' => 'text', 'text' => 'Line 1' },
+        { 'type' => 'image', 'data' => 'base64...' },
+        { 'type' => 'text', 'text' => 'Line 2' }
+      ]
+
+      allow(transport).to receive(:send_request)
+        .with(hash_including(method: 'tools/call'))
+        .and_return(jsonrpc_response(2, { 'content' => content }))
+
+      expect(client.tool_text('my_tool')).to eq("Line 1\nLine 2")
+    end
+  end
+
+  describe '#find_tool' do
+    before { stub_connect! }
+
+    it 'returns matching tool definition' do
+      tools = [
+        { 'name' => 'foo', 'description' => 'Foo tool' },
+        { 'name' => 'bar', 'description' => 'Bar tool' }
+      ]
+
+      allow(transport).to receive(:send_request)
+        .with(hash_including(method: 'tools/list'))
+        .and_return(jsonrpc_response(2, { 'tools' => tools }))
+
+      expect(client.find_tool('bar')).to eq({ 'name' => 'bar', 'description' => 'Bar tool' })
+    end
+
+    it 'returns nil when not found' do
+      allow(transport).to receive(:send_request)
+        .with(hash_including(method: 'tools/list'))
+        .and_return(jsonrpc_response(2, { 'tools' => [] }))
+
+      expect(client.find_tool('missing')).to be_nil
+    end
+  end
+
+  describe '#list_resources' do
+    before { stub_connect! }
+
+    it 'returns resource definitions' do
+      resources = [{ 'uri' => 'file:///tmp/data.json', 'name' => 'data.json' }]
+
+      allow(transport).to receive(:send_request)
+        .with(hash_including(method: 'resources/list'))
+        .and_return(jsonrpc_response(2, { 'resources' => resources }))
+
+      expect(client.list_resources).to eq(resources)
+    end
+  end
+
+  describe '#read_resource' do
+    before { stub_connect! }
+
+    it 'returns resource contents' do
+      contents = [{ 'uri' => 'file:///tmp/data.json', 'text' => '{"key":"value"}' }]
+
+      allow(transport).to receive(:send_request)
+        .with(hash_including(method: 'resources/read', params: { uri: 'file:///tmp/data.json' }))
+        .and_return(jsonrpc_response(2, { 'contents' => contents }))
+
+      expect(client.read_resource('file:///tmp/data.json')).to eq(contents)
+    end
+  end
+
+  describe '#list_prompts' do
+    before { stub_connect! }
+
+    it 'returns prompt definitions' do
+      prompts = [{ 'name' => 'summarize', 'description' => 'Summarize text' }]
+
+      allow(transport).to receive(:send_request)
+        .with(hash_including(method: 'prompts/list'))
+        .and_return(jsonrpc_response(2, { 'prompts' => prompts }))
+
+      expect(client.list_prompts).to eq(prompts)
+    end
+  end
+
+  describe '#get_prompt' do
+    before { stub_connect! }
+
+    it 'returns prompt result' do
+      result = { 'messages' => [{ 'role' => 'user', 'content' => 'Summarize: hello' }] }
+
+      allow(transport).to receive(:send_request)
+        .with(hash_including(method: 'prompts/get', params: { name: 'summarize', arguments: { text: 'hello' } }))
+        .and_return(jsonrpc_response(2, result))
+
+      expect(client.get_prompt('summarize', { text: 'hello' })).to eq(result)
+    end
+  end
+
+  describe 'error handling' do
+    before { stub_connect! }
+
+    it 'raises ProtocolError on JSON-RPC error response' do
+      allow(transport).to receive(:send_request)
+        .with(hash_including(method: 'tools/list'))
+        .and_return(jsonrpc_error(2, -32601, 'Method not found'))
+
+      expect { client.list_tools }.to raise_error(Html2mdMcpClient::ProtocolError, /Method not found/)
+    end
+
+    it 'raises ProtocolError on ID mismatch' do
+      allow(transport).to receive(:send_request)
+        .with(hash_including(method: 'tools/list'))
+        .and_return(jsonrpc_response(999, { 'tools' => [] }))
+
+      expect { client.list_tools }.to raise_error(Html2mdMcpClient::ProtocolError, /ID mismatch/)
+    end
+  end
+end

data/spec/html2md_mcp_client/transport/http_spec.rb

@@ -0,0 +1,138 @@
+require 'spec_helper'
+
+RSpec.describe Html2mdMcpClient::Transport::Http do
+  let(:url) { 'http://localhost:3001/mcp' }
+  let(:transport) { described_class.new(url) }
+
+  describe '#send_request' do
+    it 'sends a POST with JSON body and returns parsed response' do
+      payload = { jsonrpc: '2.0', id: 1, method: 'initialize', params: {} }
+      response_body = { 'jsonrpc' => '2.0', 'id' => 1, 'result' => { 'ok' => true } }
+
+      stub_request(:post, url)
+        .with(
+          body: payload.to_json,
+          headers: { 'Content-Type' => 'application/json', 'Accept' => 'application/json, text/event-stream' }
+        )
+        .to_return(status: 200, body: response_body.to_json, headers: { 'Content-Type' => 'application/json' })
+
+      expect(transport.send_request(payload)).to eq(response_body)
+    end
+
+    it 'captures session ID from response headers' do
+      stub_request(:post, url)
+        .to_return(
+          status: 200,
+          body: { 'jsonrpc' => '2.0', 'id' => 1, 'result' => {} }.to_json,
+          headers: { 'Mcp-Session-Id' => 'abc-123' }
+        )
+
+      transport.send_request({ jsonrpc: '2.0', id: 1, method: 'test', params: {} })
+      expect(transport.session_id).to eq('abc-123')
+    end
+
+    it 'sends session ID on subsequent requests' do
+      # First request sets session
+      stub_request(:post, url)
+        .to_return(
+          status: 200,
+          body: { 'jsonrpc' => '2.0', 'id' => 1, 'result' => {} }.to_json,
+          headers: { 'Mcp-Session-Id' => 'abc-123' }
+        )
+
+      transport.send_request({ jsonrpc: '2.0', id: 1, method: 'test', params: {} })
+
+      # Second request should include session header
+      stub_request(:post, url)
+        .with(headers: { 'Mcp-Session-Id' => 'abc-123' })
+        .to_return(
+          status: 200,
+          body: { 'jsonrpc' => '2.0', 'id' => 2, 'result' => {} }.to_json
+        )
+
+      transport.send_request({ jsonrpc: '2.0', id: 2, method: 'test2', params: {} })
+    end
+
+    it 'parses SSE responses' do
+      sse_body = "event: message\ndata: {\"jsonrpc\":\"2.0\",\"id\":1,\"result\":{\"tools\":[]}}\n\n"
+
+      stub_request(:post, url)
+        .to_return(
+          status: 200,
+          body: sse_body,
+          headers: { 'Content-Type' => 'text/event-stream' }
+        )
+
+      result = transport.send_request({ jsonrpc: '2.0', id: 1, method: 'tools/list', params: {} })
+      expect(result).to eq({ 'jsonrpc' => '2.0', 'id' => 1, 'result' => { 'tools' => [] } })
+    end
+
+    it 'raises ConnectionError on HTTP error status' do
+      stub_request(:post, url).to_return(status: 500, body: 'Internal Server Error')
+
+      expect { transport.send_request({ jsonrpc: '2.0', id: 1, method: 'test', params: {} }) }
+        .to raise_error(Html2mdMcpClient::ConnectionError, /HTTP 500/)
+    end
+
+    it 'raises ConnectionError on connection refused' do
+      stub_request(:post, url).to_raise(Errno::ECONNREFUSED)
+
+      expect { transport.send_request({ jsonrpc: '2.0', id: 1, method: 'test', params: {} }) }
+        .to raise_error(Html2mdMcpClient::ConnectionError, /Cannot connect/)
+    end
+
+    it 'raises ProtocolError on invalid JSON' do
+      stub_request(:post, url).to_return(status: 200, body: 'not json')
+
+      expect { transport.send_request({ jsonrpc: '2.0', id: 1, method: 'test', params: {} }) }
+        .to raise_error(Html2mdMcpClient::ProtocolError, /Invalid JSON/)
+    end
+  end
+
+  describe '#send_notification' do
+    it 'sends a POST and does not raise on failure' do
+      stub_request(:post, url).to_return(status: 500)
+      expect { transport.send_notification({ jsonrpc: '2.0', method: 'notify' }) }.not_to raise_error
+    end
+  end
+
+  describe '#close' do
+    it 'clears the session ID' do
+      stub_request(:post, url)
+        .to_return(
+          status: 200,
+          body: { 'jsonrpc' => '2.0', 'id' => 1, 'result' => {} }.to_json,
+          headers: { 'Mcp-Session-Id' => 'abc-123' }
+        )
+
+      transport.send_request({ jsonrpc: '2.0', id: 1, method: 'test', params: {} })
+      expect(transport.session_id).to eq('abc-123')
+
+      transport.close
+      expect(transport.session_id).to be_nil
+    end
+  end
+
+  describe 'custom headers' do
+    it 'includes custom headers in requests' do
+      t = described_class.new(url, headers: { 'Authorization' => 'Bearer tok123' })
+
+      stub_request(:post, url)
+        .with(headers: { 'Authorization' => 'Bearer tok123' })
+        .to_return(status: 200, body: { 'jsonrpc' => '2.0', 'id' => 1, 'result' => {} }.to_json)
+
+      t.send_request({ jsonrpc: '2.0', id: 1, method: 'test', params: {} })
+    end
+  end
+
+  describe 'HTTPS' do
+    it 'enables SSL for https URLs' do
+      t = described_class.new('https://secure.example.com/mcp')
+
+      stub_request(:post, 'https://secure.example.com/mcp')
+        .to_return(status: 200, body: { 'jsonrpc' => '2.0', 'id' => 1, 'result' => {} }.to_json)
+
+      t.send_request({ jsonrpc: '2.0', id: 1, method: 'test', params: {} })
+    end
+  end
+end

data/spec/html2md_mcp_client/transport/stdio_spec.rb

@@ -0,0 +1,121 @@
+require 'spec_helper'
+
+RSpec.describe Html2mdMcpClient::Transport::Stdio do
+  let(:transport) { described_class.new('echo', args: ['test']) }
+
+  describe '#start' do
+    it 'spawns the subprocess' do
+      stdin = instance_double(IO)
+      stdout = instance_double(IO)
+      stderr = instance_double(IO)
+      thread = instance_double(Thread)
+
+      expect(Open3).to receive(:popen3).with('echo', 'test').and_return([stdin, stdout, stderr, thread])
+      transport.start
+    end
+
+    it 'raises ConnectionError when command not found' do
+      bad = described_class.new('nonexistent_command_xyz')
+      expect { bad.start }.to raise_error(Html2mdMcpClient::ConnectionError, /Cannot start/)
+    end
+  end
+
+  describe '#send_request' do
+    it 'writes JSON and reads the response' do
+      stdin = StringIO.new
+      stdout = StringIO.new("{\"jsonrpc\":\"2.0\",\"id\":1,\"result\":{\"ok\":true}}\n")
+      stderr = StringIO.new
+      thread = instance_double(Thread)
+
+      allow(Open3).to receive(:popen3).and_return([stdin, stdout, stderr, thread])
+      transport.start
+
+      result = transport.send_request({ jsonrpc: '2.0', id: 1, method: 'test', params: {} })
+      expect(result).to eq({ 'jsonrpc' => '2.0', 'id' => 1, 'result' => { 'ok' => true } })
+    end
+
+    it 'skips notifications (lines without id)' do
+      lines = [
+        "{\"jsonrpc\":\"2.0\",\"method\":\"notification\"}\n",
+        "{\"jsonrpc\":\"2.0\",\"id\":1,\"result\":{\"found\":true}}\n"
+      ].join
+      stdin = StringIO.new
+      stdout = StringIO.new(lines)
+      stderr = StringIO.new
+      thread = instance_double(Thread)
+
+      allow(Open3).to receive(:popen3).and_return([stdin, stdout, stderr, thread])
+      transport.start
+
+      result = transport.send_request({ jsonrpc: '2.0', id: 1, method: 'test', params: {} })
+      expect(result['result']).to eq({ 'found' => true })
+    end
+
+    it 'skips empty lines and invalid JSON' do
+      lines = [
+        "\n",
+        "not json\n",
+        "{\"jsonrpc\":\"2.0\",\"id\":1,\"result\":{}}\n"
+      ].join
+      stdin = StringIO.new
+      stdout = StringIO.new(lines)
+      stderr = StringIO.new
+      thread = instance_double(Thread)
+
+      allow(Open3).to receive(:popen3).and_return([stdin, stdout, stderr, thread])
+      transport.start
+
+      result = transport.send_request({ jsonrpc: '2.0', id: 1, method: 'test', params: {} })
+      expect(result).to eq({ 'jsonrpc' => '2.0', 'id' => 1, 'result' => {} })
+    end
+
+    it 'raises ConnectionError when process terminates (nil from gets)' do
+      stdin = StringIO.new
+      stdout = StringIO.new # empty — gets returns nil
+      stderr = StringIO.new
+      thread = instance_double(Thread)
+
+      allow(Open3).to receive(:popen3).and_return([stdin, stdout, stderr, thread])
+      transport.start
+
+      expect { transport.send_request({ jsonrpc: '2.0', id: 1, method: 'test', params: {} }) }
+        .to raise_error(Html2mdMcpClient::ConnectionError, /terminated/)
+    end
+  end
+
+  describe '#send_notification' do
+    it 'writes without raising on pipe error' do
+      stdin = instance_double(IO)
+      allow(stdin).to receive(:puts).and_raise(Errno::EPIPE)
+      allow(stdin).to receive(:flush)
+
+      stdout = StringIO.new
+      stderr = StringIO.new
+      thread = instance_double(Thread)
+
+      allow(Open3).to receive(:popen3).and_return([stdin, stdout, stderr, thread])
+      transport.start
+
+      expect { transport.send_notification({ jsonrpc: '2.0', method: 'notify' }) }.not_to raise_error
+    end
+  end
+
+  describe '#close' do
+    it 'closes all IO streams and kills the thread' do
+      stdin = instance_double(IO, close: nil)
+      stdout = instance_double(IO, close: nil)
+      stderr = instance_double(IO, close: nil)
+      thread = instance_double(Thread, kill: nil)
+
+      allow(Open3).to receive(:popen3).and_return([stdin, stdout, stderr, thread])
+      transport.start
+
+      expect(stdin).to receive(:close)
+      expect(stdout).to receive(:close)
+      expect(stderr).to receive(:close)
+      expect(thread).to receive(:kill)
+
+      transport.close
+    end
+  end
+end

data/spec/html2md_mcp_client_spec.rb

@@ -0,0 +1,35 @@
+require 'spec_helper'
+
+RSpec.describe Html2mdMcpClient do
+  describe '.http' do
+    it 'returns a Client with Http transport' do
+      client = Html2mdMcpClient.http('http://localhost:3001/mcp')
+      expect(client).to be_a(Html2mdMcpClient::Client)
+      expect(client.transport).to be_a(Html2mdMcpClient::Transport::Http)
+    end
+
+    it 'passes custom headers to transport' do
+      client = Html2mdMcpClient.http('http://localhost:3001/mcp', headers: { 'Authorization' => 'Bearer x' })
+      expect(client.transport).to be_a(Html2mdMcpClient::Transport::Http)
+    end
+
+    it 'passes client_name option' do
+      client = Html2mdMcpClient.http('http://localhost:3001/mcp', client_name: 'searchbird')
+      expect(client).to be_a(Html2mdMcpClient::Client)
+    end
+  end
+
+  describe '.stdio' do
+    it 'returns a Client with Stdio transport' do
+      client = Html2mdMcpClient.stdio('echo', args: ['test'])
+      expect(client).to be_a(Html2mdMcpClient::Client)
+      expect(client.transport).to be_a(Html2mdMcpClient::Transport::Stdio)
+    end
+  end
+
+  describe 'VERSION' do
+    it 'is defined' do
+      expect(Html2mdMcpClient::VERSION).to match(/\A\d+\.\d+\.\d+\z/)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,41 @@
+require 'html2md_mcp_client'
+require 'webmock/rspec'
+
+WebMock.disable_net_connect!
+
+# Shared helpers for building JSON-RPC responses
+module JsonRpcHelpers
+  def jsonrpc_response(id, result)
+    { 'jsonrpc' => '2.0', 'id' => id, 'result' => result }
+  end
+
+  def jsonrpc_error(id, code, message)
+    { 'jsonrpc' => '2.0', 'id' => id, 'error' => { 'code' => code, 'message' => message } }
+  end
+
+  def initialize_result
+    {
+      'serverInfo' => { 'name' => 'test-server', 'version' => '1.0.0' },
+      'capabilities' => { 'tools' => {} }
+    }
+  end
+
+  # Stubs the initialize handshake for HTTP transport tests
+  def stub_mcp_init(url)
+    stub_request(:post, url)
+      .with { |req| JSON.parse(req.body)['method'] == 'initialize' }
+      .to_return(
+        status: 200,
+        headers: { 'Content-Type' => 'application/json', 'Mcp-Session-Id' => 'test-session-123' },
+        body: jsonrpc_response(1, initialize_result).to_json
+      )
+
+    stub_request(:post, url)
+      .with { |req| JSON.parse(req.body)['method'] == 'notifications/initialized' }
+      .to_return(status: 200, body: '')
+  end
+end
+
+RSpec.configure do |config|
+  config.include JsonRpcHelpers
+end

metadata

@@ -0,0 +1,90 @@
+--- !ruby/object:Gem::Specification
+name: html2md_mcp_client
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Searchbird
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-14 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Connects to MCP servers over HTTP or stdio. Supports tools, resources,
+  and prompts.
+email:
+- dev@searchbird.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- html2md_mcp_client.gemspec
+- lib/html2md_mcp_client.rb
+- lib/html2md_mcp_client/client.rb
+- lib/html2md_mcp_client/errors.rb
+- lib/html2md_mcp_client/transport/http.rb
+- lib/html2md_mcp_client/transport/stdio.rb
+- lib/html2md_mcp_client/version.rb
+- spec/html2md_mcp_client/client_spec.rb
+- spec/html2md_mcp_client/transport/http_spec.rb
+- spec/html2md_mcp_client/transport/stdio_spec.rb
+- spec/html2md_mcp_client_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/roscom/html2md_mcp_client
+licenses:
+- MIT
+metadata: {}
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.5'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3.1
+signing_key:
+specification_version: 4
+summary: Ruby client for the Model Context Protocol (MCP)
+test_files:
+- spec/html2md_mcp_client/transport/http_spec.rb
+- spec/html2md_mcp_client/transport/stdio_spec.rb
+- spec/html2md_mcp_client/client_spec.rb
+- spec/spec_helper.rb
+- spec/html2md_mcp_client_spec.rb