claude-agent-sdk 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d1b1a2ec74f15062544d42a0df92058e256bab2ed29754e19133bfc1340cddcf
-  data.tar.gz: f01aea04b3f32e51b5d98e6994d52c8e2864259fa86d1c5bdc64104486b63687
+  metadata.gz: fe94c46bcf37e8f5fd38dcc5ccaa17e3490d70f79b083ffd4f753711e8df38ab
+  data.tar.gz: ff8fd7d82daa4acac453b15c727b96c03edf8fa2f1d52c772b75b24cd0df2792
 SHA512:
-  metadata.gz: ef15b15c77ceb22fc0b40884ecc1e79a884b9b7d043b21420ef0faa34d638206eec6284ab6afeb015097d721c75c0e00ce0f3db4c63e7f8e90305bda2e468b16
-  data.tar.gz: 74ee1d9b848c2e84336fb3a12e8147b35243f64ad6c1d352fe451a39c16a92cdaa92303acb20cf053495c580171bfe36d60f5a53bee98d2781da0b1b261870d3
+  metadata.gz: 597dd01120488fdd74c18c2ac0623bcb7d9f0f9af784cc868a291e3075a25a999023258acf338210e7e0f2d0d2ed3de5512cce8e5c72fb0b29142c665d8ab2ac
+  data.tar.gz: a3f2c72a4beac29ba34471bbf7195e71f92720afc220d2c52250421f49da4bedc3ce8be113e8a1c75fb9a370418528d7912f71343fe7acebe81be26abbc9d32f

data/CHANGELOG.md

@@ -5,6 +5,28 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2025-10-17
+
+### Changed
+- **BREAKING:** Updated minimum Ruby version from 3.0+ to 3.2+ (required by official MCP SDK)
+- **Major refactoring:** SDK MCP server now uses official Ruby MCP SDK (`mcp` gem v0.4) internally
+- Internal implementation migrated from custom MCP to wrapping official `MCP::Server`
+
+### Added
+- Official Ruby MCP SDK (`mcp` gem) as runtime dependency
+- Full MCP protocol compliance via official SDK
+- `handle_json` method for protocol-compliant JSON-RPC handling
+
+### Improved
+- Better long-term maintenance by leveraging official SDK updates
+- Aligned with Python SDK implementation pattern (using official MCP library)
+- All 86 tests passing with full backward compatibility maintained
+
+### Technical Details
+- Creates dynamic `MCP::Tool`, `MCP::Resource`, and `MCP::Prompt` classes from block-based definitions
+- User-facing API remains unchanged - no breaking changes for Ruby 3.2+ users
+- Maintains backward-compatible methods (`list_tools`, `call_tool`, etc.)
+
 ## [0.1.3] - 2025-10-15
 
 ### Added

data/README.md

@@ -29,7 +29,7 @@ gem install claude-agent-sdk
 ```
 
 **Prerequisites:**
-- Ruby 3.0+
+- Ruby 3.2+
 - Node.js
 - Claude Code 2.0.0+: `npm install -g @anthropic-ai/claude-code`
 
@@ -131,7 +131,11 @@ For a complete example, see [examples/streaming_input_example.rb](examples/strea
 
 ## Client
 
-`ClaudeAgentSDK::Client` supports bidirectional, interactive conversations with Claude Code. Unlike `query()`, `Client` enables **custom tools**, **hooks**, and **permission callbacks**, all of which can be defined as Ruby procs/lambdas. See [lib/claude_agent_sdk.rb](lib/claude_agent_sdk.rb).
+`ClaudeAgentSDK::Client` supports bidirectional, interactive conversations with Claude Code. Unlike `query()`, `Client` enables **custom tools**, **hooks**, and **permission callbacks**, all of which can be defined as Ruby procs/lambdas.
+
+**The Client class automatically uses streaming mode** for bidirectional communication, allowing you to send multiple queries dynamically during a single session without closing the connection. This matches the Python SDK's `ClaudeSDKClient` behavior.
+
+See [lib/claude_agent_sdk.rb](lib/claude_agent_sdk.rb) for implementation details.
 
 ### Custom Tools (SDK MCP Servers)
 
@@ -139,6 +143,8 @@ A **custom tool** is a Ruby proc/lambda that you can offer to Claude, for Claude
 
 Custom tools are implemented as in-process MCP servers that run directly within your Ruby application, eliminating the need for separate processes that regular MCP servers require.
 
+**Implementation**: This SDK uses the [official Ruby MCP SDK](https://github.com/modelcontextprotocol/ruby-sdk) (`mcp` gem) internally, providing full protocol compliance while offering a simpler block-based API for tool definition.
+
 For a complete example, see [examples/mcp_calculator.rb](examples/mcp_calculator.rb).
 
 #### Creating a Simple Tool
@@ -292,6 +298,7 @@ Async do
   client = ClaudeAgentSDK::Client.new
 
   begin
+    # Connect automatically uses streaming mode for bidirectional communication
     client.connect
 
     # Send a query

data/lib/claude_agent_sdk/sdk_mcp_server.rb

@@ -1,18 +1,18 @@
 # frozen_string_literal: true
 
+require 'mcp'
+
 module ClaudeAgentSDK
-  # SDK MCP Server - runs in-process within your Ruby application
+  # SDK MCP Server - wraps official MCP::Server with block-based API
   #
   # Unlike external MCP servers that run as separate processes, SDK MCP servers
   # run directly in your application's process, providing better performance
   # and simpler deployment.
   #
-  # Supports:
-  # - Tools: Executable functions that Claude can call
-  # - Resources: Data sources that can be read (files, databases, APIs, etc.)
-  # - Prompts: Reusable prompt templates with arguments
+  # This class wraps the official MCP Ruby SDK and provides a simpler block-based
+  # API for defining tools, resources, and prompts.
   class SdkMcpServer
-    attr_reader :name, :version, :tools, :resources, :prompts
+    attr_reader :name, :version, :tools, :resources, :prompts, :mcp_server
 
     def initialize(name:, version: '1.0.0', tools: [], resources: [], prompts: [])
       @name = name
@@ -20,12 +20,34 @@ module ClaudeAgentSDK
       @tools = tools
       @resources = resources
       @prompts = prompts
-      @tool_map = tools.each_with_object({}) { |tool, hash| hash[tool.name] = tool }
-      @resource_map = resources.each_with_object({}) { |res, hash| hash[res.uri] = res }
-      @prompt_map = prompts.each_with_object({}) { |prompt, hash| hash[prompt.name] = prompt }
+
+      # Create dynamic Tool classes from tool definitions
+      tool_classes = create_tool_classes(tools)
+
+      # Create dynamic Resource classes from resource definitions
+      resource_classes = create_resource_classes(resources)
+
+      # Create dynamic Prompt classes from prompt definitions
+      prompt_classes = create_prompt_classes(prompts)
+
+      # Create the official MCP::Server instance
+      @mcp_server = MCP::Server.new(
+        name: name,
+        version: version,
+        tools: tool_classes,
+        resources: resource_classes,
+        prompts: prompt_classes
+      )
+    end
+
+    # Handle a JSON-RPC request
+    # @param json_string [String] JSON-RPC request
+    # @return [String] JSON-RPC response
+    def handle_json(json_string)
+      @mcp_server.handle_json(json_string)
     end
 
-    # List all available tools
+    # List all available tools (for backward compatibility)
     # @return [Array<Hash>] Array of tool definitions
     def list_tools
       @tools.map do |tool|
@@ -37,12 +59,12 @@ module ClaudeAgentSDK
       end
     end
 
-    # Execute a tool by name
+    # Execute a tool by name (for backward compatibility)
     # @param name [String] Tool name
     # @param arguments [Hash] Tool arguments
     # @return [Hash] Tool result
     def call_tool(name, arguments)
-      tool = @tool_map[name]
+      tool = @tools.find { |t| t.name == name }
       raise "Tool '#{name}' not found" unless tool
 
       # Call the tool's handler
@@ -56,7 +78,7 @@ module ClaudeAgentSDK
       result
     end
 
-    # List all available resources
+    # List all available resources (for backward compatibility)
     # @return [Array<Hash>] Array of resource definitions
     def list_resources
       @resources.map do |resource|
@@ -69,11 +91,11 @@ module ClaudeAgentSDK
       end
     end
 
-    # Read a resource by URI
+    # Read a resource by URI (for backward compatibility)
     # @param uri [String] Resource URI
     # @return [Hash] Resource content
     def read_resource(uri)
-      resource = @resource_map[uri]
+      resource = @resources.find { |r| r.uri == uri }
       raise "Resource '#{uri}' not found" unless resource
 
       # Call the resource's reader
@@ -87,7 +109,7 @@ module ClaudeAgentSDK
       content
     end
 
-    # List all available prompts
+    # List all available prompts (for backward compatibility)
     # @return [Array<Hash>] Array of prompt definitions
     def list_prompts
       @prompts.map do |prompt|
@@ -99,12 +121,12 @@ module ClaudeAgentSDK
       end
     end
 
-    # Get a prompt by name
+    # Get a prompt by name (for backward compatibility)
     # @param name [String] Prompt name
     # @param arguments [Hash] Arguments to fill in the prompt template
     # @return [Hash] Prompt with filled-in arguments
     def get_prompt(name, arguments = {})
-      prompt = @prompt_map[name]
+      prompt = @prompts.find { |p| p.name == name }
       raise "Prompt '#{name}' not found" unless prompt
 
       # Call the prompt's generator
@@ -120,6 +142,172 @@ module ClaudeAgentSDK
 
     private
 
+    # Create dynamic Tool classes from tool definitions
+    def create_tool_classes(tools)
+      tools.map do |tool_def|
+        # Create a new class that extends MCP::Tool
+        Class.new(MCP::Tool) do
+          @tool_def = tool_def
+
+          class << self
+            attr_reader :tool_def
+
+            def description
+              @tool_def.description
+            end
+
+            def input_schema
+              convert_schema(@tool_def.input_schema)
+            end
+
+            def call(server_context: nil, **args)
+              # Filter out server_context and pass remaining args to handler
+              result = @tool_def.handler.call(args)
+
+              # Convert result to MCP::Tool::Response format
+              content = result[:content].map do |item|
+                {
+                  type: item[:type],
+                  text: item[:text]
+                }
+              end
+
+              MCP::Tool::Response.new(content)
+            end
+
+            private
+
+            def convert_schema(schema)
+              # If it's already a proper JSON schema, return it
+              if schema.is_a?(Hash) && schema[:type] && schema[:properties]
+                return schema
+              end
+
+              # Simple schema: hash mapping parameter names to types
+              if schema.is_a?(Hash)
+                properties = {}
+                schema.each do |param_name, param_type|
+                  properties[param_name] = type_to_json_schema(param_type)
+                end
+
+                return {
+                  type: 'object',
+                  properties: properties,
+                  required: properties.keys.map(&:to_s)
+                }
+              end
+
+              # Default fallback
+              { type: 'object', properties: {} }
+            end
+
+            def type_to_json_schema(type)
+              case type
+              when :string, String
+                { type: 'string' }
+              when :integer, Integer
+                { type: 'integer' }
+              when :float, Float
+                { type: 'number' }
+              when :boolean, TrueClass, FalseClass
+                { type: 'boolean' }
+              when :number
+                { type: 'number' }
+              else
+                { type: 'string' } # Default fallback
+              end
+            end
+          end
+
+          # Set the tool name
+          define_singleton_method(:name) { @tool_def.name }
+        end
+      end
+    end
+
+    # Create dynamic Resource classes from resource definitions
+    def create_resource_classes(resources)
+      resources.map do |resource_def|
+        # Create a new class that extends MCP::Resource
+        Class.new(MCP::Resource) do
+          @resource_def = resource_def
+
+          class << self
+            attr_reader :resource_def
+
+            def uri
+              @resource_def.uri
+            end
+
+            def name
+              @resource_def.name
+            end
+
+            def description
+              @resource_def.description
+            end
+
+            def mime_type
+              @resource_def.mime_type
+            end
+
+            def read
+              result = @resource_def.reader.call
+
+              # Convert to MCP format
+              result[:contents].map do |content|
+                MCP::ResourceContents.new(
+                  uri: content[:uri],
+                  mime_type: content[:mimeType] || content[:mime_type],
+                  text: content[:text]
+                )
+              end
+            end
+          end
+        end
+      end
+    end
+
+    # Create dynamic Prompt classes from prompt definitions
+    def create_prompt_classes(prompts)
+      prompts.map do |prompt_def|
+        # Create a new class that extends MCP::Prompt
+        Class.new(MCP::Prompt) do
+          @prompt_def = prompt_def
+
+          class << self
+            attr_reader :prompt_def
+
+            def name
+              @prompt_def.name
+            end
+
+            def description
+              @prompt_def.description
+            end
+
+            def arguments
+              @prompt_def.arguments || []
+            end
+
+            def get(**args)
+              result = @prompt_def.generator.call(args)
+
+              # Convert to MCP format
+              {
+                messages: result[:messages].map do |msg|
+                  {
+                    role: msg[:role],
+                    content: msg[:content]
+                  }
+                end
+              }
+            end
+          end
+        end
+      end
+    end
+
     def convert_input_schema(schema)
       # If it's already a proper JSON schema, return it
       if schema.is_a?(Hash) && schema[:type] && schema[:properties]

data/lib/claude_agent_sdk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ClaudeAgentSDK
-  VERSION = '0.1.3'
+  VERSION = '0.2.0'
 end

data/lib/claude_agent_sdk.rb

@@ -86,11 +86,12 @@ module ClaudeAgentSDK
   #
   # This client provides full control over the conversation flow with support
   # for streaming, hooks, permission callbacks, and dynamic message sending.
+  # The Client class always uses streaming mode for bidirectional communication.
   #
   # @example Basic usage
   #   Async do
   #     client = ClaudeAgentSDK::Client.new
-  #     client.connect
+  #     client.connect  # No arguments needed - automatically uses streaming mode
   #
   #     client.query("What is the capital of France?")
   #     client.receive_response do |msg|
@@ -150,8 +151,10 @@ module ClaudeAgentSDK
         configured_options = @options.dup_with(permission_prompt_tool_name: 'stdio')
       end
 
-      # Create transport
-      actual_prompt = prompt || ''
+      # Auto-connect with empty enumerator if no prompt is provided
+      # This matches the Python SDK pattern where ClaudeSDKClient always uses streaming mode
+      # An empty enumerator keeps stdin open for bidirectional communication
+      actual_prompt = prompt || [].to_enum
       @transport = SubprocessCLITransport.new(actual_prompt, configured_options)
       @transport.connect
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: claude-agent-sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Community Contributors
 bindir: bin
 cert_chain: []
-date: 2025-10-15 00:00:00.000000000 Z
+date: 2025-10-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: async
@@ -23,6 +23,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.4'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -114,7 +128,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.0.0
+      version: 3.2.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="