@posthog/mcp 0.0.2 → 0.0.4

package/README.md

@@ -34,9 +34,40 @@ track(server, {
 With `context: true`, the SDK adds a required `context` argument to every tool call, strips it before invoking your handler, and captures it as `$mcp_intent` on PostHog events.
 Captured tool parameters omit the duplicated `context` value and MCP transport internals.
 
+Use `intentFallback` when you want a fallback for clients that call tools without the `context` argument.
+This is a consumer-supplied callback — the SDK does no inference of its own; whatever string you return becomes `$mcp_intent`.
+The explicit `context` argument always wins; fallback values are marked with `$mcp_intent_source = "inferred"`.
+
+```ts
+track(server, {
+  apiKey: process.env.POSTHOG_API_KEY,
+  context: true,
+  intentFallback: (request) => {
+    const toolName = request.params?.name;
+    return toolName ? `Calling ${toolName}` : undefined;
+  },
+});
+```
+
 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:
@@ -52,6 +83,36 @@ track(server, {
 });
 ```
 
+## Event schema
+
+The SDK emits PostHog events using a stable MCP-specific schema.
+The package exports `PostHogMCPAnalyticsEvent`, `PostHogMCPAnalyticsProperty`, and `POSTHOG_MCP_ANALYTICS_SOURCE` constants so product code can query the same contract without hard-coded strings.
+
+Canonical event names:
+
+- `mcp_tool_call` for each MCP tool call
+- `mcp_tools_list` when clients list available tools
+- `mcp_initialize` when clients initialize a session
+- `$ai_span` for tool-call spans when `enableAITracing: true`
+- `$exception` for captured tool errors
+
+Important properties:
+
+- `$mcp_source = "posthog_mcp_analytics"`
+- `$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_parameters` and `$mcp_response`, after redaction and truncation
+- `$mcp_duration_ms`
+- `$mcp_is_error`
+- `$session_id`
+- `$ai_trace_id`, `$ai_span_id`, and `$ai_session_id` when AI tracing is enabled
+
+The SDK does not emit `$mcp_context`.
+Use `$mcp_intent` for agent/user intent.
+
+See [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) for the full architecture, property catalog, sample queries, and migration notes vs the upstream mcpcat schema.
+
 ## Development
 
 ```bash

package/dist/index.cjs

@@ -120,15 +120,14 @@ function getMCPCompatibleErrorMessage(error) {
 	return "Unknown error";
 }
 //#endregion
-//#region src/modules/ids.ts
-function newPrefixedId(prefix) {
-	return `${prefix}_${(0, node_crypto.randomUUID)()}`;
-}
-function deterministicPrefixedId(prefix, input) {
-	return `${prefix}_${(0, node_crypto.createHash)("sha256").update(input).digest("hex").slice(0, 32)}`;
-}
-//#endregion
 //#region src/modules/event-types.ts
+/**
+* Internal SDK event vocabulary.
+*
+* These values are not imported from `@modelcontextprotocol/sdk`; they are the
+* protocol-shaped event types this SDK observes before mapping them to PostHog
+* event names.
+*/
 const MCPAnalyticsEventType = {
 	identify: "posthog:identify",
 	custom: "posthog:custom",
@@ -141,6 +140,14 @@ const MCPAnalyticsEventType = {
 	mcpToolsList: "mcp:tools/list"
 };
 //#endregion
+//#region src/modules/ids.ts
+function newPrefixedId(prefix) {
+	return `${prefix}_${(0, node_crypto.randomUUID)()}`;
+}
+function deterministicPrefixedId(prefix, input) {
+	return `${prefix}_${(0, node_crypto.createHash)("sha256").update(input).digest("hex").slice(0, 32)}`;
+}
+//#endregion
 //#region src/modules/validation.ts
 const TAG_KEY_REGEX = /^[a-zA-Z0-9$_.:\- ]+$/;
 const MAX_TAG_KEY_LENGTH = 32;
@@ -343,7 +350,21 @@ 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",
+	Custom: "mcp_custom",
+	Exception: "$exception",
+	Identify: "$identify",
+	Initialize: "mcp_initialize",
+	PromptGet: "mcp_prompt_get",
+	PromptsList: "mcp_prompts_list",
+	ResourceRead: "mcp_resource_read",
+	ResourcesList: "mcp_resources_list",
+	ToolCall: "mcp_tool_call",
+	ToolsList: "mcp_tools_list"
+};
 const PostHogMCPAnalyticsProperty = {
 	AiInputState: "$ai_input_state",
 	AiIsError: "$ai_is_error",
@@ -356,9 +377,11 @@ 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",
+	IntentSource: "$mcp_intent_source",
 	Parameters: "$mcp_parameters",
 	ResourceName: "$mcp_resource_name",
 	Response: "$mcp_response",
@@ -370,8 +393,17 @@ const PostHogMCPAnalyticsProperty = {
 };
 //#endregion
 //#region src/modules/posthog-events.ts
-const MCP_EVENT_PREFIX_REGEX = /^mcp:/;
-const SLASH_REGEX = /\//g;
+const BUILT_IN_EVENT_NAME_BY_TYPE = {
+	[MCPAnalyticsEventType.custom]: PostHogMCPAnalyticsEvent.Custom,
+	[MCPAnalyticsEventType.identify]: PostHogMCPAnalyticsEvent.Identify,
+	[MCPAnalyticsEventType.mcpInitialize]: PostHogMCPAnalyticsEvent.Initialize,
+	[MCPAnalyticsEventType.mcpPromptsGet]: PostHogMCPAnalyticsEvent.PromptGet,
+	[MCPAnalyticsEventType.mcpPromptsList]: PostHogMCPAnalyticsEvent.PromptsList,
+	[MCPAnalyticsEventType.mcpResourcesList]: PostHogMCPAnalyticsEvent.ResourcesList,
+	[MCPAnalyticsEventType.mcpResourcesRead]: PostHogMCPAnalyticsEvent.ResourceRead,
+	[MCPAnalyticsEventType.mcpToolsCall]: PostHogMCPAnalyticsEvent.ToolCall,
+	[MCPAnalyticsEventType.mcpToolsList]: PostHogMCPAnalyticsEvent.ToolsList
+};
 function getDistinctId(event) {
 	return event.identifyActorGivenId || event.sessionId || "anonymous";
 }
@@ -386,17 +418,17 @@ function buildPostHogCaptureEvents(event, options = {}) {
 }
 function buildCaptureEvent(event, options) {
 	const distinctId = getDistinctId(event);
-	const eventName = mapEventType(event.eventType);
 	const timestamp = getTimestamp(event);
 	const properties = {
 		[PostHogMCPAnalyticsProperty.SessionId]: event.sessionId,
 		[PostHogMCPAnalyticsProperty.Source]: POSTHOG_MCP_ANALYTICS_SOURCE
 	};
+	addConversationIdProperty(event, properties);
 	addCommonEventProperties(event, properties);
 	addTraceReferenceProperties(event, properties, options);
 	addCustomEventProperties(event, properties);
 	return {
-		event: eventName,
+		event: BUILT_IN_EVENT_NAME_BY_TYPE[event.eventType],
 		distinct_id: distinctId,
 		properties,
 		timestamp,
@@ -417,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;
@@ -428,6 +463,7 @@ function addCommonEventProperties(event, properties) {
 	if (event.clientName) properties[PostHogMCPAnalyticsProperty.ClientName] = event.clientName;
 	if (event.clientVersion) properties[PostHogMCPAnalyticsProperty.ClientVersion] = event.clientVersion;
 	if (event.userIntent) properties[PostHogMCPAnalyticsProperty.Intent] = event.userIntent;
+	if (event.userIntentSource) properties[PostHogMCPAnalyticsProperty.IntentSource] = event.userIntentSource;
 	if (event.isError !== void 0) properties[PostHogMCPAnalyticsProperty.IsError] = event.isError;
 	if (event.parameters !== void 0) properties[PostHogMCPAnalyticsProperty.Parameters] = event.parameters;
 	if (event.response !== void 0) properties[PostHogMCPAnalyticsProperty.Response] = event.response;
@@ -447,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;
@@ -461,7 +498,7 @@ function buildExceptionEvent(event) {
 	if (event.clientName) properties[PostHogMCPAnalyticsProperty.ClientName] = event.clientName;
 	if (event.clientVersion) properties[PostHogMCPAnalyticsProperty.ClientVersion] = event.clientVersion;
 	return {
-		event: "$exception",
+		event: PostHogMCPAnalyticsEvent.Exception,
 		distinct_id: distinctId,
 		properties,
 		timestamp,
@@ -480,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;
@@ -487,27 +525,17 @@ function buildAISpanEvent(event) {
 	if (event.serverName) properties[PostHogMCPAnalyticsProperty.ServerName] = event.serverName;
 	if (event.clientName) properties[PostHogMCPAnalyticsProperty.ClientName] = event.clientName;
 	if (event.userIntent) properties[PostHogMCPAnalyticsProperty.Intent] = event.userIntent;
+	if (event.userIntentSource) properties[PostHogMCPAnalyticsProperty.IntentSource] = event.userIntentSource;
 	if (event.tags) for (const [key, value] of Object.entries(event.tags)) properties[key] = value;
 	if (event.properties) for (const [key, value] of Object.entries(event.properties)) properties[key] = value;
 	return {
-		event: "$ai_span",
+		event: PostHogMCPAnalyticsEvent.AiSpan,
 		distinct_id: distinctId,
 		properties,
 		timestamp,
 		type: "capture"
 	};
 }
-function mapEventType(eventType) {
-	return {
-		[MCPAnalyticsEventType.mcpToolsCall]: "mcp_tool_call",
-		[MCPAnalyticsEventType.mcpToolsList]: "mcp_tools_list",
-		[MCPAnalyticsEventType.mcpInitialize]: "mcp_initialize",
-		[MCPAnalyticsEventType.mcpResourcesRead]: "mcp_resource_read",
-		[MCPAnalyticsEventType.mcpResourcesList]: "mcp_resources_list",
-		[MCPAnalyticsEventType.mcpPromptsGet]: "mcp_prompt_get",
-		[MCPAnalyticsEventType.mcpPromptsList]: "mcp_prompts_list"
-	}[eventType] || `mcp_${eventType.replace(MCP_EVENT_PREFIX_REGEX, "").replace(SLASH_REGEX, "_")}`;
-}
 //#endregion
 //#region src/modules/redaction.ts
 /**
@@ -701,7 +729,7 @@ function sanitizeParameters(obj) {
 }
 //#endregion
 //#region package.json
-var version = "0.0.2";
+var version = "0.0.4";
 //#endregion
 //#region src/modules/session.ts
 function newSessionId() {
@@ -1085,7 +1113,6 @@ var EventQueue = class {
 				timestamp: new Date(captureEvent.timestamp)
 			});
 			writeToLog(`Queued PostHog event ${event.id} | ${event.eventType} | ${event.duration} ms | ${event.identifyActorGivenId || "anonymous"}`);
-			writeToLog(`Event details: ${JSON.stringify(event)}`);
 		} catch (error) {
 			writeToLog(`Failed to queue PostHog event ${event.id}: ${getMCPCompatibleErrorMessage(error)}`);
 			throw error;
@@ -1148,7 +1175,7 @@ function publishEvent(server, eventInput) {
 		id: eventInput.id || "",
 		sessionId: eventInput.sessionId || data.sessionId,
 		apiKey: data.apiKey,
-		eventType: eventInput.eventType || "",
+		eventType: eventInput.eventType || MCPAnalyticsEventType.custom,
 		timestamp: eventInput.timestamp || /* @__PURE__ */ new Date(),
 		duration,
 		ipAddress: sessionInfo.ipAddress,
@@ -1165,8 +1192,10 @@ function publishEvent(server, eventInput) {
 		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
@@ -1903,6 +1932,155 @@ 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;
+	return typeof context === "string" && context.trim() ? context : void 0;
+}
+function normalizeIntent(intent) {
+	if (typeof intent !== "string") return null;
+	const trimmed = intent.trim();
+	return trimmed ? trimmed : null;
+}
+async function runIntentFallback(data, request, extra) {
+	if (!data.options.intentFallback) return null;
+	try {
+		const intent = normalizeIntent(await data.options.intentFallback(request, extra));
+		return intent ? {
+			intent,
+			source: "inferred"
+		} : null;
+	} catch (error) {
+		writeToLog(`intentFallback callback error: ${error}`);
+		return null;
+	}
+}
+async function resolveToolCallIntent(data, request, extra) {
+	const contextArgument = getContextArgument$2(request);
+	if (isContextEnabled(data.options.context) && request.params?.name !== "get_more_tools" && contextArgument) return {
+		intent: contextArgument,
+		source: "context_parameter"
+	};
+	return await runIntentFallback(data, request, extra);
+}
+function setEventIntent(event, resolvedIntent) {
+	if (!resolvedIntent) return;
+	event.userIntent = resolvedIntent.intent;
+	event.userIntentSource = resolvedIntent.source;
+}
+function setExplicitContextIntent(event, context) {
+	const intent = normalizeIntent(context);
+	if (!intent) return;
+	event.userIntent = intent;
+	event.userIntentSource = "context_parameter";
+}
+//#endregion
 //#region src/modules/tracing.ts
 function isToolResultError$1(result) {
 	return !!result && typeof result === "object" && "isError" in result && result.isError === true;
@@ -1955,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());
 		}
@@ -2039,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
@@ -2050,18 +2232,24 @@ async function handleToolCallRequest(server, originalCallToolHandler, request, e
 	try {
 		await handleIdentify(server, data, request, extra);
 		await applyResolvedMetadata$1(event, data, request, extra);
-		setToolCallContext(event, data.options.context, request);
-		const result = await executeToolCall(server, originalCallToolHandler, request, extra, event);
+		setEventIntent(event, await resolveToolCallIntent(data, request, extra));
+		const result = await executeToolCall(server, originalCallToolHandler, downstreamRequest, extra, event);
 		if (isToolResultError$1(result)) {
 			event.isError = true;
 			event.error = captureException(result);
-		}
-		event.response = result;
+		} else event.isError = false;
+		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;
 	}
@@ -2069,7 +2257,7 @@ async function handleToolCallRequest(server, originalCallToolHandler, request, e
 async function executeToolCall(server, originalCallToolHandler, request, extra, event) {
 	if (request.params?.name === "get_more_tools") {
 		const context = getContextArgument$1(request) || "";
-		event.userIntent = context;
+		setExplicitContextIntent(event, context);
 		return handleReportMissing({ context });
 	}
 	if (originalCallToolHandler) return await originalCallToolHandler(request, extra);
@@ -2085,11 +2273,6 @@ async function applyResolvedMetadata$1(event, data, request, extra) {
 	const resolvedProperties = await resolveEventProperties(data, request, extra);
 	if (resolvedProperties) event.properties = resolvedProperties;
 }
-function setToolCallContext(event, context, request) {
-	if (!(isContextEnabled(context) && request.params?.name !== "get_more_tools")) return;
-	const contextArgument = getContextArgument$1(request);
-	if (contextArgument) event.userIntent = contextArgument;
-}
 function getContextArgument$1(request) {
 	const context = request.params?.arguments?.context;
 	return typeof context === "string" ? context : void 0;
@@ -2257,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);
@@ -2298,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
@@ -2323,16 +2509,17 @@ async function initializeToolCallEvent(server, request, extra, startTime) {
 		await handleIdentify(server, data, request, extra);
 		event.sessionId = data.sessionId;
 		await applyResolvedMetadata(event, data, request, extra);
-		const contextArgument = getContextArgument(request);
-		if (isContextEnabled(data.options.context) && contextArgument) event.userIntent = contextArgument;
+		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
 		};
 	}
@@ -2347,7 +2534,10 @@ async function executeReportMissingTool(server, request, tracing, startTime) {
 	try {
 		const context = getContextArgument(request) || "";
 		const result = await handleReportMissing({ context });
-		publishSuccessfulToolEvent(server, tracing, result, startTime, { userIntent: context });
+		publishSuccessfulToolEvent(server, tracing, result, startTime, {
+			userIntent: context,
+			userIntentSource: "context_parameter"
+		});
 		return result;
 	} catch (error) {
 		publishFailedToolEvent(server, tracing, error, startTime);
@@ -2357,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;
 	}
@@ -2375,12 +2571,15 @@ function getContextArgument(request) {
 }
 function publishSuccessfulToolEvent(server, tracing, result, startTime, options = {}) {
 	if (!(tracing.event && tracing.shouldPublishEvent)) return;
-	if (options.userIntent) tracing.event.userIntent = options.userIntent;
+	if (options.userIntent) {
+		setExplicitContextIntent(tracing.event, options.userIntent);
+		if (options.userIntentSource) tracing.event.userIntentSource = options.userIntentSource;
+	}
 	if (isToolResultError(result)) {
 		tracing.event.isError = true;
 		tracing.event.error = captureException(options.capturedError || result);
 		options.clearCapturedError?.();
-	}
+	} else tracing.event.isError = false;
 	tracing.event.response = result;
 	tracing.event.duration = Date.now() - startTime.getTime();
 	publishEvent(server, tracing.event);
@@ -2417,6 +2616,7 @@ function setupTracking(server) {
 * @param options.enableAITracing - Emits `$ai_span` events for tool calls so MCP activity appears in PostHog LLM analytics. Defaults to false.
 * @param options.enableTracing - Enables tracking of tool calls and usage patterns.
 * @param options.context - Enables the required "context" parameter on tools to capture user intent. Pass false to disable, or an object with a custom description.
+* @param options.intentFallback - Optional consumer-supplied callback invoked when a tool call has no explicit `context` argument. Return a short user intent string to capture as `$mcp_intent` (with `$mcp_intent_source = "inferred"`). The SDK does not infer anything on its own — this is purely a slot for your own derivation logic (e.g. a switch on `request.params.name`, an LLM call, etc.). Runs on the hot path of every uncontextualized tool call.
 * @param options.identify - Async function to identify users and attach custom data to their sessions.
 * @param options.redactSensitiveInformation - Function to redact sensitive data before sending to PostHog.
 * @param options.eventTags - Callback invoked on every auto-captured event (tool calls, tool lists, initialize) to attach string key-value tags. Tags are intended to be indexed and queryable in PostHog — use them for structured metadata you'll want to filter or group by (e.g., trace IDs, environments, regions). Tags are validated client-side: keys must be ≤32 chars matching `[a-zA-Z0-9$_.:\- ]`, values must be strings ≤200 chars with no newlines, max 50 entries per event. Invalid entries are silently dropped with a warning logged to `~/posthog-mcp-analytics.log`. If the callback throws or returns null, tags are omitted. Receives the same `(request, extra)` arguments as `identify`.
@@ -2544,13 +2744,15 @@ function buildTrackingData(lowLevelServer, options) {
 			enableAITracing: options.enableAITracing ?? false,
 			enableTracing: options.enableTracing ?? true,
 			context: options.context,
+			intentFallback: options.intentFallback,
 			identify: options.identify,
 			redactSensitiveInformation: options.redactSensitiveInformation,
 			eventTags: options.eventTags,
 			eventProperties: options.eventProperties,
 			host: options.host,
 			posthogClient: options.posthogClient,
-			posthogOptions: options.posthogOptions
+			posthogOptions: options.posthogOptions,
+			enableConversationId: options.enableConversationId ?? false
 		},
 		sessionSource: "generated"
 	};
@@ -2688,6 +2890,8 @@ function publishResolvedCustomEvent(target, event) {
 	eventQueue.add(event);
 }
 //#endregion
+exports.POSTHOG_MCP_ANALYTICS_SOURCE = POSTHOG_MCP_ANALYTICS_SOURCE;
+exports.PostHogMCPAnalyticsEvent = PostHogMCPAnalyticsEvent;
 exports.PostHogMCPAnalyticsProperty = PostHogMCPAnalyticsProperty;
 exports.publishCustomEvent = publishCustomEvent;
 exports.track = track;