@posthog/mcp 0.0.3 → 0.0.4

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:

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",
@@ -421,6 +423,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,6 +449,9 @@ 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;
@@ -477,6 +483,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;
@@ -510,6 +517,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;
@@ -721,7 +729,7 @@ function sanitizeParameters(obj) {
 }
 //#endregion
 //#region package.json
-var version = "0.0.3";
+var version = "0.0.4";
 //#endregion
 //#region src/modules/session.ts
 function newSessionId() {
@@ -1187,6 +1195,7 @@ function publishEvent(server, eventInput) {
 		userIntentSource: eventInput.userIntentSource,
 		isError: eventInput.isError,
 		error: eventInput.error,
+		conversationId: eventInput.conversationId,
 		redactionFn: eventInput.redactionFn,
 		tags: eventInput.tags,
 		properties: eventInput.properties
@@ -1923,6 +1932,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,6 +2133,7 @@ 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());
 		}
@@ -2102,10 +2218,13 @@ 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 event = {
 		sessionId: getServerSessionId(server, extra),
+		conversationId: conversation.conversationId,
 		resourceName: request.params?.name || "Unknown Tool Name",
-		parameters: buildCapturedMcpParameters(request),
+		parameters: buildCapturedMcpParameters(downstreamRequest),
 		eventType: MCPAnalyticsEventType.mcpToolsCall,
 		timestamp: /* @__PURE__ */ new Date(),
 		redactionFn: data.options.redactSensitiveInformation
@@ -2114,18 +2233,22 @@ async function handleToolCallRequest(server, originalCallToolHandler, request, e
 		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;
@@ -2317,14 +2440,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,24 +2481,27 @@ 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 event = {
 			sessionId: getServerSessionId(server, extra),
+			conversationId: conversation.conversationId,
 			resourceName: request.params?.name || "Unknown Tool",
-			parameters: buildCapturedMcpParameters(request),
+			parameters: buildCapturedMcpParameters(downstreamRequest),
 			eventType: MCPAnalyticsEventType.mcpToolsCall,
 			timestamp: startTime,
 			redactionFn: data.options.redactSensitiveInformation
@@ -2386,12 +2512,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 +2547,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;
 	}
@@ -2617,7 +2751,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"
 	};