@posthog/mcp 0.0.9 → 0.1.17

package/src/extensions/sink.ts

@@ -0,0 +1,130 @@
+import type { PostHog } from 'posthog-node'
+import { uuidv7 } from '@posthog/core'
+
+import type { BeforeSendFn, Event, McpEvent } from '../types'
+import { log } from './logger'
+import { type PostHogCaptureEvent, buildPostHogCaptureEvents } from './posthog-events'
+import { newPrefixedId } from './ids'
+import { sanitizeEvent } from './sanitization'
+import { truncateEvent } from './truncation'
+
+/** Per-event toggles consulted by the sink when fanning out an event. */
+export interface McpCaptureOptions {
+  enableExceptionAutocapture: boolean
+  /** Inspect/modify/drop hook applied to each fanned-out payload before capture. */
+  beforeSend?: BeforeSendFn
+}
+
+/**
+ * Runs an MCP event through the full transform: sanitize → truncate → fan out
+ * into the `$mcp_*` / `$exception` capture payloads → `beforeSend`. Returns
+ * `null` (and logs) if a transform stage throws, so the event is dropped rather
+ * than partially sent. Individual payloads dropped by `beforeSend` are filtered
+ * out of the returned `captures`.
+ *
+ * This is the single source of truth for the pipeline — both {@link McpEventSink}
+ * and the test harness call it, so tests assert on exactly the payloads that
+ * reach `posthog.capture()`.
+ */
+export async function processMcpEvent(
+  event: McpEvent,
+  options: McpCaptureOptions
+): Promise<{ event: Event; captures: PostHogCaptureEvent[] } | null> {
+  let processed: McpEvent = event
+
+  try {
+    processed = sanitizeEvent(processed)
+  } catch (err) {
+    log(`Failed to sanitize event: ${err}`)
+    return null
+  }
+
+  try {
+    processed = truncateEvent(processed)
+  } catch (err) {
+    log(`Failed to truncate event: ${err}`)
+    return null
+  }
+
+  processed.id = processed.id || newPrefixedId('evt')
+  const fullEvent = processed as Event
+
+  const built = buildPostHogCaptureEvents(fullEvent, {
+    enableExceptionAutocapture: options.enableExceptionAutocapture,
+  })
+
+  const captures = await applyBeforeSend(built, options.beforeSend)
+
+  return { event: fullEvent, captures }
+}
+
+/**
+ * Runs each payload through `beforeSend`, keeping those it returns and dropping
+ * those it nullifies or throws on. No-op (identity) when no hook is configured.
+ */
+async function applyBeforeSend(
+  captures: PostHogCaptureEvent[],
+  beforeSend: BeforeSendFn | undefined
+): Promise<PostHogCaptureEvent[]> {
+  if (!beforeSend) {
+    return captures
+  }
+
+  const kept: PostHogCaptureEvent[] = []
+  for (const capture of captures) {
+    try {
+      const result = await beforeSend(capture)
+      if (result) {
+        kept.push(result)
+      }
+    } catch (err) {
+      log(`beforeSend threw for event ${capture.event}; dropping it: ${err}`)
+    }
+  }
+  return kept
+}
+
+/**
+ * Wraps a user-supplied `posthog-node` client. Runs every MCP event through the
+ * sanitize → truncate pipeline, fans it out into the `$mcp_*` / `$exception`
+ * events, applies `beforeSend`, and hands each to `posthog.capture()`.
+ *
+ * The SDK does not own the client lifecycle — the host application constructs
+ * the `PostHog` instance and is responsible for `shutdown()` (matching
+ * `@posthog/ai`).
+ */
+export class McpEventSink {
+  constructor(private readonly posthog: PostHog) {}
+
+  /**
+   * Push an MCP event through the pipeline (sanitize → truncate → fan out →
+   * beforeSend → capture). Errors at any stage are logged and the event is
+   * dropped, never re-thrown into tool code.
+   */
+  async capture(event: McpEvent, options: McpCaptureOptions): Promise<void> {
+    const result = await processMcpEvent(event, options)
+    if (!result) {
+      return
+    }
+
+    const { event: fullEvent, captures } = result
+    try {
+      for (const captureEvent of captures) {
+        this.posthog.capture({
+          distinctId: captureEvent.distinct_id,
+          event: captureEvent.event,
+          properties: captureEvent.properties,
+          timestamp: new Date(captureEvent.timestamp),
+          uuid: uuidv7(),
+        })
+      }
+      log(
+        `Captured PostHog event ${fullEvent.id} | ${fullEvent.eventType} | ${fullEvent.duration} ms | ${
+          fullEvent.identifyActorGivenId || 'anonymous'
+        }`
+      )
+    } catch (err) {
+      log(`Failed to capture PostHog event ${fullEvent.id}: ${err}`)
+    }
+  }
+}

package/src/extensions/tools.ts

@@ -0,0 +1,50 @@
+import { type CallToolResult, type ListToolsResult } from '@modelcontextprotocol/sdk/types.js'
+import { log } from './logger'
+
+export const GET_MORE_TOOLS_NAME = 'get_more_tools' as const
+
+type ReportMissingToolDescriptor = ListToolsResult['tools'][number]
+
+export function getReportMissingToolDescriptor(): ReportMissingToolDescriptor {
+  return {
+    name: GET_MORE_TOOLS_NAME,
+    description:
+      'Check for additional tools whenever your task might benefit from specialized capabilities - even if existing tools could work as a fallback.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        context: {
+          type: 'string',
+          description: 'A description of your goal and what kind of tool would help accomplish it.',
+        },
+      },
+      required: ['context'],
+    },
+    annotations: {
+      title: 'Get More Tools',
+      // Doesn't mutate state on the MCP server
+      readOnlyHint: true,
+      // Interacts with external entities because we store this in analytics
+      openWorldHint: true,
+      // A tool like `get_more_tools` would usually NOT be idempontent, but since we are
+      // only using this to keep track of missing tools/feedback/analytics, it is actually idempontent.
+      // It's also preferable to track it as idempontent to make agents more prone to call it proactively.
+      idempotentHint: true,
+      // Never deletes any data from the MCP server
+      destructiveHint: false,
+    },
+  }
+}
+
+export function handleReportMissing(args: { context: string }): CallToolResult {
+  log(`Missing tool reported: ${JSON.stringify(args)}`)
+
+  return {
+    content: [
+      {
+        type: 'text' as const,
+        text: 'Unfortunately, we have shown you the full tool list. We have noted your feedback and will work to improve the tool list in the future.',
+      },
+    ],
+  }
+}

package/src/extensions/tracing-helpers.ts

@@ -0,0 +1,51 @@
+import type { CompatibleRequestHandlerExtra, MCPAnalyticsData, MCPRequestLike, McpEvent } from '../types'
+import { resolveEventProperties } from './internal'
+
+/**
+ * Helpers shared by the low-level (`instrument-lowlevel.ts`) and high-level
+ * (`instrument-highlevel.ts`) MCP server wrappers. Extracted so both paths stay in sync — any change to
+ * "what counts as an error result", "how do we resolve customer event
+ * properties", "where do we find the context argument", or "how do we measure
+ * duration" needs to land in one place.
+ */
+
+/**
+ * MCP tool results signal errors by setting `isError: true` on the result
+ * object rather than throwing. Detect that consistently.
+ */
+export function isToolResultError(result: unknown): boolean {
+  return !!result && typeof result === 'object' && 'isError' in result && result.isError === true
+}
+
+/**
+ * Resolves the `eventProperties` callback (if configured) and stamps the
+ * result onto the event. No-op when the callback is absent or returns nullish.
+ */
+export async function applyResolvedMetadata(
+  event: McpEvent,
+  data: MCPAnalyticsData,
+  request: MCPRequestLike,
+  extra?: CompatibleRequestHandlerExtra
+): Promise<void> {
+  const resolvedProperties = await resolveEventProperties(data, request, extra)
+  if (resolvedProperties) {
+    event.properties = resolvedProperties
+  }
+}
+
+/**
+ * Reads the SDK-injected `context` argument off a tool-call request. Returns
+ * the trimmed string when present, otherwise `undefined`.
+ */
+export function getContextArgument(request: MCPRequestLike): string | undefined {
+  const context = request.params?.arguments?.context
+  return typeof context === 'string' ? context : undefined
+}
+
+/**
+ * Wall-clock duration of a tracked operation in milliseconds, from `event.timestamp`
+ * to now. Returns `0` when timestamp is missing so callers don't have to null-check.
+ */
+export function getEventDuration(event: McpEvent): number {
+  return event.timestamp ? Date.now() - event.timestamp.getTime() : 0
+}

package/src/extensions/truncation.ts

@@ -0,0 +1,453 @@
+import type { ErrorProperties, Event, StackFrame, McpEvent } from '../types'
+
+// --- Constants ---
+export const MAX_DEPTH = 10
+export const MAX_BREADTH = 100
+export const MAX_STRING_LENGTH = 32_768 // 32KB
+export const MAX_EVENT_BYTES = 102_400 // 100KB
+
+// --- Field-level limit constants ---
+const MAX_USER_INTENT_LENGTH = 2048
+const MAX_ERROR_MESSAGE_LENGTH = 2048
+const MAX_RESOURCE_NAME_LENGTH = 256
+const MAX_METADATA_LENGTH = 256
+const MAX_STACK_FRAMES = 50
+const MAX_CONTENT_TEXT_LENGTH = 32_768
+
+// --- Truncation markers ---
+const TRUNCATION_SUFFIX = '...'
+
+type MutableEvent = Partial<Event | McpEvent> & Record<string, unknown>
+type MutableRecord = Record<string, unknown>
+
+/**
+ * Recursively normalizes a value, handling:
+ * - String truncation (> MAX_STRING_LENGTH)
+ * - Non-serializable values (functions, symbols, undefined, BigInt, NaN, Infinity)
+ * - Date objects -> ISO string
+ * - Circular reference detection
+ * - Depth limiting
+ * - Breadth limiting
+ */
+export function normalize(
+  input: unknown,
+  depth: number = MAX_DEPTH,
+  maxBreadth: number = MAX_BREADTH,
+  maxStringLength: number = MAX_STRING_LENGTH
+): unknown {
+  const memo = new WeakSet<object>()
+  return visit(input, depth, maxBreadth, maxStringLength, memo)
+}
+
+function visit(
+  value: unknown,
+  remainingDepth: number,
+  maxBreadth: number,
+  maxStringLength: number,
+  memo: WeakSet<object>
+): unknown {
+  // null
+  if (value === null) {
+    return null
+  }
+
+  // undefined
+  if (value === undefined) {
+    return '[undefined]'
+  }
+
+  // boolean
+  if (typeof value === 'boolean') {
+    return value
+  }
+
+  // number (including NaN, Infinity)
+  if (typeof value === 'number') {
+    if (Number.isNaN(value)) {
+      return '[NaN]'
+    }
+    if (!Number.isFinite(value)) {
+      return value > 0 ? '[Infinity]' : '[-Infinity]'
+    }
+    return value
+  }
+
+  // bigint
+  if (typeof value === 'bigint') {
+    return `[BigInt: ${value}]`
+  }
+
+  // string
+  if (typeof value === 'string') {
+    if (value.length > maxStringLength) {
+      return value.slice(0, maxStringLength) + TRUNCATION_SUFFIX
+    }
+    return value
+  }
+
+  // symbol
+  if (typeof value === 'symbol') {
+    const desc = value.description
+    return desc ? `[Symbol(${desc})]` : '[Symbol()]'
+  }
+
+  // function
+  if (typeof value === 'function') {
+    const name = value.name || '<anonymous>'
+    return `[Function: ${name}]`
+  }
+
+  // Date
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? '[Invalid Date]' : value.toISOString()
+  }
+
+  // Objects and arrays from here — need depth/breadth/circular checks
+  if (typeof value === 'object') {
+    // Circular reference detection
+    if (memo.has(value)) {
+      return '[Circular ~]'
+    }
+
+    // Depth limit
+    if (remainingDepth <= 0) {
+      return Array.isArray(value) ? '[Array]' : '[Object]'
+    }
+
+    memo.add(value)
+
+    let result: unknown
+    if (Array.isArray(value)) {
+      result = visitArray(value, remainingDepth - 1, maxBreadth, maxStringLength, memo)
+    } else {
+      result = visitObject(value as Record<string, unknown>, remainingDepth - 1, maxBreadth, maxStringLength, memo)
+    }
+
+    memo.delete(value)
+    return result
+  }
+
+  // Fallback: coerce to string
+  return String(value)
+}
+
+function visitArray(
+  arr: unknown[],
+  remainingDepth: number,
+  maxBreadth: number,
+  maxStringLength: number,
+  memo: WeakSet<object>
+): unknown[] {
+  const result: unknown[] = []
+  for (let i = 0; i < arr.length; i++) {
+    if (i >= maxBreadth) {
+      result.push('[MaxProperties ~]')
+      break
+    }
+    result.push(visit(arr[i], remainingDepth, maxBreadth, maxStringLength, memo))
+  }
+  return result
+}
+
+function visitObject(
+  obj: Record<string, unknown>,
+  remainingDepth: number,
+  maxBreadth: number,
+  maxStringLength: number,
+  memo: WeakSet<object>
+): Record<string, unknown> {
+  const result: Record<string, unknown> = {}
+  const keys = Object.keys(obj)
+  let count = 0
+
+  for (const key of keys) {
+    if (count >= maxBreadth) {
+      result['...'] = '[MaxProperties ~]'
+      break
+    }
+    // Skip undefined values — matches JSON.stringify behavior (omits undefined properties)
+    if (obj[key] === undefined) {
+      continue
+    }
+    result[key] = visit(obj[key], remainingDepth, maxBreadth, maxStringLength, memo)
+    count++
+  }
+
+  return result
+}
+
+// --- Field-level truncation helpers ---
+
+function truncateString(str: string | undefined, maxLength: number): string | undefined {
+  if (str == null) {
+    return str
+  }
+  if (str.length <= maxLength) {
+    return str
+  }
+  return str.slice(0, maxLength) + TRUNCATION_SUFFIX
+}
+
+function truncateStackFrames(frames: StackFrame[] | undefined): StackFrame[] | undefined {
+  if (!frames || frames.length <= MAX_STACK_FRAMES) {
+    return frames
+  }
+  const half = Math.floor(MAX_STACK_FRAMES / 2)
+  return [...frames.slice(0, half), ...frames.slice(-half)]
+}
+
+/**
+ * Bounds an `ErrorProperties` payload: truncates each exception's `value`
+ * (message) and caps its stack frames. Operates on the core `$exception_list`
+ * shape produced by `captureException`.
+ */
+function truncateExceptionList(error: ErrorProperties): ErrorProperties {
+  if (!Array.isArray(error.$exception_list)) {
+    return error
+  }
+  return {
+    ...error,
+    $exception_list: error.$exception_list.map((exception) => {
+      const next = { ...exception }
+      if (typeof next.value === 'string') {
+        next.value = truncateString(next.value, MAX_ERROR_MESSAGE_LENGTH)
+      }
+      if (next.stacktrace?.frames) {
+        next.stacktrace = { ...next.stacktrace, frames: truncateStackFrames(next.stacktrace.frames) }
+      }
+      return next
+    }),
+  }
+}
+
+function truncateResponseContent(response: unknown): unknown {
+  if (response == null || typeof response !== 'object') {
+    return response
+  }
+  const result: MutableRecord = { ...(response as MutableRecord) }
+  if (Array.isArray(result.content)) {
+    result.content = result.content.map((block: unknown) => {
+      if (
+        block != null &&
+        typeof block === 'object' &&
+        'type' in block &&
+        'text' in block &&
+        block?.type === 'text' &&
+        typeof block.text === 'string' &&
+        block.text.length > MAX_CONTENT_TEXT_LENGTH
+      ) {
+        return {
+          ...(block as MutableRecord),
+          text: block.text.slice(0, MAX_CONTENT_TEXT_LENGTH) + TRUNCATION_SUFFIX,
+        }
+      }
+      return block
+    })
+  }
+  return result
+}
+
+/**
+ * Calculates the UTF-8 byte size of a JSON-serialized value.
+ */
+const textEncoder = new TextEncoder()
+
+function jsonByteSize(value: unknown): number {
+  return textEncoder.encode(JSON.stringify(value)).length
+}
+
+/**
+ * Finds and truncates the largest string values in an object to fit within a byte budget.
+ * Last-resort mechanism when depth reduction alone isn't enough.
+ * Iterates until the result fits or no further reduction is possible.
+ */
+function truncateLargestFields<T>(obj: T, maxBytes: number): T {
+  const result = structuredClone(obj)
+
+  for (let attempt = 0; attempt < 10; attempt++) {
+    const currentSize = jsonByteSize(result)
+    if (currentSize <= maxBytes) {
+      return result
+    }
+
+    const excess = currentSize - maxBytes
+
+    // Find all string values and their sizes, sorted largest first
+    const stringPaths: Array<{ path: string[]; length: number }> = []
+    collectStringPaths(result, [], stringPaths)
+    stringPaths.sort((a, b) => b.length - a.length)
+
+    if (stringPaths.length === 0) {
+      break // no strings left to truncate
+    }
+
+    // Distribute the reduction across the largest strings
+    let remaining = excess + 200 // buffer for JSON overhead from added "..." suffixes
+    let truncated = false
+
+    for (const { path, length } of stringPaths) {
+      if (remaining <= 0) {
+        break
+      }
+      const reduction = Math.min(remaining, Math.floor(length * 0.5))
+      if (reduction < 10) {
+        continue // not worth truncating tiny strings
+      }
+      const newLength = length - reduction
+      const currentValue = getNestedValue(result, path)
+      if (typeof currentValue !== 'string') {
+        continue
+      }
+      setNestedValue(result, path, currentValue.slice(0, newLength) + TRUNCATION_SUFFIX)
+      remaining -= reduction
+      truncated = true
+    }
+
+    if (!truncated) {
+      break // no progress possible
+    }
+  }
+
+  return result
+}
+
+function collectStringPaths(
+  obj: unknown,
+  currentPath: string[],
+  results: Array<{ path: string[]; length: number }>
+): void {
+  if (typeof obj === 'string' && obj.length > 100) {
+    results.push({ path: [...currentPath], length: obj.length })
+    return
+  }
+  if (Array.isArray(obj)) {
+    for (const [i, item] of obj.entries()) {
+      collectStringPaths(item, [...currentPath, String(i)], results)
+    }
+    return
+  }
+  if (obj != null && typeof obj === 'object') {
+    for (const [key, value] of Object.entries(obj)) {
+      collectStringPaths(value, [...currentPath, key], results)
+    }
+  }
+}
+
+function getNestedValue(obj: unknown, path: string[]): unknown {
+  let current: unknown = obj
+  for (const key of path) {
+    if (current == null || typeof current !== 'object') {
+      return
+    }
+    current = (current as MutableRecord)[key]
+  }
+  return current
+}
+
+function setNestedValue(obj: unknown, path: string[], value: unknown): void {
+  let current: unknown = obj
+  for (let i = 0; i < path.length - 1; i++) {
+    if (current == null || typeof current !== 'object') {
+      return
+    }
+    current = (current as MutableRecord)[path[i]]
+  }
+  const finalKey = path.at(-1)
+  if (finalKey !== undefined && current != null && typeof current === 'object') {
+    ;(current as MutableRecord)[finalKey] = value
+  }
+}
+
+/**
+ * Ensures an event fits within MAX_EVENT_BYTES by progressively reducing
+ * normalization depth, then truncating largest string fields as a last resort.
+ */
+function truncateToSize(event: MutableEvent): MutableEvent {
+  // Check if already within budget
+  if (jsonByteSize(event) <= MAX_EVENT_BYTES) {
+    return event
+  }
+
+  // Progressive depth reduction
+  for (let depth = MAX_DEPTH - 1; depth >= 1; depth--) {
+    const reduced: MutableEvent = { ...event }
+    if (reduced.parameters != null) {
+      reduced.parameters = normalize(reduced.parameters, depth)
+    }
+    if (reduced.response != null) {
+      reduced.response = normalize(reduced.response, depth)
+    }
+    if (reduced.identifyActorData != null) {
+      reduced.identifyActorData = normalize(reduced.identifyActorData, depth) as Event['identifyActorData']
+    }
+    if (reduced.error != null) {
+      reduced.error = normalize(reduced.error, depth) as Event['error']
+    }
+
+    if (jsonByteSize(reduced) <= MAX_EVENT_BYTES) {
+      return reduced
+    }
+  }
+
+  // Last resort: truncate largest string fields
+  const minimal: MutableEvent = { ...event }
+  if (minimal.parameters != null) {
+    minimal.parameters = normalize(minimal.parameters, 1)
+  }
+  if (minimal.response != null) {
+    minimal.response = normalize(minimal.response, 1)
+  }
+  if (minimal.identifyActorData != null) {
+    minimal.identifyActorData = normalize(minimal.identifyActorData, 1) as Event['identifyActorData']
+  }
+  if (minimal.error != null) {
+    minimal.error = normalize(minimal.error, 1) as Event['error']
+  }
+
+  return truncateLargestFields(minimal, MAX_EVENT_BYTES)
+}
+
+/**
+ * Applies layered truncation to an event:
+ * 1. Field-level string limits (userIntent, resourceName, metadata fields, error.message)
+ * 2. Error frame limiting (first 25 + last 25 if > 50)
+ * 3. Response content text limits (32KB per text block)
+ * 4. Recursive normalization on user-controlled fields
+ * 5. Size-targeted truncation (progressive depth reduction + last-resort string truncation)
+ */
+export function truncateEvent<T extends Event | McpEvent>(event: T): T {
+  const result: MutableEvent = { ...event }
+
+  // Layer 1: Field-level string limits
+  result.userIntent = truncateString(result.userIntent, MAX_USER_INTENT_LENGTH)
+  result.resourceName = truncateString(result.resourceName, MAX_RESOURCE_NAME_LENGTH)
+  result.serverName = truncateString(result.serverName, MAX_METADATA_LENGTH)
+  result.serverVersion = truncateString(result.serverVersion, MAX_METADATA_LENGTH)
+  result.clientName = truncateString(result.clientName, MAX_METADATA_LENGTH)
+  result.clientVersion = truncateString(result.clientVersion, MAX_METADATA_LENGTH)
+
+  // Error field limits — operate on the core `$exception_list` shape
+  if (result.error != null && typeof result.error === 'object') {
+    result.error = truncateExceptionList(result.error as ErrorProperties)
+  }
+
+  // Response content text limits
+  result.response = truncateResponseContent(result.response)
+
+  // Layer 2: Recursive normalization on user-controlled fields
+  if (result.parameters != null) {
+    result.parameters = normalize(result.parameters)
+  }
+  if (result.response != null) {
+    result.response = normalize(result.response)
+  }
+  if (result.identifyActorData != null) {
+    result.identifyActorData = normalize(result.identifyActorData) as Event['identifyActorData']
+  }
+  if (result.error != null) {
+    result.error = normalize(result.error) as Event['error']
+  }
+
+  // Layer 3: Size-targeted normalization
+  return truncateToSize(result) as T
+}