@posthog/mcp 0.7.0 → 0.9.0

package/src/extensions/session-token.ts

@@ -0,0 +1,168 @@
+/**
+ * Self-encoded session tokens for stateless / multi-pod MCP servers.
+ *
+ * A stateless server keeps nothing between requests, so every request starts a
+ * new session and the client name/version (only sent at `initialize`) is lost.
+ * The one value clients replay on every request is the `Mcp-Session-Id` header.
+ * So at `initialize` we mint that header as a token carrying the session id and
+ * client identity — any pod can read them back from the header alone.
+ *
+ * The token is unsigned: it holds only what the client already self-reports.
+ */
+
+export const MCP_SESSION_HEADER = 'mcp-session-id'
+
+/** What a session token carries. */
+export interface SessionTokenPayload {
+  /** PostHog session id (`ses_…`) → `$session_id`. */
+  sessionId: string
+  /** MCP client name → `$mcp_client_name`. */
+  clientName?: string
+  /** MCP client version → `$mcp_client_version`. */
+  clientVersion?: string
+}
+
+// On the wire the token is base64url(JSON) with shortened keys to keep the
+// header small: sid = sessionId, cn = clientName, cv = clientVersion.
+const MAX_TOKEN_LENGTH = 4096
+const MAX_SESSION_ID_LENGTH = 128
+const MAX_CLIENT_FIELD_LENGTH = 200
+
+const BASE64URL_PATTERN = /^[A-Za-z0-9_-]+={0,2}$/
+
+/**
+ * Encodes a session token for the `Mcp-Session-Id` response header. Also
+ * exported for SSE servers, which flush headers before handlers run and so
+ * must set the header themselves at the HTTP layer.
+ */
+export function encodeSessionId(payload: SessionTokenPayload): string {
+  if (!payload || typeof payload.sessionId !== 'string' || payload.sessionId.length === 0) {
+    throw new Error('encodeSessionId requires a non-empty `sessionId` (use newSessionId())')
+  }
+  const wire: Record<string, string> = { sid: payload.sessionId }
+  if (typeof payload.clientName === 'string' && payload.clientName.length > 0) {
+    wire.cn = payload.clientName.slice(0, MAX_CLIENT_FIELD_LENGTH)
+  }
+  if (typeof payload.clientVersion === 'string' && payload.clientVersion.length > 0) {
+    wire.cv = payload.clientVersion.slice(0, MAX_CLIENT_FIELD_LENGTH)
+  }
+  return utf8ToBase64Url(JSON.stringify(wire))
+}
+
+/**
+ * Decodes an `Mcp-Session-Id` value into a token payload. Returns `null` for
+ * anything that isn't one of our tokens (transport UUIDs, JWTs, garbage) and
+ * never throws.
+ */
+export function decodeSessionId(value: unknown): SessionTokenPayload | null {
+  if (typeof value !== 'string' || value.length === 0 || value.length > MAX_TOKEN_LENGTH) {
+    return null
+  }
+  // JWTs carry dots; UUIDs pass this check but fail JSON.parse below.
+  if (!BASE64URL_PATTERN.test(value)) {
+    return null
+  }
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(base64UrlToUtf8(value))
+  } catch {
+    return null
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    return null
+  }
+  const wire = parsed as Record<string, unknown>
+  if (typeof wire.sid !== 'string' || wire.sid.length === 0 || wire.sid.length > MAX_SESSION_ID_LENGTH) {
+    return null
+  }
+  const payload: SessionTokenPayload = { sessionId: wire.sid }
+  // A bad cn/cv just means no client info — it does not reject the token.
+  if (typeof wire.cn === 'string' && wire.cn.length > 0) {
+    payload.clientName = wire.cn.slice(0, MAX_CLIENT_FIELD_LENGTH)
+  }
+  if (typeof wire.cv === 'string' && wire.cv.length > 0) {
+    payload.clientVersion = wire.cv.slice(0, MAX_CLIENT_FIELD_LENGTH)
+  }
+  return payload
+}
+
+/**
+ * Reads the `mcp-session-id` header off `extra.requestInfo.headers`. The SDK
+ * transports lowercase header keys; the fallback scan covers hand-built extras.
+ */
+export function readMcpSessionHeader(headers: unknown): string | undefined {
+  if (!headers || typeof headers !== 'object') {
+    return undefined
+  }
+  const record = headers as Record<string, unknown>
+  let value = record[MCP_SESSION_HEADER]
+  if (value === undefined) {
+    const key = Object.keys(record).find((k) => k.toLowerCase() === MCP_SESSION_HEADER)
+    value = key === undefined ? undefined : record[key]
+  }
+  const first = Array.isArray(value) ? value[0] : value
+  if (typeof first !== 'string') {
+    return undefined
+  }
+  const trimmed = first.trim()
+  return trimmed.length > 0 ? trimmed : undefined
+}
+
+/**
+ * Puts a minted token on the transport so it goes out as the `Mcp-Session-Id`
+ * response header. The Node transport's `sessionId` is a getter backed by an
+ * inner web-standard transport, so verify the write by reading back and fall
+ * back to writing the inner one. Returns whether the write stuck; never throws.
+ */
+export function writeSessionIdToTransport(transport: unknown, token: string): boolean {
+  if (!transport || typeof transport !== 'object') {
+    return false
+  }
+  const outer = transport as { sessionId?: string; _webStandardTransport?: unknown }
+  try {
+    outer.sessionId = token
+  } catch {
+    // getter-only wrapper — try the inner transport below
+  }
+  if (outer.sessionId === token) {
+    return true
+  }
+  const inner = outer._webStandardTransport
+  if (inner && typeof inner === 'object') {
+    try {
+      ;(inner as { sessionId?: string }).sessionId = token
+    } catch {
+      // read-only inner transport — the final read-back decides
+    }
+  }
+  return outer.sessionId === token
+}
+
+// base64url without assuming Node: Buffer where available, TextEncoder/btoa on
+// edge runtimes. Must survive non-ASCII client names.
+
+function utf8ToBase64Url(input: string): string {
+  if (typeof Buffer !== 'undefined' && typeof Buffer.from === 'function') {
+    return Buffer.from(input, 'utf8').toString('base64url')
+  }
+  const bytes = new TextEncoder().encode(input)
+  let binary = ''
+  for (let i = 0; i < bytes.length; i++) {
+    binary += String.fromCharCode(bytes[i])
+  }
+  return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
+}
+
+function base64UrlToUtf8(input: string): string {
+  const normalized = input.replace(/-/g, '+').replace(/_/g, '/').replace(/=+$/, '')
+  const padded = normalized + '='.repeat((4 - (normalized.length % 4)) % 4)
+  if (typeof Buffer !== 'undefined' && typeof Buffer.from === 'function') {
+    return Buffer.from(padded, 'base64').toString('utf8')
+  }
+  const binary = atob(padded)
+  const bytes = new Uint8Array(binary.length)
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i)
+  }
+  return new TextDecoder().decode(bytes)
+}

package/src/extensions/session.ts

@@ -1,6 +1,7 @@
-// Portions of this file are derived from MCPCat/mcpcat-typescript-sdk
-// Copyright (c) 2025 MCPcat
-// Licensed under the MIT License: https://github.com/MCPCat/mcpcat-typescript-sdk/blob/main/LICENSE
+// Portions of this file are derived from agentcathq/agentcat-typescript-sdk
+// (formerly MCPCat/mcpcat-typescript-sdk)
+// Copyright (c) 2025 AgentCat, Inc. (formerly MCPcat)
+// Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
 import { version } from '../version'
 import type {
@@ -13,6 +14,7 @@ import type {
 import { INACTIVITY_TIMEOUT_IN_MINUTES } from './constants'
 import { deterministicPrefixedId, newPrefixedId } from './ids'
 import { getServerTrackingData, setServerTrackingData } from './internal'
+import { decodeSessionId, readMcpSessionHeader } from './session-token'
 
 export function newSessionId(): string {
   return newPrefixedId('ses')
@@ -27,58 +29,58 @@ export function deriveSessionIdFromMCPSession(mcpSessionId: string): string {
 }
 
 /**
- * Resolves the session id for a request, preferring the MCP protocol sessionId
- * over an SDK-generated one so a transport-supplied session wins.
+ * Resolves the session id for a request: from the replayed session token, from
+ * the transport's MCP session id, or — when the request carries nothing — from
+ * this instance's memory. Also saves the token's client name/version so events
+ * built later in the request can use them (see getSessionInfo).
  */
-export function getServerSessionId(server: MCPServerLike, extra?: CompatibleRequestHandlerExtra): string {
+export function getSessionId(server: MCPServerLike, extra?: CompatibleRequestHandlerExtra): string {
   const data = getServerTrackingData(server)
-
   if (!data) {
     throw new Error('Server tracking data not found')
   }
 
-  const mcpSessionId = extra?.sessionId
-
-  if (mcpSessionId) {
-    data.sessionId = deriveSessionIdFromMCPSession(mcpSessionId)
-    data.lastMcpSessionId = mcpSessionId
+  // Our token rides the `mcp-session-id` request header, which stateless
+  // transports ignore — so read it ourselves.
+  const sessionHeader = readMcpSessionHeader(extra?.requestInfo?.headers)
+  const token = decodeSessionId(sessionHeader)
+
+  let sessionId: string
+  if (token) {
+    // Token we minted at `initialize` (see session-token.ts).
+    data.sessionSource = 'token'
+    data.sessionInfo.clientName = token.clientName
+    data.sessionInfo.clientVersion = token.clientVersion
+    sessionId = token.sessionId
+  } else if (extra?.sessionId) {
+    // Session id issued by a stateful transport: hash it so the same MCP
+    // session maps to the same SDK session across restarts.
     data.sessionSource = 'mcp'
-    setServerTrackingData(server, data)
-    setLastActivity(server)
-    return data.sessionId
+    sessionId = deriveSessionIdFromMCPSession(extra.sessionId)
+  } else {
+    sessionId = getSessionIdFromMemory(data)
   }
 
-  // Once a session has been MCP-derived, keep that id even if a later request
-  // arrives without the MCP sessionId, so the session doesn't fragment.
-  if (data.sessionSource === 'mcp' && data.lastMcpSessionId) {
-    setLastActivity(server)
-    return data.sessionId
-  }
+  data.sessionId = sessionId
+  data.lastActivity = new Date()
+  setServerTrackingData(server, data)
+  return sessionId
+}
 
-  // SDK-generated sessions roll over after an inactivity timeout.
-  const now = Date.now()
+/**
+ * Nothing replayed on this request: keep the id we already have. Only
+ * generated sessions roll over on inactivity — token/MCP ids live as long as
+ * the client replays them, and regenerating one would split the session.
+ */
+function getSessionIdFromMemory(data: MCPAnalyticsData): string {
   const timeoutMs = INACTIVITY_TIMEOUT_IN_MINUTES * 60 * 1000
-  if (now - data.lastActivity.getTime() > timeoutMs) {
-    data.sessionId = newSessionId()
-    data.sessionSource = 'generated'
-    setServerTrackingData(server, data)
+  const isStale = Date.now() - data.lastActivity.getTime() > timeoutMs
+  if (data.sessionSource === 'generated' && isStale) {
+    return newSessionId()
   }
-  setLastActivity(server)
-
   return data.sessionId
 }
 
-export function setLastActivity(server: MCPServerLike): void {
-  const data = getServerTrackingData(server)
-
-  if (!data) {
-    throw new Error('Server tracking data not found')
-  }
-
-  data.lastActivity = new Date()
-  setServerTrackingData(server, data)
-}
-
 /**
  * Builds the session metadata stamped onto an event. The caller passes the
  * session id resolved for *this* request so identity attribution can't be

package/src/extensions/sink.ts

@@ -1,6 +1,7 @@
-// Portions of this file are derived from MCPCat/mcpcat-typescript-sdk
-// Copyright (c) 2025 MCPcat
-// Licensed under the MIT License: https://github.com/MCPCat/mcpcat-typescript-sdk/blob/main/LICENSE
+// Portions of this file are derived from agentcathq/agentcat-typescript-sdk
+// (formerly MCPCat/mcpcat-typescript-sdk)
+// Copyright (c) 2025 AgentCat, Inc. (formerly MCPcat)
+// Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
 import type { PostHog } from 'posthog-node'
 import { uuidv7 } from '@posthog/core'

package/src/extensions/tools.ts

@@ -1,6 +1,7 @@
-// Portions of this file are derived from MCPCat/mcpcat-typescript-sdk
-// Copyright (c) 2025 MCPcat
-// Licensed under the MIT License: https://github.com/MCPCat/mcpcat-typescript-sdk/blob/main/LICENSE
+// Portions of this file are derived from agentcathq/agentcat-typescript-sdk
+// (formerly MCPCat/mcpcat-typescript-sdk)
+// Copyright (c) 2025 AgentCat, Inc. (formerly MCPcat)
+// Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
 import { type CallToolResult, type ListToolsResult } from '@modelcontextprotocol/sdk/types.js'
 import { log } from './logger'

package/src/extensions/tracing-helpers.ts

@@ -1,6 +1,7 @@
-// Portions of this file are derived from MCPCat/mcpcat-typescript-sdk
-// Copyright (c) 2025 MCPcat
-// Licensed under the MIT License: https://github.com/MCPCat/mcpcat-typescript-sdk/blob/main/LICENSE
+// Portions of this file are derived from agentcathq/agentcat-typescript-sdk
+// (formerly MCPCat/mcpcat-typescript-sdk)
+// Copyright (c) 2025 AgentCat, Inc. (formerly MCPcat)
+// Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
 import type { CompatibleRequestHandlerExtra, MCPAnalyticsData, MCPRequestLike, McpEvent } from '../types'
 import { resolveEventProperties } from './internal'

package/src/extensions/truncation.ts

@@ -1,6 +1,7 @@
-// Portions of this file are derived from MCPCat/mcpcat-typescript-sdk
-// Copyright (c) 2025 MCPcat
-// Licensed under the MIT License: https://github.com/MCPCat/mcpcat-typescript-sdk/blob/main/LICENSE
+// Portions of this file are derived from agentcathq/agentcat-typescript-sdk
+// (formerly MCPCat/mcpcat-typescript-sdk)
+// Copyright (c) 2025 AgentCat, Inc. (formerly MCPcat)
+// Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
 import type { ErrorProperties, Event, StackFrame, McpEvent } from '../types'
 
@@ -429,6 +430,7 @@ export function truncateEvent<T extends Event | McpEvent>(event: T): T {
   result.serverVersion = truncateString(result.serverVersion, MAX_METADATA_LENGTH)
   result.clientName = truncateString(result.clientName, MAX_METADATA_LENGTH)
   result.clientVersion = truncateString(result.clientVersion, MAX_METADATA_LENGTH)
+  result.errorType = truncateString(result.errorType, MAX_METADATA_LENGTH)
 
   // Error field limits — operate on the core `$exception_list` shape
   if (result.error != null && typeof result.error === 'object') {

package/src/index.ts

@@ -1,6 +1,7 @@
-// Portions of this file are derived from MCPCat/mcpcat-typescript-sdk
-// Copyright (c) 2025 MCPcat
-// Licensed under the MIT License: https://github.com/MCPCat/mcpcat-typescript-sdk/blob/main/LICENSE
+// Portions of this file are derived from agentcathq/agentcat-typescript-sdk
+// (formerly MCPCat/mcpcat-typescript-sdk)
+// Copyright (c) 2025 AgentCat, Inc. (formerly MCPcat)
+// Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
 import type { PostHog } from 'posthog-node'
 import { isCompatibleServerType, isHighLevelServer } from './extensions/compatibility'
@@ -191,7 +192,16 @@ async function captureCustomEvent(lowLevelServer: MCPServerLike, eventData: Capt
   log(`Captured event "${eventData.event}" for session ${trackingData.sessionId}`)
 }
 
-export { deriveSessionIdFromMCPSession }
+export { deriveSessionIdFromMCPSession, newSessionId }
+// Session tokens for stateless / multi-pod servers. Minted and decoded
+// automatically on JSON-mode StreamableHTTP; SSE servers set the header
+// themselves with `encodeSessionId`.
+export {
+  MCP_SESSION_HEADER,
+  decodeSessionId,
+  encodeSessionId,
+  type SessionTokenPayload,
+} from './extensions/session-token'
 export {
   POSTHOG_MCP_ANALYTICS_SOURCE,
   PostHogMCPAnalyticsEvent,

package/src/types.ts

@@ -1,6 +1,7 @@
-// Portions of this file are derived from MCPCat/mcpcat-typescript-sdk
-// Copyright (c) 2025 MCPcat
-// Licensed under the MIT License: https://github.com/MCPCat/mcpcat-typescript-sdk/blob/main/LICENSE
+// Portions of this file are derived from agentcathq/agentcat-typescript-sdk
+// (formerly MCPCat/mcpcat-typescript-sdk)
+// Copyright (c) 2025 AgentCat, Inc. (formerly MCPcat)
+// Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js'
 import type { ErrorTracking } from '@posthog/core'
@@ -136,6 +137,13 @@ export interface Event {
   conversationId?: string
   duration?: number
   error?: ErrorProperties | null
+  /**
+   * Coarse failure category → `$mcp_error_type`. An explicit, low-cardinality
+   * label the host can supply (e.g. `validation`, `permission`, `timeout`).
+   * When omitted on an errored call, it falls back to the thrown error's type
+   * (the `$exception_list` entry's `type`).
+   */
+  errorType?: string
   eventId?: string
   eventType: MCPAnalyticsEventType
   groups?: Record<string, string>
@@ -172,9 +180,17 @@ export interface Event {
 /** A partially-built MCP event as it flows through the SDK before capture. */
 export type McpEvent = Partial<Event>
 
+/** HTTP request info the SDK's Streamable HTTP transports attach per request. */
+export interface CompatibleRequestInfoLike {
+  headers?: Record<string, string | string[] | undefined>
+  [key: string]: unknown
+}
+
 export interface CompatibleRequestHandlerExtra {
   headers?: Record<string, string | string[]>
   sessionId?: string
+  /** Present on HTTP transports only — headers ride every request, unlike `clientInfo`. */
+  requestInfo?: CompatibleRequestInfoLike
   [key: string]: unknown
 }
 
@@ -192,9 +208,17 @@ export interface HighLevelMCPServerLike {
   tool?(name: string, description: string, paramsSchema: unknown, cb: ToolCallback): void
 }
 
+/** The connected transport as exposed by the SDK's `Protocol.transport` getter. */
+export interface CompatibleTransportLike {
+  sessionId?: string
+  [key: string]: unknown
+}
+
 export interface MCPServerLike {
   _requestHandlers: Map<string, (request: MCPRequestLike, extra?: CompatibleRequestHandlerExtra) => Promise<unknown>>
   _serverInfo?: ServerClientInfoLike
+  /** Optional so older SDKs (and bare test doubles) still validate. */
+  transport?: CompatibleTransportLike
   getClientVersion(): ServerClientInfoLike | undefined
   setRequestHandler(
     schema: unknown,
@@ -238,11 +262,11 @@ export interface MCPAnalyticsData {
   sink: McpEventSink | undefined
   identifiedSessions: IdentityCache
   lastActivity: Date
-  lastMcpSessionId?: string
   options: MCPAnalyticsOptions
   sessionId: string
   sessionInfo: SessionInfo
-  sessionSource: 'generated' | 'mcp'
+  /** `token` = recovered from a self-encoded `Mcp-Session-Id` token (see session-token.ts). */
+  sessionSource: 'generated' | 'mcp' | 'token'
   toolCategories: Map<string, string>
   toolDescriptions: Map<string, string>
 }
@@ -317,6 +341,13 @@ export interface ToolCallCaptureData extends McpCaptureCommon {
    * synthesized from the tool name.
    */
   error?: unknown
+  /**
+   * Coarse failure category → `$mcp_error_type` (e.g. `validation`,
+   * `permission`, `timeout`, `rate_limited`). A low-cardinality label that lets
+   * the dashboard break failures down by reason without joining to `$exception`.
+   * When omitted on an error, the SDK falls back to the thrown error's type.
+   */
+  errorType?: string
 }
 
 /** Payload for {@link PostHogMCP.captureInitialize}. Emits `$mcp_initialize`. */
@@ -350,6 +381,8 @@ export interface ToolsListCaptureData extends McpCaptureCommon {
   isError?: boolean
   /** The thrown value when `isError` is true → fans out an `$exception` sibling. */
   error?: unknown
+  /** Coarse failure category → `$mcp_error_type`. Falls back to the thrown error's type. */
+  errorType?: string
 }
 
 /** Options for {@link PostHogMCP.prepareToolList}. */

package/src/version.ts

@@ -1 +1 @@
-export const version = '0.7.0'
+export const version = '0.9.0'