posthog-ruby 3.23.7 → 3.24.0

data/lib/posthog/mcp/truncation.rb

@@ -0,0 +1,326 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+
+module PostHog
+  module MCP
+    # Layered truncation so an event fits within a byte budget before capture:
+    #
+    # 1. Field-level string limits (intent, resource name, metadata fields).
+    # 2. Stack-frame limiting and message caps on the `$exception_list` shape.
+    # 3. Response content text limits (32KB per text block).
+    # 4. Recursive normalization of user-controlled fields (depth/breadth/string caps).
+    # 5. Size-targeted truncation: progressive depth reduction, then trimming the
+    #    largest strings until under MAX_EVENT_BYTES.
+    #
+    # Pure functions; the input event is never mutated. Hash keys are strings.
+    #
+    # @api private
+    module Truncation
+      MAX_DEPTH = 10
+      MAX_BREADTH = 100
+      MAX_STRING_LENGTH = 32_768
+      # The core client drops any single message
+      # larger than `Defaults::Message::MAX_BYTES` (32KB) at batch time, so the
+      # internal event is budgeted to leave headroom for the envelope (`$lib`,
+      # timestamp, uuid, distinct_id) the client adds around it.
+      MAX_EVENT_BYTES = PostHog::Defaults::Message::MAX_BYTES - 2048
+
+      MAX_USER_INTENT_LENGTH = 2048
+      MAX_ERROR_MESSAGE_LENGTH = 2048
+      MAX_RESOURCE_NAME_LENGTH = 256
+      MAX_METADATA_LENGTH = 256
+      MAX_STACK_FRAMES = 50
+      MAX_CONTENT_TEXT_LENGTH = 32_768
+
+      TRUNCATION_SUFFIX = '...'
+
+      METADATA_FIELDS = [
+        ['user_intent', MAX_USER_INTENT_LENGTH],
+        ['resource_name', MAX_RESOURCE_NAME_LENGTH],
+        ['server_name', MAX_METADATA_LENGTH],
+        ['server_version', MAX_METADATA_LENGTH],
+        ['client_name', MAX_METADATA_LENGTH],
+        ['client_version', MAX_METADATA_LENGTH],
+        ['error_type', MAX_METADATA_LENGTH],
+        ['client_user_agent', MAX_METADATA_LENGTH],
+        ['vendor_client', MAX_METADATA_LENGTH],
+        ['llm_model', MAX_METADATA_LENGTH]
+      ].freeze
+
+      # Includes user-supplied `properties` (custom events, `event_properties`,
+      # `capture_tool_call`): a large numeric array cannot be shrunk by string
+      # trimming, so it must take part in depth/breadth reduction or the core
+      # client drops the whole message at batch time.
+      NORMALIZED_FIELDS = %w[parameters response identify_actor_data error properties].freeze
+
+      module_function
+
+      # Recursively normalize a value: cap strings, coerce non-serializable
+      # values, convert times, detect cycles, and bound depth/breadth.
+      def normalize(value, depth = MAX_DEPTH, max_breadth = MAX_BREADTH, max_string_length = MAX_STRING_LENGTH)
+        visit(value, depth, max_breadth, max_string_length, {}.compare_by_identity)
+      end
+
+      def visit(value, remaining_depth, max_breadth, max_string_length, memo)
+        case value
+        when nil, true, false, Integer then value
+        when Float
+          return '[NaN]' if value.nan?
+          return (value.positive? ? '[Infinity]' : '[-Infinity]') if value.infinite?
+
+          value
+        when String
+          value.length > max_string_length ? value[0, max_string_length] + TRUNCATION_SUFFIX : value
+        when Symbol then value.to_s
+        when Time then value.utc.iso8601(3)
+        when Proc, Method
+          name = value.respond_to?(:name) ? value.name : nil
+          "[Function: #{name || '<anonymous>'}]"
+        when Array
+          return '[Circular ~]' if memo.key?(value)
+          return '[Array]' if remaining_depth <= 0
+
+          memo[value] = true
+          result = visit_array(value, remaining_depth - 1, max_breadth, max_string_length, memo)
+          memo.delete(value)
+          result
+        when Hash
+          return '[Circular ~]' if memo.key?(value)
+          return '[Object]' if remaining_depth <= 0
+
+          memo[value] = true
+          result = visit_object(value, remaining_depth - 1, max_breadth, max_string_length, memo)
+          memo.delete(value)
+          result
+        else
+          value.respond_to?(:iso8601) ? value.iso8601 : value.to_s
+        end
+      end
+
+      def visit_array(array, remaining_depth, max_breadth, max_string_length, memo)
+        result = []
+        array.each_with_index do |item, index|
+          if index >= max_breadth
+            result << '[MaxProperties ~]'
+            break
+          end
+          result << visit(item, remaining_depth, max_breadth, max_string_length, memo)
+        end
+        result
+      end
+
+      def visit_object(hash, remaining_depth, max_breadth, max_string_length, memo)
+        result = {}
+        count = 0
+        hash.each do |key, val|
+          if count >= max_breadth
+            result['...'] = '[MaxProperties ~]'
+            break
+          end
+          result[key.to_s] = visit(val, remaining_depth, max_breadth, max_string_length, memo)
+          count += 1
+        end
+        result
+      end
+
+      def truncate_string(value, max_length)
+        return value unless value.is_a?(String) && value.length > max_length
+
+        value[0, max_length] + TRUNCATION_SUFFIX
+      end
+
+      def truncate_stack_frames(frames)
+        return frames unless frames.is_a?(Array) && frames.length > MAX_STACK_FRAMES
+
+        half = MAX_STACK_FRAMES / 2
+        frames[0, half] + frames[-half, half]
+      end
+
+      def truncate_exception_list(error)
+        list = error['$exception_list']
+        return error unless list.is_a?(Array)
+
+        truncated = list.map do |exception|
+          next exception unless exception.is_a?(Hash)
+
+          nxt = exception.dup
+          nxt['value'] = truncate_string(nxt['value'], MAX_ERROR_MESSAGE_LENGTH) if nxt['value'].is_a?(String)
+          stacktrace = nxt['stacktrace']
+          if stacktrace.is_a?(Hash) && stacktrace['frames'].is_a?(Array) && !stacktrace['frames'].empty?
+            nxt['stacktrace'] = stacktrace.merge('frames' => truncate_stack_frames(stacktrace['frames']))
+          end
+          nxt
+        end
+        error.merge('$exception_list' => truncated)
+      end
+
+      def truncate_response_content(response)
+        return response unless response.is_a?(Hash)
+
+        content = response['content']
+        return response unless content.is_a?(Array)
+
+        new_content = content.map do |block|
+          if block.is_a?(Hash) && block['type'] == 'text' && block['text'].is_a?(String) &&
+             block['text'].length > MAX_CONTENT_TEXT_LENGTH
+            block.merge('text' => block['text'][0, MAX_CONTENT_TEXT_LENGTH] + TRUNCATION_SUFFIX)
+          else
+            block
+          end
+        end
+        response.merge('content' => new_content)
+      end
+
+      # Byte size of the compact JSON encoding, coercing non-JSON values like the
+      # transport would.
+      def json_byte_size(value)
+        JSON.generate(jsonable(value)).bytesize
+      end
+
+      def jsonable(value)
+        case value
+        when Hash then value.to_h { |k, v| [k.to_s, jsonable(v)] }
+        when Array then value.map { |v| jsonable(v) }
+        when String, Integer, true, false, nil then value
+        when Float then value.finite? ? value : value.to_s
+        when Time then value.utc.iso8601(3)
+        else
+          value.respond_to?(:iso8601) ? value.iso8601 : value.to_s
+        end
+      end
+
+      def collect_string_paths(obj, current_path, results)
+        case obj
+        when String
+          results << { path: current_path.dup, length: obj.length } if obj.length > 100
+        when Array
+          obj.each_with_index { |item, i| collect_string_paths(item, current_path + [i.to_s], results) }
+        when Hash
+          obj.each { |key, value| collect_string_paths(value, current_path + [key.to_s], results) }
+        end
+      end
+
+      def get_nested_value(obj, path)
+        path.reduce(obj) do |current, key|
+          case current
+          when Array then current[key.to_i]
+          when Hash then current[key]
+          else return nil
+          end
+        end
+      end
+
+      def set_nested_value(obj, path, value)
+        parent = path.empty? ? nil : get_nested_value(obj, path[0...-1])
+        case parent
+        when Array then parent[path.last.to_i] = value
+        when Hash then parent[path.last] = value
+        end
+      end
+
+      def deep_copy(obj)
+        case obj
+        when Hash then obj.to_h { |k, v| [k, deep_copy(v)] }
+        when Array then obj.map { |v| deep_copy(v) }
+        else obj
+        end
+      end
+
+      def truncate_largest_fields(obj, max_bytes)
+        result = deep_copy(obj)
+
+        10.times do
+          current_size = json_byte_size(result)
+          return result if current_size <= max_bytes
+
+          excess = current_size - max_bytes
+          string_paths = []
+          collect_string_paths(result, [], string_paths)
+          string_paths.sort_by! { |entry| -entry[:length] }
+          break if string_paths.empty?
+
+          remaining = excess + 200
+          truncated = false
+          string_paths.each do |entry|
+            break if remaining <= 0
+
+            length = entry[:length]
+            reduction = [remaining, length / 2].min
+            next if reduction < 10
+
+            new_length = length - reduction
+            current_value = get_nested_value(result, entry[:path])
+            next unless current_value.is_a?(String)
+
+            set_nested_value(result, entry[:path], current_value[0, new_length] + TRUNCATION_SUFFIX)
+            remaining -= reduction
+            truncated = true
+          end
+
+          break unless truncated
+        end
+
+        result
+      end
+
+      def truncate_to_size(event, fields = NORMALIZED_FIELDS)
+        return event if json_byte_size(event) <= MAX_EVENT_BYTES
+
+        # Trim the largest strings first so a big tool response keeps its shape
+        # (the budget here is tight enough that depth reduction alone would turn
+        # a `content` array into "[Array]").
+        trimmed = truncate_largest_fields(event, MAX_EVENT_BYTES)
+        return trimmed if json_byte_size(trimmed) <= MAX_EVENT_BYTES
+
+        (MAX_DEPTH - 1).downto(1) do |depth|
+          reduced = event.dup
+          fields.each do |field|
+            reduced[field] = normalize(reduced[field], depth) unless reduced[field].nil?
+          end
+          return reduced if json_byte_size(reduced) <= MAX_EVENT_BYTES
+        end
+
+        minimal = event.dup
+        fields.each do |field|
+          minimal[field] = normalize(minimal[field], 1) unless minimal[field].nil?
+        end
+        truncate_largest_fields(minimal, MAX_EVENT_BYTES)
+      end
+
+      # Re-apply the byte budget to a built payload a `before_send` hook returned.
+      # The hook runs after {truncate_event}, so it can grow an event back over
+      # the transport's per-message limit, where the batch would drop it whole;
+      # trimming here costs the enrichment its bulk instead of the whole event.
+      #
+      # @param payload [Hash] a payload from {EventBuilder.build}, post-hook
+      # @return [Hash] a payload within the byte budget
+      def truncate_payload(payload)
+        return payload unless payload.is_a?(Hash)
+
+        key = payload.key?(:properties) && !payload.key?('properties') ? :properties : 'properties'
+        truncate_to_size(payload, [key])
+      end
+
+      # @param event [Hash] internal event with string keys
+      # @return [Hash] new event within the byte budget
+      def truncate_event(event)
+        result = event.dup
+
+        METADATA_FIELDS.each do |key, max_length|
+          result[key] = truncate_string(result[key], max_length) if result[key].is_a?(String)
+        end
+
+        result['error'] = truncate_exception_list(result['error']) if result['error'].is_a?(Hash)
+        result['response'] = truncate_response_content(result['response']) unless result['response'].nil?
+
+        NORMALIZED_FIELDS.each do |field|
+          result[field] = normalize(result[field]) unless result[field].nil?
+        end
+
+        truncate_to_size(result)
+      end
+    end
+  end
+end

data/lib/posthog/mcp.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require 'posthog'
+
+require 'posthog/mcp/constants'
+require 'posthog/mcp/log'
+require 'posthog/mcp/ids'
+require 'posthog/mcp/options'
+require 'posthog/mcp/session_token'
+require 'posthog/mcp/session'
+require 'posthog/mcp/identity'
+require 'posthog/mcp/tools'
+require 'posthog/mcp/exceptions'
+require 'posthog/mcp/sanitization'
+require 'posthog/mcp/truncation'
+require 'posthog/mcp/conversation_id'
+require 'posthog/mcp/intent'
+require 'posthog/mcp/schema_mutation'
+require 'posthog/mcp/event_builder'
+require 'posthog/mcp/sink'
+require 'posthog/mcp/tracking_data'
+require 'posthog/mcp/request_scope'
+require 'posthog/mcp/analytics'
+require 'posthog/mcp/instrumentation'
+require 'posthog/mcp/server_extension'
+require 'posthog/mcp/rack_middleware'
+require 'posthog/mcp/client'
+
+module PostHog
+  # PostHog MCP analytics for servers built on the official Ruby `mcp` gem.
+  #
+  # Wrap an `MCP::Server` so every tool call, handshake, listing, prompt,
+  # resource read, and failure is captured to PostHog as a `$mcp_*` event.
+  #
+  # @note Experimental and not officially supported: no support is provided for
+  #   this integration, and its API and the captured event schema may change in a
+  #   minor release. A warning is logged when this file is required.
+  #   Docs: https://posthog.com/docs/mcp-analytics
+  #
+  # @example
+  #   require 'posthog/mcp'
+  #
+  #   posthog = PostHog::Client.new(api_key: 'phc_...', host: 'https://us.i.posthog.com')
+  #   server = MCP::Server.new(name: 'my-server', version: '1.0.0', tools: [MyTool])
+  #   analytics = PostHog::MCP.instrument(server, posthog)
+  #
+  #   # With posthog-rails the client is resolved from PostHog.client:
+  #   PostHog::MCP.instrument(server)
+  module MCP
+    EXPERIMENTAL_NOTICE =
+      'PostHog::MCP is experimental and not officially supported: no support is provided for it, and its ' \
+      'API and the captured $mcp_* event schema may change in a minor release. Docs: ' \
+      'https://posthog.com/docs/mcp-analytics. Feedback welcome at https://github.com/PostHog/posthog-ruby/issues.'
+
+    class << self
+      # Instrument an `MCP::Server`.
+      #
+      # @param server [MCP::Server] the server to wrap
+      # @param client [PostHog::Client, nil] the PostHog client to send through. Defaults to
+      #   `PostHog.client` when the posthog-rails facade is loaded.
+      # @param options [PostHog::MCP::Options, nil] prebuilt options; otherwise pass keywords
+      # @param kwargs [Hash] {PostHog::MCP::Options} keywords (`identify:`, `before_send:`, ...)
+      # @return [PostHog::MCP::Analytics] handle for custom events; a no-op handle when
+      #   instrumentation fails (logged, never raised)
+      # @raise [LoadError] when the `mcp` gem is not available
+      def instrument(server, client = nil, options: nil, **kwargs)
+        opts = options.is_a?(Options) ? options : Options.new(**kwargs)
+        ensure_mcp_sdk!
+        experimental_notice!(opts)
+
+        begin
+          unless server.is_a?(::MCP::Server)
+            raise TypeError, "Unsupported server type: #{server.class}. Pass an MCP::Server."
+          end
+
+          existing = tracking_data(server)
+          if existing
+            Log.debug(opts, 'instrument() - server already instrumented, skipping initialization')
+            return Analytics.new(server)
+          end
+
+          resolved_client = resolve_client(client)
+          Log.warn(opts, 'Warning: no PostHog client available; MCP events will not be sent.') if resolved_client.nil?
+          sink = resolved_client ? Sink.new(resolved_client) : nil
+          data = TrackingData.new(options: opts, sink: sink, server_name: safe_call(server, :name),
+                                  server_version: safe_call(server, :version))
+          install_extensions!
+          server.instance_variable_set(:@__posthog_mcp, data)
+          register_missing_capability_tool(server, data)
+          Analytics.new(server)
+        rescue StandardError => e
+          Log.warn(opts, "Warning: failed to instrument server - #{e.class}: #{e.message}")
+          NoopAnalytics.new
+        end
+      end
+
+      # @api private
+      # @return [PostHog::MCP::TrackingData, nil]
+      def tracking_data(server)
+        return nil unless server.instance_variable_defined?(:@__posthog_mcp)
+
+        server.instance_variable_get(:@__posthog_mcp)
+      end
+
+      # Encode a session token for a custom HTTP layer's `Mcp-Session-Id` response header.
+      #
+      # @param payload [PostHog::MCP::SessionTokenPayload, Hash]
+      # @return [String]
+      def encode_session_id(payload)
+        SessionToken.encode(payload)
+      end
+
+      # Decode an `Mcp-Session-Id` value; nil for anything that is not one of our tokens.
+      #
+      # @return [PostHog::MCP::SessionTokenPayload, nil]
+      def decode_session_id(value)
+        SessionToken.decode(value)
+      end
+
+      # Deterministic `$session_id` for a transport session id (stable across restarts).
+      #
+      # @return [String]
+      def derive_session_id_from_mcp_session(mcp_session_id)
+        Session.derive_session_id_from_mcp_session(mcp_session_id)
+      end
+
+      # Deterministic `$session_id` for an agent conversation handle.
+      #
+      # @return [String]
+      def derive_session_id_from_conversation(conversation_id)
+        Session.derive_session_id_from_conversation(conversation_id)
+      end
+
+      # The canned `get_more_tools` result for custom dispatchers.
+      #
+      # @return [Hash]
+      def get_more_tools_result # rubocop:disable Naming/AccessorMethodName -- public API name
+        Tools.result
+      end
+
+      # @api private
+      def mcp_sdk_available?
+        defined?(::MCP::Server) ? true : false
+      end
+
+      # @api private
+      def experimental_notice!(options = nil)
+        Log.debug(options, EXPERIMENTAL_NOTICE)
+        return if @experimental_notice_shown
+
+        @experimental_notice_shown = true
+        Kernel.warn("[posthog-ruby] #{EXPERIMENTAL_NOTICE}")
+      end
+
+      # @api private
+      def reset_for_tests!
+        @experimental_notice_shown = false
+      end
+
+      private
+
+      def ensure_mcp_sdk!
+        return if mcp_sdk_available?
+
+        raise LoadError, "PostHog::MCP.instrument needs the MCP SDK. Add `gem 'mcp', '>= 1.4'` to your Gemfile. " \
+                         '(PostHog::MCP::Client for custom dispatchers works without it.)'
+      end
+
+      def resolve_client(client)
+        return client if client
+
+        PostHog.respond_to?(:client) ? PostHog.client : nil
+      rescue StandardError
+        nil
+      end
+
+      def safe_call(object, method_name)
+        object.respond_to?(method_name) ? object.public_send(method_name) : nil
+      rescue StandardError
+        nil
+      end
+
+      # Adds the `get_more_tools` virtual tool as a real server tool. An application
+      # tool that already uses the name wins and is tracked as an ordinary tool.
+      def register_missing_capability_tool(server, data)
+        return unless data.options.report_missing
+
+        name = Tools.missing_capability_tool_name(data.options)
+        return if server.tools.is_a?(Hash) && server.tools.key?(name)
+
+        data.virtual_tool = Tools.register(server, name, data.options)
+      rescue StandardError => e
+        Log.warn(data.options, "Warning: could not register the #{name} tool - #{e.class}: #{e.message}")
+      end
+
+      def install_extensions!
+        return if @extensions_installed
+
+        ::MCP::Server.prepend(ServerExtension)
+        if defined?(::MCP::Server::Transports::StreamableHTTPTransport)
+          ::MCP::Server::Transports::StreamableHTTPTransport.prepend(TransportExtension)
+        end
+        @extensions_installed = true
+      end
+    end
+  end
+end
+
+begin
+  require 'mcp'
+rescue LoadError
+  # The `mcp` gem is a peer dependency of PostHog::MCP.instrument; PostHog::MCP::Client
+  # (custom dispatchers) works without it. `instrument` raises a LoadError with a hint.
+end
+
+PostHog::MCP.experimental_notice!

data/lib/posthog/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PostHog
-  VERSION = '3.23.7'
+  VERSION = '3.24.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: posthog-ruby
 version: !ruby/object:Gem::Version
-  version: 3.23.7
+  version: 3.24.0
 platform: ruby
 authors:
 - ''
@@ -48,6 +48,31 @@ files:
 - lib/posthog/flag_definition_cache.rb
 - lib/posthog/internal/context.rb
 - lib/posthog/logging.rb
+- lib/posthog/mcp.rb
+- lib/posthog/mcp/README.md
+- lib/posthog/mcp/analytics.rb
+- lib/posthog/mcp/client.rb
+- lib/posthog/mcp/constants.rb
+- lib/posthog/mcp/conversation_id.rb
+- lib/posthog/mcp/event_builder.rb
+- lib/posthog/mcp/exceptions.rb
+- lib/posthog/mcp/identity.rb
+- lib/posthog/mcp/ids.rb
+- lib/posthog/mcp/instrumentation.rb
+- lib/posthog/mcp/intent.rb
+- lib/posthog/mcp/log.rb
+- lib/posthog/mcp/options.rb
+- lib/posthog/mcp/rack_middleware.rb
+- lib/posthog/mcp/request_scope.rb
+- lib/posthog/mcp/sanitization.rb
+- lib/posthog/mcp/schema_mutation.rb
+- lib/posthog/mcp/server_extension.rb
+- lib/posthog/mcp/session.rb
+- lib/posthog/mcp/session_token.rb
+- lib/posthog/mcp/sink.rb
+- lib/posthog/mcp/tools.rb
+- lib/posthog/mcp/tracking_data.rb
+- lib/posthog/mcp/truncation.rb
 - lib/posthog/message_batch.rb
 - lib/posthog/noop_worker.rb
 - lib/posthog/response.rb