@posthog/mcp 0.0.8 → 0.1.16

package/src/extensions/constants.ts

@@ -0,0 +1,48 @@
+export const INACTIVITY_TIMEOUT_IN_MINUTES = 30
+
+export 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."`
+
+export 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."
+
+export const POSTHOG_MCP_ANALYTICS_SOURCE = 'posthog_mcp_analytics'
+
+// All PostHog-owned event names start with `$` per the PostHog convention.
+// Non-`$` names would be treated as customer-defined events and confuse the schema.
+export const PostHogMCPAnalyticsEvent = {
+  Custom: '$mcp_custom',
+  Exception: '$exception',
+  Identify: '$identify',
+  Initialize: '$mcp_initialize',
+  MissingCapability: '$mcp_missing_capability',
+  PromptGet: '$mcp_prompt_get',
+  PromptsList: '$mcp_prompts_list',
+  ResourceRead: '$mcp_resource_read',
+  ResourcesList: '$mcp_resources_list',
+  ToolCall: '$mcp_tool_call',
+  ToolsList: '$mcp_tools_list',
+} as const
+
+export type PostHogMCPAnalyticsEvent = (typeof PostHogMCPAnalyticsEvent)[keyof typeof PostHogMCPAnalyticsEvent]
+
+export const PostHogMCPAnalyticsProperty = {
+  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',
+  ListedToolNames: '$mcp_listed_tool_names',
+  Parameters: '$mcp_parameters',
+  ResourceName: '$mcp_resource_name',
+  Response: '$mcp_response',
+  ServerName: '$mcp_server_name',
+  ServerVersion: '$mcp_server_version',
+  SessionId: '$session_id',
+  Source: '$mcp_source',
+  ToolDescription: '$mcp_tool_description',
+  ToolName: '$mcp_tool_name',
+} as const
+
+export type PostHogMCPAnalyticsProperty = (typeof PostHogMCPAnalyticsProperty)[keyof typeof PostHogMCPAnalyticsProperty]

package/src/extensions/context-parameters.ts

@@ -0,0 +1,119 @@
+import type { MCPAnalyticsOptions } from '../types'
+import { DEFAULT_CONTEXT_PARAMETER_DESCRIPTION } from './constants'
+import { log } from './logger'
+
+interface JsonSchema {
+  additionalProperties?: boolean
+  allOf?: unknown
+  anyOf?: unknown
+  oneOf?: unknown
+  properties?: Record<string, unknown>
+  required?: string[]
+  type?: string
+}
+
+export interface ContextInjectableTool {
+  inputSchema?: JsonSchema
+  name?: string
+  [key: string]: unknown
+}
+
+export function isContextEnabled(context: MCPAnalyticsOptions['context']): boolean {
+  return context !== false
+}
+
+export function getContextDescription(context: MCPAnalyticsOptions['context']): string | undefined {
+  return typeof context === 'object' ? context.description : undefined
+}
+
+/**
+ * Adds a context parameter to a tool's JSON Schema.
+ * This function is called AFTER the MCP SDK has converted Zod schemas to JSON Schema,
+ * so we only need to handle JSON Schema format.
+ *
+ * Skips injection (with warning) for:
+ * - Tools that already have a 'context' parameter
+ * - Complex schemas (oneOf/allOf/anyOf) that can't safely have properties added
+ * - Schemas with additionalProperties: false
+ */
+export function addContextParameterToTool<TTool extends ContextInjectableTool>(
+  tool: TTool,
+  contextDescriptionOverride?: string
+): TTool {
+  // Create a shallow copy of the tool to avoid modifying the original
+  const modifiedTool = { ...tool }
+  const toolName = tool.name || 'unknown'
+  const schema = modifiedTool.inputSchema as JsonSchema | undefined
+
+  // Check if tool already has context parameter - skip to avoid collision
+  if (schema?.properties?.context) {
+    log(`WARN: Tool "${toolName}" already has 'context' parameter. Skipping context injection.`)
+    return modifiedTool
+  }
+
+  // Skip complex schemas that can't safely have properties added at root level
+  if (schema?.oneOf || schema?.allOf || schema?.anyOf) {
+    log(`WARN: Tool "${toolName}" has complex schema (oneOf/allOf/anyOf). Skipping context injection.`)
+    return modifiedTool
+  }
+
+  // Note: If additionalProperties is false, we'll need to remove that constraint
+  // when adding context, otherwise the schema would be invalid. We handle this
+  // after the deep copy below.
+
+  if (!modifiedTool.inputSchema) {
+    modifiedTool.inputSchema = {
+      type: 'object',
+      properties: {},
+      required: [],
+    }
+  }
+
+  const contextDescription = contextDescriptionOverride || DEFAULT_CONTEXT_PARAMETER_DESCRIPTION
+
+  // Deep copy the inputSchema to avoid mutations
+  modifiedTool.inputSchema = JSON.parse(JSON.stringify(modifiedTool.inputSchema)) as JsonSchema
+
+  const inputSchema = modifiedTool.inputSchema as JsonSchema
+
+  // Ensure properties object exists
+  if (!inputSchema.properties) {
+    inputSchema.properties = {}
+  }
+
+  // Handle additionalProperties: false - must remove this constraint since we're adding context
+  // The MCP SDK adds this constraint when converting Zod schemas to JSON Schema
+  if (inputSchema.additionalProperties === false) {
+    inputSchema.additionalProperties = undefined
+  }
+
+  // Add context property
+  inputSchema.properties.context = {
+    type: 'string',
+    description: contextDescription,
+  }
+
+  // Add context to required array
+  if (Array.isArray(inputSchema.required)) {
+    if (!inputSchema.required.includes('context')) {
+      inputSchema.required.push('context')
+    }
+  } else {
+    inputSchema.required = ['context']
+  }
+
+  return modifiedTool
+}
+
+export function addContextParameterToTools<TTool extends ContextInjectableTool>(
+  tools: TTool[],
+  contextDescriptionOverride?: string
+): TTool[] {
+  return tools.map((tool) => {
+    // Skip get_more_tools - it has its own special context parameter
+    if (tool.name === 'get_more_tools') {
+      return tool
+    }
+    return addContextParameterToTool(tool, contextDescriptionOverride)
+  })
+}

package/src/extensions/conversation-id.ts

@@ -0,0 +1,177 @@
+import { uuidv7 } from '@posthog/core'
+import { DEFAULT_CONVERSATION_ID_DESCRIPTION } from './constants'
+import { log } from './logger'
+import { GET_MORE_TOOLS_NAME } from './tools'
+
+export const CONVERSATION_ID_PARAM_NAME = 'conversation_id'
+
+interface JsonSchema {
+  additionalProperties?: boolean
+  allOf?: unknown
+  anyOf?: unknown
+  oneOf?: unknown
+  properties?: Record<string, unknown>
+  required?: string[]
+  type?: string
+}
+
+export interface ConversationIdInjectableTool {
+  inputSchema?: JsonSchema
+  name?: string
+  [key: string]: unknown
+}
+
+export function addConversationIdToTool<TTool extends ConversationIdInjectableTool>(tool: TTool): TTool {
+  const modifiedTool = { ...tool }
+  const toolName = tool.name || 'unknown'
+  const schema = modifiedTool.inputSchema as JsonSchema | undefined
+
+  if (schema?.properties?.[CONVERSATION_ID_PARAM_NAME]) {
+    log(
+      `WARN: Tool "${toolName}" already has '${CONVERSATION_ID_PARAM_NAME}' parameter. Skipping conversation_id injection.`
+    )
+    return modifiedTool
+  }
+
+  if (schema?.oneOf || schema?.allOf || schema?.anyOf) {
+    log(`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)) as JsonSchema
+
+  const inputSchema = modifiedTool.inputSchema as JsonSchema
+
+  if (!inputSchema.properties) {
+    inputSchema.properties = {}
+  }
+
+  if (inputSchema.additionalProperties === false) {
+    inputSchema.additionalProperties = undefined
+  }
+
+  inputSchema.properties[CONVERSATION_ID_PARAM_NAME] = {
+    type: 'string',
+    description: DEFAULT_CONVERSATION_ID_DESCRIPTION,
+  }
+
+  return modifiedTool
+}
+
+export function addConversationIdToTools<TTool extends ConversationIdInjectableTool>(tools: TTool[]): TTool[] {
+  return tools.map((tool) => {
+    if (tool.name === GET_MORE_TOOLS_NAME) {
+      return tool
+    }
+    return addConversationIdToTool(tool)
+  })
+}
+
+export type ConversationIdResolution =
+  | { minted: false; conversationId: string | undefined }
+  | { minted: true; conversationId: string }
+
+/**
+ * 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
+ */
+export function resolveConversationId(
+  enabled: boolean,
+  args: unknown,
+  toolName: string | undefined
+): ConversationIdResolution {
+  if (!enabled || toolName === GET_MORE_TOOLS_NAME) {
+    return { minted: false, conversationId: undefined }
+  }
+  const supplied = extractConversationId(args)
+  if (supplied) {
+    return { minted: false, conversationId: supplied }
+  }
+  return { minted: true, conversationId: uuidv7() }
+}
+
+/**
+ * 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).
+ */
+export function canInjectConversationIdPromptBack(result: unknown): boolean {
+  if (!(result && typeof result === 'object')) {
+    return false
+  }
+  const resultObj = result as { content?: unknown; isError?: unknown }
+  if (resultObj.isError === true) {
+    return false
+  }
+  return Array.isArray(resultObj.content)
+}
+
+export function extractConversationId(args: unknown): string | undefined {
+  if (!(args && typeof args === 'object')) {
+    return
+  }
+  const value = (args as Record<string, unknown>)[CONVERSATION_ID_PARAM_NAME]
+  if (typeof value !== 'string') {
+    return
+  }
+  const trimmed = value.trim()
+  return trimmed.length > 0 ? trimmed : undefined
+}
+
+export function cloneRequestWithoutConversationId<
+  TRequest extends { params?: { arguments?: unknown; [k: string]: unknown } },
+>(request: TRequest): TRequest {
+  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) as typeof request.params.arguments,
+    },
+  }
+}
+
+export function stripConversationId(args: unknown): unknown {
+  if (!args || typeof args !== 'object' || !(CONVERSATION_ID_PARAM_NAME in (args as Record<string, unknown>))) {
+    return args
+  }
+  const { [CONVERSATION_ID_PARAM_NAME]: _omit, ...rest } = args as Record<string, unknown>
+  return rest
+}
+
+export function buildConversationIdPromptBack(conversationId: string): {
+  type: 'text'
+  text: string
+} {
+  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.`,
+  }
+}
+
+export function injectConversationIdPromptBack(result: unknown, conversationId: string): unknown {
+  if (!canInjectConversationIdPromptBack(result)) {
+    return result
+  }
+  const resultObj = result as { content: unknown[] }
+  return {
+    ...resultObj,
+    content: [...resultObj.content, buildConversationIdPromptBack(conversationId)],
+  }
+}

package/src/extensions/event-types.ts

@@ -0,0 +1,21 @@
+/**
+ * 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.
+ */
+export const MCPAnalyticsEventType = {
+  identify: 'posthog:identify',
+  custom: 'posthog:custom',
+  mcpMissingCapability: 'mcp:missing_capability',
+  mcpInitialize: 'mcp:initialize',
+  mcpPromptsGet: 'mcp:prompts/get',
+  mcpPromptsList: 'mcp:prompts/list',
+  mcpResourcesList: 'mcp:resources/list',
+  mcpResourcesRead: 'mcp:resources/read',
+  mcpToolsCall: 'mcp:tools/call',
+  mcpToolsList: 'mcp:tools/list',
+} as const
+
+export type MCPAnalyticsEventType = (typeof MCPAnalyticsEventType)[keyof typeof MCPAnalyticsEventType]

package/src/extensions/exceptions.ts

@@ -0,0 +1,83 @@
+import { ErrorTracking as CoreErrorTracking } from '@posthog/core'
+
+/**
+ * Builds PostHog error-tracking properties (`$exception_list`) from arbitrary
+ * thrown values, reusing `@posthog/core`'s shared coercers + stack parser
+ * instead of a bespoke V8 parser. Mirrors how `posthog-node` constructs its
+ * builder, minus the Node-only frame modifiers (source context, relative
+ * paths) which live in the `posthog-node` package and require async fs access.
+ */
+const errorPropertiesBuilder = new CoreErrorTracking.ErrorPropertiesBuilder(
+  [
+    new CoreErrorTracking.EventCoercer(),
+    new CoreErrorTracking.ErrorCoercer(),
+    new CoreErrorTracking.ObjectCoercer(),
+    new CoreErrorTracking.StringCoercer(),
+    new CoreErrorTracking.PrimitiveCoercer(),
+  ],
+  CoreErrorTracking.createStackParser('node:javascript', CoreErrorTracking.nodeStackLineParser)
+)
+
+interface CallToolContentPart {
+  text?: unknown
+  type?: unknown
+}
+
+interface CallToolResult {
+  content: unknown[]
+  isError: unknown
+}
+
+/**
+ * Captures structured exception properties from any thrown value.
+ *
+ * Returns the `$exception_list` shape PostHog error tracking expects, so MCP
+ * tool failures group and (with uploaded source maps) symbolicate the same way
+ * as exceptions from any other PostHog SDK.
+ *
+ * @param error - The thrown value (Error, string, object, CallToolResult, or anything).
+ * @returns Core `ErrorProperties` ready to spread onto a `$exception` event.
+ */
+export function captureException(error: unknown): CoreErrorTracking.ErrorProperties {
+  // MCP SDK 1.21.0+ converts tool errors to CallToolResult, which the core
+  // coercers don't recognize. Extract the human-readable message first so the
+  // exception still carries something useful.
+  const normalized = isCallToolResult(error) ? extractCallToolResultMessage(error) : error
+  return errorPropertiesBuilder.buildFromUnknown(normalized)
+}
+
+/**
+ * Detects a CallToolResult error object (SDK 1.21.0+ format):
+ * `{ content: [{ type: "text", text: "..." }], isError: true }`.
+ */
+function isCallToolResult(value: unknown): value is CallToolResult {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    'isError' in value &&
+    'content' in value &&
+    Array.isArray((value as { content?: unknown }).content)
+  )
+}
+
+function isTextContentPart(value: unknown): value is { text: string } {
+  if (value === null || typeof value !== 'object') {
+    return false
+  }
+  const contentPart = value as CallToolContentPart
+  return contentPart.type === 'text' && typeof contentPart.text === 'string'
+}
+
+/**
+ * Extracts the concatenated text from a CallToolResult's content array.
+ * The SDK strips the original Error, so only the message survives.
+ */
+function extractCallToolResultMessage(result: CallToolResult): string {
+  return (
+    result.content
+      .filter(isTextContentPart)
+      .map((contentPart) => contentPart.text)
+      .join(' ')
+      .trim() || 'Unknown error'
+  )
+}

package/src/extensions/ids.ts

@@ -0,0 +1,32 @@
+import { uuidv7 } from '@posthog/core'
+
+export type MCPAnalyticsIDPrefix = 'evt' | 'ses'
+
+export function newPrefixedId(prefix: MCPAnalyticsIDPrefix): string {
+  return `${prefix}_${uuidv7()}`
+}
+
+/**
+ * Deterministic id derived from an arbitrary string. Used to map MCP protocol
+ * session ids to SDK session ids so the same MCP session reuses the same
+ * `$session_id` across server restarts.
+ *
+ * Uses the FNV-1a 64-bit hash (mixed twice to fill 32 hex chars), which works
+ * everywhere — no `node:crypto`, no Web Crypto async API. Not cryptographic; we
+ * only need stable, low-collision input → output mapping.
+ */
+export function deterministicPrefixedId(prefix: MCPAnalyticsIDPrefix, input: string): string {
+  return `${prefix}_${fnv1aHex(input)}${fnv1aHex(`${input}::salt`)}`
+}
+
+function fnv1aHex(input: string): string {
+  // 64-bit FNV-1a implemented with two 32-bit halves to stay within safe-integer range.
+  let h1 = 0x84222325
+  let h2 = 0xcbf29ce4
+  for (let i = 0; i < input.length; i++) {
+    const c = input.charCodeAt(i)
+    h1 = Math.imul(h1 ^ c, 0x000001b3)
+    h2 = Math.imul(h2 ^ c, 0x00000193)
+  }
+  return (h1 >>> 0).toString(16).padStart(8, '0') + (h2 >>> 0).toString(16).padStart(8, '0')
+}