@posthog/mcp 0.0.1 → 0.0.3

package/README.md

@@ -2,7 +2,7 @@
 
 TypeScript SDK for instrumenting Model Context Protocol servers with PostHog analytics.
 
-> [!WARNING]
+> Warning:
 > This package is in very early access and is not suitable for production use yet.
 > The API, event names, PostHog property schema, tracing behavior, and release process may change without notice while we dogfood the SDK.
 > We publish in public because PostHog builds in public, but you should treat `0.0.x` releases as experimental.
@@ -34,6 +34,21 @@ 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.
 
@@ -52,6 +67,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;
@@ -344,6 +351,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",
@@ -359,6 +379,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",
@@ -370,8 +391,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,7 +416,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,
@@ -396,7 +425,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,
@@ -428,6 +457,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;
@@ -461,7 +491,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,
@@ -487,27 +517,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 +721,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() {
@@ -1085,7 +1105,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 +1167,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,6 +1184,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,
@@ -1903,6 +1923,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;
@@ -2050,18 +2113,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;
 	}
@@ -2069,7 +2134,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 +2150,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;
@@ -2323,8 +2383,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
@@ -2347,7 +2406,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);
@@ -2375,12 +2437,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 +2482,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,6 +2610,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,
@@ -2688,6 +2755,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;