mcpeye 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1e03d773ff0e269c253e95b6c9ab2bc1397a128ff04dd10fe1946ca2abf225d
-  data.tar.gz: '08536ff4f7bf9b3dd60191719a9b7e1197e1d4340e96816a2aa1a80283805ced'
+  metadata.gz: 5b65ed38eb2861006ebcd79b5592922e1281d71fce912dec5543b01cba961244
+  data.tar.gz: 3184681a41e2669cf3b9c240acad0bd4418d811fdbc97bb988ac82b5533ec42b
 SHA512:
-  metadata.gz: 44cecb923f26ef7dd4356731807879b19369c7e38cadc95ac21625645f20d8745bfd625e804402ba0a8771ba8eeba223aabd497e15fe193b36ef2ba6938ce55c
-  data.tar.gz: 95b4cbd7133bbf670c015aa04a6cc38eb000c34a96f527d19a48dffcd4e447992034f2179cda63bbe7194d96d799decfca1c5dad1826485a3b3c3fd3d707777e
+  metadata.gz: fe8f68cdae22753dd5ff53e284e0c493e313e4f9dca104e50f3a9be6d5ae6147d19b8215f0f288989ae8e30c2e3c4134d02a85ee4cbd12cebc2f07241e9dd2e8
+  data.tar.gz: dd3ca7ff1636b5a7b1cd424c2a854e095cddb331c199c4c7775737a0f2e7bd88a1cf861e5b59b112cf04a114cfb424c565173145356829dd6c735447b0008d68

data/README.md

@@ -8,8 +8,7 @@ agents try to do through your MCP tools — and, crucially, the asks your tools
 instance. There the worker clusters sessions into the **Intent Gap Report**: the
 top user asks your tools attempted but failed to deliver.
 
-This gem is the dogfooding SDK for the mcpeye team's own Rails-based MCP server,
-and for any Ruby shop running one. It is **pure stdlib at runtime** (`net/http`,
+This gem instruments any Ruby / Rails MCP server. It is **pure stdlib at runtime** (`net/http`,
 `json`, `securerandom`) and **never raises into, or alters, the host server**.
 Capture is O(1); set `flush_interval:` to ship telemetry off the tool-call thread
 (see [Options](#options) for the zero-thread default's one caveat).
@@ -92,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
 
@@ -134,7 +153,7 @@ Identity values (`userId`/`client`/`serverVersion`) are coerced to strings befor
 they're sent (the ingest contract requires strings), so an integer id is fine —
 but pass an **opaque, non-PII** value.
 
-## Dogfooding in a Rails MCP server
+## Use in a Rails MCP server
 
 `config/initializers/mcpeye.rb`:
 

data/lib/mcpeye/tracker.rb

@@ -44,6 +44,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;
@@ -143,26 +252,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
@@ -731,6 +856,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)

data/lib/mcpeye/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: mcpeye
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 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