posthog-ruby 3.23.7 → 3.24.0

data/lib/posthog/mcp/intent.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module PostHog
+  module MCP
+    # Resolve `$mcp_intent` from the agent-supplied `context` argument (source
+    # `context_parameter`) or the customer's `intent_fallback` (source `inferred`).
+    #
+    # @api private
+    module Intent
+      module_function
+
+      def normalize(intent)
+        return nil unless intent.is_a?(String)
+
+        trimmed = intent.strip
+        trimmed.empty? ? nil : trimmed
+      end
+
+      # @param context [String, nil] the `context` argument, and only when this
+      #   layer owns it. A tool that declares `context` in its own schema is
+      #   passed application data, which is never the agent's stated intent.
+      # @return [Array(String, String), nil] `[intent, source]`
+      def resolve(data, request, extra, context = nil)
+        params = request[:params] || request['params'] || {}
+        name = params[:name] || params['name']
+        missing_name = Tools.missing_capability_tool_name(data.options)
+        intent = normalize(context)
+        return [intent, 'context_parameter'] if data.options.context_enabled? && name != missing_name && intent
+
+        run_fallback(data, request, extra)
+      end
+
+      def run_fallback(data, request, extra)
+        fallback = data.options.intent_fallback
+        return nil unless fallback
+
+        intent = normalize(Callbacks.call(fallback, request, extra))
+        intent ? [intent, 'inferred'] : nil
+      rescue StandardError => e
+        Log.debug(data.options, "intent_fallback callback error: #{e.message}")
+        nil
+      end
+    end
+
+    # Model capture (`capture_model`). MCP does not standardize model identity:
+    # some clients expose it through vendor metadata, others let the agent
+    # self-report through the injected `llm_model` argument. Client metadata wins;
+    # `$mcp_llm_model_source` preserves provenance. Both are unverified.
+    #
+    # @api private
+    module ModelCapture
+      PARAM_NAME = 'llm_model'
+      CODEX_TURN_METADATA_KEY = 'x-codex-turn-metadata'
+
+      module_function
+
+      def normalize(model)
+        return nil unless model.is_a?(String)
+
+        trimmed = model.strip
+        trimmed.empty? || trimmed.casecmp('unknown').zero? ? nil : trimmed
+      end
+
+      # @param request [Hash] JSON-RPC-shaped request (params may carry `_meta`)
+      # @param self_reported [String, nil] the stripped `llm_model` argument, if the SDK owned it
+      # @return [Array(String, String), nil] `[model, source]`
+      def resolve(request, self_reported)
+        params = request[:params] || request['params'] || {}
+        meta = params[:_meta] || params['_meta']
+        codex = meta.is_a?(Hash) ? (meta[CODEX_TURN_METADATA_KEY] || meta[CODEX_TURN_METADATA_KEY.to_sym]) : nil
+        if codex.is_a?(Hash)
+          model = normalize(codex['model'] || codex[:model])
+          return [model, 'client_metadata'] if model
+        end
+
+        model = normalize(self_reported)
+        model ? [model, 'self_reported'] : nil
+      end
+    end
+
+    # Raw transport headers stamped per event (HTTP only, never cached).
+    #
+    # @api private
+    module TransportIdentity
+      CLIENT_USER_AGENT_HEADER = 'user-agent'
+      VENDOR_CLIENT_HEADER = 'x-anthropic-client'
+
+      module_function
+
+      def stamp(event, headers)
+        return event unless headers.is_a?(Hash)
+
+        user_agent = headers[CLIENT_USER_AGENT_HEADER]
+        vendor = headers[VENDOR_CLIENT_HEADER]
+        event['client_user_agent'] = user_agent if user_agent.is_a?(String) && !user_agent.empty?
+        event['vendor_client'] = vendor if vendor.is_a?(String) && !vendor.empty?
+        event
+      end
+    end
+  end
+end

data/lib/posthog/mcp/log.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module PostHog
+  module MCP
+    # Logging for the MCP integration.
+    #
+    # Debug-level chatter goes only to the `logger:` option (a no-op by default),
+    # because a stdio MCP server owns `$stdout` for the protocol and the core
+    # SDK's default logger writes there. Warnings additionally reach the app's
+    # logger when Rails is loaded (where {PostHog::Logging.logger} wraps
+    # `Rails.logger`) and stderr otherwise, so misconfiguration is never silent
+    # and never corrupts a stdio transport.
+    #
+    # @api private
+    module Log
+      module_function
+
+      def debug(options, message)
+        sink = options.respond_to?(:logger) ? options.logger : nil
+        sink&.call(message)
+      rescue StandardError
+        nil
+      end
+
+      def warn(options, message)
+        debug(options, message)
+        if defined?(::Rails)
+          PostHog::Logging.logger.warn(message)
+        else
+          Kernel.warn("[posthog-ruby] #{message}")
+        end
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/posthog/mcp/options.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module PostHog
+  module MCP
+    # Description override for the injected `context` argument.
+    #
+    # @!attribute description
+    #   @return [String, nil]
+    ContextOptions = Struct.new(:description, keyword_init: true)
+
+    # Description override for the injected `llm_model` argument.
+    #
+    # @!attribute description
+    #   @return [String, nil]
+    ModelOptions = Struct.new(:description, keyword_init: true)
+
+    # Resolved identity for a session. `distinct_id` becomes the event's
+    # distinct id, `properties` go to `$set`, `groups` (`{group_type => group_key}`)
+    # are stamped on every event as `$groups`.
+    UserIdentity = Struct.new(:distinct_id, :properties, :groups, keyword_init: true) do
+      # @api private
+      def self.coerce(value)
+        case value
+        when UserIdentity then value
+        when Hash
+          distinct_id = value[:distinct_id] || value['distinct_id'] || value[:distinctId] || value['distinctId']
+          return nil if distinct_id.nil? || distinct_id.to_s.empty?
+
+          new(
+            distinct_id: distinct_id.to_s,
+            properties: value[:properties] || value['properties'],
+            groups: value[:groups] || value['groups']
+          )
+        end
+      end
+    end
+
+    # Result of {PostHog::MCP::Client#prepare_tool_call}: the intent and the
+    # self-reported model pulled off the call, the arguments with the injected
+    # `context` and `llm_model` stripped, and whether the call targeted the
+    # `get_more_tools` virtual tool.
+    PreparedToolCall = Struct.new(:args, :intent, :intent_source, :llm_model, :llm_model_source,
+                                  :is_missing_capability, keyword_init: true)
+
+    # Configuration for {PostHog::MCP.instrument}.
+    #
+    # @note Experimental: option names may change in a future minor release.
+    class Options
+      # @return [#call, nil] STDIO-safe log sink receiving single String messages. Default: no-op.
+      attr_reader :logger
+      # @return [Boolean] Register the `get_more_tools` virtual tool. Default false.
+      attr_reader :report_missing
+      # @return [String] Name of the virtual tool. Default `get_more_tools`.
+      attr_reader :missing_capability_tool_name
+      # @return [Boolean] Inject `conversation_id` and anchor `$session_id` on it. Default false.
+      attr_reader :enable_conversation_id
+      # @return [Boolean] Emit a sibling `$exception` event for failed calls. Default true.
+      attr_reader :enable_exception_autocapture
+      # @return [Boolean, ContextOptions] Inject the required `context` argument. Default true.
+      attr_reader :context
+      # @return [Boolean, ModelOptions] Capture `$mcp_llm_model`. Default false.
+      attr_reader :capture_model
+      # @return [#call, UserIdentity, Hash, nil] `(request, extra) -> UserIdentity | Hash | nil`, or a static identity.
+      attr_reader :identify
+      # @return [#call, nil] `(request, extra) -> String | nil`, consulted when no `context` arg was passed.
+      attr_reader :intent_fallback
+      # @return [#call, nil] `(payload) -> payload | nil`; runs once per emitted payload, nil drops it.
+      attr_reader :before_send
+      # @return [#call, nil] `(request, extra) -> Hash | nil`, spread flat onto every auto-captured event.
+      attr_reader :event_properties
+
+      def initialize(logger: nil, report_missing: false, missing_capability_tool_name: nil,
+                     enable_conversation_id: false, enable_exception_autocapture: true, context: true,
+                     capture_model: false, identify: nil, intent_fallback: nil, before_send: nil,
+                     event_properties: nil)
+        @logger = logger
+        @report_missing = report_missing == true
+        @missing_capability_tool_name = missing_capability_tool_name
+        @enable_conversation_id = enable_conversation_id == true
+        @enable_exception_autocapture = enable_exception_autocapture != false
+        @context = normalize_context(context)
+        @capture_model = normalize_model(capture_model)
+        @identify = identify
+        @intent_fallback = intent_fallback
+        @before_send = before_send
+        @event_properties = event_properties
+      end
+
+      # @return [Boolean]
+      def context_enabled?
+        @context != false
+      end
+
+      # @return [String, nil]
+      def context_description
+        @context.is_a?(ContextOptions) ? @context.description : nil
+      end
+
+      # @return [Boolean]
+      def capture_model_enabled?
+        @capture_model != false
+      end
+
+      # @return [String, nil]
+      def model_description
+        @capture_model.is_a?(ModelOptions) ? @capture_model.description : nil
+      end
+
+      private
+
+      def normalize_context(context)
+        case context
+        when false, nil then context.nil?
+        when Hash then ContextOptions.new(description: context[:description] || context['description'])
+        else context
+        end
+      end
+
+      def normalize_model(capture_model)
+        case capture_model
+        when Hash then ModelOptions.new(description: capture_model[:description] || capture_model['description'])
+        when true, ModelOptions then capture_model
+        else false
+        end
+      end
+    end
+  end
+end

data/lib/posthog/mcp/rack_middleware.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module PostHog
+  module MCP
+    # Rack middleware for stateless / multi-pod MCP servers built on a custom
+    # Rack stack (not the `mcp` gem's Streamable HTTP transport, which
+    # {PostHog::MCP.instrument} wires automatically).
+    #
+    # It publishes the request's headers to {RequestScope}, so an instrumented
+    # `MCP::Server` dispatched anywhere below it sees the HTTP context the gem's
+    # own transport would have given it, and it carries the `Mcp-Session-Id`
+    # token minted at `initialize` back onto the response. Clients replay that
+    # token on every request, so any pod recovers `$session_id` and the client
+    # identity from the header alone.
+    #
+    # Neither the request nor the response body is read here. The token comes
+    # from whoever handled the request and already knows it succeeded: the
+    # instrumented server, or - for a hand-rolled dispatcher built on
+    # {PostHog::MCP::Client} - a call to the mint hook this middleware exposes as
+    # `env['posthog_mcp.mint']`.
+    #
+    # The decoded token (replayed or freshly minted) is exposed to the app as
+    # `env['posthog_mcp.session']` ({SessionTokenPayload}).
+    #
+    # @note Experimental. `PostHog::MCP` is not officially supported; see the
+    #   docs at https://posthog.com/docs/mcp-analytics.
+    #
+    # @example An instrumented server behind a custom Rack stack
+    #   use PostHog::MCP::RackMiddleware
+    #
+    # @example A hand-rolled dispatcher minting the session itself
+    #   session = env['posthog_mcp.mint']&.call(
+    #     client_name: info['name'], client_version: info['version'], protocol_version: params['protocolVersion']
+    #   )
+    #   analytics.capture_initialize(session_id: session&.session_id, ...)
+    class RackMiddleware
+      ENV_KEY = 'posthog_mcp.session'
+      MINT_ENV_KEY = 'posthog_mcp.mint'
+
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        replayed = SessionToken.decode(SessionToken.read_header(MCP_SESSION_HEADER => env['HTTP_MCP_SESSION_ID']))
+        env[ENV_KEY] = replayed if replayed
+
+        RequestScope.with(headers: RequestScope.headers_from_env(env), transport: :http) do |scope|
+          env[MINT_ENV_KEY] = mint_hook(scope, env) unless replayed
+          status, headers, body = @app.call(env)
+          settle_token(scope[:mint], status, headers, env, replayed)
+          [status, headers, body]
+        ensure
+          env.delete(MINT_ENV_KEY)
+        end
+      end
+
+      private
+
+      # A token is minted only once the handshake produced an `InitializeResult`,
+      # so a rejected `initialize` - including a JSON-RPC error riding on a 200 -
+      # mints nothing. The status check covers a hand-rolled dispatcher that
+      # minted and then failed the request: the client never gets a session it
+      # cannot use, and `env` stops advertising one.
+      def settle_token(token, status, headers, env, replayed)
+        return if token.nil?
+
+        if success?(status) && attachable?(headers)
+          headers[MCP_SESSION_HEADER] = token
+          env[ENV_KEY] = SessionToken.decode(token)
+        elsif !replayed
+          env.delete(ENV_KEY)
+        end
+      end
+
+      def success?(status)
+        status.to_i.between?(200, 299)
+      end
+
+      def attachable?(headers)
+        headers.respond_to?(:key?) && headers.keys.none? { |key| key.to_s.casecmp?(MCP_SESSION_HEADER) }
+      end
+
+      # `env['posthog_mcp.mint']`, for a dispatcher that handles `initialize`
+      # itself: call it once the handshake is accepted to get the session this
+      # request belongs to. Only present when the client replayed no token, and
+      # nil for a modern-era client (protocol revision 2026-07-28 or later), which
+      # must not be answered with an `Mcp-Session-Id`.
+      #
+      # @return [Proc] `(client_name:, client_version:, protocol_version:) -> SessionTokenPayload | nil`
+      def mint_hook(scope, env)
+        lambda do |client_name: nil, client_version: nil, protocol_version: nil|
+          next env[ENV_KEY] if scope[:mint]
+          next nil unless Instrumentation.legacy_era?(protocol_version)
+
+          payload = SessionTokenPayload.new(
+            session_id: Session.new_session_id,
+            client_name: string_or_nil(client_name),
+            client_version: string_or_nil(client_version),
+            protocol_version: string_or_nil(protocol_version)
+          )
+          scope[:mint] = SessionToken.encode(payload)
+          env[ENV_KEY] = payload
+        end
+      end
+
+      def string_or_nil(value)
+        value.is_a?(String) && !value.empty? ? value : nil
+      end
+    end
+  end
+end

data/lib/posthog/mcp/request_scope.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module PostHog
+  module MCP
+    # Request-scoped hand-off from the Streamable HTTP transport to the server
+    # extension. The `mcp` gem re-parses the JSON body between
+    # `StreamableHTTPTransport#handle_request` and `Server#handle_json`, so the
+    # HTTP headers cannot travel with the request object; this is the one place
+    # the integration relies on ambient state.
+    #
+    # Uses fiber storage (`Fiber[]`, Ruby 3.2+), which is per fiber, isolated per
+    # Ractor, and inherited by fibers/threads a tool spawns. Falls back to
+    # fiber-local `Thread.current[]` on Ruby 3.0/3.1.
+    #
+    # @api private
+    module RequestScope
+      KEY = :posthog_mcp_request_scope
+      FIBER_STORAGE = Fiber.respond_to?(:[]) && Fiber.respond_to?(:[]=)
+
+      # Rack `env` keys for the headers the integration reads, by header name.
+      HEADER_ENV_KEYS = {
+        'user-agent' => 'HTTP_USER_AGENT',
+        'x-anthropic-client' => 'HTTP_X_ANTHROPIC_CLIENT',
+        'mcp-session-id' => 'HTTP_MCP_SESSION_ID',
+        'mcp-protocol-version' => 'HTTP_MCP_PROTOCOL_VERSION'
+      }.freeze
+
+      module_function
+
+      # @return [Hash, nil] `{headers:, transport:, mint:, session_id:}` for the in-flight HTTP request,
+      #   plus `actor:` once {Instrumentation} has resolved identity for it.
+      #   `session_id` is the `$session_id` {Instrumentation} settled on before running the
+      #   tool body, and `actor` the identity it resolved, so a custom event captured inside
+      #   the tool is attributed to this request - to the right session and the right person -
+      #   even while another request on the same server is in flight. `actor` is absent until
+      #   the request resolves identity, which is what tells {Analytics} it has none to use.
+      def current
+        FIBER_STORAGE ? Fiber[KEY] : Thread.current[KEY]
+      end
+
+      def current=(value)
+        if FIBER_STORAGE
+          Fiber[KEY] = value
+        else
+          Thread.current[KEY] = value
+        end
+      end
+
+      # @param headers [Hash{String => String}] lowercase header names
+      # @param transport [Symbol] `:http` for the Streamable HTTP transport, `:other`
+      #   for a transport that publishes no headers (stdio, a custom dispatcher)
+      # @param env [Hash] a Rack `env`
+      # @return [Hash{String => String}] the headers {Instrumentation} reads, lowercase
+      def headers_from_env(env)
+        return {} unless env.is_a?(Hash)
+
+        HEADER_ENV_KEYS.each_with_object({}) do |(name, env_key), acc|
+          value = env[env_key]
+          acc[name] = value if value.is_a?(String) && !value.empty?
+        end
+      end
+
+      def with(headers:, transport: :http)
+        previous = current
+        self.current = { headers: headers, transport: transport, mint: nil, session_id: nil }
+        yield current
+      ensure
+        self.current = previous
+      end
+    end
+  end
+end