vector_mcp 0.1.0

data/lib/vector_mcp/transport/stdio.rb

@@ -0,0 +1,258 @@
+# frozen_string_literal: true
+
+# lib/vector_mcp/transport/stdio.rb
+require "json"
+require_relative "../errors"
+require_relative "../util"
+
+module VectorMCP
+  module Transport
+    # Implements the Model Context Protocol transport over standard input/output (stdio).
+    # This transport reads JSON-RPC messages line-by-line from `$stdin` and writes
+    # responses/notifications line-by-line to `$stdout`.
+    #
+    # It is suitable for inter-process communication on the same machine where a parent
+    # process spawns an MCP server and communicates with it via its stdio streams.
+    class Stdio
+      # @return [VectorMCP::Server] The server instance this transport is bound to.
+      attr_reader :server
+      # @return [Logger] The logger instance, shared with the server.
+      attr_reader :logger
+
+      # Initializes a new Stdio transport.
+      #
+      # @param server [VectorMCP::Server] The server instance that will handle messages.
+      def initialize(server)
+        @server = server
+        @logger = server.logger
+        @input_mutex = Mutex.new
+        @output_mutex = Mutex.new
+        @running = false
+        @input_thread = nil
+      end
+
+      # Starts the stdio transport, listening for input and processing messages.
+      # This method will block until the input stream is closed or an interrupt is received.
+      #
+      # @return [void]
+      def run
+        session = create_session
+        logger.info("Starting stdio transport")
+        @running = true
+
+        begin
+          launch_input_thread(session)
+          @input_thread.join
+        rescue Interrupt
+          logger.info("Interrupted. Shutting down...")
+        ensure
+          shutdown_transport
+        end
+      end
+
+      # Sends a JSON-RPC response message for a given request ID.
+      #
+      # @param id [String, Integer, nil] The ID of the request being responded to.
+      # @param result [Object] The result data for the successful request.
+      # @return [void]
+      def send_response(id, result)
+        response = {
+          jsonrpc: "2.0",
+          id: id,
+          result: result
+        }
+        write_message(response)
+      end
+
+      # Sends a JSON-RPC error response message.
+      #
+      # @param id [String, Integer, nil] The ID of the request that caused the error.
+      # @param code [Integer] The JSON-RPC error code.
+      # @param message [String] A short description of the error.
+      # @param data [Object, nil] Additional error data (optional).
+      # @return [void]
+      def send_error(id, code, message, data = nil)
+        error_obj = { code: code, message: message }
+        error_obj[:data] = data if data
+        response = {
+          jsonrpc: "2.0",
+          id: id,
+          error: error_obj
+        }
+        write_message(response)
+      end
+
+      # Sends a JSON-RPC notification message (a request without an ID).
+      #
+      # @param method [String] The method name of the notification.
+      # @param params [Hash, Array, nil] The parameters for the notification (optional).
+      # @return [void]
+      def send_notification(method, params = nil)
+        notification = {
+          jsonrpc: "2.0",
+          method: method
+        }
+        notification[:params] = params if params
+        write_message(notification)
+      end
+
+      # Initiates an immediate shutdown of the transport.
+      # Sets the running flag to false and attempts to kill the input reading thread.
+      #
+      # @return [void]
+      def shutdown
+        logger.info("Shutdown requested for stdio transport.")
+        @running = false
+        @input_thread&.kill if @input_thread&.alive?
+      end
+
+      private
+
+      # The main loop for reading and processing lines from `$stdin`.
+      # @api private
+      # @param session [VectorMCP::Session] The session object for this connection.
+      # @return [void]
+      def read_input_loop(session)
+        session_id = "stdio-session" # Constant identifier for stdio sessions
+
+        while @running
+          line = read_input_line
+          if line.nil?
+            logger.info("End of input ($stdin closed). Shutting down stdio transport.")
+            break
+          end
+          next if line.strip.empty?
+
+          handle_input_line(line, session, session_id)
+        end
+      end
+
+      # Reads a single line from `$stdin` in a thread-safe manner.
+      # @api private
+      # @return [String, nil] The line read from stdin, or nil if EOF is reached.
+      def read_input_line
+        @input_mutex.synchronize do
+          $stdin.gets
+        end
+      end
+
+      # Parses a line of input as JSON and dispatches it to the server for handling.
+      # Sends back any response data or errors.
+      # @api private
+      # @param line [String] The line of text read from stdin.
+      # @param session [VectorMCP::Session] The current session.
+      # @param session_id [String] The identifier for this session.
+      # @return [void]
+      def handle_input_line(line, session, session_id)
+        message = parse_json(line)
+        return if message.is_a?(Array) && message.empty? # Error handled in parse_json, indicated by empty array
+
+        response_data = server.handle_message(message, session, session_id)
+        send_response(message["id"], response_data) if message["id"] && response_data
+      rescue VectorMCP::ProtocolError => e
+        handle_protocol_error(e, message)
+      rescue StandardError => e
+        handle_unexpected_error(e, message)
+      end
+
+      # --- Run helpers (private) ---
+
+      # Creates a new session for the stdio connection.
+      # @api private
+      # @return [VectorMCP::Session] The newly created session.
+      def create_session
+        VectorMCP::Session.new(
+          server_info: server.server_info,
+          server_capabilities: server.server_capabilities,
+          protocol_version: server.protocol_version
+        )
+      end
+
+      # Launches the input reading loop in a new thread.
+      # Exits the process on fatal errors within this thread.
+      # @api private
+      # @param session [VectorMCP::Session] The session to pass to the input loop.
+      # @return [void]
+      def launch_input_thread(session)
+        @input_thread = Thread.new do
+          read_input_loop(session)
+        rescue StandardError => e
+          logger.error("Fatal error in input thread: #{e.message}")
+          exit(1) # Critical failure, exit the server process
+        end
+      end
+
+      # Cleans up transport resources, ensuring the input thread is stopped.
+      # @api private
+      # @return [void]
+      def shutdown_transport
+        @running = false
+        @input_thread&.kill if @input_thread&.alive?
+        logger.info("Stdio transport shut down")
+      end
+
+      # --- Input helpers (private) ---
+
+      # Parses a line of text as JSON.
+      # If parsing fails, sends a JSON-RPC ParseError and returns an empty array
+      # to signal that the error has been handled.
+      # @api private
+      # @param line [String] The line to parse.
+      # @return [Hash, Array] The parsed JSON message as a Hash, or an empty Array if a parse error occurred and was handled.
+      def parse_json(line)
+        JSON.parse(line.strip)
+      rescue JSON::ParserError => e
+        logger.error("Failed to parse message as JSON: #{line.strip.inspect} - #{e.message}")
+        id = begin
+          VectorMCP::Util.extract_id_from_invalid_json(line)
+        rescue StandardError
+          nil # Best effort, don't let ID extraction fail fatally
+        end
+        send_error(id, -32_700, "Parse error")
+        [] # Signal that error was handled
+      end
+
+      # Handles known VectorMCP::ProtocolError exceptions during message processing.
+      # @api private
+      # @param error [VectorMCP::ProtocolError] The protocol error instance.
+      # @param message [Hash, nil] The original parsed message, if available.
+      # @return [void]
+      def handle_protocol_error(error, message)
+        logger.error("Protocol error processing message: #{error.message} (code: #{error.code}), Details: #{error.details.inspect}")
+        request_id = error.request_id || message&.fetch("id", nil)
+        send_error(request_id, error.code, error.message, error.details)
+      end
+
+      # Handles unexpected StandardError exceptions during message processing.
+      # @api private
+      # @param error [StandardError] The unexpected error instance.
+      # @param message [Hash, nil] The original parsed message, if available.
+      # @return [void]
+      def handle_unexpected_error(error, message)
+        logger.error("Unexpected error handling message: #{error.message}\n#{error.backtrace.join("\n")}")
+        request_id = message&.fetch("id", nil)
+        send_error(request_id, -32_603, "Internal error", { details: error.message })
+      end
+
+      # Writes a message hash to `$stdout` as a JSON string, followed by a newline.
+      # Ensures the output is flushed. Handles EPIPE errors if stdout closes.
+      # @api private
+      # @param message [Hash] The message hash to send.
+      # @return [void]
+      def write_message(message)
+        json_msg = message.to_json
+        logger.debug { "Sending stdio message: #{json_msg}" }
+
+        begin
+          @output_mutex.synchronize do
+            $stdout.puts(json_msg)
+            $stdout.flush
+          end
+        rescue Errno::EPIPE
+          logger.error("Output pipe closed. Cannot send message. Shutting down stdio transport.")
+          shutdown # Initiate shutdown as we can no longer communicate
+        end
+      end
+    end
+  end
+end

data/lib/vector_mcp/util.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module VectorMCP
+  # Provides utility functions for VectorMCP operations, such as data conversion
+  # and parsing.
+  module Util
+    module_function
+
+    # Converts a given Ruby object into an **array of MCP content items**.
+    # This is the *primary* public helper for transforming arbitrary Ruby values
+    # into the wire-format expected by the MCP spec.
+    #
+    # Keys present in each returned hash:
+    # * **:type**      – Currently always `"text"`; future protocol versions may add rich/binary types.
+    # * **:text**      – UTF-8 encoded payload.
+    # * **:mimeType**  – IANA media-type describing `:text` (`"text/plain"`, `"application/json"`, …).
+    # * **:uri**       – _Optional._  Added downstream (e.g., by {Handlers::Core.read_resource}).
+    #
+    # The method **never** returns `nil` and **always** returns at least one element.
+    #
+    # @param input [Object] The Ruby value to convert. Supported types are
+    #   `String`, `Hash`, `Array`, or any object that responds to `#to_s`.
+    # @param mime_type [String] The fallback MIME type for plain-text conversions
+    #   (defaults to `"text/plain"`).
+    # @return [Array<Hash>] A non-empty array whose hashes conform to the MCP
+    #   `Content` schema.
+    #
+    # @example Simple string
+    #   VectorMCP::Util.convert_to_mcp_content("Hello")
+    #   # => [{type: "text", text: "Hello", mimeType: "text/plain"}]
+    #
+    # @example Complex object
+    #   VectorMCP::Util.convert_to_mcp_content({foo: 1})
+    #   # => [{type: "text", text: "{\"foo\":1}", mimeType: "application/json"}]
+    def convert_to_mcp_content(input, mime_type: "text/plain")
+      return string_content(input, mime_type) if input.is_a?(String)
+      return hash_content(input)             if input.is_a?(Hash)
+      return array_content(input, mime_type) if input.is_a?(Array)
+
+      fallback_content(input, mime_type)
+    end
+
+    # --- Conversion helpers (exposed as module functions) ---
+
+    # Converts a String into an MCP text content item.
+    # @param str [String] The string to convert.
+    # @param mime_type [String] The MIME type for the content.
+    # @return [Array<Hash>] MCP content array with one text item.
+    def string_content(str, mime_type)
+      [{ type: "text", text: str, mimeType: mime_type }]
+    end
+
+    # Converts a Hash into an MCP content item.
+    # If the hash appears to be a pre-formatted MCP content item, it's used directly.
+    # Otherwise, it's converted to a JSON string with `application/json` MIME type.
+    # @param hash [Hash] The hash to convert.
+    # @return [Array<Hash>] MCP content array.
+    def hash_content(hash)
+      if hash[:type] || hash["type"] # Already in content format
+        [hash.transform_keys(&:to_sym)]
+      else
+        [{ type: "text", text: hash.to_json, mimeType: "application/json" }]
+      end
+    end
+
+    # Converts an Array into MCP content items.
+    # If all array elements are pre-formatted MCP content items, they are used directly.
+    # Otherwise, each item in the array is recursively converted using {#convert_to_mcp_content}.
+    # @param arr [Array] The array to convert.
+    # @param mime_type [String] The default MIME type for child items if they need conversion.
+    # @return [Array<Hash>] MCP content array.
+    def array_content(arr, mime_type)
+      if arr.all? { |item| item.is_a?(Hash) && (item[:type] || item["type"]) }
+        arr.map { |item| item.transform_keys(&:to_sym) }
+      else
+        # Recursively convert each item, preserving the original mime_type intent for non-structured children.
+        arr.flat_map { |item| convert_to_mcp_content(item, mime_type: mime_type) }
+      end
+    end
+
+    # Fallback conversion for any other object type to an MCP text content item.
+    # Converts the object to its string representation.
+    # @param obj [Object] The object to convert.
+    # @param mime_type [String] The MIME type for the content.
+    # @return [Array<Hash>] MCP content array with one text item.
+    def fallback_content(obj, mime_type)
+      [{ type: "text", text: obj.to_s, mimeType: mime_type }]
+    end
+
+    module_function :string_content, :hash_content, :array_content, :fallback_content
+
+    # Extracts an ID from a potentially malformed JSON string using regex.
+    # This is a best-effort attempt, primarily for error reporting when full JSON parsing fails.
+    # It looks for patterns like `"id": 123` or `"id": "abc"`.
+    #
+    # @param json_string [String] The (potentially invalid) JSON string.
+    # @return [String, nil] The extracted ID as a string if found (numeric or string), otherwise nil.
+    def extract_id_from_invalid_json(json_string)
+      # Try to find id field with numeric value
+      numeric_match = json_string.match(/"id"\s*:\s*(\d+)/)
+      return numeric_match[1] if numeric_match
+
+      # Try to find id field with string value, preserving escaped characters
+      string_match = json_string.match(/"id"\s*:\s*"((?:\\.|[^"])*)"/)
+      return string_match[1] if string_match
+
+      nil
+    end
+  end
+end

data/lib/vector_mcp/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module VectorMCP
+  # The current version of the VectorMCP gem.
+  VERSION = "0.1.0"
+end

data/lib/vector_mcp.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+# lib/vector_mcp.rb
+require "logger"
+
+require_relative "vector_mcp/version"
+require_relative "vector_mcp/errors"
+require_relative "vector_mcp/definitions"
+require_relative "vector_mcp/session"
+require_relative "vector_mcp/util"
+require_relative "vector_mcp/handlers/core"
+require_relative "vector_mcp/transport/stdio"
+require_relative "vector_mcp/transport/sse"
+require_relative "vector_mcp/server"
+
+# The VectorMCP module provides a full-featured, opinionated Ruby implementation
+# of the **Model Context Protocol (MCP)**.  It gives developers everything needed
+# to spin up an MCP-compatible server—including:
+#
+# * **Transport adapters** (synchronous `stdio` or asynchronous HTTP + SSE)
+# * **High-level abstractions** for *tools*, *resources*, and *prompts*
+# * **JSON-RPC 2.0** message handling with sensible defaults and detailed
+#   error reporting helpers
+# * A small, dependency-free core (aside from optional async transports) that
+#   can be embedded in CLI apps, web servers, or background jobs.
+#
+# At its simplest you can do:
+#
+# ```ruby
+# require "vector_mcp"
+#
+# server = VectorMCP.new(name: "my-mcp-server")
+# server.register_tool(
+#   name: "echo",
+#   description: "Echo back the supplied text",
+#   input_schema: {type: "object", properties: {text: {type: "string"}}}
+# ) { |args| args["text"] }
+#
+# server.run # => starts the stdio transport and begins processing JSON-RPC messages
+# ```
+#
+# For production you could instead pass an `SSE` transport instance to `run` in
+# order to serve multiple concurrent clients over HTTP.
+#
+module VectorMCP
+  # @return [Logger] the shared logger instance for the library.
+  @logger = Logger.new($stderr, level: Logger::INFO, progname: "VectorMCP")
+
+  class << self
+    # @!attribute [r] logger
+    #   @return [Logger] the shared logger instance for the library.
+    attr_reader :logger
+
+    # Creates a new {VectorMCP::Server} instance. This is a **thin wrapper** around
+    # `VectorMCP::Server.new`; it exists purely for syntactic sugar so you can write
+    # `VectorMCP.new` instead of `VectorMCP::Server.new`.
+    #
+    # Any positional or keyword arguments are forwarded verbatim to the underlying
+    # constructor, so refer to {VectorMCP::Server#initialize} for the full list of
+    # accepted parameters.
+    def new(*args, **kwargs)
+      Server.new(*args, **kwargs)
+    end
+  end
+end

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: vector_mcp
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Sergio Bayona
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: async
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.23.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 2.23.0
+- !ruby/object:Gem::Dependency
+  name: async-container
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.16'
+- !ruby/object:Gem::Dependency
+  name: async-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.61'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.61'
+- !ruby/object:Gem::Dependency
+  name: async-io
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.36'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.36'
+- !ruby/object:Gem::Dependency
+  name: falcon
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.42'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.42'
+description: Server-side tools for implementing the Model Context Protocol in Ruby
+  applications
+email:
+- bayona.sergio@gmail.com
+executables:
+- console
+- setup
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- bin/console
+- bin/setup
+- lib/vector_mcp.rb
+- lib/vector_mcp/definitions.rb
+- lib/vector_mcp/errors.rb
+- lib/vector_mcp/handlers/core.rb
+- lib/vector_mcp/server.rb
+- lib/vector_mcp/session.rb
+- lib/vector_mcp/transport/sse.rb
+- lib/vector_mcp/transport/stdio.rb
+- lib/vector_mcp/util.rb
+- lib/vector_mcp/version.rb
+homepage: https://github.com/sergiobayona/vector_mcp
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/sergiobayona/vector_mcp
+  source_code_uri: https://github.com/sergiobayona/vector_mcp
+  changelog_uri: https://github.com/sergiobayona/vector_mcp/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.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.8
+specification_version: 4
+summary: Ruby implementation of the Model Context Protocol (MCP)
+test_files: []