@posthog/mcp 0.12.0 → 0.13.1

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
 
+// 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
+// well-defined *structured identifiers* — the kind regex can match with high
+// precision. Person names and postal addresses are deliberately out of scope:
+// they need an NER model that a client SDK cannot ship, and naive patterns would
+// over-redact ordinary prose. Patterns are ordered so an earlier pass never eats
+// digits a later pass needs (email before phone, IPs before phone, cards before
+// the generic phone pass). See `redactPii`.
+// Horizontal Unicode spaces (NBSP, narrow NBSP, ideographic space, ...) are what
+// appear when text is copied from web pages or PDFs. `redactPii` normalizes them
+// to an ASCII space first so the separator-based card/phone/SSN candidates match
+// them instead of leaking the identifier they group.
+const UNICODE_SPACE_PATTERN = /[\u00A0\u1680\u2000-\u200A\u202F\u205F\u3000]/g
+// Quantifiers are bounded to RFC-ish limits (local-part <=64, domain <=255,
+// TLD <=24) rather than open-ended `+`. Unbounded `+` here is quadratic: on a
+// long run of local-part chars with no valid `.tld`, `replace` rescans from
+// every start position. `$mcp_intent` is attacker-influenceable free text seen
+// before truncation, so an open-ended pattern is a reachable event-loop stall.
+const EMAIL_PATTERN = /[A-Za-z0-9._%+-]{1,64}@[A-Za-z0-9.-]{1,255}\.[A-Za-z]{2,24}/g
+const IPV4_PATTERN = /\b(?:(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)\.){3}(?:25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)\b/g
+// Four forms: full 8-group, `::`-terminated (`2001:db8::`), a middle `::`
+// (`2001:db8::8a2e:1`), and a leading `::` (`::1`). The compressed branches use a
+// `(?<![\w:])` boundary so a hex-looking C++ scope like `std::bad` — whose left
+// side is not a valid hex group — is not mistaken for an address, while a
+// genuinely address-shaped `dead::beef` still matches.
+const IPV6_PATTERN =
+  /\b(?:[0-9A-Fa-f]{1,4}:){7}[0-9A-Fa-f]{1,4}\b|(?<![\w:])(?:[0-9A-Fa-f]{1,4}:){1,7}:(?![\w:])|(?<![\w:])(?:[0-9A-Fa-f]{1,4}:){1,6}:[0-9A-Fa-f]{1,4}(?::[0-9A-Fa-f]{1,4}){0,5}(?![\w])|(?<![\w:])::(?:[0-9A-Fa-f]{1,4}(?::[0-9A-Fa-f]{1,4}){0,6})(?![\w])/g
+// A separator (space, dot, or dash) is required between the 3-2-4 groups so bare
+// 9-digit IDs are never mistaken for an SSN.
+const US_SSN_PATTERN = /\b\d{3}[ .-]\d{2}[ .-]\d{4}\b/g
+// A run of >=13 digits optionally grouped by a single space, dot, dash, or
+// slash. This only marks the numeric region; `redactCardInMatch` then looks for
+// the actual card as a run of whole separator-delimited groups that passes Luhn,
+// so an adjacent field such as an expiry (`4111 1111 1111 1111 12/30`) is not
+// absorbed into a failing check that would leak the card.
+const CREDIT_CARD_CANDIDATE_PATTERN = /\b\d(?:[ ./-]?\d){12,}\b/g
+// Matches each separator-delimited digit group inside a card candidate.
+const DIGIT_GROUP_PATTERN = /\d+/g
+// Phone matching is structural rather than "any 10–15 digits", so dates
+// (`2024-01-15 12:30`) and dotted versions are not mistaken for numbers. Two
+// forms: a North-American 3-3-4 grouping, and an international number that must
+// start with `+` and a country code. The area code is either `(415)` (the
+// separator after it is optional, so `(415)555-0142` matches) or a bare `415`
+// that must be followed by a separator (space, dot, dash, or slash) — so a bare
+// digit run is never taken for a phone number.
+const PHONE_NANP_PATTERN = /(?<![\w+])(?:\+?1[ ./-]?)?(?:\(\d{3}\)[ ./-]?|\d{3}[ ./-])\d{3}[ ./-]\d{4}(?![\w])/g
+const PHONE_INTL_PATTERN = /(?<!\w)\+\d{1,3}(?:[ ./()-]{0,2}\d){7,13}(?![\w])/g
+
 type JsonRecord = Record<string, unknown>
 
 function isRecord(value: unknown): value is JsonRecord {
@@ -54,6 +103,86 @@ function sanitizeString(value: string): string {
   return value.replace(POSTHOG_TOKEN_PATTERN, REDACTED_VALUE)
 }
 
+function passesLuhn(digits: string): boolean {
+  let sum = 0
+  let double = false
+  for (let index = digits.length - 1; index >= 0; index--) {
+    let digit = digits.charCodeAt(index) - 48
+    if (digit < 0 || digit > 9) {
+      return false
+    }
+    if (double) {
+      digit *= 2
+      if (digit > 9) {
+        digit -= 9
+      }
+    }
+    sum += digit
+    double = !double
+  }
+  return sum % 10 === 0
+}
+
+// A card candidate can span more than one card plus adjacent fields (e.g. an
+// expiry, or a second card). This redacts every card in it: scanning
+// left-to-right over the whole separator-delimited digit groups, at each start it
+// takes the longest run whose joined digits are 13–19 long and pass Luhn, redacts
+// just that span, and resumes after it; a group that begins no valid run is kept
+// and skipped. Checking group-aligned runs rather than arbitrary digit windows
+// keeps the false-positive rate at Luhn's own ~1-in-10, instead of letting a
+// chance-valid sub-window of an ordinary long ID trigger redaction.
+function redactCardInMatch(match: string): string {
+  const groups: { digits: string; start: number; end: number }[] = []
+  for (let m = DIGIT_GROUP_PATTERN.exec(match); m !== null; m = DIGIT_GROUP_PATTERN.exec(match)) {
+    groups.push({ digits: m[0], start: m.index, end: m.index + m[0].length })
+  }
+  let output = ''
+  let cursor = 0
+  let first = 0
+  while (first < groups.length) {
+    let digits = ''
+    let matchedLast = -1
+    for (let last = first; last < groups.length; last++) {
+      digits += groups[last].digits
+      if (digits.length > 19) {
+        break
+      }
+      if (digits.length >= 13 && passesLuhn(digits)) {
+        matchedLast = last
+      }
+    }
+    if (matchedLast >= 0) {
+      output += match.slice(cursor, groups[first].start) + REDACTED_VALUE
+      cursor = groups[matchedLast].end
+      first = matchedLast + 1
+    } else {
+      first++
+    }
+  }
+  return output + match.slice(cursor)
+}
+
+/**
+ * Redacts structured personal identifiers (emails, IP addresses, credit-card
+ * numbers, US SSNs, and phone numbers) from a free-text string. Intended for the
+ * agent-narrated `$mcp_intent` value only — not for structured tool parameters or
+ * responses, where the same shapes are often legitimate data. Horizontal Unicode
+ * spaces are first normalized to an ASCII space so copy-pasted identifiers still
+ * match. Returns a new string; leaves the input's identifiers untouched when
+ * nothing matches.
+ */
+export function redactPii(value: string): string {
+  let result = value.replace(UNICODE_SPACE_PATTERN, ' ')
+  result = result.replace(EMAIL_PATTERN, REDACTED_VALUE)
+  result = result.replace(IPV4_PATTERN, REDACTED_VALUE)
+  result = result.replace(IPV6_PATTERN, REDACTED_VALUE)
+  result = result.replace(CREDIT_CARD_CANDIDATE_PATTERN, redactCardInMatch)
+  result = result.replace(US_SSN_PATTERN, REDACTED_VALUE)
+  result = result.replace(PHONE_NANP_PATTERN, REDACTED_VALUE)
+  result = result.replace(PHONE_INTL_PATTERN, REDACTED_VALUE)
+  return result
+}
+
 export function sanitizeCapturedValue(value: unknown): unknown {
   if (value == null) {
     return value

package/src/extensions/model-parameters.ts

@@ -74,7 +74,10 @@ export function addModelParameterToTools<TTool extends ModelInjectableTool>(
  * not become a property value queries would group by.
  */
 export function getModelArgument(request: MCPRequestLike): string | undefined {
-  const model = request.params?.arguments?.llm_model
+  return normalizeModel(request.params?.arguments?.llm_model)
+}
+
+function normalizeModel(model: unknown): string | undefined {
   if (typeof model !== 'string') {
     return undefined
   }
@@ -86,9 +89,10 @@ export function getModelArgument(request: MCPRequestLike): string | undefined {
 }
 
 export function setEventModel(event: McpEvent, model: string | undefined): void {
-  if (!model) {
+  const normalizedModel = normalizeModel(model)
+  if (!normalizedModel) {
     return
   }
-  event.llmModel = model
+  event.llmModel = normalizedModel
   event.llmModelSource = 'self_reported'
 }

package/src/extensions/posthog-mcp.ts

@@ -3,14 +3,17 @@ import { PostHog, type PostHogOptions } from 'posthog-node'
 import type {
   InitializeCaptureData,
   JsonRecord,
+  MCPAnalyticsOptions,
   McpCaptureCommon,
   McpEvent,
   MissingCapabilityCaptureData,
   PreparedToolCall,
+  PrepareToolCallOptions,
   PrepareToolListOptions,
   ToolCallCaptureData,
   ToolsListCaptureData,
 } from '../types'
+import { analyticsOwnsParameter, stripOwnedAnalyticsArguments } from './analytics-parameters'
 import {
   addContextParameterToTools,
   getContextDescription,
@@ -22,6 +25,13 @@ import { captureException } from './exceptions'
 import { normalizeHeaderString } from './headers'
 import { applyMcpLibIdentity } from './lib-identity'
 import { log } from './logger'
+import {
+  addModelParameterToTool,
+  getModelArgument,
+  getModelDescription,
+  isCaptureModelEnabled,
+  setEventModel,
+} from './model-parameters'
 import { McpEventSink } from './sink'
 import { GET_MORE_TOOLS_NAME, getReportMissingToolDescriptor } from './tools'
 
@@ -37,6 +47,11 @@ export interface PostHogMCPOptions extends PostHogOptions {
    * can't drift. Defaults to `get_more_tools`.
    */
   missingCapabilityToolName?: string
+  /**
+   * Inject a required `llm_model` argument into advertised tools and capture
+   * the agent's self-reported value. Off by default.
+   */
+  captureModel?: MCPAnalyticsOptions['captureModel']
 }
 
 /**
@@ -57,7 +72,10 @@ export interface PostHogMCPOptions extends PostHogOptions {
  * ```ts
  * import { PostHogMCP } from "@posthog/mcp"
  *
- * const posthog = new PostHogMCP("phc_your_project_token", { host: "https://us.i.posthog.com" })
+ * const posthog = new PostHogMCP("phc_your_project_token", {
+ *   host: "https://us.i.posthog.com",
+ *   captureModel: true,
+ * })
  *
  * posthog.captureToolCall({
  *   toolName: "search_docs",
@@ -78,10 +96,13 @@ export class PostHogMCP extends PostHog {
   // The get_more_tools name lives here (not on the per-call options) so that
   // prepareToolList (inject) and prepareToolCall (detect) always agree.
   readonly #missingCapabilityToolName: string
+  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.#captureModel = options.captureModel
     applyMcpLibIdentity(this)
   }
 
@@ -97,6 +118,10 @@ export class PostHogMCP extends PostHog {
     event.isError = data.isError
     event.errorType = data.errorType
     applyIntent(event, data.intent, data.intentSource)
+    setEventModel(event, data.llmModel)
+    if (event.llmModel && data.llmModelSource) {
+      event.llmModelSource = data.llmModelSource
+    }
     if (data.isError) {
       event.error = captureException(data.error ?? `Tool ${data.toolName} returned an error`)
     }
@@ -137,9 +162,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`) and, when `reportMissing` is on, appends the
-   * `get_more_tools` virtual tool (rename it via the `missingCapabilityToolName`
-   * constructor option). Returns a new array; your tools are untouched.
+   * 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.
    *
    * The appended `get_more_tools` descriptor carries only the base MCP tool fields
    * (name, description, input schema) — not any framework-specific fields your
@@ -165,18 +190,41 @@ export class PostHogMCP extends PostHog {
     if (options.reportMissing && !prepared.some((tool) => tool?.name === this.#missingCapabilityToolName)) {
       prepared = [...prepared, getReportMissingToolDescriptor(this.#missingCapabilityToolName) as TTool]
     }
+
+    if (isCaptureModelEnabled(this.#captureModel)) {
+      this.#modelParameterOwnership.clear()
+      const ownershipByName = new Map<string, boolean>()
+      for (const tool of prepared) {
+        if (typeof tool.name !== 'string') {
+          continue
+        }
+        const ownsModel = analyticsOwnsParameter(tool.inputSchema, 'llm_model')
+        ownershipByName.set(tool.name, (ownershipByName.get(tool.name) ?? true) && ownsModel)
+      }
+      for (const [toolName, ownsModel] of ownershipByName) {
+        this.#modelParameterOwnership.set(toolName, ownsModel)
+      }
+      const modelDescription = getModelDescription(this.#captureModel)
+      prepared = prepared.map((tool) =>
+        typeof tool.name === 'string' && ownershipByName.get(tool.name) === false
+          ? tool
+          : addModelParameterToTool(tool, modelDescription)
+      )
+    }
     return prepared
   }
 
   /**
-   * Read an incoming `tools/call` before you dispatch it: pulls the agent's
-   * intent off the injected `context` argument, strips `context` from the
-   * arguments (so your handler and its schema validation never see it), and flags
+   * Read an incoming `tools/call` before you dispatch it: pulls analytics values
+   * from SDK-owned arguments, strips those arguments before validation, and flags
    * whether the call targeted the `get_more_tools` virtual tool.
    *
-   * Pass the returned `intent` / `intentSource` to {@link captureToolCall}, and
+   * Pass the returned intent and model fields to {@link captureToolCall}, and
    * dispatch the returned `args` to your tool.
    *
+   * On stateless or multi-replica servers, pass the original tool descriptor
+   * so ownership does not depend on which process served `tools/list`.
+   *
    * This only extracts the explicit `context` argument (`intentSource:
    * 'context_parameter'`); it does not infer intent. If you run your own
    * inference, pass that string with `intentSource: 'inferred'` straight to
@@ -185,22 +233,42 @@ export class PostHogMCP extends PostHog {
    *
    * @example
    * ```ts
-   * const { intent, intentSource, args, isMissingCapability } = posthog.prepareToolCall(name, rawArgs)
+   * const { intent, intentSource, llmModel, llmModelSource, args, isMissingCapability } =
+   *   posthog.prepareToolCall(name, rawArgs)
    * if (isMissingCapability) {
-   *   posthog.captureMissingCapability({ context: intent, ...identity })
+   *   posthog.captureMissingCapability({ context: intent, llmModel, llmModelSource, ...identity })
    *   return getMoreToolsResult()
    * }
    * const result = await runTool(name, args)
    * posthog.captureToolCall({ toolName: name, intent, intentSource, ...identity })
    * ```
    */
-  prepareToolCall(name: string, args?: Record<string, unknown>): PreparedToolCall {
+  prepareToolCall(
+    name: string,
+    args?: Record<string, unknown>,
+    options: PrepareToolCallOptions = {}
+  ): PreparedToolCall {
     const rawContext = args?.context
     const intent = typeof rawContext === 'string' && rawContext.trim() ? rawContext.trim() : undefined
+    const ownsModel =
+      isCaptureModelEnabled(this.#captureModel) &&
+      (options.originalTool
+        ? analyticsOwnsParameter(options.originalTool.inputSchema, 'llm_model')
+        : this.#modelParameterOwnership.get(name) === true)
+    const llmModel = ownsModel ? getModelArgument({ params: { arguments: args } }) : undefined
+    const strippedArgs = stripContext(args)
     return {
       intent,
       intentSource: intent ? 'context_parameter' : undefined,
-      args: stripContext(args),
+      llmModel,
+      llmModelSource: llmModel ? 'self_reported' : undefined,
+      args: ownsModel
+        ? (stripOwnedAnalyticsArguments(strippedArgs, {
+            context: false,
+            conversationId: false,
+            llmModel: true,
+          }) as Record<string, unknown> | undefined)
+        : strippedArgs,
       isMissingCapability: name === this.#missingCapabilityToolName,
     }
   }
@@ -215,6 +283,10 @@ export class PostHogMCP extends PostHog {
     event.resourceName = this.#missingCapabilityToolName
     event.parameters = data.parameters
     applyIntent(event, data.context, 'context_parameter')
+    setEventModel(event, data.llmModel)
+    if (event.llmModel && data.llmModelSource) {
+      event.llmModelSource = data.llmModelSource
+    }
     this.#emit(event)
   }
 

package/src/extensions/sanitization.ts

@@ -4,7 +4,7 @@
 // Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
 import type { ErrorProperties, Event, McpEvent } from '../types'
-import { sanitizeCapturedValue } from './mcp-payloads'
+import { redactPii, sanitizeCapturedValue } from './mcp-payloads'
 
 type SanitizedRecord = Record<string, unknown>
 
@@ -15,8 +15,8 @@ function isRecord(value: unknown): value is SanitizedRecord {
 /**
  * Sanitizes an event by redacting non-text content blocks from responses
  * and large base64-encoded strings from parameters, and applying the same
- * string redaction (PostHog tokens, base64 blobs, sensitive keys) to the
- * agent-supplied intent.
+ * string redaction (PostHog tokens, base64 blobs, sensitive keys) to values
+ * supplied by the agent.
  *
  * This is a synchronous operation that returns a new object without mutating the original.
  * It should run after customer redaction in the event pipeline.
@@ -32,11 +32,18 @@ export function sanitizeEvent<T extends Event | McpEvent>(event: T): T {
     result.parameters = sanitizeParameters(result.parameters)
   }
 
-  // The intent comes straight from an agent-narrated `context` string, so it
-  // can contain a secret the LLM read aloud. Redact it like any other captured
-  // value rather than shipping it raw as `$mcp_intent`.
+  // The intent comes straight from an agent-narrated `context` string, so it can
+  // contain a secret the LLM read aloud or personal data it narrated about the
+  // user. Redact it like any other captured value, then strip structured PII
+  // (emails, phone numbers, IPs, cards, SSNs) rather than shipping it raw as
+  // `$mcp_intent`. PII redaction is scoped to the intent only — structured tool
+  // parameters and responses often hold the same shapes as legitimate data.
   if (result.userIntent != null) {
-    result.userIntent = sanitizeCapturedValue(result.userIntent) as string
+    result.userIntent = redactPii(sanitizeCapturedValue(result.userIntent) as string)
+  }
+
+  if (result.llmModel != null) {
+    result.llmModel = sanitizeCapturedValue(result.llmModel) as string
   }
 
   if (result.error != null) {

package/src/index.ts

@@ -233,6 +233,7 @@ export type {
   MCPAnalyticsOptions,
   MissingCapabilityCaptureData,
   PreparedToolCall,
+  PrepareToolCallOptions,
   PrepareToolListOptions,
   RequestHeaderBag,
   ToolCallCaptureData,

package/src/types.ts

@@ -511,6 +511,13 @@ export interface ToolCallCaptureData extends McpCaptureCommon {
    * the host derived it. Defaults to `context_parameter` when an intent is set.
    */
   intentSource?: MCPAnalyticsIntentSource
+  /**
+   * The calling agent's self-reported model id -> `$mcp_llm_model`. On the
+   * custom-dispatcher path, read it from {@link PostHogMCP.prepareToolCall}.
+   */
+  llmModel?: string
+  /** How the model id was obtained -> `$mcp_llm_model_source`. */
+  llmModelSource?: MCPAnalyticsModelSource
   /** Captured call arguments → `$mcp_parameters` (sanitized + truncated). */
   parameters?: unknown
   /** Captured tool result → `$mcp_response` (sanitized + truncated). */
@@ -586,18 +593,30 @@ export interface PrepareToolListOptions {
   reportMissing?: boolean
 }
 
+/** Options for {@link PostHogMCP.prepareToolCall}. */
+export interface PrepareToolCallOptions {
+  /**
+   * The tool descriptor before PostHog preparation. Pass this on stateless or
+   * multi-replica servers so SDK argument ownership is resolved per request.
+   */
+  originalTool?: { inputSchema?: unknown }
+}
+
 /**
  * Result of {@link PostHogMCP.prepareToolCall}: the intent pulled off the
- * incoming call, the arguments with the injected `context` removed (so your tool
- * handler and its schema validation never see it), and whether the call targeted
- * the `get_more_tools` virtual tool.
+ * incoming call, the arguments with SDK-owned analytics fields removed, and
+ * whether the call targeted the `get_more_tools` virtual tool.
  */
 export interface PreparedToolCall {
   /** The agent's stated intent (the `context` argument), if present. */
   intent?: string
   /** Where the intent came from. Always `context_parameter` here when set. */
   intentSource?: MCPAnalyticsIntentSource
-  /** The call arguments with the injected `context` key stripped out. */
+  /** The agent's self-reported model id, when `captureModel` is enabled and owned by the SDK. */
+  llmModel?: string
+  /** How the model id was obtained. Always `self_reported` when present. */
+  llmModelSource?: MCPAnalyticsModelSource
+  /** The call arguments with SDK-owned `context` and `llm_model` keys removed. */
   args?: Record<string, unknown>
   /** True when `name` is the `get_more_tools` virtual tool. */
   isMissingCapability: boolean
@@ -610,6 +629,10 @@ export interface MissingCapabilityCaptureData extends McpCaptureCommon {
    * on the `get_more_tools` call) → `$mcp_intent`.
    */
   context?: string
+  /** The calling agent's self-reported model id -> `$mcp_llm_model`. */
+  llmModel?: string
+  /** How the model id was obtained -> `$mcp_llm_model_source`. */
+  llmModelSource?: MCPAnalyticsModelSource
   /** Captured call arguments → `$mcp_parameters` (sanitized + truncated). */
   parameters?: unknown
 }

package/src/version.ts

@@ -1 +1 @@
-export const version = '0.12.0'
+export const version = '0.13.1'