mcpspan 0.1.0

data/lib/mcpspan/instrumentation.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module McpSpan
+  # Measuring the tools of a server built on the official Ruby MCP SDK, the `mcp` gem.
+  #
+  # The gem has one `around_request` slot, which belongs to the developer, and it sees neither a call's arguments
+  # nor its result. So an instrumented server gets this module prepended to its own singleton class: `call_tool`
+  # sees the whole call, and `call_tool_with_args`, which the gem calls only once the arguments have passed its
+  # checks, shows directly whether the call reached the tool. Other servers, and the gem's classes, are untouched.
+  module Instrumentation
+    # Set, fiber-locally, while an instrumented server handles a call, so a tracked tool inside it counts nothing
+    # twice and the server can see that the tool was reached.
+    CURRENT = :__mcpspan_call
+
+    # What an instrumented server knows about the call it is handling.
+    State = Struct.new(:reached)
+
+    # Named, not referenced: the gem autoloads these, and loading the HTTP transport needs the rack gem, which a stdio
+    # server need not have. Touching the constant there would raise LoadError inside a tool call.
+    HTTP_TRANSPORT = "MCP::Server::Transports::StreamableHTTPTransport"
+    INPUT_REQUIRED = "MCP::InputRequiredResult"
+
+    # What a hook rescues so that measuring can never be why a call fails: StandardError, and ScriptError for a
+    # library that could not be loaded. Signals and exits pass through.
+    INTERNAL = [StandardError, ScriptError].freeze
+
+    module_function
+
+    # The gem's private methods the hooks take the place of. If a version renames them, instrumenting leaves the
+    # server as it was rather than guessing; test/instrument_test.rb fails first.
+    HOOKED = %i[call_tool call_tool_with_args].freeze
+
+    def instrument(server)
+      return server unless defined?(::MCP::Server) && server.is_a?(::MCP::Server)
+      return server if server.singleton_class.include?(ServerHooks)
+      return server unless hookable?
+
+      server.singleton_class.prepend(ServerHooks)
+      server.singleton_class.prepend(Primitives::ServerHooks) if Primitives.hookable?
+      server
+    end
+
+    def hookable?
+      HOOKED.all? { |name| ::MCP::Server.private_method_defined?(name) }
+    end
+
+    def excluded?(tool, name)
+      McpSpan.excluded_names.include?(name.to_s) || tool&.instance_variable_get(:@__mcpspan_excluded)
+    end
+
+    # Our identifier for the connection a call arrived on, or nil for none.
+    #
+    # Over HTTP without a transport session (stateless, and every call on 2026-07-28, which has no sessions and for
+    # which the gem makes a throwaway session per request) there is none: each call would otherwise be a session of
+    # its own. The identifier is random, kept on the gem's session object, and never derived from the transport's.
+    def session_id(session)
+      return nil if session.nil?
+
+      transport = session.instance_variable_get(:@transport)
+      over_http = named?(transport, HTTP_TRANSPORT)
+      return nil if over_http && (session.session_id.nil? || session.era == :modern)
+
+      session.instance_variable_get(:@__mcpspan_session) ||
+        session.instance_variable_set(:@__mcpspan_session, SecureRandom.uuid)
+    end
+
+    # The client's name and version: from the call itself on 2026-07-28, else from its connection's handshake.
+    def client(envelope, session, server)
+      info = envelope&.client_info || session&.client || server.instance_variable_get(:@client)
+      return {} unless info.is_a?(Hash)
+
+      name = info[:name] || info["name"]
+      version = info[:version] || info["version"]
+      { client_name: name&.to_s, client_version: version&.to_s }
+    end
+
+    # The version the server gives itself, `MCP::Server.new(version:)`. Unset, the gem announces its default.
+    def server_version(server)
+      server.respond_to?(:version) ? server.version&.to_s : nil
+    end
+
+    def result_text(result)
+      content = result[:content] || result["content"] || []
+      texts = content.filter_map do |block|
+        next unless block.is_a?(Hash)
+
+        type = block[:type] || block["type"]
+        (block[:text] || block["text"]).to_s if type.to_s == "text"
+      end
+      Text.truncate(texts.join(" ").strip, Text::MAX_RESULT_MESSAGE)
+    end
+
+    # Whether an object is of a class, or a subclass, known here only by name.
+    def named?(object, class_name)
+      object.class.ancestors.any? { |ancestor| ancestor.name == class_name }
+    end
+
+    def interim?(result)
+      named?(result, INPUT_REQUIRED)
+    end
+
+    def exception(error)
+      [error.class.name || "Exception", Text.truncate(error.message.to_s, Text::MAX_EXCEPTION_MESSAGE)]
+    end
+
+    # Hooks prepended to one server's singleton class.
+    module ServerHooks
+      private
+
+      def call_tool(request, session: nil, **rest)
+        call, tool = __mcpspan_begin(request, session, rest[:envelope])
+        return super if call.nil?
+
+        state = State.new(false)
+        outer = Thread.current[CURRENT]
+        Thread.current[CURRENT] = state
+        begin
+          result = super
+        rescue ::MCP::CancelledError
+          # A cancelled call has no outcome to record.
+          raise
+        rescue StandardError => e
+          __mcpspan_failed(call, tool, state, e)
+          raise
+        ensure
+          Thread.current[CURRENT] = outer
+        end
+        __mcpspan_settled(call, state, result)
+        result
+      end
+
+      def call_tool_with_args(*args, **kwargs)
+        state = Thread.current[CURRENT]
+        state.reached = true if state
+        super
+      end
+
+      def __mcpspan_begin(request, session, envelope)
+        return nil unless Collector.collecting? && request.is_a?(Hash)
+
+        name = request[:name]
+        tool = tools[name]
+        return nil if Instrumentation.excluded?(tool, name)
+
+        call = Collector.begin_call(
+          name,
+          arguments: request[:arguments],
+          session_id: Instrumentation.session_id(session),
+          server_version: Instrumentation.server_version(self),
+          **Instrumentation.client(envelope, session, self),
+        )
+        [call, tool]
+      rescue *INTERNAL
+        nil
+      end
+
+      def __mcpspan_failed(call, tool, state, error)
+        if tool.nil?
+          Collector.record(call, success: false, source: Source::UNKNOWN_TOOL)
+        else
+          # The gem wraps what a tool raised, and keeps it; the tool's own class is what is worth recording.
+          original = error.respond_to?(:original_error) && error.original_error ? error.original_error : error
+          type, message = Instrumentation.exception(state.reached ? original : error)
+          Collector.record(call, success: false, source: Source::EXCEPTION, type: type, message: message)
+        end
+      rescue *INTERNAL
+        nil
+      end
+
+      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]
+
+        # 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))
+        else
+          Collector.record(call, success: false, source: Source::ARGUMENTS)
+        end
+      rescue *INTERNAL
+        nil
+      end
+    end
+
+    # Hooks prepended to one tracked tool class's singleton class.
+    module ToolHooks
+      def call(*args, **kwargs, &)
+        # Inside an instrumented server, the server measures the call.
+        return super if Thread.current[CURRENT] || !Collector.collecting? || Instrumentation.excluded?(self, name_value)
+
+        # Recorded by hand, the call cannot see its connection or its client.
+        call = Collector.begin_call(name_value, arguments: kwargs.except(:server_context),
+                                                client_name: nil, session_id: nil,)
+        begin
+          result = super
+        rescue StandardError => e
+          type, message = Instrumentation.exception(e)
+          Collector.record(call, success: false, source: Source::EXCEPTION, type: type, message: message) if call
+          raise
+        end
+        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))
+          elsif !Instrumentation.interim?(result)
+            Collector.record(call, success: true)
+          end
+        end
+        result
+      end
+    end
+  end
+end

data/lib/mcpspan/primitives.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+module McpSpan
+  # Resource reads and prompt gets (contract, 3.5), on the official Ruby MCP SDK.
+  #
+  # The gem answers `resources/read` through `read_resource_contents`, which runs the server's read handler: its own,
+  # for resources and templates defined as classes, or one the developer set with `resources_read_handler`. It
+  # answers `prompts/get` through `get_prompt`, which refuses an unknown prompt and missing arguments before it calls
+  # `call_prompt_template_with_args`. Hooks on those three, prepended to one server's singleton class as the tool hooks
+  # are, see every read and get.
+  #
+  # What was asked for is named before anything runs, from the server's own records: a fixed resource by its URI, a
+  # templated one by its template, never by the address the client sent, and an address with neither by its scheme
+  # alone, since the rest of it came from the client.
+  module Primitives
+    # Set, fiber-locally, while an instrumented server gets a prompt, so it can see that the prompt was reached.
+    PROMPTING = :__mcpspan_prompt
+
+    SCHEME = /\A([a-zA-Z][a-zA-Z0-9+.-]*):/
+
+    # A template's `{name}` variables, as the gem matches them: one or more characters other than `/`.
+    VARIABLE = /\\\{([A-Za-z_]\w*)\\\}/
+
+    # The gem's private methods these hooks take the place of. A version without them leaves resources and prompts
+    # unrecorded, and tools measured as before.
+    HOOKED = %i[read_resource_contents get_prompt call_prompt_template_with_args].freeze
+
+    module_function
+
+    def hookable?
+      HOOKED.all? { |name| ::MCP::Server.private_method_defined?(name) }
+    end
+
+    # The scheme of an address, which is all of an unknown one that may be kept: `db://`.
+    def scheme(uri)
+      match = SCHEME.match(uri.to_s)
+      match ? "#{match[1]}://" : "unknown://"
+    end
+
+    # The name a read is recorded under, and the template's variables when a template matched it.
+    def resolve(uri, index, templates)
+      return [uri, nil] if index.is_a?(Hash) && index.key?(uri)
+
+      Array(templates).each do |template|
+        pattern = template.uri_template
+        next unless pattern.is_a?(String)
+
+        variables = match(pattern, uri)
+        return [pattern, variables] if variables
+      end
+      nil
+    end
+
+    def match(template, uri)
+      pattern = Regexp.escape(template).gsub(VARIABLE) { "(?<#{Regexp.last_match(1)}>[^/]+)" }
+      Regexp.new("\\A#{pattern}\\z").match(uri)&.named_captures
+    end
+
+    # Hooks prepended to one server's singleton class.
+    module ServerHooks
+      private
+
+      def read_resource_contents(request, session: nil, **rest)
+        call, known = __mcpspan_begin_read(request, session, rest[:envelope])
+        return super if call.nil?
+
+        begin
+          result = super
+        rescue ::MCP::CancelledError
+          raise
+        rescue StandardError => e
+          __mcpspan_read_failed(call, known, e)
+          raise
+        end
+        __mcpspan_succeeded(call, result)
+        result
+      end
+
+      def get_prompt(request, session: nil, **rest)
+        call, known = __mcpspan_begin_prompt(request, session, rest[:envelope])
+        return super if call.nil?
+
+        reached = [false]
+        outer = Thread.current[PROMPTING]
+        Thread.current[PROMPTING] = reached
+        begin
+          result = super
+        rescue ::MCP::CancelledError
+          raise
+        rescue StandardError => e
+          __mcpspan_prompt_failed(call, known, reached[0], e)
+          raise
+        ensure
+          Thread.current[PROMPTING] = outer
+        end
+        __mcpspan_succeeded(call, result)
+        result
+      end
+
+      def call_prompt_template_with_args(*args, **kwargs)
+        reached = Thread.current[PROMPTING]
+        reached[0] = true if reached
+        super
+      end
+
+      def __mcpspan_begin_read(request, session, envelope)
+        return nil unless Collector.collecting? && request.is_a?(Hash)
+
+        uri = request[:uri].to_s
+        name, variables = Primitives.resolve(uri, @resource_index, @resource_templates)
+        known = !name.nil?
+        call = Collector.begin_call(
+          known ? name : Primitives.scheme(uri),
+          arguments: variables,
+          session_id: Instrumentation.session_id(session),
+          server_version: Instrumentation.server_version(self),
+          **Instrumentation.client(envelope, session, self),
+          kind: "resource",
+        )
+        call && [call, known]
+      rescue *Instrumentation::INTERNAL
+        nil
+      end
+
+      def __mcpspan_begin_prompt(request, session, envelope)
+        return nil unless Collector.collecting? && request.is_a?(Hash)
+
+        name = request[:name]
+        call = Collector.begin_call(
+          name,
+          arguments: request[:arguments],
+          session_id: Instrumentation.session_id(session),
+          server_version: Instrumentation.server_version(self),
+          **Instrumentation.client(envelope, session, self),
+          kind: "prompt",
+        )
+        call && [call, @prompts.key?(name)]
+      rescue *Instrumentation::INTERNAL
+        nil
+      end
+
+      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)
+      rescue *Instrumentation::INTERNAL
+        nil
+      end
+
+      def __mcpspan_read_failed(call, known, error)
+        if !known && Instrumentation.named?(error, "MCP::Server::ResourceNotFoundError")
+          Collector.record(call, success: false, source: Source::UNKNOWN_RESOURCE)
+        else
+          __mcpspan_exception(call, error)
+        end
+      rescue *Instrumentation::INTERNAL
+        nil
+      end
+
+      def __mcpspan_prompt_failed(call, known, reached, error)
+        if !known
+          Collector.record(call, success: false, source: Source::UNKNOWN_PROMPT)
+        elsif !reached
+          # Only the gem's check for missing arguments stands between finding the prompt and calling it.
+          Collector.record(call, success: false, source: Source::ARGUMENTS)
+        else
+          __mcpspan_exception(call, error)
+        end
+      rescue *Instrumentation::INTERNAL
+        nil
+      end
+
+      def __mcpspan_exception(call, error)
+        original = error.respond_to?(:original_error) && error.original_error ? error.original_error : error
+        type, message = Instrumentation.exception(original)
+        Collector.record(call, success: false, source: Source::EXCEPTION, type: type, message: message)
+      end
+    end
+  end
+end

data/lib/mcpspan/reporter.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module McpSpan
+  # Collects events and delivers them from a thread of its own.
+  #
+  # `record` is the only method a tool call touches, and it only appends to memory under a lock: the call returns
+  # without waiting on the network.
+  class Reporter
+    DEFAULT_FLUSH_INTERVAL = 5.0
+    DEFAULT_MAX_BATCH_SIZE = 100
+    DEFAULT_MAX_QUEUE_SIZE = 10_000
+
+    # The wait after the n-th consecutive failure: doubling to a ceiling, spread over its second half.
+    def self.backoff(failures, random = rand)
+      ceiling = [1.0 * (2**[failures - 1, 16].min), 60.0].min
+      (ceiling / 2) + (random * ceiling / 2)
+    end
+
+    def initialize(endpoint:, send:, flush_interval:, max_batch_size:, max_queue_size:, debug:, on_diagnostic:)
+      @endpoint = endpoint
+      @send = send
+      @flush_interval = flush_interval
+      @max_batch_size = max_batch_size
+      @max_queue_size = max_queue_size
+      @debug = debug
+      @on_diagnostic = on_diagnostic
+      @lock = Mutex.new
+      @wake = ConditionVariable.new
+      # One delivery at a time, so the same events are never posted twice.
+      @sending = Mutex.new
+      @queue = []
+      @dropped = 0
+      @reported_drops = 0
+      @failures = 0
+      @next_attempt = nil
+      @woken = false
+      @stopped = false
+      @rejected = false
+      @thread = nil
+      @pid = nil
+    end
+
+    # Starts delivery, announcing the server first (contract, 3.4).
+    def start
+      @lock.synchronize { spawn }
+    end
+
+    # Queues an event and returns at once.
+    def record(event)
+      @lock.synchronize do
+        return if @stopped || @rejected
+
+        # A forked child, as a web server's worker is, inherits the queue but not the thread.
+        if @pid != Process.pid
+          @queue.clear
+          spawn
+        end
+        if @queue.size >= @max_queue_size
+          @queue.shift
+          @dropped += 1
+        end
+        @queue << event
+        if @queue.size >= @max_batch_size
+          @woken = true
+          @wake.signal
+        end
+      end
+    end
+
+    # Delivers what is queued now, ignoring any retry delay, and carries on.
+    def flush
+      deliver(force: true)
+    end
+
+    # Stops delivery and makes a final attempt at what is queued, ignoring any retry delay: this is the last chance
+    # these events get. A delivery already under way is waited for, rather than its events posted twice.
+    def stop
+      thread = @lock.synchronize do
+        @stopped = true
+        @woken = true
+        @wake.signal
+        @thread if @pid == Process.pid
+      end
+      thread&.join(Transport::TIMEOUT + 1)
+      deliver(force: true)
+    end
+
+    private
+
+    def spawn
+      @pid = Process.pid
+      @thread = Thread.new { run }
+      @thread.name = "mcpspan-delivery"
+      # A delivery thread must never be why a program does not exit, nor print a stray backtrace.
+      @thread.report_on_exception = false
+    end
+
+    def run
+      announce
+      loop do
+        @lock.synchronize do
+          deadline = monotonic + @flush_interval
+          until @woken || @stopped || @rejected
+            left = deadline - monotonic
+            break if left <= 0
+
+            @wake.wait(@lock, left)
+          end
+          @woken = false
+          return if @stopped || @rejected
+        end
+        deliver(force: false)
+      end
+    rescue StandardError => e
+      log("mcpspan: delivery stopped (#{e.class}: #{e.message})")
+    end
+
+    def announce
+      failure = @send.call([])
+      return if failure.nil?
+
+      if [401, 403].include?(failure.status)
+        reject(failure.status)
+      else
+        log("mcpspan: could not announce this server to #{@endpoint} (#{failure.message}). " \
+            "Events will still be delivered once it answers.")
+      end
+    end
+
+    def deliver(force:)
+      @lock.synchronize do
+        return if @rejected
+        return if !force && @next_attempt && monotonic < @next_attempt
+      end
+      @sending.synchronize do
+        report_drops
+        loop do
+          batch = @lock.synchronize do
+            return if @rejected
+
+            @queue.shift(@max_batch_size)
+          end
+          return if batch.empty?
+
+          failure = @send.call(batch)
+          if failure
+            failed(batch, failure)
+            return
+          end
+          @lock.synchronize do
+            @failures = 0
+            @next_attempt = nil
+          end
+        end
+      end
+    end
+
+    def report_drops
+      dropped = @lock.synchronize do
+        count = @dropped - @reported_drops
+        @reported_drops = @dropped
+        count
+      end
+      log("mcpspan: discarded #{dropped} events, the queue was full") if dropped.positive?
+    end
+
+    def failed(batch, failure)
+      return reject(failure.status) if [401, 403].include?(failure.status)
+
+      attempt = @lock.synchronize do
+        if failure.retryable
+          @queue.unshift(*batch)
+          while @queue.size > @max_queue_size
+            @queue.shift
+            @dropped += 1
+          end
+        end
+        @failures += 1
+        # The longer of our own backoff and what the API asked for.
+        @next_attempt = monotonic + [self.class.backoff(@failures), failure.retry_after].max
+        @failures
+      end
+      # Refused the same way every time: dropped, and collecting goes on.
+      log("mcpspan: dropped #{batch.size} events, rejected as #{failure.status}") unless failure.retryable
+      log("mcpspan: delivery failed (#{failure.message}), attempt #{attempt}")
+    end
+
+    # Gives up on a key the endpoint refused, and says so once even with diagnostics off: a silent SDK collecting
+    # nothing because of a mistyped key is the worst way to spend an afternoon.
+    def reject(status)
+      @lock.synchronize do
+        return if @rejected
+
+        @rejected = true
+        @queue.clear
+        @wake.signal
+      end
+      warn_always("mcpspan: the ingest endpoint rejected the API key (HTTP #{status}). " \
+                  "Telemetry is now disabled for this process.")
+    end
+
+    def log(message)
+      warn_always(message) if @debug
+    end
+
+    # The developer's callback if given, otherwise standard error. Never standard output: on the stdio transport it
+    # carries the MCP protocol, and a stray line there breaks the server.
+    def warn_always(message)
+      if @on_diagnostic
+        @on_diagnostic.call(message)
+      else
+        warn(message)
+      end
+    rescue StandardError
+      nil
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

data/lib/mcpspan/text.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module McpSpan
+  # Limits the ingest API enforces, and the text that has to fit them. A batch holding one field over its limit is
+  # refused whole, so everything that comes from outside the developer's control is cut before it is sent.
+  module Text
+    MAX_NAME = 200
+    MAX_EXCEPTION_MESSAGE = 500
+    MAX_RESULT_MESSAGE = 200
+    MAX_DESCRIBED_PARAMETERS = 50
+    # 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.
+    def truncate(text, limit)
+      text = text.to_s
+      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
+
+    def client_name(name)
+      return nil if name.nil? || name.strip.empty?
+
+      truncate(name, MAX_NAME)
+    end
+
+    def version(version)
+      version = version.to_s.strip
+      version.empty? ? nil : truncate(version, MAX_VERSION)
+    end
+
+    # Parameter names and their JSON types. Values are never read beyond their type.
+    def describe_parameters(arguments)
+      return nil unless arguments.is_a?(Hash) && !arguments.empty?
+
+      arguments.first(MAX_DESCRIBED_PARAMETERS).to_h do |name, value|
+        [truncate(name, MAX_NAME), json_type(value)]
+      end
+    end
+
+    def json_type(value)
+      case value
+      when nil then "null"
+      when true, false then "boolean"
+      when Numeric then "number"
+      when String, Symbol then "string"
+      when Array then "array"
+      else "object"
+      end
+    end
+  end
+end