mcp 1.8.1 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 255e316335616783063d8a7374f385ff10b99c9ddef24571734e19b6ec6f5f93
-  data.tar.gz: 07021e227f5b1be05fd2c1e4dc88e0d563bc963b6f1190f998aa632ed6871031
+  metadata.gz: 95dcc461ef4ba74c3128e82441b81587135488d8c9e4d17f5ea91ba45867f080
+  data.tar.gz: 2d0afc689585aad6ffaf37c4ca5528497e30bf81e733514a05faf724cfb3e2f4
 SHA512:
-  metadata.gz: 3d496817c30ae59b7f99704fead73cc9dfe5d926a87455a5c51fcc766bdf299d943ce86c0d43ca859d870a488df191cc0a4bdeba302b95d8ebcf084730743a68
-  data.tar.gz: 6291785257c054baf3570fb9baef4ecb1db006c920608ad69239460e2494610fa9133341bdf903a4c127f7ab40146f2bf9eecb34266621cba172a08ef52812f0
+  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/json_rpc_handler.rb

@@ -53,7 +53,9 @@ module JsonRpcHandler
     end
   end
 
-  def handle_json(request_json, id_validation_pattern: DEFAULT_ALLOWED_ID_CHARACTERS, &method_finder)
+  # `on_generate_error`, when given, is called with the `JSON::GeneratorError` of a response that cannot be generated,
+  # before that response is replaced with Internal error.
+  def handle_json(request_json, id_validation_pattern: DEFAULT_ALLOWED_ID_CHARACTERS, on_generate_error: nil, &method_finder)
     begin
       begin
         request = JSON.parse(request_json, symbolize_names: true)
@@ -77,7 +79,35 @@ module JsonRpcHandler
       })
     end
 
-    response&.to_json
+    begin
+      response&.to_json
+    rescue JSON::GeneratorError => e
+      on_generate_error&.call(e)
+      encodable_response(response, id_validation_pattern: id_validation_pattern).to_json
+    end
+  end
+
+  # `response` with each part JSON cannot generate replaced with Internal error. A batch is replaced item by item,
+  # so the other items keep their results.
+  def encodable_response(response, id_validation_pattern: nil)
+    return response.map { |item| encodable_response(item, id_validation_pattern: id_validation_pattern) } if response.is_a?(Array)
+
+    response.to_json
+    response
+  rescue JSON::GeneratorError
+    internal_error_for(response, id_validation_pattern: id_validation_pattern)
+  end
+
+  # The error answering a request whose response cannot be generated: a result or an error holding a string that
+  # is not valid UTF-8, typically one the request carried and the SDK or a handler repeated, such as a tool name
+  # in its Tool not found error. It carries the request id when the response has one, which was validated before
+  # the method ran.
+  def internal_error_for(response, id_validation_pattern: nil)
+    id = response[:id] if response.is_a?(Hash)
+    error_response(id: id.nil? ? :unknown_id : id, id_validation_pattern: id_validation_pattern, error: {
+      code: ErrorCode::INTERNAL_ERROR,
+      message: "Internal error",
+    })
   end
 
   def process_request(request, id_validation_pattern:, &method_finder)

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/stdio.rb

@@ -434,7 +434,7 @@ module MCP
           line = read_line(method, params)
           raise_connection_error!(method, params) if line.nil?
 
-          parsed = JSON.parse(line.strip)
+          parsed = JSON.parse(strip_frame(line))
 
           # A frame carrying `method` is a request or notification, never the awaited response,
           # whatever its id says: JSON-RPC id spaces are per sender, so a server-chosen ping id
@@ -484,8 +484,10 @@ module MCP
         parsed["method"] == MCP::Methods::PING && json_rpc_id?(parsed["id"]) && JsonRpcHandler.valid_version?(parsed["jsonrpc"])
       end
 
+      # An id the pong could not write back is skipped too: a String that is not valid UTF-8, or a number
+      # such as `1e400`, which the parser reads as an infinite Float that JSON cannot represent.
       def json_rpc_id?(id)
-        id.is_a?(String) || id.is_a?(Numeric)
+        (id.is_a?(String) && id.valid_encoding?) || id.is_a?(Integer) || (id.is_a?(Float) && id.finite?)
       end
 
       def ensure_running!
@@ -534,6 +536,14 @@ module MCP
         )
       end
 
+      # Strips a frame as bytes. The server's stdout is read as UTF-8, and `String#strip` raises for a UTF-8 string
+      # holding an invalid byte at either end on every supported Ruby, and anywhere in it from Ruby 3.2 on, which would
+      # surface as that exception instead of the client's own error. As bytes, the frame reaches the parser, which
+      # refuses what is not JSON with the client's parse failure.
+      def strip_frame(line)
+        line.b.strip.force_encoding(Encoding::UTF_8)
+      end
+
       def raise_connection_error!(method, params)
         raise RequestHandlerError.new(
           "Server process closed stdout unexpectedly",

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