mcpspan 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d0a4e3f16e81ed07733683b6bd1984d05955ba6cd3baff32dfeae0855dd3a52
-  data.tar.gz: 5b3a34b8f738da547c0d6cebbfdcb4debf6622eaf92f5c6bfb3ba6c68438dd5a
+  metadata.gz: 809dac003b7d4f882b23c28d717c060123f019b3dd833a9df61bc868ba7c6445
+  data.tar.gz: 03b8898e5e333f995e9f10b9512bf35d658356e6264eeffd62a723bbdaa55aec
 SHA512:
-  metadata.gz: 4b93798f1e34fec652bb47d9a184d22df8a1cf6ee64b3ef774203572b6ffe9d314e511f164bb175e6f50cee52602415aa7740c46cb74525646acfbb9b34dfa1d
-  data.tar.gz: 8847e3f04f30ba0e3c2f2aafb693851084f963c308e3cac81c665f816f3399e591d893a0d0716e0412cfb2d77b3210902ba24dc2cc658eff8062967dbbde4863
+  metadata.gz: 98b5fa6edb27bddcb8d9c06ba77a6f4e5715ef0923339a15a49bc329dbc521826887cc34b9474b0c3b2efa2bffdba7e334cb015e51d57956cc2acab919a91d84
+  data.tar.gz: ec137d06a3c7b5b08f3e55fe6ae930cc35cb0860a07e4fcfbde699e807e52b529ddd476e40b9a93f82ce82a7800ef78372b28868e95cfe87e770efebab4d6a90

data/README.md

@@ -142,6 +142,14 @@ refused call carries no message, because validation text can quote back what
 the agent sent. Whether a call reached your tool is observed directly, not
 read from the server's wording.
 
+For a refusal of arguments, the SDK also says which ones. It checks what the
+agent sent against the input schema your server listed, in your process, and
+records the top-level arguments that did not match, by the names the schema
+declares, so the tool's page can show that 29 refusals were all `passengers`.
+Values are never sent, and neither is a name the agent made up. It works from
+the latest `tools/list` your server answered in the same process; a refusal
+before any listing names nothing.
+
 ## Privacy
 
 **Parameter values never leave your process.** Not by default, not in any
@@ -149,8 +157,14 @@ 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), a fingerprint of the
+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
 registered with: never the address a client read, only its template or, for
 an address the server does not have, its scheme.
 
@@ -166,6 +180,18 @@ called with `destination` and never with `departure_date` tells you your tool
 description is not landing. Knowing which destination tells you nothing you
 needed, and puts your users' data somewhere it does not belong.
 
+Error messages are sent, cut short, because they are usually what says why a
+call failed. If your tools can fail with text you would not send anywhere, as
+a tool that runs commands or reads files might quote a path or a token, turn
+them off:
+
+```ruby
+McpSpan.instrument(server, capture_error_messages: false)
+```
+
+Every failure is still recorded, with where it came from and the exception's
+class. Only the text is left out.
+
 ## Self-hosting
 
 ```ruby
@@ -207,6 +233,7 @@ Keywords of `McpSpan.instrument` and `McpSpan.configure`.
 | `api_key` | `MCPSPAN_API_KEY` | Identifies your server. Without it, nothing is collected. |
 | `endpoint` | `MCPSPAN_ENDPOINT`; none | Your mcpspan installation. Nothing is collected without it. |
 | `capture_parameter_names` | `false` | Records parameter names and types, never values. |
+| `capture_error_messages` | `true` | Sends the text of a failure, cut short. Off sends that it failed and how, without the text. |
 | `server_version` | `MCPSPAN_SERVER_VERSION`, then the server's own | The version to record calls under: a release, a tag, a commit. |
 | `debug` | `false` | Writes delivery diagnostics to standard error. |
 | `on_diagnostic` | - | Receives diagnostics instead. Implies `debug`. |

data/lib/mcpspan/argument_checks.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+require "json"
+
+module McpSpan
+  # Which top-level arguments of a refused call did not match the tool's input schema (contract, 3.10). The server's
+  # own refusal is not read: each validation library words it differently, and some quote the value the agent sent.
+  # The arguments are checked here instead, against the schema the server listed, by a small set of rules that never
+  # fail what they do not understand. Only names the schema declares come out, so nothing the client made up, and no
+  # value, is sent.
+  module ArgumentChecks
+    # Names sent at most, per call.
+    MAX_NAMES = 20
+
+    class << self
+      # The declared names whose arguments fail the schema, sorted, at most twenty. Both are read the way they were
+      # sent, through JSON, so symbols and strings alike. Never raises.
+      def invalid(schema, arguments)
+        rules = plain(schema)
+        return [] unless rules.is_a?(Hash)
+
+        values = arguments.nil? ? {} : plain(arguments)
+        return [] unless values.is_a?(Hash)
+
+        names = []
+        required = rules["required"]
+        names.concat(required.select { |name| name.is_a?(String) && !values.key?(name) }) if required.is_a?(Array)
+        properties = rules["properties"]
+        if properties.is_a?(Hash)
+          properties.each do |name, rule|
+            names << name if values.key?(name) && !matches?(rule, values[name])
+          end
+        end
+        names.uniq.sort.first(MAX_NAMES)
+      rescue StandardError
+        []
+      end
+
+      private
+
+      def plain(value)
+        JSON.parse(JSON.generate(value))
+      end
+
+      # Whether a value passes a schema under the checks the contract lists, and only those.
+      def matches?(schema, value)
+        return false if schema == false
+        return true unless schema.is_a?(Hash)
+
+        type = schema["type"]
+        return false if type.is_a?(String) && !type?(type, value)
+        return false if type.is_a?(Array) && type.all?(String) && type.none? { |name| type?(name, value) }
+
+        allowed = schema["enum"]
+        if allowed.is_a?(Array)
+          sent = Definitions.canonical_text(value)
+          return false if allowed.none? { |option| Definitions.canonical_text(option) == sent }
+        end
+        if schema.key?("const") && Definitions.canonical_text(schema["const"]) != Definitions.canonical_text(value)
+          return false
+        end
+
+        within?(schema, value)
+      end
+
+      # The bounds on numbers, lengths and counts, and what objects and arrays hold.
+      def within?(schema, value)
+        bound = ->(name) { number?(schema[name]) ? schema[name] : nil }
+        if number?(value)
+          return false if bound.call("minimum")&.then { |minimum| value < minimum }
+          return false if bound.call("maximum")&.then { |maximum| value > maximum }
+          return false if bound.call("exclusiveMinimum")&.then { |above| value <= above }
+          return false if bound.call("exclusiveMaximum")&.then { |below| value >= below }
+        end
+
+        case value
+        when String
+          # A Ruby string's length is in characters, which in UTF-8 are code points.
+          return false if bound.call("minLength")&.then { |shortest| value.length < shortest }
+          return false if bound.call("maxLength")&.then { |longest| value.length > longest }
+        when Array
+          return false if bound.call("minItems")&.then { |fewest| value.length < fewest }
+          return false if bound.call("maxItems")&.then { |most| value.length > most }
+
+          each = schema["items"]
+          checked = each.is_a?(Hash) || [true, false].include?(each)
+          return false if checked && !value.all? { |item| matches?(each, item) }
+        when Hash
+          required = schema["required"]
+          return false if required.is_a?(Array) && required.any? { |name| name.is_a?(String) && !value.key?(name) }
+
+          properties = schema["properties"]
+          if properties.is_a?(Hash) && properties.any? { |name, rule| value.key?(name) && !matches?(rule, value[name]) }
+            return false
+          end
+        end
+        true
+      end
+
+      def type?(type, value)
+        case type
+        when "string" then value.is_a?(String)
+        when "number" then number?(value)
+        when "integer" then number?(value) && value == value.truncate
+        when "boolean" then [true, false].include?(value)
+        when "object" then value.is_a?(Hash)
+        when "array" then value.is_a?(Array)
+        when "null" then value.nil?
+        # A type this list does not know is not checked.
+        else true
+        end
+      end
+
+      def number?(value)
+        value.is_a?(Integer) || (value.is_a?(Float) && value.finite?)
+      end
+    end
+  end
+end

data/lib/mcpspan/collector.rb

@@ -14,13 +14,14 @@ module McpSpan
     MAX_EVENTS_PER_REQUEST = 1_000
 
     SETTINGS = %i[
-      api_key endpoint capture_parameter_names server_version debug on_diagnostic flush_on_exit flush_interval
-      max_batch_size max_queue_size
+      api_key endpoint capture_parameter_names capture_error_messages server_version debug on_diagnostic
+      flush_on_exit flush_interval max_batch_size max_queue_size
     ].freeze
 
     # What an integration knows about one call as it starts. A kind of nil is a tool call.
+    # `arguments` are kept as sent, by reference, only to tell which a refusal was over (contract, 3.10).
     Call = Struct.new(:tool_name, :parameters, :client_name, :client_version, :server_version, :session_id, :started,
-                      :timestamp, :kind, keyword_init: true,)
+                      :timestamp, :kind, :repeated, :arguments, keyword_init: true,)
 
     @lock = Mutex.new
     @reporter = nil
@@ -101,6 +102,7 @@ module McpSpan
           started: started,
           timestamp: timestamp,
           kind: kind,
+          arguments: arguments,
         )
       end
 
@@ -123,8 +125,11 @@ module McpSpan
       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?
+        settings = @settings
+        return if reporter.nil? || settings.nil?
 
+        # The text of a failure, unless the developer chose to send none (contract, 5).
+        message = nil unless settings[:capture_error_messages]
         reporter.record(Event.new(
           id: SecureRandom.uuid,
           kind: call.kind,
@@ -141,6 +146,8 @@ module McpSpan
           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,
+          invalid_arguments: call.kind.nil? && source == Source::ARGUMENTS ? refused_names(call) : nil,
           timestamp: call.timestamp.strftime("%Y-%m-%dT%H:%M:%S.%LZ"),
           session_id: call.session_id,
           parameters: call.parameters,
@@ -149,6 +156,12 @@ module McpSpan
         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)
+        names.empty? ? nil : names.map { |name| Text.truncate(name, Text::MAX_NAME) }
+      end
+
       # For tests: forgets that the missing endpoint was already mentioned.
       def forget_no_endpoint_notice
         @lock.synchronize { @said_no_endpoint = false }
@@ -211,6 +224,7 @@ module McpSpan
           api_key: first_set(settings[:api_key], ENV.fetch("MCPSPAN_API_KEY", nil)),
           endpoint: first_set(settings[:endpoint], ENV.fetch("MCPSPAN_ENDPOINT", nil)),
           capture_parameter_names: settings[:capture_parameter_names] ? true : false,
+          capture_error_messages: settings.fetch(:capture_error_messages, true) ? true : false,
           server_version: first_set(settings[:server_version], ENV.fetch("MCPSPAN_SERVER_VERSION", nil)),
           debug: debug,
           on_diagnostic: on_diagnostic,

data/lib/mcpspan/definitions.rb

@@ -14,6 +14,8 @@ module McpSpan
                 "\t" => "\\t", }.freeze
 
     @listed = {}
+    # Each tool's input schema as last listed, to tell which arguments a refusal was over (contract, 3.10).
+    @schemas = {}
     @lock = Mutex.new
 
     class << self
@@ -22,13 +24,21 @@ module McpSpan
         @lock.synchronize { @listed[tool_name] }
       end
 
+      # The latest input schema listed for a tool, or nil when no listing in this process named it.
+      def schema_of(tool_name)
+        @lock.synchronize { @schemas[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
+          @lock.synchronize do
+            @listed[tool["name"]] = fingerprint if fingerprint
+            @schemas[tool["name"]] = tool["inputSchema"]
+          end
         end
       rescue StandardError
         nil
@@ -36,7 +46,10 @@ module McpSpan
 
       # For tests: forgets every listing.
       def forget
-        @lock.synchronize { @listed.clear }
+        @lock.synchronize do
+          @listed.clear
+          @schemas.clear
+        end
       end
 
       # The first 16 hex characters of the SHA-256 of the tool's name, title, description and input schema, as
@@ -48,6 +61,12 @@ module McpSpan
         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.

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, :definition_hash, :timestamp,
-    :session_id, :parameters,
+    :client_type, :client_name, :client_version, :server_version, :response_bytes, :definition_hash, :repeated,
+    :invalid_arguments, :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.
@@ -27,6 +27,8 @@ module McpSpan
         serverVersion: server_version,
         responseBytes: response_bytes,
         definitionHash: definition_hash,
+        repeated: repeated,
+        invalidArguments: invalid_arguments,
         timestamp: timestamp,
         sdkVersion: VERSION,
         sessionId: session_id,

data/lib/mcpspan/instrumentation.rb

@@ -177,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.3.0"
+  VERSION = "0.5.0"
 end

data/lib/mcpspan.rb

@@ -7,6 +7,8 @@ require_relative "mcpspan/transport"
 require_relative "mcpspan/reporter"
 require_relative "mcpspan/collector"
 require_relative "mcpspan/definitions"
+require_relative "mcpspan/argument_checks"
+require_relative "mcpspan/repeats"
 require_relative "mcpspan/instrumentation"
 require_relative "mcpspan/primitives"
 
@@ -18,8 +20,9 @@ require_relative "mcpspan/primitives"
 # Without an API key nothing is collected and nothing is sent. Parameter values never leave the process.
 #
 # Settings: +api_key+ (else +MCPSPAN_API_KEY+), +endpoint+, your mcpspan installation (else +MCPSPAN_ENDPOINT+; no
-# default, and nothing is collected without it), +capture_parameter_names+, +debug+, +on_diagnostic+,
-# +flush_on_exit+, +flush_interval+ (seconds), +max_batch_size+, +max_queue_size+. Nothing here raises over a setting.
+# default, and nothing is collected without it), +capture_parameter_names+, +capture_error_messages+ (on unless
+# false), +debug+, +on_diagnostic+, +flush_on_exit+, +flush_interval+ (seconds), +max_batch_size+, +max_queue_size+.
+# Nothing here raises over a setting.
 module McpSpan
   @excluded_names = Set.new
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mcpspan
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Kacper Zatoń
@@ -19,11 +19,13 @@ files:
 - LICENSE
 - README.md
 - lib/mcpspan.rb
+- lib/mcpspan/argument_checks.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