mcpspan 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 996561d4546232205752457ea56cb9aa1570402a5f056b9578db0a6bc3a590d3
-  data.tar.gz: 846bdb5f3f05efac26377a3a52de6c0319c05acafa7b3e5a33cc808b63973590
+  metadata.gz: a62e8c7de0a3fe8feed4683fa2a3aaa3b307c317f69d3f42091e62dbf32f05a7
+  data.tar.gz: 719d417a432bb75fdb3437d1e043c63d95754ed056d047fff42f23a28e3ac5c2
 SHA512:
-  metadata.gz: 7295717445bbd5a6c57938769b3ebcb9d0185baf9d99f5f266387f900c7b86aa4881eadc31029232c6a754e4ca76b9419132524641b5c4d8c05ab9ddcbe6508f
-  data.tar.gz: 7758b51df47a9aa9c6956477dac680cf083f95a756f961c15116b316e7a17a1a35237daa954d151bdaf9cb0d502a15edd17c7127ef73fa8fc9f3912c0c030bd9
+  metadata.gz: c595aa5e4e7416e2e0ea941ab5d032d9acf349c582731fa49a5c93859863a3210e4984aeef330c57a644ad9b8ba95c786ab21c2e7f3cfe67bb9e5938adc0f2fc
+  data.tar.gz: '078ec63e4be0c64dbe694a2f6fca21a9a7bda88f48ace0e9ee4a371ee1c7c9e77150d4dd52637012d62fb0cbedc7a93ba0613ee4dde7429c139f7b51039ef752'

data/README.md

@@ -149,8 +149,10 @@ mode, not in debug.
 
 What is collected: the tool name, how long it took, whether it succeeded, the
 error type and a truncated message when it did not, how large the answer was
-in bytes (its size only, never its content), which client called, and the SDK
-version. For a resource or a prompt, the same, under the name it was
+in bytes (its size only, never its content), whether it repeated the previous
+call's arguments to the same tool in its session (compared in your process;
+the arguments, or any digest of them, never leave it), which client called,
+and the SDK version. For a resource or a prompt, the same, under the name it was
 registered with: never the address a client read, only its template or, for
 an address the server does not have, its scheme.
 

data/lib/mcpspan/collector.rb

@@ -20,7 +20,7 @@ module McpSpan
 
     # What an integration knows about one call as it starts. A kind of nil is a tool call.
     Call = Struct.new(:tool_name, :parameters, :client_name, :client_version, :server_version, :session_id, :started,
-                      :timestamp, :kind, keyword_init: true,)
+                      :timestamp, :kind, :repeated, keyword_init: true,)
 
     @lock = Mutex.new
     @reporter = nil
@@ -139,6 +139,9 @@ module McpSpan
           client_version: Text.version(call.client_version),
           server_version: Text.version(call.server_version),
           response_bytes: response_bytes(response),
+          # A tool the server has, refused arguments included: often the schema is why.
+          definition_hash: call.kind.nil? && source != Source::UNKNOWN_TOOL ? Definitions.of(call.tool_name) : nil,
+          repeated: call.kind.nil? && call.repeated ? true : nil,
           timestamp: call.timestamp.strftime("%Y-%m-%dT%H:%M:%S.%LZ"),
           session_id: call.session_id,
           parameters: call.parameters,

data/lib/mcpspan/definitions.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+
+module McpSpan
+  # Tool definitions as the server lists them, fingerprinted (contract, 3.8). Rewording a description can change how
+  # agents use a tool more than a change to its code; the fingerprint is taken from the answer to `tools/list`, what
+  # an agent actually read, and sent with every call to the tool. Kept for the process: one process reports to one
+  # server.
+  module Definitions
+    HASHED = %w[name title description inputSchema].freeze
+    ESCAPES = { '"' => '\\"', "\\" => "\\\\", "\b" => "\\b", "\f" => "\\f", "\n" => "\\n", "\r" => "\\r",
+                "\t" => "\\t", }.freeze
+
+    @listed = {}
+    @lock = Mutex.new
+
+    class << self
+      # The latest fingerprint listed for a tool, or nil when no listing in this process named it.
+      def of(tool_name)
+        @lock.synchronize { @listed[tool_name] }
+      end
+
+      # Notes every tool in a listing, in whatever key style the gem keeps them. Never raises.
+      def note(tools)
+        JSON.parse(JSON.generate(Array(tools))).each do |tool|
+          next unless tool.is_a?(Hash) && tool["name"].is_a?(String)
+
+          fingerprint = hash(tool)
+          @lock.synchronize { @listed[tool["name"]] = fingerprint } if fingerprint
+        end
+      rescue StandardError
+        nil
+      end
+
+      # For tests: forgets every listing.
+      def forget
+        @lock.synchronize { @listed.clear }
+      end
+
+      # The first 16 hex characters of the SHA-256 of the tool's name, title, description and input schema, as
+      # canonical JSON; nil for a definition that cannot be written so.
+      def hash(tool)
+        hashed = HASHED.each_with_object({}) { |field, out| out[field] = tool[field] unless tool[field].nil? }
+        Digest::SHA256.hexdigest(canonical(hashed))[0, 16]
+      rescue StandardError
+        nil
+      end
+
+      # A value as canonical JSON (contract, 3.8), read the way it was sent: through JSON, so symbols and strings
+      # alike. Raises on what cannot be written so.
+      def canonical_text(value)
+        canonical(JSON.parse(JSON.generate(value)))
+      end
+
+      private
+
+      # Sorted keys, no whitespace, minimal escaping: the same text in every SDK.
+      def canonical(value)
+        case value
+        when nil then "null"
+        when true then "true"
+        when false then "false"
+        when Integer then value.to_s
+        when Float
+          raise ArgumentError, "not a JSON number" unless value.finite?
+
+          value == value.floor && value.abs < 1e15 ? value.to_i.to_s : value.to_s
+        when String then text(value)
+        when Array then "[#{value.map { |item| canonical(item) }.join(",")}]"
+        when Hash
+          pairs = value.map { |key, item| [key.to_s, item] }.sort_by(&:first)
+          "{#{pairs.map { |key, item| "#{text(key)}:#{canonical(item)}" }.join(",")}}"
+        else raise ArgumentError, "cannot fingerprint #{value.class}"
+        end
+      end
+
+      def text(value)
+        out = +'"'
+        value.each_char do |character|
+          out << (ESCAPES[character] || (character.ord < 0x20 ? format("\\u%04x", character.ord) : character))
+        end
+        out << '"'
+      end
+    end
+  end
+end

data/lib/mcpspan/event.rb

@@ -6,8 +6,8 @@ module McpSpan
   # One call of a tool, a resource or a prompt, in the shape the ingest API takes. Parameter values are never in it.
   Event = Struct.new(
     :id, :kind, :tool_name, :duration_ms, :success, :error_source, :error_type, :error_message,
-    :client_type, :client_name, :client_version, :server_version, :response_bytes, :timestamp, :session_id,
-    :parameters,
+    :client_type, :client_name, :client_version, :server_version, :response_bytes, :definition_hash, :repeated,
+    :timestamp, :session_id, :parameters,
     keyword_init: true,
   ) do
     # The event as the API takes it, leaving absent fields out rather than sending them as null.
@@ -26,6 +26,8 @@ module McpSpan
         clientVersion: client_version,
         serverVersion: server_version,
         responseBytes: response_bytes,
+        definitionHash: definition_hash,
+        repeated: repeated,
         timestamp: timestamp,
         sdkVersion: VERSION,
         sessionId: session_id,

data/lib/mcpspan/instrumentation.rb

@@ -39,9 +39,35 @@ module McpSpan
 
       server.singleton_class.prepend(ServerHooks)
       server.singleton_class.prepend(Primitives::ServerHooks) if Primitives.hookable?
+      watch_listings(server)
       server
     end
 
+    # Notes the tools each `tools/list` answer describes (contract, 3.8). The gem binds its handlers when the server
+    # is built, so the bound handler is wrapped where the server keeps it, taking the server's context only if the
+    # handler it wraps asks for it, as the gem decides from the handler's own parameters.
+    def watch_listings(server)
+      handlers = server.instance_variable_get(:@handlers)
+      method = ::MCP::Methods::TOOLS_LIST
+      original = handlers.is_a?(Hash) ? handlers[method] : nil
+      return unless original.respond_to?(:call) && original.respond_to?(:parameters)
+
+      note = lambda do |result|
+        Definitions.note(result[:tools] || result["tools"]) if Collector.collecting? && result.is_a?(Hash)
+        result
+      end
+      contextual = original.parameters.any? { |kind, name| %i[key keyreq].include?(kind) && name == :server_context }
+      handlers[method] = if contextual
+                           lambda do |params, server_context: nil|
+                             note.call(original.call(params, server_context: server_context))
+                           end
+                         else
+                           ->(params) { note.call(original.call(params)) }
+                         end
+    rescue StandardError
+      nil
+    end
+
     def hookable?
       HOOKED.all? { |name| ::MCP::Server.private_method_defined?(name) }
     end
@@ -151,6 +177,10 @@ module McpSpan
           server_version: Instrumentation.server_version(self),
           **Instrumentation.client(envelope, session, self),
         )
+        # Compared once, as the request arrives, before any validation (contract, 3.9).
+        if call&.session_id && !Repeats.continues_earlier_call?(request)
+          call.repeated = Repeats.note(call.session_id, name, request[:arguments])
+        end
         [call, tool]
       rescue *INTERNAL
         nil

data/lib/mcpspan/repeats.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module McpSpan
+  # Whether a call repeats the previous call to the same tool in the same session (contract, 3.9): an agent stuck in a
+  # loop. Only the answer leaves the process. Kept here is a SHA-256 of the canonical arguments of the latest call per
+  # session and tool, never sent: a digest of a short identifier or an enumerated value is found by trying every one.
+  module Repeats
+    # Session and tool pairs kept, the oldest forgotten first.
+    MAX_KEPT = 10_000
+
+    # Insertion-ordered: a pair noted again is moved to the end, so the first is always the longest unused.
+    @latest = {}
+    @lock = Mutex.new
+
+    class << self
+      # Notes a call's arguments, as the client sent them, and says whether they are the previous call's to the same
+      # tool in the same session. Arguments that cannot be written down are never a repeat.
+      def note(session_id, tool_name, arguments)
+        digest = Digest::SHA256.digest(Definitions.canonical_text(arguments || {}))
+        key = [session_id, tool_name.to_s]
+        @lock.synchronize do
+          previous = @latest.delete(key)
+          @latest[key] = digest
+          @latest.shift if @latest.size > MAX_KEPT
+          previous == digest
+        end
+      rescue StandardError
+        false
+      end
+
+      # Whether a call answers an interim result's question (2026-07-28): it then continues that call, and is neither
+      # compared nor kept.
+      def continues_earlier_call?(request)
+        return false unless request.is_a?(Hash)
+
+        %i[inputResponses requestState].any? do |name|
+          value = request[name] || request[name.to_s]
+          !value.nil? && value != ""
+        end
+      end
+
+      # For tests: forgets every call.
+      def forget
+        @lock.synchronize { @latest.clear }
+      end
+    end
+  end
+end

data/lib/mcpspan/version.rb

@@ -2,5 +2,5 @@
 
 module McpSpan
   # The SDK's own version, reported with every event.
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

data/lib/mcpspan.rb

@@ -6,6 +6,8 @@ require_relative "mcpspan/event"
 require_relative "mcpspan/transport"
 require_relative "mcpspan/reporter"
 require_relative "mcpspan/collector"
+require_relative "mcpspan/definitions"
+require_relative "mcpspan/repeats"
 require_relative "mcpspan/instrumentation"
 require_relative "mcpspan/primitives"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mcpspan
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Kacper Zatoń
@@ -20,9 +20,11 @@ files:
 - README.md
 - lib/mcpspan.rb
 - lib/mcpspan/collector.rb
+- lib/mcpspan/definitions.rb
 - lib/mcpspan/event.rb
 - lib/mcpspan/instrumentation.rb
 - lib/mcpspan/primitives.rb
+- lib/mcpspan/repeats.rb
 - lib/mcpspan/reporter.rb
 - lib/mcpspan/text.rb
 - lib/mcpspan/transport.rb