agent-harness 0.5.3 → 0.5.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3dfde368468f5c0c037ec1cb2fefd705e813d192e3723fd70126757cd851cf14
-  data.tar.gz: f68f11de99ea61807ab1bb7a94a28aca4aa37e3346469b195a77019f6ceeceec
+  metadata.gz: 0ac511d4448bf777f9389cdba34c165a3b97ac607cfca1db90f0fd5c9de0a4af
+  data.tar.gz: 946efb4b7f13e36da7b4c3cc8c3efc3722421aa83ccaf9789efdaa4e776d4bc6
 SHA512:
-  metadata.gz: 4cf0d1807fee47eb2ef1aecc63ab8c10ce71a681d6c98ca2cb860ae7eb9ba7b1a8d88e4382e9ff1f5f2f25acd9380a6cf4c3d8e61f5cf008d920b4d2bbf7b4bc
-  data.tar.gz: cd6ac3ae08acf302369a28cdda0a3e332994f679ad37258c0f4dd869f99f18396ccb1cb52d9a6d5bcbb3c6ac3c776ba87a5338edb8280b46785edce254eb8258
+  metadata.gz: 7c3afe5167530f2cd4f8b435b5098732a12b3630f4324cbfa002f3983d760e3a41488ae0d565a0a0694d9b08704d74f010845fb39251a8f92782c6c6d01a572e
+  data.tar.gz: 8a9d9706b997b2c8543a45a43cdf476a089eaded7283fe6b3dade1394242f9786c7458b68a2953bcb866611d21a74a360a35d5b1ae3ade40ebe222c819d3c7ce

data/.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.5.3"
+  ".": "0.5.4"
 }

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## [Unreleased]
 
+## [0.5.4](https://github.com/viamin/agent-harness/compare/agent-harness/v0.5.3...agent-harness/v0.5.4) (2026-03-27)
+
+
+### Bug Fixes
+
+* 44: feat(mcp): add first-class MCP server configuration to request execution ([#45](https://github.com/viamin/agent-harness/issues/45)) ([454cd9b](https://github.com/viamin/agent-harness/commit/454cd9be1c4bcd2eb92a4ca6f81cc012d4ce1f8c))
+
 ## [0.5.3](https://github.com/viamin/agent-harness/compare/agent-harness/v0.5.2...agent-harness/v0.5.3) (2026-03-27)
 
 

data/lib/agent_harness/errors.rb

@@ -57,6 +57,20 @@ module AgentHarness
   # Configuration errors
   class ConfigurationError < Error; end
 
+  # MCP-specific errors
+  class McpConfigurationError < ConfigurationError; end
+
+  class McpUnsupportedError < ProviderError
+    attr_reader :provider
+
+    def initialize(message = nil, provider: nil, **kwargs)
+      @provider = provider
+      super(message, **kwargs)
+    end
+  end
+
+  class McpTransportUnsupportedError < McpUnsupportedError; end
+
   # Orchestration errors
   class NoProvidersAvailableError < Error
     attr_reader :attempted_providers, :errors

data/lib/agent_harness/mcp_server.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module AgentHarness
+  # Canonical representation of an MCP server for request-time execution.
+  #
+  # Provider-agnostic value object that can be translated by each provider
+  # adapter into its CLI-specific configuration.
+  #
+  # @example stdio server
+  #   McpServer.new(
+  #     name: "filesystem",
+  #     transport: "stdio",
+  #     command: ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/workspace"],
+  #     env: { "DEBUG" => "0" }
+  #   )
+  #
+  # @example HTTP/URL server
+  #   McpServer.new(
+  #     name: "playwright",
+  #     transport: "http",
+  #     url: "http://mcp-playwright:3000/mcp"
+  #   )
+  class McpServer
+    VALID_TRANSPORTS = %w[stdio http sse].freeze
+
+    attr_reader :name, :transport, :command, :args, :env, :url
+
+    # @param name [String] unique name for this MCP server
+    # @param transport [String] one of "stdio", "http", "sse"
+    # @param command [Array<String>, nil] command to launch (stdio only)
+    # @param args [Array<String>, nil] additional args for the command
+    # @param env [Hash<String,String>, nil] environment variables for the server process
+    # @param url [String, nil] URL for HTTP/SSE transport
+    def initialize(name:, transport:, command: nil, args: nil, env: nil, url: nil)
+      @name = name
+      @transport = transport.to_s
+      @command = command
+      @args = args || []
+      @env = env || {}
+      @url = url
+
+      validate!
+    end
+
+    # Build from a plain Hash (e.g. from user input or serialized config)
+    #
+    # @param hash [Hash] server definition
+    # @return [McpServer]
+    def self.from_hash(hash)
+      unless hash.is_a?(Hash)
+        raise McpConfigurationError, "MCP server definition must be a Hash, got #{hash.class}"
+      end
+
+      begin
+        hash = hash.transform_keys(&:to_sym)
+      rescue NoMethodError, TypeError => e
+        raise McpConfigurationError, "MCP server hash contains invalid keys: #{e.message}"
+      end
+
+      new(
+        name: hash[:name],
+        transport: hash[:transport],
+        command: hash[:command],
+        args: hash[:args],
+        env: hash[:env],
+        url: hash[:url]
+      )
+    end
+
+    def stdio?
+      @transport == "stdio"
+    end
+
+    def http?
+      %w[http sse].include?(@transport)
+    end
+
+    def to_h
+      h = {name: @name, transport: @transport}
+      if stdio?
+        h[:command] = @command
+        h[:args] = @args unless @args.empty?
+      else
+        h[:url] = @url
+      end
+      h[:env] = @env unless @env.empty?
+      h
+    end
+
+    private
+
+    def validate!
+      raise McpConfigurationError, "MCP server name is required" if @name.nil? || @name.to_s.strip.empty?
+
+      unless VALID_TRANSPORTS.include?(@transport)
+        raise McpConfigurationError,
+          "Invalid MCP transport '#{@transport}' for server '#{@name}'. Valid transports: #{VALID_TRANSPORTS.join(", ")}"
+      end
+
+      validate_args!
+      validate_env!
+      validate_stdio! if stdio?
+      validate_http! if http?
+      validate_no_stdio_only_fields_on_http! if http?
+    end
+
+    def validate_args!
+      return if @args.is_a?(Array) && @args.all? { |a| a.is_a?(String) }
+
+      raise McpConfigurationError,
+        "MCP server '#{@name}' args must be an Array of Strings"
+    end
+
+    def validate_env!
+      return if @env.is_a?(Hash) && @env.keys.all? { |k| k.is_a?(String) } && @env.values.all? { |v| v.is_a?(String) }
+
+      raise McpConfigurationError,
+        "MCP server '#{@name}' env must be a Hash with String keys and values"
+    end
+
+    def validate_stdio!
+      if @command.nil? || !@command.is_a?(Array) || @command.empty?
+        raise McpConfigurationError,
+          "MCP server '#{@name}' with stdio transport requires a non-empty command array"
+      end
+
+      unless @command.all? { |c| c.is_a?(String) }
+        raise McpConfigurationError,
+          "MCP server '#{@name}' command must contain only strings"
+      end
+
+      return if @url.nil?
+
+      raise McpConfigurationError,
+        "MCP server '#{@name}' with stdio transport should not have a url"
+    end
+
+    def validate_http!
+      if @url.nil? || @url.to_s.strip.empty?
+        raise McpConfigurationError,
+          "MCP server '#{@name}' with #{@transport} transport requires a url"
+      end
+
+      return if @command.nil?
+
+      raise McpConfigurationError,
+        "MCP server '#{@name}' with #{@transport} transport should not have a command"
+    end
+
+    def validate_no_stdio_only_fields_on_http!
+      return if @args.empty?
+
+      raise McpConfigurationError,
+        "MCP server '#{@name}' with #{@transport} transport should not have args (args are only valid for stdio)"
+    end
+  end
+end

data/lib/agent_harness/providers/adapter.rb

@@ -124,6 +124,58 @@ module AgentHarness
         []
       end
 
+      # Supported MCP transport types for this provider
+      #
+      # @return [Array<String>] supported transports (e.g. ["stdio", "http"])
+      def supported_mcp_transports
+        []
+      end
+
+      # Build provider-specific MCP flags/arguments for CLI invocation
+      #
+      # @param mcp_servers [Array<McpServer>] MCP server definitions
+      # @param working_dir [String, nil] working directory for temp files
+      # @return [Array<String>] CLI flags to append to the command
+      def build_mcp_flags(mcp_servers, working_dir: nil)
+        []
+      end
+
+      # Validate that this provider can handle the given MCP servers
+      #
+      # @param mcp_servers [Array<McpServer>] MCP server definitions
+      # @raise [McpUnsupportedError] if MCP is not supported
+      # @raise [McpTransportUnsupportedError] if a transport is not supported
+      def validate_mcp_servers!(mcp_servers)
+        return if mcp_servers.nil? || mcp_servers.empty?
+
+        unless supports_mcp?
+          raise McpUnsupportedError.new(
+            "Provider '#{self.class.provider_name}' does not support MCP servers",
+            provider: self.class.provider_name
+          )
+        end
+
+        supported = supported_mcp_transports
+
+        if supported.empty?
+          raise McpUnsupportedError.new(
+            "Provider '#{self.class.provider_name}' does not support request-time MCP servers",
+            provider: self.class.provider_name
+          )
+        end
+
+        mcp_servers.each do |server|
+          next if supported.include?(server.transport)
+
+          raise McpTransportUnsupportedError.new(
+            "Provider '#{self.class.provider_name}' does not support MCP transport " \
+            "'#{server.transport}' (server: '#{server.name}'). " \
+            "Supported transports: #{supported.join(", ")}",
+            provider: self.class.provider_name
+          )
+        end
+      end
+
       # Check if provider supports dangerous mode
       #
       # @return [Boolean] true if dangerous mode is supported

data/lib/agent_harness/providers/anthropic.rb

@@ -172,10 +172,27 @@ module AgentHarness
         }
       end
 
+      def send_message(prompt:, **options)
+        super
+      ensure
+        cleanup_mcp_tempfiles!
+      end
+
       def supports_mcp?
         true
       end
 
+      def supported_mcp_transports
+        %w[stdio http sse]
+      end
+
+      def build_mcp_flags(mcp_servers, working_dir: nil)
+        return [] if mcp_servers.empty?
+
+        config_path = write_mcp_config_file(mcp_servers, working_dir: working_dir)
+        ["--mcp-config", config_path]
+      end
+
       def supports_dangerous_mode?
         true
       end
@@ -266,6 +283,11 @@ module AgentHarness
           cmd += dangerous_mode_flags
         end
 
+        # Add MCP server flags (validated/normalized by Base#send_message)
+        if options[:mcp_servers]&.any?
+          cmd += build_mcp_flags(options[:mcp_servers])
+        end
+
         # Add custom flags from config
         cmd += @config.default_flags if @config.default_flags&.any?
 
@@ -376,6 +398,87 @@ module AgentHarness
         servers
       end
 
+      def write_mcp_config_file(mcp_servers, working_dir: nil)
+        require "tempfile"
+        require "tmpdir"
+        require "securerandom"
+
+        config = build_claude_mcp_config(mcp_servers)
+        config_json = JSON.generate(config)
+
+        if @executor.is_a?(DockerCommandExecutor)
+          # When running inside a Docker container, write the config file
+          # inside the container so the CLI process can read it.
+          # Track the path so cleanup_mcp_tempfiles! can remove it after execution.
+          container_path = "/tmp/agent_harness_mcp_#{SecureRandom.hex(8)}.json"
+          result = @executor.execute(
+            ["sh", "-c", "cat > #{container_path}"],
+            stdin_data: config_json,
+            timeout: 5
+          )
+          unless result.success?
+            raise McpConfigurationError,
+              "Failed to write MCP config inside container: #{result.stderr}"
+          end
+
+          @mcp_docker_config_paths ||= []
+          @mcp_docker_config_paths << container_path
+
+          container_path
+        else
+          dir = working_dir || Dir.tmpdir
+          file = Tempfile.new(["agent_harness_mcp_", ".json"], dir)
+          file.write(config_json)
+          file.close
+
+          # Hold a reference so the Tempfile is not garbage-collected (and
+          # therefore deleted) before the CLI process reads it.
+          # Cleaned up by cleanup_mcp_tempfiles! after execution.
+          @mcp_config_tempfiles ||= []
+          @mcp_config_tempfiles << file
+
+          file.path
+        end
+      end
+
+      def build_claude_mcp_config(mcp_servers)
+        servers = {}
+        mcp_servers.each do |server|
+          h = if server.stdio?
+            entry = {command: server.command.first}
+            remaining_args = server.command[1..] + server.args
+            entry[:args] = remaining_args unless remaining_args.empty?
+            entry
+          else
+            {url: server.url}
+          end
+          h[:env] = server.env unless server.env.empty?
+          servers[server.name] = h
+        end
+        {mcpServers: servers}
+      end
+
+      def cleanup_mcp_tempfiles!
+        if @mcp_config_tempfiles
+          @mcp_config_tempfiles.each do |file|
+            file.close unless file.closed?
+            file.unlink
+          rescue
+            nil
+          end
+          @mcp_config_tempfiles = nil
+        end
+
+        if @mcp_docker_config_paths
+          @mcp_docker_config_paths.each do |path|
+            @executor.execute(["rm", "-f", path], timeout: 5)
+          rescue
+            nil
+          end
+          @mcp_docker_config_paths = nil
+        end
+      end
+
       def log_debug(action, **context)
         @logger&.debug("[AgentHarness::Anthropic] #{action}: #{context.inspect}")
       end

data/lib/agent_harness/providers/base.rb

@@ -63,6 +63,10 @@ module AgentHarness
       def send_message(prompt:, **options)
         log_debug("send_message_start", prompt_length: prompt.length, options: options.keys)
 
+        # Normalize and validate MCP servers
+        options = normalize_mcp_servers(options)
+        validate_mcp_servers!(options[:mcp_servers]) if options[:mcp_servers]&.any?
+
         # Build command
         command = build_command(prompt, options)
 
@@ -83,6 +87,8 @@ module AgentHarness
         log_debug("send_message_complete", duration: duration, tokens: response.tokens)
 
         response
+      rescue McpConfigurationError, McpUnsupportedError, McpTransportUnsupportedError
+        raise
       rescue => e
         handle_error(e, prompt: prompt, options: options)
       end
@@ -145,6 +151,38 @@ module AgentHarness
 
       private
 
+      def normalize_mcp_servers(options)
+        servers = options[:mcp_servers]
+        return options if servers.nil?
+
+        unless servers.is_a?(Array)
+          raise McpConfigurationError,
+            "mcp_servers must be an Array of Hash or McpServer, got #{servers.class}"
+        end
+
+        return options if servers.empty?
+
+        normalized = servers.map do |server|
+          if server.is_a?(McpServer)
+            server
+          elsif server.is_a?(Hash)
+            McpServer.from_hash(server)
+          else
+            raise McpConfigurationError, "MCP server must be a Hash or McpServer, got #{server.class}"
+          end
+        end
+
+        # Ensure MCP server names are unique to avoid silent overwrites downstream
+        names = normalized.map(&:name)
+        duplicate_names = names.group_by { |n| n }.select { |_, v| v.size > 1 }.keys
+        unless duplicate_names.empty?
+          raise McpConfigurationError,
+            "Duplicate MCP server names detected: #{duplicate_names.join(", ")}"
+        end
+
+        options.merge(mcp_servers: normalized)
+      end
+
       def execute_with_timeout(command, timeout:, env:)
         @executor.execute(command, timeout: timeout, env: env)
       end

data/lib/agent_harness/providers/cursor.rb

@@ -109,6 +109,14 @@ module AgentHarness
         true
       end
 
+      # Cursor supports MCP for fetching existing server configurations (via
+      # fetch_mcp_servers) but does not support injecting request-time MCP
+      # servers into CLI invocations. Returning an empty list causes
+      # validate_mcp_servers! to raise McpUnsupportedError with a clear message.
+      def supported_mcp_transports
+        []
+      end
+
       def fetch_mcp_servers
         # Try CLI first, then config file
         fetch_mcp_servers_cli || fetch_mcp_servers_config
@@ -142,6 +150,10 @@ module AgentHarness
       def send_message(prompt:, **options)
         log_debug("send_message_start", prompt_length: prompt.length, options: options.keys)
 
+        # Normalize and validate MCP servers (same as Base#send_message)
+        options = normalize_mcp_servers(options)
+        validate_mcp_servers!(options[:mcp_servers]) if options[:mcp_servers]&.any?
+
         # Build command (without prompt in args - we send via stdin)
         command = [self.class.binary_name, "-p"]
 
@@ -162,6 +174,8 @@ module AgentHarness
         log_debug("send_message_complete", duration: duration)
 
         response
+      rescue McpConfigurationError, McpUnsupportedError, McpTransportUnsupportedError
+        raise
       rescue => e
         handle_error(e, prompt: prompt, options: options)
       end

data/lib/agent_harness/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AgentHarness
-  VERSION = "0.5.3"
+  VERSION = "0.5.4"
 end

data/lib/agent_harness.rb

@@ -137,6 +137,7 @@ end
 
 # Core components
 require_relative "agent_harness/errors"
+require_relative "agent_harness/mcp_server"
 require_relative "agent_harness/configuration"
 require_relative "agent_harness/command_executor"
 require_relative "agent_harness/docker_command_executor"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: agent-harness
 version: !ruby/object:Gem::Version
-  version: 0.5.3
+  version: 0.5.4
 platform: ruby
 authors:
 - Bart Agapinan
@@ -84,6 +84,7 @@ files:
 - lib/agent_harness/docker_command_executor.rb
 - lib/agent_harness/error_taxonomy.rb
 - lib/agent_harness/errors.rb
+- lib/agent_harness/mcp_server.rb
 - lib/agent_harness/orchestration/circuit_breaker.rb
 - lib/agent_harness/orchestration/conductor.rb
 - lib/agent_harness/orchestration/health_monitor.rb