@posthog/mcp 0.0.0

package/dist/index.d.cts

@@ -0,0 +1,240 @@
+import { EventMessage, PostHogOptions } from "posthog-node";
+
+//#region src/types.d.ts
+type JsonRecord = Record<string, unknown>;
+interface MCPRequestParamsLike {
+  arguments?: JsonRecord;
+  name?: string;
+  [key: string]: unknown;
+}
+interface MCPRequestLike {
+  id?: number | string;
+  jsonrpc?: string;
+  method?: string;
+  params?: MCPRequestParamsLike;
+  [key: string]: unknown;
+}
+interface PostHogCaptureClient {
+  capture(props: EventMessage): void;
+  flush?(): Promise<void>;
+  shutdown?(shutdownTimeoutMs?: number): Promise<void>;
+}
+interface MCPAnalyticsOptions {
+  apiKey?: string | null;
+  context?: boolean | MCPAnalyticsContextOptions;
+  enableAITracing?: 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>;
+  posthogClient?: PostHogCaptureClient;
+  posthogOptions?: Pick<PostHogOptions, "fetch" | "flushAt" | "flushInterval" | "host" | "requestTimeout" | "waitUntil" | "waitUntilDebounceMs" | "waitUntilMaxWaitMs">;
+  redactSensitiveInformation?: RedactFunction;
+  reportMissing?: boolean;
+}
+interface MCPAnalyticsContextOptions {
+  description?: string;
+}
+type RedactFunction = (text: string) => Promise<string>;
+interface CompatibleRequestHandlerExtra {
+  headers?: Record<string, string | string[]>;
+  sessionId?: string;
+  [key: string]: unknown;
+}
+interface UserIdentity {
+  userData?: JsonRecord;
+  userId: string;
+  userName?: string;
+}
+interface CustomEventData {
+  apiKey?: string | null;
+  duration?: number;
+  error?: unknown;
+  isError?: boolean;
+  message?: string;
+  parameters?: unknown;
+  posthogClient?: PostHogCaptureClient;
+  properties?: JsonRecord;
+  resourceName?: string;
+  response?: unknown;
+  tags?: Record<string, string>;
+}
+//#endregion
+//#region src/modules/constants.d.ts
+declare const PostHogMCPAnalyticsProperty: {
+  readonly AiInputState: "$ai_input_state";
+  readonly AiIsError: "$ai_is_error";
+  readonly AiLatency: "$ai_latency";
+  readonly AiOutputState: "$ai_output_state";
+  readonly AiProduct: "$ai_product";
+  readonly AiSessionId: "$ai_session_id";
+  readonly AiSpanId: "$ai_span_id";
+  readonly AiSpanName: "$ai_span_name";
+  readonly AiTraceId: "$ai_trace_id";
+  readonly ClientName: "$mcp_client_name";
+  readonly ClientVersion: "$mcp_client_version";
+  readonly DurationMs: "$mcp_duration_ms";
+  readonly IsError: "$mcp_is_error";
+  readonly Intent: "$mcp_intent";
+  readonly Parameters: "$mcp_parameters";
+  readonly ResourceName: "$mcp_resource_name";
+  readonly Response: "$mcp_response";
+  readonly ServerName: "$mcp_server_name";
+  readonly ServerVersion: "$mcp_server_version";
+  readonly SessionId: "$session_id";
+  readonly Source: "$mcp_source";
+  readonly ToolName: "$mcp_tool_name";
+};
+type PostHogMCPAnalyticsProperty = (typeof PostHogMCPAnalyticsProperty)[keyof typeof PostHogMCPAnalyticsProperty];
+//#endregion
+//#region src/index.d.ts
+/**
+ * Integrates PostHog MCP into an MCP server to track tool usage patterns and user interactions.
+ *
+ * @param server - The MCP server instance to track. Must be a compatible MCP server implementation.
+ * @param options - Configuration to customize tracking behavior.
+ * @param options.apiKey - PostHog project API key (`phc_...`). Optional when using an injected `posthogClient`.
+ * @param options.host - Custom PostHog ingestion host. Defaults to `https://us.i.posthog.com`.
+ * @param options.reportMissing - Adds a "get_more_tools" tool that allows LLMs to automatically report missing functionality. Defaults to false.
+ * @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.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`.
+ * @param options.eventProperties - Callback invoked on every auto-captured event to attach flexible JSON metadata (device info, feature flags, nested context). No constraints beyond standard JSON types. If the callback throws or returns null, properties are omitted. Receives the same `(request, extra)` arguments as `identify`.
+ * @param options.posthogClient - Optional existing posthog-node compatible client. If provided, MCP events are captured with that client instead of creating a new one.
+ * @param options.posthogOptions - Optional posthog-node options used when the SDK creates its own client.
+ *
+ * @returns The tracked server instance.
+ *
+ * @remarks
+ * Analytics data and debug information are logged to `~/posthog-mcp-analytics.log` since console logs interfere
+ * with STDIO-based MCP servers.
+ *
+ * Do not call `track()` multiple times on the same server instance as this will cause unexpected behavior.
+ *
+ * @example
+ * ```typescript
+ * import { track } from "@posthog/mcp";
+ *
+ * const mcpServer = new Server({ name: "my-mcp-server", version: "1.0.0" });
+ *
+ * // Track the server with PostHog MCP
+ * track(mcpServer, { apiKey: "phc_abc123xyz" });
+ *
+ * // Register your tools
+ * mcpServer.setRequestHandler(ListToolsRequestSchema, async () => ({
+ *   tools: [{ name: "my_tool", description: "Does something useful" }]
+ * }));
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With user identification
+ * track(mcpServer, {
+ *   apiKey: "phc_abc123xyz",
+ *   identify: async (request, extra) => {
+ *     const user = await getUserFromToken(request.params.arguments.token);
+ *     return {
+ *       userId: user.id,
+ *       userData: { plan: user.plan, company: user.company }
+ *     };
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom context description
+ * track(mcpServer, {
+ *   apiKey: "phc_abc123xyz",
+ *   context: {
+ *     description: "Explain why you're calling this tool and what business objective it helps achieve"
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With sensitive data redaction
+ * track(mcpServer, {
+ *   apiKey: "phc_abc123xyz",
+ *   redactSensitiveInformation: async (text) => {
+ *     return text.replace(/api_key_\w+/g, "[REDACTED]");
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With event tags and properties
+ * track(mcpServer, {
+ *   apiKey: "phc_abc123xyz",
+ *   eventTags: async (request, extra) => ({
+ *     trace_id: extra?.requestContext?.traceId,
+ *     env: process.env.NODE_ENV,
+ *     region: "us-east-1",
+ *   }),
+ *   eventProperties: async (request, extra) => ({
+ *     device: "desktop",
+ *     app_version: "2.1.0",
+ *     feature_flags: ["dark_mode", "beta_ui"],
+ *   }),
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ */
+declare function track<TServer>(server: TServer, options?: MCPAnalyticsOptions): TServer;
+/**
+ * Publishes a custom event to PostHog MCP with flexible session management.
+ *
+ * @param serverOrSessionId - Either a tracked MCP server instance or a MCP session ID string
+ * @param eventData - Event data to include with the custom event. `apiKey` is required when publishing against a raw session ID.
+ *
+ * @returns Promise that resolves when the event is queued for publishing
+ *
+ * @example
+ * ```typescript
+ * // With a tracked server
+ * await publishCustomEvent(
+ *   server,
+ *   {
+ *     resourceName: "custom-action",
+ *     parameters: { action: "user-feedback", rating: 5 },
+ *     message: "User provided feedback"
+ *   }
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With a MCP session ID
+ * await publishCustomEvent(
+ *   "user-session-12345",
+ *   {
+ *     apiKey: "phc_abc123xyz",
+ *     isError: true,
+ *     error: { message: "Custom error occurred", code: "ERR_001" }
+ *   }
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * await publishCustomEvent(
+ *   server,
+ *   {
+ *     resourceName: "feature-usage",
+ *   }
+ * );
+ * ```
+ */
+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 };
+//# sourceMappingURL=index.d.cts.map

package/dist/index.d.mts

@@ -0,0 +1,239 @@
+import { EventMessage, PostHogOptions } from "posthog-node";
+//#region src/types.d.ts
+type JsonRecord = Record<string, unknown>;
+interface MCPRequestParamsLike {
+  arguments?: JsonRecord;
+  name?: string;
+  [key: string]: unknown;
+}
+interface MCPRequestLike {
+  id?: number | string;
+  jsonrpc?: string;
+  method?: string;
+  params?: MCPRequestParamsLike;
+  [key: string]: unknown;
+}
+interface PostHogCaptureClient {
+  capture(props: EventMessage): void;
+  flush?(): Promise<void>;
+  shutdown?(shutdownTimeoutMs?: number): Promise<void>;
+}
+interface MCPAnalyticsOptions {
+  apiKey?: string | null;
+  context?: boolean | MCPAnalyticsContextOptions;
+  enableAITracing?: 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>;
+  posthogClient?: PostHogCaptureClient;
+  posthogOptions?: Pick<PostHogOptions, "fetch" | "flushAt" | "flushInterval" | "host" | "requestTimeout" | "waitUntil" | "waitUntilDebounceMs" | "waitUntilMaxWaitMs">;
+  redactSensitiveInformation?: RedactFunction;
+  reportMissing?: boolean;
+}
+interface MCPAnalyticsContextOptions {
+  description?: string;
+}
+type RedactFunction = (text: string) => Promise<string>;
+interface CompatibleRequestHandlerExtra {
+  headers?: Record<string, string | string[]>;
+  sessionId?: string;
+  [key: string]: unknown;
+}
+interface UserIdentity {
+  userData?: JsonRecord;
+  userId: string;
+  userName?: string;
+}
+interface CustomEventData {
+  apiKey?: string | null;
+  duration?: number;
+  error?: unknown;
+  isError?: boolean;
+  message?: string;
+  parameters?: unknown;
+  posthogClient?: PostHogCaptureClient;
+  properties?: JsonRecord;
+  resourceName?: string;
+  response?: unknown;
+  tags?: Record<string, string>;
+}
+//#endregion
+//#region src/modules/constants.d.ts
+declare const PostHogMCPAnalyticsProperty: {
+  readonly AiInputState: "$ai_input_state";
+  readonly AiIsError: "$ai_is_error";
+  readonly AiLatency: "$ai_latency";
+  readonly AiOutputState: "$ai_output_state";
+  readonly AiProduct: "$ai_product";
+  readonly AiSessionId: "$ai_session_id";
+  readonly AiSpanId: "$ai_span_id";
+  readonly AiSpanName: "$ai_span_name";
+  readonly AiTraceId: "$ai_trace_id";
+  readonly ClientName: "$mcp_client_name";
+  readonly ClientVersion: "$mcp_client_version";
+  readonly DurationMs: "$mcp_duration_ms";
+  readonly IsError: "$mcp_is_error";
+  readonly Intent: "$mcp_intent";
+  readonly Parameters: "$mcp_parameters";
+  readonly ResourceName: "$mcp_resource_name";
+  readonly Response: "$mcp_response";
+  readonly ServerName: "$mcp_server_name";
+  readonly ServerVersion: "$mcp_server_version";
+  readonly SessionId: "$session_id";
+  readonly Source: "$mcp_source";
+  readonly ToolName: "$mcp_tool_name";
+};
+type PostHogMCPAnalyticsProperty = (typeof PostHogMCPAnalyticsProperty)[keyof typeof PostHogMCPAnalyticsProperty];
+//#endregion
+//#region src/index.d.ts
+/**
+ * Integrates PostHog MCP into an MCP server to track tool usage patterns and user interactions.
+ *
+ * @param server - The MCP server instance to track. Must be a compatible MCP server implementation.
+ * @param options - Configuration to customize tracking behavior.
+ * @param options.apiKey - PostHog project API key (`phc_...`). Optional when using an injected `posthogClient`.
+ * @param options.host - Custom PostHog ingestion host. Defaults to `https://us.i.posthog.com`.
+ * @param options.reportMissing - Adds a "get_more_tools" tool that allows LLMs to automatically report missing functionality. Defaults to false.
+ * @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.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`.
+ * @param options.eventProperties - Callback invoked on every auto-captured event to attach flexible JSON metadata (device info, feature flags, nested context). No constraints beyond standard JSON types. If the callback throws or returns null, properties are omitted. Receives the same `(request, extra)` arguments as `identify`.
+ * @param options.posthogClient - Optional existing posthog-node compatible client. If provided, MCP events are captured with that client instead of creating a new one.
+ * @param options.posthogOptions - Optional posthog-node options used when the SDK creates its own client.
+ *
+ * @returns The tracked server instance.
+ *
+ * @remarks
+ * Analytics data and debug information are logged to `~/posthog-mcp-analytics.log` since console logs interfere
+ * with STDIO-based MCP servers.
+ *
+ * Do not call `track()` multiple times on the same server instance as this will cause unexpected behavior.
+ *
+ * @example
+ * ```typescript
+ * import { track } from "@posthog/mcp";
+ *
+ * const mcpServer = new Server({ name: "my-mcp-server", version: "1.0.0" });
+ *
+ * // Track the server with PostHog MCP
+ * track(mcpServer, { apiKey: "phc_abc123xyz" });
+ *
+ * // Register your tools
+ * mcpServer.setRequestHandler(ListToolsRequestSchema, async () => ({
+ *   tools: [{ name: "my_tool", description: "Does something useful" }]
+ * }));
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With user identification
+ * track(mcpServer, {
+ *   apiKey: "phc_abc123xyz",
+ *   identify: async (request, extra) => {
+ *     const user = await getUserFromToken(request.params.arguments.token);
+ *     return {
+ *       userId: user.id,
+ *       userData: { plan: user.plan, company: user.company }
+ *     };
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With custom context description
+ * track(mcpServer, {
+ *   apiKey: "phc_abc123xyz",
+ *   context: {
+ *     description: "Explain why you're calling this tool and what business objective it helps achieve"
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With sensitive data redaction
+ * track(mcpServer, {
+ *   apiKey: "phc_abc123xyz",
+ *   redactSensitiveInformation: async (text) => {
+ *     return text.replace(/api_key_\w+/g, "[REDACTED]");
+ *   }
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With event tags and properties
+ * track(mcpServer, {
+ *   apiKey: "phc_abc123xyz",
+ *   eventTags: async (request, extra) => ({
+ *     trace_id: extra?.requestContext?.traceId,
+ *     env: process.env.NODE_ENV,
+ *     region: "us-east-1",
+ *   }),
+ *   eventProperties: async (request, extra) => ({
+ *     device: "desktop",
+ *     app_version: "2.1.0",
+ *     feature_flags: ["dark_mode", "beta_ui"],
+ *   }),
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ */
+declare function track<TServer>(server: TServer, options?: MCPAnalyticsOptions): TServer;
+/**
+ * Publishes a custom event to PostHog MCP with flexible session management.
+ *
+ * @param serverOrSessionId - Either a tracked MCP server instance or a MCP session ID string
+ * @param eventData - Event data to include with the custom event. `apiKey` is required when publishing against a raw session ID.
+ *
+ * @returns Promise that resolves when the event is queued for publishing
+ *
+ * @example
+ * ```typescript
+ * // With a tracked server
+ * await publishCustomEvent(
+ *   server,
+ *   {
+ *     resourceName: "custom-action",
+ *     parameters: { action: "user-feedback", rating: 5 },
+ *     message: "User provided feedback"
+ *   }
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With a MCP session ID
+ * await publishCustomEvent(
+ *   "user-session-12345",
+ *   {
+ *     apiKey: "phc_abc123xyz",
+ *     isError: true,
+ *     error: { message: "Custom error occurred", code: "ERR_001" }
+ *   }
+ * );
+ * ```
+ *
+ * @example
+ * ```typescript
+ * await publishCustomEvent(
+ *   server,
+ *   {
+ *     resourceName: "feature-usage",
+ *   }
+ * );
+ * ```
+ */
+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 };
+//# sourceMappingURL=index.d.mts.map