@posthog/mcp 0.0.4 → 0.0.5

package/README.md

@@ -102,6 +102,7 @@ Important properties:
 - `$mcp_intent` from the `context` argument, or from `intentFallback` when no context was provided
 - `$mcp_intent_source` as `context_parameter` or `inferred`
 - `$mcp_tool_name` and `$mcp_resource_name`
+- `$mcp_tool_description`, the tool's current `description` at the moment of the call — populated on `mcp_tool_call` and on the paired `$exception` event so the description is visible inline while triaging
 - `$mcp_parameters` and `$mcp_response`, after redaction and truncation
 - `$mcp_duration_ms`
 - `$mcp_is_error`

package/dist/index.cjs

@@ -389,6 +389,7 @@ const PostHogMCPAnalyticsProperty = {
 	ServerVersion: "$mcp_server_version",
 	SessionId: "$session_id",
 	Source: "$mcp_source",
+	ToolDescription: "$mcp_tool_description",
 	ToolName: "$mcp_tool_name"
 };
 //#endregion
@@ -457,6 +458,7 @@ function addCommonEventProperties(event, properties) {
 		properties[PostHogMCPAnalyticsProperty.ResourceName] = event.resourceName;
 		if (event.eventType === MCPAnalyticsEventType.mcpToolsCall) properties[PostHogMCPAnalyticsProperty.ToolName] = event.resourceName;
 	}
+	if (event.toolDescription && event.eventType === MCPAnalyticsEventType.mcpToolsCall) properties[PostHogMCPAnalyticsProperty.ToolDescription] = event.toolDescription;
 	if (event.duration !== void 0) properties[PostHogMCPAnalyticsProperty.DurationMs] = event.duration;
 	if (event.serverName) properties[PostHogMCPAnalyticsProperty.ServerName] = event.serverName;
 	if (event.serverVersion) properties[PostHogMCPAnalyticsProperty.ServerVersion] = event.serverVersion;
@@ -493,6 +495,7 @@ function buildExceptionEvent(event) {
 		properties[PostHogMCPAnalyticsProperty.ResourceName] = event.resourceName;
 		if (event.eventType === MCPAnalyticsEventType.mcpToolsCall) properties[PostHogMCPAnalyticsProperty.ToolName] = event.resourceName;
 	}
+	if (event.toolDescription && event.eventType === MCPAnalyticsEventType.mcpToolsCall) properties[PostHogMCPAnalyticsProperty.ToolDescription] = event.toolDescription;
 	if (event.serverName) properties[PostHogMCPAnalyticsProperty.ServerName] = event.serverName;
 	if (event.serverVersion) properties[PostHogMCPAnalyticsProperty.ServerVersion] = event.serverVersion;
 	if (event.clientName) properties[PostHogMCPAnalyticsProperty.ClientName] = event.clientName;
@@ -552,6 +555,7 @@ const PROTECTED_FIELDS = new Set([
 	"identifyActorName",
 	"identifyData",
 	"resourceName",
+	"toolDescription",
 	"eventType",
 	"actorId",
 	"tags",
@@ -729,7 +733,7 @@ function sanitizeParameters(obj) {
 }
 //#endregion
 //#region package.json
-var version = "0.0.4";
+var version = "0.0.5";
 //#endregion
 //#region src/modules/session.ts
 function newSessionId() {
@@ -1189,6 +1193,7 @@ function publishEvent(server, eventInput) {
 		identifyActorName: sessionInfo.identifyActorName,
 		identifyActorData: sessionInfo.identifyActorData,
 		resourceName: eventInput.resourceName,
+		toolDescription: eventInput.toolDescription,
 		parameters: eventInput.parameters,
 		response: eventInput.response,
 		userIntent: eventInput.userIntent,
@@ -2137,6 +2142,7 @@ async function getTracedToolsList(server, originalListToolsHandler, request, ext
 		if (data?.options.reportMissing) {
 			if (!tools.some((tool) => tool?.name === "get_more_tools")) tools.push(getReportMissingToolDescriptor());
 		}
+		if (data) cacheToolDescriptions(data.toolDescriptions, tools);
 		return tools;
 	} catch (error) {
 		writeToLog(`Warning: Original list tools handler failed, this suggests an error PostHog MCP analytics did not cause - ${error}`);
@@ -2220,13 +2226,15 @@ async function handleToolCallRequest(server, originalCallToolHandler, request, e
 	}
 	const conversation = resolveConversationId(data.options.enableConversationId ?? false, request.params?.arguments, request.params?.name);
 	const downstreamRequest = conversation.conversationId ? cloneRequestWithoutConversationId(request) : request;
+	const toolName = request.params?.name;
 	const event = {
 		sessionId: getServerSessionId(server, extra),
 		conversationId: conversation.conversationId,
-		resourceName: request.params?.name || "Unknown Tool Name",
+		resourceName: toolName || "Unknown Tool Name",
 		parameters: buildCapturedMcpParameters(downstreamRequest),
 		eventType: MCPAnalyticsEventType.mcpToolsCall,
 		timestamp: /* @__PURE__ */ new Date(),
+		toolDescription: toolName ? data.toolDescriptions.get(toolName) : void 0,
 		redactionFn: data.options.redactSensitiveInformation
 	};
 	try {
@@ -2280,6 +2288,10 @@ function getContextArgument$1(request) {
 function getEventDuration(event) {
 	return event.timestamp ? Date.now() - event.timestamp.getTime() : 0;
 }
+function cacheToolDescriptions(cache, tools) {
+	if (!tools) return;
+	for (const tool of tools) if (tool?.name && typeof tool.description === "string") cache.set(tool.name, tool.description);
+}
 //#endregion
 //#region src/modules/mcp-sdk-compat.ts
 /**
@@ -2367,7 +2379,8 @@ function addTracingToToolRegistry(tools, server) {
 }
 function setupListenerToRegisteredTools(server) {
 	try {
-		if (!getServerTrackingData(server.server)) {
+		const data = getServerTrackingData(server.server);
+		if (!data) {
 			writeToLog("Warning: Cannot setup listener - no tracking data found");
 			return;
 		}
@@ -2375,6 +2388,7 @@ function setupListenerToRegisteredTools(server) {
 			set(target, property, value) {
 				try {
 					if (typeof property === "string" && value && typeof value === "object" && hasToolFunction(value)) {
+						if (typeof value.description === "string") data.toolDescriptions.set(property, value.description);
 						if (value[MCP_ANALYTICS_PROCESSED]) {
 							writeToLog(`Tool ${String(property)} already processed, skipping proxy wrapping`);
 							return Reflect.set(target, property, value);
@@ -2497,13 +2511,15 @@ async function initializeToolCallEvent(server, request, downstreamRequest, extra
 				shouldPublishEvent: false
 			};
 		}
+		const toolName = request.params?.name;
 		const event = {
 			sessionId: getServerSessionId(server, extra),
 			conversationId: conversation.conversationId,
-			resourceName: request.params?.name || "Unknown Tool",
+			resourceName: toolName || "Unknown Tool",
 			parameters: buildCapturedMcpParameters(downstreamRequest),
 			eventType: MCPAnalyticsEventType.mcpToolsCall,
 			timestamp: startTime,
+			toolDescription: toolName ? data.toolDescriptions.get(toolName) : void 0,
 			redactionFn: data.options.redactSensitiveInformation
 		};
 		await handleIdentify(server, data, request, extra);
@@ -2593,16 +2609,20 @@ function publishFailedToolEvent(server, tracing, error, startTime) {
 }
 function setupTracking(server) {
 	try {
-		getServerTrackingData(server.server);
+		const mcpAnalyticsData = getServerTrackingData(server.server);
 		setupToolsCallHandlerWrapping(server);
 		setupInitializeTracing(server);
 		server._registeredTools = addTracingToToolRegistry(server._registeredTools, server);
+		if (mcpAnalyticsData) seedToolDescriptionsFromRegistry(mcpAnalyticsData.toolDescriptions, server._registeredTools);
 		setupListToolsTracing(server);
 		setupListenerToRegisteredTools(server);
 	} catch (error) {
 		writeToLog(`Warning: Failed to setup tool call tracing - ${error}`);
 	}
 }
+function seedToolDescriptionsFromRegistry(cache, tools) {
+	for (const [name, tool] of Object.entries(tools)) if (typeof tool?.description === "string") cache.set(name, tool.description);
+}
 //#endregion
 //#region src/index.ts
 /**
@@ -2738,6 +2758,7 @@ function buildTrackingData(lowLevelServer, options) {
 		sessionId: newSessionId(),
 		lastActivity: /* @__PURE__ */ new Date(),
 		identifiedSessions: /* @__PURE__ */ new Map(),
+		toolDescriptions: /* @__PURE__ */ new Map(),
 		sessionInfo: getSessionInfo(lowLevelServer, void 0),
 		options: {
 			reportMissing: options.reportMissing ?? false,