make transports implement template methods instead

Author: jcat4

README.md

@@ -588,26 +588,30 @@ otherwise `resources/read` requests will be a no-op.
 ## Building an MCP Client
 
 The `MCP::Client` class provides an interface for interacting with MCP servers.
-Clients are initialized with a transport layer instance that instructs them how to interact with the server.
+Clients are initialized with a transport layer instance that handles the low-level communication mechanics.
+
+## Transport Layer Interface
 
 If the transport layer you need is not included in the gem, you can build and pass your own instances so long as they conform to the following interface:
 
 ```ruby
 class CustomTransport
-  def tools
-    # Must return Array<MCP::Client::Tool>
-  end
-
-  def call_tool(tool:, input:)
-    # tool: MCP::Client::Tool
-    # input: Hash - the arguments to pass to the tool
-    # Returns: Hash - the content from the response (typically response.dig("result", "content"))
+  # Sends a JSON-RPC request to the server and returns the raw response
+  #
+  # @param request [Hash] A complete JSON-RPC request object.
+  # https://www.jsonrpc.org/specification#request_object
+  # @return [Hash] A hash modeling a JSON-RPC response object:
+  # https://www.jsonrpc.org/specification#response_object
+  def send_request(request:)
+    # Your transport-specific logic here
+    # - HTTP: POST to endpoint with JSON body
+    # - WebSocket: Send message over WebSocket
+    # - stdio: Write to stdout, read from stdin
+    # - etc.
   end
 end
 ```
 
-**Note:** We strongly recommend returning `MCP::Client::Tool` instances rather than custom tool objects with the same interface, as this ensures compatibility with future SDK features and provides a consistent interface.
-
 ### HTTP Transport Layer
 
 Use the `MCP::Client::Http` transport to interact with MCP servers using simple HTTP requests.
@@ -685,3 +689,4 @@ Releases are triggered by PRs to the `main` branch updating the version number i
 1. **Merge your PR to the main branch** - This will automatically trigger the release workflow via GitHub Actions
 
 When changes are merged to the `main` branch, the GitHub Actions workflow (`.github/workflows/release.yml`) is triggered and the gem is published to RubyGems.
+

lib/mcp/client.rb

@@ -2,6 +2,8 @@
 
 module MCP
   class Client
+    JSON_RPC_VERSION = "2.0"
+
     # Initializes a new MCP::Client instance.
     #
     # @param transport [Object] The transport object to use for communication with the server.
@@ -35,7 +37,25 @@ def initialize(transport:)
     #     puts tool.name
     #   end
     def tools
-      transport.tools
+      request = {
+        jsonrpc: JSON_RPC_VERSION,
+        id: request_id,
+        method: "tools/list",
+        mcp: {
+          jsonrpc: JSON_RPC_VERSION,
+          id: request_id,
+          method: "tools/list",
+        }.compact,
+      }
+
+      response = transport.send_request(request: request)
+      response.dig("result", "tools")&.map do |tool|
+        Tool.new(
+          name: tool["name"],
+          description: tool["description"],
+          input_schema: tool["inputSchema"],
+        )
+      end || []
     end
 
     # Calls a tool via the transport layer.
@@ -52,7 +72,27 @@ def tools
     #   The exact requirements for `input` are determined by the transport layer in use.
     #   Consult the documentation for your transport (e.g., MCP::Client::HTTP) for details.
     def call_tool(tool:, input: nil)
-      transport.call_tool(tool: tool, input: input)
+      request = {
+        jsonrpc: JSON_RPC_VERSION,
+        id: request_id,
+        method: "tools/call",
+        params: { name: tool.name, arguments: input },
+        mcp: {
+          jsonrpc: JSON_RPC_VERSION,
+          id: request_id,
+          method: "tools/call",
+          params: { name: tool.name, arguments: input },
+        }.compact,
+      }
+
+      response = transport.send_request(request: request)
+      response.dig("result", "content")
+    end
+
+    private
+
+    def request_id
+      SecureRandom.uuid_v7
     end
 
     class RequestHandlerError < StandardError

lib/mcp/client/http.rb

@@ -10,62 +10,11 @@ def initialize(url:, headers: {})
         @headers = headers
       end
 
-      def tools
-        response = send_request(method: "tools/list").body
+      def send_request(request:)
+        method = request[:method] || request["method"]
+        params = request[:params] || request["params"]
 
-        response.dig("result", "tools")&.map do |tool|
-          Tool.new(
-            name: tool["name"],
-            description: tool["description"],
-            input_schema: tool["inputSchema"],
-          )
-        end || []
-      end
-
-      def call_tool(tool:, input:)
-        response = send_request(
-          method: "tools/call",
-          params: { name: tool.name, arguments: input },
-        ).body
-
-        response.dig("result", "content")
-      end
-
-      private
-
-      attr_reader :headers
-
-      def client
-        require_faraday!
-        @client ||= Faraday.new(url) do |faraday|
-          faraday.request(:json)
-          faraday.response(:json)
-          faraday.response(:raise_error)
-
-          headers.each do |key, value|
-            faraday.headers[key] = value
-          end
-        end
-      end
-
-      def require_faraday!
-        require "faraday"
-      rescue LoadError
-        raise LoadError, "The 'faraday' gem is required to use the MCP client HTTP transport. " \
-          "Add it to your Gemfile: gem 'faraday', '>= 2.0'"
-      end
-
-      def send_request(method:, params: nil)
-        client.post(
-          "",
-          {
-            jsonrpc: "2.0",
-            id: request_id,
-            method:,
-            params:,
-            mcp: { jsonrpc: "2.0", id: request_id, method:, params: }.compact,
-          }.compact,
-        )
+        client.post("", request).body
       rescue Faraday::BadRequestError => e
         raise RequestHandlerError.new(
           "The #{method} request is invalid",
@@ -110,8 +59,28 @@ def send_request(method:, params: nil)
         )
       end
 
-      def request_id
-        SecureRandom.uuid_v7
+      private
+
+      attr_reader :headers
+
+      def client
+        require_faraday!
+        @client ||= Faraday.new(url) do |faraday|
+          faraday.request(:json)
+          faraday.response(:json)
+          faraday.response(:raise_error)
+
+          headers.each do |key, value|
+            faraday.headers[key] = value
+          end
+        end
+      end
+
+      def require_faraday!
+        require "faraday"
+      rescue LoadError
+        raise LoadError, "The 'faraday' gem is required to use the MCP client HTTP transport. " \
+          "Add it to your Gemfile: gem 'faraday', '>= 2.0'"
       end
     end
   end