@posthog/mcp 0.10.2 → 0.10.4

package/src/extensions/conversation-id.ts

@@ -4,24 +4,19 @@
 // Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
 import { uuidv7 } from '@posthog/core'
+import {
+  canInjectAnalyticsParameter,
+  hasAnalyticsParameter,
+  type AnalyticsInjectableJsonSchema,
+} from './analytics-parameters'
 import { DEFAULT_CONVERSATION_ID_DESCRIPTION } from './constants'
 import { log } from './logger'
 import { GET_MORE_TOOLS_NAME } from './tools'
 
 export const CONVERSATION_ID_PARAM_NAME = 'conversation_id'
 
-interface JsonSchema {
-  additionalProperties?: boolean
-  allOf?: unknown
-  anyOf?: unknown
-  oneOf?: unknown
-  properties?: Record<string, unknown>
-  required?: string[]
-  type?: string
-}
-
 export interface ConversationIdInjectableTool {
-  inputSchema?: JsonSchema
+  inputSchema?: AnalyticsInjectableJsonSchema
   name?: string
   [key: string]: unknown
 }
@@ -29,17 +24,16 @@ export interface ConversationIdInjectableTool {
 export function addConversationIdToTool<TTool extends ConversationIdInjectableTool>(tool: TTool): TTool {
   const modifiedTool = { ...tool }
   const toolName = tool.name || 'unknown'
-  const schema = modifiedTool.inputSchema as JsonSchema | undefined
-
-  if (schema?.properties?.[CONVERSATION_ID_PARAM_NAME]) {
-    log(
-      `WARN: Tool "${toolName}" already has '${CONVERSATION_ID_PARAM_NAME}' parameter. Skipping conversation_id injection.`
-    )
-    return modifiedTool
-  }
-
-  if (schema?.oneOf || schema?.allOf || schema?.anyOf) {
-    log(`WARN: Tool "${toolName}" has complex schema (oneOf/allOf/anyOf). Skipping conversation_id injection.`)
+  const schema = modifiedTool.inputSchema as AnalyticsInjectableJsonSchema | undefined
+
+  if (!canInjectAnalyticsParameter(schema, CONVERSATION_ID_PARAM_NAME)) {
+    if (hasAnalyticsParameter(schema, CONVERSATION_ID_PARAM_NAME)) {
+      log(
+        `WARN: Tool "${toolName}" already has '${CONVERSATION_ID_PARAM_NAME}' parameter. Skipping conversation_id injection.`
+      )
+    } else {
+      log(`WARN: Tool "${toolName}" has complex schema (oneOf/allOf/anyOf/$ref). Skipping conversation_id injection.`)
+    }
     return modifiedTool
   }
 
@@ -51,9 +45,9 @@ export function addConversationIdToTool<TTool extends ConversationIdInjectableTo
     }
   }
 
-  modifiedTool.inputSchema = JSON.parse(JSON.stringify(modifiedTool.inputSchema)) as JsonSchema
+  modifiedTool.inputSchema = JSON.parse(JSON.stringify(modifiedTool.inputSchema)) as AnalyticsInjectableJsonSchema
 
-  const inputSchema = modifiedTool.inputSchema as JsonSchema
+  const inputSchema = modifiedTool.inputSchema as AnalyticsInjectableJsonSchema
 
   if (!inputSchema.properties) {
     inputSchema.properties = {}
@@ -137,25 +131,6 @@ export function extractConversationId(args: unknown): string | undefined {
   return trimmed.length > 0 ? trimmed : undefined
 }
 
-export function cloneRequestWithoutConversationId<
-  TRequest extends { params?: { arguments?: unknown; [k: string]: unknown } },
->(request: TRequest): TRequest {
-  if (!request.params || typeof request.params !== 'object') {
-    return request
-  }
-  const args = request.params.arguments
-  if (!(args && typeof args === 'object')) {
-    return request
-  }
-  return {
-    ...request,
-    params: {
-      ...request.params,
-      arguments: stripConversationId(args) as typeof request.params.arguments,
-    },
-  }
-}
-
 export function stripConversationId(args: unknown): unknown {
   if (!args || typeof args !== 'object' || !(CONVERSATION_ID_PARAM_NAME in (args as Record<string, unknown>))) {
     return args

package/src/extensions/instrument-highlevel.ts

@@ -11,7 +11,12 @@ import type {
   RegisteredTool,
   ToolCallback,
 } from '../types'
-import { stripConversationId } from './conversation-id'
+import {
+  analyticsOwnsParameter,
+  getAnalyticsParameterOwnership,
+  stripOwnedAnalyticsArguments,
+} from './analytics-parameters'
+import { isContextEnabled } from './context-parameters'
 import { MCPAnalyticsEventType } from './event-types'
 import { getServerTrackingData } from './internal'
 import { log } from './logger'
@@ -78,7 +83,10 @@ function setupListenerToRegisteredTools(server: HighLevelMCPServerLike): void {
               return Reflect.set(target, property, value)
             }
 
-            const nextValue = addTracingToToolCallbackInternal(value, property, server)
+            // The MCP SDK's registry copy is currently stale after update(), but keep this lookup lazy so
+            // ownership follows the current schema once the registry reflects live tool state.
+            const getCurrentInputSchema = () => value.inputSchema
+            const nextValue = addTracingToToolCallbackInternal(value, property, server, getCurrentInputSchema)
 
             if (typeof nextValue.update === 'function') {
               const originalUpdate = nextValue.update
@@ -89,7 +97,8 @@ function setupListenerToRegisteredTools(server: HighLevelMCPServerLike): void {
                     const wrappedTool = addTracingToToolCallbackInternal(
                       { callback: updateObj.callback },
                       property,
-                      server
+                      server,
+                      getCurrentInputSchema
                     )
                     updateObj.callback = getToolFunction(wrappedTool)
                   }
@@ -141,12 +150,12 @@ function setupListenerToRegisteredTools(server: HighLevelMCPServerLike): void {
 function addTracingToToolCallbackInternal(
   tool: RegisteredTool,
   toolName: string,
-  server: HighLevelMCPServerLike
+  server: HighLevelMCPServerLike,
+  getCurrentInputSchema: () => unknown = () => tool.inputSchema
 ): RegisteredTool {
   const originalCallback = getToolFunction(tool)
-  const missingToolName = resolveMissingCapabilityToolName(
-    getServerTrackingData(server.server as MCPServerLike)?.options
-  )
+  const options = getServerTrackingData(server.server as MCPServerLike)?.options
+  const missingToolName = resolveMissingCapabilityToolName(options)
 
   if (wrappedCallbacks.has(originalCallback)) {
     log(`Tool ${toolName} callback already wrapped, skipping re-wrap`)
@@ -170,15 +179,17 @@ function addTracingToToolCallbackInternal(
       extra = params[0] as CompatibleRequestHandlerExtra
     }
 
-    const removeContextFromArgs = (input: unknown): unknown => {
-      if (input && typeof input === 'object' && 'context' in input) {
-        const { context: _context, ...rest } = input
-        return rest
-      }
-      return input
-    }
-
-    const cleanedArgs = toolName === missingToolName ? args : stripConversationId(removeContextFromArgs(args))
+    const inputSchema = getCurrentInputSchema()
+    const cleanedArgs = stripOwnedAnalyticsArguments(args, {
+      context:
+        toolName !== missingToolName &&
+        isContextEnabled(options?.context) &&
+        analyticsOwnsParameter(inputSchema, 'context'),
+      conversationId:
+        toolName !== missingToolName &&
+        options?.enableConversationId === true &&
+        analyticsOwnsParameter(inputSchema, 'conversation_id'),
+    })
 
     try {
       if (cleanedArgs === undefined) {
@@ -209,6 +220,7 @@ function addTracingToToolCallbackInternal(
 }
 
 async function handleToolCallRequest(
+  highLevelServer: HighLevelMCPServerLike,
   server: MCPServerLike,
   originalCallToolHandler: MCPRequestHandler,
   request: MCPRequest,
@@ -235,16 +247,19 @@ async function handleToolCallRequest(
     })
   }
 
-  // The high-level handler re-derives arguments from the original request and
-  // strips the injected params inside the wrapped callback, so we hand it the
-  // original request rather than the conversation-stripped one. Errors thrown
-  // by the tool are stashed on `extra` by the callback wrapper; surface them.
+  const toolName = request.params?.name
+  const registeredTool = toolName ? highLevelServer._registeredTools[toolName] : undefined
+
+  // Strip SDK-owned arguments before the MCP SDK validates the registered Zod
+  // schema. The callback wrapper repeats the ownership-aware cleanup as a
+  // defensive fallback for direct callback invocation.
   return await captureToolCall({
     server,
     data,
     request,
     extra,
-    execute: () => originalCallToolHandler(request, extra),
+    execute: (downstreamRequest) => originalCallToolHandler(downstreamRequest as MCPRequest, extra),
+    parameterOwnership: registeredTool ? getAnalyticsParameterOwnership(registeredTool.inputSchema) : undefined,
     takeCapturedError: () => {
       const captured = extra?.__mcp_analytics_error
       if (extra) {
@@ -264,7 +279,12 @@ export function instrumentHighLevelServer(server: HighLevelMCPServerLike): void
     const handlers = {
       initialize: handleInitializeRequest,
       'tools/list': handleListToolsRequest,
-      'tools/call': handleToolCallRequest,
+      'tools/call': (
+        trackedServer: MCPServerLike,
+        originalHandler: MCPRequestHandler,
+        request: MCPRequest,
+        extra: MCPRequestExtra
+      ) => handleToolCallRequest(server, trackedServer, originalHandler, request, extra),
     }
     patchRequestHandlers(lowLevelServer, handlers)
 

package/src/extensions/instrumentation.ts

@@ -5,6 +5,7 @@
 
 import type { ListToolsResult } from '@modelcontextprotocol/sdk/types.js'
 import type {
+  AnalyticsParameterOwnership,
   CompatibleRequestHandlerExtra,
   MCPAnalyticsData,
   MCPRequestLike,
@@ -12,12 +13,12 @@ import type {
   McpEvent,
   ServerClientInfoLike,
 } from '../types'
+import { getAnalyticsParameterOwnership, stripOwnedAnalyticsArguments } from './analytics-parameters'
 import { addContextParameterToTools, getContextDescription, isContextEnabled } from './context-parameters'
 import {
   addConversationIdToTools,
   type ConversationIdResolution,
   canInjectConversationIdPromptBack,
-  cloneRequestWithoutConversationId,
   injectConversationIdPromptBack,
   resolveConversationId,
 } from './conversation-id'
@@ -45,11 +46,7 @@ import { applyResolvedMetadata, isToolResultError } from './tracing-helpers'
 
 type MCPRequestHandler = (request: MCPRequestLike, extra?: CompatibleRequestHandlerExtra) => Promise<unknown>
 
-/**
- * Runs the underlying tool. Receives the request with the SDK-injected
- * `conversation_id` stripped; an adapter is free to ignore it (the high-level
- * path strips arguments inside the wrapped callback instead).
- */
+/** Runs the underlying tool with SDK-owned analytics arguments removed. */
 type ToolExecutor = (downstreamRequest: MCPRequestLike) => Promise<unknown>
 
 interface TraceToolCallParams {
@@ -58,6 +55,8 @@ interface TraceToolCallParams {
   request: MCPRequestLike
   extra?: CompatibleRequestHandlerExtra
   execute: ToolExecutor
+  /** Optional schema-derived ownership override for adapters with direct registry access. */
+  parameterOwnership?: AnalyticsParameterOwnership
   /**
    * Event type to capture. Defaults to a tool call; the `get_more_tools` virtual
    * tool passes `mcpMissingCapability` so it records a capability gap rather than
@@ -88,15 +87,26 @@ interface TraceToolCallParams {
  * throws, and the tool's own errors are always re-thrown to the caller.
  */
 export async function captureToolCall(params: TraceToolCallParams): Promise<unknown> {
-  const { server, data, request, extra, execute, eventType, explicitContextIntent, takeCapturedError } = params
-
+  const {
+    server,
+    data,
+    request,
+    extra,
+    execute,
+    parameterOwnership,
+    eventType,
+    explicitContextIntent,
+    takeCapturedError,
+  } = params
+
+  const ownership = getActiveAnalyticsParameterOwnership(data, request.params?.name, parameterOwnership)
   const conversation = resolveConversationId(
-    data.options.enableConversationId ?? false,
+    ownership.conversationId,
     request.params?.arguments,
     request.params?.name,
     resolveMissingCapabilityToolName(data.options)
   )
-  const downstreamRequest = conversation.conversationId ? cloneRequestWithoutConversationId(request) : request
+  const downstreamRequest = cloneRequestWithoutOwnedAnalyticsArguments(request, ownership)
 
   // Prepare the event in isolation: if identity/metadata/intent resolution
   // throws, we drop instrumentation for this call but still run the tool.
@@ -109,6 +119,7 @@ export async function captureToolCall(params: TraceToolCallParams): Promise<unkn
     extra,
     startTime,
     conversation,
+    ownership,
     eventType ?? MCPAnalyticsEventType.mcpToolsCall
   )
   if (event && explicitContextIntent) {
@@ -128,6 +139,38 @@ export async function captureToolCall(params: TraceToolCallParams): Promise<unkn
   return finalResult
 }
 
+function getActiveAnalyticsParameterOwnership(
+  data: MCPAnalyticsData,
+  toolName: string | undefined,
+  override?: AnalyticsParameterOwnership
+): 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:
+      !isMissingCapabilityTool && data.options.enableConversationId === true && ownership?.conversationId === true,
+  }
+}
+
+function cloneRequestWithoutOwnedAnalyticsArguments(
+  request: MCPRequestLike,
+  ownership: AnalyticsParameterOwnership
+): MCPRequestLike {
+  const args = request.params?.arguments
+  const cleanedArgs = stripOwnedAnalyticsArguments(args, ownership)
+  if (cleanedArgs === args || !request.params) {
+    return request
+  }
+  return {
+    ...request,
+    params: {
+      ...request.params,
+      arguments: cleanedArgs as typeof request.params.arguments,
+    },
+  }
+}
+
 async function prepareToolCallEvent(
   server: MCPServerLike,
   data: MCPAnalyticsData,
@@ -136,6 +179,7 @@ async function prepareToolCallEvent(
   extra: CompatibleRequestHandlerExtra | undefined,
   startTime: Date,
   conversation: ConversationIdResolution,
+  ownership: AnalyticsParameterOwnership,
   eventType: MCPAnalyticsEventType
 ): Promise<McpEvent | null> {
   try {
@@ -159,7 +203,7 @@ async function prepareToolCallEvent(
     stampMetaClientInfo(event, request)
 
     await applyResolvedMetadata(event, data, request, extra)
-    setEventIntent(event, await resolveToolCallIntent(data, request, extra))
+    setEventIntent(event, await resolveToolCallIntent(data, request, ownership.context, extra))
     return event
   } catch (error) {
     log(
@@ -336,6 +380,18 @@ export async function handleListToolsRequest(
   return { tools }
 }
 
+function cacheToolAnalyticsParameterOwnership(
+  cache: Map<string, AnalyticsParameterOwnership>,
+  tools: ListToolsResult['tools']
+): void {
+  // Merge pages and concurrent enumerations; repeated tool names overwrite stale schemas.
+  for (const tool of tools) {
+    if (tool?.name) {
+      cache.set(tool.name, getAnalyticsParameterOwnership(tool.inputSchema))
+    }
+  }
+}
+
 function collectListedToolNames(tools: ListToolsResult['tools'] | undefined): string[] | undefined {
   if (!tools || tools.length === 0) {
     return
@@ -356,6 +412,10 @@ async function getTracedToolsList(
     const originalResponse = (await originalListToolsHandler(request, extra)) as ListToolsResult
     let tools = originalResponse.tools || []
 
+    if (data) {
+      cacheToolAnalyticsParameterOwnership(data.toolAnalyticsParameterOwnership, tools)
+    }
+
     if (data && isContextEnabled(data.options.context)) {
       tools = addContextParameterToTools(tools, getContextDescription(data.options.context))
     }

package/src/extensions/intent.ts

@@ -53,10 +53,16 @@ async function runIntentFallback(
 export async function resolveToolCallIntent(
   data: MCPAnalyticsData,
   request: MCPRequestLike,
+  analyticsOwnsContext: boolean,
   extra?: CompatibleRequestHandlerExtra
 ): Promise<ResolvedIntent | null> {
   const contextArgument = getContextArgument(request)
-  if (isContextEnabled(data.options.context) && request.params?.name !== 'get_more_tools' && contextArgument) {
+  if (
+    analyticsOwnsContext &&
+    isContextEnabled(data.options.context) &&
+    request.params?.name !== 'get_more_tools' &&
+    contextArgument
+  ) {
     return { intent: contextArgument, source: 'context_parameter' }
   }
 

package/src/extensions/mcp-sdk-compat.ts

@@ -97,6 +97,21 @@ export function isZ4Schema(schema: unknown): boolean {
   return !!(schema as ZodV4Internal)._zod
 }
 
+function isZodTypeLike(value: unknown): boolean {
+  return (
+    !!value &&
+    typeof value === 'object' &&
+    'parse' in value &&
+    typeof value.parse === 'function' &&
+    'safeParse' in value &&
+    typeof value.safeParse === 'function'
+  )
+}
+
+export function isZodRawShapeCompat(schema: unknown): schema is Record<string, unknown> {
+  return !!schema && typeof schema === 'object' && Object.values(schema).some(isZodTypeLike)
+}
+
 export function getObjectShape(schema: unknown): Record<string, unknown> | undefined {
   if (!schema || typeof schema !== 'object') {
     return

package/src/index.ts

@@ -143,6 +143,7 @@ function buildTrackingData(
     sessionId: newSessionId(),
     lastActivity: new Date(),
     identifiedSessions: new IdentityCache(),
+    toolAnalyticsParameterOwnership: new Map(),
     toolCategories: new Map<string, string>(),
     toolDescriptions: new Map<string, string>(),
     sessionInfo: getSessionInfo(lowLevelServer, undefined),

package/src/types.ts

@@ -271,6 +271,11 @@ export interface SessionInfo {
   serverVersion?: string
 }
 
+export interface AnalyticsParameterOwnership {
+  context: boolean
+  conversationId: boolean
+}
+
 export interface MCPAnalyticsData {
   sink: McpEventSink | undefined
   identifiedSessions: IdentityCache
@@ -280,6 +285,7 @@ export interface MCPAnalyticsData {
   sessionInfo: SessionInfo
   /** `token` = recovered from a self-encoded `Mcp-Session-Id` token (see session-token.ts). */
   sessionSource: 'generated' | 'mcp' | 'token'
+  toolAnalyticsParameterOwnership: Map<string, AnalyticsParameterOwnership>
   toolCategories: Map<string, string>
   toolDescriptions: Map<string, string>
 }

package/src/version.ts

@@ -1 +1 @@
-export const version = '0.10.2'
+export const version = '0.10.4'