omni_agent 0.1.9 → 0.1.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 66c390e526b0bd6176f8755538304d0e0e99d9cc36627be1ee9b63119b53ce34
-  data.tar.gz: 4918452fbba6d30772abbf9d072d0c16cf363d5220a099183e9caa04d7481220
+  metadata.gz: bc288d35e0b6c6e5e4ea763c36d05aa37ee95d20aeb2f4b1369e15a6ba22bc92
+  data.tar.gz: 428b4d96e1b1f7ad2bf1f7cd2c99893333c0eac59d2add9a94faf18198376baa
 SHA512:
-  metadata.gz: 522e4be90a757a9056e95cf45f5aafb1f18d7b6914e1ca667e32b3774ab70422f552e333ac2e340c4d1dab1c628350e04d494a9726b908467eb53723ae300dd6
-  data.tar.gz: c2c7939747237e554df0ac2569b84e36b164c1235f75fa876f04518cb644ad02579e18f4ee168c53ff55f32b75c8a58284ff921b217eda4b9148f67a8d5e4de7
+  metadata.gz: 9c55eaf9a31782bb1c16c152d15627943cef09f5a179c6039590b412dba505196aae36ed325905992bd26df567c74553a83fec629c59062c2cfa5d4981a03bf4
+  data.tar.gz: 904fdc44a855a5b7cfe66817cd531cc86bd44d5a8f8bccd6b97c6bf3d313a4b4e4a7a2f18fb18305bf5ae5be4bca7424562c1e39f77ecbb12ee63bea4d00fcf3

data/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.1.11](https://github.com/ACR1209/omni_agent/compare/omni_agent/v0.1.10...omni_agent/v0.1.11) (2026-10-15)
+
+
+### Features
+
+* **mcp:** add OAuth 2.1 authentication per the MCP authorization spec ([160c3d4](https://github.com/ACR1209/omni_agent/commit/160c3d47fb70272c58162359296c795a03b52219))
+
+
+### Bug Fixes
+
+* **mcp:** stop blocking requests while fetching the JWKS ([5074eb2](https://github.com/ACR1209/omni_agent/commit/5074eb2d939b2c1d6c365b15482cc9024f361527))
+
+## [0.1.10](https://github.com/ACR1209/omni_agent/compare/omni_agent/v0.1.9...omni_agent/v0.1.10) (2026-10-09)
+
+
+### Features
+
+* **mcp:** expose tools and agents as MCP servers ([#40](https://github.com/ACR1209/omni_agent/issues/40)) ([db8dcb8](https://github.com/ACR1209/omni_agent/commit/db8dcb8776cc0baaed45112b61bc329f03d32181))
+
 ## [0.1.9](https://github.com/ACR1209/omni_agent/compare/omni_agent/v0.1.8...omni_agent/v0.1.9) (2026-07-12)
 
 

data/README.md

@@ -12,6 +12,7 @@ tool schemas, and generation lifecycle callbacks.
 - Agent callbacks (`before_generation`, `after_generation`)
 - Agent and tool tags to support filtering strategies
 - OpenAI provider integration out of the box, plus an Ollama provider for local models
+- MCP server support: expose tools and whole agents to Claude Code, Claude Desktop, Cursor and other MCP clients
 - Rake tasks and Rails generators for scaffolding
 
 ## Installation
@@ -240,6 +241,55 @@ There's also an equivalent `rake omni_agent:eval` task (`rake "omni_agent:eval[p
 
 Calls real LLM providers (cost, non-determinism) — deliberately **not** part of `bundle exec rspec` or CI.
 
+## MCP Servers
+
+Expose your tools (and whole agents) to MCP clients such as Claude Code, Claude Desktop and Cursor. The protocol is implemented natively; no extra gem is needed.
+
+```bash
+rails generate omni_agent:mcp_server Support --with-tools LookupOrder --agents SupportAgent
+```
+
+```ruby
+# app/mcp_servers/support_server.rb
+class SupportServer < OmniAgent::MCP::Server
+	instructions "Tools for the support team."
+
+	# Tools in app/mcp_servers/support_server/tools/ (SupportServer::Tools::*) are added automatically.
+	# Reuse existing tools and agents too:
+	tools ResearchAgent::Tools::GetWeather
+	tools_from SupportAgent
+	expose_agent ResearchAgent, as: :research, description: "Ask the research agent", forward: [ :current_user ]
+
+	authenticate :bearer, tokens: -> { ENV.fetch("SUPPORT_MCP_TOKENS", "").split(",") }
+	# or: authenticate { |request| User.find_by(api_token: request.bearer_token) }
+	# or OAuth 2.1 (MCP authorization spec), with tokens from your authorization server:
+	# authenticate :oauth, resource: "https://app.example.com/mcp/support",
+	#                      authorization_servers: "https://auth.example.com",
+	#                      jwks_uri: "https://auth.example.com/.well-known/jwks.json"
+
+	authorize_tool { |tool_class, principal| !tool_class.tags.include?(:admin) }
+	context { |principal, _request| { current_user: principal } }
+end
+```
+
+```ruby
+# config/routes.rb -- Streamable HTTP (stateless, POST only)
+mcp_server :support                        # SupportServer at /mcp/support
+mcp_server :billing, path: "/internal/mcp"
+# or mount every server in app/mcp_servers at /mcp/<name>:
+mcp_servers
+```
+
+```bash
+# stdio, for local clients
+bundle exec omni_agent mcp SupportServer
+
+claude mcp add --transport http support http://localhost:3000/mcp/support --header "Authorization: Bearer $TOKEN"
+claude mcp add support -- bundle exec omni_agent mcp SupportServer
+```
+
+Tools can declare MCP-only hints with `title "Get weather"` and `annotations read_only: true, destructive: false, idempotent: true, open_world: true`. HTTP servers must declare `authenticate` (use `authenticate :none` to opt out on purpose). Requests from browser origins that are not in `allowed_origins` / `config.mcp_allowed_origins` are rejected.
+
 ## Configuration
 
 Global defaults can be configured through `OmniAgent.configure`:

data/exe/omni_agent

@@ -5,10 +5,21 @@ require "optparse"
 
 options = { fresh: false }
 parser = OptionParser.new do |opts|
-  opts.banner = "Usage: omni_agent eval [pattern] [options]"
+  opts.banner = <<~BANNER
+    Usage: omni_agent eval [pattern] [options]
+           omni_agent mcp <ServerClass>
+  BANNER
   opts.on("--fresh", "Clear the eval cache before running") { options[:fresh] = true }
 end
 
+def require_rails_environment(command)
+  environment_file = File.expand_path("config/environment", Dir.pwd)
+  unless File.exist?("#{environment_file}.rb")
+    abort "Could not find config/environment.rb -- run `omni_agent #{command}` from your Rails app root."
+  end
+  require environment_file
+end
+
 command = ARGV.shift
 
 case command
@@ -16,11 +27,7 @@ when "eval"
   parser.parse!(ARGV)
   pattern = ARGV.shift
 
-  environment_file = File.expand_path("config/environment", Dir.pwd)
-  unless File.exist?("#{environment_file}.rb")
-    abort "Could not find config/environment.rb -- run `omni_agent eval` from your Rails app root."
-  end
-  require environment_file
+  require_rails_environment("eval")
 
   status = OmniAgent::Eval::CLI.run(pattern: pattern, fresh: options[:fresh])
 
@@ -32,6 +39,15 @@ when "eval"
   when :failed
     exit 1
   end
+when "mcp"
+  server = ARGV.shift.to_s.strip
+  if server.empty?
+    warn "Missing server class. Example: omni_agent mcp SupportServer"
+    exit 1
+  end
+
+  require_rails_environment("mcp")
+  OmniAgent::MCP::Stdio.start(server)
 when nil
   warn parser.banner
   exit 1

data/lib/generators/omni_agent/agent/agent_generator.rb

@@ -7,6 +7,7 @@ module OmniAgent
       class_option :with_tools,
                    type: :array,
                    default: nil,
+                   lazy_default: [],
                    banner: "[Tool1 Tool2 ...]",
                    desc: "Create tools folder and scaffold tools. Optionally pass tool names"
       class_option :model,

data/lib/generators/omni_agent/install/install_generator.rb

@@ -15,6 +15,7 @@ module OmniAgent
       def show_next_steps
         say "OmniAgent install complete."
         say "Next: rails generate omni_agent:agent SupportAgent --with-tools Tool1 Tool2"
+        say "Expose tools to MCP clients: rails generate omni_agent:mcp_server Support --agents SupportAgent"
       end
     end
   end

data/lib/generators/omni_agent/mcp_server/mcp_server_generator.rb

@@ -0,0 +1,155 @@
+require "rails/generators/named_base"
+
+module OmniAgent
+  module Generators
+    class McpServerGenerator < Rails::Generators::NamedBase
+      desc "Creates an OmniAgent MCP server in app/mcp_servers and mounts it in config/routes.rb"
+
+      class_option :with_tools,
+                   type: :array,
+                   default: nil,
+                   lazy_default: [],
+                   banner: "[Tool1 Tool2 ...]",
+                   desc: "Scaffold server-local tools in app/mcp_servers/<name>_server/tools. Optionally pass tool names"
+      class_option :tools,
+                   type: :array,
+                   default: [],
+                   banner: "[ResearchAgent::Tools::GetWeather ...]",
+                   desc: "Existing tool classes to expose"
+      class_option :agents,
+                   type: :array,
+                   default: [],
+                   banner: "[ResearchAgent ...]",
+                   desc: "Agents whose tools are all exposed (tools_from)"
+      class_option :path,
+                   type: :string,
+                   default: nil,
+                   desc: "Mount path for the HTTP endpoint (default: /mcp/<name>)"
+
+      def create_server_file
+        create_file(File.join("app", "mcp_servers", "#{server_file_name}.rb"), server_template)
+      end
+
+      def create_tools_if_requested
+        return if options[:with_tools].nil?
+
+        requested_tool_names.each do |tool_name|
+          create_file(File.join("app", "mcp_servers", server_file_name, "tools", "#{tool_name.underscore}.rb"), tool_template(tool_name))
+        end
+      end
+
+      def mount_route
+        if mounts_all_servers?
+          say_status :skip, "config/routes.rb already mounts every server with `mcp_servers`", :yellow
+          return
+        end
+
+        route_line = "mcp_server #{server_slug.include?('/') ? server_slug.inspect : ":#{server_slug}"}"
+        route_line += %(, path: "#{options[:path]}") if options[:path].present?
+        route route_line
+      end
+
+      def show_next_steps
+        say ""
+        say "MCP server #{server_class_name} created."
+        say ""
+        say "Set a token, start the app and connect Claude Code over HTTP:"
+        say "  #{token_env_var}=change-me bin/rails server"
+        say "  claude mcp add --transport http #{server_identifier} http://localhost:3000#{mount_path} --header \"Authorization: Bearer change-me\""
+        say ""
+        say "Or run it locally over stdio (no HTTP auth; see stdio_principal):"
+        say "  claude mcp add #{server_identifier} -- bundle exec omni_agent mcp #{server_class_name}"
+      end
+
+      private
+
+      def server_class_name
+        class_name.end_with?("Server") ? class_name : "#{class_name}Server"
+      end
+
+      def server_file_name
+        server_class_name.underscore
+      end
+
+      def server_slug
+        OmniAgent::MCP::Routing.slug_for(server_class_name)
+      end
+
+      def server_identifier
+        server_slug.tr("/", "_")
+      end
+
+      def mount_path
+        options[:path].presence || "#{OmniAgent::MCP::Routing::DEFAULT_PATH_PREFIX}/#{server_slug.dasherize}"
+      end
+
+      def mounts_all_servers?
+        routes_file = File.join(destination_root, "config", "routes.rb")
+        File.exist?(routes_file) && File.read(routes_file).match?(/^\s*mcp_servers\s*(\(\s*\)|except:.*)?\s*$/)
+      end
+
+      def token_env_var
+        "#{server_identifier.upcase}_MCP_TOKENS"
+      end
+
+      def server_template
+        <<~RUBY
+          class #{server_class_name} < OmniAgent::MCP::Server
+            instructions "Tools exposed by #{server_class_name}."
+
+          #{tool_lines.map { |line| "  #{line}" }.join("\n")}
+
+            # Comma-separated list of accepted bearer tokens.
+            authenticate :bearer, tokens: -> { ENV.fetch("#{token_env_var}", "").split(",") }
+            # Or OAuth 2.1 with tokens from your authorization server (add `gem "jwt"`):
+            # authenticate :oauth, resource: "https://app.example.com/mcp/...",
+            #                      authorization_servers: "https://auth.example.com",
+            #                      jwks_uri: "https://auth.example.com/.well-known/jwks.json"
+
+            # Hide tools per principal:
+            # authorize_tool { |tool_class, principal| true }
+
+            # Extra values merged into each tool's `context`:
+            # context { |principal, request| { current_user: principal } }
+          end
+        RUBY
+      end
+
+      def requested_tool_names
+        names = Array(options[:with_tools]).map(&:strip).reject(&:empty?)
+        names.empty? ? [ "ExampleTool" ] : names.map(&:camelize)
+      end
+
+      def tool_template(tool_name)
+        <<~RUBY
+          module #{server_class_name}::Tools
+            class #{tool_name} < OmniAgent::Tool
+              description "#{tool_name} generated by omni_agent:mcp_server"
+              annotations read_only: true
+
+              input do
+                string :input_text, description: "Text input"
+              end
+
+              def execute(input_text:)
+                "Echo: \#{input_text}"
+              end
+            end
+          end
+        RUBY
+      end
+
+      def tool_lines
+        tools = Array(options[:tools]).map(&:strip).reject(&:empty?)
+        agents = Array(options[:agents]).map(&:strip).reject(&:empty?)
+
+        lines = []
+        lines << "tools #{tools.join(', ')}" if tools.any?
+        lines.concat(agents.map { |agent| "tools_from #{agent}" })
+        lines.unshift("# Tools in app/mcp_servers/#{server_file_name}/tools/ are added automatically.")
+        lines << "# tools SomeAgent::Tools::SomeTool" if tools.empty? && agents.empty?
+        lines
+      end
+    end
+  end
+end

data/lib/omni_agent/agent.rb

@@ -99,6 +99,38 @@ module OmniAgent
         @delegated_tool_classes || []
       end
 
+      def tool_classes
+        tool_namespace = "#{name}::Tools".safe_constantize
+
+        namespace_tools = if tool_namespace
+          tool_namespace.constants.filter_map do |const_name|
+            const = tool_namespace.const_get(const_name)
+            const if const.is_a?(Class) && const < OmniAgent::Tool
+          end
+        else
+          []
+        end
+
+        namespace_tools + configured_delegated_tool_classes
+      end
+
+      def build_delegated_tool_class(agent_class, description:, run_alias:, forward:)
+        tool_description = description || "Delegate to #{agent_class.name}."
+
+        Class.new(OmniAgent::Tool) do
+          description tool_description
+
+          input do
+            string :input, description: "Input/question to send to the delegated agent."
+          end
+
+          define_method(:execute) do |input:|
+            forwarded_context = OmniAgent::Agent.__send__(:filter_forwarded_context, context, forward)
+            OmniAgent::Agent.__send__(:run_delegated_agent, agent_class, input, run_alias, forwarded_context)
+          end
+        end
+      end
+
       def with(context = nil, provider_override: nil, model_override: nil, options_override: {}, **context_keywords)
         merged_context = {}
         merged_context.merge!(context) if context.is_a?(Hash)
@@ -135,23 +167,6 @@ module OmniAgent
         as.to_s.split(/[_\s]+/).reject(&:empty?).map { |part| part[0].upcase + part[1..] }.join
       end
 
-      def build_delegated_tool_class(agent_class, description:, run_alias:, forward:)
-        tool_description = description || "Delegate to #{agent_class.name}."
-
-        Class.new(OmniAgent::Tool) do
-          description tool_description
-
-          input do
-            string :input, description: "Input/question to send to the delegated agent."
-          end
-
-          define_method(:execute) do |input:|
-            forwarded_context = OmniAgent::Agent.__send__(:filter_forwarded_context, context, forward)
-            OmniAgent::Agent.__send__(:run_delegated_agent, agent_class, input, run_alias, forwarded_context)
-          end
-        end
-      end
-
       def filter_forwarded_context(context, forward)
         return {} unless context.is_a?(Hash)
         return context.dup if forward == true
@@ -316,18 +331,7 @@ module OmniAgent
     end
 
     def available_tools
-      tool_namespace = "#{self.class.name}::Tools".safe_constantize
-
-      namespace_tools = if tool_namespace
-        tool_namespace.constants.filter_map do |const_name|
-          const = tool_namespace.const_get(const_name)
-          const if const.is_a?(Class) && const < OmniAgent::Tool
-        end
-      else
-        []
-      end
-
-      namespace_tools + self.class.configured_delegated_tool_classes
+      self.class.tool_classes
     end
 
     private

data/lib/omni_agent/configuration.rb

@@ -1,7 +1,8 @@
 module OmniAgent
   class Configuration
     attr_accessor :default_provider, :default_model, :max_retries, :retry_base_delay, :max_tool_iterations,
-                  :max_delegation_depth, :eval_judge_provider, :eval_judge_model, :eval_cache_enabled, :eval_cache_path
+                  :max_delegation_depth, :eval_judge_provider, :eval_judge_model, :eval_cache_enabled, :eval_cache_path,
+                  :mcp_allowed_origins, :mcp_max_request_bytes
 
     def initialize
       @default_provider = :openai
@@ -14,6 +15,8 @@ module OmniAgent
       @eval_judge_model = nil
       @eval_cache_enabled = true
       @eval_cache_path = "tmp/omni_agent_eval_cache.json"
+      @mcp_allowed_origins = []
+      @mcp_max_request_bytes = 1_048_576
     end
   end
 end

data/lib/omni_agent/engine.rb

@@ -1,5 +1,9 @@
 module OmniAgent
   class Engine < ::Rails::Engine
     isolate_namespace OmniAgent
+
+    initializer "omni_agent.mcp_routing" do
+      ActionDispatch::Routing::Mapper.include(OmniAgent::MCP::Routing)
+    end
   end
 end

data/lib/omni_agent/errors.rb

@@ -6,6 +6,7 @@ module OmniAgent
     class MaxToolIterationsError < Error; end
     class MaxDelegationDepthError < Error; end
     class EvalAssertionError < Error; end
+    class MCPError < Error; end
   end
 
   Error = Errors::Error
@@ -14,4 +15,5 @@ module OmniAgent
   MaxToolIterationsError = Errors::MaxToolIterationsError
   MaxDelegationDepthError = Errors::MaxDelegationDepthError
   EvalAssertionError = Errors::EvalAssertionError
+  MCPError = Errors::MCPError
 end

data/lib/omni_agent/mcp/authenticator.rb

@@ -0,0 +1,85 @@
+require "active_support/security_utils"
+
+module OmniAgent
+  module MCP
+    class Authenticator
+      # error and access_token are only set by `authenticate :oauth`.
+      Result = Struct.new(:authenticated, :principal, :error, :access_token) do
+        def authenticated?
+          authenticated == true
+        end
+      end
+
+      ARRAY_TOKEN_PRINCIPAL = :bearer_token
+
+      def initialize(server_class)
+        @server_class = server_class
+      end
+
+      def authenticate(request)
+        authentication = @server_class.configured_authentication
+
+        if authentication.nil?
+          raise OmniAgent::MCPError,
+                "#{@server_class.name} does not declare authentication. " \
+                "Add `authenticate :bearer, tokens: ...`, `authenticate :oauth, ...`, `authenticate { |request| ... }`, " \
+                "or explicitly opt out with `authenticate :none`."
+        end
+
+        case authentication[:strategy]
+        when :none
+          success(nil)
+        when :bearer
+          authenticate_bearer(request, authentication[:tokens])
+        when :oauth
+          authentication[:resource_server].authenticate(request)
+        when :custom
+          principal = authentication[:block].call(request)
+          principal ? success(principal) : failure
+        end
+      end
+
+      private
+
+      def authenticate_bearer(request, tokens)
+        presented = request.bearer_token
+        return failure if presented.nil?
+
+        matched = false
+        principal = nil
+
+        # Compare against every configured token (no early exit) so response
+        # timing does not reveal which token, or how many tokens, matched.
+        token_candidates(tokens).each do |candidate_principal, token|
+          next if token.nil? || token.to_s.empty?
+
+          if ActiveSupport::SecurityUtils.secure_compare(token.to_s, presented) && !matched
+            matched = true
+            principal = candidate_principal
+          end
+        end
+
+        matched ? success(principal) : failure
+      end
+
+      def token_candidates(tokens)
+        tokens = tokens.call if tokens.respond_to?(:call)
+
+        case tokens
+        when Hash
+          tokens.map { |principal, token| [ principal, token ] }
+        else
+          Array(tokens).map { |token| [ ARRAY_TOKEN_PRINCIPAL, token ] }
+        end
+      end
+
+      def success(principal)
+        Result.new(true, principal)
+      end
+
+      def failure
+        Result.new(false, nil)
+      end
+    end
+  end
+end

data/lib/omni_agent/mcp/handler.rb

@@ -0,0 +1,128 @@
+module OmniAgent
+  module MCP
+    class Handler
+      class ProtocolError < StandardError
+        attr_reader :code
+
+        def initialize(code, message)
+          super(message)
+          @code = code
+        end
+      end
+
+      def initialize(server)
+        @server = server
+      end
+
+      # Takes a parsed JSON-RPC message and returns the response Hash, or nil
+      # when no response is due (notifications and client responses).
+      def call(message)
+        unless message.is_a?(Hash)
+          reason = message.is_a?(Array) ? "Batch requests are not supported" : "Invalid Request"
+          return error_response(nil, INVALID_REQUEST, reason)
+        end
+
+        message = message.transform_keys(&:to_s)
+        return nil if client_response?(message)
+
+        id = message["id"]
+        notification = !message.key?("id")
+
+        unless message["jsonrpc"] == JSONRPC_VERSION && message["method"].is_a?(String)
+          return notification ? nil : error_response(id, INVALID_REQUEST, "Invalid Request")
+        end
+
+        return nil if notification
+
+        result = dispatch(message["method"], message["params"])
+        success_response(id, result)
+      rescue ProtocolError => e
+        error_response(id, e.code, e.message)
+      rescue StandardError => e
+        log_error("MCP internal error", e)
+        error_response(id, INTERNAL_ERROR, "Internal error")
+      end
+
+      private
+
+      attr_reader :server
+
+      def dispatch(method, params)
+        params = normalize_params(params)
+
+        case method
+        when "initialize" then initialize_result(params)
+        when "ping" then {}
+        when "tools/list" then tools_list_result
+        when "tools/call" then tools_call_result(params)
+        else
+          raise ProtocolError.new(METHOD_NOT_FOUND, "Method not found: #{method}")
+        end
+      end
+
+      def normalize_params(params)
+        return {} if params.nil?
+        raise ProtocolError.new(INVALID_PARAMS, "params must be an object") unless params.is_a?(Hash)
+
+        params.transform_keys(&:to_s)
+      end
+
+      def initialize_result(params)
+        requested = params["protocolVersion"]
+        protocol_version = SUPPORTED_PROTOCOL_VERSIONS.include?(requested) ? requested : LATEST_PROTOCOL_VERSION
+        server_class = server.class
+
+        result = {
+          protocolVersion: protocol_version,
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: { name: server_class.server_name, version: server_class.server_version }
+        }
+        result[:instructions] = server_class.instructions if server_class.instructions
+        result
+      end
+
+      def tools_list_result
+        tools = server.visible_tools.map { |name, tool_class| ToolAdapter.definition(name, tool_class) }
+        { tools: tools }
+      end
+
+      def tools_call_result(params)
+        name = params["name"]
+        raise ProtocolError.new(INVALID_PARAMS, "Missing tool name") unless name.is_a?(String)
+
+        tool_class = server.find_tool(name)
+        raise ProtocolError.new(INVALID_PARAMS, "Unknown tool: #{name}") unless tool_class
+
+        arguments = params["arguments"] || {}
+        raise ProtocolError.new(INVALID_PARAMS, "arguments must be an object") unless arguments.is_a?(Hash)
+
+        execute_tool(name, tool_class, arguments)
+      end
+
+      def execute_tool(name, tool_class, arguments)
+        tool = tool_class.new
+        tool.context = server.tool_context
+        ToolAdapter.result(tool.invoke(arguments))
+      rescue StandardError => e
+        log_error("MCP tool #{name} failed", e)
+        ToolAdapter.error_result("Error executing tool: #{e.message}")
+      end
+
+      def client_response?(message)
+        !message.key?("method") && (message.key?("result") || message.key?("error"))
+      end
+
+      def success_response(id, result)
+        { jsonrpc: JSONRPC_VERSION, id: id, result: result }
+      end
+
+      def error_response(id, code, message)
+        { jsonrpc: JSONRPC_VERSION, id: id, error: { code: code, message: message } }
+      end
+
+      def log_error(prefix, error)
+        MCP.logger&.error("[OmniAgent::MCP] #{prefix}: #{error.class}: #{error.message}")
+      end
+    end
+  end
+end