@posthog/mcp 0.10.4 → 0.10.6

package/src/extensions/instrumentation.ts

@@ -28,7 +28,7 @@ import { MCPAnalyticsEventType } from './event-types'
 import { captureException } from './exceptions'
 import { resolveToolCallIntent, setEventIntent, setExplicitContextIntent } from './intent'
 import { getServerTrackingData, handleIdentify, setServerTrackingData } from './internal'
-import { log } from './logger'
+import type { LoggerFn } from './logger'
 import { buildCapturedMcpParameters } from './mcp-payloads'
 import { getLiteralValue, getObjectShape } from './mcp-sdk-compat'
 import { getSessionId, newSessionId } from './session'
@@ -98,13 +98,20 @@ export async function captureToolCall(params: TraceToolCallParams): Promise<unkn
     explicitContextIntent,
     takeCapturedError,
   } = params
-
-  const ownership = getActiveAnalyticsParameterOwnership(data, request.params?.name, parameterOwnership)
+  const resolvedEventType = eventType ?? MCPAnalyticsEventType.mcpToolsCall
+  const ownership = getActiveAnalyticsParameterOwnership(
+    data,
+    request.params?.name,
+    parameterOwnership,
+    resolvedEventType === MCPAnalyticsEventType.mcpMissingCapability
+  )
   const conversation = resolveConversationId(
     ownership.conversationId,
     request.params?.arguments,
     request.params?.name,
-    resolveMissingCapabilityToolName(data.options)
+    resolvedEventType === MCPAnalyticsEventType.mcpMissingCapability
+      ? resolveMissingCapabilityToolName(data.options)
+      : ''
   )
   const downstreamRequest = cloneRequestWithoutOwnedAnalyticsArguments(request, ownership)
 
@@ -120,7 +127,7 @@ export async function captureToolCall(params: TraceToolCallParams): Promise<unkn
     startTime,
     conversation,
     ownership,
-    eventType ?? MCPAnalyticsEventType.mcpToolsCall
+    resolvedEventType
   )
   if (event && explicitContextIntent) {
     setExplicitContextIntent(event, explicitContextIntent)
@@ -130,22 +137,22 @@ export async function captureToolCall(params: TraceToolCallParams): Promise<unkn
   try {
     result = await execute(downstreamRequest)
   } catch (error) {
-    publishFailedToolEvent(server, event, error, startTime, conversation)
+    publishFailedToolEvent(server, event, error, startTime, conversation, data.logger)
     throw error
   }
 
   const finalResult = applyConversationPromptBack(event, result, conversation)
-  publishSuccessfulToolEvent(server, event, finalResult, startTime, takeCapturedError)
+  publishSuccessfulToolEvent(server, event, finalResult, startTime, data.logger, takeCapturedError)
   return finalResult
 }
 
 function getActiveAnalyticsParameterOwnership(
   data: MCPAnalyticsData,
   toolName: string | undefined,
-  override?: AnalyticsParameterOwnership
+  override: AnalyticsParameterOwnership | undefined,
+  isMissingCapabilityTool: boolean
 ): AnalyticsParameterOwnership {
   const ownership = override ?? (toolName ? data.toolAnalyticsParameterOwnership.get(toolName) : undefined)
-  const isMissingCapabilityTool = toolName === resolveMissingCapabilityToolName(data.options)
   return {
     context: !isMissingCapabilityTool && isContextEnabled(data.options.context) && ownership?.context === true,
     conversationId:
@@ -206,7 +213,7 @@ async function prepareToolCallEvent(
     setEventIntent(event, await resolveToolCallIntent(data, request, ownership.context, extra))
     return event
   } catch (error) {
-    log(
+    data.logger(
       `Warning: PostHog MCP analytics instrumentation failed for tool ${request.params?.name}, the tool will still run - ${error}`
     )
     return null
@@ -240,6 +247,7 @@ function publishSuccessfulToolEvent(
   event: McpEvent | null,
   result: unknown,
   startTime: Date,
+  logger: LoggerFn,
   takeCapturedError?: () => unknown
 ): void {
   if (!event) {
@@ -255,9 +263,9 @@ function publishSuccessfulToolEvent(
     }
     event.response = result
     event.duration = Date.now() - startTime.getTime()
-    captureEvent(server, event)
+    captureEvent(server, event, logger)
   } catch (error) {
-    log(`Warning: PostHog MCP analytics failed to publish tool event - ${error}`)
+    logger(`Warning: PostHog MCP analytics failed to publish tool event - ${error}`)
   }
 }
 
@@ -266,7 +274,8 @@ function publishFailedToolEvent(
   event: McpEvent | null,
   error: unknown,
   startTime: Date,
-  conversation: ConversationIdResolution
+  conversation: ConversationIdResolution,
+  logger: LoggerFn
 ): void {
   if (!event) {
     return
@@ -278,9 +287,9 @@ function publishFailedToolEvent(
     event.isError = true
     event.error = captureException(error)
     event.duration = Date.now() - startTime.getTime()
-    captureEvent(server, event)
+    captureEvent(server, event, logger)
   } catch (publishError) {
-    log(`Warning: PostHog MCP analytics failed to publish failed tool event - ${publishError}`)
+    logger(`Warning: PostHog MCP analytics failed to publish failed tool event - ${publishError}`)
   }
 }
 
@@ -305,11 +314,27 @@ export type HandlerPatch = (
  * that register handlers post-construction work — e.g. `@rekog/mcp-nest` hands a
  * bare server to instrument() and only then registers its handlers.
  */
+const originalRequestHandlers = new WeakMap<MCPServerLike, Map<string, MCPRequestHandler>>()
+
+function rememberOriginalRequestHandler(
+  server: MCPServerLike,
+  handlerName: string,
+  originalHandler: MCPRequestHandler
+): void {
+  let handlers = originalRequestHandlers.get(server)
+  if (!handlers) {
+    handlers = new Map()
+    originalRequestHandlers.set(server, handlers)
+  }
+  handlers.set(handlerName, originalHandler)
+}
+
 export function patchRequestHandlers(server: MCPServerLike, patches: Record<string, HandlerPatch>): void {
   // Monkey patch existing handlers.
   for (const [handlerName, patch] of Object.entries(patches)) {
     const originalHandler = server._requestHandlers.get(handlerName)
     if (originalHandler) {
+      rememberOriginalRequestHandler(server, handlerName, originalHandler)
       server._requestHandlers.set(handlerName, (request, extra) => patch(server, originalHandler, request, extra))
     }
   }
@@ -320,14 +345,55 @@ export function patchRequestHandlers(server: MCPServerLike, patches: Record<stri
     const shape = getObjectShape(requestSchema)
     const handlerName = shape?.method ? getLiteralValue(shape.method) : undefined
     const patch = typeof handlerName === 'string' ? patches[handlerName] : undefined
-    if (!patch) {
+    if (!patch || typeof handlerName !== 'string') {
       return originalSetRequestHandler(requestSchema, originalHandler)
     }
 
-    return originalSetRequestHandler(requestSchema, (request, extra) => patch(server, originalHandler, request, extra))
+    // Register first so the MCP SDK's request/result validation stays inside
+    // our analytics wrapper, matching handlers that existed before instrument().
+    const result = originalSetRequestHandler(requestSchema, originalHandler)
+    const registeredHandler = server._requestHandlers.get(handlerName)
+    if (registeredHandler) {
+      rememberOriginalRequestHandler(server, handlerName, registeredHandler)
+      server._requestHandlers.set(handlerName, (request, extra) => patch(server, registeredHandler, request, extra))
+    }
+    return result
   }) as MCPServerLike['setRequestHandler']
 }
 
+/**
+ * Checks the server's raw listing for a real owner of a candidate virtual tool.
+ * This does not depend on a previous client request and does not call the
+ * instrumented list wrapper, so it neither injects PostHog tools nor captures a
+ * synthetic tools/list event. `undefined` fails open to the real dispatcher.
+ */
+export async function isToolAdvertised(
+  server: MCPServerLike,
+  toolName: string,
+  extra: CompatibleRequestHandlerExtra | undefined,
+  logger: LoggerFn
+): Promise<boolean | undefined> {
+  const listHandler = originalRequestHandlers.get(server)?.get('tools/list')
+  if (!listHandler || !server._requestHandlers.has('tools/list')) {
+    return undefined
+  }
+
+  try {
+    const response = (await listHandler({ method: 'tools/list', params: {} }, extra)) as ListToolsResult
+    if (!response || !Array.isArray(response.tools)) {
+      return undefined
+    }
+    // Match the page the current list instrumentation can expose. Pagination
+    // passthrough is handled separately from missing-capability ownership.
+    return response.tools.some((tool) => tool?.name === toolName)
+  } catch (error) {
+    logger(
+      `Warning: PostHog MCP analytics could not determine whether "${toolName}" is advertised; delegating to the server - ${error}`
+    )
+    return undefined
+  }
+}
+
 /**
  * Captures each `tools/list` and injects the SDK-managed tools (context
  * parameter, conversation id, `get_more_tools`) into the returned list.
@@ -336,7 +402,8 @@ export async function handleListToolsRequest(
   server: MCPServerLike,
   originalListToolsHandler: MCPRequestHandler,
   request: MCPRequestLike,
-  extra?: CompatibleRequestHandlerExtra
+  extra: CompatibleRequestHandlerExtra | undefined,
+  logger: LoggerFn
 ): Promise<{ tools: ListToolsResult['tools'] }> {
   const data = getServerTrackingData(server)
   const startTime = new Date()
@@ -352,23 +419,23 @@ export async function handleListToolsRequest(
     await applyResolvedMetadata(event, data, request, extra)
   }
 
-  const tools = await getTracedToolsList(server, originalListToolsHandler, request, extra, event)
+  const tools = await getTracedToolsList(server, originalListToolsHandler, request, extra, event, logger)
 
   if (!data) {
-    log(
+    logger(
       'Warning: PostHog MCP analytics is unable to find server tracking data. Please ensure you have called instrument(server, options) before using tool calls.'
     )
     return { tools }
   }
 
   if (tools.length === 0) {
-    log(
+    data.logger(
       'Warning: No tools found in the original list. This is likely due to the tools not being registered before PostHog MCP analytics.instrument().'
     )
     event.error = captureException('No tools were sent to MCP client.')
     event.isError = true
     event.duration = Date.now() - startTime.getTime()
-    captureEvent(server, event)
+    captureEvent(server, event, data.logger)
     return { tools }
   }
 
@@ -376,7 +443,7 @@ export async function handleListToolsRequest(
   event.listedToolNames = collectListedToolNames(tools)
   event.isError = false
   event.duration = Date.now() - startTime.getTime()
-  captureEvent(server, event)
+  captureEvent(server, event, data.logger)
   return { tools }
 }
 
@@ -405,30 +472,39 @@ async function getTracedToolsList(
   originalListToolsHandler: MCPRequestHandler,
   request: MCPRequestLike,
   extra: CompatibleRequestHandlerExtra | undefined,
-  event: McpEvent
+  event: McpEvent,
+  logger: LoggerFn
 ): Promise<ListToolsResult['tools']> {
   try {
     const data = getServerTrackingData(server)
     const originalResponse = (await originalListToolsHandler(request, extra)) as ListToolsResult
-    let tools = originalResponse.tools || []
+    // Injection must not mutate arrays reused or frozen by the server.
+    let tools = [...(originalResponse.tools || [])]
 
     if (data) {
       cacheToolAnalyticsParameterOwnership(data.toolAnalyticsParameterOwnership, tools)
     }
-
     if (data && isContextEnabled(data.options.context)) {
-      tools = addContextParameterToTools(tools, getContextDescription(data.options.context))
-    }
-
-    if (data?.options.enableConversationId) {
-      tools = addConversationIdToTools(tools, resolveMissingCapabilityToolName(data.options))
+      tools = addContextParameterToTools(tools, getContextDescription(data.options.context), data.logger)
     }
 
-    if (data?.options.reportMissing) {
+    if (data) {
       const missingToolName = resolveMissingCapabilityToolName(data.options)
-      const alreadyPresent = tools.some((tool) => tool?.name === missingToolName)
-      if (!alreadyPresent) {
-        tools.push(getReportMissingToolDescriptor(missingToolName))
+      let injectedMissingCapabilityTool = false
+      if (data.options.reportMissing) {
+        const alreadyPresent = tools.some((tool) => tool?.name === missingToolName)
+        if (alreadyPresent) {
+          data.logger(
+            `Warning: Cannot inject missing-capability tool "${missingToolName}" because a real tool already uses that name. The real tool will not be intercepted.`
+          )
+        } else {
+          tools.push(getReportMissingToolDescriptor(missingToolName))
+          injectedMissingCapabilityTool = true
+        }
+      }
+
+      if (data.options.enableConversationId) {
+        tools = addConversationIdToTools(tools, missingToolName, injectedMissingCapabilityTool, data.logger)
       }
     }
 
@@ -439,13 +515,13 @@ async function getTracedToolsList(
 
     return tools
   } catch (error) {
-    log(
+    logger(
       `Warning: Original list tools handler failed, this suggests an error PostHog MCP analytics did not cause - ${error}`
     )
     event.error = captureException(error)
     event.isError = true
     event.duration = event.timestamp ? Date.now() - event.timestamp.getTime() : 0
-    captureEvent(server, event)
+    captureEvent(server, event, logger)
     throw error
   }
 }
@@ -541,7 +617,7 @@ function mintStatelessSessionOnInitialize(
     setServerTrackingData(server, data)
     return sessionId
   } catch (error) {
-    log(`Warning: PostHog MCP analytics failed to mint a stateless session id - ${error}`)
+    data.logger(`Warning: PostHog MCP analytics failed to mint a stateless session id - ${error}`)
     return undefined
   }
 }
@@ -571,7 +647,7 @@ function upgradeMintedTokenToNegotiated(
     })
     writeSessionIdToTransport(transport, token)
   } catch (error) {
-    log(`Warning: PostHog MCP analytics failed to upgrade the stateless session token - ${error}`)
+    data.logger(`Warning: PostHog MCP analytics failed to upgrade the stateless session token - ${error}`)
   }
 }
 
@@ -599,11 +675,12 @@ export async function handleInitializeRequest(
   server: MCPServerLike,
   originalInitializeHandler: MCPRequestHandler,
   request: MCPRequestLike,
-  extra?: CompatibleRequestHandlerExtra
+  extra: CompatibleRequestHandlerExtra | undefined,
+  logger: LoggerFn
 ): Promise<unknown> {
   const data = getServerTrackingData(server)
   if (!data) {
-    log(
+    logger(
       'Warning: PostHog MCP analytics is unable to find server tracking data. Please ensure you have called instrument(server, options) before using tool calls.'
     )
     return await originalInitializeHandler(request, extra)
@@ -640,7 +717,7 @@ export async function handleInitializeRequest(
   if (mintedSessionId) {
     upgradeMintedTokenToNegotiated(server, data, mintedSessionId, negotiatedProtocolVersion)
   }
-  captureEvent(server, event)
+  captureEvent(server, event, data.logger)
   return result
 }
 

package/src/extensions/intent.ts

@@ -11,7 +11,6 @@ import type {
   McpEvent,
 } from '../types'
 import { isContextEnabled } from './context-parameters'
-import { log } from './logger'
 
 interface ResolvedIntent {
   intent: string
@@ -45,7 +44,7 @@ async function runIntentFallback(
     const intent = normalizeIntent(await data.options.intentFallback(request, extra))
     return intent ? { intent, source: 'inferred' } : null
   } catch (error) {
-    log(`intentFallback callback error: ${error}`)
+    data.logger(`intentFallback callback error: ${error}`)
     return null
   }
 }
@@ -57,12 +56,7 @@ export async function resolveToolCallIntent(
   extra?: CompatibleRequestHandlerExtra
 ): Promise<ResolvedIntent | null> {
   const contextArgument = getContextArgument(request)
-  if (
-    analyticsOwnsContext &&
-    isContextEnabled(data.options.context) &&
-    request.params?.name !== 'get_more_tools' &&
-    contextArgument
-  ) {
+  if (analyticsOwnsContext && isContextEnabled(data.options.context) && contextArgument) {
     return { intent: contextArgument, source: 'context_parameter' }
   }
 

package/src/extensions/internal.ts

@@ -12,7 +12,6 @@ import type {
   UserIdentity,
 } from '../types'
 import { MCPAnalyticsEventType } from './event-types'
-import { log } from './logger'
 import { captureEvent } from './capture'
 import { stampMetaClientInfo } from './client-identity'
 
@@ -169,14 +168,16 @@ export async function handleIdentify(
       data.identifiedSessions.set(sessionId, mergedIdentity)
 
       if (shouldPublish) {
-        log(`Identified session ${sessionId} with identity: ${JSON.stringify(mergedIdentity)}`)
-        captureEvent(server, identifyEvent)
+        data.logger(`Identified session ${sessionId}`)
+        captureEvent(server, identifyEvent, data.logger)
       }
     } else {
-      log(`Warning: Supplied identify function returned null for session ${sessionId}`)
+      data.logger(`Warning: Supplied identify function returned null for session ${sessionId}`)
     }
   } catch (error) {
-    log(`Error: User supplied identify function threw an error while identifying session ${sessionId} - ${error}`)
+    data.logger(
+      `Error: User supplied identify function threw an error while identifying session ${sessionId} - ${error}`
+    )
   }
 }
 
@@ -196,7 +197,7 @@ export async function resolveEventProperties(
   try {
     return (await data.options.eventProperties(request, extra)) ?? null
   } catch (e) {
-    log(`eventProperties callback error: ${e}`)
+    data.logger(`eventProperties callback error: ${e}`)
     return null
   }
 }

package/src/extensions/logger.ts

@@ -8,10 +8,11 @@
  *
  * MCP servers running over the STDIO transport use stdout/stderr to exchange
  * protocol messages, so we cannot use the default `console.log`. We accept a
- * `logger` option on the public API; when omitted, log calls are silently
- * dropped. Errors that affect tracking should still be observable in apps that
- * want them, so the consumer can plug in any function (e.g. `console.error`
- * for non-STDIO transports, a file logger, etc.).
+ * `logger` option on the public API or the legacy logger configured through
+ * `setLogger`; when neither is configured, log calls are silently dropped.
+ * Errors that affect tracking should still be observable in apps that want
+ * them, so the consumer can plug in any function (e.g. `console.error` for
+ * non-STDIO transports, a file logger, etc.).
  */
 export type LoggerFn = (message: string) => void
 
@@ -21,12 +22,26 @@ export function setLogger(logger: LoggerFn | undefined): void {
   activeLogger = logger
 }
 
-export function log(message: string): void {
-  if (activeLogger) {
+function writeLog(logger: LoggerFn | undefined, message: string): void {
+  if (logger) {
     try {
-      activeLogger(message)
+      logger(message)
     } catch {
       // never let logging blow up the tracking pipeline
     }
   }
 }
+
+/**
+ * Creates a safe logger for one instrumented server. A server-specific logger
+ * remains isolated, while an omitted logger preserves the legacy `setLogger`
+ * fallback.
+ */
+export function createLogger(logger: LoggerFn | undefined): LoggerFn {
+  return logger ? (message) => writeLog(logger, message) : log
+}
+
+/** Logs through the legacy module-level logger configured by {@link setLogger}. */
+export function log(message: string): void {
+  writeLog(activeLogger, message)
+}

package/src/extensions/sink.ts

@@ -7,7 +7,7 @@ import type { PostHog } from 'posthog-node'
 import { uuidv7 } from '@posthog/core'
 
 import type { BeforeSendFn, Event, McpEvent } from '../types'
-import { log } from './logger'
+import { log, type LoggerFn } from './logger'
 import { type PostHogCaptureEvent, buildPostHogCaptureEvents } from './posthog-events'
 import { newPrefixedId } from './ids'
 import { sanitizeEvent } from './sanitization'
@@ -33,21 +33,22 @@ export interface McpCaptureOptions {
  */
 export async function processMcpEvent(
   event: McpEvent,
-  options: McpCaptureOptions
+  options: McpCaptureOptions,
+  logger: LoggerFn = log
 ): Promise<{ event: Event; captures: PostHogCaptureEvent[] } | null> {
   let processed: McpEvent = event
 
   try {
     processed = sanitizeEvent(processed)
   } catch (err) {
-    log(`Failed to sanitize event: ${err}`)
+    logger(`Failed to sanitize event: ${err}`)
     return null
   }
 
   try {
     processed = truncateEvent(processed)
   } catch (err) {
-    log(`Failed to truncate event: ${err}`)
+    logger(`Failed to truncate event: ${err}`)
     return null
   }
 
@@ -58,7 +59,7 @@ export async function processMcpEvent(
     enableExceptionAutocapture: options.enableExceptionAutocapture,
   })
 
-  const captures = await applyBeforeSend(built, options.beforeSend)
+  const captures = await applyBeforeSend(built, options.beforeSend, logger)
 
   return { event: fullEvent, captures }
 }
@@ -69,7 +70,8 @@ export async function processMcpEvent(
  */
 async function applyBeforeSend(
   captures: PostHogCaptureEvent[],
-  beforeSend: BeforeSendFn | undefined
+  beforeSend: BeforeSendFn | undefined,
+  logger: LoggerFn
 ): Promise<PostHogCaptureEvent[]> {
   if (!beforeSend) {
     return captures
@@ -83,7 +85,7 @@ async function applyBeforeSend(
         kept.push(result)
       }
     } catch (err) {
-      log(`beforeSend threw for event ${capture.event}; dropping it: ${err}`)
+      logger(`beforeSend threw for event ${capture.event}; dropping it: ${err}`)
     }
   }
   return kept
@@ -99,7 +101,10 @@ async function applyBeforeSend(
  * `@posthog/ai`).
  */
 export class McpEventSink {
-  constructor(private readonly posthog: PostHog) {}
+  constructor(
+    private readonly posthog: PostHog,
+    private readonly logger: LoggerFn = log
+  ) {}
 
   /**
    * Push an MCP event through the pipeline (sanitize → truncate → fan out →
@@ -107,7 +112,7 @@ export class McpEventSink {
    * dropped, never re-thrown into tool code.
    */
   async capture(event: McpEvent, options: McpCaptureOptions): Promise<void> {
-    const result = await processMcpEvent(event, options)
+    const result = await processMcpEvent(event, options, this.logger)
     if (!result) {
       return
     }
@@ -132,13 +137,13 @@ export class McpEventSink {
           uuid: uuidv7(),
         })
       }
-      log(
+      this.logger(
         `Captured PostHog event ${fullEvent.id} | ${fullEvent.eventType} | ${fullEvent.duration} ms | ${
-          fullEvent.identifyActorGivenId || 'anonymous'
+          fullEvent.identifyActorGivenId ? 'identified' : 'anonymous'
         }`
       )
     } catch (err) {
-      log(`Failed to capture PostHog event ${fullEvent.id}: ${err}`)
+      this.logger(`Failed to capture PostHog event ${fullEvent.id}: ${err}`)
     }
   }
 }

package/src/extensions/tools.ts

@@ -4,7 +4,7 @@
 // Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
 import { type CallToolResult, type ListToolsResult } from '@modelcontextprotocol/sdk/types.js'
-import { log } from './logger'
+import { log, type LoggerFn } from './logger'
 
 export const GET_MORE_TOOLS_NAME = 'get_more_tools' as const
 
@@ -67,7 +67,7 @@ export function getMoreToolsResult(): CallToolResult {
   }
 }
 
-export function handleReportMissing(args: { context: string }): CallToolResult {
-  log(`Missing tool reported: ${JSON.stringify(args)}`)
+export function handleReportMissing(args: { context: string }, logger: LoggerFn = log): CallToolResult {
+  logger(`Missing tool reported: ${JSON.stringify(args)}`)
   return getMoreToolsResult()
 }