@posthog/mcp 0.0.9 → 0.1.17

package/src/index.ts

@@ -0,0 +1,174 @@
+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 { log, setLogger } from './extensions/logger'
+import { captureEvent } from './extensions/capture'
+import { deriveSessionIdFromMCPSession, getSessionInfo, newSessionId } from './extensions/session'
+import { instrumentLowLevelServer } from './extensions/instrument-lowlevel'
+import { instrumentHighLevelServer } from './extensions/instrument-highlevel'
+import type {
+  CaptureEventData,
+  HighLevelMCPServerLike,
+  McpAnalytics,
+  MCPAnalyticsData,
+  MCPAnalyticsOptions,
+  MCPServerLike,
+  McpEvent,
+} from './types'
+
+/**
+ * Instruments an MCP server so PostHog auto-captures tool calls, tool listings, initialize
+ * requests, identity, and exceptions. Returns a handle whose `capture()` method records
+ * custom events, so you don't pass the server around after wiring it up.
+ *
+ * **Idempotent per server instance.** Per-server tracking state lives in a module-level
+ * `WeakMap<MCPServerLike, MCPAnalyticsData>` (`internal.ts`); a second `instrument()` call
+ * on the same server reuses it rather than double-wrapping handlers.
+ *
+ * @param server - The MCP server to instrument (low-level `Server` or high-level `McpServer`).
+ * @param posthog - A `posthog-node` client you construct and own (matching `@posthog/ai`); call `posthog.shutdown()` on exit to flush.
+ * @param options - Optional configuration. See `MCPAnalyticsOptions`.
+ *
+ * @example
+ * ```ts
+ * import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
+ * import { PostHog } from "posthog-node"
+ * import { instrument } from "@posthog/mcp"
+ *
+ * const posthog = new PostHog(process.env.POSTHOG_PROJECT_TOKEN, { host: "https://us.i.posthog.com" })
+ * const server = new McpServer({ name: "my-mcp", version: "1.0.0" })
+ * const analytics = instrument(server, posthog)
+ *
+ * await analytics.capture({ event: "feedback_submitted", properties: { rating: 5 } })
+ * ```
+ */
+function instrument(server: unknown, posthog: PostHog, options: MCPAnalyticsOptions = {}): McpAnalytics {
+  try {
+    if (options.logger) {
+      setLogger(options.logger)
+    }
+    if (!posthog) {
+      log('Warning: No PostHog client passed to instrument(). Events will not be sent anywhere.')
+    }
+
+    const validatedServer = isCompatibleServerType(server)
+    const lowLevelServer = getLowLevelServer(validatedServer)
+
+    if (getServerTrackingData(lowLevelServer)) {
+      log('instrument() - Server already instrumented, skipping initialization')
+      return createAnalyticsHandle(lowLevelServer)
+    }
+
+    const sink = posthog ? new McpEventSink(posthog) : undefined
+    const mcpAnalyticsData = buildTrackingData(lowLevelServer, options, sink)
+
+    setServerTrackingData(lowLevelServer, mcpAnalyticsData)
+    setupTrackedServer(validatedServer, lowLevelServer)
+
+    return createAnalyticsHandle(lowLevelServer)
+  } catch (error) {
+    log(`Warning: Failed to instrument server - ${error}`)
+    // Degrade gracefully: a no-op handle so the host app keeps working.
+    return { capture: async () => undefined }
+  }
+}
+
+function createAnalyticsHandle(lowLevelServer: MCPServerLike): McpAnalytics {
+  return {
+    capture: (eventData) => captureCustomEvent(lowLevelServer, eventData),
+  }
+}
+
+function getLowLevelServer(server: MCPServerLike | HighLevelMCPServerLike): MCPServerLike {
+  return isHighLevelServer(server) ? (server as HighLevelMCPServerLike).server : (server as MCPServerLike)
+}
+
+/**
+ * Defaults for the boolean toggles. User options are spread over these, so the
+ * resolved config is the single source of truth — adding a new option can never
+ * be silently dropped by a hand-maintained field list (the bug that left
+ * `enableExceptionAutocapture` dead). Options without a meaningful default (e.g.
+ * `enableExceptionAutocapture`) are left to their read-site fallbacks.
+ */
+const DEFAULT_OPTIONS = {
+  reportMissing: false,
+  enableConversationId: false,
+} satisfies Partial<MCPAnalyticsOptions>
+
+function buildTrackingData(
+  lowLevelServer: MCPServerLike,
+  options: MCPAnalyticsOptions,
+  sink: McpEventSink | undefined
+): MCPAnalyticsData {
+  return {
+    sink,
+    sessionId: newSessionId(),
+    lastActivity: new Date(),
+    identifiedSessions: new IdentityCache(),
+    toolDescriptions: new Map<string, string>(),
+    sessionInfo: getSessionInfo(lowLevelServer, undefined),
+    options: { ...DEFAULT_OPTIONS, ...options },
+    sessionSource: 'generated',
+  }
+}
+
+function setupTrackedServer(
+  validatedServer: MCPServerLike | HighLevelMCPServerLike,
+  lowLevelServer: MCPServerLike
+): void {
+  if (isHighLevelServer(validatedServer)) {
+    const highLevelServer = validatedServer as HighLevelMCPServerLike
+    instrumentHighLevelServer(highLevelServer)
+    return
+  }
+
+  try {
+    instrumentLowLevelServer(lowLevelServer)
+  } catch (error) {
+    log(`Warning: Failed to setup tool call instrumentation - ${error}`)
+  }
+}
+
+async function captureCustomEvent(lowLevelServer: MCPServerLike, eventData: CaptureEventData): Promise<void> {
+  if (!eventData || typeof eventData.event !== 'string' || eventData.event.length === 0) {
+    throw new Error('`capture` requires an `event` name, e.g. analytics.capture({ event: "feedback_submitted" })')
+  }
+
+  const trackingData = getServerTrackingData(lowLevelServer)
+  if (!trackingData) {
+    return
+  }
+
+  const event: McpEvent = {
+    sessionId: trackingData.sessionId,
+    eventType: MCPAnalyticsEventType.custom,
+    eventName: eventData.event,
+    timestamp: new Date(),
+    properties: eventData.properties,
+  }
+
+  // Re-use the same per-server publish path so the event picks up session info,
+  // identity, sdk metadata, etc. Awaited so callers know the event was processed.
+  await captureEvent(lowLevelServer, event)
+  log(`Captured event "${eventData.event}" for session ${trackingData.sessionId}`)
+}
+
+export { deriveSessionIdFromMCPSession }
+export {
+  POSTHOG_MCP_ANALYTICS_SOURCE,
+  PostHogMCPAnalyticsEvent,
+  PostHogMCPAnalyticsProperty,
+} from './extensions/constants'
+export type {
+  BeforeSendFn,
+  CaptureEventData,
+  McpAnalytics,
+  MCPAnalyticsContextOptions,
+  MCPAnalyticsIntentSource,
+  MCPAnalyticsOptions,
+  UserIdentity,
+} from './types'
+export type IdentifyFunction = MCPAnalyticsOptions['identify']
+export { instrument }

package/src/types.ts

@@ -0,0 +1,244 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js'
+import type { ErrorTracking } from '@posthog/core'
+import type { MCPAnalyticsEventType } from './extensions/event-types'
+import type { IdentityCache } from './extensions/internal'
+import type { PostHogCaptureEvent } from './extensions/posthog-events'
+import type { McpEventSink } from './extensions/sink'
+import type { LoggerFn } from './extensions/logger'
+
+export type JsonRecord = Record<string, unknown>
+
+/** PostHog error-tracking properties (`$exception_list`). Re-exported from `@posthog/core`. */
+export type ErrorProperties = ErrorTracking.ErrorProperties
+/** A single parsed stack frame. Re-exported from `@posthog/core`. */
+export type StackFrame = ErrorTracking.StackFrame
+
+export interface MCPRequestParamsLike {
+  arguments?: JsonRecord
+  name?: string
+  [key: string]: unknown
+}
+
+export interface MCPRequestLike {
+  id?: number | string
+  jsonrpc?: string
+  method?: string
+  params?: MCPRequestParamsLike
+  [key: string]: unknown
+}
+
+/** Handle returned by `instrument()` — the analytics surface for an instrumented server. */
+export interface McpAnalytics {
+  /**
+   * Capture a custom event for this server. The `event` name is required and sent
+   * verbatim (a customer event, so it is not `$`-prefixed). Resolves once the event
+   * has been processed. Use for domain-specific actions that aren't auto-captured
+   * (user feedback, workflow milestones, etc).
+   */
+  capture(eventData: CaptureEventData): Promise<void>
+}
+
+export interface MCPAnalyticsOptions {
+  /**
+   * Optional STDIO-safe log sink for SDK-internal warnings. Receives single string messages.
+   * Defaults to a no-op since MCP STDIO transports cannot use console.
+   */
+  logger?: LoggerFn
+  /** Enable the `get_more_tools` virtual tool so agents can report missing functionality. */
+  reportMissing?: boolean
+  /** Enables the `conversation_id` tool parameter + prompt-back loop. */
+  enableConversationId?: boolean
+  /**
+   * Emit a `$exception` event alongside any failed tool call. Defaults to `true`.
+   * Set to `false` if you handle error tracking elsewhere and don't want MCP errors
+   * fanning out into PostHog error tracking.
+   */
+  enableExceptionAutocapture?: boolean
+  /** Inject a required `context` parameter on every tool to capture user intent. */
+  context?: boolean | MCPAnalyticsContextOptions
+  /**
+   * Identify the calling user. Returning a non-null value sets `distinct_id` and `$set`
+   * on subsequent events for the session. Object form is treated as a static identity.
+   */
+  identify?:
+    | ((request: MCPRequestLike, extra?: CompatibleRequestHandlerExtra) => Promise<UserIdentity | null>)
+    | UserIdentity
+    | null
+  /**
+   * Called when a tool is invoked without an explicit `context` argument. Return a short
+   * intent string to record as `$mcp_intent` with `$mcp_intent_source = "inferred"`.
+   */
+  intentFallback?: (
+    request: MCPRequestLike,
+    extra?: CompatibleRequestHandlerExtra
+  ) => MaybePromise<string | null | undefined>
+  /**
+   * Inspect, modify, or drop each event right before it is sent to PostHog
+   * (matching posthog-node's `beforeSend`). Receives the fully-built capture
+   * payload — event name, `distinct_id`, and `properties` — and runs once per
+   * emitted event, including the `$exception` sibling of a failed tool call.
+   *
+   * Return the (possibly mutated) event to send it, or `null`/`undefined` to
+   * drop it. Use this to redact sensitive values, add or remove properties, or
+   * suppress specific events. A throw drops that event.
+   */
+  beforeSend?: BeforeSendFn
+  /**
+   * Attach extra event properties on every auto-captured event. Spread into the PostHog
+   * event properties as-is; values must be JSON-serializable.
+   */
+  eventProperties?: (
+    request: MCPRequestLike,
+    extra?: CompatibleRequestHandlerExtra
+  ) => JsonRecord | null | Promise<JsonRecord | null>
+}
+
+export interface MCPAnalyticsContextOptions {
+  description?: string
+}
+
+export type MaybePromise<T> = T | Promise<T>
+export type MCPAnalyticsIntentSource = 'context_parameter' | 'inferred'
+
+export type ToolCallback =
+  | ((args: unknown, extra: CompatibleRequestHandlerExtra) => CallToolResult | Promise<CallToolResult>)
+  | ((extra: CompatibleRequestHandlerExtra) => CallToolResult | Promise<CallToolResult>)
+
+// RegisteredTool type that supports both MCP SDK 1.23- (callback) and 1.24+ (handler)
+export type RegisteredTool = {
+  description?: string
+  inputSchema?: unknown
+  update?: (...args: unknown[]) => unknown
+} & ({ callback: ToolCallback; handler?: never } | { handler: ToolCallback; callback?: never })
+
+/**
+ * Hook invoked for every event just before it is handed to `posthog.capture()`.
+ * Return the event (optionally mutated) to send it, or a nullish value to drop it.
+ */
+export type BeforeSendFn = (event: PostHogCaptureEvent) => MaybePromise<PostHogCaptureEvent | null | undefined>
+
+export interface Event {
+  actorId?: string
+  clientName?: string
+  clientVersion?: string
+  conversationId?: string
+  duration?: number
+  error?: ErrorProperties | null
+  eventId?: string
+  eventType: MCPAnalyticsEventType
+  groups?: Record<string, string>
+  /**
+   * Explicit PostHog event name. When set (via `capture(server, { event })`) it
+   * overrides the built-in name derived from `eventType`, so callers can emit any
+   * event name. User-supplied names are sent verbatim (not `$`-prefixed).
+   */
+  eventName?: string
+  id: string
+  /** Resolved person properties for the session, written to `$set`. */
+  identifyActorData?: JsonRecord
+  /** Resolved distinct id for the session (from `identify().distinctId`). */
+  identifyActorGivenId?: string
+  ipAddress?: string
+  isError?: boolean
+  listedToolNames?: string[]
+  parameters?: unknown
+  properties?: JsonRecord | null
+  resourceName?: string
+  response?: unknown
+  sdkLanguage?: string
+  sdkVersion?: string
+  serverName?: string
+  serverVersion?: string
+  sessionId: string
+  timestamp: Date
+  toolDescription?: string
+  userIntent?: string
+  userIntentSource?: MCPAnalyticsIntentSource
+}
+
+/** A partially-built MCP event as it flows through the SDK before capture. */
+export type McpEvent = Partial<Event>
+
+export interface CompatibleRequestHandlerExtra {
+  headers?: Record<string, string | string[]>
+  sessionId?: string
+  [key: string]: unknown
+}
+
+export interface ServerClientInfoLike {
+  name?: string
+  version?: string
+}
+
+export interface HighLevelMCPServerLike {
+  _registeredTools: { [name: string]: RegisteredTool }
+  registerTool?(name: string, config: { description?: string; inputSchema?: unknown }, handler: ToolCallback): void
+  server: MCPServerLike
+  tool?(name: string, cb: ToolCallback): void
+  tool?(name: string, paramsSchema: unknown, cb: ToolCallback): void
+  tool?(name: string, description: string, paramsSchema: unknown, cb: ToolCallback): void
+}
+
+export interface MCPServerLike {
+  _requestHandlers: Map<string, (request: MCPRequestLike, extra?: CompatibleRequestHandlerExtra) => Promise<unknown>>
+  _serverInfo?: ServerClientInfoLike
+  getClientVersion(): ServerClientInfoLike | undefined
+  setRequestHandler(
+    schema: unknown,
+    handler: (request: MCPRequestLike, extra?: CompatibleRequestHandlerExtra) => Promise<unknown>
+  ): void
+}
+
+export interface UserIdentity {
+  /**
+   * The person's distinct id (becomes `distinct_id`). Same concept as
+   * posthog-node's `identify({ distinctId })`.
+   */
+  distinctId: string
+  /**
+   * Person properties, written to `$set` (e.g. `{ name, email, plan }`) — the
+   * same `properties` you'd pass to posthog-node's `identify`.
+   */
+  properties?: JsonRecord
+  /**
+   * PostHog group memberships as `{ groupType: groupKey }`. Stamped onto every
+   * event for the session as `$groups`, so callers never hand-write the
+   * `$groups` dollar-key themselves.
+   */
+  groups?: Record<string, string>
+}
+
+export interface SessionInfo {
+  clientName?: string
+  clientVersion?: string
+  identifyActorData?: JsonRecord
+  identifyActorGivenId?: string
+  identifyActorGroups?: Record<string, string>
+  ipAddress?: string
+  sdkLanguage?: string
+  sdkVersion?: string
+  serverName?: string
+  serverVersion?: string
+}
+
+export interface MCPAnalyticsData {
+  sink: McpEventSink | undefined
+  identifiedSessions: IdentityCache
+  lastActivity: Date
+  lastMcpSessionId?: string
+  options: MCPAnalyticsOptions
+  sessionId: string
+  sessionInfo: SessionInfo
+  sessionSource: 'generated' | 'mcp'
+  toolDescriptions: Map<string, string>
+}
+
+export interface CaptureEventData {
+  /**
+   * PostHog event name (required). Sent verbatim — a custom event is a
+   * customer-defined event, so it is NOT `$`-prefixed.
+   */
+  event: string
+  /** Event properties, spread onto the PostHog event. Values must be JSON-serializable. */
+  properties?: JsonRecord
+}

package/src/version.ts

@@ -0,0 +1 @@
+export const version = '0.1.17'