@posthog/mcp 0.11.7 → 0.13.0

package/src/types.ts

@@ -129,6 +129,20 @@ export interface MCPAnalyticsOptions {
   enableExceptionAutocapture?: boolean
   /** Inject a required `context` parameter on every tool to capture user intent. */
   context?: boolean | MCPAnalyticsContextOptions
+  /**
+   * Inject a required `llm_model` parameter on every tool so the calling agent
+   * self-reports the model it runs as, captured as `$mcp_llm_model` with
+   * `$mcp_llm_model_source = "self_reported"`. Off by default.
+   *
+   * The MCP wire deliberately carries no model identity, so self-report is the
+   * only capture path — harnesses inject the model id into the agent's system
+   * prompt, and agents restate it accurately. Like `clientInfo` in the MCP
+   * spec, the value is unverified: use it for per-model quality analytics, not
+   * billing or security. An honest `"unknown"` from the agent is dropped
+   * rather than captured. Reasoning effort is intentionally not collected —
+   * agents don't reliably know it, so it would only ever be noise.
+   */
+  captureModel?: boolean | MCPAnalyticsModelOptions
   /**
    * 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.
@@ -172,8 +186,13 @@ export interface MCPAnalyticsContextOptions {
   description?: string
 }
 
+export interface MCPAnalyticsModelOptions {
+  description?: string
+}
+
 export type MaybePromise<T> = T | Promise<T>
 export type MCPAnalyticsIntentSource = 'context_parameter' | 'inferred'
+export type MCPAnalyticsModelSource = 'self_reported'
 
 export type ToolCallback =
   | ((
@@ -225,6 +244,14 @@ export interface Event {
   eventId?: string
   eventType: MCPAnalyticsEventType
   groups?: Record<string, string>
+  /**
+   * The calling agent's self-reported model id → `$mcp_llm_model`. Read off
+   * the SDK-injected `llm_model` argument (`captureModel` option); unverified
+   * by design, like the MCP spec's own `clientInfo`.
+   */
+  llmModel?: string
+  /** How the model id was obtained → `$mcp_llm_model_source`. Always `self_reported` today. */
+  llmModelSource?: MCPAnalyticsModelSource
   /**
    * Explicit PostHog event name. When set (via `capture(server, { event })`) it
    * overrides the built-in name derived from `eventType`, so callers can emit any
@@ -380,6 +407,7 @@ export interface SessionInfo {
 export interface AnalyticsParameterOwnership {
   context: boolean
   conversationId: boolean
+  llmModel: boolean
   /**
    * True when we declared `_mcp_instructions` on this tool's advertised output
    * schema, so writing that key into `structuredContent` will validate. False
@@ -483,6 +511,13 @@ export interface ToolCallCaptureData extends McpCaptureCommon {
    * the host derived it. Defaults to `context_parameter` when an intent is set.
    */
   intentSource?: MCPAnalyticsIntentSource
+  /**
+   * The calling agent's self-reported model id -> `$mcp_llm_model`. On the
+   * custom-dispatcher path, read it from {@link PostHogMCP.prepareToolCall}.
+   */
+  llmModel?: string
+  /** How the model id was obtained -> `$mcp_llm_model_source`. */
+  llmModelSource?: MCPAnalyticsModelSource
   /** Captured call arguments → `$mcp_parameters` (sanitized + truncated). */
   parameters?: unknown
   /** Captured tool result → `$mcp_response` (sanitized + truncated). */
@@ -558,18 +593,30 @@ export interface PrepareToolListOptions {
   reportMissing?: boolean
 }
 
+/** Options for {@link PostHogMCP.prepareToolCall}. */
+export interface PrepareToolCallOptions {
+  /**
+   * The tool descriptor before PostHog preparation. Pass this on stateless or
+   * multi-replica servers so SDK argument ownership is resolved per request.
+   */
+  originalTool?: { inputSchema?: unknown }
+}
+
 /**
  * Result of {@link PostHogMCP.prepareToolCall}: the intent pulled off the
- * incoming call, the arguments with the injected `context` removed (so your tool
- * handler and its schema validation never see it), and whether the call targeted
- * the `get_more_tools` virtual tool.
+ * incoming call, the arguments with SDK-owned analytics fields removed, and
+ * whether the call targeted the `get_more_tools` virtual tool.
  */
 export interface PreparedToolCall {
   /** The agent's stated intent (the `context` argument), if present. */
   intent?: string
   /** Where the intent came from. Always `context_parameter` here when set. */
   intentSource?: MCPAnalyticsIntentSource
-  /** The call arguments with the injected `context` key stripped out. */
+  /** The agent's self-reported model id, when `captureModel` is enabled and owned by the SDK. */
+  llmModel?: string
+  /** How the model id was obtained. Always `self_reported` when present. */
+  llmModelSource?: MCPAnalyticsModelSource
+  /** The call arguments with SDK-owned `context` and `llm_model` keys removed. */
   args?: Record<string, unknown>
   /** True when `name` is the `get_more_tools` virtual tool. */
   isMissingCapability: boolean
@@ -582,6 +629,10 @@ export interface MissingCapabilityCaptureData extends McpCaptureCommon {
    * on the `get_more_tools` call) → `$mcp_intent`.
    */
   context?: string
+  /** The calling agent's self-reported model id -> `$mcp_llm_model`. */
+  llmModel?: string
+  /** How the model id was obtained -> `$mcp_llm_model_source`. */
+  llmModelSource?: MCPAnalyticsModelSource
   /** Captured call arguments → `$mcp_parameters` (sanitized + truncated). */
   parameters?: unknown
 }

package/src/version.ts

@@ -1 +1 @@
-export const version = '0.11.7'
+export const version = '0.13.0'