encom 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8768eb489945cac6ad76aae9c8f34457db2224cc343868b93518fb7b2ae32ae7
+  data.tar.gz: b9621af83733c962fb380915dd3fbd5c5cd452bb53dbffc6a0b2b50143c76119
+SHA512:
+  metadata.gz: d0d9977d2fd67dd06414c88a10fc309212cd4df8fd261bb0fbe4d9c4e7bb97cc84e91a9f6605b455c3ccc04f887f59526f79e73fba44d08ec5e535e82085223b
+  data.tar.gz: 14ad9642e9978fc251b3d03d215d81ce9aab1f8f4baf24b5ab8a5afbe29b0e795a923a8b8d802c99c3ffee1e7943503facdc905fd1a13cd5fc61783b4e347b4d

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/standardrb/standard
+ruby_version: 3.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Kyle Byrne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,159 @@
+# Encom
+
+Work in progress Ruby implementation of the [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP).
+
+Encom is a Ruby library for implementing both MCP servers and clients. The gem provides a flexible and easy-to-use framework to build applications that can communicate using the [MCP specification](https://spec.modelcontextprotocol.io/specification/2024-11-05/).
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'encom'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install encom
+```
+
+## Building an MCP Server
+
+### Basic Server Implementation
+
+```ruby
+require 'encom/server'
+require 'encom/server_transport/stdio'
+
+class MyServer < Encom::Server
+  name "MyMCPServer"
+  version "1.0.0"
+  
+  # Define a tool that the server exposes
+  tool :hello_world,
+       "Says hello to the specified name",
+       {
+         type: "object",
+         properties: {
+           name: {
+             type: "string",
+             description: "The name to greet"
+           }
+         },
+         required: ["name"]
+       } do |args|
+         { greeting: "Hello, #{args[:name]}!" }
+       end
+end
+
+# Start the server with a chosen transport mechanism
+server = MyServer.new
+server.run(Encom::ServerTransport::Stdio)
+```
+
+### Starting Your Server
+
+```ruby
+# Run the server file
+ruby my_server.rb
+```
+
+## Building an MCP Client
+
+### Basic Client Implementation
+
+```ruby
+require 'encom/client'
+require 'encom/transport/stdio'
+
+# Create a client
+client = Encom::Client.new(
+  name: 'MyClient',
+  version: '1.0.0',
+  capabilities: {
+    tools: {
+      execute: true
+    }
+  }
+)
+
+# Set up error handling
+client.on_error do |error|
+  puts "ERROR: #{error.class} - #{error.message}"
+end
+
+# Connect to an MCP server
+transport = Encom::Transport::Stdio.new(
+  command: 'ruby',
+  args: ['path/to/your/server.rb']
+)
+
+client.connect(transport)
+
+# List available tools
+tools = client.list_tools
+
+# Call a tool
+result = client.call_tool(
+  name: 'hello_world',
+  arguments: { name: 'World' }
+)
+
+puts result[:greeting] # Outputs: Hello, World!
+
+# Close the connection when done
+client.close
+```
+
+## Example Usage
+
+See the `examples` directory for complete demonstrations:
+
+- `filesystem_demo.rb`: Shows how to connect to an MCP filesystem server
+
+## Specification support
+
+### Server
+
+- Tools ✅
+- Prompts 🟠
+- Resources 🟠
+
+We haven't yet added a DSL for defining prompts or resources but these can be defined as shown in `bin/mock_mcp_server`
+
+### Client
+- Server tool interface ✅
+- Server prompt interface ❌
+- Server resource interface ❌
+- Roots ❌
+- Sampling ❌
+
+
+### Available Transports
+
+Encom currently supports different transport mechanisms for communication:
+
+- **STDIO**: Communication through standard input/output
+- Custom transports can be implemented by extending the base transport classes
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/kylebyrne/encom.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'standard/rake'
+
+task default: %i[spec standard]

data/examples/filesystem_demo.rb

@@ -0,0 +1,191 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'encom/client'
+require 'encom/transport/stdio'
+require 'fileutils'
+require 'tmpdir'
+
+# Create a client with appropriate capabilities
+def create_client
+  client = Encom::Client.new(
+    name: 'FilesystemDemoClient',
+    version: '1.0.0',
+    capabilities: {
+      tools: {
+        execute: true
+      }
+    }
+  )
+
+  # Set up error handling
+  client.on_error do |error|
+    puts "ERROR: #{error.class} - #{error.message}"
+  end
+
+  client
+end
+
+# Connect to the filesystem server
+def connect_to_server(client)
+  # Use npx to run the server without requiring global installation
+  transport = Encom::Transport::Stdio.new(
+    command: 'npx',
+    args: [
+      '-y',
+      '@modelcontextprotocol/server-filesystem',
+      '.' # Allow access to the current directory
+    ]
+  )
+
+  puts 'Connecting to filesystem server using npx...'
+  client.connect(transport)
+
+  # Give it a moment to initialize
+  sleep(1)
+
+  if client.initialized
+    puts "✓ Connected to #{client.server_info[:name]} #{client.server_info[:version]}"
+    puts "✓ Protocol version: #{client.protocol_version}"
+    puts "✓ Server capabilities: #{client.server_capabilities.inspect}"
+    puts ''
+  else
+    puts '✗ Failed to connect to server'
+    exit(1)
+  end
+end
+
+# List available tools
+def list_tools(client)
+  puts 'Fetching available tools...'
+  tools = client.list_tools
+
+  puts "Available tools (#{tools.size}):"
+  tools.each_with_index do |tool, i|
+    puts "#{i + 1}. #{tool[:name]} - #{tool[:description]}"
+  end
+  puts ''
+
+  tools
+end
+
+# Demo the filesystem tools
+def demo_filesystem_tools(client, _tools)
+  # Get the list of allowed directories
+  puts 'Getting allowed directories...'
+  result = client.call_tool(
+    name: 'list_allowed_directories',
+    arguments: {}
+  )
+  allowed_dirs = extract_text_content(result)
+  puts allowed_dirs
+  puts ''
+
+  # List files in current directory
+  puts 'Listing files in current directory...'
+  result = client.call_tool(
+    name: 'list_directory',
+    arguments: {
+      path: '.'
+    }
+  )
+  puts extract_text_content(result)
+  puts ''
+
+  # Create a temporary file within the project directory
+  temp_file = "examples/mcp_demo_#{Time.now.to_i}.txt"
+  puts "Creating a temporary file at #{temp_file}..."
+
+  content = "This is a test file created by the MCP filesystem demo at #{Time.now}"
+  result = client.call_tool(
+    name: 'write_file',
+    arguments: {
+      path: temp_file,
+      content: content
+    }
+  )
+  puts extract_text_content(result)
+  puts ''
+
+  # Read the file back
+  puts 'Reading back the file content...'
+  result = client.call_tool(
+    name: 'read_file',
+    arguments: {
+      path: temp_file
+    }
+  )
+  puts "File content: #{extract_text_content(result)}"
+  puts ''
+
+  # Get file info
+  puts 'Getting file information...'
+  result = client.call_tool(
+    name: 'get_file_info',
+    arguments: {
+      path: temp_file
+    }
+  )
+  puts extract_text_content(result)
+  puts ''
+
+  # Clean up - Move the file to a .bak extension to demonstrate move_file
+  puts 'Demonstrating move_file by renaming the temporary file...'
+  bak_file = "#{temp_file}.bak"
+  result = client.call_tool(
+    name: 'move_file',
+    arguments: {
+      source: temp_file,
+      destination: bak_file
+    }
+  )
+  puts extract_text_content(result)
+  puts "File renamed to: #{bak_file}"
+  puts ''
+
+  # Search for our backup file
+  puts 'Searching for our backup file...'
+  result = client.call_tool(
+    name: 'search_files',
+    arguments: {
+      path: 'examples',
+      pattern: 'mcp_demo_'
+    }
+  )
+  puts extract_text_content(result)
+  puts ''
+
+  puts "Note: Remember to manually delete the backup file: #{bak_file}"
+  puts ''
+end
+
+# Helper to extract text content from a tool response
+def extract_text_content(result)
+  if result && result[:content]&.first
+    content_item = result[:content].first
+    if content_item[:type] == 'text'
+      content_item[:text]
+    else
+      content_item.inspect
+    end
+  else
+    'No content in response'
+  end
+end
+
+# Main program
+def main
+  client = create_client
+  connect_to_server(client)
+
+  tools = list_tools(client)
+  demo_filesystem_tools(client, tools)
+
+  puts 'Demo completed successfully!'
+ensure
+  client&.close
+end
+
+# Run the demo
+main if $PROGRAM_NAME == __FILE__

data/lib/encom/client.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'encom/error_codes'
+module Encom
+  class Client
+    LATEST_PROTOCOL_VERSION = '2024-11-05'
+    SUPPORTED_PROTOCOL_VERSIONS = [
+      LATEST_PROTOCOL_VERSION
+      # Add more supported versions as they're developed
+    ].freeze
+
+    class ProtocolVersionError < StandardError; end
+    class ConnectionError < StandardError; end
+    class ToolError < StandardError; end
+    class RequestTimeoutError < StandardError; end
+
+    attr_reader :name, :version, :responses, :server_info, :server_capabilities,
+                :initialized, :protocol_version, :tool_responses
+
+    def initialize(name:, version:, capabilities:)
+      @name = name
+      @version = version
+      @capabilities = capabilities
+      @message_id = 0
+      @responses = []
+      @tool_responses = {}
+      @pending_requests = {}
+      @response_mutex = Mutex.new
+      @response_condition = ConditionVariable.new
+      @initialized = false
+      @closing = false
+      @error_handlers = []
+      @first_error_reported = false # Flag to track if we've already reported an error
+    end
+
+    # Register a callback for error handling
+    def on_error(&block)
+      @error_handlers << block
+      self
+    end
+
+    def connect(transport)
+      @transport = transport
+
+      @transport
+        .on_close { close }
+        .on_data { |data| handle_response(data) }
+        .on_error { |error| handle_transport_error(error) }
+        .start
+
+      # Send initialize request
+      request(
+        {
+          method: 'initialize',
+          params: {
+            protocolVersion: LATEST_PROTOCOL_VERSION,
+            capabilities: @capabilities,
+            clientInfo: {
+              name: @name,
+              version: @version
+            }
+          }
+        }
+      )
+    rescue JSON::ParserError => e
+      # This might be a protocol version error or other startup error
+      trigger_error(ConnectionError.new("Error parsing initial response: #{e.message}"))
+    end
+
+    def handle_transport_error(error)
+      trigger_error(ConnectionError.new("Transport error: #{error.message}"))
+    end
+
+    def handle_response(data)
+      data = data.strip if data.is_a?(String)
+      parsed_response = JSON.parse(data, symbolize_names: true)
+
+      @responses << parsed_response
+
+      # Check for protocol errors immediately, even without an ID
+      if parsed_response[:error] &&
+         parsed_response[:error][:code] == Encom::ErrorCodes::PROTOCOL_ERROR &&
+         parsed_response[:error][:message].include?('Unsupported protocol version')
+        # Only trigger a protocol error if we haven't already closed the connection
+        unless @closing
+          error = ProtocolVersionError.new(parsed_response[:error][:message])
+          close
+          trigger_error(error)
+        end
+        return
+      end
+
+      if parsed_response[:id]
+        @response_mutex.synchronize do
+          @tool_responses[parsed_response[:id]] = parsed_response
+          @response_condition.broadcast # Signal threads waiting for this response
+        end
+
+        if parsed_response[:result]
+          handle_initialize_result(parsed_response) if @pending_requests[parsed_response[:id]] == 'initialize'
+        elsif parsed_response[:error]
+          handle_error(parsed_response)
+        end
+      end
+    rescue JSON::ParserError => e
+      error_msg = "Error parsing response: #{e.message}, Raw response: #{data.inspect}"
+      trigger_error(ConnectionError.new(error_msg))
+    end
+
+    def handle_initialize_result(response)
+      @server_info = response[:result][:serverInfo]
+      @server_capabilities = response[:result][:capabilities]
+      @protocol_version = response[:result][:protocolVersion]
+
+      unless SUPPORTED_PROTOCOL_VERSIONS.include?(@protocol_version)
+        error_message = "Unsupported protocol version: #{@protocol_version}. " \
+                        "This client supports: #{SUPPORTED_PROTOCOL_VERSIONS.join(', ')}"
+        error = ProtocolVersionError.new(error_message)
+        close
+        trigger_error(error)
+        return
+      end
+
+      @initialized = true
+
+      notification(
+        {
+          method: 'initialized',
+          params: {}
+        }
+      )
+    end
+
+    def handle_error(response)
+      # Don't process errors if we're already closing
+      return if @closing
+
+      # Check if this is an error response to an initialize request
+      if @pending_requests[response[:id]] == 'initialize' &&
+         response[:error][:code] == Encom::ErrorCodes::PROTOCOL_ERROR
+        error = ProtocolVersionError.new("Unsupported protocol version: #{response[:error][:message]}")
+        close
+        trigger_error(error)
+        return
+      end
+
+      error_msg = "Error from server: #{response[:error][:message]} (#{response[:error][:code]})"
+      trigger_error(ConnectionError.new(error_msg))
+    end
+
+    def trigger_error(error)
+      # Only report the first error
+      return if @first_error_reported
+
+      @first_error_reported = true
+
+      if @error_handlers.empty?
+        # TODO: I'd love to re-raise this to the user but this ends up run
+        # in a background thread right now due to how we've implement the stdio transport
+        puts "MCP Client Error: #{error.message}"
+      else
+        @error_handlers.each { |handler| handler.call(error) }
+      end
+    end
+
+    def request(request_data)
+      @message_id += 1
+      id = @message_id
+
+      @pending_requests[id] = request_data[:method]
+
+      @transport.send(
+        JSON.generate({
+          jsonrpc: '2.0',
+          id: id
+        }.merge(request_data))
+      )
+
+      id
+    end
+
+    def notification(notification_data)
+      @transport.send(
+        JSON.generate({
+          jsonrpc: '2.0'
+        }.merge(notification_data))
+      )
+    end
+
+    # Wait for a response with a specific ID, with timeout
+    #
+    # @param id [Integer] The ID of the request to wait for
+    # @param timeout [Numeric] The timeout in seconds
+    # @return [Hash] The response
+    # @raise [RequestTimeoutError] If the timeout is reached
+    def wait_for_response(id, timeout = 5)
+      deadline = Time.now + timeout
+
+      @response_mutex.synchronize do
+        @response_condition.wait(@response_mutex, 0.1) while !@tool_responses.key?(id) && Time.now < deadline
+
+        raise RequestTimeoutError, "Timeout waiting for response to request #{id}" unless @tool_responses.key?(id)
+
+        @tool_responses[id]
+      end
+    end
+
+    # List available tools from the server
+    #
+    # @param params [Hash, nil] Optional parameters for the list_tools request
+    # @param timeout [Numeric] The timeout in seconds
+    # @return [Array<Hash>] The list of tools
+    # @raise [RequestTimeoutError] If the timeout is reached
+    # @raise [ConnectionError] If there is an error communicating with the server
+    def list_tools(params = nil, timeout = 5)
+      request_data = {
+        method: 'tools/list'
+      }
+
+      request_data[:params] = params if params
+
+      id = request(request_data)
+
+      # Wait for the response
+      response = wait_for_response(id, timeout)
+
+      if response[:error]
+        error_msg = "Error from server: #{response[:error][:message]} (#{response[:error][:code]})"
+        raise ConnectionError, error_msg
+      end
+
+      # Return the tools array
+      response[:result][:tools]
+    end
+
+    # Call a tool on the server
+    #
+    # @param name [String] The name of the tool to call
+    # @param arguments [Hash] The arguments to pass to the tool
+    # @param timeout [Numeric] The timeout in seconds
+    # @return [Hash] The tool result containing content array
+    # @raise [RequestTimeoutError] If the timeout is reached
+    # @raise [ToolError] If there is an error with the tool execution
+    # @raise [ConnectionError] If there is an error communicating with the server
+    def call_tool(name:, arguments:, timeout: 5)
+      id = request(
+        {
+          method: 'tools/call',
+          params: {
+            name: name,
+            arguments: arguments
+          }
+        }
+      )
+
+      # Wait for the response
+      response = wait_for_response(id, timeout)
+
+      if response[:error]
+        error_msg = "Tool error: #{response[:error][:message]} (#{response[:error][:code]})"
+        raise ToolError, error_msg
+      end
+
+      # Return the result content
+      response[:result]
+    end
+
+    # Get the list of tools from a previous list_tools request
+    #
+    # @param request_id [Integer] The ID of the list_tools request
+    # @return [Array<Hash>, nil] The list of tools or nil if the response isn't available
+    def get_tools(request_id)
+      response = @tool_responses[request_id]
+      return nil unless response && response[:result]
+
+      response[:result][:tools]
+    end
+
+    # Get the result of a tool call
+    #
+    # @param request_id [Integer] The ID of the call_tool request
+    # @return [Hash, nil] The tool result or nil if the response isn't available
+    def get_tool_result(request_id)
+      response = @tool_responses[request_id]
+      return nil unless response
+
+      if response[:error]
+        error_msg = "Tool error: #{response[:error][:message]} (#{response[:error][:code]})"
+        raise ToolError, error_msg
+      end
+
+      response[:result]
+    end
+
+    def close
+      return if @closing
+
+      @closing = true
+      puts 'Closing'
+
+      return unless @transport
+
+      @transport.close
+      @transport = nil
+    end
+  end
+end