@posthog/mcp 0.18.1 → 0.20.0

package/src/extensions/tool-input.ts

@@ -0,0 +1,92 @@
+import type { InputAliasMap, JsonRecord, ShouldRecordInputKeyFn, ToolInputOptions } from '../types'
+import { PostHogMCPAnalyticsProperty } from './constants'
+import { getObjectShape, isZodRawShapeCompat, unwrapInputSchema } from './mcp-sdk-compat'
+
+const MAX_INPUT_KEYS = 20
+const MAX_KEY_LENGTH = 64
+const ANALYTICS_KEYS = new Set(['context', 'llm_model', 'conversation_id'])
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function declaredProperties(schema: unknown): Record<string, unknown> | undefined {
+  if (!isRecord(schema)) return undefined
+  const properties = schema.properties
+  if (isZodRawShapeCompat(schema)) return schema
+  return getObjectShape(unwrapInputSchema(schema)) ?? (isRecord(properties) ? properties : undefined)
+}
+
+const recordDeclaredOnly: ShouldRecordInputKeyFn = (_key, { declared }) => declared
+
+function shouldRecord(fn: ShouldRecordInputKeyFn, key: string, declared: boolean): boolean {
+  try {
+    return fn(key, { declared }) === true
+  } catch {
+    return false
+  }
+}
+
+function aliasNames(aliases: InputAliasMap | undefined): string[] {
+  if (!isRecord(aliases)) return []
+  return Object.values(aliases).flatMap((names) =>
+    Array.isArray(names) ? names.filter((name): name is string => typeof name === 'string') : []
+  )
+}
+
+/**
+ * Each alias the server needed: the canonical name is absent and this is the first of its
+ * aliases present, the same order a normalizer that fills the canonical from its aliases uses.
+ */
+function describeAliasesUsed(aliases: InputAliasMap | undefined, input: Record<string, unknown>): string[] {
+  if (!isRecord(aliases)) return []
+  const used: string[] = []
+  for (const [canonical, names] of Object.entries(aliases)) {
+    if (!Array.isArray(names) || Object.prototype.hasOwnProperty.call(input, canonical)) continue
+    const alias = names.find((name) => typeof name === 'string' && Object.prototype.hasOwnProperty.call(input, name))
+    if (alias && alias.length <= MAX_KEY_LENGTH && canonical.length <= MAX_KEY_LENGTH) {
+      used.push(`${alias}:${canonical}`)
+    }
+  }
+  return used.sort().slice(0, MAX_INPUT_KEYS)
+}
+
+/**
+ * Describe the original arguments without reading their values.
+ * Pass a server-owned JSON Schema or Zod object schema, never a schema from the caller.
+ * By default unknown names become `[redacted]` because an argument name can contain private data;
+ * `shouldRecordInputKey` replaces that rule.
+ */
+export function getToolInputProperties(input: unknown, inputSchema?: unknown, options?: ToolInputOptions): JsonRecord {
+  try {
+    if (!isRecord(input)) return {}
+    const prototype = Object.getPrototypeOf(input)
+    if (prototype !== null && prototype !== Object.prototype) return {}
+    const properties = declaredProperties(inputSchema)
+    const known = new Set([...Object.keys(properties ?? {}), ...aliasNames(options?.inputAliases)])
+    const keys = Object.keys(input).filter((key) => known.has(key) || !ANALYTICS_KEYS.has(key))
+    const record = options?.shouldRecordInputKey ?? recordDeclaredOnly
+    const declared: string[] = []
+    const undeclared: string[] = []
+    let hasRedacted = false
+    for (const key of keys) {
+      const isDeclared = known.has(key)
+      if (key.length <= MAX_KEY_LENGTH && shouldRecord(record, key, isDeclared)) {
+        ;(isDeclared ? declared : undeclared).push(key)
+      } else {
+        hasRedacted = true
+      }
+    }
+    const visibleKeys = [...declared.sort(), ...undeclared.sort()].slice(0, MAX_INPUT_KEYS)
+    if (hasRedacted && visibleKeys.length < MAX_INPUT_KEYS) {
+      visibleKeys.push('[redacted]')
+    }
+    const aliasesUsed = describeAliasesUsed(options?.inputAliases, input)
+    return {
+      [PostHogMCPAnalyticsProperty.InputKeys]: visibleKeys,
+      ...(aliasesUsed.length > 0 ? { [PostHogMCPAnalyticsProperty.InputAliasesUsed]: aliasesUsed } : {}),
+    }
+  } catch {
+    return {}
+  }
+}

package/src/index.ts

@@ -7,7 +7,7 @@ import type { PostHog } from 'posthog-node'
 import { isCompatibleServerType, isHighLevelServer } from './extensions/compatibility'
 import { McpEventSink } from './extensions/sink'
 import { MCPAnalyticsEventType } from './extensions/event-types'
-import { IdentityCache, getServerTrackingData, setServerTrackingData } from './extensions/internal'
+import { BoundedCache, IdentityCache, getServerTrackingData, setServerTrackingData } from './extensions/internal'
 import { createLogger } from './extensions/logger'
 import { captureEvent } from './extensions/capture'
 import { applyMcpLibIdentity } from './extensions/lib-identity'
@@ -161,6 +161,7 @@ function buildTrackingData(
     toolAnalyticsParameterOwnership: new Map(),
     toolCategories: new Map<string, string>(),
     toolDescriptions: new Map<string, string>(),
+    toolInputSchemas: new BoundedCache(),
     sessionInfo: getSessionInfo(lowLevelServer, undefined),
     options: {
       ...DEFAULT_OPTIONS,
@@ -230,6 +231,7 @@ export {
 // Host callbacks receive the SDK's `extra`/`ctx` unchanged, and the two SDK
 // majors carry HTTP headers in different places and shapes. This reads either.
 export { getRequestHeaders } from './extensions/request-headers'
+export { getToolInputProperties } from './extensions/tool-input'
 export { PostHogMCP, type PostHogMCPOptions } from './extensions/posthog-mcp'
 export { getMoreToolsResult } from './extensions/tools'
 export { sendFeedbackResult, SEND_FEEDBACK_TOOL_NAME } from './extensions/feedback'
@@ -249,6 +251,7 @@ export type {
   CaptureEventData,
   CollectFeedbackConfig,
   InitializeCaptureData,
+  InputAliasMap,
   McpAnalytics,
   McpCaptureCommon,
   MCPAnalyticsContextOptions,
@@ -262,7 +265,9 @@ export type {
   PrepareToolCallOptions,
   PrepareToolListOptions,
   RequestHeaderBag,
+  ShouldRecordInputKeyFn,
   ToolCallCaptureData,
+  ToolInputOptions,
   ToolsListCaptureData,
   UserIdentity,
 } from './types'

package/src/types.ts

@@ -6,7 +6,7 @@
 import type { ErrorTracking } from '@posthog/core'
 import type { AnalyticsInjectableJsonSchema } from './extensions/analytics-parameters'
 import type { MCPAnalyticsEventType } from './extensions/event-types'
-import type { IdentityCache } from './extensions/internal'
+import type { BoundedCache, IdentityCache } from './extensions/internal'
 import type { PostHogCaptureEvent } from './extensions/posthog-events'
 import type { McpEventSink } from './extensions/sink'
 import type { LoggerFn } from './extensions/logger'
@@ -186,6 +186,19 @@ export interface MCPAnalyticsOptions {
    * suppress specific events. A throw drops that event.
    */
   beforeSend?: BeforeSendFn
+  /**
+   * Decide which argument names `$mcp_input_keys` records on tool-call events.
+   * By default only names the tool's input schema declares are recorded; every
+   * other name becomes one `[redacted]` entry, because a name can carry private data.
+   */
+  shouldRecordInputKey?: ShouldRecordInputKeyFn
+  /**
+   * Return the alternative argument names accepted by one tool. The map is
+   * canonical name to aliases in the order the server tries them. Automatic
+   * instrumentation uses it for `$mcp_input_keys` and
+   * `$mcp_input_aliases_used`; it never changes the tool arguments.
+   */
+  resolveInputAliases?: (toolName: string) => InputAliasMap | undefined
   /**
    * Attach extra event properties on every auto-captured event. Spread into the PostHog
    * event properties as-is; values must be JSON-serializable.
@@ -304,6 +317,30 @@ export type RegisteredTool = {
  */
 export type BeforeSendFn = (event: PostHogCaptureEvent) => MaybePromise<PostHogCaptureEvent | null | undefined>
 
+/**
+ * Decides whether one top-level argument name appears in `$mcp_input_keys`.
+ * `declared` is true when the server's input schema declares the name.
+ * Return `true` to record the name; any other result, or a throw, records `[redacted]`.
+ */
+export type ShouldRecordInputKeyFn = (key: string, details: { declared: boolean }) => boolean
+
+export interface ToolInputOptions {
+  /**
+   * Replace the default rule, which records only declared names. The SDK still
+   * drops names longer than 64 characters and records at most 20 names.
+   */
+  shouldRecordInputKey?: ShouldRecordInputKeyFn
+  /**
+   * The alternative argument names the server accepts, as canonical name to aliases in the
+   * order the server tries them, for example `{ id: ['experimentId'] }`. Must be owned by the
+   * server, never taken from the caller. Alias names count as declared in `$mcp_input_keys`,
+   * and `$mcp_input_aliases_used` records each alias the server needed, as `alias:canonical`.
+   */
+  inputAliases?: InputAliasMap
+}
+
+export type InputAliasMap = Readonly<Record<string, readonly string[]>>
+
 export interface Event {
   actorId?: string
   clientName?: string
@@ -515,6 +552,7 @@ export interface MCPAnalyticsData {
   toolAnalyticsParameterOwnership: Map<string, AnalyticsParameterOwnership>
   toolCategories: Map<string, string>
   toolDescriptions: Map<string, string>
+  toolInputSchemas: BoundedCache<Map<string, unknown>>
 }
 
 export interface CaptureEventData {

package/src/version.ts

@@ -1 +1 @@
-export const version = '0.18.1'
+export const version = '0.20.0'