mcpspan 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 84a76f8debbf2cfc4830ae61f49f68e8bea556dee0176e1707415d19ec6fe7b9
+  data.tar.gz: b7ab651d3b894265c4a7dd21d5827b31f5996f85cb734759e4e1fb420cb17dc6
+SHA512:
+  metadata.gz: 84bfdf6a1e69cb02d126641811e12730e72c2166fdb507c1d2dad5e2dd17cb26ddee618b9776742a6a63be2a79c1ae891cc6666409abfd08d9f41626a3c3dd3e
+  data.tar.gz: 235cbe6fbeae4a5e88c53048595c11dd8930a7a411a6c7c4fe449997393c9677181c26bc9d36e427d4f87f5efeab3c41d49114087c87cc1bdb68460e77ae8d3e

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kacper Zatoń
+
+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,232 @@
+# mcpspan for Ruby
+
+Analytics for MCP servers. Find out which of your tools get called, by which
+client, how long they take, and which ones fail.
+
+Your own logs tell you a tool ran. This tells you whether it was Claude,
+Cursor, or something you have not heard of, how that call compares to the
+other nine hundred, and whether the failures are your tool breaking or your
+tool politely saying no.
+
+## Install
+
+```sh
+bundle add mcpspan
+```
+
+For a server built on the official Ruby MCP SDK, the `mcp` gem, 1.6 or newer.
+Needs Ruby 3.2 or newer. Nothing else: delivery uses the standard library.
+
+## Use
+
+One line, after the server is built:
+
+```ruby
+server = MCP::Server.new(name: "flights", tools: [SearchFlights, BookFlight])
+McpSpan.instrument(server, api_key: ENV["MCPSPAN_API_KEY"], endpoint: "http://localhost:6271")
+
+MCP::Server::Transports::StdioTransport.new(server).open
+```
+
+Every tool on the server is measured, whether it was given to the server or
+added later with `define_tool`. Nothing about how you write tools changes,
+and each tool returns and raises exactly what it did before.
+
+Over streamable HTTP, instrument the server you hand the transport:
+
+```ruby
+transport = MCP::Server::Transports::StreamableHTTPTransport.new(McpSpan.instrument(server))
+```
+
+With no `api_key`, it is read from `MCPSPAN_API_KEY`.
+
+### Sessions and clients
+
+Calls are grouped into sessions when there is a connection to group them by:
+a stdio process, or an HTTP transport that hands out session IDs. A stateless
+HTTP endpoint, and every endpoint on the 2026-07-28 protocol, which dropped
+sessions, records calls without one.
+
+The client is read from the call itself on 2026-07-28, where each request
+names its client, and from the handshake on 2025-11-25.
+
+A tool that asks the client for more before it can finish is one call however
+many round trips that takes.
+
+### Without a key
+
+If there is no key, nothing is collected, nothing is sent, and no thread is
+started. That makes it safe to leave in place in tests, in CI, and in a fork
+somebody is only reading.
+
+### One tool at a time
+
+For a server `instrument` does not cover, track the tool class:
+
+```ruby
+McpSpan.track(SearchFlights)
+```
+
+A tracked tool on an instrumented server is counted once.
+
+### Leaving a tool out
+
+```ruby
+McpSpan.exclude(HealthCheck)
+```
+
+For tools called by machinery rather than by an agent. A health check polled
+every few seconds outnumbers everything a person does and drags the whole
+server's error rate and response time towards its own. The mark sits on the
+tool class, so a rename carries it along. A tool made with `define_tool` has
+no class of its own, and is left out by name:
+
+```ruby
+server.define_tool(name: McpSpan.exclude("health_check")) { MCP::Tool::Response.new([]) }
+```
+
+### Resources and prompts
+
+Reads of your resources and gets of your prompts are measured too, with
+nothing to add: each is one event, in the same session and from the same
+client as the tool calls around it, and the dashboard shows them in a card of
+their own and in each session's timeline. Listings are not recorded.
+
+A resource at a fixed address is named by that address. One read through a
+template is named by the template, `trips://{id}`, never by the address the
+client asked for, which can carry a user's data; the template's variables are
+its parameters, by name only. A read of an address the server has nothing for
+is named by its scheme alone, `db://`. A prompt is named by its name, and its
+arguments are its parameters, as a tool's are.
+
+Resources and templates defined as classes, and ones answered by your own
+`resources_read_handler`, are named alike.
+
+### Versions
+
+Every call carries the version of the server that answered it, so the
+dashboard marks where each release began and compares it with the one before.
+There is nothing to add: it is the version the server gives itself,
+`MCP::Server.new(name: "flights", version: "1.4.0")`. A server that gives none
+is announced by the gem as `0.1.0`, and recorded so. To record a commit or a
+deploy instead, set `server_version` (or `MCPSPAN_SERVER_VERSION`). The
+client's version is recorded beside its name.
+
+### Shutting down
+
+What is queued is delivered as the program exits, so most servers need
+nothing here. If yours has its own shutdown path and you want to be explicit:
+
+```ruby
+McpSpan.shutdown
+```
+
+A process killed outright runs nothing after that, and the last few seconds
+of calls go with it.
+
+## Two kinds of failure
+
+MCP asks tools to report their own errors inside the result, with `error: true`
+on the `MCP::Tool::Response`, so the model can see what went wrong. An
+exception is the deviation from that, and usually means the tool broke.
+
+Both are recorded, and each event says which happened, with the exception's
+class for the second: a `BookingError` is recorded as `BookingError`, as your
+tool raised it, though the MCP SDK hands the client a generic internal error.
+
+### And two that never reach your tool
+
+Calls the server refuses on its own are recorded too: arguments that are
+missing or fail the tool's input schema, and names it has no tool for. A
+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.
+
+## Privacy
+
+**Parameter values never leave your process.** Not by default, not in any
+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, 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.
+
+Optionally, parameter *names and types*:
+
+```ruby
+McpSpan.instrument(server, capture_parameter_names: true)
+```
+
+That records `{"destination": "string", "passengers": "number"}`, in JSON's
+vocabulary, as the client sent them. Knowing `search_flights` is always
+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.
+
+## Self-hosting
+
+```ruby
+McpSpan.instrument(server, endpoint: "https://mcpspan.example.com")
+```
+
+Or set `MCPSPAN_ENDPOINT`. There is no default: events go only where you point
+them. With a key and no endpoint, nothing is collected, and the SDK says so
+once on standard error.
+
+When it starts with a key, the SDK sends one empty batch to say it is there.
+That is how the dashboard's Status page tells a server nobody has used yet
+from one pointed at the wrong address, and how a wrong key is reported when
+your server starts rather than at its first tool call.
+
+## It will not break your server
+
+- Delivery runs on a thread of its own. A tool call returns without waiting
+  on the network. A forked worker, as Puma's are, starts delivering on its own
+  at its first call.
+- A failure to send never reaches your code, and nothing here raises over a
+  setting. Retryable failures wait and try again with a widening gap; a
+  refused key switches collection off and says so once on standard error.
+- The queue is bounded. An unreachable endpoint cannot grow it until your
+  process runs out of memory.
+- Nothing is ever written to standard output, which carries the MCP protocol
+  on a stdio server. Diagnostics go to standard error.
+- The MCP SDK has one `around_request` slot, and it is yours: mcpspan leaves
+  it alone. It hooks two private methods of the one server it instruments
+  instead, and if a version of the MCP SDK renames them, instrumenting leaves
+  the server as it was.
+
+## Options
+
+Keywords of `McpSpan.instrument` and `McpSpan.configure`.
+
+| Option | Default | What it does |
+|---|---|---|
+| `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. |
+| `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`. |
+| `flush_on_exit` | `true` | Delivers what is queued as the program exits. |
+| `flush_interval` | `5` seconds | How long a partly filled batch waits. |
+| `max_batch_size` | `100` | Events per request. Reaching it sends early. |
+| `max_queue_size` | `10000` | Events held while delivery is failing. |
+
+Configuring again with the same settings changes nothing.
+
+## Developing
+
+```sh
+bundle install
+bundle exec rake
+```
+
+The SDK follows [the contract every mcpspan SDK
+follows](../../docs/sdk-contract.md), checked by the suite in
+[`conformance/`](../../conformance/README.md).
+
+## Licence
+
+MIT.

data/lib/mcpspan/collector.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module McpSpan
+  # The one configuration a process runs with, and recording calls under it.
+  module Collector
+    # Said when there is a key and nowhere to send: somebody meant to collect. There is no default endpoint, since
+    # mcpspan runs wherever its user runs it, and a default would send their data somewhere they did not choose.
+    NO_ENDPOINT = "mcpspan: an API key is set but no endpoint, so nothing is collected. Set MCPSPAN_ENDPOINT (or the " \
+                  "endpoint option) to your mcpspan installation, for example http://localhost:6271."
+    # The API takes at most this many events in one request.
+    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
+    ].freeze
+
+    # What an integration knows about one call as it starts. A kind of nil is a tool call.
+    Call = Struct.new(:tool_name, :parameters, :client_name, :client_version, :server_version, :session_id, :started,
+                      :timestamp, :kind, keyword_init: true,)
+
+    @lock = Mutex.new
+    @reporter = nil
+    @settings = nil
+    @at_exit = false
+    @said_no_endpoint = false
+
+    class << self
+      # Starts collecting, or stops if there is no key to collect with. The same settings again change nothing.
+      def configure(settings, sender: nil)
+        resolved = resolve(settings)
+        previous = @lock.synchronize do
+          return if @reporter && @settings == resolved
+
+          current = @reporter
+          @reporter = nil
+          @settings = nil
+          current
+        end
+        previous&.stop
+
+        # No key is a normal state, in development and CI, and not reported.
+        return if resolved[:api_key].empty?
+        return say_no_endpoint(resolved[:on_diagnostic]) if resolved[:endpoint].empty? && sender.nil?
+
+        reporter = Reporter.new(
+          endpoint: resolved[:endpoint],
+          send: sender || Transport.new(resolved[:endpoint], resolved[:api_key]).method(:call),
+          flush_interval: resolved[:flush_interval],
+          max_batch_size: resolved[:max_batch_size],
+          max_queue_size: resolved[:max_queue_size],
+          debug: resolved[:debug],
+          on_diagnostic: resolved[:on_diagnostic],
+        )
+        @lock.synchronize do
+          @reporter = reporter
+          @settings = resolved
+        end
+        at_exit_once if resolved[:flush_on_exit]
+        # In the background: startup does not wait for the network.
+        reporter.start
+      end
+
+      def shutdown
+        reporter = @lock.synchronize do
+          current = @reporter
+          @reporter = nil
+          @settings = nil
+          current
+        end
+        reporter&.stop
+      end
+
+      def collecting?
+        !@reporter.nil?
+      end
+
+      def flush
+        @reporter&.flush
+      end
+
+      # Notes the start of a call, or nil when nothing is being recorded. The clock is read first. A server version
+      # the SDK was told wins over the one the server gives itself.
+      def begin_call(tool_name, arguments:, session_id:, kind: nil, client_name: nil, client_version: nil,
+                     server_version: nil)
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        timestamp = Time.now.utc
+        settings = @settings
+        return nil if settings.nil?
+
+        Call.new(
+          tool_name: tool_name.to_s,
+          parameters: settings[:capture_parameter_names] ? Text.describe_parameters(arguments) : nil,
+          client_name: client_name,
+          client_version: client_version,
+          server_version: settings[:server_version].empty? ? server_version : settings[:server_version],
+          session_id: session_id,
+          started: started,
+          timestamp: timestamp,
+          kind: kind,
+        )
+      end
+
+      # Builds the event for a finished call and queues it. It never blocks on the network.
+      def record(call, success:, source: nil, type: nil, message: nil)
+        duration_ms = (Process.clock_gettime(Process::CLOCK_MONOTONIC) - call.started) * 1000.0
+        reporter = @reporter
+        return if reporter.nil?
+
+        reporter.record(Event.new(
+          id: SecureRandom.uuid,
+          kind: call.kind,
+          tool_name: Text.truncate(call.tool_name, Text::MAX_NAME),
+          duration_ms: duration_ms,
+          success: success,
+          error_source: source,
+          error_type: type && Text.truncate(type, Text::MAX_NAME),
+          error_message: message.nil? || message.empty? ? nil : message,
+          client_type: Text.client_type(call.client_name),
+          client_name: Text.client_name(call.client_name),
+          client_version: Text.version(call.client_version),
+          server_version: Text.version(call.server_version),
+          timestamp: call.timestamp.strftime("%Y-%m-%dT%H:%M:%S.%LZ"),
+          session_id: call.session_id,
+          parameters: call.parameters,
+        ))
+      rescue StandardError
+        nil
+      end
+
+      # For tests: forgets that the missing endpoint was already mentioned.
+      def forget_no_endpoint_notice
+        @lock.synchronize { @said_no_endpoint = false }
+      end
+
+      private
+
+      # Said unasked, as a refused key is: without it the data goes nowhere and nothing tells anyone.
+      def say_no_endpoint(on_diagnostic)
+        first = @lock.synchronize do
+          said = @said_no_endpoint
+          @said_no_endpoint = true
+          !said
+        end
+        return unless first
+
+        on_diagnostic ? on_diagnostic.call(NO_ENDPOINT) : warn(NO_ENDPOINT)
+      rescue StandardError
+        nil
+      end
+
+      def at_exit_once
+        @lock.synchronize do
+          return if @at_exit
+
+          @at_exit = true
+        end
+        # Runs when the program ends on its own, not on a signal it does not handle; that stays the program's own.
+        at_exit do
+          reporter = @reporter
+          reporter.stop if reporter && @settings&.fetch(:flush_on_exit)
+        rescue StandardError
+          nil
+        end
+      end
+
+      def resolve(settings)
+        debug = settings[:debug] ? true : !settings[:on_diagnostic].nil?
+        warn = lambda do |message|
+          next unless debug
+
+          settings[:on_diagnostic] ? settings[:on_diagnostic].call(message) : warn(message)
+        end
+        unknown = settings.keys - SETTINGS
+        warn.call("mcpspan: ignoring unknown settings #{unknown.join(", ")}") unless unknown.empty?
+
+        # A malformed setting falls back to its default, and says so when asked.
+        positive = lambda do |name, default, kind|
+          value = settings[name]
+          next default if value.nil?
+          next value if value.is_a?(kind) && value.positive?
+
+          warn.call("mcpspan: ignoring #{name}=#{value.inspect}, expected a positive number")
+          default
+        end
+        on_diagnostic = settings[:on_diagnostic]
+        on_diagnostic = nil unless on_diagnostic.respond_to?(:call)
+
+        {
+          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,
+          server_version: first_set(settings[:server_version], ENV.fetch("MCPSPAN_SERVER_VERSION", nil)),
+          debug: debug,
+          on_diagnostic: on_diagnostic,
+          flush_on_exit: settings.fetch(:flush_on_exit, true) ? true : false,
+          flush_interval: positive.call(:flush_interval, Reporter::DEFAULT_FLUSH_INTERVAL, Numeric).to_f,
+          max_batch_size: [positive.call(:max_batch_size, Reporter::DEFAULT_MAX_BATCH_SIZE, Integer),
+                           MAX_EVENTS_PER_REQUEST,].min,
+          max_queue_size: positive.call(:max_queue_size, Reporter::DEFAULT_MAX_QUEUE_SIZE, Integer),
+        }
+      end
+
+      def first_set(*values)
+        values.map { |value| value.to_s.strip }.find { |value| !value.empty? } || ""
+      end
+    end
+  end
+end

data/lib/mcpspan/event.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "json"
+
+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, :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.
+    def to_h
+      {
+        id: id,
+        kind: kind,
+        toolName: tool_name,
+        durationMs: duration_ms,
+        success: success,
+        errorSource: error_source,
+        errorType: error_type,
+        errorMessage: error_message,
+        clientType: client_type,
+        clientName: client_name,
+        clientVersion: client_version,
+        serverVersion: server_version,
+        timestamp: timestamp,
+        sdkVersion: VERSION,
+        sessionId: session_id,
+        parameters: parameters,
+      }.compact
+    end
+
+    # The body of one batch.
+    def self.batch(events)
+      JSON.generate({ events: events.map(&:to_h) })
+    end
+  end
+
+  # How a failed call announced itself, as the contract names it.
+  module Source
+    RESULT = "result"
+    EXCEPTION = "exception"
+    ARGUMENTS = "arguments"
+    UNKNOWN_TOOL = "unknown_tool"
+    UNKNOWN_RESOURCE = "unknown_resource"
+    UNKNOWN_PROMPT = "unknown_prompt"
+  end
+end