mcpspan 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 809dac003b7d4f882b23c28d717c060123f019b3dd833a9df61bc868ba7c6445
-  data.tar.gz: 03b8898e5e333f995e9f10b9512bf35d658356e6264eeffd62a723bbdaa55aec
+  metadata.gz: 25cc72fce303e0fbb6aa636d4a50bba9f2c10756df307d965aab48476a94fb36
+  data.tar.gz: 20b8cf13af0f6f24e9c40ac2ff0b4bdf9240c0f5ee7e7f436ec5b542c8f4f2d3
 SHA512:
-  metadata.gz: 98b5fa6edb27bddcb8d9c06ba77a6f4e5715ef0923339a15a49bc329dbc521826887cc34b9474b0c3b2efa2bffdba7e334cb015e51d57956cc2acab919a91d84
-  data.tar.gz: ec137d06a3c7b5b08f3e55fe6ae930cc35cb0860a07e4fcfbde699e807e52b529ddd476e40b9a93f82ce82a7800ef78372b28868e95cfe87e770efebab4d6a90
+  metadata.gz: 1fd550e46bba2af4c2d65bbaf6253f8835dd1773995fff00d1573422ca6eafda7fcb1a6c7c805009cb8ed2e45bbeb69625f46648a522fc25a7554032da283ffa
+  data.tar.gz: 43df35e2670e3c746984df1075d08219e6ffc51d4304d1e9cf26ad165b96d4bad91307eaffdb4239fed51bc29d99e24b53413c34add6f5dd6eaa4d9b0f1f8a94

data/README.md

@@ -164,7 +164,10 @@ tool's definition as your server lists it (its name, title, description and
 input schema, hashed, so the dashboard can mark when you changed it), for a call your
 server refused for its arguments the names of those that did not match the
 tool's schema (never what was sent), which
-client called, and the SDK version. For a resource or a prompt, the same, under the name it was
+client called, and the SDK version. When your server answers a request for
+its list of tools: each tool's name, that fingerprint and the size of its
+definition in bytes, once per session, so the dashboard can show what the
+list costs an agent and which tools are never called. 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

@@ -139,7 +139,10 @@ module McpSpan
           error_source: source,
           error_type: type && Text.truncate(type, Text::MAX_NAME),
           error_message: message.nil? || message.empty? ? nil : message,
-          client_type: Text.client_type(call.client_name),
+          # Always "unknown": the mcpspan server decides the client from its name
+          # (contract, 7). Sent only because servers released before 2026-10-15
+          # refuse an event without it.
+          client_type: "unknown",
           client_name: Text.client_name(call.client_name),
           client_version: Text.version(call.client_version),
           server_version: Text.version(call.server_version),
@@ -156,6 +159,40 @@ module McpSpan
         nil
       end
 
+      # Tools in a listing beyond this are left out (contract, 3.11).
+      MAX_LISTED_TOOLS = 500
+
+      # Records what the server answered to `tools/list` (contract, 3.11): the tools' names, fingerprints and sizes,
+      # once per session for the same answer, leaving out the tools the block says are excluded. `call` carries the
+      # client, the session and the versions. It never blocks on the network.
+      def record_listing(call, tools)
+        reporter = @reporter
+        return if reporter.nil? || call.nil?
+
+        shown = tools.reject { |name, _, _| yield(name) }.first(MAX_LISTED_TOOLS).map do |name, hash, bytes|
+          { name: Text.truncate(name, Text::MAX_NAME), definitionHash: hash, definitionBytes: bytes }
+        end
+        signature = shown.map { |tool| "#{tool[:name]}\0#{tool[:definitionHash]}" }.join("\0")
+        return unless Listings.first?(call.session_id, signature)
+
+        reporter.record(Event.new(
+          id: SecureRandom.uuid,
+          kind: "listing",
+          tool_name: "tools/list",
+          duration_ms: 0,
+          success: true,
+          client_type: "unknown",
+          client_name: Text.client_name(call.client_name),
+          client_version: Text.version(call.client_version),
+          server_version: Text.version(call.server_version),
+          timestamp: call.timestamp.strftime("%Y-%m-%dT%H:%M:%S.%LZ"),
+          session_id: call.session_id,
+          listed_tools: shown,
+        ))
+      rescue StandardError
+        nil
+      end
+
       # Which declared arguments a refusal was over (contract, 3.10), or nil when none were found.
       def refused_names(call)
         names = ArgumentChecks.invalid(Definitions.schema_of(call.tool_name), call.arguments)

data/lib/mcpspan/definitions.rb

@@ -29,19 +29,23 @@ module McpSpan
         @lock.synchronize { @schemas[tool_name] }
       end
 
-      # Notes every tool in a listing, in whatever key style the gem keeps them. Never raises.
+      # Notes every tool in a listing, in whatever key style the gem keeps them, and returns them in its order as
+      # name, fingerprint and size (contract, 3.11). Never raises.
       def note(tools)
+        found = []
         JSON.parse(JSON.generate(Array(tools))).each do |tool|
           next unless tool.is_a?(Hash) && tool["name"].is_a?(String)
 
-          fingerprint = hash(tool)
+          written = fingerprint(tool)
           @lock.synchronize do
-            @listed[tool["name"]] = fingerprint if fingerprint
+            @listed[tool["name"]] = written[0] if written
             @schemas[tool["name"]] = tool["inputSchema"]
           end
+          found << [tool["name"], *written] if written
         end
+        found
       rescue StandardError
-        nil
+        found || []
       end
 
       # For tests: forgets every listing.
@@ -55,8 +59,15 @@ module McpSpan
       # 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)
+        fingerprint(tool)&.first
+      end
+
+      # The fingerprint, and the size in UTF-8 bytes of the canonical JSON it is taken from (contract, 3.11); nil for
+      # a definition that cannot be written so.
+      def fingerprint(tool)
         hashed = HASHED.each_with_object({}) { |field, out| out[field] = tool[field] unless tool[field].nil? }
-        Digest::SHA256.hexdigest(canonical(hashed))[0, 16]
+        written = canonical(hashed)
+        [Digest::SHA256.hexdigest(written)[0, 16], written.bytesize]
       rescue StandardError
         nil
       end

data/lib/mcpspan/event.rb

@@ -7,7 +7,7 @@ module McpSpan
   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, :definition_hash, :repeated,
-    :invalid_arguments, :timestamp, :session_id, :parameters,
+    :invalid_arguments, :timestamp, :session_id, :parameters, :listed_tools,
     keyword_init: true,
   ) do
     # The event as the API takes it, leaving absent fields out rather than sending them as null.
@@ -33,6 +33,8 @@ module McpSpan
         sdkVersion: VERSION,
         sessionId: session_id,
         parameters: parameters,
+        # On a listing: the tools the server listed, in its order (contract, 3.11).
+        listedTools: listed_tools,
       }.compact
     end
 

data/lib/mcpspan/instrumentation.rb

@@ -52,18 +52,32 @@ module McpSpan
       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)
+      contextual = original.parameters.any? { |kind, name| %i[key keyreq].include?(kind) && name == :server_context }
+      # Always asking for the context, which is where the session and the client are; the gem's own handler gets
+      # it only if it asked for it too.
+      handlers[method] = lambda do |params, server_context: nil|
+        result = contextual ? original.call(params, server_context: server_context) : original.call(params)
+        record_listing(server, result, server_context) 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
+
+    # Notes a listing's fingerprints (contract, 3.8) and records it (3.11). Never raises.
+    def record_listing(server, result, server_context)
+      tools = Definitions.note(result[:tools] || result["tools"])
+      session = server_context&.instance_variable_get(:@notification_target)
+      envelope = server_context.respond_to?(:envelope) ? server_context.envelope : nil
+      call = Collector.begin_call(
+        "tools/list",
+        arguments: nil,
+        session_id: session_id(session),
+        server_version: server_version(server),
+        kind: "listing",
+        **client(envelope, session, server),
+      )
+      Collector.record_listing(call, tools) { |name| excluded?(server.tools[name], name) }
     rescue StandardError
       nil
     end

data/lib/mcpspan/listings.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module McpSpan
+  # The listings already sent for each session, so the same answer to `tools/list` is sent once per session
+  # (contract, 3.11). A client lists the tools at the start of a session and often again; the count that matters is
+  # the sessions that were shown the tools, not how often they asked.
+  module Listings
+    # Sessions kept, the oldest forgotten first.
+    MAX_SESSIONS = 10_000
+
+    @sent = {}
+    @lock = Mutex.new
+
+    class << self
+      # Whether a listing is new for its session, noting it as sent. A listing with no session always is.
+      def first?(session_id, signature)
+        return true if session_id.nil?
+
+        @lock.synchronize do
+          signatures = @sent.delete(session_id) || {}
+          new = !signatures.key?(signature)
+          signatures[signature] = true
+          @sent[session_id] = signatures
+          @sent.delete(@sent.keys.first) if @sent.size > MAX_SESSIONS
+          new
+        end
+      end
+
+      # For tests: forgets every listing sent.
+      def forget
+        @lock.synchronize { @sent.clear }
+      end
+    end
+  end
+end

data/lib/mcpspan/text.rb

@@ -11,15 +11,6 @@ module McpSpan
     # A release, a tag, a commit: the server's or the client's.
     MAX_VERSION = 100
 
-    # First match wins, so `claude-code` is tested before `claude`.
-    CLIENT_TYPES = [
-      [["claude-code", "claude code"], "claude-code"],
-      [["claude"], "claude"],
-      [["cursor"], "cursor"],
-      [%w[chatgpt openai], "chatgpt"],
-      [["inspector"], "mcp-inspector"],
-    ].freeze
-
     module_function
 
     # Cuts text to a limit in characters, leaving a visible sign that something was removed.
@@ -28,16 +19,8 @@ module McpSpan
       text.length <= limit ? text : "#{text[0, limit - 3]}..."
     end
 
-    def client_type(name)
-      return "unknown" if name.nil? || name.strip.empty?
-
-      lower = name.downcase
-      CLIENT_TYPES.each do |needles, type|
-        return type if needles.any? { |needle| lower.include?(needle) }
-      end
-      "other"
-    end
-
+    # The name as the client gave it, cut to what the API takes. The mcpspan
+    # server tells clients apart by it (contract, 7).
     def client_name(name)
       return nil if name.nil? || name.strip.empty?
 

data/lib/mcpspan/version.rb

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

data/lib/mcpspan.rb

@@ -9,6 +9,7 @@ require_relative "mcpspan/collector"
 require_relative "mcpspan/definitions"
 require_relative "mcpspan/argument_checks"
 require_relative "mcpspan/repeats"
+require_relative "mcpspan/listings"
 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.5.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Kacper Zatoń
@@ -24,6 +24,7 @@ files:
 - lib/mcpspan/definitions.rb
 - lib/mcpspan/event.rb
 - lib/mcpspan/instrumentation.rb
+- lib/mcpspan/listings.rb
 - lib/mcpspan/primitives.rb
 - lib/mcpspan/repeats.rb
 - lib/mcpspan/reporter.rb