@posthog/mcp 0.0.1 → 0.0.3

package/dist/index.d.cts

@@ -28,6 +28,7 @@ interface MCPAnalyticsOptions {
   eventTags?: (request: MCPRequestLike, extra?: CompatibleRequestHandlerExtra) => Record<string, string> | null | Promise<Record<string, string> | null>;
   host?: string;
   identify?: (request: MCPRequestLike, extra?: CompatibleRequestHandlerExtra) => Promise<UserIdentity | null>;
+  intentFallback?: (request: MCPRequestLike, extra?: CompatibleRequestHandlerExtra) => MaybePromise<string | null | undefined>;
   posthogClient?: PostHogCaptureClient;
   posthogOptions?: Pick<PostHogOptions, "fetch" | "flushAt" | "flushInterval" | "host" | "requestTimeout" | "waitUntil" | "waitUntilDebounceMs" | "waitUntilMaxWaitMs">;
   redactSensitiveInformation?: RedactFunction;
@@ -36,6 +37,8 @@ interface MCPAnalyticsOptions {
 interface MCPAnalyticsContextOptions {
   description?: string;
 }
+type MaybePromise<T> = T | Promise<T>;
+type MCPAnalyticsIntentSource = "context_parameter" | "inferred";
 type RedactFunction = (text: string) => Promise<string>;
 interface CompatibleRequestHandlerExtra {
   headers?: Record<string, string | string[]>;
@@ -62,6 +65,21 @@ interface CustomEventData {
 }
 //#endregion
 //#region src/modules/constants.d.ts
+declare const POSTHOG_MCP_ANALYTICS_SOURCE = "posthog_mcp_analytics";
+declare const PostHogMCPAnalyticsEvent: {
+  readonly AiSpan: "$ai_span";
+  readonly Custom: "mcp_custom";
+  readonly Exception: "$exception";
+  readonly Identify: "$identify";
+  readonly Initialize: "mcp_initialize";
+  readonly PromptGet: "mcp_prompt_get";
+  readonly PromptsList: "mcp_prompts_list";
+  readonly ResourceRead: "mcp_resource_read";
+  readonly ResourcesList: "mcp_resources_list";
+  readonly ToolCall: "mcp_tool_call";
+  readonly ToolsList: "mcp_tools_list";
+};
+type PostHogMCPAnalyticsEvent = (typeof PostHogMCPAnalyticsEvent)[keyof typeof PostHogMCPAnalyticsEvent];
 declare const PostHogMCPAnalyticsProperty: {
   readonly AiInputState: "$ai_input_state";
   readonly AiIsError: "$ai_is_error";
@@ -77,6 +95,7 @@ declare const PostHogMCPAnalyticsProperty: {
   readonly DurationMs: "$mcp_duration_ms";
   readonly IsError: "$mcp_is_error";
   readonly Intent: "$mcp_intent";
+  readonly IntentSource: "$mcp_intent_source";
   readonly Parameters: "$mcp_parameters";
   readonly ResourceName: "$mcp_resource_name";
   readonly Response: "$mcp_response";
@@ -100,6 +119,7 @@ type PostHogMCPAnalyticsProperty = (typeof PostHogMCPAnalyticsProperty)[keyof ty
  * @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`.
@@ -236,5 +256,5 @@ declare function track<TServer>(server: TServer, options?: MCPAnalyticsOptions):
 declare function publishCustomEvent(serverOrSessionId: unknown, eventData?: CustomEventData): Promise<void>;
 type IdentifyFunction = MCPAnalyticsOptions["identify"];
 //#endregion
-export { type CustomEventData, IdentifyFunction, type MCPAnalyticsContextOptions, type MCPAnalyticsOptions, PostHogMCPAnalyticsProperty, type RedactFunction, type UserIdentity, publishCustomEvent, track };
+export { type CustomEventData, IdentifyFunction, type MCPAnalyticsContextOptions, type MCPAnalyticsIntentSource, type MCPAnalyticsOptions, POSTHOG_MCP_ANALYTICS_SOURCE, PostHogMCPAnalyticsEvent, PostHogMCPAnalyticsProperty, type RedactFunction, type UserIdentity, publishCustomEvent, track };
 //# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -27,6 +27,7 @@ interface MCPAnalyticsOptions {
   eventTags?: (request: MCPRequestLike, extra?: CompatibleRequestHandlerExtra) => Record<string, string> | null | Promise<Record<string, string> | null>;
   host?: string;
   identify?: (request: MCPRequestLike, extra?: CompatibleRequestHandlerExtra) => Promise<UserIdentity | null>;
+  intentFallback?: (request: MCPRequestLike, extra?: CompatibleRequestHandlerExtra) => MaybePromise<string | null | undefined>;
   posthogClient?: PostHogCaptureClient;
   posthogOptions?: Pick<PostHogOptions, "fetch" | "flushAt" | "flushInterval" | "host" | "requestTimeout" | "waitUntil" | "waitUntilDebounceMs" | "waitUntilMaxWaitMs">;
   redactSensitiveInformation?: RedactFunction;
@@ -35,6 +36,8 @@ interface MCPAnalyticsOptions {
 interface MCPAnalyticsContextOptions {
   description?: string;
 }
+type MaybePromise<T> = T | Promise<T>;
+type MCPAnalyticsIntentSource = "context_parameter" | "inferred";
 type RedactFunction = (text: string) => Promise<string>;
 interface CompatibleRequestHandlerExtra {
   headers?: Record<string, string | string[]>;
@@ -61,6 +64,21 @@ interface CustomEventData {
 }
 //#endregion
 //#region src/modules/constants.d.ts
+declare const POSTHOG_MCP_ANALYTICS_SOURCE = "posthog_mcp_analytics";
+declare const PostHogMCPAnalyticsEvent: {
+  readonly AiSpan: "$ai_span";
+  readonly Custom: "mcp_custom";
+  readonly Exception: "$exception";
+  readonly Identify: "$identify";
+  readonly Initialize: "mcp_initialize";
+  readonly PromptGet: "mcp_prompt_get";
+  readonly PromptsList: "mcp_prompts_list";
+  readonly ResourceRead: "mcp_resource_read";
+  readonly ResourcesList: "mcp_resources_list";
+  readonly ToolCall: "mcp_tool_call";
+  readonly ToolsList: "mcp_tools_list";
+};
+type PostHogMCPAnalyticsEvent = (typeof PostHogMCPAnalyticsEvent)[keyof typeof PostHogMCPAnalyticsEvent];
 declare const PostHogMCPAnalyticsProperty: {
   readonly AiInputState: "$ai_input_state";
   readonly AiIsError: "$ai_is_error";
@@ -76,6 +94,7 @@ declare const PostHogMCPAnalyticsProperty: {
   readonly DurationMs: "$mcp_duration_ms";
   readonly IsError: "$mcp_is_error";
   readonly Intent: "$mcp_intent";
+  readonly IntentSource: "$mcp_intent_source";
   readonly Parameters: "$mcp_parameters";
   readonly ResourceName: "$mcp_resource_name";
   readonly Response: "$mcp_response";
@@ -99,6 +118,7 @@ type PostHogMCPAnalyticsProperty = (typeof PostHogMCPAnalyticsProperty)[keyof ty
  * @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`.
@@ -235,5 +255,5 @@ declare function track<TServer>(server: TServer, options?: MCPAnalyticsOptions):
 declare function publishCustomEvent(serverOrSessionId: unknown, eventData?: CustomEventData): Promise<void>;
 type IdentifyFunction = MCPAnalyticsOptions["identify"];
 //#endregion
-export { type CustomEventData, IdentifyFunction, type MCPAnalyticsContextOptions, type MCPAnalyticsOptions, PostHogMCPAnalyticsProperty, type RedactFunction, type UserIdentity, publishCustomEvent, track };
+export { type CustomEventData, IdentifyFunction, type MCPAnalyticsContextOptions, type MCPAnalyticsIntentSource, type MCPAnalyticsOptions, POSTHOG_MCP_ANALYTICS_SOURCE, PostHogMCPAnalyticsEvent, PostHogMCPAnalyticsProperty, type RedactFunction, type UserIdentity, publishCustomEvent, track };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -119,15 +119,14 @@ function getMCPCompatibleErrorMessage(error) {
 	return "Unknown error";
 }
 //#endregion
-//#region src/modules/ids.ts
-function newPrefixedId(prefix) {
-	return `${prefix}_${randomUUID()}`;
-}
-function deterministicPrefixedId(prefix, input) {
-	return `${prefix}_${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",
@@ -140,6 +139,14 @@ const MCPAnalyticsEventType = {
 	mcpToolsList: "mcp:tools/list"
 };
 //#endregion
+//#region src/modules/ids.ts
+function newPrefixedId(prefix) {
+	return `${prefix}_${randomUUID()}`;
+}
+function deterministicPrefixedId(prefix, input) {
+	return `${prefix}_${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,6 +350,19 @@ function getRequestResourceName(request) {
 //#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 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",
@@ -358,6 +378,7 @@ const PostHogMCPAnalyticsProperty = {
 	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",
@@ -369,8 +390,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";
 }
@@ -385,7 +415,6 @@ 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,
@@ -395,7 +424,7 @@ function buildCaptureEvent(event, options) {
 	addTraceReferenceProperties(event, properties, options);
 	addCustomEventProperties(event, properties);
 	return {
-		event: eventName,
+		event: BUILT_IN_EVENT_NAME_BY_TYPE[event.eventType],
 		distinct_id: distinctId,
 		properties,
 		timestamp,
@@ -427,6 +456,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;
@@ -460,7 +490,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,
@@ -486,27 +516,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
 /**
@@ -700,7 +720,7 @@ function sanitizeParameters(obj) {
 }
 //#endregion
 //#region package.json
-var version = "0.0.1";
+var version = "0.0.3";
 //#endregion
 //#region src/modules/session.ts
 function newSessionId() {
@@ -1084,7 +1104,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;
@@ -1147,7 +1166,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,
@@ -1164,6 +1183,7 @@ function publishEvent(server, eventInput) {
 		parameters: eventInput.parameters,
 		response: eventInput.response,
 		userIntent: eventInput.userIntent,
+		userIntentSource: eventInput.userIntentSource,
 		isError: eventInput.isError,
 		error: eventInput.error,
 		redactionFn: eventInput.redactionFn,
@@ -1902,6 +1922,49 @@ function setupMCPAnalyticsTools(server) {
 	}
 }
 //#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;
@@ -2049,18 +2112,20 @@ 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);
+		setEventIntent(event, await resolveToolCallIntent(data, request, extra));
 		const result = await executeToolCall(server, originalCallToolHandler, request, extra, event);
 		if (isToolResultError$1(result)) {
 			event.isError = true;
 			event.error = captureException(result);
-		}
+		} else event.isError = false;
 		event.response = result;
+		event.duration = getEventDuration(event);
 		publishEvent(server, event);
 		return result;
 	} catch (error) {
 		event.isError = true;
 		event.error = captureException(error);
+		event.duration = getEventDuration(event);
 		publishEvent(server, event);
 		throw error;
 	}
@@ -2068,7 +2133,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);
@@ -2084,11 +2149,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;
@@ -2322,8 +2382,7 @@ 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,
 			shouldPublishEvent: true
@@ -2346,7 +2405,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);
@@ -2374,12 +2436,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);
@@ -2416,6 +2481,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`.
@@ -2543,6 +2609,7 @@ 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,
@@ -2687,6 +2754,6 @@ function publishResolvedCustomEvent(target, event) {
 	eventQueue.add(event);
 }
 //#endregion
-export { PostHogMCPAnalyticsProperty, publishCustomEvent, track };
+export { POSTHOG_MCP_ANALYTICS_SOURCE, PostHogMCPAnalyticsEvent, PostHogMCPAnalyticsProperty, publishCustomEvent, track };
 
 //# sourceMappingURL=index.mjs.map