@posthog/mcp 0.0.3 → 0.0.5

package/README.md

@@ -52,6 +52,22 @@ track(server, {
 With `enableAITracing: true`, tool calls also emit `$ai_span` events with `$ai_trace_id` and `$ai_span_id`.
 The regular `mcp_tool_call` event includes the same trace/span IDs so it can be joined back to the LLM analytics span.
 
+### Conversation ID (opt-in)
+
+When `enableConversationId: true` is passed to `track()`, the SDK injects an optional `conversation_id` argument into every tool's input schema and tells the agent to reuse the value the server returns. When the agent omits it on a call, the SDK mints a UUID and appends a short text block to the tool's response asking the agent to echo the same `conversation_id` on subsequent calls. The value the agent supplies (or the SDK mints) is captured on PostHog events as `$mcp_conversation_id` — separate from `$session_id`, which is unchanged. Off by default.
+
+```ts
+track(server, {
+  apiKey: process.env.POSTHOG_API_KEY,
+  enableConversationId: true,
+});
+```
+
+**Caveats:**
+
+- The prompt-back is appended as a regular `text` content block (the only channel MCP currently offers for server→agent communication). Consumers that surface raw tool-call content to end users will see `[SERVER]: Reuse conversation_id=…` in their UI. If/when the MCP spec grows a server-directives channel (e.g. on `_meta`), the SDK will move there.
+- The captured `$mcp_conversation_id` value is agent-controlled when the agent supplies one — the SDK accepts any non-empty string. Customers wanting to bind it to their own session scheme (chat ID, JWT `jti`, request ID) can do so freely; the trade-off is that nothing prevents a misbehaving agent from sending arbitrary values.
+
 The SDK sends events through `posthog-node`, so it uses the same PostHog ingestion client, batching, retry, flush, and shutdown behavior as the existing Node SDK.
 
 If your application already owns a PostHog client, pass it in instead:
@@ -86,6 +102,7 @@ Important properties:
 - `$mcp_intent` from the `context` argument, or from `intentFallback` when no context was provided
 - `$mcp_intent_source` as `context_parameter` or `inferred`
 - `$mcp_tool_name` and `$mcp_resource_name`
+- `$mcp_tool_description`, the tool's current `description` at the moment of the call — populated on `mcp_tool_call` and on the paired `$exception` event so the description is visible inline while triaging
 - `$mcp_parameters` and `$mcp_response`, after redaction and truncation
 - `$mcp_duration_ms`
 - `$mcp_is_error`

package/dist/index.cjs

@@ -350,6 +350,7 @@ function getRequestResourceName(request) {
 //#endregion
 //#region src/modules/constants.ts
 const DEFAULT_CONTEXT_PARAMETER_DESCRIPTION = `Explain why you are calling this tool and how it fits into the user's overall goal. This parameter is used for analytics and user intent tracking. YOU MUST provide 15-25 words (count carefully). NEVER use first person ('I', 'we', 'you') - maintain third-person perspective. NEVER include sensitive information such as credentials, passwords, or personal data. Example (20 words): "Searching across the organization's repositories to find all open issues related to performance complaints and latency issues for team prioritization."`;
+const DEFAULT_CONVERSATION_ID_DESCRIPTION = "Echo the conversation_id from the server's previous response. The server provides it on the first call — never invent one, and do not issue parallel tool calls until you have it.";
 const POSTHOG_MCP_ANALYTICS_SOURCE = "posthog_mcp_analytics";
 const PostHogMCPAnalyticsEvent = {
 	AiSpan: "$ai_span",
@@ -376,6 +377,7 @@ const PostHogMCPAnalyticsProperty = {
 	AiTraceId: "$ai_trace_id",
 	ClientName: "$mcp_client_name",
 	ClientVersion: "$mcp_client_version",
+	ConversationId: "$mcp_conversation_id",
 	DurationMs: "$mcp_duration_ms",
 	IsError: "$mcp_is_error",
 	Intent: "$mcp_intent",
@@ -387,6 +389,7 @@ const PostHogMCPAnalyticsProperty = {
 	ServerVersion: "$mcp_server_version",
 	SessionId: "$session_id",
 	Source: "$mcp_source",
+	ToolDescription: "$mcp_tool_description",
 	ToolName: "$mcp_tool_name"
 };
 //#endregion
@@ -421,6 +424,7 @@ function buildCaptureEvent(event, options) {
 		[PostHogMCPAnalyticsProperty.SessionId]: event.sessionId,
 		[PostHogMCPAnalyticsProperty.Source]: POSTHOG_MCP_ANALYTICS_SOURCE
 	};
+	addConversationIdProperty(event, properties);
 	addCommonEventProperties(event, properties);
 	addTraceReferenceProperties(event, properties, options);
 	addCustomEventProperties(event, properties);
@@ -446,11 +450,15 @@ function addTraceReferenceProperties(event, properties, options) {
 	properties[PostHogMCPAnalyticsProperty.AiTraceId] = getAITraceId(event);
 	properties[PostHogMCPAnalyticsProperty.AiSpanId] = getAISpanId(event);
 }
+function addConversationIdProperty(event, properties) {
+	if (event.conversationId !== void 0 && event.conversationId !== "") properties[PostHogMCPAnalyticsProperty.ConversationId] = event.conversationId;
+}
 function addCommonEventProperties(event, properties) {
 	if (event.resourceName) {
 		properties[PostHogMCPAnalyticsProperty.ResourceName] = event.resourceName;
 		if (event.eventType === MCPAnalyticsEventType.mcpToolsCall) properties[PostHogMCPAnalyticsProperty.ToolName] = event.resourceName;
 	}
+	if (event.toolDescription && event.eventType === MCPAnalyticsEventType.mcpToolsCall) properties[PostHogMCPAnalyticsProperty.ToolDescription] = event.toolDescription;
 	if (event.duration !== void 0) properties[PostHogMCPAnalyticsProperty.DurationMs] = event.duration;
 	if (event.serverName) properties[PostHogMCPAnalyticsProperty.ServerName] = event.serverName;
 	if (event.serverVersion) properties[PostHogMCPAnalyticsProperty.ServerVersion] = event.serverVersion;
@@ -477,6 +485,7 @@ function buildExceptionEvent(event) {
 		$exception_source: "backend",
 		[PostHogMCPAnalyticsProperty.SessionId]: event.sessionId
 	};
+	addConversationIdProperty(event, properties);
 	if (event.error) {
 		if (event.error.message) properties.$exception_message = event.error.message;
 		if (event.error.type) properties.$exception_type = event.error.type;
@@ -486,6 +495,7 @@ function buildExceptionEvent(event) {
 		properties[PostHogMCPAnalyticsProperty.ResourceName] = event.resourceName;
 		if (event.eventType === MCPAnalyticsEventType.mcpToolsCall) properties[PostHogMCPAnalyticsProperty.ToolName] = event.resourceName;
 	}
+	if (event.toolDescription && event.eventType === MCPAnalyticsEventType.mcpToolsCall) properties[PostHogMCPAnalyticsProperty.ToolDescription] = event.toolDescription;
 	if (event.serverName) properties[PostHogMCPAnalyticsProperty.ServerName] = event.serverName;
 	if (event.serverVersion) properties[PostHogMCPAnalyticsProperty.ServerVersion] = event.serverVersion;
 	if (event.clientName) properties[PostHogMCPAnalyticsProperty.ClientName] = event.clientName;
@@ -510,6 +520,7 @@ function buildAISpanEvent(event) {
 		[PostHogMCPAnalyticsProperty.SessionId]: event.sessionId,
 		[PostHogMCPAnalyticsProperty.Source]: POSTHOG_MCP_ANALYTICS_SOURCE
 	};
+	addConversationIdProperty(event, properties);
 	if (event.duration !== void 0) properties[PostHogMCPAnalyticsProperty.AiLatency] = event.duration / 1e3;
 	if (event.isError && event.error) properties.$ai_error = event.error;
 	if (event.parameters !== void 0) properties[PostHogMCPAnalyticsProperty.AiInputState] = event.parameters;
@@ -544,6 +555,7 @@ const PROTECTED_FIELDS = new Set([
 	"identifyActorName",
 	"identifyData",
 	"resourceName",
+	"toolDescription",
 	"eventType",
 	"actorId",
 	"tags",
@@ -721,7 +733,7 @@ function sanitizeParameters(obj) {
 }
 //#endregion
 //#region package.json
-var version = "0.0.3";
+var version = "0.0.5";
 //#endregion
 //#region src/modules/session.ts
 function newSessionId() {
@@ -1181,12 +1193,14 @@ function publishEvent(server, eventInput) {
 		identifyActorName: sessionInfo.identifyActorName,
 		identifyActorData: sessionInfo.identifyActorData,
 		resourceName: eventInput.resourceName,
+		toolDescription: eventInput.toolDescription,
 		parameters: eventInput.parameters,
 		response: eventInput.response,
 		userIntent: eventInput.userIntent,
 		userIntentSource: eventInput.userIntentSource,
 		isError: eventInput.isError,
 		error: eventInput.error,
+		conversationId: eventInput.conversationId,
 		redactionFn: eventInput.redactionFn,
 		tags: eventInput.tags,
 		properties: eventInput.properties
@@ -1923,6 +1937,112 @@ function setupMCPAnalyticsTools(server) {
 	}
 }
 //#endregion
+//#region src/modules/conversation-id.ts
+const CONVERSATION_ID_PARAM_NAME = "conversation_id";
+function addConversationIdToTool(tool) {
+	const modifiedTool = { ...tool };
+	const toolName = tool.name || "unknown";
+	const schema = modifiedTool.inputSchema;
+	if (schema?.properties?.["conversation_id"]) {
+		writeToLog(`WARN: Tool "${toolName}" already has '${CONVERSATION_ID_PARAM_NAME}' parameter. Skipping conversation_id injection.`);
+		return modifiedTool;
+	}
+	if (schema?.oneOf || schema?.allOf || schema?.anyOf) {
+		writeToLog(`WARN: Tool "${toolName}" has complex schema (oneOf/allOf/anyOf). Skipping conversation_id injection.`);
+		return modifiedTool;
+	}
+	if (!modifiedTool.inputSchema) modifiedTool.inputSchema = {
+		type: "object",
+		properties: {},
+		required: []
+	};
+	modifiedTool.inputSchema = JSON.parse(JSON.stringify(modifiedTool.inputSchema));
+	const inputSchema = modifiedTool.inputSchema;
+	if (!inputSchema.properties) inputSchema.properties = {};
+	if (inputSchema.additionalProperties === false) inputSchema.additionalProperties = void 0;
+	inputSchema.properties[CONVERSATION_ID_PARAM_NAME] = {
+		type: "string",
+		description: DEFAULT_CONVERSATION_ID_DESCRIPTION
+	};
+	return modifiedTool;
+}
+function addConversationIdToTools(tools) {
+	return tools.map((tool) => {
+		if (tool.name === "get_more_tools") return tool;
+		return addConversationIdToTool(tool);
+	});
+}
+/**
+* Decides which conversation_id to use for a tool call:
+*   - disabled or get_more_tools → none
+*   - agent supplied a value → use it
+*   - agent omitted → mint a UUID
+*/
+function resolveConversationId(enabled, args, toolName) {
+	if (!enabled || toolName === "get_more_tools") return {
+		minted: false,
+		conversationId: void 0
+	};
+	const supplied = extractConversationId(args);
+	if (supplied) return {
+		minted: false,
+		conversationId: supplied
+	};
+	return {
+		minted: true,
+		conversationId: (0, node_crypto.randomUUID)()
+	};
+}
+/**
+* Predicate matching the same eligibility checks injectConversationIdPromptBack uses,
+* exposed so callers can pre-decide whether the prompt-back will actually land
+* (and clear event.conversationId if not, to avoid orphan ids in analytics).
+*/
+function canInjectConversationIdPromptBack(result) {
+	if (!(result && typeof result === "object")) return false;
+	const resultObj = result;
+	if (resultObj.isError === true) return false;
+	return Array.isArray(resultObj.content);
+}
+function extractConversationId(args) {
+	if (!(args && typeof args === "object")) return;
+	const value = args[CONVERSATION_ID_PARAM_NAME];
+	if (typeof value !== "string") return;
+	const trimmed = value.trim();
+	return trimmed.length > 0 ? trimmed : void 0;
+}
+function cloneRequestWithoutConversationId(request) {
+	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)
+		}
+	};
+}
+function stripConversationId(args) {
+	if (!args || typeof args !== "object" || !("conversation_id" in args)) return args;
+	const { [CONVERSATION_ID_PARAM_NAME]: _omit, ...rest } = args;
+	return rest;
+}
+function buildConversationIdPromptBack(conversationId) {
+	return {
+		type: "text",
+		text: `[SERVER]: Reuse conversation_id=${conversationId} on every subsequent tool call in this conversation. Required for the server to correlate calls and provide context-aware results.`
+	};
+}
+function injectConversationIdPromptBack(result, conversationId) {
+	if (!canInjectConversationIdPromptBack(result)) return result;
+	const resultObj = result;
+	return {
+		...resultObj,
+		content: [...resultObj.content, buildConversationIdPromptBack(conversationId)]
+	};
+}
+//#endregion
 //#region src/modules/intent.ts
 function getContextArgument$2(request) {
 	const context = request.params?.arguments?.context;
@@ -2018,9 +2138,11 @@ async function getTracedToolsList(server, originalListToolsHandler, request, ext
 		const data = getServerTrackingData(server);
 		let tools = (await originalListToolsHandler(request, extra)).tools || [];
 		if (data && isContextEnabled(data.options.context)) tools = addContextParameterToTools(tools, getContextDescription(data.options.context));
+		if (data?.options.enableConversationId) tools = addConversationIdToTools(tools);
 		if (data?.options.reportMissing) {
 			if (!tools.some((tool) => tool?.name === "get_more_tools")) tools.push(getReportMissingToolDescriptor());
 		}
+		if (data) cacheToolDescriptions(data.toolDescriptions, tools);
 		return tools;
 	} catch (error) {
 		writeToLog(`Warning: Original list tools handler failed, this suggests an error PostHog MCP analytics did not cause - ${error}`);
@@ -2102,30 +2224,39 @@ async function handleToolCallRequest(server, originalCallToolHandler, request, e
 		writeToLog("Warning: PostHog MCP analytics is unable to find server tracking data. Please ensure you have called track(server, options) before using tool calls.");
 		return await originalCallToolHandler?.(request, extra);
 	}
+	const conversation = resolveConversationId(data.options.enableConversationId ?? false, request.params?.arguments, request.params?.name);
+	const downstreamRequest = conversation.conversationId ? cloneRequestWithoutConversationId(request) : request;
+	const toolName = request.params?.name;
 	const event = {
 		sessionId: getServerSessionId(server, extra),
-		resourceName: request.params?.name || "Unknown Tool Name",
-		parameters: buildCapturedMcpParameters(request),
+		conversationId: conversation.conversationId,
+		resourceName: toolName || "Unknown Tool Name",
+		parameters: buildCapturedMcpParameters(downstreamRequest),
 		eventType: MCPAnalyticsEventType.mcpToolsCall,
 		timestamp: /* @__PURE__ */ new Date(),
+		toolDescription: toolName ? data.toolDescriptions.get(toolName) : void 0,
 		redactionFn: data.options.redactSensitiveInformation
 	};
 	try {
 		await handleIdentify(server, data, request, extra);
 		await applyResolvedMetadata$1(event, data, request, extra);
 		setEventIntent(event, await resolveToolCallIntent(data, request, extra));
-		const result = await executeToolCall(server, originalCallToolHandler, request, extra, event);
+		const result = await executeToolCall(server, originalCallToolHandler, downstreamRequest, extra, event);
 		if (isToolResultError$1(result)) {
 			event.isError = true;
 			event.error = captureException(result);
 		} else event.isError = false;
-		event.response = result;
+		let finalResult = result;
+		if (conversation.minted) if (canInjectConversationIdPromptBack(result)) finalResult = injectConversationIdPromptBack(result, conversation.conversationId);
+		else event.conversationId = void 0;
+		event.response = finalResult;
 		event.duration = getEventDuration(event);
 		publishEvent(server, event);
-		return result;
+		return finalResult;
 	} catch (error) {
 		event.isError = true;
 		event.error = captureException(error);
+		if (conversation.minted) event.conversationId = void 0;
 		event.duration = getEventDuration(event);
 		publishEvent(server, event);
 		throw error;
@@ -2157,6 +2288,10 @@ function getContextArgument$1(request) {
 function getEventDuration(event) {
 	return event.timestamp ? Date.now() - event.timestamp.getTime() : 0;
 }
+function cacheToolDescriptions(cache, tools) {
+	if (!tools) return;
+	for (const tool of tools) if (tool?.name && typeof tool.description === "string") cache.set(tool.name, tool.description);
+}
 //#endregion
 //#region src/modules/mcp-sdk-compat.ts
 /**
@@ -2244,7 +2379,8 @@ function addTracingToToolRegistry(tools, server) {
 }
 function setupListenerToRegisteredTools(server) {
 	try {
-		if (!getServerTrackingData(server.server)) {
+		const data = getServerTrackingData(server.server);
+		if (!data) {
 			writeToLog("Warning: Cannot setup listener - no tracking data found");
 			return;
 		}
@@ -2252,6 +2388,7 @@ function setupListenerToRegisteredTools(server) {
 			set(target, property, value) {
 				try {
 					if (typeof property === "string" && value && typeof value === "object" && hasToolFunction(value)) {
+						if (typeof value.description === "string") data.toolDescriptions.set(property, value.description);
 						if (value[MCP_ANALYTICS_PROCESSED]) {
 							writeToLog(`Tool ${String(property)} already processed, skipping proxy wrapping`);
 							return Reflect.set(target, property, value);
@@ -2317,14 +2454,14 @@ function addTracingToToolCallbackInternal(tool, toolName, _server) {
 			args = void 0;
 			extra = params[0];
 		}
-		const removeContextFromArgs = (args) => {
-			if (args && typeof args === "object" && "context" in args) {
-				const { context: _context, ...argsWithoutContext } = args;
-				return argsWithoutContext;
+		const removeContextFromArgs = (input) => {
+			if (input && typeof input === "object" && "context" in input) {
+				const { context: _context, ...rest } = input;
+				return rest;
 			}
-			return args;
+			return input;
 		};
-		const cleanedArgs = toolName === "get_more_tools" ? args : removeContextFromArgs(args);
+		const cleanedArgs = toolName === "get_more_tools" ? args : stripConversationId(removeContextFromArgs(args));
 		try {
 			if (cleanedArgs === void 0) return await originalCallback(extra);
 			return await originalCallback(cleanedArgs, extra);
@@ -2358,26 +2495,31 @@ function createToolsCallWrapper(originalHandler, server) {
 }
 async function handleWrappedToolsCall(originalHandler, server, request, extra) {
 	const startTime = /* @__PURE__ */ new Date();
-	const tracing = await initializeToolCallEvent(server, request, extra, startTime);
+	const conversation = resolveConversationId(getServerTrackingData(server)?.options.enableConversationId ?? false, request.params?.arguments, request.params?.name);
+	const tracing = await initializeToolCallEvent(server, request, conversation.conversationId ? cloneRequestWithoutConversationId(request) : request, extra, startTime, conversation);
 	if (request?.params?.name === "get_more_tools") return await executeReportMissingTool(server, request, tracing, startTime);
 	return await executeOriginalTool(originalHandler, server, request, extra, tracing, startTime);
 }
-async function initializeToolCallEvent(server, request, extra, startTime) {
+async function initializeToolCallEvent(server, request, downstreamRequest, extra, startTime, conversation) {
 	try {
 		const data = getServerTrackingData(server);
 		if (!data) {
 			writeToLog("Warning: PostHog MCP analytics is unable to find server tracking data. Please ensure you have called track(server, options) before using tool calls.");
 			return {
 				event: null,
+				mintedConversationId: void 0,
 				shouldPublishEvent: false
 			};
 		}
+		const toolName = request.params?.name;
 		const event = {
 			sessionId: getServerSessionId(server, extra),
-			resourceName: request.params?.name || "Unknown Tool",
-			parameters: buildCapturedMcpParameters(request),
+			conversationId: conversation.conversationId,
+			resourceName: toolName || "Unknown Tool",
+			parameters: buildCapturedMcpParameters(downstreamRequest),
 			eventType: MCPAnalyticsEventType.mcpToolsCall,
 			timestamp: startTime,
+			toolDescription: toolName ? data.toolDescriptions.get(toolName) : void 0,
 			redactionFn: data.options.redactSensitiveInformation
 		};
 		await handleIdentify(server, data, request, extra);
@@ -2386,12 +2528,14 @@ async function initializeToolCallEvent(server, request, extra, startTime) {
 		setEventIntent(event, await resolveToolCallIntent(data, request, extra));
 		return {
 			event,
+			mintedConversationId: conversation.minted ? conversation.conversationId : void 0,
 			shouldPublishEvent: true
 		};
 	} catch (error) {
 		writeToLog(`Warning: PostHog MCP analytics tracing failed for tool ${request.params?.name}, falling back to original handler - ${error}`);
 		return {
 			event: null,
+			mintedConversationId: void 0,
 			shouldPublishEvent: false
 		};
 	}
@@ -2419,14 +2563,20 @@ async function executeReportMissingTool(server, request, tracing, startTime) {
 async function executeOriginalTool(originalHandler, server, request, extra, tracing, startTime) {
 	try {
 		const result = await originalHandler(request, extra);
-		publishSuccessfulToolEvent(server, tracing, result, startTime, {
+		let finalResult = result;
+		if (tracing.mintedConversationId) {
+			if (canInjectConversationIdPromptBack(result)) finalResult = injectConversationIdPromptBack(result, tracing.mintedConversationId);
+			else if (tracing.event) tracing.event.conversationId = void 0;
+		}
+		publishSuccessfulToolEvent(server, tracing, finalResult, startTime, {
 			capturedError: extra?.__mcp_analytics_error,
 			clearCapturedError: () => {
 				if (extra) extra.__mcp_analytics_error = void 0;
 			}
 		});
-		return result;
+		return finalResult;
 	} catch (error) {
+		if (tracing.mintedConversationId && tracing.event) tracing.event.conversationId = void 0;
 		publishFailedToolEvent(server, tracing, error, startTime);
 		throw error;
 	}
@@ -2459,16 +2609,20 @@ function publishFailedToolEvent(server, tracing, error, startTime) {
 }
 function setupTracking(server) {
 	try {
-		getServerTrackingData(server.server);
+		const mcpAnalyticsData = getServerTrackingData(server.server);
 		setupToolsCallHandlerWrapping(server);
 		setupInitializeTracing(server);
 		server._registeredTools = addTracingToToolRegistry(server._registeredTools, server);
+		if (mcpAnalyticsData) seedToolDescriptionsFromRegistry(mcpAnalyticsData.toolDescriptions, server._registeredTools);
 		setupListToolsTracing(server);
 		setupListenerToRegisteredTools(server);
 	} catch (error) {
 		writeToLog(`Warning: Failed to setup tool call tracing - ${error}`);
 	}
 }
+function seedToolDescriptionsFromRegistry(cache, tools) {
+	for (const [name, tool] of Object.entries(tools)) if (typeof tool?.description === "string") cache.set(name, tool.description);
+}
 //#endregion
 //#region src/index.ts
 /**
@@ -2604,6 +2758,7 @@ function buildTrackingData(lowLevelServer, options) {
 		sessionId: newSessionId(),
 		lastActivity: /* @__PURE__ */ new Date(),
 		identifiedSessions: /* @__PURE__ */ new Map(),
+		toolDescriptions: /* @__PURE__ */ new Map(),
 		sessionInfo: getSessionInfo(lowLevelServer, void 0),
 		options: {
 			reportMissing: options.reportMissing ?? false,
@@ -2617,7 +2772,8 @@ function buildTrackingData(lowLevelServer, options) {
 			eventProperties: options.eventProperties,
 			host: options.host,
 			posthogClient: options.posthogClient,
-			posthogOptions: options.posthogOptions
+			posthogOptions: options.posthogOptions,
+			enableConversationId: options.enableConversationId ?? false
 		},
 		sessionSource: "generated"
 	};