posthog-ruby 3.23.8 → 3.24.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4074fb22041c597b36316d8f5ecd613adeb94c6e5440af887dbb0e4ccf95eb1
-  data.tar.gz: b0a587ad8bef2e363321de12c0fdb7cce636fc80338caa3e4009855d4665e9ce
+  metadata.gz: 471bfa76731003cb33a963c903119506339f2e5cc51eb5b326a8af5df7deaabd
+  data.tar.gz: c41215d0fcc1edc5894b513788ca1e5777e98061f6017e80ae845c46c009d906
 SHA512:
-  metadata.gz: 2aa7c9f54b15c7f4a53f3ed54419ac052a4ecbf9ab4b6454efe4fa4a99389e40ce35cf218aa19f5030e4cfb6ef3dcdb6d4669404687e050029d8ef77fb40a035
-  data.tar.gz: e3438baa285a1fab688cf3f7aa3192f87c5719c1dc086a43147d6f1e88609ec9281479a80984726c59a0ae26a1a1f2faf069e3428f9f7a6f9b6d89efb0e1c31b
+  metadata.gz: f183202aacd689a033e142a57d79355b115306fc39538220c7b002828883d15c8c61cccd29f3a40c7fde95df2ddefd55cebc4f0eab8fdf5cb9a800887b2536bd
+  data.tar.gz: 02123c015cb06e724ab63576948dbf928c7ce1f919772c0e5b70d69d62e2b7ce27ccbbb8a16b24de583c608d8566f5c7da806a2756cf6a182a40d7ced73d466e

data/lib/posthog/client.rb

@@ -302,6 +302,11 @@ module PostHog
 
       symbolize_keys! attrs
       minimal_flag_called_event = attrs.delete(:_minimal_flag_called_event) == true
+      # Integrations that ride on a host application's client (e.g. PostHog::MCP)
+      # may relabel a single event's `$lib`/`$lib_version` without relabeling the
+      # client or its User-Agent.
+      lib_override = attrs.delete(:_lib)
+      lib_version_override = attrs.delete(:_lib_version)
       enrich_capture_attrs_with_context(attrs)
 
       # Precedence: an explicit `flags` snapshot always wins, regardless of
@@ -370,8 +375,8 @@ module PostHog
       end
 
       attrs[:is_server] = @is_server
-      attrs[:lib] = @lib
-      attrs[:lib_version] = @lib_version
+      attrs[:lib] = lib_override || @lib
+      attrs[:lib_version] = (lib_version_override || @lib_version).to_s
       message = FieldParser.parse_for_capture(attrs)
       # Minimal events are built from the allowlist after full assembly so
       # context properties and parser-added metadata can never leak in.

data/lib/posthog/mcp/README.md

@@ -0,0 +1,53 @@
+# PostHog MCP analytics for Ruby
+
+> **Experimental and unsupported.** `PostHog::MCP` is not an officially supported PostHog SDK: no
+> support is provided for it, and its API, options, and the captured `$mcp_*` event schema may change
+> in a minor release. A one-line warning is logged when you require it. Bug reports and patches are
+> welcome at https://github.com/PostHog/posthog-ruby/issues, but don't build production reporting on
+> it yet.
+
+Product analytics for [Model Context Protocol](https://modelcontextprotocol.io) servers built on the
+official Ruby [`mcp`](https://rubygems.org/gems/mcp) gem. Wrap an `MCP::Server` so every tool call,
+agent intent, handshake, listing, prompt, resource read, and failure is captured to PostHog.
+
+**Documentation: https://posthog.com/docs/mcp-analytics** — setup, every option, the event and
+property catalog, sessions on stateless/multi-pod servers, conversation ids, intent, identifying
+users, privacy, and custom dispatchers. That's the single source of truth; this directory
+deliberately keeps no second copy of it.
+
+Install is just `gem 'posthog-ruby'`. `PostHog::MCP.instrument` needs the `mcp` gem (`>= 1.4`) at
+runtime, but anyone wrapping a server already has it. `PostHog::MCP::Client` (custom dispatchers)
+needs nothing beyond `posthog-ruby`.
+
+## Ruby-specific notes
+
+These are the few things that differ from what the docs describe for the other SDKs.
+
+* **`$lib` is per event.** MCP events report `$lib: "posthog-ruby-mcp"` while the client you pass in
+  keeps its own identity (`posthog-ruby` or `posthog-rails`) for everything else it sends, so
+  instrumenting a server inside a Rails app doesn't relabel the app's other events.
+* **Truncation is tighter.** Events are truncated to fit the core client's 32KB per-message limit,
+  because posthog-ruby drops larger messages at batch time - truncating harder beats losing the
+  event.
+* **Request scope needs Ruby 3.2+ to be inherited.** A custom event captured from a thread or fiber
+  a tool spawns is attributed to that request on 3.2+ (fiber storage); before 3.2 capture from the
+  tool body itself, or an HTTP server falls back to a standalone session.
+* **Composed schemas are left alone.** A tool whose `input_schema` is `oneOf`/`allOf`/`anyOf` or a
+  `$ref` has nothing injected into it and nothing stripped from its calls.
+* **stdio servers own `$stdout`.** The integration's own messages go only to the `logger:` you pass
+  (default: nowhere); the experimental notice and misconfiguration warnings go to stderr. Point the
+  core SDK's logger away from stdout too: `PostHog::Logging.logger = Logger.new($stderr)`.
+
+## Layout
+
+| File | What it does |
+|---|---|
+| `mcp.rb` (parent dir) | `PostHog::MCP.instrument` and the public helpers |
+| `server_extension.rb` | Prepended onto `MCP::Server` and the Streamable HTTP transport |
+| `instrumentation.rb` | Per-request dispatch: intent, identity, sessions, recording |
+| `client.rb` | `PostHog::MCP::Client` for custom dispatchers |
+| `rack_middleware.rb` | `Mcp-Session-Id` tokens for a custom Rack stack |
+| `sanitization.rb`, `truncation.rb` | Redaction and payload budgets |
+
+Runnable example: [`examples/mcp_server.rb`](../../../examples/mcp_server.rb). Specs:
+`spec/posthog/mcp/`.

data/lib/posthog/mcp/analytics.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module PostHog
+  module MCP
+    # Handle returned by {PostHog::MCP.instrument}. Emits custom events onto the
+    # same pipeline as the auto-captured `$mcp_*` events.
+    #
+    # @note Experimental.
+    class Analytics
+      # @api private
+      def initialize(server)
+        @server = server
+      end
+
+      # Capture a custom event scoped to the current MCP session. The event
+      # name is sent verbatim (a customer event, not `$`-prefixed).
+      #
+      # Inside a tool body the session and the identity are the ones pinned to
+      # the in-flight request by {Instrumentation}, so a concurrent request on
+      # the same session cannot reattribute this event. Over stdio, where a
+      # server only ever talks to one client, the session is the server's
+      # current one. On an HTTP server a call that has lost the request scope
+      # gets a standalone session rather than the server's, which may belong to
+      # another caller's request.
+      #
+      # @param event [String] event name
+      # @param properties [Hash] event properties
+      # @return [void]
+      # @raise [ArgumentError] when the event name is blank
+      def capture(event, properties = {})
+        unless event.is_a?(String) && !event.strip.empty?
+          raise ArgumentError, 'capture() requires an event name, e.g. analytics.capture("feedback_submitted")'
+        end
+
+        data = PostHog::MCP.tracking_data(@server)
+        return if data.nil?
+
+        scope = RequestScope.current
+        scope = nil unless scope.is_a?(Hash)
+        Instrumentation.capture_event(data, {
+                                        'session_id' => current_session_id(data, scope),
+                                        'event_type' => EventType::CUSTOM,
+                                        'event_name' => event,
+                                        'timestamp' => Time.now.utc,
+                                        'properties' => properties
+                                      }, actor: scoped_actor(scope))
+        nil
+      end
+
+      # Flush the underlying PostHog client.
+      #
+      # @return [void]
+      def flush
+        data = PostHog::MCP.tracking_data(@server)
+        client = data&.sink&.client
+        client.flush if client.respond_to?(:flush)
+        nil
+      end
+
+      private
+
+      # The session pinned to the in-flight request, when there is one. On a server
+      # that has served an HTTP request the server-wide session is not a safe
+      # fallback: it belongs to whichever request settled it last, which under
+      # concurrency is somebody else's. That happens when a tool hands its work to
+      # a thread or fiber it spawned on Ruby 3.0/3.1, where {RequestScope} is
+      # fiber-local and is not inherited. Fail closed with a standalone session
+      # rather than filing the event under another caller's identity; over stdio a
+      # server only ever talks to one client, so the fallback stays.
+      def current_session_id(data, scope)
+        scoped = scope ? scope[:session_id] : nil
+        return scoped if scoped
+        return data.session_id unless data.http_transport_seen
+
+        warn_unscoped_capture(data)
+        Session.new_session_id
+      end
+
+      # The identity the in-flight request resolved, which {Instrumentation} pinned
+      # on the scope before running the tool body. Absent outside a request it
+      # started, and only then is the session-keyed cache consulted instead.
+      def scoped_actor(scope)
+        scope&.key?(:actor) ? scope[:actor] : Instrumentation::UNRESOLVED_ACTOR
+      end
+
+      def warn_unscoped_capture(data)
+        return if data.warned_unscoped_capture
+
+        data.warned_unscoped_capture = true
+        Log.warn(
+          data.options,
+          'Warning: analytics.capture() ran without the scope of the request that started it, so its event got ' \
+          'a standalone $session_id instead of the caller\'s. On Ruby 3.2+ the scope follows threads and fibers ' \
+          'a tool spawns; before that it does not, so capture custom events from the tool body itself.'
+        )
+      end
+    end
+
+    # Returned when instrumentation could not be set up; every call is a no-op.
+    #
+    # @api private
+    class NoopAnalytics < Analytics
+      def initialize
+        super(nil)
+      end
+
+      def capture(_event = nil, _properties = {})
+        nil
+      end
+
+      def flush
+        nil
+      end
+    end
+  end
+end

data/lib/posthog/mcp/client.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+module PostHog
+  module MCP
+    # A {PostHog::Client} with first-class MCP analytics for custom dispatchers
+    # (your own HTTP layer, no `MCP::Server` to wrap). The host resolves
+    # identity and context per request and calls the capture methods directly;
+    # events flow through the same sanitize -> truncate -> `$exception` fan-out
+    # pipeline as {PostHog::MCP.instrument}. Does not need the `mcp` gem.
+    #
+    # @note Experimental.
+    #
+    # @example
+    #   posthog = PostHog::MCP::Client.new(api_key: 'phc_...', host: 'https://us.i.posthog.com')
+    #   posthog.capture_tool_call('search_docs', duration_ms: 42, distinct_id: 'user_123')
+    class Client < PostHog::Client
+      # @param opts [Hash] {PostHog::Client} options plus:
+      # @option opts [String] :missing_capability_tool_name name of the virtual tool (default `get_more_tools`)
+      # @option opts [Boolean] :mcp_exception_autocapture emit a sibling `$exception` for failed calls (default true)
+      def initialize(opts = {})
+        opts = opts.transform_keys(&:to_sym)
+        @missing_capability_tool_name = opts.delete(:missing_capability_tool_name) || Tools::GET_MORE_TOOLS_NAME
+        @mcp_exception_autocapture = opts.delete(:mcp_exception_autocapture) != false
+        super
+        @mcp_sink = Sink.new(self)
+        @mcp_options = Options.new(
+          enable_exception_autocapture: @mcp_exception_autocapture,
+          missing_capability_tool_name: @missing_capability_tool_name
+        )
+      end
+
+      # Capture a tool invocation. Emits `$mcp_tool_call` (+ `$exception` on error).
+      #
+      # @return [void]
+      def capture_tool_call(tool_name, intent: nil, intent_source: nil, parameters: nil, response: nil,
+                            duration_ms: nil, is_error: false, error: nil, error_type: nil, category: nil,
+                            tool_description: nil, protocol_version: nil, distinct_id: nil, session_id: nil,
+                            client_user_agent: nil, vendor_client: nil, set_properties: nil, groups: nil,
+                            properties: nil, timestamp: nil, llm_model: nil, llm_model_source: nil)
+        event = base_event(EventType::MCP_TOOLS_CALL, distinct_id, session_id, set_properties, groups, properties,
+                           timestamp, client_user_agent, vendor_client)
+        event['resource_name'] = tool_name
+        event['tool_description'] = tool_description
+        event['tool_category'] = category
+        event['protocol_version'] = protocol_version
+        event['parameters'] = parameters
+        event['response'] = response
+        event['duration'] = duration_ms
+        event['is_error'] = is_error == true
+        event['error_type'] = error_type
+        apply_intent(event, intent, intent_source)
+        apply_model(event, llm_model, llm_model_source)
+        if is_error
+          event['error'] =
+            Exceptions.capture_exception(error.nil? ? "Tool #{tool_name} returned an error" : error)
+        end
+        emit(event)
+      end
+
+      # Capture the connection handshake. Emits `$mcp_initialize`.
+      #
+      # @return [void]
+      def capture_initialize(client_name: nil, client_version: nil, protocol_version: nil, parameters: nil,
+                             response: nil, duration_ms: nil, distinct_id: nil, session_id: nil,
+                             client_user_agent: nil, vendor_client: nil, set_properties: nil, groups: nil,
+                             properties: nil, timestamp: nil)
+        event = base_event(EventType::MCP_INITIALIZE, distinct_id, session_id, set_properties, groups, properties,
+                           timestamp, client_user_agent, vendor_client)
+        event['client_name'] = client_name
+        event['client_version'] = client_version
+        event['protocol_version'] = protocol_version
+        event['parameters'] = parameters
+        event['response'] = response
+        event['duration'] = duration_ms
+        emit(event)
+      end
+
+      # Capture a `tools/list` response. Emits `$mcp_tools_list` with `$mcp_listed_tool_names`.
+      #
+      # @return [void]
+      def capture_tools_list(tool_names: nil, parameters: nil, response: nil, duration_ms: nil, is_error: false,
+                             error: nil, error_type: nil, protocol_version: nil, distinct_id: nil, session_id: nil,
+                             client_user_agent: nil, vendor_client: nil, set_properties: nil, groups: nil,
+                             properties: nil, timestamp: nil)
+        event = base_event(EventType::MCP_TOOLS_LIST, distinct_id, session_id, set_properties, groups, properties,
+                           timestamp, client_user_agent, vendor_client)
+        event['listed_tool_names'] = tool_names
+        event['protocol_version'] = protocol_version
+        event['parameters'] = parameters
+        event['response'] = response
+        event['duration'] = duration_ms
+        event['is_error'] = is_error == true
+        event['error_type'] = error_type
+        event['error'] = Exceptions.capture_exception(error.nil? ? 'tools/list failed' : error) if is_error
+        emit(event)
+      end
+
+      # Capture a `get_more_tools` call as a missing-capability report. Emits
+      # `$mcp_missing_capability` with the agent's description as `$mcp_intent`.
+      #
+      # @return [void]
+      def capture_missing_capability(context: nil, parameters: nil, protocol_version: nil, distinct_id: nil,
+                                     session_id: nil, client_user_agent: nil, vendor_client: nil,
+                                     set_properties: nil, groups: nil, properties: nil, timestamp: nil,
+                                     llm_model: nil, llm_model_source: nil)
+        event = base_event(EventType::MCP_MISSING_CAPABILITY, distinct_id, session_id, set_properties, groups,
+                           properties, timestamp, client_user_agent, vendor_client)
+        event['resource_name'] = @missing_capability_tool_name
+        event['protocol_version'] = protocol_version
+        event['parameters'] = parameters
+        apply_intent(event, context, 'context_parameter')
+        apply_model(event, llm_model, llm_model_source)
+        emit(event)
+      end
+
+      # Inject the `context` argument (and, with `capture_model`, `llm_model`) into
+      # every tool descriptor (Hash with `inputSchema`) so agents state their intent,
+      # and optionally append the `get_more_tools` virtual tool. Returns a new Array
+      # of new Hashes. A tool whose schema is composed (oneOf/allOf/anyOf) or a
+      # `$ref` is passed through untouched.
+      #
+      # @param tools [Array<Hash>] `tools/list` entries
+      # @return [Array<Hash>]
+      def prepare_tool_list(tools, context: true, report_missing: false, capture_model: false)
+        options = Options.new(context: context, capture_model: capture_model)
+        prepared = tools.map do |tool|
+          next tool unless tool.is_a?(Hash) && (options.context_enabled? || options.capture_model_enabled?)
+
+          name = SchemaMutation.fetch(tool, :name) || 'unknown'
+          next tool if name == @missing_capability_tool_name
+
+          schema = SchemaMutation.fetch(tool, :inputSchema)
+          if options.context_enabled?
+            schema = SchemaMutation.add_context_parameter(schema, tool_name: name,
+                                                                  description: options.context_description)
+          end
+          if options.capture_model_enabled?
+            schema = SchemaMutation.add_model_parameter(schema, tool_name: name,
+                                                                description: options.model_description)
+          end
+          tool.merge(SchemaMutation.key_for(tool, :inputSchema) => schema)
+        end
+        if report_missing && prepared.none? { |t| SchemaMutation.fetch(t, :name) == @missing_capability_tool_name }
+          prepared << Tools.descriptor(@missing_capability_tool_name, options)
+        end
+        prepared
+      end
+
+      # Pull the agent's intent off the `context` argument and its self-reported
+      # model off `llm_model`, strip the arguments this integration injected, and
+      # flag the `get_more_tools` virtual tool. Hand `intent`/`intent_source` and
+      # `llm_model`/`llm_model_source` straight to {#capture_tool_call}.
+      #
+      # Pass the tool's own `inputSchema` (the same Hash you handed to
+      # {#prepare_tool_list}) so a field the tool declares itself is left in
+      # `args` and never read as analytics: only an injected argument is stripped
+      # and reported. A composed (oneOf/allOf/anyOf) or `$ref` schema is never
+      # injected into, so its fields are the tool's own and are left alone too.
+      # Without the schema there is no way to tell the two apart, so the injected
+      # names are always stripped.
+      #
+      # @param name [String] tool name
+      # @param args [Hash, nil] the call's arguments
+      # @param input_schema [Hash, nil] the tool's raw `inputSchema`
+      # @return [PreparedToolCall]
+      def prepare_tool_call(name, args = nil, input_schema: nil)
+        intent = tool_declares?(input_schema, 'context') ? nil : Intent.normalize(argument(args, 'context'))
+        model = if tool_declares?(input_schema, ModelCapture::PARAM_NAME)
+                  nil
+                else
+                  ModelCapture.normalize(argument(args, ModelCapture::PARAM_NAME))
+                end
+        PreparedToolCall.new(
+          args: strip_injected(args, input_schema),
+          intent: intent,
+          intent_source: intent ? 'context_parameter' : nil,
+          llm_model: model,
+          llm_model_source: model ? 'self_reported' : nil,
+          is_missing_capability: name == @missing_capability_tool_name
+        )
+      end
+
+      private
+
+      def base_event(event_type, distinct_id, session_id, set_properties, groups, properties, timestamp,
+                     client_user_agent, vendor_client)
+        event = {
+          'event_type' => event_type,
+          'session_id' => session_id,
+          'timestamp' => timestamp || Time.now.utc,
+          'properties' => properties,
+          'groups' => groups,
+          'client_user_agent' => client_user_agent,
+          'vendor_client' => vendor_client
+        }
+        event['identify_actor_given_id'] = distinct_id if distinct_id.is_a?(String) && !distinct_id.empty?
+        event['identify_actor_data'] = set_properties if set_properties.is_a?(Hash) && !set_properties.empty?
+        event
+      end
+
+      def apply_model(event, llm_model, source)
+        model = ModelCapture.normalize(llm_model)
+        return unless model
+
+        event['llm_model'] = model
+        event['llm_model_source'] = source || 'self_reported'
+      end
+
+      def apply_intent(event, intent, source)
+        trimmed = intent.is_a?(String) ? intent.strip : ''
+        return if trimmed.empty?
+
+        event['user_intent'] = trimmed
+        event['user_intent_source'] = source || 'context_parameter'
+      end
+
+      def emit(event)
+        @mcp_sink.capture(event, @mcp_options)
+        nil
+      end
+
+      # True when the argument belongs to the tool rather than to this layer: it
+      # declares the field itself, or its schema is one we never inject into.
+      def tool_declares?(input_schema, param)
+        return false unless input_schema
+
+        !SchemaMutation.injectable?(input_schema) || SchemaMutation.declares_param?(input_schema, param)
+      end
+
+      def argument(args, param)
+        return nil unless args.is_a?(Hash)
+
+        args[param.to_sym] || args[param]
+      end
+
+      def strip_injected(args, input_schema)
+        return args unless args.is_a?(Hash)
+
+        keys = ['context', ModelCapture::PARAM_NAME].reject { |param| tool_declares?(input_schema, param) }
+                                                    .flat_map { |param| [param.to_sym, param] }
+                                                    .select { |key| args.key?(key) }
+        keys.empty? ? args : args.except(*keys)
+      end
+    end
+  end
+end

data/lib/posthog/mcp/constants.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module PostHog
+  module MCP
+    # Value of `$mcp_source` on every primary `$mcp_*` event.
+    SOURCE = 'posthog_mcp_analytics'
+
+    # `$lib` stamped on MCP analytics events (per event, never on the client).
+    LIB_NAME = 'posthog-ruby-mcp'
+
+    # Generated (in-memory) sessions roll over after this much inactivity.
+    INACTIVITY_TIMEOUT_MINUTES = 30
+
+    # Header carrying the transport session id, and our self-encoded token.
+    MCP_SESSION_HEADER = 'mcp-session-id'
+
+    # Description of the injected `context` argument.
+    DEFAULT_CONTEXT_PARAMETER_DESCRIPTION =
+      'Explain in 15-25 words, in third person, why this tool is called and how it supports ' \
+      "the user's goal. For analytics only. You MUST describe only the abstract purpose of the " \
+      'tool call. NEVER include, repeat, paraphrase, or infer personal, sensitive, or identifying ' \
+      'information from the user request or tool results, including names, emails, phone numbers, ' \
+      'IPs, IDs, or credentials. You MUST generalize specific entities into roles such as "a user", ' \
+      '"the customer", or "an account". Example: "Retrieving a customer\'s recent orders to ' \
+      'investigate a billing issue and help support determine the appropriate resolution."'
+
+    # Description of the injected `llm_model` argument.
+    DEFAULT_MODEL_PARAMETER_DESCRIPTION =
+      'The exact model identifier you (the assistant) are running as, taken from your system ' \
+      'prompt or environment (e.g. "claude-opus-4-8", "gpt-5.2"). Used for analytics only. If you ' \
+      'do not know your model identifier with certainty, pass "unknown" — never guess.'
+
+    # Description of the injected `conversation_id` argument.
+    DEFAULT_CONVERSATION_ID_DESCRIPTION =
+      "Echo the conversation_id from the server's previous response. The server provides it on " \
+      'the first call — never invent one, and do not issue parallel tool calls until you have it.'
+
+    # PostHog-owned event names. All `$`-prefixed per the PostHog convention.
+    module Event
+      CUSTOM = '$mcp_custom'
+      EXCEPTION = '$exception'
+      IDENTIFY = '$identify'
+      INITIALIZE = '$mcp_initialize'
+      MISSING_CAPABILITY = '$mcp_missing_capability'
+      PROMPT_GET = '$mcp_prompt_get'
+      PROMPTS_LIST = '$mcp_prompts_list'
+      RESOURCE_READ = '$mcp_resource_read'
+      RESOURCES_LIST = '$mcp_resources_list'
+      TOOL_CALL = '$mcp_tool_call'
+      TOOLS_LIST = '$mcp_tools_list'
+    end
+
+    # PostHog property wire keys emitted on MCP events.
+    module Property
+      CLIENT_NAME = '$mcp_client_name'
+      CLIENT_USER_AGENT = '$mcp_client_user_agent'
+      CLIENT_VERSION = '$mcp_client_version'
+      VENDOR_CLIENT = '$mcp_vendor_client'
+      PROTOCOL_VERSION = '$mcp_protocol_version'
+      CONVERSATION_ID = '$mcp_conversation_id'
+      DURATION_MS = '$mcp_duration_ms'
+      ERROR_MESSAGE = '$mcp_error_message'
+      ERROR_TYPE = '$mcp_error_type'
+      IS_ERROR = '$mcp_is_error'
+      INTENT = '$mcp_intent'
+      INTENT_SOURCE = '$mcp_intent_source'
+      LISTED_TOOL_NAMES = '$mcp_listed_tool_names'
+      LLM_MODEL = '$mcp_llm_model'
+      LLM_MODEL_SOURCE = '$mcp_llm_model_source'
+      PARAMETERS = '$mcp_parameters'
+      RESOURCE_NAME = '$mcp_resource_name'
+      RESPONSE = '$mcp_response'
+      SERVER_NAME = '$mcp_server_name'
+      SERVER_VERSION = '$mcp_server_version'
+      SESSION_ID = '$session_id'
+      SOURCE = '$mcp_source'
+      TOOL_CATEGORY = '$mcp_tool_category'
+      TOOL_DESCRIPTION = '$mcp_tool_description'
+      TOOL_NAME = '$mcp_tool_name'
+    end
+
+    # Internal dispatch keys for the event pipeline (never sent on the wire).
+    #
+    # @api private
+    module EventType
+      CUSTOM = 'posthog:custom'
+      IDENTIFY = 'posthog:identify'
+      MCP_INITIALIZE = 'mcp:initialize'
+      MCP_MISSING_CAPABILITY = 'mcp:missing_capability'
+      MCP_PROMPTS_GET = 'mcp:prompts/get'
+      MCP_PROMPTS_LIST = 'mcp:prompts/list'
+      MCP_RESOURCES_LIST = 'mcp:resources/list'
+      MCP_RESOURCES_READ = 'mcp:resources/read'
+      MCP_TOOLS_CALL = 'mcp:tools/call'
+      MCP_TOOLS_LIST = 'mcp:tools/list'
+
+      EVENT_NAME_BY_TYPE = {
+        CUSTOM => Event::CUSTOM,
+        IDENTIFY => Event::IDENTIFY,
+        MCP_INITIALIZE => Event::INITIALIZE,
+        MCP_MISSING_CAPABILITY => Event::MISSING_CAPABILITY,
+        MCP_PROMPTS_GET => Event::PROMPT_GET,
+        MCP_PROMPTS_LIST => Event::PROMPTS_LIST,
+        MCP_RESOURCES_LIST => Event::RESOURCES_LIST,
+        MCP_RESOURCES_READ => Event::RESOURCE_READ,
+        MCP_TOOLS_CALL => Event::TOOL_CALL,
+        MCP_TOOLS_LIST => Event::TOOLS_LIST
+      }.freeze
+    end
+  end
+end

data/lib/posthog/mcp/conversation_id.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module PostHog
+  module MCP
+    # Optional `conversation_id` loop-back. When enabled, the SDK injects a
+    # `conversation_id` parameter into every tool, mints one when the agent does
+    # not supply it, hands it back on the response, and captures it as
+    # `$mcp_conversation_id`, stitching calls across reconnects and pods.
+    #
+    # @api private
+    module ConversationId
+      PARAM_NAME = 'conversation_id'
+      MINTED_CONVERSATION_ID = /\A[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\z/i
+
+      MCP_INSTRUCTIONS_KEY = '_mcp_instructions'
+      INSTRUCTIONS_FIELD_DESCRIPTION = 'Server-issued metadata for this conversation.'
+      CONVERSATION_ID_FIELD_DESCRIPTION = 'The server-issued conversation identifier.'
+
+      module_function
+
+      def normalize(value)
+        return nil unless value.is_a?(String)
+
+        trimmed = value.strip
+        trimmed.empty? ? nil : trimmed
+      end
+
+      def extract(args)
+        return nil unless args.is_a?(Hash)
+
+        normalize(args[PARAM_NAME] || args[PARAM_NAME.to_sym])
+      end
+
+      # @param supplied [String, nil] the `conversation_id` argument, and only
+      #   when this layer owns it. A tool that declares `conversation_id` in its
+      #   own schema is passed application data, which must not anchor analytics:
+      #   two users sharing such a value would be stitched into one conversation.
+      # @return [Array(String, Boolean), Array(nil, false)] `[conversation_id, minted]`
+      def resolve(enabled, supplied, tool_name, missing_capability_tool_name)
+        return [nil, false] if !enabled || tool_name == missing_capability_tool_name
+
+        value = normalize(supplied)
+        return [value.downcase, false] if value && MINTED_CONVERSATION_ID.match?(value)
+
+        [Ids.uuid_v7, true]
+      end
+
+      def prompt_back?(result)
+        result.is_a?(Hash) && (result[:content] || result['content']).is_a?(Array)
+      end
+
+      # Plain data, not an instruction: an instruction-shaped block is what a
+      # client's prompt-injection filter strips. Compact JSON.
+      def build_prompt_back(conversation_id)
+        { type: 'text', text: JSON.generate({ conversation_id: conversation_id }) }
+      end
+
+      # @return [Hash] a new result with the prompt-back appended (or the input unchanged)
+      def inject_prompt_back(result, conversation_id)
+        return result unless prompt_back?(result)
+
+        key = result.key?(:content) ? :content : 'content'
+        result.merge(key => result[key] + [build_prompt_back(conversation_id)])
+      end
+
+      # Mirror the handle into `structuredContent` for tools whose output schema
+      # declared `_mcp_instructions`. Customer data wins when the key exists.
+      #
+      # @return [Array(Object, Boolean)] `[result, delivered]`
+      def mirror_instructions(result, conversation_id)
+        return [result, false] unless result.is_a?(Hash)
+
+        key = %i[structuredContent structured_content].find { |k| result.key?(k) } ||
+              %w[structuredContent structured_content].find { |k| result.key?(k) }
+        return [result, false] if key.nil?
+
+        structured = result[key]
+        return [result, false] unless structured.is_a?(Hash)
+        return [result, false] if structured.key?(MCP_INSTRUCTIONS_KEY) || structured.key?(MCP_INSTRUCTIONS_KEY.to_sym)
+
+        payload = { 'conversation_id' => conversation_id }
+        instructions_key = structured.keys.first.is_a?(Symbol) ? MCP_INSTRUCTIONS_KEY.to_sym : MCP_INSTRUCTIONS_KEY
+        [result.merge(key => structured.merge(instructions_key => payload)), true]
+      end
+    end
+  end
+end