mcpspan 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 84a76f8debbf2cfc4830ae61f49f68e8bea556dee0176e1707415d19ec6fe7b9
-  data.tar.gz: b7ab651d3b894265c4a7dd21d5827b31f5996f85cb734759e4e1fb420cb17dc6
+  metadata.gz: 8d0a4e3f16e81ed07733683b6bd1984d05955ba6cd3baff32dfeae0855dd3a52
+  data.tar.gz: 5b3a34b8f738da547c0d6cebbfdcb4debf6622eaf92f5c6bfb3ba6c68438dd5a
 SHA512:
-  metadata.gz: 84bfdf6a1e69cb02d126641811e12730e72c2166fdb507c1d2dad5e2dd17cb26ddee618b9776742a6a63be2a79c1ae891cc6666409abfd08d9f41626a3c3dd3e
-  data.tar.gz: 235cbe6fbeae4a5e88c53048595c11dd8930a7a411a6c7c4fe449997393c9677181c26bc9d36e427d4f87f5efeab3c41d49114087c87cc1bdb68460e77ae8d3e
+  metadata.gz: 4b93798f1e34fec652bb47d9a184d22df8a1cf6ee64b3ef774203572b6ffe9d314e511f164bb175e6f50cee52602415aa7740c46cb74525646acfbb9b34dfa1d
+  data.tar.gz: 8847e3f04f30ba0e3c2f2aafb693851084f963c308e3cac81c665f816f3399e591d893a0d0716e0412cfb2d77b3210902ba24dc2cc658eff8062967dbbde4863

data/README.md

@@ -148,8 +148,9 @@ read from the server's wording.
 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, which client called, and
-the SDK version. For a resource or a prompt, the same, under the name it was
+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
 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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "json"
 require "securerandom"
 
 module McpSpan
@@ -103,8 +104,23 @@ module McpSpan
         )
       end
 
-      # Builds the event for a finished call and queues it. It never blocks on the network.
-      def record(call, success:, source: nil, type: nil, message: nil)
+      # The largest size an event carries; anything larger is sent as this (contract, 3.7).
+      MAX_RESPONSE_BYTES = 2_147_483_647
+
+      # Size of an answer in bytes of its compact JSON (contract, 3.7), or nil when there is none or it cannot be
+      # encoded. The JSON is counted and dropped; nothing of it is kept or sent.
+      def response_bytes(response)
+        return nil if response.nil?
+
+        value = response.is_a?(Hash) || response.is_a?(Array) || response.is_a?(String) ? response : response.to_h
+        [JSON.generate(value).bytesize, MAX_RESPONSE_BYTES].min
+      rescue StandardError
+        nil
+      end
+
+      # Builds the event for a finished call and queues it. It never blocks on the network. `response` is the answer,
+      # when there was one, to be measured.
+      def record(call, success:, source: nil, type: nil, message: nil, response: nil)
         duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - call.started) * 1000.0
         reporter = @reporter
         return if reporter.nil?
@@ -122,6 +138,9 @@ module McpSpan
           client_name: Text.client_name(call.client_name),
           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,
           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,82 @@
+# 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
+
+      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,7 +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, :timestamp, :session_id, :parameters,
+    :client_type, :client_name, :client_version, :server_version, :response_bytes, :definition_hash, :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.
@@ -24,6 +25,8 @@ module McpSpan
         clientName: client_name,
         clientVersion: client_version,
         serverVersion: server_version,
+        responseBytes: response_bytes,
+        definitionHash: definition_hash,
         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
@@ -172,11 +198,12 @@ module McpSpan
       def __mcpspan_settled(call, state, result)
         # An interim result asking the client for input settles nothing; the call that follows it does.
         return if Instrumentation.interim?(result)
-        return Collector.record(call, success: true) unless result.is_a?(Hash) && result[:isError]
+        return Collector.record(call, success: true, response: result) unless result.is_a?(Hash) && result[:isError]
 
         # The gem refuses missing or invalid arguments with an error result, before the tool is called.
         if state.reached
-          Collector.record(call, success: false, source: Source::RESULT, message: Instrumentation.result_text(result))
+          Collector.record(call, success: false, source: Source::RESULT, message: Instrumentation.result_text(result),
+                                 response: result,)
         else
           Collector.record(call, success: false, source: Source::ARGUMENTS)
         end
@@ -204,9 +231,10 @@ module McpSpan
         if call
           hash = result.respond_to?(:to_h) ? result.to_h : {}
           if hash[:isError]
-            Collector.record(call, success: false, source: Source::RESULT, message: Instrumentation.result_text(hash))
+            Collector.record(call, success: false, source: Source::RESULT, message: Instrumentation.result_text(hash),
+                                   response: hash,)
           elsif !Instrumentation.interim?(result)
-            Collector.record(call, success: true)
+            Collector.record(call, success: true, response: hash)
           end
         end
         result

data/lib/mcpspan/primitives.rb

@@ -141,7 +141,7 @@ module McpSpan
 
       def __mcpspan_succeeded(call, result)
         # An interim result asking the client for input settles nothing; the request that follows it does.
-        Collector.record(call, success: true) unless Instrumentation.interim?(result)
+        Collector.record(call, success: true, response: result) unless Instrumentation.interim?(result)
       rescue *Instrumentation::INTERNAL
         nil
       end

data/lib/mcpspan/version.rb

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

data/lib/mcpspan.rb

@@ -6,6 +6,7 @@ require_relative "mcpspan/event"
 require_relative "mcpspan/transport"
 require_relative "mcpspan/reporter"
 require_relative "mcpspan/collector"
+require_relative "mcpspan/definitions"
 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.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Kacper Zatoń
@@ -20,6 +20,7 @@ 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