@posthog/mcp 0.14.1 → 0.16.0

package/src/extensions/mcp-payloads.ts

@@ -16,6 +16,55 @@ const POSTHOG_TOKEN_PATTERN = /\bph[a-z]_[A-Za-z0-9_-]{20,}\b/g
 const SENSITIVE_KEY_PATTERN =
   /^(authorization|cookie|set-cookie|x-api-key|api[-_]?key|api[-_]?token|access[-_]?token|refresh[-_]?token|token|password|secret|client[-_]?secret|private[-_]?key)$/i
 
+// Deliberately no leading `\b`: `_` is a word character but not scheme-legal, so
+// `resource_https://user:pw@host` has no boundary to anchor to and would keep its
+// credentials. Leftmost matching makes `foo.https://x` match from `f` with scheme
+// `foo.https`, which redacts the same URL and is therefore harmless.
+//
+// `'` is a valid URI sub-delimiter, so the terminal class must not stop at one:
+// excluding it truncated `https://example.com/o'reilly?token=x` at the path and
+// shipped the token in the clear. Only the characters that are never valid
+// unencoded in a URI are excluded.
+//
+// The authority is optional too. An MCP resource URI frequently has none
+// (`resource:guide?token=x`, `file:/guide.md`), and requiring `//` let those
+// through untouched; `[^\s<>"]+` absorbs a `//host` when there is one. The cost
+// is over-matching ordinary prose (`Error:foo`, `at12:30`, `C:\path`), which is
+// harmless: a match with nothing to redact is returned byte-for-byte, so the
+// text around it is never rewritten.
+const URL_PATTERN = /[a-z][a-z0-9+.-]{0,63}:[^\s<>"]+/gi
+/** The same pattern without `g`, for asking whether a value holds a URL at all. */
+const URL_PATTERN_ONCE = new RegExp(URL_PATTERN.source, 'i')
+/** Finds the first scheme that brings a real authority, i.e. what the pattern required before it went authority-less. */
+const URL_AUTHORITY_SEARCH = /[a-z][a-z0-9+.-]{0,63}:\/\//i
+/** The same, anchored: does this match *open* with an authority? */
+const URL_AUTHORITY_PATTERN = new RegExp(`^${URL_AUTHORITY_SEARCH.source}`, 'i')
+/** Every authority start in a value, in order. */
+const URL_AUTHORITY_SEARCH_ALL = new RegExp(URL_AUTHORITY_SEARCH.source, 'gi')
+/** The field separators. `?` and `#` are structural only as delimiters — see {@link isStructural}. */
+const URL_FIELD_CHARACTERS = '=&'
+/** The legacy field separator. Never split on, only checked; see {@link sanitizeUrlFieldValue}. */
+const LEGACY_FIELD_SEPARATOR = ';'
+// The terminal class above also absorbs the prose punctuation that follows a URL
+// in a sentence, `'` included now that a URL can contain one. See
+// `splitTrailingPunctuation`.
+const URL_TRAILING_PUNCTUATION = ".,;:!?)]}'"
+const MAX_URL_LENGTH = 8192
+const MAX_URL_QUERY_FIELDS = 128
+// A query key is sensitive when any `-`/`_`/`.`/`/`/`;`-delimited segment names
+// a credential, so compound names (`private_token`, `oauth_signature`,
+// `subscription-key`, `X-Amz-Security-Token`, `Key-Pair-Id`) are covered without
+// enumerating every vendor's spelling. `/` is a separator because a fragment's
+// field list can be written `#/token=…`, and `;` because a legacy `;`-separated
+// pair parses into a single key (`download;token`) — either would otherwise hide
+// the name. Over-redacting a benign `sort_key` — or `sort/key`, or `sort;key` —
+// is the accepted trade for an analytics payload.
+const SENSITIVE_QUERY_KEY_SEGMENT_PATTERN =
+  /(^|[-_./;])(auth|token|secret|password|passwd|pwd|credential|signature|sig|key|hmac|sas|bearer|jwt|session|sessionid)([-_./;]|$)/i
+// `code` — the OAuth authorization code — is matched only as a whole key: as a
+// segment it would eat `country_code`, `zip_code`, and `lang_code`.
+const SENSITIVE_QUERY_KEY_EXACT_PATTERN = /^(code|AWSAccessKeyId|GoogleAccessId|Policy)$/i
+
 // PII redaction for the agent-narrated intent string only. `$mcp_intent` is free
 // text the calling LLM writes into the injected `context` argument, so it can
 // carry personal data the model read aloud despite being told not to. We redact
@@ -75,6 +124,12 @@ function shouldRedactKey(key: string): boolean {
   return SENSITIVE_KEY_PATTERN.test(key)
 }
 
+function shouldRedactQueryKey(key: string): boolean {
+  return (
+    shouldRedactKey(key) || SENSITIVE_QUERY_KEY_SEGMENT_PATTERN.test(key) || SENSITIVE_QUERY_KEY_EXACT_PATTERN.test(key)
+  )
+}
+
 function isBase64DataUrl(value: string): boolean {
   const prefix = BASE64_DATA_URL_PREFIX_PATTERN.exec(value)
   if (!prefix) {
@@ -91,16 +146,384 @@ function isBase64DataUrl(value: string): boolean {
   return BASE64_DATA_URL_PAYLOAD_PATTERN.test(payload.replace(/[\r\n]/g, ''))
 }
 
-function sanitizeString(value: string): string {
-  if (
+function exceedsUrlFieldLimit(fields: string): boolean {
+  return fields.split('&', MAX_URL_QUERY_FIELDS + 1).length > MAX_URL_QUERY_FIELDS
+}
+
+/** How much of the sanitizer one call is allowed to apply. */
+interface UrlSanitizeMode {
+  /** Sanitize a URL found inside a retained field value. Off past depth 1. */
+  allowNestedUrls: boolean
+  /** Split prose punctuation off the end. Off when the match is a whole string. */
+  stripPunctuation: boolean
+}
+
+/** Whether any `;`-separated piece of `value` names a credential. */
+function hasLegacySensitiveField(value: string): boolean {
+  return value.split(LEGACY_FIELD_SEPARATOR).some((piece) => shouldRedactQueryKey(piece.split('=', 1)[0]))
+}
+
+/** The sanitized value of one query or fragment field. */
+function sanitizeUrlFieldValue(key: string, value: string, allowNestedUrls: boolean): string {
+  if (shouldRedactQueryKey(key)) {
+    return REDACTED_VALUE
+  }
+  // `;` once separated fields the way `&` does, so a value carrying one may hold
+  // a credential field inside it. Splitting on it is not an option — that cuts a
+  // credential's own value in two and publishes the tail as a bare key
+  // (`?password=prefix;rest`) — so instead the whole value goes when any piece
+  // of it names a credential.
+  if (value.includes(LEGACY_FIELD_SEPARATOR) && hasLegacySensitiveField(value)) {
+    return REDACTED_VALUE
+  }
+  if (!URL_PATTERN_ONCE.test(value)) {
+    return value
+  }
+  // One level of nesting is the whole budget. Past it a URL-bearing value is
+  // dropped rather than trusted: nothing deeper would sanitize it, so a gateway
+  // address wrapping a gateway address would otherwise ship its credentials.
+  return allowNestedUrls
+    ? sanitizeUrlsInString(value, { allowNestedUrls: false, stripPunctuation: true })
+    : REDACTED_VALUE
+}
+
+/**
+ * Redacts the values of credential-named fields in one `&`-separated field list
+ * — a query string or a fragment. `serialized` is only meaningful when `changed`
+ * is true, so an untouched part keeps its original encoding instead of being
+ * re-serialized. `lastFieldSensitive` says whether whatever follows the list
+ * could be more of a credential, which is what decides both the fragment tail
+ * and restored prose punctuation; see {@link sanitizeUrl}.
+ */
+function sanitizeUrlFields(
+  fields: string,
+  allowNestedUrls: boolean
+): { changed: boolean; lastFieldSensitive: boolean; serialized: string } {
+  const sanitized = new URLSearchParams()
+  let changed = false
+  let lastFieldSensitive = false
+  for (const [key, value] of new URLSearchParams(fields)) {
+    const sanitizedValue = sanitizeUrlFieldValue(key, value, allowNestedUrls)
+    // `changed` is compared, not inferred from the key: the PostHog-token pass
+    // runs first, so a value can already read `[redacted]`, and calling that a
+    // change would re-serialize the field only to percent-encode it.
+    changed ||= sanitizedValue !== value
+    // Sensitivity is the separate question — whether what follows this field
+    // could be more of a credential — and an already-redacted value is still a
+    // credential's field.
+    lastFieldSensitive = shouldRedactQueryKey(key) || sanitizedValue !== value
+    sanitized.append(key, sanitizedValue)
+  }
+  return { changed, lastFieldSensitive, serialized: sanitized.toString() }
+}
+
+/**
+ * Splits the prose punctuation that follows a URL in a sentence off the end of a
+ * match, so it is not parsed as part of the address and can be re-appended
+ * verbatim to whatever the sanitizer returns.
+ *
+ * Walked back character by character rather than matched with a `$`-anchored
+ * pattern: a captured URI is attacker-influenceable, and on a long punctuation
+ * run that does not end the match a backtracking pattern is quadratic.
+ */
+function splitTrailingPunctuation(value: string): { address: string; suffix: string } {
+  let end = value.length
+  while (end > 0 && URL_TRAILING_PUNCTUATION.includes(value[end - 1])) {
+    end--
+  }
+  return { address: value.slice(0, end), suffix: value.slice(end) }
+}
+
+/**
+ * A fragment's tail, given how its head came out.
+ *
+ * A `?` inside a credential looks exactly like the one between a route and its
+ * fields. So when the head's last field is a credential's, everything after that
+ * `?` may be the rest of its value — `#password=prefix?rest` — and the
+ * tail goes whole rather than being read on its own terms. An empty tail has
+ * nothing to hide and stays empty. Either way it counts as a rewritten trailing
+ * field, so prose punctuation after the URL goes with it for the same reason.
+ */
+function sanitizeFragmentTail(
+  tail: string,
+  headLastFieldSensitive: boolean,
+  allowNestedUrls: boolean
+): { value: string; lastFieldSensitive: boolean } {
+  if (!headLastFieldSensitive) {
+    return sanitizeFragmentPart(tail, allowNestedUrls)
+  }
+  return { value: tail === '' ? '' : REDACTED_VALUE, lastFieldSensitive: true }
+}
+
+/**
+ * Splits a fragment at its first `?`. `tail` is null when there is none.
+ *
+ * Nothing is assumed about either part. Shape alone cannot tell a router's route
+ * from a field list — `#/docs/id=1?token=…` puts an `=` in the route, and
+ * `#/token=…&next=https://x/?page=1` puts a `/` and a `?` in a field list — so
+ * each part is read as fields when it holds an `=` and as text otherwise.
+ */
+function splitFragmentParts(hash: string): { head: string; tail: string | null } {
+  const fragment = hash.slice(1)
+  const separator = fragment.indexOf('?')
+  if (separator < 0) {
+    return { head: fragment, tail: null }
+  }
+  return { head: fragment.slice(0, separator), tail: fragment.slice(separator + 1) }
+}
+
+/** One fragment part, and whether its last field was rewritten. */
+function sanitizeFragmentPart(part: string, allowNestedUrls: boolean): { value: string; lastFieldSensitive: boolean } {
+  if (!part.includes('=')) {
+    return { value: sanitizeFragmentText(part, allowNestedUrls), lastFieldSensitive: false }
+  }
+  const fields = sanitizeUrlFields(part, allowNestedUrls)
+  // Verbatim unless something was actually rewritten: only the part that changed
+  // should change encoding.
+  return { value: fields.changed ? fields.serialized : part, lastFieldSensitive: fields.lastFieldSensitive }
+}
+
+/**
+ * Sanitizes the part of a fragment that is text rather than fields — a plain
+ * `#intro`, or the route in front of a field list. It is text, and text can
+ * carry an address, so it gets the URL pass.
+ *
+ * Depth is capped the way a field value's is: at the nested level a URL-bearing
+ * text is dropped rather than descended into. That is also what stops
+ * `resource:x#resource:x#…` from recursing once per `#`.
+ */
+function sanitizeFragmentText(text: string, allowNestedUrls: boolean): string {
+  if (!allowNestedUrls) {
+    return URL_PATTERN_ONCE.test(text) ? REDACTED_VALUE : text
+  }
+  return sanitizeUrlsInString(text, { allowNestedUrls: false, stripPunctuation: true })
+}
+
+/**
+ * Every offset inside `value` where an adjacent address starts; see
+ * {@link sanitizeUrl}.
+ *
+ * An authority is in *value position* — left alone, because the field pass
+ * already gives it the nested pass — when a field name's `=` is the nearest
+ * structural character behind it. Structural means a field separator (`=`, `&`,
+ * `;`) or one of the URL's three delimiters; see {@link isDelimiter}. Before any
+ * delimiter no `=` has been seen, so `…/redirect=https://user:pw@host` is two
+ * addresses rather than one field.
+ *
+ * Decided in one forward walk, not a backward scan per authority. The scan was
+ * quadratic on a value that opens its fields once and then runs thousands of
+ * addresses together, because every one of them scanned back to the same `?`.
+ */
+function findEmbeddedAuthorityIndexes(value: string): number[] {
+  const starts = [...value.matchAll(URL_AUTHORITY_SEARCH_ALL)].map((match) => match.index)
+  const indexes: number[] = []
+  const delimiters = { query: false, fragment: false, fragmentQuery: false }
+  let pending = 0
+  let inFields = false
+  let lastStructural = ''
+  for (let cursor = 0; cursor < value.length && pending < starts.length; cursor++) {
+    if (starts[pending] === cursor) {
+      if (cursor > 0 && lastStructural !== '=') {
+        indexes.push(cursor)
+      }
+      pending++
+    }
+    const character = value[cursor]
+    if (isDelimiter(character, delimiters, lastStructural)) {
+      lastStructural = character
+      inFields = true
+    } else if (inFields && URL_FIELD_CHARACTERS.includes(character)) {
+      lastStructural = character
+    }
+  }
+  return indexes
+}
+
+/**
+ * Whether this `?` or `#` is one of a URL's three delimiters, consuming it if so.
+ *
+ * A URL has exactly one query delimiter, one fragment delimiter, and — matching
+ * how the fragment is split — one delimiter between the fragment's own head and
+ * tail. Every other `?` or `#` is ordinary text inside a value, and reading one
+ * as structural would cut `?token=prefix?https://secret/…` in half at a `?` that
+ * belongs to the token.
+ */
+function isDelimiter(
+  character: string,
+  seen: { query: boolean; fragment: boolean; fragmentQuery: boolean },
+  lastStructural: string
+): boolean {
+  if (character === '#') {
+    return seen.fragment ? false : (seen.fragment = true)
+  }
+  if (character !== '?') {
+    return false
+  }
+  if (seen.fragment) {
+    // Inside a fragment, a `?` right after a field name may belong to that
+    // field's value rather than open the tail. Leaving it unstructural keeps a
+    // following address attached, so the fragment split and its fail-closed tail
+    // rule get to decide — they can see the whole credential, this cannot.
+    if (lastStructural === '=') {
+      return false
+    }
+    return seen.fragmentQuery ? false : (seen.fragmentQuery = true)
+  }
+  return seen.query ? false : (seen.query = true)
+}
+
+/**
+ * Redacts the credentials embedded in one URL-shaped match: the userinfo, plus
+ * the values of credential-named query and fragment fields. A retained value that
+ * is itself a URL — a gateway's `?url=` passthrough — gets the same pass one
+ * level deep.
+ *
+ * One match can hold more than one address: a prose word in front of it
+ * (`Failed URL:https://…`, `a:b:https://…`), several run together
+ * (`…/doc,https://…`), or one parked in another's query or fragment
+ * (`…/?download)[b](https://…`). The later address always begins inside what
+ * would parse as the earlier one's path, query key, or fragment — none of which
+ * is examined for userinfo — so it is cut out and sanitized on its own.
+ *
+ * The exception is an authority in value position (see
+ * {@link findEmbeddedAuthorityIndexes}), which the field pass already gives the
+ * nested pass. Cutting there would take a gateway's `?url=https://…` out of the
+ * field it belongs to.
+ *
+ * One pass, no recursion: after the cuts, every authority left inside a piece is
+ * either at its start or in value position, so no piece can need cutting again.
+ *
+ * Every piece but the last is sanitized without the punctuation split: it is
+ * followed by an address rather than by prose, so its last character is a
+ * separator, not a sentence's. (It matters — stripping the `:` off `URL:` would
+ * leave `URL`, which `new URL()` rejects, and the prose word would become
+ * `[redacted]`.)
+ */
+function sanitizeUrl(value: string, mode: UrlSanitizeMode): string {
+  const embedded = findEmbeddedAuthorityIndexes(value)
+  if (embedded.length === 0) {
+    return sanitizeSingleUrl(value, mode)
+  }
+  let result = ''
+  let start = 0
+  for (const index of embedded) {
+    result += sanitizeSingleUrl(value.slice(start, index), { ...mode, stripPunctuation: false })
+    start = index
+  }
+  return result + sanitizeSingleUrl(value.slice(start), mode)
+}
+
+/** {@link sanitizeUrl} for a value already known to hold exactly one address. */
+function sanitizeSingleUrl(value: string, mode: UrlSanitizeMode): string {
+  // The length bound caps the work an attacker-shaped address can force, so it
+  // only applies to a match that has an authority. A long authority-less match
+  // is usually a data URI; it is parsed like any other, which is linear in
+  // `new URL()` and still capped by the field bound below, and comes back
+  // byte-for-byte when it holds nothing to redact.
+  if (value.length > MAX_URL_LENGTH && URL_AUTHORITY_PATTERN.test(value)) {
+    return REDACTED_VALUE
+  }
+
+  const { address, suffix } = mode.stripPunctuation ? splitTrailingPunctuation(value) : { address: value, suffix: '' }
+  let url: URL
+  try {
+    url = new URL(address)
+  } catch {
+    return REDACTED_VALUE + suffix
+  }
+
+  const query = url.search.slice(1)
+  const hasFragment = url.hash !== ''
+  const fragment = splitFragmentParts(url.hash)
+  if (exceedsUrlFieldLimit(query) || exceedsUrlFieldLimit(fragment.head) || exceedsUrlFieldLimit(fragment.tail ?? '')) {
+    return REDACTED_VALUE + suffix
+  }
+
+  let changed = false
+  if (url.username || url.password) {
+    url.username = REDACTED_VALUE
+    url.password = ''
+    changed = true
+  }
+  const sanitizedQuery = sanitizeUrlFields(query, mode.allowNestedUrls)
+  if (sanitizedQuery.changed) {
+    url.search = sanitizedQuery.serialized
+    changed = true
+  }
+  const sanitizedHead = sanitizeFragmentPart(fragment.head, mode.allowNestedUrls)
+  const sanitizedTail =
+    fragment.tail === null
+      ? null
+      : sanitizeFragmentTail(fragment.tail, sanitizedHead.lastFieldSensitive, mode.allowNestedUrls)
+  const sanitizedHash = sanitizedTail === null ? sanitizedHead.value : `${sanitizedHead.value}?${sanitizedTail.value}`
+  if (sanitizedHash !== url.hash.slice(1)) {
+    url.hash = sanitizedHash
+    changed = true
+  }
+
+  // The punctuation split off the end may be the tail of the very credential
+  // just replaced (`?password=fakepass!!!`) rather than the sentence's. When the
+  // last field of the URL's trailing part is a credential's the punctuation goes
+  // with it; losing a comma from the surrounding prose is the accepted cost of
+  // not shipping `!!!`.
+  const trailingFields = hasFragment ? (sanitizedTail ?? sanitizedHead) : sanitizedQuery
+  return (changed ? url.toString() : address) + (trailingFields.lastFieldSensitive ? '' : suffix)
+}
+
+/**
+ * Replaces every URL-shaped match in `text`.
+ *
+ * A match that IS the whole string is an address rather than prose — a captured
+ * `$mcp_resource_name`, a `params.uri`, a nested `?url=` value — so nothing is
+ * split off its end: a trailing `!` there belongs to the URL.
+ */
+function sanitizeUrlsInString(text: string, mode: UrlSanitizeMode): string {
+  return text.replace(URL_PATTERN, (match) =>
+    sanitizeUrl(match, { ...mode, stripPunctuation: mode.stripPunctuation && match.length !== text.length })
+  )
+}
+
+/** Whether a string is large enough, and shaped enough like base64, to be a blob. */
+function isBinaryBlob(value: string): boolean {
+  return (
     value.length >= SIZE_GATE &&
     (BASE64_PATTERN.test(value) ||
       isBase64DataUrl(value) ||
       (BASE64URL_SPECIFIC_CHAR_PATTERN.test(value) && BASE64URL_PATTERN.test(value)))
-  ) {
+  )
+}
+
+/** Replaces PostHog API keys wherever they appear in a string. */
+function redactCredentials(value: string): string {
+  return value.replace(POSTHOG_TOKEN_PATTERN, REDACTED_VALUE)
+}
+
+/** Replaces every URL-shaped match, credentials and all. */
+function redactUrls(value: string): string {
+  return sanitizeUrlsInString(value, { allowNestedUrls: true, stripPunctuation: true })
+}
+
+function sanitizeString(value: string): string {
+  return isBinaryBlob(value) ? BINARY_REDACTED_VALUE : redactUrls(redactCredentials(value))
+}
+
+/**
+ * Sanitizes agent-narrated free text (`$mcp_intent`, the `send_feedback`
+ * fields): structured PII on top of the passes every captured string gets.
+ *
+ * Every step of the order is load-bearing. The binary gate reads the value as it
+ * arrived, because splicing `[redacted]` into a blob — a Luhn-valid run inside
+ * base64 is enough — stops it looking like base64 and would ship it whole.
+ * Credentials go before PII, because a PII pattern can cut a token in half (a
+ * phone-shaped run inside one) and leave the halves behind. PII goes before the
+ * URL pass, because the URL rewrite percent-encodes the `@` that the email
+ * pattern anchors on.
+ */
+export function sanitizeFreeText(value: string): string {
+  if (isBinaryBlob(value)) {
     return BINARY_REDACTED_VALUE
   }
-  return value.replace(POSTHOG_TOKEN_PATTERN, REDACTED_VALUE)
+  return redactUrls(redactPii(redactCredentials(value)))
 }
 
 function passesLuhn(digits: string): boolean {
@@ -184,16 +607,29 @@ export function redactPii(value: string): string {
 }
 
 export function sanitizeCapturedValue(value: unknown): unknown {
+  return sanitizeValueWith(value, sanitizeString)
+}
+
+/**
+ * {@link sanitizeCapturedValue} with the intent-grade string pass
+ * ({@link sanitizeFreeText}) on every string leaf, so nested agent-narrated
+ * values get structured-PII redaction in the load-bearing order too.
+ */
+export function sanitizeFreeTextValue(value: unknown): unknown {
+  return sanitizeValueWith(value, sanitizeFreeText)
+}
+
+function sanitizeValueWith(value: unknown, sanitizeStringFn: (value: string) => string): unknown {
   if (value == null) {
     return value
   }
 
   if (typeof value === 'string') {
-    return sanitizeString(value)
+    return sanitizeStringFn(value)
   }
 
   if (Array.isArray(value)) {
-    return value.map(sanitizeCapturedValue)
+    return value.map((item) => sanitizeValueWith(item, sanitizeStringFn))
   }
 
   if (value instanceof Date) {
@@ -206,7 +642,7 @@ export function sanitizeCapturedValue(value: unknown): unknown {
 
   const result: JsonRecord = {}
   for (const [key, nestedValue] of Object.entries(value)) {
-    result[key] = shouldRedactKey(key) ? REDACTED_VALUE : sanitizeCapturedValue(nestedValue)
+    result[key] = shouldRedactKey(key) ? REDACTED_VALUE : sanitizeValueWith(nestedValue, sanitizeStringFn)
   }
   return result
 }

package/src/extensions/posthog-events.ts

@@ -10,6 +10,7 @@ import { MCPAnalyticsEventType } from './event-types'
 const BUILT_IN_EVENT_NAME_BY_TYPE = {
   [MCPAnalyticsEventType.custom]: PostHogMCPAnalyticsEvent.Custom,
   [MCPAnalyticsEventType.identify]: PostHogMCPAnalyticsEvent.Identify,
+  [MCPAnalyticsEventType.mcpFeedback]: PostHogMCPAnalyticsEvent.Feedback,
   [MCPAnalyticsEventType.mcpMissingCapability]: PostHogMCPAnalyticsEvent.MissingCapability,
   [MCPAnalyticsEventType.mcpInitialize]: PostHogMCPAnalyticsEvent.Initialize,
   [MCPAnalyticsEventType.mcpPromptsGet]: PostHogMCPAnalyticsEvent.PromptGet,

package/src/extensions/posthog-mcp.ts

@@ -1,6 +1,9 @@
 import { PostHog, type PostHogOptions } from 'posthog-node'
 
 import type {
+  FeedbackCaptureData,
+  CollectFeedbackOptions,
+  CollectFeedbackConfig,
   InitializeCaptureData,
   JsonRecord,
   MCPAnalyticsOptions,
@@ -13,6 +16,14 @@ import type {
   ToolCallCaptureData,
   ToolsListCaptureData,
 } from '../types'
+import {
+  buildFeedbackEventProperties,
+  buildFeedbackIntent,
+  getFeedbackToolDescriptor,
+  parseFeedbackReport,
+  resolveCollectFeedbackOptions,
+  SEND_FEEDBACK_TOOL_NAME,
+} from './feedback'
 import { analyticsOwnsParameter, stripOwnedAnalyticsArguments } from './analytics-parameters'
 import {
   addContextParameterToTools,
@@ -47,6 +58,17 @@ export interface PostHogMCPOptions extends PostHogOptions {
    * can't drift. Defaults to `get_more_tools`.
    */
   missingCapabilityToolName?: string
+  /**
+   * Enable + configure the `send_feedback` virtual tool: injected by
+   * {@link PostHogMCP.prepareToolList} (when its `collectFeedback` toggle is on)
+   * and detected by {@link PostHogMCP.prepareToolCall}. Set once here so
+   * injection and detection can't drift — without this option, `prepareToolCall`
+   * never flags a call as feedback, so a real tool that uses the name is not
+   * shadowed. Pick a `toolName` no real tool uses. `onFeedback` is ignored on
+   * this path — the host dispatcher routes reports itself via
+   * {@link PreparedToolCall.feedbackReport}.
+   */
+  collectFeedback?: CollectFeedbackConfig
   /**
    * Capture the calling model from recognized client metadata, with an injected
    * `llm_model` argument as fallback. Off by default.
@@ -93,19 +115,36 @@ export interface PostHogMCPOptions extends PostHogOptions {
 export class PostHogMCP extends PostHog {
   readonly #sink = new McpEventSink(this)
 
-  // The get_more_tools name lives here (not on the per-call options) so that
+  // The virtual-tool config lives here (not on the per-call options) so that
   // prepareToolList (inject) and prepareToolCall (detect) always agree.
   readonly #missingCapabilityToolName: string
+  // `undefined` is the enable switch's off state: without it, prepareToolCall
+  // must never claim a call named like the virtual tool — the host may have a
+  // real tool by that name, and flagging it would shadow the real handler.
+  readonly #feedbackOptions: CollectFeedbackOptions | undefined
   readonly #captureModel: MCPAnalyticsOptions['captureModel']
   readonly #modelParameterOwnership = new Map<string, boolean>()
 
   constructor(apiKey: string, options: PostHogMCPOptions = {}) {
     super(apiKey, options)
     this.#missingCapabilityToolName = options.missingCapabilityToolName ?? GET_MORE_TOOLS_NAME
+    this.#feedbackOptions = resolveCollectFeedbackOptions(options.collectFeedback)
+    // Fail fast on a config error (reserved extra key, undeclared extraRequired)
+    // instead of first surfacing it when a tools/list is served.
+    getFeedbackToolDescriptor(this.#feedbackOptions)
+    if (this.#feedbackOptions?.onFeedback) {
+      log(
+        'Warning: collectFeedback.onFeedback is ignored on the PostHogMCP path - route reports from your dispatcher via prepareToolCall().feedbackReport instead.'
+      )
+    }
     this.#captureModel = options.captureModel
     applyMcpLibIdentity(this)
   }
 
+  get #feedbackToolName(): string {
+    return this.#feedbackOptions?.toolName ?? SEND_FEEDBACK_TOOL_NAME
+  }
+
   /** Capture a tool invocation. Emits `$mcp_tool_call` (+ an `$exception` sibling on error). */
   captureToolCall(data: ToolCallCaptureData): void {
     const event = baseEvent(MCPAnalyticsEventType.mcpToolsCall, data)
@@ -160,8 +199,9 @@ export class PostHogMCP extends PostHog {
    * Decorate your `tools/list` response with PostHog's analytics affordances:
    * injects the `context` argument into every tool (so agents state their intent,
    * captured as `$mcp_intent`), injects `llm_model` when the constructor's
-   * `captureModel` option is enabled, and appends `get_more_tools` when
-   * `reportMissing` is on. Returns a new array; your tools are untouched.
+   * `captureModel` option is enabled, appends `get_more_tools` when
+   * `reportMissing` is on, and appends `send_feedback` when `collectFeedback` is
+   * on. Returns a new array; your tools are untouched.
    *
    * The appended `get_more_tools` descriptor carries only the base MCP tool fields
    * (name, description, input schema) — not any framework-specific fields your
@@ -188,6 +228,14 @@ export class PostHogMCP extends PostHog {
       prepared = [...prepared, getReportMissingToolDescriptor(this.#missingCapabilityToolName) as TTool]
     }
 
+    if (
+      options.collectFeedback &&
+      this.#feedbackOptions !== undefined &&
+      !prepared.some((tool) => tool?.name === this.#feedbackToolName)
+    ) {
+      prepared = [...prepared, getFeedbackToolDescriptor(this.#feedbackOptions) as TTool]
+    }
+
     if (isCaptureModelEnabled(this.#captureModel)) {
       this.#modelParameterOwnership.clear()
       const ownershipByName = new Map<string, boolean>()
@@ -256,6 +304,7 @@ export class PostHogMCP extends PostHog {
       ? resolveModel({ params: { arguments: args, _meta: options.requestMeta } }, ownsModel)
       : undefined
     const strippedArgs = stripContext(args)
+    const isFeedback = this.#feedbackOptions !== undefined && name === this.#feedbackToolName
     return {
       intent,
       intentSource: intent ? 'context_parameter' : undefined,
@@ -269,6 +318,8 @@ export class PostHogMCP extends PostHog {
           }) as Record<string, unknown> | undefined)
         : strippedArgs,
       isMissingCapability: name === this.#missingCapabilityToolName,
+      isFeedback,
+      feedbackReport: isFeedback ? parseFeedbackReport(args, this.#feedbackOptions) : undefined,
     }
   }
 
@@ -286,6 +337,26 @@ export class PostHogMCP extends PostHog {
     this.#emit(event)
   }
 
+  /**
+   * Capture a `send_feedback` call as an agent-feedback report. Emits
+   * `$mcp_feedback` with the report's `$mcp_feedback_*` properties and its
+   * summary/details as `$mcp_intent`. Reply to the agent with
+   * `sendFeedbackResult()` (or a custom text) after routing the report to your
+   * own feedback backend.
+   */
+  captureFeedback(data: FeedbackCaptureData): void {
+    const event = baseEvent(MCPAnalyticsEventType.mcpFeedback, data)
+    event.resourceName = this.#feedbackToolName
+    // Deliberately no `$mcp_parameters`: the arguments are agent-narrated free
+    // text, and the PII-redacted `$mcp_feedback_*` properties are the captured
+    // surface. Raw arguments would bypass that redaction. Feedback properties
+    // win over the caller's, matching the instrument() path's spread order.
+    event.properties = { ...event.properties, ...buildFeedbackEventProperties(data.report) }
+    applyIntent(event, buildFeedbackIntent(data.report), 'context_parameter')
+    setEventModel(event, data.llmModel, data.llmModelSource)
+    this.#emit(event)
+  }
+
   /**
    * Fire-and-forget, mirroring posthog-node's `capture()`: the event is enqueued
    * on the client, not awaited. Never throws — a failure to record analytics