mcpspan 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 996561d4546232205752457ea56cb9aa1570402a5f056b9578db0a6bc3a590d3
-  data.tar.gz: 846bdb5f3f05efac26377a3a52de6c0319c05acafa7b3e5a33cc808b63973590
+  metadata.gz: 8d0a4e3f16e81ed07733683b6bd1984d05955ba6cd3baff32dfeae0855dd3a52
+  data.tar.gz: 5b3a34b8f738da547c0d6cebbfdcb4debf6622eaf92f5c6bfb3ba6c68438dd5a
 SHA512:
-  metadata.gz: 7295717445bbd5a6c57938769b3ebcb9d0185baf9d99f5f266387f900c7b86aa4881eadc31029232c6a754e4ca76b9419132524641b5c4d8c05ab9ddcbe6508f
-  data.tar.gz: 7758b51df47a9aa9c6956477dac680cf083f95a756f961c15116b316e7a17a1a35237daa954d151bdaf9cb0d502a15edd17c7127ef73fa8fc9f3912c0c030bd9
+  metadata.gz: 4b93798f1e34fec652bb47d9a184d22df8a1cf6ee64b3ef774203572b6ffe9d314e511f164bb175e6f50cee52602415aa7740c46cb74525646acfbb9b34dfa1d
+  data.tar.gz: 8847e3f04f30ba0e3c2f2aafb693851084f963c308e3cac81c665f816f3399e591d893a0d0716e0412cfb2d77b3210902ba24dc2cc658eff8062967dbbde4863

data/lib/mcpspan/collector.rb

@@ -139,6 +139,8 @@ 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,
           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,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, :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,7 @@ module McpSpan
         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

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.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.2.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