mcpulse 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f94e04b6545f611b806eec5c45cb9eb372002ca6ab480166a53c2fae50b6b653
+  data.tar.gz: 72899707fa300d39372d397297e445f29f0032ca6c96a570e0b12f895695e1f1
+SHA512:
+  metadata.gz: e81096f3940e671d6f1961312b82ca4aac82a72238f0f3acccf3348c4a1689ca30fffabb64b170ee36dec465d3363a627d553f3ec357ae0360f7549c4d200b94
+  data.tar.gz: f04005d8f6ee55d394c6eb29eba129f19d8cb2a8cb6281f6e851e39b7c69b66f44d32dd347e4f342cd57f8c25a1ac7bbe0e99ff63f01b44567460d71c7c4fd6a

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MCPulse
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,100 @@
+# mcpulse
+
+Analytics for MCP servers, in Ruby.
+
+```ruby
+require "mcpulse"
+
+MCPulse.configure(key: "mp_live_…")
+
+# Around your tool handler:
+MCPulse.record("search", arguments, client_name: client) do
+  my_handler.call(arguments)
+end
+```
+
+Wrapping the handler rather than watching from outside is what lets MCPulse tell
+a handler that raised from one that returned an error result — a distinction an
+MCP server erases by converting both into `isError` before anything outside sees
+it.
+
+## Install
+
+```ruby
+gem "mcpulse"
+```
+
+No runtime dependencies. This gem loads into other people's servers, and a
+dependency that conflicts with what the customer already bundles is a support
+burden with no upside for a single POST.
+
+## Options
+
+| Keyword | Default | Meaning |
+|---|---|---|
+| `key:` | — | Ingest key, `mp_live_…`, minted per MCP in the dashboard |
+| `endpoint:` | `https://api.getmcpulse.com` | Point at a local API while developing |
+| `enabled:` | `true` | `false` makes everything a no-op — useful in tests and CI |
+| `debug:` | `false` | Log what is sent, and why a send failed, to **stderr** |
+
+An empty key turns it off, so a server started without its key configured is
+silent rather than a source of 401s on every flush.
+
+## Reporting your tools
+
+```ruby
+MCPulse.record_startup(tools_list_response, client_name: client)
+```
+
+Pass the JSON your `tools/list` returns — `schema_bytes` is the cost of a tool's
+presence in the context window, so it has to be measured on what actually goes
+over the wire.
+
+## One known gap
+
+`bad_args` is not reported. A server that validates arguments before calling the
+handler rejects them outside the block, so the call never reaches `record`.
+Reporting it anyway would mean reading the difference back out of an error
+message, and error strings are not an interface anyone promised to keep. `ok`,
+`tool_error` and `crashed` are all exact.
+
+## What leaves your process
+
+Sizes and hashes. Arguments and results do not, and no option turns that on.
+
+## The three rules
+
+1. **Never raise.** Every entry point rescues. Your exception is re-raised
+   untouched; ours never reach you.
+2. **Never block.** A `Thread` with its own array rather than a sized `Queue` —
+   a bounded `Queue#push` blocks when full, which is exactly what must not
+   happen on the path a model is waiting on. This drops the oldest entry instead.
+3. **Never store customer data.** See above.
+
+## Cross-language consistency
+
+`args_hash` is the first 12 hex characters of the SHA-256 of the
+[RFC 8785](https://www.rfc-editor.org/rfc/rfc8785) canonical form of the
+arguments. `spec/fixtures/canonical.json` is the shared conformance suite every
+MCPulse SDK runs.
+
+Ruby needed three things undone: `Float#to_s` writes `1.0` and `1.0e-07` where
+ECMAScript writes `1` and `1e-7`; `JSON.generate` leaves keys in insertion
+order; and RFC 8785 sorts keys by UTF-16 code unit while Ruby compares UTF-8
+bytes — the two disagree above the BMP, where U+1F680 (the surrogate pair D83D
+DE80) sorts *before* U+FFFD.
+
+Symbol-keyed hashes canonicalise identically to string-keyed ones, which matters
+because that is what most Ruby MCP servers actually hold.
+
+## Running the tests
+
+```bash
+ruby spec/run.rb
+```
+
+No gems needed.
+
+## Licence
+
+MIT

data/lib/mcpulse/buffer.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require_relative 'options'
+require_relative 'transport'
+
+module MCPulse
+  # Holds payloads and sends them in batches, on a thread of its own.
+  #
+  # The contract with the tool call that produced a payload is that +add+ returns immediately and
+  # never raises. Everything expensive happens on a background thread, so no model ever waits on
+  # MCPulse to answer.
+  #
+  # A Thread rather than a Fiber or a queue with a bound: a bounded +Queue#push+ blocks when full,
+  # which is exactly what must never happen on the path a model is waiting on. This keeps its own
+  # array and drops the oldest entry instead.
+  class PayloadBuffer
+    def initialize(options, log)
+      @options = options
+      @log = log
+
+      @mutex = Mutex.new
+      @wake = ConditionVariable.new
+      @pending = []
+      @closed = false
+      # Held for the duration of a batch, so a flush waits for a real send.
+      @sending = Mutex.new
+
+      @worker = Thread.new { run }
+      # Never hold the customer's process open over analytics.
+      @worker.abort_on_exception = false
+    end
+
+    # Buffers one payload. Returns immediately, never raises.
+    def add(payload)
+      ready = false
+
+      @mutex.synchronize do
+        return if @closed
+
+        if @pending.size >= Options::MAX_BUFFERED
+          # Oldest first: recent calls describe what the server is doing now, and that is the more
+          # useful half of a buffer that could not be sent.
+          @pending.shift
+          @log.call('buffer full, dropped oldest payload')
+        end
+
+        @pending << payload
+        ready = @pending.size >= Options::FLUSH_AT_ITEMS
+        @wake.signal if ready
+      end
+
+      nil
+    rescue StandardError
+      # Recording must never be the reason a tool call fails.
+      nil
+    end
+
+    # Final flush, best effort. After this the buffer accepts nothing more.
+    def close(timeout: Options::EXIT_FLUSH_SECONDS)
+      @mutex.synchronize do
+        return if @closed
+
+        @closed = true
+        @wake.broadcast
+      end
+
+      send_once
+      @worker.join(timeout)
+      nil
+    rescue StandardError
+      nil
+    end
+
+    private
+
+    def run
+      loop do
+        @mutex.synchronize do
+          # Either something asked for a flush, or the five seconds elapsed.
+          @wake.wait(@mutex, Options::FLUSH_EVERY_SECONDS) if @pending.empty? && !@closed
+        end
+
+        send_once
+
+        break if @mutex.synchronize { @closed && @pending.empty? }
+      end
+    rescue StandardError => e
+      @log.call('sender stopped', e)
+    end
+
+    def send_once
+      @sending.synchronize do
+        batch = @mutex.synchronize do
+          next [] if @pending.empty?
+
+          # Taken in one go: anything added while this is in flight belongs to the next batch, not
+          # this one.
+          @pending.slice!(0, @pending.size)
+        end
+        return if batch.empty?
+
+        sent = Transport.post_batch(batch, @options)
+        @log.call("#{sent ? 'sent' : 'dropped'} #{batch.size} payloads")
+      end
+    rescue StandardError => e
+      @log.call('send failed', e)
+    end
+  end
+end

data/lib/mcpulse/canonical.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+module MCPulse
+  # JSON Canonicalization Scheme (RFC 8785).
+  #
+  # +args_hash+ only means anything if every MCPulse SDK, in every language, turns the same
+  # arguments into the same bytes. Ruby's +JSON.generate+ does not get there on its own: it writes
+  # +1.0+ where ECMAScript writes +1+, it leaves keys in insertion order, and Ruby's own string
+  # ordering is by UTF-8 byte where JCS sorts by UTF-16 code unit. Each of those silently sends the
+  # same call to a different bucket than the TypeScript SDK would.
+  #
+  # So none of the serialisation below goes through +JSON+. Every rule is spelled out, and
+  # +spec/fixtures/canonical.json+ — the same file every other MCPulse SDK runs — is what holds
+  # this module to them.
+  module Canonical
+    # Raised for anything JSON cannot represent: a NaN, an infinity, a cycle, an unknown type.
+    class NotJSON < StandardError; end
+
+    SHORT_ESCAPES = {
+      "\b" => '\b',
+      "\t" => '\t',
+      "\n" => '\n',
+      "\f" => '\f',
+      "\r" => '\r',
+      '"' => '\"',
+      '\\' => '\\\\'
+    }.freeze
+
+    module_function
+
+    # The canonical JSON form of +value+, as a UTF-8 String.
+    def canonicalize(value)
+      out = +''
+      write(out, value, [])
+      out
+    end
+
+    def write(out, value, seen)
+      case value
+      when nil then out << 'null'
+      when true then out << 'true'
+      when false then out << 'false'
+      when String, Symbol then write_string(out, value.to_s)
+      # Numeric covers Integer, Float, Rational and BigDecimal. Anything Float() cannot accept —
+      # a Complex, say — raises below and becomes a NotJSON, which is the right answer for it.
+      when Numeric then write_number(out, value)
+      when Array then write_array(out, value, seen)
+      when Hash then write_object(out, value, seen)
+      else
+        # A struct, or an object that knows how to become JSON. Round-trip it so it arrives here
+        # as one of the shapes above; the escaping its encoder applies on the way out is undone by
+        # the parse on the way back in, so it cannot leak into the canonical form.
+        write_via_json(out, value, seen)
+      end
+    end
+
+    def write_via_json(out, value, seen)
+      raise NotJSON, "cannot canonicalize #{value.class}" unless value.respond_to?(:to_json)
+
+      decoded = JSON.parse(value.to_json)
+      write(out, decoded, seen)
+    rescue JSON::JSONError, NoMethodError => e
+      raise NotJSON, "cannot canonicalize #{value.class}: #{e.message}"
+    end
+
+    def write_array(out, value, seen)
+      raise NotJSON, 'circular structure' if seen.any? { |item| item.equal?(value) }
+
+      seen.push(value)
+      out << '['
+      value.each_with_index do |item, index|
+        out << ',' if index.positive?
+        write(out, item, seen)
+      end
+      out << ']'
+      seen.pop
+    end
+
+    def write_object(out, value, seen)
+      raise NotJSON, 'circular structure' if seen.any? { |item| item.equal?(value) }
+
+      seen.push(value)
+      out << '{'
+      # Keys are carried alongside their original form, so a symbol-keyed Hash — which is what a
+      # Ruby MCP server most often has — still finds its values after sorting by the string.
+      sorted_entries(value).each_with_index do |(name, original), index|
+        out << ',' if index.positive?
+        write_string(out, name)
+        out << ':'
+        write(out, value[original], seen)
+      end
+      out << '}'
+      seen.pop
+    end
+
+    # Keys in RFC 8785 order: by UTF-16 code unit, not by UTF-8 byte.
+    #
+    # The two agree for everything in the Basic Multilingual Plane and disagree above it. U+1F680
+    # encodes as the surrogate pair D83D DE80, so JCS sorts it *before* U+FFFD while Ruby's default
+    # comparison puts it after. Encoding to UTF-16BE and comparing bytes is exactly the code-unit
+    # comparison JCS asks for.
+    def sorted_entries(hash)
+      hash.keys.map do |key|
+        unless key.is_a?(String) || key.is_a?(Symbol)
+          raise NotJSON, "object key must be a string, got #{key.class}"
+        end
+
+        [key.to_s, key]
+      end.sort_by { |(name, _original)| utf16_bytes(name) }
+    end
+
+    def utf16_bytes(text)
+      text.encode(Encoding::UTF_16BE, invalid: :replace, undef: :replace).bytes
+    rescue Encoding::UndefinedConversionError, Encoding::InvalidByteSequenceError
+      text.bytes
+    end
+
+    # ─── Strings ───────────────────────────────────────────────────────────────
+
+    # A JSON string per JCS 3.2.2.2, which is ECMAScript's escaping: the short escapes where one
+    # exists, lowercase \u00xx for the rest of the C0 range, and nothing else touched.
+    #
+    # In particular non-ASCII is written literally, and so are <, > and &.
+    def write_string(out, text)
+      out << '"'
+      text.each_char do |char|
+        short = SHORT_ESCAPES[char]
+        if short
+          out << short
+        elsif char.ord < 0x20
+          out << format('\u%04x', char.ord)
+        else
+          out << char
+        end
+      end
+      out << '"'
+    end
+
+    # ─── Numbers ───────────────────────────────────────────────────────────────
+
+    # ECMAScript +Number::toString+, which is what JCS 3.2.2.3 defers to.
+    #
+    # Every number is treated as an IEEE-754 double, including Ruby's arbitrary-precision Integer:
+    # RFC 8785 limits JSON to double precision, and matching JavaScript is the entire point. An
+    # integer past 2**53 therefore loses precision here exactly as it would there, which is what
+    # keeps the two SDKs' hashes equal.
+    def write_number(out, value)
+      number = Float(value)
+      raise NotJSON, 'non-finite number' if number.nan? || number.infinite?
+
+      if number.zero?
+        # Covers -0.0, which JCS writes as "0".
+        out << '0'
+        return
+      end
+
+      if number.negative?
+        out << '-'
+        number = -number
+      end
+
+      digits, n = shortest(number)
+      k = digits.length
+
+      # The five cases of ECMAScript Number::toString, in its own order.
+      if k <= n && n <= 21
+        out << digits << ('0' * (n - k))
+      elsif n.positive? && n <= 21
+        out << digits[0, n] << '.' << digits[n..]
+      elsif n > -6 && n <= 0
+        out << '0.' << ('0' * -n) << digits
+      else
+        exponent = n - 1
+        out << (k == 1 ? digits : "#{digits[0]}.#{digits[1..]}")
+        out << 'e' << (exponent.negative? ? '-' : '+') << exponent.abs.to_s
+      end
+    rescue TypeError, RangeError => e
+      raise NotJSON, "number out of range: #{e.message}"
+    end
+
+    # Decomposes a positive finite double into its shortest round-tripping digits and the position
+    # of the decimal point: the value is +digits * 10**(n - digits.length)+.
+    #
+    # Ruby's +Float#to_s+ is already shortest-round-tripping, so this only has to re-read it — the
+    # exponent formatting is what differs between the two languages, not the digits.
+    def shortest(number)
+      formatted = number.to_s
+      mantissa, exponent_text = formatted.split(/e/i, 2)
+      exponent = exponent_text ? exponent_text.to_i : 0
+
+      integer_part, fraction_part = mantissa.split('.', 2)
+      fraction_part ||= ''
+      digits = "#{integer_part}#{fraction_part}"
+      n = exponent + integer_part.length
+
+      stripped = digits.sub(/\A0+/, '')
+      n -= digits.length - stripped.length
+      digits = stripped.sub(/0+\z/, '')
+
+      digits.empty? ? ['0', 1] : [digits, n]
+    end
+  end
+end

data/lib/mcpulse/emptiness.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module MCPulse
+  # Did this call succeed while returning nothing useful?
+  #
+  # This is the metric that catches the failures nobody reports: a search that finds no rows, a
+  # lookup that misses, a query that comes back +[]+. The protocol calls all of those success, the
+  # model gets nothing it can use, and the author never hears about it.
+  #
+  # Only ever asked of a call that already succeeded — an error has its own outcome and is not also
+  # "empty".
+  module Emptiness
+    module_function
+
+    def empty_result?(result)
+      return true if result.nil?
+
+      structured = member(result, 'structuredContent')
+      unless structured.nil?
+        inner = unwrap_result_envelope(structured)
+        # What comes out of the envelope is whatever the tool returned. When that is a string it
+        # gets the same reading a text part does.
+        return inner.is_a?(String) ? hollow_text?(inner) : hollow?(inner)
+      end
+
+      content = member(result, 'content')
+      return empty_content?(content) if content.is_a?(Array)
+
+      # Not a tool result shape at all — judge the thing itself.
+      hollow?(result)
+    end
+
+    # Undoes a single-key <tt>{"result" => …}</tt> wrapper.
+    #
+    # SDKs that derive an output schema from a handler's return type wrap a non-object return: a
+    # tool that returns +"[]"+ arrives as <tt>{"result" => "[]"}</tt>. Judging the envelope would
+    # quietly kill this metric — every result would be a Hash with one key, so nothing would ever
+    # be empty, and the one thing +is_empty+ exists to catch would never fire.
+    def unwrap_result_envelope(structured)
+      return structured unless structured.is_a?(Hash) && structured.size == 1
+
+      structured['result'] || structured[:result] || structured
+    end
+
+    # MCP returns content as a list of parts.
+    #
+    # No parts is empty. One text part is the common case, and it is empty when the text is blank
+    # or when the text is itself a serialised empty collection — +"[]"+ is the single most common
+    # way a tool says "nothing found" while reporting success.
+    def empty_content?(content)
+      return true if content.empty?
+      return false if content.size > 1
+
+      part = content.first
+      return false unless member(part, 'type') == 'text'
+
+      text = member(part, 'text')
+      text.is_a?(String) && hollow_text?(text)
+    end
+
+    def hollow_text?(text)
+      trimmed = text.strip
+      return true if trimmed.empty?
+
+      hollow?(JSON.parse(trimmed))
+    rescue JSON::ParserError
+      # Prose, not JSON. A tool that answers in a sentence has said something.
+      false
+    end
+
+    # Empty array, empty hash, blank string, or nothing at all.
+    def hollow?(value)
+      case value
+      when nil then true
+      when String then value.strip.empty?
+      when Array, Hash then value.empty?
+      else
+        # A number or a boolean is an answer. 0 and false are results, not absences, and counting
+        # them as empty would report working tools as broken.
+        false
+      end
+    end
+
+    # Reads a named member off a Hash with either key type, or off an object with a reader.
+    def member(value, name)
+      case value
+      when nil then nil
+      when Hash then value[name].nil? ? value[name.to_sym] : value[name]
+      else
+        value.respond_to?(name) ? value.public_send(name) : nil
+      end
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/mcpulse/hashing.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'securerandom'
+
+require_relative 'canonical'
+
+module MCPulse
+  # Fingerprinting a call's arguments.
+  module Hashing
+    # What an argument set hashes to when it cannot be serialised at all.
+    UNHASHABLE = '000000000000'
+
+    module_function
+
+    # A short, one-way fingerprint of a call's arguments.
+    #
+    # This is the only thing MCPulse ever learns about what was passed to a tool, and it is
+    # deliberately not enough to learn anything: 12 hex characters of a SHA-256 over the RFC 8785
+    # canonical form, with no way back. All the product asks of it is "were these two calls made
+    # with the same arguments or different ones" — which is what separates a model retrying a
+    # reworded request from a client paging through results.
+    def args_hash(args)
+      # A tool that takes no arguments is called with +arguments+ absent. That is an ordinary
+      # call, not a failure, and it hashes as the empty object it is — otherwise every no-argument
+      # tool shares one hash with every call whose arguments blew up.
+      value = args.nil? ? {} : args
+
+      Digest::SHA256.hexdigest(Canonical.canonicalize(value))[0, 12]
+    rescue StandardError
+      # Arguments JSON cannot represent. The call still happened and still deserves a row; it
+      # simply cannot be compared to another, so give it a constant that says exactly that.
+      UNHASHABLE
+    end
+
+    # Identifies one run of the customer's server, so calls can be grouped and a cost-per-session
+    # worked out.
+    #
+    # Random rather than derived — there is nothing about the process worth encoding here, and
+    # anything derived from the machine would be an identifier we did not intend to collect.
+    def new_session_id
+      "s_#{SecureRandom.hex(6)}"
+    end
+  end
+end

data/lib/mcpulse/logger.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module MCPulse
+  # Debug output, on stderr.
+  #
+  # stdout is the transport for a stdio MCP server — a single stray line there corrupts the
+  # JSON-RPC stream and takes the customer's server down with it. This is the one thing in the gem
+  # that would be trivially easy to get wrong and catastrophic to ship, so it goes through one
+  # place.
+  #
+  # Deliberately not +Logger+ or a Rails logger: a library that writes through the host's
+  # configuration can end up on stdout because of a setting it never saw.
+  class DebugLog
+    def initialize(debug)
+      @debug = debug
+    end
+
+    def call(message, detail = nil)
+      return unless @debug
+
+      suffix = detail.nil? ? '' : " #{format_detail(detail)}"
+      warn("[mcpulse] #{message}#{suffix}")
+    rescue StandardError
+      # Logging is never worth an exception.
+      nil
+    end
+
+    private
+
+    def format_detail(detail)
+      detail.is_a?(Exception) ? "#{detail.class}: #{detail.message}" : detail.to_s
+    end
+  end
+end

data/lib/mcpulse/options.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module MCPulse
+  # Everything +MCPulse.watch+ accepts, and what it means when you leave it out.
+  class Options
+    # Where payloads go when no endpoint is given.
+    DEFAULT_ENDPOINT = 'https://api.getmcpulse.com'
+
+    # Flush when either is reached, whichever comes first.
+    FLUSH_AT_ITEMS = 30
+    FLUSH_EVERY_SECONDS = 5.0
+
+    # Hard ceiling on the buffer. Reached only when the network is gone; past it the oldest
+    # payloads are dropped, because a customer's server running out of memory over our analytics
+    # is the one failure we must never cause.
+    MAX_BUFFERED = 1000
+
+    # Best-effort window for the final flush on the way out, and the cap on one batch.
+    EXIT_FLUSH_SECONDS = 1.0
+    SEND_TIMEOUT_SECONDS = 10.0
+
+    # Caps, so one malformed name cannot bloat a batch.
+    MAX_TOOL_NAME = 200
+    MAX_CLIENT_NAME = 128
+    MAX_TOOLS = 500
+
+    attr_reader :key, :endpoint
+
+    def initialize(key:, endpoint: nil, enabled: true, debug: false)
+      @key = key.is_a?(String) ? key.strip : ''
+      target = endpoint.is_a?(String) && !endpoint.strip.empty? ? endpoint : DEFAULT_ENDPOINT
+      @endpoint = target.sub(%r{/+\z}, '')
+      @enabled = enabled
+      @debug = debug
+    end
+
+    def debug?
+      @debug
+    end
+
+    # Whether anything should be recorded at all.
+    #
+    # An empty key turns the SDK off: a server started without its key configured should be
+    # silent, not a source of 401s on every flush.
+    def active?
+      @enabled && !@key.empty?
+    end
+
+    def stream_key
+      "#{@endpoint}|#{@key}"
+    end
+  end
+
+  # How a tool call ended. Exactly one of these, always.
+  module Outcome
+    OK = 'ok'
+    BAD_ARGS = 'bad_args'
+    TOOL_ERROR = 'tool_error'
+    CRASHED = 'crashed'
+
+    ALL = [OK, BAD_ARGS, TOOL_ERROR, CRASHED].freeze
+  end
+
+  # How MCPulse measures what a payload costs a context window.
+  module Sizes
+    module_function
+
+    # The length of +text+ in UTF-16 code units.
+    #
+    # +response_bytes+ and +schema_bytes+ are, today, what JavaScript's +String.length+ returns —
+    # code units, not bytes. The fields are named for bytes and hold code units, so "café" measures
+    # 4 and an emoji measures 2.
+    #
+    # That is a known wart in the wire format, and fixing it is a pending decision. Until it is
+    # made, every port reproduces the TypeScript behaviour rather than each inventing its own,
+    # because the whole value of these numbers is that they are comparable across a customer's
+    # servers. When the wire fixes it, this method is the one line that changes.
+    def utf16_length(text)
+      text.encode(Encoding::UTF_16BE, invalid: :replace, undef: :replace).bytesize / 2
+    rescue StandardError
+      text.length
+    end
+  end
+end

data/lib/mcpulse/stream.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require_relative 'buffer'
+require_relative 'hashing'
+
+module MCPulse
+  # One session and one buffer per destination, for the life of the process.
+  #
+  # The obvious shape is to make both where the server is built, which is right for a stdio server
+  # — one process, one server, one session — and wrong for an HTTP one. A streamable-HTTP server
+  # builds a fresh handler per request, and every tool call would become a session of its own.
+  #
+  # That is not a cosmetic difference. Retries are found by looking for the same tool twice inside
+  # one session, and first-call success is defined as no retry following. With one call per session
+  # there can never be a retry, so the server reports a perfect score however badly it is doing —
+  # the one number this product exists to tell the truth about.
+  #
+  # Keyed by endpoint and key rather than a bare singleton: two watched servers reporting to
+  # different MCPs in one process are two different streams, and merging them would file one
+  # customer's calls under another's.
+  class Stream
+    attr_reader :session_id, :buffer, :log
+
+    # Diverts payloads away from the buffer. Only tests set it.
+    class << self
+      attr_accessor :sink
+    end
+
+    def initialize(options, log)
+      @session_id = Hashing.new_session_id
+      @buffer = PayloadBuffer.new(options, log)
+      @log = log
+      @client_name = 'unknown'
+      @startup_sent = false
+      @mutex = Mutex.new
+    end
+
+    # Whoever most recently identified themselves.
+    #
+    # One value per process per destination, last identification wins. For a server with two
+    # concurrent clients that is an approximation, but it is the same approximation the shared
+    # session already makes, and a name that is occasionally the other client's beats a column
+    # that is always "unknown".
+    def client_name
+      @mutex.synchronize { @client_name }
+    end
+
+    def remember_client(name)
+      return if name.nil? || !name.is_a?(String) || name.empty?
+
+      @mutex.synchronize { @client_name = name[0, Options::MAX_CLIENT_NAME] }
+    end
+
+    def claim_startup
+      @mutex.synchronize do
+        return false if @startup_sent
+
+        @startup_sent = true
+        true
+      end
+    end
+
+    # Hands one payload to the buffer, or to a test's capture.
+    def emit(payload)
+      capture = self.class.sink
+      return capture.call(payload) if capture
+
+      @buffer.add(payload)
+    end
+
+    @streams = {}
+    @registry_mutex = Mutex.new
+    @hook_registered = false
+
+    class << self
+      def for(options, log)
+        @registry_mutex.synchronize do
+          existing = @streams[options.stream_key]
+          return existing if existing
+
+          created = new(options, log)
+          @streams[options.stream_key] = created
+
+          unless @hook_registered
+            # Registered once for the whole gem, however many servers are watched. at_exit runs
+            # before the interpreter tears the threads down, which is what makes the final flush
+            # possible at all.
+            @hook_registered = true
+            at_exit { flush_all }
+          end
+
+          created
+        end
+      end
+
+      # One last flush on the way out, so the final few calls of a session are not lost.
+      def flush_all
+        pending = @registry_mutex.synchronize do
+          taken = @streams.values
+          @streams = {}
+          taken
+        end
+
+        pending.each do |stream|
+          stream.buffer.close
+        rescue StandardError
+          nil
+        end
+      end
+
+      # Only tests reach for this.
+      def reset!
+        @registry_mutex.synchronize { @streams = {} }
+      end
+    end
+  end
+end

data/lib/mcpulse/transport.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'net/http'
+require 'uri'
+
+require_relative 'options'
+
+module MCPulse
+  # Posting one batch.
+  #
+  # +net/http+ from the standard library rather than Faraday or HTTParty: this gem loads into other
+  # people's servers, and a dependency that conflicts with what the customer already bundles is a
+  # support burden with no upside for a single POST. It runs on a background thread, so blocking
+  # here costs nothing.
+  module Transport
+    module_function
+
+    # Sends one batch and reports whether it landed. Never raises — a caller must not have to
+    # rescue.
+    #
+    # A failed batch is dropped, deliberately. Retrying means either a queue that grows while the
+    # network is down, or duplicate rows when a 202 is lost on the way back. Neither is worth it
+    # for analytics: the next flush is five seconds away, and a gap in a chart is a far smaller
+    # problem than memory growth inside someone else's server.
+    def post_batch(payloads, options, timeout: Options::SEND_TIMEOUT_SECONDS)
+      return true if payloads.empty?
+
+      uri = URI.parse("#{options.endpoint}/v1/ingest")
+      body = JSON.generate({ batch: payloads })
+
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == 'https'
+      http.open_timeout = timeout
+      http.read_timeout = timeout
+      http.write_timeout = timeout if http.respond_to?(:write_timeout=)
+
+      request = Net::HTTP::Post.new(uri.request_uri)
+      request['content-type'] = 'application/json'
+      request['authorization'] = "Bearer #{options.key}"
+      request['user-agent'] = 'mcpulse-ruby'
+      request.body = body
+
+      response = http.request(request)
+      response.code.to_i.between?(200, 299)
+    rescue StandardError
+      # DNS, TLS, a timeout, a proxy that hung up. All the same to us.
+      false
+    end
+  end
+end

data/lib/mcpulse/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module MCPulse
+  VERSION = '0.1.0'
+
+  # Bumped only for a breaking change; the API rejects anything else.
+  WIRE_VERSION = 1
+end

data/lib/mcpulse.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require 'json'
+
+require_relative 'mcpulse/canonical'
+require_relative 'mcpulse/emptiness'
+require_relative 'mcpulse/hashing'
+require_relative 'mcpulse/logger'
+require_relative 'mcpulse/options'
+require_relative 'mcpulse/stream'
+require_relative 'mcpulse/version'
+
+# MCPulse — analytics for MCP servers.
+#
+#   MCPulse.configure(key: "mp_live_…")
+#
+#   MCPulse.record("search", arguments) do
+#     my_handler.call(arguments)
+#   end
+#
+# Three rules this gem keeps, in order of how badly it would hurt to break one:
+#
+# 1. *Never raise.* Every entry point rescues. If MCPulse fails inside a customer's tool call,
+#    their tool fails and they blame us.
+# 2. *Never block.* Record, buffer, return. Nothing waits on the network on the path a model is
+#    waiting on.
+# 3. *Never store customer data.* Sizes and hashes leave this process. Arguments and results do
+#    not, and no option turns that off.
+module MCPulse
+  class << self
+    # Starts recording, or turns everything into a no-op if the options say not to.
+    #
+    # Idempotent: calling it twice reuses the same session rather than opening a second one. Left
+    # unguarded, a server built per request would report every call under two sessions and double
+    # both the customer's numbers and their bill.
+    def configure(key:, endpoint: nil, enabled: true, debug: false)
+      options = Options.new(key: key, endpoint: endpoint, enabled: enabled, debug: debug)
+      log = DebugLog.new(options.debug?)
+
+      unless options.active?
+        log.call('disabled — no key, or enabled: false')
+        @stream = nil
+        return nil
+      end
+
+      @stream = Stream.for(options, log)
+      log.call('watching')
+      @stream
+    rescue StandardError
+      # Deliberately silent. Failing here must look like configure was never called, and there is
+      # no logger to complain to if the options were the thing that was malformed.
+      @stream = nil
+    end
+
+    # The session calls are being filed under, or nil when recording is off.
+    #
+    # Exposed so a server can log which session it joined, and so the shared-session guarantee can
+    # be asserted rather than assumed.
+    def session_id
+      @stream&.session_id
+    end
+
+    # Notes who is connected, so calls can be attributed to a client.
+    def remember_client(name)
+      @stream&.remember_client(name)
+      nil
+    rescue StandardError
+      nil
+    end
+
+    # Times one tool call and buffers the result.
+    #
+    # The block's return value is handed back untouched and an exception is re-raised untouched,
+    # so a recorded call behaves exactly like an unrecorded one.
+    #
+    # Wrapping the handler rather than watching from outside is what lets MCPulse tell a handler
+    # that raised from one that returned an error result — a distinction an MCP server erases by
+    # converting both into +isError+ before anything outside can see it.
+    def record(tool_name, arguments = nil, client_name: nil)
+      stream = @stream
+      return yield if stream.nil?
+
+      stream.remember_client(client_name)
+
+      started_at = Time.now.utc
+      started = monotonic
+
+      result = nil
+      raised = false
+      begin
+        result = yield
+        result
+      rescue StandardError, ScriptError
+        raised = true
+        # Re-raised untouched: swallowing it would change what the customer's server does.
+        raise
+      ensure
+        begin
+          emit_call(stream, tool_name, arguments, result, raised, started_at, started)
+        rescue StandardError
+          # Recording must never be the reason a tool call fails.
+          nil
+        end
+      end
+    end
+
+    # Reports the server's tool list, once per session.
+    #
+    # +schema_bytes+ is the cost of a tool's presence in the context window, so pass the JSON that
+    # actually goes over the wire — what +tools/list+ returns — not the Ruby object the tool was
+    # declared from.
+    def record_startup(tools, client_name: nil)
+      stream = @stream
+      return nil if stream.nil? || !stream.claim_startup
+
+      stream.remember_client(client_name)
+
+      described = Array(tools).first(Options::MAX_TOOLS).filter_map do |tool|
+        name = Emptiness.member(tool, 'name')
+        next nil unless name.is_a?(String) && !name.empty?
+
+        { name: name[0, Options::MAX_TOOL_NAME], schema_bytes: measure(tool) }
+      end
+
+      stream.emit(
+        v: WIRE_VERSION,
+        type: 'startup',
+        session_id: stream.session_id,
+        client_name: stream.client_name,
+        tools: described
+      )
+      stream.log.call("startup: #{described.size} tools, client #{stream.client_name}")
+      nil
+    rescue StandardError
+      nil
+    end
+
+    # Sends everything buffered and stops accepting more.
+    #
+    # An +at_exit+ hook already does this. Call it by hand only when the server stops without the
+    # process exiting — a test suite, or a host that restarts servers in place.
+    def flush_all
+      Stream.flush_all
+    end
+
+    private
+
+    def emit_call(stream, tool_name, arguments, result, raised, started_at, started)
+      outcome = decide_outcome(result, raised)
+      name = tool_name.to_s
+      name = 'unknown' if name.empty?
+
+      stream.emit(
+        v: WIRE_VERSION,
+        type: 'call',
+        session_id: stream.session_id,
+        client_name: stream.client_name,
+        tool_name: name[0, Options::MAX_TOOL_NAME],
+        started_at: started_at.strftime('%Y-%m-%dT%H:%M:%S.%LZ'),
+        duration_ms: ((monotonic - started) * 1000).round,
+        outcome: outcome,
+        response_bytes: measure(result),
+        # An error is not also an absence — it has its own outcome already.
+        is_empty: outcome == Outcome::OK && Emptiness.empty_result?(result),
+        args_hash: Hashing.args_hash(arguments)
+      )
+    end
+
+    # What the outcome was, given that the handler is what we wrapped.
+    #
+    # Wrapping the block means a raise arrives here as a raise rather than as the +isError+ result
+    # the server would have converted it into. What cannot be seen from here is +bad_args+: a
+    # server that validates arguments before calling the handler rejects them outside this block.
+    # Reporting it anyway would mean reading the difference back out of an error message, and error
+    # strings are not an interface anyone promised to keep.
+    def decide_outcome(result, raised)
+      return Outcome::CRASHED if raised
+
+      flag = Emptiness.member(result, 'isError')
+      flag = Emptiness.member(result, 'is_error') if flag.nil?
+      flag == true ? Outcome::TOOL_ERROR : Outcome::OK
+    end
+
+    # What something costs the context window. Unserialisable means unmeasurable.
+    def measure(value)
+      return 0 if value.nil?
+
+      Sizes.utf16_length(JSON.generate(value))
+    rescue StandardError
+      0
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification
+name: mcpulse
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- MCPulse
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-09-06 00:00:00.000000000 Z
+dependencies: []
+description: |
+  See which of your MCP tools actually work for the models calling them.
+  Records how every tool call ended, how long it took, and whether it came
+  back empty. Arguments and results never leave your process.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/mcpulse.rb
+- lib/mcpulse/buffer.rb
+- lib/mcpulse/canonical.rb
+- lib/mcpulse/emptiness.rb
+- lib/mcpulse/hashing.rb
+- lib/mcpulse/logger.rb
+- lib/mcpulse/options.rb
+- lib/mcpulse/stream.rb
+- lib/mcpulse/transport.rb
+- lib/mcpulse/version.rb
+homepage: https://github.com/getmcpulse/mcpulse-ruby
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/getmcpulse/mcpulse-ruby
+  bug_tracker_uri: https://github.com/getmcpulse/mcpulse-ruby/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.20
+signing_key:
+specification_version: 4
+summary: Analytics for MCP servers. One import, one wrap.
+test_files: []