mcpeye 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a764f79cce8846c6a9bcf750e778de9f88c082518eac5c6c4d271c15743456a4
-  data.tar.gz: c1621b94ab8dc5689cd4b335d1bb4fd79b854c430ea83754c81feb138b510150
+  metadata.gz: 3d50e6d30ef0e2cf6796b7b7b67397c40c11290f289152d124c3ff5417ff6150
+  data.tar.gz: 23729136fae41b35dcf3152354d59fd5e2753d7429831b1f474bc01de56c6d5a
 SHA512:
-  metadata.gz: 5b0c8dd68029607b4126f3f0f9423e560b3a278919edd449498cd7bf3cb11f9edbd14da33b705579a6c719e89d6167c4ac92c47a1f660505c30e1ae27c7e5339
-  data.tar.gz: e88ec3f95170142f0e5fed4aeff5a2e6ad8c1821c818b257c01e0066dedb03e06b0522ebf235ad3379800aeaee010e9f179d3ffc294d9e33c6dd43fb5f35deb9
+  metadata.gz: 84b70bcbed2a41a80a198b44e32b4f84eaa7f753aa3701e708eebc7210e78833dd6a1d67f471ac7e62aa7f1326dd96a75eaa9b3e8946465e78432e2554ee67e7
+  data.tar.gz: a75cc956872617ae3da0400b44b8a54a1f3e2bb7b265ca6e4dad5fb5ae50f453d24ec3256cfda971563091ff77f1a4b33059d6bfc73b378745530ffdefd015a4

data/README.md

@@ -91,10 +91,30 @@ tracker = Mcpeye.track(
 # idempotent.)
 ```
 
-`Mcpeye.track` injects `mcpeyeIntent` into discoverable tool schemas and wraps
-discoverable handlers automatically. Ruby MCP server shapes vary, so when the
-internals can't be introspected `track` returns a working tracker unchanged (and
-reports once via `on_error`) — instrument manually with `#wrap` / `#record`.
+`Mcpeye.track` works **out of the box with the official [`mcp` gem](https://github.com/modelcontextprotocol/ruby-sdk)**
+(`MCP::Server` + `MCP::Tool` subclasses):
+
+```ruby
+require "mcp"
+require "mcpeye"
+
+server = MCP::Server.new(name: "my-server", tools: [SearchTool, OrderTool])
+Mcpeye.track(server, "my-project-id", ingest_url: "http://localhost:3001")
+# That's it — every tools/call is captured and mcpeyeIntent is advertised in tools/list.
+```
+
+For the official gem it hooks the server's `tools/call` and `tools/list` **per
+server instance** (never your global `MCP::Tool` classes), so it captures every
+call — *including* the ones the gem rejects at schema validation, the failed asks
+mcpeye exists to surface — and the injected `mcpeyeIntent` is stripped from the
+arguments before your tool runs (it never reaches your `def self.call` signature).
+It also auto-detects Hash / `fast-mcp` server shapes.
+
+**Call `track` after your tools are registered** (for the official gem, any time
+after `MCP::Server.new(tools: […])`). If a server shape can't be introspected,
+`track` returns a working tracker and **warns loudly via `on_error`** (whose
+default prints to stderr) — it never silently captures nothing — and you can
+instrument manually with `#wrap` / `#record`.
 
 ## Options
 
@@ -145,9 +165,19 @@ MCPEYE = Mcpeye.track(
   ENV.fetch("MCPEYE_PROJECT_ID"),
   ingest_url: ENV.fetch("MCPEYE_INGEST_URL", "http://localhost:3001"),
   ingest_secret: ENV["MCPEYE_INGEST_SECRET"],
-  # Per-request identity: evaluated once per flush, so a thread/request-local
-  # value is attributed correctly. Pass an OPAQUE, non-PII id (coerced to a string).
-  identify: -> { { userId: Current.user_id&.to_s, client: Current.client, serverVersion: MyApp::VERSION } },
+  # End-user identity. `userId`/`userEmail` are resolved PER CALL on the request
+  # thread (so a thread/request-local value like Rails Current / RequestStore is
+  # attributed correctly even on a multi-user / stateless server); client/serverVersion
+  # are read per flush. Pass an OPAQUE, stable userId. This is what powers the
+  # dashboard's search-by-id/email — without it, sessions read "user not identified".
+  identify: lambda {
+    {
+      userId: Current.user_id&.to_s,        # who the end user is (for search)
+      userEmail: Current.user_email,        # human-readable, optional (PII you store)
+      client: Current.client,               # process/connection-level
+      serverVersion: MyApp::VERSION,
+    }
+  },
   # Drop your own domain-sensitive fields on top of the built-in denylist:
   denylist_fields: %w[ssn account_number],
   # Forward diagnostics into your logger instead of stderr:
@@ -155,6 +185,13 @@ MCPEYE = Mcpeye.track(
 )
 ```
 
+> **Multi-user / stateless servers (e.g. a streamable-HTTP MCP).** Because `identify`
+> runs per call on the request thread, set your per-request user context BEFORE the
+> tool dispatches (e.g. in middleware: `RequestStore.store[:current_user_id] = ...`)
+> and read it in `identify` (`RequestStore.store[:current_user_id]`). Each captured
+> call is then attributed to the right user, even though one flushed batch may mix
+> users.
+
 ### Puma / Unicorn (forking servers)
 
 A thread does **not** survive `fork`, so in a clustered server start the flush

data/lib/mcpeye/tracker.rb

@@ -24,7 +24,12 @@ module Mcpeye
   #
   # The wire shape matches @mcpeye/core's IngestPayload exactly (and is
   # byte-compatible with the TS and Python SDKs):
-  #   { projectId, identity: { userId?, client?, serverVersion? }, events: [...] }
+  #   { projectId, identity: { userId?, userEmail?, client?, serverVersion? },
+  #     events: [{ ..., userId?, userEmail? }] }
+  # Each event also carries its OWN userId/userEmail, resolved PER CALL on the
+  # request thread (see #resolve_call_identity) — so attribution is correct on a
+  # multi-user server where one flushed batch mixes users; the batch identity is the
+  # fallback.
   #
   # Prime directive: this NEVER raises into, or alters, the host MCP server. The
   # only intentional raise is an empty `project_id` at construction (fail loud
@@ -44,6 +49,115 @@ module Mcpeye
   # custom Rack handler, ...), so #instrument duck-types the common shapes and
   # degrades gracefully when it cannot introspect a server — you can always
   # capture calls manually with #wrap / #record.
+
+  # Prepended to an official `MCP::Server`'s SINGLETON class so its `call_tool` is
+  # captured at the dispatch layer — the Ruby analog of the TS/Python protocol-level
+  # hook. The official gem invokes `call_tool` directly (mcp 0.20 server.rb), running
+  # required-arg + schema validation there, so wrapping it (not the tool classes) also
+  # captures the validation failures the gem returns BEFORE a tool's own `.call` —
+  # exactly the failed asks mcpeye exists to surface.
+  #
+  # Prepended PER SERVER (this instance's singleton), never to the global `MCP::Tool`
+  # subclasses, so a tool class shared across servers is never bound to one tracker.
+  # Fail-open: the host's return value is always passed through unchanged, and the
+  # injected `mcpeyeIntent` is stripped from the arguments BEFORE `super`, so the gem
+  # never splats it into the host tool's keyword signature (which would raise
+  # `unknown keyword: :mcpeyeIntent` and break the call).
+  module OfficialServerCapture
+    def call_tool(request, **kwargs)
+      tracker = @__mcpeye_tracker
+      return super if tracker.nil?
+
+      name = (request[:name] || request["name"]).to_s
+      raw_args = request[:arguments] || request["arguments"]
+      args = raw_args.is_a?(Hash) ? raw_args : {}
+
+      # Strip the injected intent in place (request[:arguments] is the same object),
+      # so the gem validates/dispatches WITHOUT mcpeyeIntent.
+      intent = nil
+      begin
+        v = args.delete(Mcpeye::Intent::INTENT_PARAM_NAME)
+        v = args.delete(Mcpeye::Intent::INTENT_PARAM_NAME.to_sym) if v.nil?
+        intent = v if v.is_a?(String) && !v.strip.empty?
+      rescue StandardError
+        intent = nil
+      end
+
+      # Reserved capability tool: never dispatch to the host; answer locally.
+      if name == Mcpeye::RequestCapability::TOOL_NAME && tracker.capture_missing_capabilities?
+        return tracker.answer_request_capability_official(args)
+      end
+
+      started = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)
+      begin
+        response = super
+      rescue StandardError => e
+        dur = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond) - started
+        begin
+          tracker.record(name, args, is_error: true, error_message: e.message, intent: intent, duration_ms: dur)
+        rescue StandardError
+          nil
+        end
+        raise
+      end
+
+      begin
+        dur = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond) - started
+        is_error, error_text, result_payload = Mcpeye::OfficialServerCapture.classify(response)
+        if is_error
+          tracker.record(name, args, is_error: true, error_message: error_text, intent: intent, duration_ms: dur)
+        else
+          tracker.record(name, args, result: result_payload, intent: intent, duration_ms: dur)
+        end
+      rescue StandardError
+        nil
+      end
+
+      response
+    end
+
+    # The official gem's call_tool returns EITHER a Hash (`{content:, isError:}`,
+    # the common 0.2x case) OR a Tool::Response object. Classify both into
+    # [is_error, error_text, result_payload]. Fail-open: unknown shapes -> success.
+    def self.classify(response)
+      if response.respond_to?(:error?)
+        payload =
+          if response.respond_to?(:structured_content) && response.structured_content
+            response.structured_content
+          elsif response.respond_to?(:content)
+            { "content" => response.content }
+          else
+            response
+          end
+        [!!response.error?, text_of_content(response.respond_to?(:content) ? response.content : nil), payload]
+      elsif response.is_a?(Hash)
+        flag = response["isError"]
+        flag = response[:isError] if flag.nil?
+        [!!flag, text_of_content(response["content"] || response[:content]), response]
+      else
+        [false, nil, response]
+      end
+    rescue StandardError
+      [false, nil, response]
+    end
+
+    # Join the text parts of an MCP content array (Hash or struct items).
+    def self.text_of_content(content)
+      return nil unless content.is_a?(Array)
+
+      parts = content.filter_map do |item|
+        if item.is_a?(Hash)
+          item[:text] || item["text"]
+        elsif item.respond_to?(:text)
+          item.text
+        end
+      end
+      parts.empty? ? nil : parts.join("\n")
+    rescue StandardError
+      nil
+    end
+  end
+
   class Tracker
     # POST once the buffer reaches this many events (eager flush). When a
     # background flush thread is running it is woken to drain off the hot path;
@@ -73,10 +187,15 @@ module Mcpeye
     # ingest_secret   — shared secret sent as x-mcpeye-secret.
     #                   Defaults to ENV["MCPEYE_INGEST_SECRET"].
     # redact          — when true (default) scrub arguments/result/intent/error client-side.
-    # identity        — static Hash { userId:, client:, serverVersion: }.
-    # identify        — optional callable evaluated once per flush, returning the
-    #                   identity Hash (per-request/thread-local attribution). A
-    #                   raising identify yields {} for that flush, never breaks it.
+    # identity        — static Hash { userId:, userEmail:, client:, serverVersion: }
+    #                   (batch-level fallback).
+    # identify        — optional callable for dynamic attribution. Evaluated PER CALL
+    #                   on the request thread for userId/userEmail (correct per-event
+    #                   attribution on a multi-user server) AND once per flush for the
+    #                   batch identity. Return { userId:, userEmail:, client:,
+    #                   serverVersion: }. A raising identify yields no identity for that
+    #                   call/flush, never breaks the host. Example:
+    #                     identify: -> { { userId: RequestStore.store[:current_user_id] } }
     # flush_threshold — eager-flush buffer size (default 20).
     # flush_interval  — background flush interval in seconds (default nil = no
     #                   background thread; stay zero-thread unless asked).
@@ -143,26 +262,42 @@ module Mcpeye
     # shape matches — you can still use #wrap / #record. Reports once if nothing
     # could be introspected.
     def instrument(server)
+      # Official mcp gem (MCP::Server + MCP::Tool subclasses): dispatch-level,
+      # per-server capture. Distinct from the duck-typed path below, whose tools
+      # are handler-Hashes the official gem never produces.
+      return instrument_official(server) if official_mcp_server?(server)
+
       injected = inject_count(server)
       # Add the reserved tool AFTER intent injection (so it never gets an mcpeyeIntent
       # param) and BEFORE handler wrapping (so its pre-wrapped handler is skipped, not
       # double-wrapped). A no-op when capture_missing_capabilities is off.
       append_request_capability_tool(server)
       wrapped = wrap_handler_count(server)
-      if injected.zero? && wrapped.zero?
-        report_once(
-          :no_introspect,
-          RuntimeError.new(
-            "could not introspect server tools; instrument is a no-op — capture calls manually with #wrap/#record"
-          )
-        )
-      end
+      warn_uninstrumentable(server) if injected.zero? && wrapped.zero?
       server
     rescue StandardError => e
       @on_error.call(e)
       server
     end
 
+    # Whether the reserved mcpeye_request_capability tool is enabled. Read by the
+    # official-server capture module (which lives outside the Tracker instance).
+    def capture_missing_capabilities?
+      @capture_missing_capabilities
+    end
+
+    # Record a reserved-capability call and return the canned ack as a plain
+    # CallToolResult Hash. The official gem serializes call_tool's return value
+    # directly (it does NOT call #to_h), so a Hash — not a Tool::Response object —
+    # is what reaches the client.
+    def answer_request_capability_official(_args = {})
+      handle_request_capability(_args)
+      { "content" => [{ "type" => "text", "text" => RequestCapability::ACK }], "isError" => false }
+    rescue StandardError => e
+      @on_error.call(e)
+      { "content" => [{ "type" => "text", "text" => RequestCapability::ACK }], "isError" => false }
+    end
+
     # Inject the optional mcpeyeIntent property into every discoverable tool's
     # input schema. Returns the server (fail-open). Collision-safe (never clobbers
     # a tool that already declares mcpeyeIntent), never touches `required`, and
@@ -394,6 +529,14 @@ module Mcpeye
       event["errorMessage"] = guard_error_message(error_message.to_s) unless error_message.nil?
       # Only a non-blank intent is recorded (whitespace-only is dropped, TS/Python parity).
       event["intent"] = guard_error_message(intent.to_s) if intent && !intent.to_s.strip.empty?
+      # Per-CALL end-user identity. build_event runs on the caller's (request) thread
+      # — via the official call_tool hook or the wrap proc — so `identify` is evaluated
+      # where the host's per-request user context is live (unlike the per-flush batch
+      # identity, which runs on the flush thread). This is what makes attribution
+      # correct on a multi-user server. Per-event values win over the batch identity.
+      uid, uemail = resolve_call_identity
+      event["userId"] = uid if uid
+      event["userEmail"] = uemail if uemail
       event
     end
 
@@ -524,6 +667,30 @@ module Mcpeye
       {}
     end
 
+    # Per-CALL end-user identity for ONE event, resolved on the caller's (request)
+    # thread. Uses `identify` (evaluated per call) when given, else the static
+    # `identity`. Returns [user_id, user_email] as normalized Strings or nils.
+    # Fail-open: a raising identify yields [nil, nil], never into the host call.
+    def resolve_call_identity
+      raw = @identify ? @identify.call : @identity
+      raw = {} unless raw.is_a?(Hash)
+      [norm_ident(raw[:userId] || raw["userId"]), norm_ident(raw[:userEmail] || raw["userEmail"])]
+    rescue StandardError => e
+      @on_error.call(e)
+      [nil, nil]
+    end
+
+    # Coerce an identity value to a trimmed String <=256 chars, or nil if blank.
+    # Coerces a non-String id (e.g. an Integer user id) like normalize_identity.
+    def norm_ident(value)
+      return nil if value.nil?
+
+      s = value.to_s.strip
+      return nil if s.empty?
+
+      s.length > 256 ? s[0, 256] : s
+    end
+
     # Prepend a failed batch to the front of the buffer (oldest-first, so it
     # retries first) and re-apply the cap. Caller must NOT hold @mutex.
     def requeue(batch)
@@ -731,6 +898,125 @@ module Mcpeye
       { "content" => [{ "type" => "text", "text" => RequestCapability::ACK }] }
     end
 
+    # --- official mcp gem (MCP::Server) support --------------------------
+
+    def official_mcp_server?(server)
+      defined?(MCP::Server) && server.is_a?(MCP::Server)
+    rescue StandardError
+      false
+    end
+
+    # Dispatch-level, per-server instrumentation of an official MCP::Server.
+    def instrument_official(server)
+      server.instance_variable_set(:@__mcpeye_tracker, self)
+      listed = wrap_official_list_tools(server)
+      called = wrap_official_call_tool(server)
+      warn_uninstrumentable(server) unless listed || called
+      server
+    rescue StandardError => e
+      @on_error.call(e)
+      server
+    end
+
+    # Capture: prepend the singleton-class hook so this server's call_tool is wrapped.
+    def wrap_official_call_tool(server)
+      sc = server.singleton_class
+      sc.prepend(OfficialServerCapture) unless sc.include?(OfficialServerCapture)
+      true
+    rescue StandardError => e
+      @on_error.call(e)
+      false
+    end
+
+    # Advertise: replace this server's "tools/list" handler entry so the listed
+    # schemas carry mcpeyeIntent and the reserved tool. @handlers is read at dispatch
+    # time, so swapping the entry is seen; mutating the RESPONSE never touches the
+    # global tool classes.
+    def wrap_official_list_tools(server)
+      handlers = server.instance_variable_get(:@handlers)
+      return false unless handlers.is_a?(Hash)
+
+      orig = handlers["tools/list"]
+      return false if orig.nil?
+      return true if orig.respond_to?(:mcpeye_wrapped?) && orig.mcpeye_wrapped?
+
+      add_reserved = @capture_missing_capabilities
+      wrapped = lambda do |request|
+        result = orig.call(request)
+        begin
+          augment_official_list_result(result, add_reserved)
+        rescue StandardError => e
+          @on_error.call(e)
+        end
+        result
+      end
+      wrapped.define_singleton_method(:mcpeye_wrapped?) { true }
+      handlers["tools/list"] = wrapped
+      true
+    rescue StandardError => e
+      @on_error.call(e)
+      false
+    end
+
+    def augment_official_list_result(result, add_reserved)
+      return unless result.is_a?(Hash)
+
+      tools = result[:tools] || result["tools"]
+      return unless tools.is_a?(Array)
+
+      tools.each do |tool|
+        next unless tool.is_a?(Hash)
+
+        key = if tool.key?(:inputSchema) then :inputSchema
+              elsif tool.key?("inputSchema") then "inputSchema"
+              end
+        next if key.nil?
+
+        schema = tool[key]
+        tool[key] = inject_intent_into_schema(schema) if schema.is_a?(Hash)
+      end
+
+      if add_reserved && tools.none? { |t| t.is_a?(Hash) && (t[:name] || t["name"]) == RequestCapability::TOOL_NAME }
+        tools << RequestCapability.descriptor
+      end
+    end
+
+    # Key-style-aware intent injection: official `to_h` schemas use symbol keys, so
+    # write back under the SAME key style (never produce both :properties and
+    # "properties", which would serialize to a duplicate JSON key). Collision-safe.
+    def inject_intent_into_schema(schema)
+      return schema unless Intent.object_shaped?(schema)
+
+      s = schema.dup
+      prop_key = s.key?(:properties) ? :properties : "properties"
+      props = (s[prop_key] || {}).dup
+      unless props.key?(Intent::INTENT_PARAM_NAME) || props.key?(Intent::INTENT_PARAM_NAME.to_sym)
+        props[Intent::INTENT_PARAM_NAME] = Intent.param_json_schema
+      end
+      s[prop_key] = props
+      type_key = s.key?(:type) ? :type : "type"
+      s[type_key] ||= "object"
+      s
+    rescue StandardError
+      schema
+    end
+
+    # Loud + fail-open: route a single, clear diagnostic through on_error (whose
+    # DEFAULT warns to stderr, so this is loud out of the box) when no supported
+    # shape could be instrumented. Capture never raises into the host — but it
+    # never silently no-ops either. Deduped via report_once.
+    def warn_uninstrumentable(server)
+      cls = (server.class.name rescue nil) || "the given server"
+      report_once(
+        :no_introspect,
+        RuntimeError.new(
+          "could not introspect #{cls} — no tool calls will be captured. " \
+          "Pass a supported MCP server (the official mcp gem's MCP::Server, or a " \
+          "tools-hash/fast-mcp server), or capture manually with #wrap / #record. See the README."
+        )
+      )
+    end
+
     def discover_tools(server)
       %i[tools registered_tools].each do |m|
         return server.public_send(m) if server.respond_to?(m)
@@ -813,7 +1099,7 @@ module Mcpeye
     def normalize_identity(identity)
       h = identity.is_a?(Hash) ? identity : {}
       out = {}
-      %w[userId client serverVersion].each do |k|
+      %w[userId userEmail client serverVersion].each do |k|
         v = h[k.to_sym]
         v = h[k] if v.nil?
         next if v.nil?

data/lib/mcpeye/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Mcpeye
-  VERSION = "0.1.2"
+  VERSION = "0.1.4"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mcpeye
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.4
 platform: ruby
 authors:
 - mcpeye
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-21 00:00:00.000000000 Z
+date: 2026-06-23 00:00:00.000000000 Z
 dependencies: []
 description: mcpeye captures what your agents try to do through your MCP tools — including
   the asks your tools could NOT fulfill — and ships them to a self-hosted mcpeye instance