mcpspan 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a62e8c7de0a3fe8feed4683fa2a3aaa3b307c317f69d3f42091e62dbf32f05a7
-  data.tar.gz: 719d417a432bb75fdb3437d1e043c63d95754ed056d047fff42f23a28e3ac5c2
+  metadata.gz: 809dac003b7d4f882b23c28d717c060123f019b3dd833a9df61bc868ba7c6445
+  data.tar.gz: 03b8898e5e333f995e9f10b9512bf35d658356e6264eeffd62a723bbdaa55aec
 SHA512:
-  metadata.gz: c595aa5e4e7416e2e0ea941ab5d032d9acf349c582731fa49a5c93859863a3210e4984aeef330c57a644ad9b8ba95c786ab21c2e7f3cfe67bb9e5938adc0f2fc
-  data.tar.gz: '078ec63e4be0c64dbe694a2f6fca21a9a7bda88f48ace0e9ee4a371ee1c7c9e77150d4dd52637012d62fb0cbedc7a93ba0613ee4dde7429c139f7b51039ef752'
+  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
@@ -151,8 +159,12 @@ 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), 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
+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.
 
@@ -168,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
@@ -209,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, :repeated, 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,
@@ -142,6 +147,7 @@ module McpSpan
           # 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,
@@ -150,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 }
@@ -212,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

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,
-    :timestamp, :session_id, :parameters,
+    :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.
@@ -28,6 +28,7 @@ module McpSpan
         responseBytes: response_bytes,
         definitionHash: definition_hash,
         repeated: repeated,
+        invalidArguments: invalid_arguments,
         timestamp: timestamp,
         sdkVersion: VERSION,
         sessionId: session_id,

data/lib/mcpspan/version.rb

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

data/lib/mcpspan.rb

@@ -7,6 +7,7 @@ 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"
@@ -19,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.4.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Kacper Zatoń
@@ -19,6 +19,7 @@ files:
 - LICENSE
 - README.md
 - lib/mcpspan.rb
+- lib/mcpspan/argument_checks.rb
 - lib/mcpspan/collector.rb
 - lib/mcpspan/definitions.rb
 - lib/mcpspan/event.rb