mcpspan 0.1.0

data/lib/mcpspan/transport.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "time"
+require "uri"
+
+module McpSpan
+  # A delivery that did not succeed, and whether sending the same batch again could work.
+  Failure = Struct.new(:message, :status, :retryable, :retry_after, keyword_init: true)
+
+  # Posts batches to the ingest API. It neither retries nor swallows: it answers nil for a delivery, or a Failure.
+  class Transport
+    TIMEOUT = 10
+    # The longest Retry-After followed: a server asking for longer is wrong or unwell.
+    MAX_RETRY_AFTER = 300
+
+    def initialize(endpoint, api_key)
+      @uri = URI.join("#{endpoint.chomp("/")}/", "v1/events")
+      @headers = {
+        "Content-Type" => "application/json",
+        "Authorization" => "Bearer #{api_key}",
+        "User-Agent" => "mcpspan/#{VERSION} (ruby)",
+      }
+    end
+
+    def call(events)
+      http = Net::HTTP.new(@uri.host, @uri.port)
+      http.use_ssl = @uri.scheme == "https"
+      http.open_timeout = http.read_timeout = http.write_timeout = TIMEOUT
+      # Net::HTTP never follows a redirect, which is what we want: a redirected POST delivers nothing.
+      response = http.post(@uri.request_uri, Event.batch(events), @headers)
+      status = response.code.to_i
+      return nil if (200..299).cover?(status)
+
+      Failure.new(
+        message: "ingest API answered #{status}",
+        status: status,
+        retryable: status == 408 || status == 429 || status >= 500,
+        retry_after: self.class.retry_after(response["retry-after"]),
+      )
+    rescue StandardError => e
+      # Unreachable, reset, timed out: the moment, not the batch.
+      Failure.new(message: "failed to reach #{@uri} (#{e.class}: #{e.message})", status: nil, retryable: true,
+                  retry_after: 0,)
+    end
+
+    # Retry-After in either form, whole seconds or an HTTP date. Zero leaves the SDK's own backoff to decide.
+    def self.retry_after(value, now: Time.now)
+      return 0 if value.nil?
+
+      value = value.strip
+      wait = if value.match?(/\A\d+\z/)
+               value.to_i
+             else
+               begin
+                 Time.httpdate(value) - now
+               rescue ArgumentError
+                 0
+               end
+             end
+      wait.clamp(0, MAX_RETRY_AFTER)
+    end
+  end
+end

data/lib/mcpspan/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module McpSpan
+  # The SDK's own version, reported with every event.
+  VERSION = "0.1.0"
+end

data/lib/mcpspan.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative "mcpspan/version"
+require_relative "mcpspan/text"
+require_relative "mcpspan/event"
+require_relative "mcpspan/transport"
+require_relative "mcpspan/reporter"
+require_relative "mcpspan/collector"
+require_relative "mcpspan/instrumentation"
+require_relative "mcpspan/primitives"
+
+# Analytics for MCP servers: which tools are called, by which client, how long they take, and which ones fail.
+#
+#   server = MCP::Server.new(name: "flights", tools: [SearchFlights])
+#   McpSpan.instrument(server, api_key: ENV["MCPSPAN_API_KEY"], endpoint: "http://localhost:6271")
+#
+# 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.
+module McpSpan
+  @excluded_names = Set.new
+
+  class << self
+    # Tool names left out with {exclude}.
+    attr_reader :excluded_names
+
+    # Measures every tool on a server built on the `mcp` gem, whether it was added before this call or after.
+    # Configures with +settings+ when given, else from the environment unless already configured. Returns the
+    # server.
+    def instrument(server, **settings)
+      if !settings.empty?
+        configure(**settings)
+      elsif !collecting?
+        configure
+      end
+      Instrumentation.instrument(server)
+    rescue StandardError
+      server
+    end
+
+    # Starts collecting, or stops if there is no key to collect with. Configuring again with the same settings
+    # changes nothing, so a server built per request can call it every time; different settings replace the running
+    # configuration, delivering what it held.
+    def configure(**settings)
+      Collector.configure(settings)
+      nil
+    rescue StandardError => e
+      warn("mcpspan: could not configure (#{e.class}: #{e.message})") if settings[:debug]
+      nil
+    end
+
+    # Stops collecting and delivers what is queued, ignoring any wait for a retry: it is the last chance these
+    # events get. What is queued is also delivered as the program exits, so most servers need not call this.
+    def shutdown
+      Collector.shutdown
+      nil
+    rescue StandardError
+      nil
+    end
+
+    # Whether an API key is configured and calls are being recorded.
+    def collecting?
+      Collector.collecting?
+    end
+
+    # Measures one tool class, for a server {instrument} does not cover. On an instrumented server it is counted
+    # once. Returns the tool.
+    def track(tool)
+      if tool.respond_to?(:call) && tool.respond_to?(:name_value) && !tool.singleton_class.include?(Instrumentation::ToolHooks)
+        tool.singleton_class.prepend(Instrumentation::ToolHooks)
+      end
+      tool
+    end
+
+    # Leaves a tool out: its calls, refused ones included, are not recorded. Takes the tool class, so a rename
+    # carries the exclusion along, or its name, for a tool made with +define_tool+. Returns what it was given.
+    def exclude(tool)
+      if tool.is_a?(String) || tool.is_a?(Symbol)
+        @excluded_names << tool.to_s
+      else
+        tool.instance_variable_set(:@__mcpspan_excluded, true)
+      end
+      tool
+    end
+  end
+end

metadata

@@ -0,0 +1,55 @@
+--- !ruby/object:Gem::Specification
+name: mcpspan
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kacper Zatoń
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: 'Measures the tools of a server built on the official Ruby MCP SDK: which
+  get called, by which client, how long they take and which fail. Parameter values
+  never leave the process.'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/mcpspan.rb
+- lib/mcpspan/collector.rb
+- lib/mcpspan/event.rb
+- lib/mcpspan/instrumentation.rb
+- lib/mcpspan/primitives.rb
+- lib/mcpspan/reporter.rb
+- lib/mcpspan/text.rb
+- lib/mcpspan/transport.rb
+- lib/mcpspan/version.rb
+homepage: https://github.com/mcpspan/mcpspan
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/mcpspan/mcpspan/tree/main/packages/mcpspan-ruby
+  bug_tracker_uri: https://github.com/mcpspan/mcpspan/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.20
+specification_version: 4
+summary: 'Self-hosted analytics for MCP servers: which tools, resources and prompts
+  get used, by which client, how fast, and why they fail.'
+test_files: []