just redo all of it from scratch

README.md

@@ -86,7 +86,7 @@ If you want to build a local command-line application, you can use the stdio tra
 ```ruby
 #!/usr/bin/env ruby
 require "mcp"
-require "mcp/transports/stdio"
+require "mcp/server/transports/stdio"
 
 # Create a simple tool
 class ExampleTool < MCP::Tool
@@ -115,7 +115,7 @@ server = MCP::Server.new(
 )
 
 # Create and start the transport
-transport = MCP::Transports::StdioTransport.new(server)
+transport = MCP::Server::Transports::StdioTransport.new(server)
 transport.open
 ```
 

examples/stdio_server.rb

@@ -3,7 +3,7 @@
 
 $LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
 require "mcp"
-require "mcp/transports/stdio"
+require "mcp/server/transports/stdio"
 
 # Create a simple tool
 class ExampleTool < MCP::Tool
@@ -91,5 +91,5 @@ server.resources_read_handler do |params|
 end
 
 # Create and start the transport
-transport = MCP::Transports::StdioTransport.new(server)
+transport = MCP::Server::Transports::StdioTransport.new(server)
 transport.open

lib/mcp.rb

@@ -1,23 +1,30 @@
 # frozen_string_literal: true
 
+require_relative "mcp/shared/version"
+require_relative "mcp/shared/configuration"
+require_relative "mcp/shared/instrumentation"
+require_relative "mcp/shared/methods"
+require_relative "mcp/shared/transport"
+require_relative "mcp/shared/content"
+require_relative "mcp/shared/string_utils"
+
+require_relative "mcp/shared/resource"
+require_relative "mcp/shared/resource/contents"
+require_relative "mcp/shared/resource/embedded"
+require_relative "mcp/shared/resource_template"
+
+require_relative "mcp/shared/tool"
+require_relative "mcp/shared/tool/input_schema"
+require_relative "mcp/shared/tool/response"
+require_relative "mcp/shared/tool/annotations"
+
+require_relative "mcp/shared/prompt"
+require_relative "mcp/shared/prompt/argument"
+require_relative "mcp/shared/prompt/message"
+require_relative "mcp/shared/prompt/result"
+
 require_relative "mcp/server"
-require_relative "mcp/string_utils"
+require_relative "mcp/server/transports/stdio"
-require_relative "mcp/tool"
-require_relative "mcp/tool/input_schema"
-require_relative "mcp/tool/annotations"
-require_relative "mcp/tool/response"
-require_relative "mcp/content"
-require_relative "mcp/resource"
-require_relative "mcp/resource/contents"
-require_relative "mcp/resource/embedded"
-require_relative "mcp/resource_template"
-require_relative "mcp/prompt"
-require_relative "mcp/prompt/argument"
-require_relative "mcp/prompt/message"
-require_relative "mcp/prompt/result"
-require_relative "mcp/version"
-require_relative "mcp/configuration"
-require_relative "mcp/methods"
 
 module MCP
   class << self

lib/mcp/server.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 require "json_rpc_handler"
-require_relative "instrumentation"
+require_relative "shared/instrumentation"
-require_relative "methods"
+require_relative "shared/methods"
 
 module MCP
   class Server

lib/mcp/server/transports/stdio.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "../../shared/transport"
+require "json"
+
+module MCP
+  module Transports
+    class StdioTransport < Transport
+      def initialize(server)
+        @server = server
+        @open = false
+        $stdin.set_encoding("UTF-8")
+        $stdout.set_encoding("UTF-8")
+        super
+      end
+
+      def open
+        @open = true
+        while @open && (line = $stdin.gets)
+          handle_json_request(line.strip)
+        end
+      end
+
+      def close
+        @open = false
+      end
+
+      def send_response(message)
+        json_message = message.is_a?(String) ? message : JSON.generate(message)
+        $stdout.puts(json_message)
+        $stdout.flush
+      end
+    end
+  end
+end

lib/mcp/shared/configuration.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module MCP
+  class Configuration
+    DEFAULT_PROTOCOL_VERSION = "2024-11-05"
+
+    attr_writer :exception_reporter, :instrumentation_callback, :protocol_version
+
+    def initialize(exception_reporter: nil, instrumentation_callback: nil, protocol_version: nil)
+      @exception_reporter = exception_reporter
+      @instrumentation_callback = instrumentation_callback
+      @protocol_version = protocol_version
+    end
+
+    def protocol_version
+      @protocol_version || DEFAULT_PROTOCOL_VERSION
+    end
+
+    def protocol_version?
+      !@protocol_version.nil?
+    end
+
+    def exception_reporter
+      @exception_reporter || default_exception_reporter
+    end
+
+    def exception_reporter?
+      !@exception_reporter.nil?
+    end
+
+    def instrumentation_callback
+      @instrumentation_callback || default_instrumentation_callback
+    end
+
+    def instrumentation_callback?
+      !@instrumentation_callback.nil?
+    end
+
+    def merge(other)
+      return self if other.nil?
+
+      exception_reporter = if other.exception_reporter?
+        other.exception_reporter
+      else
+        @exception_reporter
+      end
+      instrumentation_callback = if other.instrumentation_callback?
+        other.instrumentation_callback
+      else
+        @instrumentation_callback
+      end
+      protocol_version = if other.protocol_version?
+        other.protocol_version
+      else
+        @protocol_version
+      end
+
+      Configuration.new(
+        exception_reporter:,
+        instrumentation_callback:,
+        protocol_version:,
+      )
+    end
+
+    private
+
+    def default_exception_reporter
+      @default_exception_reporter ||= ->(exception, server_context) {}
+    end
+
+    def default_instrumentation_callback
+      @default_instrumentation_callback ||= ->(data) {}
+    end
+  end
+end

lib/mcp/shared/content.rb

@@ -0,0 +1,33 @@
+# typed: true
+# frozen_string_literal: true
+
+module MCP
+  module Content
+    class Text
+      attr_reader :text, :annotations
+
+      def initialize(text, annotations: nil)
+        @text = text
+        @annotations = annotations
+      end
+
+      def to_h
+        { text:, annotations:, type: "text" }.compact
+      end
+    end
+
+    class Image
+      attr_reader :data, :mime_type, :annotations
+
+      def initialize(data, mime_type, annotations: nil)
+        @data = data
+        @mime_type = mime_type
+        @annotations = annotations
+      end
+
+      def to_h
+        { data:, mime_type:, annotations:, type: "image" }.compact
+      end
+    end
+  end
+end

lib/mcp/shared/instrumentation.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module MCP
+  module Instrumentation
+    def instrument_call(method, &block)
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      begin
+        @instrumentation_data = {}
+        add_instrumentation_data(method:)
+
+        result = yield block
+
+        result
+      ensure
+        end_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        add_instrumentation_data(duration: end_time - start_time)
+
+        configuration.instrumentation_callback.call(@instrumentation_data)
+      end
+    end
+
+    def add_instrumentation_data(**kwargs)
+      @instrumentation_data.merge!(kwargs)
+    end
+  end
+end

lib/mcp/shared/methods.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module MCP
+  module Methods
+    INITIALIZE = "initialize"
+    PING = "ping"
+    LOGGING_SET_LEVEL = "logging/setLevel"
+
+    PROMPTS_GET = "prompts/get"
+    PROMPTS_LIST = "prompts/list"
+    COMPLETION_COMPLETE = "completion/complete"
+
+    RESOURCES_LIST = "resources/list"
+    RESOURCES_READ = "resources/read"
+    RESOURCES_TEMPLATES_LIST = "resources/templates/list"
+    RESOURCES_SUBSCRIBE = "resources/subscribe"
+    RESOURCES_UNSUBSCRIBE = "resources/unsubscribe"
+
+    TOOLS_CALL = "tools/call"
+    TOOLS_LIST = "tools/list"
+
+    SAMPLING_CREATE_MESSAGE = "sampling/createMessage"
+
+    class MissingRequiredCapabilityError < StandardError
+      attr_reader :method
+      attr_reader :capability
+
+      def initialize(method, capability)
+        super("Server does not support #{capability} (required for #{method})")
+        @method = method
+        @capability = capability
+      end
+    end
+
+    extend self
+
+    def ensure_capability!(method, capabilities)
+      case method
+      when PROMPTS_GET, PROMPTS_LIST
+        unless capabilities[:prompts]
+          raise MissingRequiredCapabilityError.new(method, :prompts)
+        end
+      when RESOURCES_LIST, RESOURCES_TEMPLATES_LIST, RESOURCES_READ, RESOURCES_SUBSCRIBE, RESOURCES_UNSUBSCRIBE
+        unless capabilities[:resources]
+          raise MissingRequiredCapabilityError.new(method, :resources)
+        end
+
+        if method == RESOURCES_SUBSCRIBE && !capabilities[:resources][:subscribe]
+          raise MissingRequiredCapabilityError.new(method, :resources_subscribe)
+        end
+      when TOOLS_CALL, TOOLS_LIST
+        unless capabilities[:tools]
+          raise MissingRequiredCapabilityError.new(method, :tools)
+        end
+      when SAMPLING_CREATE_MESSAGE
+        unless capabilities[:sampling]
+          raise MissingRequiredCapabilityError.new(method, :sampling)
+        end
+      when COMPLETION_COMPLETE
+        unless capabilities[:completions]
+          raise MissingRequiredCapabilityError.new(method, :completions)
+        end
+      when LOGGING_SET_LEVEL
+        # Logging is unsupported by the Server
+        unless capabilities[:logging]
+          raise MissingRequiredCapabilityError.new(method, :logging)
+        end
+      when INITIALIZE, PING
+        # No specific capability required for initialize or ping
+      end
+    end
+  end
+end

lib/mcp/shared/prompt.rb

@@ -0,0 +1,82 @@
+# typed: strict
+# frozen_string_literal: true
+
+module MCP
+  class Prompt
+    class << self
+      NOT_SET = Object.new
+
+      attr_reader :description_value
+      attr_reader :arguments_value
+
+      def template(args, server_context:)
+        raise NotImplementedError, "Subclasses must implement template"
+      end
+
+      def to_h
+        { name: name_value, description: description_value, arguments: arguments_value.map(&:to_h) }.compact
+      end
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@name_value, nil)
+        subclass.instance_variable_set(:@description_value, nil)
+        subclass.instance_variable_set(:@arguments_value, nil)
+      end
+
+      def prompt_name(value = NOT_SET)
+        if value == NOT_SET
+          @name_value
+        else
+          @name_value = value
+        end
+      end
+
+      def name_value
+        @name_value || StringUtils.handle_from_class_name(name)
+      end
+
+      def description(value = NOT_SET)
+        if value == NOT_SET
+          @description_value
+        else
+          @description_value = value
+        end
+      end
+
+      def arguments(value = NOT_SET)
+        if value == NOT_SET
+          @arguments_value
+        else
+          @arguments_value = value
+        end
+      end
+
+      def define(name: nil, description: nil, arguments: [], &block)
+        Class.new(self) do
+          prompt_name name
+          description description
+          arguments arguments
+          define_singleton_method(:template) do |args, server_context:|
+            instance_exec(args, server_context:, &block)
+          end
+        end
+      end
+
+      def validate_arguments!(args)
+        missing = required_args - args.keys
+        return if missing.empty?
+
+        raise MCP::Server::RequestHandlerError.new(
+          "Missing required arguments: #{missing.join(", ")}", nil, error_type: :missing_required_arguments
+        )
+      end
+
+      private
+
+      def required_args
+        arguments_value.filter_map { |arg| arg.name.to_sym if arg.required }
+      end
+    end
+  end
+end

lib/mcp/shared/prompt/argument.rb

@@ -0,0 +1,21 @@
+# typed: strict
+# frozen_string_literal: true
+
+module MCP
+  class Prompt
+    class Argument
+      attr_reader :name, :description, :required, :arguments
+
+      def initialize(name:, description: nil, required: false)
+        @name = name
+        @description = description
+        @required = required
+        @arguments = arguments
+      end
+
+      def to_h
+        { name:, description:, required: }.compact
+      end
+    end
+  end
+end

lib/mcp/shared/prompt/message.rb

@@ -0,0 +1,19 @@
+# typed: strict
+# frozen_string_literal: true
+
+module MCP
+  class Prompt
+    class Message
+      attr_reader :role, :content
+
+      def initialize(role:, content:)
+        @role = role
+        @content = content
+      end
+
+      def to_h
+        { role:, content: content.to_h }.compact
+      end
+    end
+  end
+end

lib/mcp/shared/prompt/result.rb

@@ -0,0 +1,19 @@
+# typed: strict
+# frozen_string_literal: true
+
+module MCP
+  class Prompt
+    class Result
+      attr_reader :description, :messages
+
+      def initialize(description: nil, messages: [])
+        @description = description
+        @messages = messages
+      end
+
+      def to_h
+        { description:, messages: messages.map(&:to_h) }.compact
+      end
+    end
+  end
+end

lib/mcp/shared/resource.rb

@@ -0,0 +1,24 @@
+# typed: strict
+# frozen_string_literal: true
+
+module MCP
+  class Resource
+    attr_reader :uri, :name, :description, :mime_type
+
+    def initialize(uri:, name:, description:, mime_type:)
+      @uri = uri
+      @name = name
+      @description = description
+      @mime_type = mime_type
+    end
+
+    def to_h
+      {
+        uri: @uri,
+        name: @name,
+        description: @description,
+        mimeType: @mime_type,
+      }.compact
+    end
+  end
+end

lib/mcp/shared/resource/contents.rb

@@ -0,0 +1,45 @@
+# typed: strict
+# frozen_string_literal: true
+
+module MCP
+  class Resource
+    class Contents
+      attr_reader :uri, :mime_type
+
+      def initialize(uri:, mime_type: nil)
+        @uri = uri
+        @mime_type = mime_type
+      end
+
+      def to_h
+        { uri:, mime_type: }.compact
+      end
+    end
+
+    class TextContents < Contents
+      attr_reader :text
+
+      def initialize(text:, uri:, mime_type:)
+        super(uri: uri, mime_type: mime_type)
+        @text = text
+      end
+
+      def to_h
+        super.merge(text: text)
+      end
+    end
+
+    class BlobContents < Contents
+      attr_reader :data
+
+      def initialize(data:, uri:, mime_type:)
+        super(uri: uri, mime_type: mime_type)
+        @data = data
+      end
+
+      def to_h
+        super.merge(data: data)
+      end
+    end
+  end
+end

lib/mcp/shared/resource/embedded.rb

@@ -0,0 +1,18 @@
+# typed: strict
+# frozen_string_literal: true
+
+module MCP
+  class Resource
+    class Embedded
+      attr_reader :resource, :annotations
+
+      def initialize(resource:, annotations: nil)
+        @annotations = annotations
+      end
+
+      def to_h
+        { resource: resource.to_h, annotations: }.compact
+      end
+    end
+  end
+end

lib/mcp/shared/resource_template.rb

@@ -0,0 +1,24 @@
+# typed: strict
+# frozen_string_literal: true
+
+module MCP
+  class ResourceTemplate
+    attr_reader :uri_template, :name, :description, :mime_type
+
+    def initialize(uri_template:, name:, description: nil, mime_type: nil)
+      @uri_template = uri_template
+      @name = name
+      @description = description
+      @mime_type = mime_type
+    end
+
+    def to_h
+      {
+        uriTemplate: @uri_template,
+        name: @name,
+        description: @description,
+        mimeType: @mime_type,
+      }.compact
+    end
+  end
+end

lib/mcp/shared/string_utils.rb

@@ -0,0 +1,26 @@
+# typed: strict
+# frozen_string_literal: true
+
+module MCP
+  module StringUtils
+    extend self
+
+    def handle_from_class_name(class_name)
+      underscore(demodulize(class_name))
+    end
+
+    private
+
+    def demodulize(path)
+      path.to_s.split("::").last || path.to_s
+    end
+
+    def underscore(camel_cased_word)
+      camel_cased_word.dup
+        .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+        .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+        .tr("-", "_")
+        .downcase
+    end
+  end
+end

lib/mcp/shared/tool.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module MCP
+  class Tool
+    class << self
+      NOT_SET = Object.new
+
+      attr_reader :description_value
+      attr_reader :input_schema_value
+      attr_reader :annotations_value
+
+      def call(*args, server_context:)
+        raise NotImplementedError, "Subclasses must implement call"
+      end
+
+      def to_h
+        result = {
+          name: name_value,
+          description: description_value,
+          inputSchema: input_schema_value.to_h,
+        }
+        result[:annotations] = annotations_value.to_h if annotations_value
+        result
+      end
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@name_value, nil)
+        subclass.instance_variable_set(:@description_value, nil)
+        subclass.instance_variable_set(:@input_schema_value, nil)
+        subclass.instance_variable_set(:@annotations_value, nil)
+      end
+
+      def tool_name(value = NOT_SET)
+        if value == NOT_SET
+          name_value
+        else
+          @name_value = value
+        end
+      end
+
+      def name_value
+        @name_value || StringUtils.handle_from_class_name(name)
+      end
+
+      def description(value = NOT_SET)
+        if value == NOT_SET
+          @description_value
+        else
+          @description_value = value
+        end
+      end
+
+      def input_schema(value = NOT_SET)
+        if value == NOT_SET
+          input_schema_value
+        elsif value.is_a?(Hash)
+          properties = value[:properties] || value["properties"] || {}
+          required = value[:required] || value["required"] || []
+          @input_schema_value = InputSchema.new(properties:, required:)
+        elsif value.is_a?(InputSchema)
+          @input_schema_value = value
+        end
+      end
+
+      def annotations(hash = NOT_SET)
+        if hash == NOT_SET
+          @annotations_value
+        else
+          @annotations_value = Annotations.new(**hash)
+        end
+      end
+
+      def define(name: nil, description: nil, input_schema: nil, annotations: nil, &block)
+        Class.new(self) do
+          tool_name name
+          description description
+          input_schema input_schema
+          self.annotations(annotations) if annotations
+          define_singleton_method(:call, &block) if block
+        end
+      end
+    end
+  end
+end

lib/mcp/shared/tool/annotations.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module MCP
+  class Tool
+    class Annotations
+      attr_reader :title, :read_only_hint, :destructive_hint, :idempotent_hint, :open_world_hint
+
+      def initialize(title: nil, read_only_hint: nil, destructive_hint: nil, idempotent_hint: nil, open_world_hint: nil)
+        @title = title
+        @read_only_hint = read_only_hint
+        @destructive_hint = destructive_hint
+        @idempotent_hint = idempotent_hint
+        @open_world_hint = open_world_hint
+      end
+
+      def to_h
+        {
+          title:,
+          readOnlyHint: read_only_hint,
+          destructiveHint: destructive_hint,
+          idempotentHint: idempotent_hint,
+          openWorldHint: open_world_hint,
+        }.compact
+      end
+    end
+  end
+end