mcp 1.8.2 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e99b2f4d4d5727123d1ae167586134b1f06498f975ed2b16cb2f7e1c413d1271
-  data.tar.gz: 9ea2939b0f5fd94cad620376561def6cc0db832f0f62f990cdf66799c91c3bb6
+  metadata.gz: 95dcc461ef4ba74c3128e82441b81587135488d8c9e4d17f5ea91ba45867f080
+  data.tar.gz: 2d0afc689585aad6ffaf37c4ca5528497e30bf81e733514a05faf724cfb3e2f4
 SHA512:
-  metadata.gz: acc1d2aa4fa8c76b2028cf2cc74b806b08ffc3e42a1e41d48326c53145fc6d3c95e6e724db9960e808b5c2f80330d4973caec143d97bf644f0f800348782476c
-  data.tar.gz: ddf8af09d31cb72577ceb3b4f2ef7fb90f0e813790966d532cc82690d9e9f56847cf8f391c36e860c6f51747dd795394f943941d6ecb44045e9ba424819b5854
+  metadata.gz: 68e755e7b252d6680ca82ce073b3e541e0b4202ac18ce5b73a5175c326aa655e7cbdf4d0685cdb06d4007cc35696b0e7ad60c7a50820567b63b84e4cce5d7c7c
+  data.tar.gz: 68a614ac492dfcfa34a1429efc57e031089dfa65b10db2f6b18b9d0bbffe6ebbcb03c13eacbac9cb3dea178fda603b279825b2cb67ccb81081523db809e27e98

data/README.md

@@ -93,6 +93,8 @@ see [Server Transports](https://ruby.sdk.modelcontextprotocol.io/server/transpor
 A minimal client spawns a stdio server as a subprocess, connects, and lists and calls its tools:
 
 ```ruby
+require "mcp"
+
 stdio_transport = MCP::Client::Stdio.new(
   command: "bundle",
   args: ["exec", "ruby", "path/to/server.rb"],

data/lib/mcp/client/skill_errors.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module MCP
+  class Client
+    # Base class of the errors the Skills extension (SEP-2640) raises on the client side, so a host can
+    # rescue all of them at once. Messages carry request and skill URIs only, never content.
+    class SkillError < StandardError; end
+
+    # A `skills/list` or `skills/get` result the server returned is not a conformant skill entry
+    # (wrong shape, a malformed digest, a resource outside the skill root, a duplicate URI within one page,
+    # or a `skills/get` result for another URI). Nothing is remembered from such a result.
+    class SkillEntryError < SkillError; end
+
+    # The content a `resources/read` returned does not match the skill's manifest: `reason` is one of
+    # `:contents` (not exactly one item for the requested URI with exactly one of `text` or `blob`,
+    # an undecodable `blob`, or an item nested too deeply to copy), `:size`, `:digest`, `:parse` (the `SKILL.md`
+    # frontmatter cannot be read), or `:frontmatter` (it differs from the entry). The skill is latched for
+    # the life of the connection.
+    class SkillVerificationError < SkillError
+      attr_reader :uri, :skill_uri, :reason
+
+      def initialize(message, uri:, skill_uri:, reason:)
+        super(message)
+        @uri = uri
+        @skill_uri = skill_uri
+        @reason = reason
+      end
+    end
+
+    # A Skills call was refused before it was sent, or its completion was discarded because the connection
+    # changed. `reason` is one of `:not_advertised`, `:connection_changed`, `:latched`, `:unknown_skill`,
+    # `:dynamic`, `:not_in_manifest`, or `:skill_md_unverified`; later releases may add reasons, so treat
+    # an unknown one as a refusal too. Nothing is latched by a refusal.
+    class SkillReadRefusedError < SkillError
+      attr_reader :uri, :skill_uri, :reason
+
+      def initialize(message, reason:, uri: nil, skill_uri: nil)
+        super(message)
+        @reason = reason
+        @uri = uri
+        @skill_uri = skill_uri
+      end
+    end
+  end
+end

data/lib/mcp/client/skills.rb

@@ -0,0 +1,430 @@
+# frozen_string_literal: true
+
+require "set"
+require "digest"
+
+module MCP
+  class Client
+    # One page of `skills/list`: `skills` is a frozen Array of `MCP::Skill`; `next_cursor`, `meta`, `ttl_ms`, and
+    # `cache_scope` mirror the response members. Frozen on construction.
+    ListSkillsResult = Struct.new(:skills, :next_cursor, :meta, :ttl_ms, :cache_scope, keyword_init: true) do
+      def initialize(**kwargs)
+        super(**kwargs)
+        freeze
+      end
+    end
+
+    # The entry `skills/get` returned for exactly the requested URI. Frozen on construction.
+    GetSkillResult = Struct.new(:skill, :meta, :ttl_ms, :cache_scope, keyword_init: true) do
+      def initialize(**kwargs)
+        super(**kwargs)
+        freeze
+      end
+    end
+
+    # A skill file read and verified by `read_skill_resource`: `bytes` is the verified content as a frozen
+    # binary-encoded String (the decoded `blob`, or the bytes of the `text`), `mime_type` is the server's
+    # unverified display metadata (never a reason to pick an interpreter), `contents` is the raw frozen
+    # `contents` Array, `skill` is the entry object the content was checked against, and `verified` is true:
+    # the digest, size, and (for a `SKILL.md`) frontmatter matched. Every value is independent of the objects
+    # it was built from, so mutating a source cannot change the result.
+    SkillReadResult = Struct.new(:uri, :bytes, :mime_type, :contents, :skill, :verified, keyword_init: true) do
+      def initialize(**kwargs)
+        super(**kwargs)
+        freeze
+      end
+    end
+
+    # Client side of the Skills extension (SEP-2640), mixed into `MCP::Client`: `list_skills`, `get_skill`,
+    # `read_skill_resource`, and `skills_capability`.
+    #
+    # Every call is admitted only after a handshake of the current connection advertised both the extension and
+    # `resources`, as the SEP asks of clients. Entries the server returned are remembered per client instance,
+    # bound to the connection: `connect` starts a new generation and forgets them. `read_skill_resource` checks
+    # the content against the entry it resolved (size, SHA-256, and the frontmatter of a `SKILL.md`), withholds
+    # content that does not match, and latches the skill so that no later read of it is sent on this connection,
+    # which is what keeps a host from loading part of a tampered skill. `read_resource` stays the raw,
+    # unverified way to fetch a skill file; `MCP::Skill.verify_resource` and `MCP::Skill.verify_frontmatter`
+    # exist for hosts that go that way and then own the latching and ordering obligations themselves.
+    module Skills
+      # Fetches one page of the skills the server serves.
+      #
+      # @raise [SkillReadRefusedError] `:not_advertised` before any request is sent, `:connection_changed` when
+      #   `connect` ran while the request was in flight (the page is discarded).
+      # @raise [SkillEntryError] When the page is not a conformant `skills/list` result.
+      def list_skills(cursor: nil, meta: nil, cancellation: nil)
+        generation = @skills_state.admit(connected: connected?)
+        params = cursor ? { cursor: cursor } : nil
+        response = request(method: Methods::SKILLS_LIST, params: params, meta: meta, cancellation: cancellation)
+        @skills_state.ensure_current!(generation)
+
+        result = response.is_a?(Hash) ? response["result"] : nil
+        raise SkillEntryError, "Response validation failed: missing or invalid `result`" unless result.is_a?(Hash)
+
+        entries = result["skills"]
+        raise SkillEntryError, "Response validation failed: `skills` is not an Array" unless entries.is_a?(Array)
+
+        skills = entries.map { |entry| parse_skill_entry(entry) }
+        uris = skills.map(&:uri)
+        raise SkillEntryError, "Response validation failed: a skill URI is listed twice in one page" unless uris.uniq.size == uris.size
+
+        @skills_state.install(generation, skills)
+        ListSkillsResult.new(
+          skills: skills.freeze,
+          next_cursor: result["nextCursor"],
+          meta: result["_meta"],
+          ttl_ms: result["ttlMs"],
+          cache_scope: result["cacheScope"],
+        )
+      end
+
+      # Fetches the entry of one skill by the URI of its `SKILL.md`, listed or not.
+      #
+      # @raise [SkillReadRefusedError] `:not_advertised` or `:connection_changed`, as for `list_skills`.
+      # @raise [SkillEntryError] When the result is not a conformant entry for exactly `uri`.
+      def get_skill(uri:, meta: nil, cancellation: nil)
+        check_skill_uri!(uri)
+
+        generation = @skills_state.admit(connected: connected?)
+        response = request(method: Methods::SKILLS_GET, params: { uri: uri }, meta: meta, cancellation: cancellation)
+        @skills_state.ensure_current!(generation)
+
+        result = response.is_a?(Hash) ? response["result"] : nil
+        raise SkillEntryError, "Response validation failed: missing or invalid `result`" unless result.is_a?(Hash)
+
+        skill = parse_skill_entry(result["skill"])
+        raise SkillEntryError, "Response validation failed: skills/get answered for #{skill.uri.dump} instead of #{uri.dump}" unless skill.uri == uri
+
+        @skills_state.install(generation, [skill])
+        GetSkillResult.new(skill: skill, meta: result["_meta"], ttl_ms: result["ttlMs"], cache_scope: result["cacheScope"])
+      end
+
+      # Reads one file of a skill through `resources/read` and verifies it against the skill's entry before
+      # returning it. The entry is `skill:` when given (for this read only), else the most specific remembered
+      # skill that contains `uri`, never an enclosing one: when an enclosing skill lists `uri` as well the read is
+      # refused as `:ambiguous`, since only the host knows which skill it is acting on, and a `SKILL.md` URI
+      # resolves only to its own entry. A supporting file is read only after the skill's `SKILL.md` verified on
+      # this instance.
+      #
+      # @raise [SkillReadRefusedError] Before anything is sent: `:not_advertised`, `:latched`, `:unknown_skill` (also
+      #   for a URI longer than 8 KiB or deeper than 128 segments, an SDK limit), `:ambiguous` (an enclosing
+      #   remembered skill lists `uri` too; pass `skill:` for the skill being acted on), `:dynamic` (no digests; use
+      #   `read_resource` with `MCP::Skill.verify_frontmatter`), `:not_in_manifest`, `:skill_md_unverified`; on
+      #   completion, `:connection_changed` or `:latched`.
+      # @raise [SkillVerificationError] When the content does not match; the skill is latched for the connection.
+      def read_skill_resource(uri:, skill: nil, meta: nil, cancellation: nil)
+        check_skill_uri!(uri)
+        raise ArgumentError, "The value of skill must be an MCP::Skill or nil (got #{skill.class})." unless skill.nil? || skill.is_a?(Skill)
+
+        # A frozen copy, so a caller mutating its String during the read cannot change the URI that was verified.
+        uri = -uri
+        unless Skill::Uri.resolvable?(uri)
+          # Refused before the ancestor roots are computed, which would cost time and memory quadratic in
+          # the length of a URI that may come from model output; the message leaves the URI out for that reason.
+          @skills_state.admit(connected: connected?)
+          raise SkillReadRefusedError.new(
+            "Skills call refused (unknown_skill): the URI is longer than #{Skill::Uri::MAX_RESOLVED_BYTES} bytes or deeper " \
+              "than #{Skill::Uri::MAX_RESOLVED_SEGMENTS} segments, beyond what the client resolves",
+            reason: :unknown_skill,
+            uri: uri,
+          )
+        end
+
+        candidates = Skill::Uri.candidate_skill_uris(uri)
+        generation, entry, resource_entry = @skills_state.admit_read(uri, candidates, skill, connected: connected?)
+        response = request(method: Methods::RESOURCES_READ, params: { uri: uri }, meta: meta, cancellation: cancellation)
+        outcome = verify_skill_contents(entry, resource_entry, uri, response)
+        bytes, mime_type, contents = @skills_state.complete_read(generation, uri, candidates, entry, explicit: !skill.nil?, outcome: outcome)
+
+        SkillReadResult.new(uri: uri, bytes: bytes, mime_type: mime_type, contents: contents, skill: entry, verified: true)
+      end
+
+      # The Skills settings the current connection's handshake advertised, as a frozen Hash, or nil when
+      # a Skills call would be refused with `:not_advertised`: not ready, not connected, or not advertised.
+      # nil never means "read skill files raw instead".
+      def skills_capability
+        @skills_state.skills_capability(connected: connected?)
+      end
+
+      private
+
+      def check_skill_uri!(uri)
+        raise ArgumentError, "The value of uri must be a String (got #{uri.class})." unless uri.is_a?(String)
+        return if uri.valid_encoding? && uri.encoding.ascii_compatible?
+
+        raise ArgumentError, "The value of uri must be validly encoded in an ASCII-compatible encoding."
+      end
+
+      def parse_skill_entry(entry)
+        Skill.from_entry(entry)
+      rescue ArgumentError => e
+        raise SkillEntryError, "Skill entry rejected: #{e.message}"
+      end
+
+      # Pure verification, run outside the state lock: exactly one content item for `uri` with exactly one of
+      # `text` or `blob`, the size before decoding, the digest, and for the skill's own `SKILL.md` the frontmatter.
+      # Returns `[:ok, bytes, mime_type, contents]` or `[:failed, error]`.
+      def verify_skill_contents(entry, resource_entry, uri, response)
+        result = response.is_a?(Hash) ? response["result"] : nil
+        contents = result.is_a?(Hash) ? result["contents"] : nil
+        item = contents.is_a?(Array) && contents.size == 1 ? contents.first : nil
+        unless item.is_a?(Hash) && item["uri"] == uri
+          return skill_verification_failure(:contents, uri, entry, "did not come back as exactly one content item")
+        end
+
+        text = item["text"]
+        blob = item["blob"]
+        unless (text.is_a?(String) && blob.nil?) || (blob.is_a?(String) && text.nil?)
+          return skill_verification_failure(:contents, uri, entry, "did not carry exactly one of text or blob")
+        end
+
+        expected_size = resource_entry.size
+        if text
+          bytes = text.b
+          return skill_verification_failure(:size, uri, entry, "has a different size than listed") unless bytes.bytesize == expected_size
+        else
+          # Checked before decoding so the manifest's size bounds the work: this is the base64 length of exactly `size` bytes.
+          return skill_verification_failure(:size, uri, entry, "has a different size than listed") unless blob.length <= ((expected_size + 2) / 3) * 4
+
+          bytes = begin
+            blob.unpack1("m0")
+          rescue ArgumentError
+            return skill_verification_failure(:contents, uri, entry, "did not carry valid base64")
+          end
+          return skill_verification_failure(:size, uri, entry, "has a different size than listed") unless bytes.bytesize == expected_size
+        end
+
+        unless "sha256:#{Digest::SHA256.hexdigest(bytes)}" == resource_entry.digest
+          return skill_verification_failure(:digest, uri, entry, "has a different digest than listed")
+        end
+
+        if uri == entry.uri
+          begin
+            Skill.verify_frontmatter(entry, bytes.dup.force_encoding(Encoding::UTF_8))
+          rescue SkillVerificationError => e
+            return [:failed, e]
+          end
+        end
+
+        copy = begin
+          Skill::Json.deep_freeze(Skill::Json.deep_dup(contents))
+        rescue ArgumentError
+          return skill_verification_failure(:contents, uri, entry, "came back nested too deeply to be the file listed")
+        end
+
+        mime_type = item["mimeType"]
+        [:ok, bytes.freeze, mime_type.is_a?(String) ? mime_type.dup.freeze : nil, copy]
+      end
+
+      def skill_verification_failure(reason, uri, entry, detail)
+        # URIs a server chose are shown with `dump`, which escapes everything outside printable ASCII (`inspect`
+        # leaves bidirectional overrides as they are), so they cannot forge or reorder lines in a host's log.
+        message = "Resource #{uri.dump} #{detail} by #{entry.uri.dump}"
+        [:failed, SkillVerificationError.new(message, uri: uri, skill_uri: entry.uri, reason: reason)]
+      end
+
+      # Per-instance Skills state, bound to the connection. Every public method takes the one Mutex and none of
+      # them calls another inside it (Ruby's Mutex is not reentrant); hashing, decoding, and parsing happen
+      # outside, in the client methods above. No lock is ever held across I/O.
+      class State
+        def initialize
+          @mutex = Mutex.new
+          @generation = 0
+          @ready = false
+          @recorded = nil
+          @index = {}
+          @verified = {}.compare_by_identity
+          @latched = Set.new
+        end
+
+        # A new connection is about to be established: forget everything and return the new generation.
+        def begin_handshake
+          @mutex.synchronize do
+            @generation += 1
+            @ready = false
+            @recorded = nil
+            @index = {}
+            @verified = {}.compare_by_identity
+            @latched = Set.new
+            @generation
+          end
+        end
+
+        # The handshake that started `generation` completed with `result`, the wire Hash `transport.connect`
+        # returned; records a frozen copy of its capabilities, unless a newer handshake started meanwhile.
+        # Capabilities nested too deeply to copy are recorded as none, so `connect` succeeds as it does without
+        # Skills and every Skills call is refused.
+        def handshake_completed(generation, result)
+          capabilities = read_key(result, "capabilities")
+          copy = begin
+            capabilities.is_a?(Hash) ? Skill::Json.deep_freeze(Skill::Json.deep_dup(capabilities)) : nil
+          rescue ArgumentError
+            nil
+          end
+          @mutex.synchronize do
+            next unless generation == @generation
+
+            @ready = true
+            @recorded = copy
+          end
+        end
+
+        # The handshake that started `generation` raised; a stale failure changes nothing.
+        def handshake_failed(generation)
+          @mutex.synchronize do
+            next unless generation == @generation
+
+            @ready = false
+            @recorded = nil
+          end
+        end
+
+        def ready?
+          @mutex.synchronize { @ready }
+        end
+
+        def admit(connected:)
+          @mutex.synchronize do
+            admit_or_refuse!(connected)
+            @generation
+          end
+        end
+
+        def ensure_current!(generation)
+          @mutex.synchronize do
+            refuse!(:connection_changed, nil, nil, "the connection changed while the request was in flight") unless generation == @generation
+          end
+        end
+
+        # Resolves and checks a read before it is sent; returns the generation, the entry, and its resource entry.
+        def admit_read(uri, candidates, explicit, connected:)
+          @mutex.synchronize do
+            admit_or_refuse!(connected)
+            latched = candidates.find { |candidate| @latched.include?(candidate) }
+            refuse!(:latched, uri, latched, "#{latched.dump} failed verification on this connection") if latched
+
+            entry = resolve_entry(uri, candidates, explicit)
+            refuse!(:dynamic, uri, entry.uri, "#{entry.uri.dump} is dynamic and lists no digests") if entry.dynamic?
+
+            resource_entry = entry.resources.find { |candidate| candidate.uri == uri }
+            refuse!(:not_in_manifest, uri, entry.uri, "#{uri.dump} is not listed by #{entry.uri.dump}") unless resource_entry
+            if uri != entry.uri && !@verified.key?(entry)
+              refuse!(:skill_md_unverified, uri, entry.uri, "#{entry.uri.dump} has not been read and verified on this connection yet")
+            end
+
+            [@generation, entry, resource_entry]
+          end
+        end
+
+        # Remembers entries a catalog call returned; a replaced entry object loses its verified status.
+        def install(generation, skills)
+          @mutex.synchronize do
+            refuse!(:connection_changed, nil, nil, "the connection changed while the request was in flight") unless generation == @generation
+
+            skills.each do |skill|
+              previous = @index[skill.uri]
+              @verified.delete(previous) if previous && !previous.equal?(skill)
+              @index[skill.uri] = skill
+            end
+          end
+        end
+
+        # Settles a read: discards a stale or newly latched completion, latches the skill on a failure, and
+        # grants the entry object verified status after its own `SKILL.md` verified (an automatic read only
+        # while the object is still current; an explicit read for the object the caller supplied).
+        def complete_read(generation, uri, candidates, entry, explicit:, outcome:)
+          @mutex.synchronize do
+            refuse!(:connection_changed, uri, entry.uri, "the connection changed while the request was in flight") unless generation == @generation
+            latched = candidates.find { |candidate| @latched.include?(candidate) }
+            refuse!(:latched, uri, latched, "#{latched.dump} failed verification on this connection") if latched
+
+            status, *values = outcome
+            if status == :failed
+              @latched << entry.uri
+              raise values.first
+            end
+
+            if uri == entry.uri && (explicit || @index[entry.uri].equal?(entry))
+              @verified[entry] = true
+            end
+            values
+          end
+        end
+
+        def skills_capability(connected:)
+          @mutex.synchronize do
+            next unless admitted?(connected)
+
+            read_key(read_key(@recorded, "extensions"), Skill::EXTENSION_ID)
+          end
+        end
+
+        private
+
+        def admit_or_refuse!(connected)
+          return if admitted?(connected)
+
+          refuse!(:not_advertised, nil, nil, "no handshake of this connection advertised the skills extension and resources")
+        end
+
+        def admitted?(connected)
+          return false unless @ready && connected && @recorded.is_a?(Hash)
+
+          settings = read_key(read_key(@recorded, "extensions"), Skill::EXTENSION_ID)
+          settings.is_a?(Hash) && read_key(@recorded, "resources").is_a?(Hash)
+        end
+
+        def resolve_entry(uri, candidates, explicit)
+          if explicit
+            if Skill::Uri.manifest_uri?(uri) && uri != explicit.uri
+              refuse!(:unknown_skill, uri, explicit.uri, "a SKILL.md URI resolves only to its own skill")
+            end
+            return explicit
+          end
+
+          if Skill::Uri.manifest_uri?(uri)
+            entry = @index[uri]
+            refuse!(:unknown_skill, uri, nil, "#{uri.dump} has not been listed or fetched on this connection; pass skill: or call get_skill") unless entry
+            return entry
+          end
+
+          remembered = candidates.reverse_each.map { |candidate| @index[candidate] }.compact
+          refuse!(:unknown_skill, uri, nil, "no remembered skill contains #{uri.dump}; pass skill: or call get_skill") if remembered.empty?
+
+          # Only the most specific remembered skill containing `uri` is resolved automatically. The specification
+          # resolves a read against the entry the host loaded the skill from, and only the host knows which skill
+          # it is acting on, so an enclosing skill that lists the file (it lists its nested skills' files too) is
+          # reached with `skill:` alone: never because the nested entry is dynamic or leaves the file out.
+          entry = remembered.first
+          return entry if entry.dynamic?
+
+          enclosing = remembered.drop(1).select do |candidate|
+            !candidate.dynamic? && candidate.resources.any? { |resource| resource.uri == uri }
+          end
+          unless enclosing.empty?
+            refuse!(
+              :ambiguous,
+              uri,
+              entry.uri,
+              "#{uri.dump} is also listed by #{enclosing.map { |candidate| candidate.uri.dump }.join(" and ")}; " \
+                "pass skill: for the skill being acted on",
+            )
+          end
+
+          entry
+        end
+
+        def read_key(hash, key)
+          return unless hash.is_a?(Hash)
+
+          value = hash[key]
+          value.nil? ? hash[key.to_sym] : value
+        end
+
+        def refuse!(reason, uri, skill_uri, detail)
+          raise SkillReadRefusedError.new("Skills call refused (#{reason}): #{detail}", reason: reason, uri: uri, skill_uri: skill_uri)
+        end
+      end
+    end
+  end
+end

data/lib/mcp/client/tool.rb

@@ -2,15 +2,21 @@
 
 module MCP
   class Client
+    # A tool as `tools/list` described it. Every member is kept as the server sent it, so what an extension
+    # puts under `_meta` (MCP Apps names a tool's app under `_meta.ui`) reaches the host unchanged.
     class Tool
-      attr_reader :name, :description, :input_schema, :output_schema, :annotations
+      attr_reader :name, :title, :description, :input_schema, :output_schema, :annotations, :icons, :execution, :meta
 
-      def initialize(name:, description:, input_schema:, output_schema: nil, annotations: nil)
+      def initialize(name:, description:, input_schema:, output_schema: nil, annotations: nil, title: nil, icons: nil, execution: nil, meta: nil)
         @name = name
+        @title = title
         @description = description
         @input_schema = input_schema
         @output_schema = output_schema
         @annotations = annotations
+        @icons = icons
+        @execution = execution
+        @meta = meta
       end
     end
   end

data/lib/mcp/client.rb

@@ -7,6 +7,8 @@ require_relative "client/oauth"
 require_relative "client/stdio"
 require_relative "client/http"
 require_relative "client/paginated_result"
+require_relative "client/skill_errors"
+require_relative "client/skills"
 require_relative "client/tool"
 require_relative "result_type"
 
@@ -114,6 +116,9 @@ module MCP
     STATE_ONLY_BACKOFF_INITIAL_SECONDS = 0.05
     STATE_ONLY_BACKOFF_CAP_SECONDS = 0.25
 
+    # The Skills extension methods (SEP-2640): `list_skills`, `get_skill`, `read_skill_resource`, `skills_capability`.
+    include Skills
+
     # Initializes a new MCP::Client instance.
     #
     # @param transport [Object] The transport object to use for communication with the server.
@@ -144,6 +149,8 @@ module MCP
       # a SEP-2322 `input_required` result.
       @input_required_handlers = {}
       @input_required_max_rounds = input_required_max_rounds
+      # Skills extension state (SEP-2640), bound to the connection by `connect`; see `Client::Skills`.
+      @skills_state = Skills::State.new
     end
 
     # The user may want to access additional transport-specific methods/attributes
@@ -217,7 +224,15 @@ module MCP
 
       effective_mode = resolve_connect_mode(mode, protocol_version)
 
-      if effective_mode == :legacy
+      # Skills state (SEP-2640) follows the connection: a handshake about to run starts a new generation, its
+      # result is recorded only if no newer handshake started meanwhile, and a failure clears readiness under
+      # the same condition, so a stale completion or failure changes nothing. The bundled transports answer
+      # a repeated `connect` with their cached handshake result without any I/O, so when the transport is
+      # connected and Skills is ready nothing is reset: the latches of a live connection stay put.
+      generation = @skills_state.begin_handshake unless skills_ready_on_connected_transport?
+      completed = false
+
+      result = if effective_mode == :legacy
         transport.connect(
           client_info: client_info,
           protocol_version: protocol_version,
@@ -231,6 +246,11 @@ module MCP
           mode: effective_mode,
         )
       end
+      completed = true
+      @skills_state.handshake_completed(generation, result) if generation
+      result
+    ensure
+      @skills_state.handshake_failed(generation) if generation && !completed
     end
 
     # Sends `server/discover` (MCP 2026-07-28, SEP-2575): sessionless capability discovery
@@ -295,10 +315,14 @@ module MCP
 
         Tool.new(
           name: tool["name"],
+          title: tool["title"],
           description: tool["description"],
           input_schema: tool["inputSchema"],
           output_schema: tool["outputSchema"],
           annotations: tool["annotations"],
+          icons: tool["icons"],
+          execution: tool["execution"],
+          meta: tool["_meta"],
         )
       end
 
@@ -673,10 +697,19 @@ module MCP
       scan = McpParamHeaders.scan(tool["inputSchema"])
       return false if scan[:valid]
 
-      warn("MCP::Client: excluding tool #{tool["name"].inspect} from tools/list: #{scan[:reason]}")
+      name = tool["name"]
+      # Both pieces are the server's: `dump` keeps control characters and bidirectional overrides out of the log line.
+      warn("MCP::Client: excluding tool #{(name.is_a?(String) ? name : name.inspect).dump} from tools/list: #{scan[:reason].dump}")
       true
     end
 
+    # Whether a `connect` would only hand back the transport's cached handshake: the transport reports itself
+    # connected and Skills already recorded a handshake of this connection. A transport without connection
+    # state always starts a new generation.
+    def skills_ready_on_connected_transport?
+      transport.respond_to?(:connected?) && transport.connected? && @skills_state.ready?
+    end
+
     # Resolves the effective SEP-2575 lifecycle mode for `connect`:
     #
     # - An explicit `protocol_version` from a legacy generation pins the legacy handshake without a probe,

data/lib/mcp/methods.rb

@@ -22,6 +22,11 @@ module MCP
     RESOURCES_SUBSCRIBE = "resources/subscribe"
     RESOURCES_UNSUBSCRIBE = "resources/unsubscribe"
 
+    # Skills extension (SEP-2640): registered only when a server configures skills,
+    # so an unconfigured server answers `-32601` rather than a capability error.
+    SKILLS_LIST = "skills/list"
+    SKILLS_GET = "skills/get"
+
     TOOLS_CALL = "tools/call"
     TOOLS_LIST = "tools/list"