@posthog/mcp 0.0.9 → 0.1.17

package/dist/types.d.ts

@@ -0,0 +1,220 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+import type { ErrorTracking } from '@posthog/core';
+import type { MCPAnalyticsEventType } from './extensions/event-types';
+import type { IdentityCache } from './extensions/internal';
+import type { PostHogCaptureEvent } from './extensions/posthog-events';
+import type { McpEventSink } from './extensions/sink';
+import type { LoggerFn } from './extensions/logger';
+export type JsonRecord = Record<string, unknown>;
+/** PostHog error-tracking properties (`$exception_list`). Re-exported from `@posthog/core`. */
+export type ErrorProperties = ErrorTracking.ErrorProperties;
+/** A single parsed stack frame. Re-exported from `@posthog/core`. */
+export type StackFrame = ErrorTracking.StackFrame;
+export interface MCPRequestParamsLike {
+    arguments?: JsonRecord;
+    name?: string;
+    [key: string]: unknown;
+}
+export interface MCPRequestLike {
+    id?: number | string;
+    jsonrpc?: string;
+    method?: string;
+    params?: MCPRequestParamsLike;
+    [key: string]: unknown;
+}
+/** Handle returned by `instrument()` — the analytics surface for an instrumented server. */
+export interface McpAnalytics {
+    /**
+     * Capture a custom event for this server. The `event` name is required and sent
+     * verbatim (a customer event, so it is not `$`-prefixed). Resolves once the event
+     * has been processed. Use for domain-specific actions that aren't auto-captured
+     * (user feedback, workflow milestones, etc).
+     */
+    capture(eventData: CaptureEventData): Promise<void>;
+}
+export interface MCPAnalyticsOptions {
+    /**
+     * Optional STDIO-safe log sink for SDK-internal warnings. Receives single string messages.
+     * Defaults to a no-op since MCP STDIO transports cannot use console.
+     */
+    logger?: LoggerFn;
+    /** Enable the `get_more_tools` virtual tool so agents can report missing functionality. */
+    reportMissing?: boolean;
+    /** Enables the `conversation_id` tool parameter + prompt-back loop. */
+    enableConversationId?: boolean;
+    /**
+     * Emit a `$exception` event alongside any failed tool call. Defaults to `true`.
+     * Set to `false` if you handle error tracking elsewhere and don't want MCP errors
+     * fanning out into PostHog error tracking.
+     */
+    enableExceptionAutocapture?: boolean;
+    /** Inject a required `context` parameter on every tool to capture user intent. */
+    context?: boolean | MCPAnalyticsContextOptions;
+    /**
+     * Identify the calling user. Returning a non-null value sets `distinct_id` and `$set`
+     * on subsequent events for the session. Object form is treated as a static identity.
+     */
+    identify?: ((request: MCPRequestLike, extra?: CompatibleRequestHandlerExtra) => Promise<UserIdentity | null>) | UserIdentity | null;
+    /**
+     * Called when a tool is invoked without an explicit `context` argument. Return a short
+     * intent string to record as `$mcp_intent` with `$mcp_intent_source = "inferred"`.
+     */
+    intentFallback?: (request: MCPRequestLike, extra?: CompatibleRequestHandlerExtra) => MaybePromise<string | null | undefined>;
+    /**
+     * Inspect, modify, or drop each event right before it is sent to PostHog
+     * (matching posthog-node's `beforeSend`). Receives the fully-built capture
+     * payload — event name, `distinct_id`, and `properties` — and runs once per
+     * emitted event, including the `$exception` sibling of a failed tool call.
+     *
+     * Return the (possibly mutated) event to send it, or `null`/`undefined` to
+     * drop it. Use this to redact sensitive values, add or remove properties, or
+     * suppress specific events. A throw drops that event.
+     */
+    beforeSend?: BeforeSendFn;
+    /**
+     * Attach extra event properties on every auto-captured event. Spread into the PostHog
+     * event properties as-is; values must be JSON-serializable.
+     */
+    eventProperties?: (request: MCPRequestLike, extra?: CompatibleRequestHandlerExtra) => JsonRecord | null | Promise<JsonRecord | null>;
+}
+export interface MCPAnalyticsContextOptions {
+    description?: string;
+}
+export type MaybePromise<T> = T | Promise<T>;
+export type MCPAnalyticsIntentSource = 'context_parameter' | 'inferred';
+export type ToolCallback = ((args: unknown, extra: CompatibleRequestHandlerExtra) => CallToolResult | Promise<CallToolResult>) | ((extra: CompatibleRequestHandlerExtra) => CallToolResult | Promise<CallToolResult>);
+export type RegisteredTool = {
+    description?: string;
+    inputSchema?: unknown;
+    update?: (...args: unknown[]) => unknown;
+} & ({
+    callback: ToolCallback;
+    handler?: never;
+} | {
+    handler: ToolCallback;
+    callback?: never;
+});
+/**
+ * Hook invoked for every event just before it is handed to `posthog.capture()`.
+ * Return the event (optionally mutated) to send it, or a nullish value to drop it.
+ */
+export type BeforeSendFn = (event: PostHogCaptureEvent) => MaybePromise<PostHogCaptureEvent | null | undefined>;
+export interface Event {
+    actorId?: string;
+    clientName?: string;
+    clientVersion?: string;
+    conversationId?: string;
+    duration?: number;
+    error?: ErrorProperties | null;
+    eventId?: string;
+    eventType: MCPAnalyticsEventType;
+    groups?: Record<string, string>;
+    /**
+     * Explicit PostHog event name. When set (via `capture(server, { event })`) it
+     * overrides the built-in name derived from `eventType`, so callers can emit any
+     * event name. User-supplied names are sent verbatim (not `$`-prefixed).
+     */
+    eventName?: string;
+    id: string;
+    /** Resolved person properties for the session, written to `$set`. */
+    identifyActorData?: JsonRecord;
+    /** Resolved distinct id for the session (from `identify().distinctId`). */
+    identifyActorGivenId?: string;
+    ipAddress?: string;
+    isError?: boolean;
+    listedToolNames?: string[];
+    parameters?: unknown;
+    properties?: JsonRecord | null;
+    resourceName?: string;
+    response?: unknown;
+    sdkLanguage?: string;
+    sdkVersion?: string;
+    serverName?: string;
+    serverVersion?: string;
+    sessionId: string;
+    timestamp: Date;
+    toolDescription?: string;
+    userIntent?: string;
+    userIntentSource?: MCPAnalyticsIntentSource;
+}
+/** A partially-built MCP event as it flows through the SDK before capture. */
+export type McpEvent = Partial<Event>;
+export interface CompatibleRequestHandlerExtra {
+    headers?: Record<string, string | string[]>;
+    sessionId?: string;
+    [key: string]: unknown;
+}
+export interface ServerClientInfoLike {
+    name?: string;
+    version?: string;
+}
+export interface HighLevelMCPServerLike {
+    _registeredTools: {
+        [name: string]: RegisteredTool;
+    };
+    registerTool?(name: string, config: {
+        description?: string;
+        inputSchema?: unknown;
+    }, handler: ToolCallback): void;
+    server: MCPServerLike;
+    tool?(name: string, cb: ToolCallback): void;
+    tool?(name: string, paramsSchema: unknown, cb: ToolCallback): void;
+    tool?(name: string, description: string, paramsSchema: unknown, cb: ToolCallback): void;
+}
+export interface MCPServerLike {
+    _requestHandlers: Map<string, (request: MCPRequestLike, extra?: CompatibleRequestHandlerExtra) => Promise<unknown>>;
+    _serverInfo?: ServerClientInfoLike;
+    getClientVersion(): ServerClientInfoLike | undefined;
+    setRequestHandler(schema: unknown, handler: (request: MCPRequestLike, extra?: CompatibleRequestHandlerExtra) => Promise<unknown>): void;
+}
+export interface UserIdentity {
+    /**
+     * The person's distinct id (becomes `distinct_id`). Same concept as
+     * posthog-node's `identify({ distinctId })`.
+     */
+    distinctId: string;
+    /**
+     * Person properties, written to `$set` (e.g. `{ name, email, plan }`) — the
+     * same `properties` you'd pass to posthog-node's `identify`.
+     */
+    properties?: JsonRecord;
+    /**
+     * PostHog group memberships as `{ groupType: groupKey }`. Stamped onto every
+     * event for the session as `$groups`, so callers never hand-write the
+     * `$groups` dollar-key themselves.
+     */
+    groups?: Record<string, string>;
+}
+export interface SessionInfo {
+    clientName?: string;
+    clientVersion?: string;
+    identifyActorData?: JsonRecord;
+    identifyActorGivenId?: string;
+    identifyActorGroups?: Record<string, string>;
+    ipAddress?: string;
+    sdkLanguage?: string;
+    sdkVersion?: string;
+    serverName?: string;
+    serverVersion?: string;
+}
+export interface MCPAnalyticsData {
+    sink: McpEventSink | undefined;
+    identifiedSessions: IdentityCache;
+    lastActivity: Date;
+    lastMcpSessionId?: string;
+    options: MCPAnalyticsOptions;
+    sessionId: string;
+    sessionInfo: SessionInfo;
+    sessionSource: 'generated' | 'mcp';
+    toolDescriptions: Map<string, string>;
+}
+export interface CaptureEventData {
+    /**
+     * PostHog event name (required). Sent verbatim — a custom event is a
+     * customer-defined event, so it is NOT `$`-prefixed.
+     */
+    event: string;
+    /** Event properties, spread onto the PostHog event. Values must be JSON-serializable. */
+    properties?: JsonRecord;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,18 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+for(var __webpack_i__ in __webpack_exports__)exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const version = "0.1.17";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,WAAW,CAAA"}

package/dist/version.js

@@ -0,0 +1,36 @@
+"use strict";
+var __webpack_require__ = {};
+(()=>{
+    __webpack_require__.d = (exports1, definition)=>{
+        for(var key in definition)if (__webpack_require__.o(definition, key) && !__webpack_require__.o(exports1, key)) Object.defineProperty(exports1, key, {
+            enumerable: true,
+            get: definition[key]
+        });
+    };
+})();
+(()=>{
+    __webpack_require__.o = (obj, prop)=>Object.prototype.hasOwnProperty.call(obj, prop);
+})();
+(()=>{
+    __webpack_require__.r = (exports1)=>{
+        if ('undefined' != typeof Symbol && Symbol.toStringTag) Object.defineProperty(exports1, Symbol.toStringTag, {
+            value: 'Module'
+        });
+        Object.defineProperty(exports1, '__esModule', {
+            value: true
+        });
+    };
+})();
+var __webpack_exports__ = {};
+__webpack_require__.r(__webpack_exports__);
+__webpack_require__.d(__webpack_exports__, {
+    version: ()=>version
+});
+const version = '0.1.17';
+exports.version = __webpack_exports__.version;
+for(var __webpack_i__ in __webpack_exports__)if (-1 === [
+    "version"
+].indexOf(__webpack_i__)) exports[__webpack_i__] = __webpack_exports__[__webpack_i__];
+Object.defineProperty(exports, '__esModule', {
+    value: true
+});

package/dist/version.mjs

@@ -0,0 +1,2 @@
+const version = '0.1.17';
+export { version };

package/package.json

@@ -1,105 +1,73 @@
 {
   "name": "@posthog/mcp",
-  "version": "0.0.9",
-  "description": "PostHog SDK for MCP servers",
-  "type": "module",
-  "main": "dist/index.cjs",
-  "module": "dist/index.mjs",
-  "types": "dist/index.d.mts",
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./dist/index.d.mts",
-        "default": "./dist/index.mjs"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
-    }
-  },
-  "scripts": {
-    "build": "tsdown",
-    "dev": "tsdown --watch",
-    "test": "vitest",
-    "test:compatibility": "vitest run src/tests/mcp-version-compatibility.test.ts",
-    "check": "ultracite check --error-on-warnings .",
-    "fix": "ultracite fix .",
-    "typecheck": "tsgo --noEmit",
-    "typecheck:tsc6": "tsc6 --noEmit",
-    "bump": "changeset version",
-    "prepare": "husky",
-    "verify": "pnpm check && pnpm typecheck && pnpm test --no-watch && pnpm build",
-    "prepublishOnly": "pnpm verify"
-  },
-  "keywords": [
-    "ai-agents",
-    "analytics",
-    "mcp",
-    "mcp-server",
-    "model-context-protocol",
-    "observability",
-    "posthog"
-  ],
-  "author": "PostHog",
-  "license": "MIT",
+  "version": "0.1.17",
+  "description": "PostHog SDK for Model Context Protocol (MCP) servers — tracks tool usage, intent, and identity",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/PostHog/mcp-analytics.git"
+    "url": "git+https://github.com/PostHog/posthog-js.git",
+    "directory": "packages/mcp"
   },
-  "bugs": {
-    "url": "https://github.com/PostHog/mcp-analytics/issues"
+  "engines": {
+    "node": "^20.20.0 || >=22.22.0"
   },
-  "homepage": "https://github.com/PostHog/mcp-analytics#readme",
   "files": [
+    "src",
     "dist",
-    "README.md",
-    "LICENSE"
+    "!src/__tests__"
   ],
-  "publishConfig": {
-    "access": "public"
+  "license": "MIT",
+  "author": {
+    "name": "PostHog",
+    "email": "engineering@posthog.com",
+    "url": "https://posthog.com"
   },
-  "engines": {
-    "node": ">=22.22.0"
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "dependencies": {
+    "@posthog/core": "1.30.12"
   },
-  "packageManager": "pnpm@10.33.2",
   "devDependencies": {
-    "@biomejs/biome": "2.4.14",
-    "@changesets/cli": "^2.29.8",
-    "@modelcontextprotocol/sdk": "~1.24.2",
-    "@types/node": "^22.15.21",
-    "@typescript/native-preview": "beta",
-    "@vitest/coverage-v8": "^4.0.14",
-    "@vitest/ui": "^4.0.14",
-    "husky": "^9.1.7",
-    "tsdown": "^0.21.10",
-    "typescript": "npm:@typescript/typescript6@^6.0.0",
-    "ultracite": "7.6.3",
-    "vitest": "^4.0.14",
-    "zod": "^3.25 || ^4.0"
+    "@babel/preset-env": "^7.27.1",
+    "@babel/preset-typescript": "^7.27.1",
+    "@modelcontextprotocol/sdk": "~1.29.0",
+    "@rslib/core": "0.10.6",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.0.0",
+    "jest": "29.7.0",
+    "zod": "^3.25.0",
+    "posthog-node": "5.36.6",
+    "@posthog-tooling/tsconfig-base": "1.1.1"
   },
   "peerDependencies": {
-    "@modelcontextprotocol/sdk": ">=1.11"
+    "@modelcontextprotocol/sdk": ">=1.26.0",
+    "posthog-node": "^5.0.0"
   },
-  "pnpm": {
-    "overrides": {
-      "js-yaml": ">=4.1.1",
-      "read-yaml-file": "^2.1.0",
-      "tmp": ">=0.2.4",
-      "vite": ">=6.4.1",
-      "body-parser": ">=2.2.1",
-      "brace-expansion": "2.0.2"
-    },
-    "overridesComments": {
-      "js-yaml": "Fixes GHSA-mh29-5h37-fv8m (prototype pollution in merge) - via @changesets/cli",
-      "read-yaml-file": "v1 uses yaml.safeLoad which was removed in js-yaml 4 — force v2 which uses yaml.load - via @changesets/cli",
-      "tmp": "Fixes GHSA-52f5-9888-hmc6 (symlink attack) - via @changesets/cli",
-      "vite": "Fixes GHSA-93m4-6634-74q7 and other vite security issues - via vitest",
-      "body-parser": "Fixes GHSA-wqch-xfxh-vrr4 (DoS via url encoding) - via @modelcontextprotocol/sdk",
-      "brace-expansion": "Fixes GHSA-v6h2-p8h4-qcjw (ReDoS vulnerability) - via eslint"
+  "keywords": [
+    "posthog",
+    "mcp",
+    "model-context-protocol",
+    "analytics",
+    "llm"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
     }
   },
-  "dependencies": {
-    "posthog-node": "^5.33.3"
+  "scripts": {
+    "clean": "rimraf dist coverage",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "generate-version": "node -p \"'export const version = \\'' + require('./package.json').version + '\\''\" > src/version.ts",
+    "pretest:unit": "pnpm generate-version",
+    "test:unit": "jest",
+    "prebuild": "pnpm generate-version",
+    "build": "rslib build",
+    "dev": "rslib build -w",
+    "package": "pnpm pack --out $PACKAGE_DEST/%s.tgz"
   }
-}
+}

package/src/extensions/capture.ts

@@ -0,0 +1,68 @@
+import type { MCPServerLike, McpEvent } from '../types'
+import { MCPAnalyticsEventType } from './event-types'
+import { getServerTrackingData } from './internal'
+import { log } from './logger'
+import { getSessionInfo } from './session'
+
+/**
+ * Materializes an `McpEvent` against the server's tracking data + session info,
+ * then hands it to the `McpEventSink` (wrapping the user's posthog-node client) for the
+ * sanitize/truncate/beforeSend pipeline and capture. No-ops if the server isn't tracked or
+ * no PostHog client is attached — not passing `posthog` is how you turn capture off.
+ *
+ * Returns the sink's capture promise so the user-facing `capture()` can await it.
+ * Auto-capture callers (tool calls, listings, identify) intentionally ignore the
+ * return value, keeping the tool path isolated from analytics latency/errors.
+ */
+export function captureEvent(server: MCPServerLike, eventInput: McpEvent): Promise<void> | undefined {
+  const data = getServerTrackingData(server)
+  if (!data) {
+    log('Warning: Server tracking data not found. Event will not be published.')
+    return
+  }
+
+  const sink = data.sink
+  if (!sink) {
+    return
+  }
+
+  const sessionInfo = getSessionInfo(server, data, eventInput.sessionId)
+
+  const duration =
+    eventInput.duration || (eventInput.timestamp ? Date.now() - eventInput.timestamp.getTime() : undefined)
+
+  const fullEvent: McpEvent = {
+    id: eventInput.id || '',
+    sessionId: eventInput.sessionId || data.sessionId,
+    eventType: eventInput.eventType || MCPAnalyticsEventType.custom,
+    eventName: eventInput.eventName,
+    timestamp: eventInput.timestamp || new Date(),
+    duration,
+    ipAddress: sessionInfo.ipAddress,
+    sdkLanguage: sessionInfo.sdkLanguage,
+    sdkVersion: sessionInfo.sdkVersion,
+    serverName: sessionInfo.serverName,
+    serverVersion: sessionInfo.serverVersion,
+    clientName: sessionInfo.clientName,
+    clientVersion: sessionInfo.clientVersion,
+    identifyActorGivenId: sessionInfo.identifyActorGivenId,
+    identifyActorData: sessionInfo.identifyActorData,
+    groups: sessionInfo.identifyActorGroups,
+    resourceName: eventInput.resourceName,
+    toolDescription: eventInput.toolDescription,
+    listedToolNames: eventInput.listedToolNames,
+    parameters: eventInput.parameters,
+    response: eventInput.response,
+    userIntent: eventInput.userIntent,
+    userIntentSource: eventInput.userIntentSource,
+    isError: eventInput.isError,
+    error: eventInput.error,
+    conversationId: eventInput.conversationId,
+    properties: eventInput.properties,
+  }
+
+  return sink.capture(fullEvent, {
+    enableExceptionAutocapture: data.options.enableExceptionAutocapture ?? true,
+    beforeSend: data.options.beforeSend,
+  })
+}

package/src/extensions/compatibility.ts

@@ -0,0 +1,138 @@
+import type { HighLevelMCPServerLike, MCPServerLike } from '../types'
+import { log } from './logger'
+
+type ServerRecord = Record<string, unknown>
+
+/**
+ * PostHog MCP analytics Compatibility Module
+ *
+ * This module ensures compatibility with Model Context Protocol TypeScript SDK.
+ * PostHog MCP analytics only supports MCP SDK version 1.11 and above.
+ *
+ * Version 1.11+ is required because it introduced stable APIs for:
+ * - Tool registration and handling
+ * - Request handler access patterns
+ * - Client version detection
+ * - Server info structure
+ */
+
+// Function to log compatibility information
+export function logCompatibilityWarning(): void {
+  log(
+    'PostHog MCP analytics SDK Compatibility: This version only supports Model Context Protocol TypeScript SDK v1.11 and above. Please upgrade if using an older version.'
+  )
+}
+
+// Check if server has high-level structure (wrapper with .server property)
+export function isHighLevelServer(server: unknown): server is ServerRecord & { server: ServerRecord } {
+  return (
+    !!server && typeof server === 'object' && 'server' in server && !!server.server && typeof server.server === 'object'
+  )
+}
+
+// Check if server has low-level structure (no .server property)
+export function isLowLevelServer(server: unknown): server is ServerRecord {
+  return !!server && typeof server === 'object' && !('server' in server)
+}
+
+// Type guard function that validates server compatibility and returns typed server
+export function isCompatibleServerType(server: unknown): MCPServerLike | HighLevelMCPServerLike {
+  if (!server || typeof server !== 'object') {
+    logCompatibilityWarning()
+    throw new Error(
+      "PostHog MCP analytics SDK compatibility error: Server must be an object. Ensure you're using MCP SDK v1.11 or higher."
+    )
+  }
+
+  if (isHighLevelServer(server)) {
+    // Validate high-level server requirements
+    if (!server._registeredTools || typeof server._registeredTools !== 'object') {
+      logCompatibilityWarning()
+      throw new Error(
+        'PostHog MCP analytics SDK compatibility error: High-level server must have _registeredTools object. This requires MCP SDK v1.11 or higher.'
+      )
+    }
+    if (typeof server.tool !== 'function') {
+      logCompatibilityWarning()
+      throw new Error(
+        'PostHog MCP analytics SDK compatibility error: High-level server must have tool() method. This requires MCP SDK v1.11 or higher.'
+      )
+    }
+
+    // Validate the underlying low-level server
+    const targetServer = server.server
+    validateLowLevelServer(targetServer)
+
+    return server as unknown as HighLevelMCPServerLike
+  }
+  // Direct low-level server validation
+  validateLowLevelServer(server)
+  return server as MCPServerLike
+}
+
+// Helper function to validate low-level server requirements
+function validateLowLevelServer(server: unknown): void {
+  if (!server || typeof server !== 'object') {
+    logCompatibilityWarning()
+    throw new Error(
+      "PostHog MCP analytics SDK compatibility error: Server must be an object. Ensure you're using MCP SDK v1.11 or higher."
+    )
+  }
+
+  const serverRecord = server as ServerRecord
+
+  if (typeof serverRecord.setRequestHandler !== 'function') {
+    logCompatibilityWarning()
+    throw new Error(
+      'PostHog MCP analytics SDK compatibility error: Server must have a setRequestHandler method. This requires MCP SDK v1.11 or higher.'
+    )
+  }
+
+  if (!(serverRecord._requestHandlers && serverRecord._requestHandlers instanceof Map)) {
+    logCompatibilityWarning()
+    throw new Error(
+      'PostHog MCP analytics SDK compatibility error: Server._requestHandlers is not accessible. This requires MCP SDK v1.11 or higher.'
+    )
+  }
+
+  // Validate that _requestHandlers contains functions with compatible signatures
+  if (typeof serverRecord._requestHandlers.get !== 'function') {
+    logCompatibilityWarning()
+    throw new Error(
+      'PostHog MCP analytics SDK compatibility error: Server._requestHandlers must be a Map with a get method. This requires MCP SDK v1.11 or higher.'
+    )
+  }
+
+  if (typeof serverRecord.getClientVersion !== 'function') {
+    logCompatibilityWarning()
+    throw new Error(
+      'PostHog MCP analytics SDK compatibility error: Server.getClientVersion must be a function. This requires MCP SDK v1.11 or higher.'
+    )
+  }
+
+  if (
+    !serverRecord._serverInfo ||
+    typeof serverRecord._serverInfo !== 'object' ||
+    !('name' in serverRecord._serverInfo)
+  ) {
+    logCompatibilityWarning()
+    throw new Error(
+      'PostHog MCP analytics SDK compatibility error: Server._serverInfo is not accessible or missing name. This requires MCP SDK v1.11 or higher.'
+    )
+  }
+}
+
+export function getMCPCompatibleErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    try {
+      return JSON.stringify(error, Object.getOwnPropertyNames(error))
+    } catch {
+      return 'Unknown error'
+    }
+  } else if (typeof error === 'string') {
+    return error
+  } else if (typeof error === 'object' && error !== null) {
+    return JSON.stringify(error)
+  }
+  return 'Unknown error'
+}