@posthog/mcp 0.0.2 → 0.0.4

package/dist/index.d.cts

@@ -23,11 +23,13 @@ interface MCPAnalyticsOptions {
   apiKey?: string | null;
   context?: boolean | MCPAnalyticsContextOptions;
   enableAITracing?: boolean;
+  enableConversationId?: boolean;
   enableTracing?: boolean;
   eventProperties?: (request: MCPRequestLike, extra?: CompatibleRequestHandlerExtra) => JsonRecord | null | Promise<JsonRecord | null>;
   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 +38,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 +66,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";
@@ -74,9 +93,11 @@ declare const PostHogMCPAnalyticsProperty: {
   readonly AiTraceId: "$ai_trace_id";
   readonly ClientName: "$mcp_client_name";
   readonly ClientVersion: "$mcp_client_version";
+  readonly ConversationId: "$mcp_conversation_id";
   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 +121,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 +258,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

@@ -22,11 +22,13 @@ interface MCPAnalyticsOptions {
   apiKey?: string | null;
   context?: boolean | MCPAnalyticsContextOptions;
   enableAITracing?: boolean;
+  enableConversationId?: boolean;
   enableTracing?: boolean;
   eventProperties?: (request: MCPRequestLike, extra?: CompatibleRequestHandlerExtra) => JsonRecord | null | Promise<JsonRecord | null>;
   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 +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[]>;
@@ -61,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";
@@ -73,9 +92,11 @@ declare const PostHogMCPAnalyticsProperty: {
   readonly AiTraceId: "$ai_trace_id";
   readonly ClientName: "$mcp_client_name";
   readonly ClientVersion: "$mcp_client_version";
+  readonly ConversationId: "$mcp_conversation_id";
   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 +120,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 +257,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