riffer 0.26.0 → 0.27.0

data/lib/riffer/mcp/registration.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Per-server state managed by Riffer::Mcp::Registry.
+#
+# Created when a server is registered. Discovers tools via the MCP
+# +tools/list+ call, then generates tool classes.
+#
+class Riffer::Mcp::Registration
+  # The manifest that describes this server.
+  attr_reader :manifest #: Riffer::Mcp::Manifest
+
+  # Generated Riffer::Tool subclasses.
+  #
+  #--
+  #: () -> Array[singleton(Riffer::Tool)]
+  def tools
+    @mutex.synchronize { @tools }
+  end
+
+  #--
+  #: (Riffer::Mcp::Manifest) -> void
+  def initialize(manifest)
+    @manifest = manifest
+    @cancelled = false
+    @tools = []
+    @mutex = Mutex.new
+    run_discovery
+  end
+
+  # Retires this registration, preventing in-flight discovery from publishing
+  # state.
+  #
+  #--
+  #: () -> void
+  def retire!
+    @mutex.synchronize { @cancelled = true }
+  end
+
+  # Returns true if this registration has been retired.
+  #
+  #--
+  #: () -> bool
+  def retired?
+    @mutex.synchronize { @cancelled }
+  end
+
+  private
+
+  # Runs tool discovery using the configured Runner.
+  #
+  # With +Runner::Sequential+ (default) discovery blocks inline. With
+  # +Runner::Threaded+ discovery runs on a pool thread but +map+ still
+  # blocks the caller — useful for Rails connection-pool isolation.
+  #
+  #--
+  #: () -> void
+  def run_discovery
+    Riffer.config.mcp.discovery_runner.map([nil], context: nil) do |_|
+      client = build_client
+      tool_defs = client.tools_list
+      tools = Riffer::Mcp::ToolFactory.build(@manifest.name, client, tool_defs)
+
+      @mutex.synchronize do
+        next if @cancelled
+        @tools = tools.freeze
+      end
+    end
+  end
+
+  #--
+  #: () -> Riffer::Mcp::Client
+  def build_client
+    Riffer::Mcp::Client.new(endpoint: @manifest.endpoint, headers: @manifest.discovery_headers || {})
+  end
+end

data/lib/riffer/mcp/registry.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Thread-safe global store for MCP server registrations.
+#
+# Keyed by manifest name. All public methods are mutex-guarded.
+#
+module Riffer::Mcp::Registry
+  @mutex = Mutex.new
+  @store = {} #: Hash[String, Riffer::Mcp::Registration]
+
+  class << self
+    # Registers an MCP server and starts async tool discovery.
+    #
+    # Accepts a Manifest instance or a hash of manifest keyword arguments.
+    # Replaces any existing registration with the same name.
+    #
+    #--
+    #: ((Hash[Symbol, untyped] | Riffer::Mcp::Manifest)) -> Riffer::Mcp::Registration
+    def register(manifest_or_hash)
+      manifest = manifest_or_hash.is_a?(Riffer::Mcp::Manifest) ? manifest_or_hash : Riffer::Mcp::Manifest.new(**manifest_or_hash)
+      registration = Riffer::Mcp::Registration.new(manifest)
+      old = @mutex.synchronize do
+        previous = @store[manifest.name]
+        @store[manifest.name] = registration
+        previous
+      end
+      old&.retire!
+      registration
+    end
+
+    # Removes a registration by name.
+    #
+    #--
+    #: ((String | Symbol)) -> void
+    def unregister(name)
+      removed = @mutex.synchronize { @store.delete(name.to_s) }
+      removed&.retire!
+    end
+
+    # Returns a frozen snapshot of all current registrations.
+    #
+    #--
+    #: () -> Hash[String, Riffer::Mcp::Registration]
+    def registrations
+      @mutex.synchronize { @store.dup.freeze }
+    end
+
+    # Returns all registrations whose manifest tags intersect with the given tags.
+    #
+    # Tags are normalized to symbols before matching.
+    #
+    #--
+    #: (Array[Symbol]) -> Array[Riffer::Mcp::Registration]
+    def find_by_tags(tags)
+      normalized = tags.map(&:to_sym)
+      @mutex.synchronize do
+        @store.values.select { |reg| (reg.manifest.tags & normalized).any? }
+      end
+    end
+  end
+end

data/lib/riffer/mcp/tool_factory.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Generates anonymous Riffer::Tool subclasses from MCP tool definitions.
+#
+# Each generated class:
+# - Has +.name+, +.description+, and +.parameters_schema+ derived from the MCP tool definition.
+# - Delegates +#call+ to the MCP client's +tools_call+ method.
+# - Skips Riffer's param validation — the MCP server validates inputs.
+#
+module Riffer::Mcp::ToolFactory
+  # Builds one Riffer::Tool subclass per tool definition.
+  #
+  # Tool names are prefixed with the manifest name to avoid collisions
+  # across MCP servers (e.g. +"jira__search"+). The original server-side
+  # name is available via +.mcp_server_tool_name+.
+  #
+  #--
+  #: (String, Riffer::Mcp::Client, Array[Hash[Symbol, untyped]]) -> Array[singleton(Riffer::Tool)]
+  def self.build(manifest_name, client, tool_defs)
+    tool_defs.map { |td| build_tool_class(manifest_name, client, td) }
+  end
+
+  # Replaces characters that are unsafe in LLM tool names.
+  #: (String) -> String
+  def self.sanitize_name_component(str)
+    str.gsub(/[^a-zA-Z0-9_-]/, "_")
+  end
+  private_class_method :sanitize_name_component
+
+  private_class_method def self.build_tool_class(manifest_name, client, td)
+    prefixed = "#{sanitize_name_component(manifest_name)}__#{sanitize_name_component(td[:name])}"
+
+    Class.new(Riffer::Tool) do
+      @mcp_client = client
+      @mcp_server_tool_name = td[:name]
+      # Set @identifier directly so .identifier does not fall back to
+      # class_name_to_path(nil) on this anonymous class.
+      @identifier = prefixed
+
+      define_singleton_method(:name) { prefixed }
+      define_singleton_method(:mcp_server_tool_name) { td[:name] }
+      define_singleton_method(:description) { td[:description] }
+      define_singleton_method(:parameters_schema) { |strict: false| td[:input_schema] || Riffer::Tool.send(:empty_schema) }
+
+      define_method(:call) do |context:, **kwargs|
+        result = self.class.instance_variable_get(:@mcp_client).tools_call(
+          self.class.instance_variable_get(:@mcp_server_tool_name), kwargs
+        )
+        text(result)
+      end
+    end
+  end
+end

data/lib/riffer/mcp.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Riffer::Mcp provides integration with Model Context Protocol (MCP) servers.
+#
+# Register MCP servers globally; agents opt-in by tag via the +use_mcp+ DSL.
+# Tags are application-defined; see +docs/14_MCP.md+ (Tags section).
+#
+#   Riffer::Mcp.register(
+#     name: "github",
+#     tags: [:github],
+#     endpoint: "https://mcp.github.com",
+#     discovery_headers: -> { {"Authorization" => "Bearer #{ENV['GITHUB_TOKEN']}"} }
+#   )
+#
+#   class MyAgent < Riffer::Agent
+#     model "openai/gpt-4o"
+#     use_mcp :github
+#   end
+#
+module Riffer::Mcp
+  # Base error for all MCP-related failures.
+  class Error < Riffer::Error; end
+
+  # Raised when +Riffer.config.mcp.credentials+ returns +nil+ during +tools/call+
+  # after the server's tools were included for this run.
+  class CredentialsDeniedError < Error; end
+
+  # Registers an MCP server, blocking until tool discovery completes.
+  #
+  # Raises on discovery failure. Pass a +Manifest+ instance or a hash with
+  # the same keys.
+  #
+  #--
+  #: ((Hash[Symbol, untyped] | Riffer::Mcp::Manifest)) -> Riffer::Mcp::Registration
+  def self.register(manifest_or_hash)
+    Registry.register(manifest_or_hash)
+  end
+
+  # Removes a registration by name.
+  #
+  # Subsequent agent runs will not see tools from this server.
+  #
+  #--
+  #: (String) -> void
+  def self.unregister(name)
+    Registry.unregister(name)
+  end
+
+  # Returns all current registrations keyed by name (for introspection).
+  #
+  #--
+  #: () -> Hash[String, Riffer::Mcp::Registration]
+  def self.registrations
+    Registry.registrations
+  end
+end

data/lib/riffer/providers/anthropic.rb

@@ -150,30 +150,36 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
       **params,
       request_options: {extra_headers: {"accept-encoding" => "identity"}}
     )
-    current_state[:stream] = stream
-
-    stream.each do |event|
-      case event
-      when Anthropic::Models::RawContentBlockStartEvent
-        handle_raw_content_block_start(event, state: current_state)
-      when Anthropic::Models::RawContentBlockDeltaEvent
-        handle_raw_content_block_delta(event, state: current_state)
-      when Anthropic::Streaming::TextEvent
-        handle_text_event(event, state: current_state, yielder: yielder)
-      when Anthropic::Streaming::ThinkingEvent
-        handle_thinking_event(event, state: current_state, yielder: yielder)
-      when Anthropic::Streaming::InputJsonEvent
-        handle_input_json_event(event, state: current_state, yielder: yielder)
-      when Anthropic::Streaming::ContentBlockStopEvent
-        block_type = event.content_block&.type.to_s
-        handle_content_block_stop_text(event, state: current_state, yielder: yielder) if block_type == "text" && current_state[:text]
-        handle_content_block_stop_tool_use(event, state: current_state, yielder: yielder) if block_type == "tool_use"
-        handle_content_block_stop_thinking(event, state: current_state, yielder: yielder) if block_type == "thinking" && current_state[:reasoning]
-        handle_content_block_stop_server_tool_use(event, state: current_state, yielder: yielder) if block_type == "server_tool_use"
-        handle_content_block_stop_web_search_result(event, state: current_state, yielder: yielder) if block_type == "web_search_tool_result"
-      when Anthropic::Streaming::MessageStopEvent
-        handle_message_stop(event, state: current_state, yielder: yielder)
+
+    begin
+      stream.each do |event|
+        case event
+        when Anthropic::Models::RawContentBlockStartEvent
+          handle_raw_content_block_start(event, state: current_state)
+        when Anthropic::Models::RawContentBlockDeltaEvent
+          handle_raw_content_block_delta(event, state: current_state)
+        when Anthropic::Streaming::TextEvent
+          handle_text_event(event, state: current_state, yielder: yielder)
+        when Anthropic::Streaming::ThinkingEvent
+          handle_thinking_event(event, state: current_state, yielder: yielder)
+        when Anthropic::Streaming::InputJsonEvent
+          handle_input_json_event(event, state: current_state, yielder: yielder)
+        when Anthropic::Streaming::ContentBlockStopEvent
+          block_type = event.content_block&.type.to_s
+          handle_content_block_stop_text(event, state: current_state, yielder: yielder) if block_type == "text" && current_state[:text]
+          handle_content_block_stop_tool_use(event, state: current_state, yielder: yielder) if block_type == "tool_use"
+          handle_content_block_stop_thinking(event, state: current_state, yielder: yielder) if block_type == "thinking" && current_state[:reasoning]
+          handle_content_block_stop_server_tool_use(event, state: current_state, yielder: yielder) if block_type == "server_tool_use"
+          handle_content_block_stop_web_search_result(event, state: current_state, yielder: yielder) if block_type == "web_search_tool_result"
+        when Anthropic::Streaming::MessageStopEvent
+          handle_message_stop(event, accumulated_message: stream.accumulated_message, yielder: yielder)
+        end
       end
+    ensure
+      # Anthropic SDK does not auto-close the underlying HTTP stream when
+      # iteration is interrupted (raise / fiber cancellation), so the SSE
+      # socket leaks until GC. close is idempotent and a no-op after EOF.
+      stream.close
     end
   end
 
@@ -280,20 +286,19 @@ class Riffer::Providers::Anthropic < Riffer::Providers::Base
   end
 
   #--
-  #: (untyped, state: Hash[Symbol, untyped], yielder: Enumerator::Yielder) -> void
-  def handle_message_stop(_event, state:, yielder:)
-    final_message = state[:stream].accumulated_message
-    if final_message&.usage
-      usage = final_message.usage
-      yielder << Riffer::StreamEvents::TokenUsageDone.new(
-        token_usage: Riffer::TokenUsage.new(
-          input_tokens: usage.input_tokens,
-          output_tokens: usage.output_tokens,
-          cache_creation_tokens: usage.cache_creation_input_tokens,
-          cache_read_tokens: usage.cache_read_input_tokens
-        )
+  #: (untyped, accumulated_message: Anthropic::Models::Message?, yielder: Enumerator::Yielder) -> void
+  def handle_message_stop(_event, accumulated_message:, yielder:)
+    usage = accumulated_message&.usage
+    return unless usage
+
+    yielder << Riffer::StreamEvents::TokenUsageDone.new(
+      token_usage: Riffer::TokenUsage.new(
+        input_tokens: usage.input_tokens,
+        output_tokens: usage.output_tokens,
+        cache_creation_tokens: usage.cache_creation_input_tokens,
+        cache_read_tokens: usage.cache_read_input_tokens
       )
-    end
+    )
   end
 
   #--

data/lib/riffer/providers/open_ai.rb

@@ -124,33 +124,40 @@ class Riffer::Providers::OpenAI < Riffer::Providers::Base
     }
 
     stream = @client.responses.stream(params)
-    stream.each do |event|
-      case event.type
-      when :"response.output_item.added"
-        handle_output_item_added_function_call(event, state: current_state, yielder: yielder) if event.item&.type == :function_call
-      when :"response.output_text.delta"
-        handle_output_text_delta(event, state: current_state, yielder: yielder)
-      when :"response.output_text.done"
-        handle_output_text_done(event, state: current_state, yielder: yielder)
-      when :"response.reasoning_summary_text.delta"
-        handle_reasoning_summary_text_delta(event, state: current_state, yielder: yielder)
-      when :"response.reasoning_summary_text.done"
-        handle_reasoning_summary_text_done(event, state: current_state, yielder: yielder)
-      when :"response.function_call_arguments.delta"
-        handle_function_call_arguments_delta(event, state: current_state, yielder: yielder)
-      when :"response.function_call_arguments.done"
-        handle_function_call_arguments_done(event, state: current_state, yielder: yielder)
-      when :"response.web_search_call.in_progress"
-        handle_web_search_status(event, status: "in_progress", yielder: yielder)
-      when :"response.web_search_call.searching"
-        handle_web_search_status(event, status: "searching", yielder: yielder)
-      when :"response.web_search_call.completed"
-        handle_web_search_status(event, status: "completed", yielder: yielder)
-      when :"response.output_item.done"
-        handle_output_item_done_web_search(event, yielder: yielder) if event.item&.type == :web_search_call
-      when :"response.completed"
-        handle_response_completed(event, state: current_state, yielder: yielder)
+    begin
+      stream.each do |event|
+        case event.type
+        when :"response.output_item.added"
+          handle_output_item_added_function_call(event, state: current_state, yielder: yielder) if event.item&.type == :function_call
+        when :"response.output_text.delta"
+          handle_output_text_delta(event, state: current_state, yielder: yielder)
+        when :"response.output_text.done"
+          handle_output_text_done(event, state: current_state, yielder: yielder)
+        when :"response.reasoning_summary_text.delta"
+          handle_reasoning_summary_text_delta(event, state: current_state, yielder: yielder)
+        when :"response.reasoning_summary_text.done"
+          handle_reasoning_summary_text_done(event, state: current_state, yielder: yielder)
+        when :"response.function_call_arguments.delta"
+          handle_function_call_arguments_delta(event, state: current_state, yielder: yielder)
+        when :"response.function_call_arguments.done"
+          handle_function_call_arguments_done(event, state: current_state, yielder: yielder)
+        when :"response.web_search_call.in_progress"
+          handle_web_search_status(event, status: "in_progress", yielder: yielder)
+        when :"response.web_search_call.searching"
+          handle_web_search_status(event, status: "searching", yielder: yielder)
+        when :"response.web_search_call.completed"
+          handle_web_search_status(event, status: "completed", yielder: yielder)
+        when :"response.output_item.done"
+          handle_output_item_done_web_search(event, yielder: yielder) if event.item&.type == :web_search_call
+        when :"response.completed"
+          handle_response_completed(event, state: current_state, yielder: yielder)
+        end
       end
+    ensure
+      # OpenAI SDK does not auto-close the underlying HTTP stream when
+      # iteration is interrupted (raise / fiber cancellation), so the SSE
+      # socket leaks until GC. close is idempotent and a no-op after EOF.
+      stream.close
     end
   end
 

data/lib/riffer/version.rb

@@ -2,5 +2,5 @@
 # rbs_inline: enabled
 
 module Riffer
-  VERSION = "0.26.0" #: String
+  VERSION = "0.27.0" #: String
 end

data/sig/generated/riffer/agent.rbs

@@ -113,6 +113,19 @@ class Riffer::Agent
   # : (Hash[Symbol, untyped]?) -> Array[singleton(Riffer::Tool)]
   def self.resolve_uses_tools_config: (Hash[Symbol, untyped]?) -> Array[singleton(Riffer::Tool)]
 
+  # Opts this agent into tools from all MCP registrations that share any of
+  # the given tag(s).
+  #
+  # +tag+ - a String or Symbol; matched against registration manifest tags.
+  #
+  # : (String | Symbol) -> void
+  def self.use_mcp: (String | Symbol) -> void
+
+  # Returns the accumulated +use_mcp+ configurations for this agent class.
+  #
+  # : () -> Array[Hash[Symbol, untyped]]
+  def self.mcp_configs: () -> Array[Hash[Symbol, untyped]]
+
   # Gets or sets the tool runtime for this agent.
   #
   # Accepts a Riffer::ToolRuntime subclass, a Riffer::ToolRuntime instance,
@@ -352,6 +365,26 @@ class Riffer::Agent
   def resolve_model: () -> String
 
   # --
+  # : () -> Array[singleton(Riffer::Tool)]
+  def resolve_uses_tools_config: () -> Array[singleton(Riffer::Tool)]
+
+  # --
+  # : () -> Array[singleton(Riffer::Tool)]
+  def resolve_mcp_tool_classes: () -> Array[singleton(Riffer::Tool)]
+
+  # Each matching MCP registration once, with tag symbols unioned across +use_mcp+ rows.
+  #
+  # : (Array[Hash[Symbol, untyped]]) -> Hash[Riffer::Mcp::Registration, Array[Symbol]]
+  def gather_mcp_registrations_with_tags: (Array[Hash[Symbol, untyped]]) -> Hash[Riffer::Mcp::Registration, Array[Symbol]]
+
+  # : (Riffer::Mcp::Registration, Array[Symbol], Proc?, Hash[Symbol, untyped]) -> Array[singleton(Riffer::Tool)]
+  def mcp_tools_for_registration: (Riffer::Mcp::Registration, Array[Symbol], Proc?, Hash[Symbol, untyped]) -> Array[singleton(Riffer::Tool)]
+
+  # Raises if two or more tool classes share the same +.name+ (ambiguous dispatch).
+  #
+  # : (Array[singleton(Riffer::Tool)]) -> void
+  def assert_distinct_tool_names!: (Array[singleton(Riffer::Tool)]) -> void
+
   # : () -> Array[singleton(Riffer::Tool)]
   def resolved_tools: () -> Array[singleton(Riffer::Tool)]
 

data/sig/generated/riffer/config.rbs

@@ -63,6 +63,15 @@ class Riffer::Config
                 | ({ ?judge_model: untyped }) -> instance
   end
 
+  class Mcp < Struct[untyped]
+    attr_accessor credentials(): untyped
+
+    attr_accessor discovery_runner(): untyped
+
+    def self.new: (?credentials: untyped, ?discovery_runner: untyped) -> instance
+                | ({ ?credentials: untyped, ?discovery_runner: untyped }) -> instance
+  end
+
   # Skills-related global configuration.
   #
   # See <tt>Riffer.config.skills.default_activate_tool</tt> and
@@ -124,6 +133,17 @@ class Riffer::Config
   # Evals configuration (Struct with +judge_model+).
   attr_reader evals: Riffer::Config::Evals
 
+  # MCP configuration (Struct with +credentials+ and +discovery_runner+).
+  #
+  # +credentials+ is an optional Proc for per-run MCP +tools/call+ HTTP headers.
+  # Signature: +->(manifest:, matched_tags:, context:) { Hash or nil }+.
+  # +nil+ from the proc at tool-resolution time omits that server's tools; +nil+
+  # at tool-call time raises Riffer::Mcp::CredentialsDeniedError.
+  #
+  # +discovery_runner+ is the Riffer::Runner used to execute tool discovery
+  # (default +Runner::Sequential+).
+  attr_reader mcp: Riffer::Config::Mcp
+
   # Global tool runtime configuration (experimental).
   #
   # Accepts a Riffer::ToolRuntime subclass, a Riffer::ToolRuntime instance,

data/sig/generated/riffer/mcp/authenticated_tool.rbs

@@ -0,0 +1,17 @@
+# Generated from lib/riffer/mcp/authenticated_tool.rb with RBS::Inline
+
+# Wraps MCP-generated tool classes so +tools/call+ uses +Riffer.config.mcp.credentials+
+# per invocation while delegating metadata to the inner class.
+module Riffer::Mcp::AuthenticatedTool
+  # Returns one wrapper class per inner tool, sharing +manifest+ and +matched_tags+.
+  #
+  # --
+  # : (Array[singleton(Riffer::Tool)], Riffer::Mcp::Manifest, Array[Symbol]) -> Array[singleton(Riffer::Tool)]
+  def self.wrap_all: (Array[singleton(Riffer::Tool)], Riffer::Mcp::Manifest, Array[Symbol]) -> Array[singleton(Riffer::Tool)]
+
+  # --
+  # : (singleton(Riffer::Tool), Riffer::Mcp::Manifest, Array[Symbol]) -> singleton(Riffer::Tool)
+  #  Class.new(Riffer::Tool) is typed as ::Class by steep — it cannot verify the subtype
+  #  relationship for dynamically created anonymous classes, so the ignore is required.
+  def self.wrap_one: (singleton(Riffer::Tool), Riffer::Mcp::Manifest, Array[Symbol]) -> singleton(Riffer::Tool)
+end

data/sig/generated/riffer/mcp/client.rbs

@@ -0,0 +1,33 @@
+# Generated from lib/riffer/mcp/client.rb with RBS::Inline
+
+# Thin wrapper around the MCP Ruby SDK client (mcp gem v0.8+).
+#
+# Resolves headers (if a Proc) once at initialization, then provides
+# +tools_list+ and +tools_call+. Used for discovery (+Manifest#discovery_headers+)
+# and for +tools/call+ when no +credentials+ proc is configured.
+#
+# MCP gem API used:
+#   MCP::Client::HTTP.new(url:, headers:)  — HTTP transport (requires faraday)
+#   MCP::Client.new(transport:)            — client
+#   client.tools                           — Array<MCP::Client::Tool>
+#   client.call_tool(tool:, arguments:)    — raw JSON-RPC response Hash
+class Riffer::Mcp::Client
+  include Riffer::Helpers::Dependencies
+
+  # --
+  # : (endpoint: String, ?headers: (Hash[String, String] | Proc), ?client: untyped?) -> void
+  def initialize: (endpoint: String, ?headers: Hash[String, String] | Proc, ?client: untyped?) -> void
+
+  # Returns an array of tool definition hashes, each with +:name+, +:description+,
+  # and +:input_schema+ keys.
+  #
+  # --
+  # : () -> Array[Hash[Symbol, untyped]]
+  def tools_list: () -> Array[Hash[Symbol, untyped]]
+
+  # Calls a tool on the MCP server and returns joined text content from the response.
+  #
+  # --
+  # : (String, ?Hash[untyped, untyped]) -> String
+  def tools_call: (String, ?Hash[untyped, untyped]) -> String
+end

data/sig/generated/riffer/mcp/manifest.rbs

@@ -0,0 +1,30 @@
+# Generated from lib/riffer/mcp/manifest.rb with RBS::Inline
+
+# Riffer::Mcp::Manifest holds the configuration for a single MCP server.
+#
+# +name+                - String identifier used as the registration key and generated-agent identifier.
+# +tags+                - Array[Symbol]; normalized to symbols at construction time.
+# +endpoint+            - String HTTPS URL passed to the MCP transport.
+# +discovery_headers+   - Hash or Proc; resolved once when building the discovery client for +tools/list+.
+# +credentials_scope+  - Optional symbol hint: +:global+, +:tenant+, +:user+ — documents whether
+#   invocation credentials are expected to depend on tenant and/or user keys in +context+ (no ids stored).
+#   Apps may treat +:user+ as "user in tenant" and pass both keys in +context+.
+class Riffer::Mcp::Manifest
+  attr_reader name: String
+
+  attr_reader tags: Array[Symbol]
+
+  attr_reader endpoint: String
+
+  attr_reader discovery_headers: (Hash[String, untyped] | ::Proc)?
+
+  attr_reader credentials_scope: Symbol?
+
+  # --
+  # : (name: String, endpoint: String, ?tags: Array[untyped]?, ?discovery_headers: (Hash[String, untyped] | ::Proc)?, ?credentials_scope: (String | Symbol)?) -> void
+  def initialize: (name: String, endpoint: String, ?tags: Array[untyped]?, ?discovery_headers: (Hash[String, untyped] | ::Proc)?, ?credentials_scope: (String | Symbol)?) -> void
+
+  private
+
+  def valid_endpoint?: () -> untyped
+end

data/sig/generated/riffer/mcp/registration.rbs

@@ -0,0 +1,49 @@
+# Generated from lib/riffer/mcp/registration.rb with RBS::Inline
+
+# Per-server state managed by Riffer::Mcp::Registry.
+#
+# Created when a server is registered. Discovers tools via the MCP
+# +tools/list+ call, then generates tool classes.
+class Riffer::Mcp::Registration
+  # The manifest that describes this server.
+  attr_reader manifest: Riffer::Mcp::Manifest
+
+  # Generated Riffer::Tool subclasses.
+  #
+  # --
+  # : () -> Array[singleton(Riffer::Tool)]
+  def tools: () -> Array[singleton(Riffer::Tool)]
+
+  # --
+  # : (Riffer::Mcp::Manifest) -> void
+  def initialize: (Riffer::Mcp::Manifest) -> void
+
+  # Retires this registration, preventing in-flight discovery from publishing
+  # state.
+  #
+  # --
+  # : () -> void
+  def retire!: () -> void
+
+  # Returns true if this registration has been retired.
+  #
+  # --
+  # : () -> bool
+  def retired?: () -> bool
+
+  private
+
+  # Runs tool discovery using the configured Runner.
+  #
+  # With +Runner::Sequential+ (default) discovery blocks inline. With
+  # +Runner::Threaded+ discovery runs on a pool thread but +map+ still
+  # blocks the caller — useful for Rails connection-pool isolation.
+  #
+  # --
+  # : () -> void
+  def run_discovery: () -> void
+
+  # --
+  # : () -> Riffer::Mcp::Client
+  def build_client: () -> Riffer::Mcp::Client
+end