mcpeye 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 01f13d2a4a0f1671c2fe3cec6feef771c84da1e88f101915972330c5c28692ce
+  data.tar.gz: 811c321338035cc6c1d89ae1a4c51a5389d2a5e10c60d006c8404dbd045c98f1
+SHA512:
+  metadata.gz: 258a88c0365ba40bd06487be165223e88d002432ca7820a2b79c986bbc81799758936d1d593aefcc908e46b4038374c2058c1557ba3cef89200e99fdbd1dd9e0
+  data.tar.gz: 04fa49d61cdb2552b7c6a1cb38db0f5108921897a84db135dc2637ef2b3befc2de728312961734ce6d21dcb32fe7550f271816b73e2ff2df15f0e19bd9c8a919

data/README.md

@@ -0,0 +1,265 @@
+# mcpeye (Ruby gem)
+
+> See why your agent is failing.
+
+Product analytics for **Ruby / Rails MCP servers**. `mcpeye` captures what
+agents try to do through your MCP tools — and, crucially, the asks your tools
+**could not** fulfill — then ships them to your self-hosted [mcpeye](https://github.com/mcpeye/mcpeye)
+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`,
+`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).
+
+## How it works
+
+1. **Inject** an optional `mcpeyeIntent` parameter into every tool's input schema.
+   The agent self-reports — in its own words — why it is calling the tool and any
+   blocker the user hit. Capture is near-zero cost: **no per-call LLM**.
+2. **Capture** each tool call (name, arguments, result, error, duration, the
+   self-reported intent).
+3. **Add** the reserved `mcpeye_request_capability` tool (active missing-capability
+   capture). When the agent wants a capability none of your tools cover, it calls
+   this tool to say so in the user's words; mcpeye answers it locally with a canned
+   acknowledgement (never forwarding it to your server) and records it as a normal
+   tool call with `tool_name = "mcpeye_request_capability"`. The report folds these
+   into "Top missing capabilities" as high-confidence, explicitly-requested
+   entries — catching the *silent miss*, where the right move is to call no tool at
+   all. Disable with `capture_missing_capabilities: false`.
+4. **Redact** secrets/PII client-side (regex-based) *before* anything leaves the
+   process, and size-bound every field. Self-hosting is the real privacy control;
+   redaction shrinks the blast radius of obvious secrets in free-text args.
+5. **Buffer + POST** the events as a single `IngestPayload` JSON to
+   `"#{ingest_url}/ingest"` with an `x-mcpeye-secret` header.
+
+The wire payload is byte-compatible across every mcpeye SDK (TS / Python / Ruby):
+
+```json
+{
+  "projectId": "my-project-id",
+  "identity": { "userId": "u_123", "client": "claude-desktop/0.7.1", "serverVersion": "1.4.0" },
+  "events": [
+    {
+      "callId": "f7c1...uuid",
+      "toolName": "search_products",
+      "arguments": { "q": "headphones" },
+      "result": { "count": 3 },
+      "isError": false,
+      "intent": "The user is searching for wireless headphones to add to their cart.",
+      "durationMs": 42,
+      "timestamp": 1718323200000
+    }
+  ]
+}
+```
+
+## Install
+
+Add to your `Gemfile`:
+
+```ruby
+gem "mcpeye"
+```
+
+Then `bundle install`. No runtime dependencies.
+
+## Configuration
+
+Reads the standard mcpeye env vars when arguments are omitted:
+
+| Env var                 | Purpose                                                  |
+| ----------------------- | -------------------------------------------------------- |
+| `MCPEYE_INGEST_URL`     | Base URL of your self-hosted mcpeye API (no `/ingest`).  |
+| `MCPEYE_INGEST_SECRET`  | Shared secret sent as the `x-mcpeye-secret` header.      |
+
+## Quick start
+
+```ruby
+require "mcpeye"
+
+tracker = Mcpeye.track(
+  server,                 # your MCP server object
+  "my-project-id",
+  ingest_url: ENV["MCPEYE_INGEST_URL"],       # e.g. "http://localhost:3001"
+  ingest_secret: ENV["MCPEYE_INGEST_SECRET"]
+)
+
+# That's it. A drain is auto-registered via at_exit, so you no longer have to
+# remember it. (An explicit `at_exit { tracker.flush }` still works — it's
+# 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`.
+
+## Options
+
+All optional except `project_id`:
+
+| Option           | Default                       | What it does                                                                 |
+| ---------------- | ----------------------------- | --------------------------------------------------------------------------- |
+| `ingest_url:`    | `ENV["MCPEYE_INGEST_URL"]`    | Base URL; `/ingest` is appended.                                            |
+| `ingest_secret:` | `ENV["MCPEYE_INGEST_SECRET"]` | Sent as `x-mcpeye-secret`. Missing → ingest 401 (warned once).             |
+| `redact:`        | `true`                        | Scrub secrets/PII from arguments/result/intent/error. `false` = verbatim.  |
+| `identity:`      | `{}`                          | Static `{ userId:, client:, serverVersion: }`.                             |
+| `identify:`      | `nil`                         | Callable evaluated **once per flush** for per-request identity. A raising one yields `{}`. |
+| `flush_interval:`| `nil` (no thread)             | Seconds between background flushes. Set it to drain low-traffic servers.    |
+| `flush_threshold:` | `20`                        | Eager-flush once this many events buffer.                                   |
+| `denylist_fields:` | `[]`                        | Extra field names whose values are always dropped (case-insensitive).      |
+| `max_buffer:`    | `10_000`                      | Hard cap; oldest events drop past it while the API is down (warned once).  |
+| `capture_missing_capabilities:` | `true`         | Add + locally answer the reserved `mcpeye_request_capability` tool. `false` keeps it out of your manifest. |
+| `on_error:`      | `warn "[mcpeye] ..."`         | Diagnostics sink for every swallowed error. Wrapped so it can never throw.  |
+
+> **Manifest cost.** With `capture_missing_capabilities: true`, your server's tool
+> list gains one extra tool — a few hundred tokens in any model context that lists
+> tools, and one more entry in any tool picker / doc generator. That is the price
+> of seeing silent misses; pass `false` to keep it out. Auto-add works for Hash /
+> Array tool registries; for other server shapes the constant + descriptor live in
+> `Mcpeye::RequestCapability` so you can register it yourself.
+
+When `flush_interval` is set, a single background flush thread ships batches off
+the tool-call thread, so capture never blocks. Without it the gem is
+**zero-thread**: events flush eagerly at `flush_threshold`, on a manual `#flush`,
+and via the auto `at_exit` drain — but that threshold flush runs **synchronously on
+the calling thread** (one `Net::HTTP` POST, bounded by the 5s/10s open/read
+timeouts), so the Nth tool call can block briefly. For a busy or latency-sensitive
+server, set `flush_interval:` so capture is fully non-blocking.
+
+Identity values (`userId`/`client`/`serverVersion`) are coerced to strings before
+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
+
+`config/initializers/mcpeye.rb`:
+
+```ruby
+require "mcpeye"
+
+MCPEYE = Mcpeye.track(
+  MyMcpServer.instance,                         # your server object
+  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 } },
+  # 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:
+  on_error: ->(e) { Rails.logger.warn("[mcpeye] #{e}") }
+)
+```
+
+### Puma / Unicorn (forking servers)
+
+A thread does **not** survive `fork`, so in a clustered server start the flush
+timer **after** each worker boots, and drain on shutdown:
+
+```ruby
+# config/puma.rb
+on_worker_boot do
+  # Re-start the background flush thread inside each forked worker.
+  MCPEYE.start_flush_thread
+end
+
+on_worker_shutdown do
+  MCPEYE.stop   # stops the timer + does a final flush
+end
+```
+
+Pass `flush_interval:` to `Mcpeye.track` (e.g. `flush_interval: 5`) so
+`start_flush_thread` has an interval to use. Even without the timer, the eager
+threshold flush + the auto `at_exit` drain still ship per worker; at worst a tiny
+tail is lost on `SIGKILL` (same as the other SDKs).
+
+## Manual capture (when auto-wrap can't attach)
+
+mcpeye duck-types the common Ruby MCP shapes — a server exposing `tools` /
+`registered_tools` (a method or `@tools` / `@registered_tools` ivar) whose entries
+are Hashes carrying an input schema (`"inputSchema"`, `:input_schema`, `"schema"`)
+and, for auto-wrapping, a `name` plus a callable (`"handler"` / `"call"`). When
+your server doesn't match (a custom Rack handler, a frozen tool registry, a future
+framework), `instrument` is a safe no-op and you capture calls yourself:
+
+```ruby
+class SearchContactsTool
+  def self.handler
+    MCPEYE.wrap("search_contacts") do |args|
+      Contact.search(args["q"]).as_json   # your real logic
+    end
+  end
+end
+```
+
+`#wrap` strips `mcpeyeIntent` out of the incoming arguments, records it as
+`intent`, runs your handler with the cleaned args, and returns the result
+unchanged. A handler that raises is recorded as `isError` and the **identical
+exception is re-raised**. Or record fully by hand:
+
+```ruby
+MCPEYE.record(
+  "place_order",
+  { "items" => [{ "sku" => "p_7720", "qty" => 1 }] },
+  result: { "id" => "ord_123" },
+  intent: "User is placing an order but couldn't find a way to apply a discount code.",
+  duration_ms: 88
+)
+MCPEYE.flush
+```
+
+## Result-level errors
+
+Besides a raised exception, mcpeye also captures a **tool-level** failure: when a
+handler returns a result Hash carrying a truthy `"isError"` (the MCP `CallTool`
+convention, e.g. `{ "isError" => true, "content" => [{ "type" => "text", "text" => "..." }] }`),
+the event is recorded with `isError: true`, an `errorMessage` derived from the
+content text, and the `result` omitted. The handler's return value is passed back
+to the caller unchanged.
+
+## Redaction
+
+Client-side, regex-based, deliberately conservative — it over-redacts rather than
+leak. Out of the box it scrubs emails, API keys (`sk-`, `sk-ant-`, GitHub
+`gh*_`, AWS `AKIA…`), Bearer tokens, JWTs, card-like and phone-like number runs,
+and drops the values of denylisted fields (`password`, `secret`, `token`,
+`apiKey`, `authorization`, …). Deeply-nested and self-referential structures are
+guarded (`[REDACTED_TOO_DEEP]` / `[REDACTED_CYCLE]`), and any single field over
+~32 KB is replaced with a small marker so a multi-MB payload can never blow the
+ingest body limit. Extend the denylist with `denylist_fields:`; disable redaction
+with `redact: false`.
+
+Redaction is **not** a substitute for self-hosting — it reduces the blast radius
+of obvious secrets that slip into free-text arguments and intent strings.
+
+## API
+
+- `Mcpeye.track(server, project_id, ingest_url:, ingest_secret:, redact:, identity:, identify:, flush_interval:, on_error:, **opts) -> Tracker`
+- `Mcpeye::Tracker#instrument(server)` — inject param + wrap discoverable handlers
+- `Mcpeye::Tracker#inject_intent_param(server)`
+- `Mcpeye::Tracker#wrap(tool_name) { |args| ... } -> Proc`
+- `Mcpeye::Tracker#record(tool_name, args, result:, is_error:, error_message:, intent:, duration_ms:) -> Hash`
+- `Mcpeye::Tracker#flush -> Net::HTTPResponse | nil` (never raises)
+- `Mcpeye::Tracker#start_flush_thread` — start the background flush timer (call in `on_worker_boot`)
+- `Mcpeye::Tracker#stop -> nil` — stop the timer + final flush
+- `Mcpeye::Tracker#pending -> Integer`
+- `Mcpeye::Redaction.redact_string(s)`, `Mcpeye::Redaction.redact_value(v, denylist_fields:)`
+- `Mcpeye::INTENT_PARAM_NAME` (`"mcpeyeIntent"`), `Mcpeye::INTENT_PARAM_DESCRIPTION`
+
+## Development
+
+```bash
+cd packages/sdk-ruby
+bundle install
+bundle exec rake spec        # the seven-spec RSpec suite
+# or: pnpm --filter @mcpeye/sdk-ruby test
+```
+
+## License
+
+MIT

data/lib/mcpeye/intent.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Mcpeye
+  # The injected-intent contract.
+  #
+  # mcpeye's cheap capture trick: the SDK injects an optional `mcpeyeIntent`
+  # parameter into every tool's input schema. The agent self-reports, in its own
+  # words, why it is calling the tool and any blocker the user hit — so we capture
+  # intent at near-zero cost, with NO per-call LLM. The LLM runs later, in the
+  # worker, only to cluster sessions into reports.
+  #
+  # The description below is what the agent reads. It is deliberately specific
+  # about surfacing failures/blockers AND naming any capability the user wanted
+  # that no tool provides — those attempted-but-failed asks, phrased as the user's
+  # own unmet need, are the hero signal (the Intent Gap Report).
+  #
+  # Keep INTENT_PARAM_DESCRIPTION byte-for-byte in sync with @mcpeye/core
+  # (packages/core/src/intent.ts) and the other SDKs (Python:
+  # packages/sdk-python/src/mcpeye/intent.py). Every server speaks the same
+  # contract; spec/intent_spec.rb asserts this string against the canonical text.
+  module Intent
+    INTENT_PARAM_NAME = "mcpeyeIntent"
+
+    # Byte-for-byte identical to packages/core/src/intent.ts INTENT_PARAM_DESCRIPTION.
+    # If you change one, change all SDKs (TS, Python, Ruby) together.
+    INTENT_PARAM_DESCRIPTION =
+      "Explain why you are calling this tool and how it fits into the user's overall workflow. " \
+      "This parameter is used only for product analytics and user-intent tracking. " \
+      "Write 25-35 words, in the third person. " \
+      "Exclude sensitive information such as credentials, passwords, or personal data. " \
+      "Describe any blocker or failure the user hit. " \
+      "Most important: if the user wanted to do something these tools cannot do, state the missing " \
+      "capability they needed, in their own words (for example: 'wanted to export the report as CSV, " \
+      "but no export tool exists')."
+
+    # JSON-Schema fragment merged into each tool's inputSchema by the SDKs.
+    # Returns a fresh Hash each call so a caller mutating it can never corrupt the
+    # shared contract.
+    def self.param_json_schema
+      {
+        "type" => "string",
+        "description" => INTENT_PARAM_DESCRIPTION
+      }
+    end
+
+    # Whether a JSON-Schema fragment is object-shaped, i.e. somewhere we can add an
+    # `mcpeyeIntent` string property. The single source of truth for object
+    # detection, shared by `inject_intent_param` and the Tracker's in-place
+    # auto-injection so the two paths can never drift (matches Python's guard):
+    #
+    # - `type == "object"`, OR a `properties` key (string or symbol), OR a
+    #   literally-empty `{}` (a parameterless tool — synthesize an object).
+    # - An explicit non-object type (e.g. `{ "type" => "array" }`) is NOT object
+    #   shaped; a typeless-but-non-empty schema (e.g. `{ "description" => "x" }`)
+    #   is NOT either — there is no sensible place to add the param, and capture
+    #   still works without it.
+    def self.object_shaped?(schema)
+      return false unless schema.is_a?(Hash)
+
+      explicit_type = schema["type"] || schema[:type]
+      explicit_type == "object" ||
+        schema.key?("properties") || schema.key?(:properties) ||
+        (explicit_type.nil? && schema.empty?)
+    end
+
+    # Return a copy of a JSON-Schema object with the `mcpeyeIntent` property merged
+    # in. Non-destructive (the original schema and its properties are copied),
+    # mirroring the TS `augmentListToolsResult` / Python `inject_intent_param`:
+    #
+    # - Object-shaped schema (see `object_shaped?`): merge in `mcpeyeIntent`,
+    #   defaulting `type` to "object".
+    # - Anything else (explicit non-object type, or typeless-non-empty): returned
+    #   unchanged — capture still works.
+    # - When `mcpeyeIntent` already exists (a tool owns the name), the property is
+    #   left exactly as the tool declared it.
+    def self.inject_intent_param(input_schema)
+      return input_schema unless object_shaped?(input_schema)
+
+      schema = input_schema.dup
+      props = (schema["properties"] || schema[:properties] || {}).dup
+      # Do not clobber a real tool param that happens to share the name.
+      unless props.key?(INTENT_PARAM_NAME) || props.key?(INTENT_PARAM_NAME.to_sym)
+        props[INTENT_PARAM_NAME] = param_json_schema
+      end
+      schema["properties"] = props
+      schema["type"] ||= "object"
+      schema
+    end
+  end
+
+  # Re-export at the top level so callers can use Mcpeye::INTENT_PARAM_NAME.
+  INTENT_PARAM_NAME = Intent::INTENT_PARAM_NAME
+  INTENT_PARAM_DESCRIPTION = Intent::INTENT_PARAM_DESCRIPTION
+end

data/lib/mcpeye/redaction.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Mcpeye
+  # v1 redaction: regex-based secret/PII scrubbing applied client-side in the SDK
+  # BEFORE anything is sent to the ingest API, and again defensively in the worker
+  # before any LLM call. Self-hosting is the real privacy mitigation; this reduces
+  # the blast radius of obvious secrets/PII in free-text arguments and intent.
+  #
+  # Deliberately conservative: it over-redacts rather than leak. Smarter,
+  # structure-aware redaction is a documented future improvement.
+  #
+  # Ported from @mcpeye/core (redaction.ts) — keep the patterns, replacements, the
+  # depth cap, and the cycle guard in sync across SDKs (TS, Python, Ruby).
+  module Redaction
+    # Each entry: [regex, replacement]. Order matches the TS port so that the
+    # most-specific keys (sk-ant-) win before the generic ones where relevant.
+    PATTERNS = [
+      # email
+      [/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/, "[REDACTED_EMAIL]"],
+      # Anthropic key (more specific than the generic sk- key — run first)
+      [/\bsk-ant-[A-Za-z0-9_-]{16,}\b/, "[REDACTED_KEY]"],
+      # OpenAI-style key
+      [/\bsk-[A-Za-z0-9_-]{16,}\b/, "[REDACTED_KEY]"],
+      # GitHub tokens (ghp_, gho_, ghu_, ghs_, ghr_)
+      [/\bgh[pousr]_[A-Za-z0-9]{20,}\b/, "[REDACTED_KEY]"],
+      # AWS access key id
+      [/\bAKIA[0-9A-Z]{16}\b/, "[REDACTED_KEY]"],
+      # Bearer tokens
+      [/\bBearer\s+[A-Za-z0-9._-]{12,}\b/i, "Bearer [REDACTED_KEY]"],
+      # JWT
+      [/\beyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b/, "[REDACTED_JWT]"],
+      # Credit-card-ish (13-16 digit groups, optional spaces/dashes)
+      [/\b(?:\d[ -]?){13,16}\b/, "[REDACTED_CARD]"],
+      # Phone numbers (loose international)
+      [/\b\+?\d{1,3}[\s.-]?\(?\d{2,4}\)?[\s.-]?\d{3,4}[\s.-]?\d{3,4}\b/, "[REDACTED_PHONE]"]
+    ].freeze
+
+    # Exact field names whose values are always dropped, regardless of content.
+    DEFAULT_DENYLIST = %w[
+      password passwd secret token apiKey api_key authorization
+    ].freeze
+
+    REDACTED_FIELD = "[REDACTED_FIELD]"
+    REDACTED_TOO_DEEP = "[REDACTED_TOO_DEEP]"
+    REDACTED_CYCLE = "[REDACTED_CYCLE]"
+
+    # Max nesting walk descends. Past this we substitute a marker instead of
+    # recursing further. Without a cap, a deeply-nested value (which the ingest
+    # schema does NOT bound) overflows the call stack — and on the server that
+    # throw aborts the whole ingest transaction, 500-ing the entire batch and
+    # discarding every other valid event. 64 is far deeper than any real tool
+    # payload. Matches @mcpeye/core's MAX_REDACT_DEPTH.
+    MAX_REDACT_DEPTH = 64
+
+    # Scrub a single string through every pattern.
+    def self.redact_string(input)
+      return input unless input.is_a?(String)
+
+      out = input.dup
+      PATTERNS.each { |(re, replacement)| out = out.gsub(re, replacement) }
+      out
+    end
+
+    # Recursively redact a JSON-ish value (Hash / Array / String / primitive).
+    #
+    # opts[:denylist_fields] — extra exact field names to drop (case-insensitive),
+    # merged with DEFAULT_DENYLIST.
+    def self.redact_value(value, opts = {})
+      extra = opts[:denylist_fields] || opts["denylist_fields"] || []
+      denylist = (DEFAULT_DENYLIST + extra).map { |f| f.to_s.downcase }.to_set
+
+      # Identity set of containers on the current recursion path, so a
+      # self-referential structure is short-circuited instead of looping forever
+      # (added on enter, removed on exit — so sibling/diamond references are still
+      # walked, only true cycles cut). Mirrors the TS `onPath` WeakSet / Python id().
+      on_path = {}.compare_by_identity
+      walk(value, denylist, 0, on_path)
+    end
+
+    def self.walk(value, denylist, depth, on_path)
+      case value
+      when String
+        redact_string(value)
+      when Array, Hash
+        return REDACTED_TOO_DEEP if depth >= MAX_REDACT_DEPTH
+        return REDACTED_CYCLE if on_path[value]
+
+        on_path[value] = true
+        begin
+          if value.is_a?(Array)
+            value.map { |v| walk(v, denylist, depth + 1, on_path) }
+          else
+            value.each_with_object({}) do |(k, v), out|
+              out[k] = if denylist.include?(k.to_s.downcase)
+                         REDACTED_FIELD
+                       else
+                         walk(v, denylist, depth + 1, on_path)
+                       end
+            end
+          end
+        ensure
+          on_path.delete(value)
+        end
+      else
+        value
+      end
+    end
+    private_class_method :walk
+  end
+end

data/lib/mcpeye/request_capability.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Mcpeye
+  # The active missing-capability contract — the reserved `mcpeye_request_capability`
+  # tool the SDK adds to the server's tool registry.
+  #
+  # The passive `mcpeyeIntent` param (see intent.rb) only sees a missing capability
+  # when the agent still calls SOME tool and self-reports the gap in the intent text.
+  # Its blind spot is the silent miss: when no tool fits, the correct behavior is to
+  # call no tool at all — so there is no intent string and no tool_call row, yet that
+  # is the highest-value roadmap signal (a user need with zero matching tool).
+  #
+  # This closes the gap actively: the SDK adds a reserved tool the agent can call to
+  # voice a capability the available tools do not cover. The SDK answers it locally
+  # (the host never sees it), returns a friendly acknowledgement, and records it as a
+  # normal tool_call with tool_name = "mcpeye_request_capability". The report folds
+  # these explicit calls into topMissingCapabilities as high-confidence entries.
+  #
+  # Keep these strings byte-for-byte in sync with @mcpeye/core
+  # (packages/core/src/request-capability.ts) and the Python SDK
+  # (packages/sdk-python/src/mcpeye/request_capability.py).
+  # spec/request_capability_spec.rb asserts them against the canonical text.
+  module RequestCapability
+    TOOL_NAME = "mcpeye_request_capability"
+
+    # Byte-for-byte identical to packages/core/src/request-capability.ts. The
+    # lower-the-bar framing ("even if an existing tool could be a fallback") is what
+    # pulls calls; a timid framing leaves the signal near zero. Change all SDKs together.
+    TOOL_DESCRIPTION =
+      "Use this tool whenever the user wants something the available tools do not cover, " \
+      "or whenever the task might benefit from a more specialized capability even if an " \
+      "existing tool could be used as a fallback. Describe the capability the user actually " \
+      "needs, in their own words (for example: 'export the report as a PDF'). This signal is " \
+      "used only to improve which tools are offered; calling it has no side effects and does " \
+      "not perform the action."
+
+    CAPABILITY_DESCRIPTION =
+      "The capability the user needs that the available tools do not provide, in the user's " \
+      "own words (for example: 'export the report as a PDF')."
+
+    CONTEXT_DESCRIPTION =
+      "Optional: what the user was trying to accomplish when they reached for this capability."
+
+    ACK =
+      "Thanks. This capability request has been recorded for the server's maintainers. " \
+      "Continue helping the user with the available tools as best you can."
+
+    # The reserved tool's input schema: `capability` required, `context` optional.
+    # Returns a fresh Hash each call so a caller mutating it can never corrupt the
+    # shared contract. Carries NO mcpeyeIntent property — the ask lives in `capability`.
+    def self.input_schema
+      {
+        "type" => "object",
+        "properties" => {
+          "capability" => { "type" => "string", "description" => CAPABILITY_DESCRIPTION },
+          "context" => { "type" => "string", "description" => CONTEXT_DESCRIPTION }
+        },
+        "required" => ["capability"]
+      }
+    end
+
+    # The full { name, description, inputSchema } descriptor, as a fresh Hash.
+    def self.descriptor
+      {
+        "name" => TOOL_NAME,
+        "description" => TOOL_DESCRIPTION,
+        "inputSchema" => input_schema
+      }
+    end
+  end
+
+  # Re-export at the top level for parity with INTENT_PARAM_NAME.
+  REQUEST_CAPABILITY_TOOL_NAME = RequestCapability::TOOL_NAME
+end