@posthog/mcp 0.3.0 → 0.4.1

package/src/extensions/posthog-mcp.ts

@@ -1,10 +1,41 @@
-import { PostHog } from 'posthog-node'
+import { PostHog, type PostHogOptions } from 'posthog-node'
 
-import type { InitializeCaptureData, JsonRecord, McpCaptureCommon, McpEvent, ToolCallCaptureData } from '../types'
+import type {
+  InitializeCaptureData,
+  JsonRecord,
+  McpCaptureCommon,
+  McpEvent,
+  MissingCapabilityCaptureData,
+  PreparedToolCall,
+  PrepareToolListOptions,
+  ToolCallCaptureData,
+  ToolsListCaptureData,
+} from '../types'
+import {
+  addContextParameterToTools,
+  getContextDescription,
+  isContextEnabled,
+  type ContextInjectableTool,
+} from './context-parameters'
 import { MCPAnalyticsEventType } from './event-types'
 import { captureException } from './exceptions'
 import { log } from './logger'
 import { McpEventSink } from './sink'
+import { GET_MORE_TOOLS_NAME, getReportMissingToolDescriptor } from './tools'
+
+/**
+ * Options for {@link PostHogMCP}. A superset of `posthog-node`'s options, plus
+ * MCP-specific knobs.
+ */
+export interface PostHogMCPOptions extends PostHogOptions {
+  /**
+   * Name of the virtual "report a missing capability" tool injected by
+   * {@link PostHogMCP.prepareToolList} and detected by
+   * {@link PostHogMCP.prepareToolCall}. Set once here so injection and detection
+   * can't drift. Defaults to `get_more_tools`.
+   */
+  missingCapabilityToolName?: string
+}
 
 /**
  * A `posthog-node` client with first-class MCP analytics. Use this when there is
@@ -46,6 +77,15 @@ export class PostHogMCP extends PostHog {
   // `beforeSend` and batching apply.
   readonly #sink = new McpEventSink(this)
 
+  // The get_more_tools name lives here (not on the per-call options) so that
+  // prepareToolList (inject) and prepareToolCall (detect) always agree.
+  readonly #missingCapabilityToolName: string
+
+  constructor(apiKey: string, options: PostHogMCPOptions = {}) {
+    super(apiKey, options)
+    this.#missingCapabilityToolName = options.missingCapabilityToolName ?? GET_MORE_TOOLS_NAME
+  }
+
   /** Capture a tool invocation. Emits `$mcp_tool_call` (+ an `$exception` sibling on error). */
   captureToolCall(data: ToolCallCaptureData): void {
     const event = baseEvent(MCPAnalyticsEventType.mcpToolsCall, data)
@@ -56,6 +96,7 @@ export class PostHogMCP extends PostHog {
     event.response = data.response
     event.duration = data.durationMs
     event.isError = data.isError
+    applyIntent(event, data.intent, data.intentSource)
     if (data.isError) {
       event.error = captureException(data.error ?? `Tool ${data.toolName} returned an error`)
     }
@@ -73,6 +114,109 @@ export class PostHogMCP extends PostHog {
     this.#emit(event)
   }
 
+  /**
+   * Capture a `tools/list` response. Emits `$mcp_tools_list` carrying the
+   * advertised tool names (`$mcp_listed_tool_names`), which powers
+   * "advertised but never called" analysis. Pass the names you're about to
+   * return — typically the result of {@link prepareToolList}.
+   */
+  captureToolsList(data: ToolsListCaptureData): void {
+    const event = baseEvent(MCPAnalyticsEventType.mcpToolsList, data)
+    event.listedToolNames = data.toolNames
+    event.parameters = data.parameters
+    event.response = data.response
+    event.duration = data.durationMs
+    event.isError = data.isError
+    if (data.isError) {
+      event.error = captureException(data.error ?? 'tools/list failed')
+    }
+    this.#emit(event)
+  }
+
+  /**
+   * Decorate your `tools/list` response with PostHog's analytics affordances:
+   * injects the `context` argument into every tool (so agents state their intent,
+   * captured as `$mcp_intent`) and, when `reportMissing` is on, appends the
+   * `get_more_tools` virtual tool (rename it via the `missingCapabilityToolName`
+   * constructor option). Returns a new array; your tools are untouched.
+   *
+   * The appended `get_more_tools` descriptor carries only the base MCP tool fields
+   * (name, description, input schema) — not any framework-specific fields your
+   * `TTool` may add (e.g. a `handler`). It is meant to be detected via
+   * {@link prepareToolCall}'s `isMissingCapability`, not dispatched through a handler.
+   *
+   * Call this when there is no `Server` to wrap — it does for a custom dispatcher
+   * what `instrument()` does for a `Server`. Pair it with {@link prepareToolCall}
+   * on the inbound side.
+   *
+   * @example
+   * ```ts
+   * // building your tools/list response
+   * return { tools: posthog.prepareToolList(myTools, { reportMissing: true }) }
+   * ```
+   */
+  prepareToolList<TTool extends ContextInjectableTool>(tools: TTool[], options: PrepareToolListOptions = {}): TTool[] {
+    const contextOption = options.context ?? true
+    let prepared = isContextEnabled(contextOption)
+      ? addContextParameterToTools(tools, getContextDescription(contextOption))
+      : [...tools]
+
+    if (options.reportMissing && !prepared.some((tool) => tool?.name === this.#missingCapabilityToolName)) {
+      prepared = [...prepared, getReportMissingToolDescriptor(this.#missingCapabilityToolName) as TTool]
+    }
+    return prepared
+  }
+
+  /**
+   * Read an incoming `tools/call` before you dispatch it: pulls the agent's
+   * intent off the injected `context` argument, strips `context` from the
+   * arguments (so your handler and its schema validation never see it), and flags
+   * whether the call targeted the `get_more_tools` virtual tool.
+   *
+   * Pass the returned `intent` / `intentSource` to {@link captureToolCall}, and
+   * dispatch the returned `args` to your tool.
+   *
+   * This only extracts the explicit `context` argument (`intentSource:
+   * 'context_parameter'`); it does not infer intent. If you run your own
+   * inference, pass that string with `intentSource: 'inferred'` straight to
+   * {@link captureToolCall} (the `instrument()` path's `intentFallback`
+   * equivalent).
+   *
+   * @example
+   * ```ts
+   * const { intent, intentSource, args, isMissingCapability } = posthog.prepareToolCall(name, rawArgs)
+   * if (isMissingCapability) {
+   *   posthog.captureMissingCapability({ context: intent, ...identity })
+   *   return getMoreToolsResult()
+   * }
+   * const result = await runTool(name, args)
+   * posthog.captureToolCall({ toolName: name, intent, intentSource, ...identity })
+   * ```
+   */
+  prepareToolCall(name: string, args?: Record<string, unknown>): PreparedToolCall {
+    const rawContext = args?.context
+    const intent = typeof rawContext === 'string' && rawContext.trim() ? rawContext.trim() : undefined
+    return {
+      intent,
+      intentSource: intent ? 'context_parameter' : undefined,
+      args: stripContext(args),
+      isMissingCapability: name === this.#missingCapabilityToolName,
+    }
+  }
+
+  /**
+   * Capture a `get_more_tools` call as a missing-capability report. Emits
+   * `$mcp_missing_capability` with the agent's description as `$mcp_intent`. Reply
+   * to the agent with `getMoreToolsResult()`.
+   */
+  captureMissingCapability(data: MissingCapabilityCaptureData): void {
+    const event = baseEvent(MCPAnalyticsEventType.mcpMissingCapability, data)
+    event.resourceName = this.#missingCapabilityToolName
+    event.parameters = data.parameters
+    applyIntent(event, data.context, 'context_parameter')
+    this.#emit(event)
+  }
+
   /**
    * Fire-and-forget, mirroring posthog-node's `capture()`: the event is enqueued
    * on the client, not awaited. Never throws — a failure to record analytics
@@ -106,3 +250,25 @@ function baseEvent(eventType: MCPAnalyticsEventType, common: McpCaptureCommon):
   }
   return event
 }
+
+/**
+ * Set the agent intent on an event → `$mcp_intent` / `$mcp_intent_source`. No-op
+ * for blank intents, so a missing `context` argument simply leaves them off.
+ */
+function applyIntent(event: McpEvent, intent: string | undefined, source: McpEvent['userIntentSource']): void {
+  const trimmed = typeof intent === 'string' ? intent.trim() : ''
+  if (!trimmed) {
+    return
+  }
+  event.userIntent = trimmed
+  event.userIntentSource = source ?? 'context_parameter'
+}
+
+/** Return a shallow copy of the arguments with the injected `context` key removed. */
+function stripContext(args: Record<string, unknown> | undefined): Record<string, unknown> | undefined {
+  if (!args || !('context' in args)) {
+    return args
+  }
+  const { context: _context, ...rest } = args
+  return rest
+}

package/src/extensions/sanitization.ts

@@ -13,7 +13,9 @@ function isRecord(value: unknown): value is SanitizedRecord {
 
 /**
  * Sanitizes an event by redacting non-text content blocks from responses
- * and large base64-encoded strings from parameters.
+ * and large base64-encoded strings from parameters, and applying the same
+ * string redaction (PostHog tokens, base64 blobs, sensitive keys) to the
+ * agent-supplied intent.
  *
  * This is a synchronous operation that returns a new object without mutating the original.
  * It should run after customer redaction in the event pipeline.
@@ -29,6 +31,13 @@ export function sanitizeEvent<T extends Event | McpEvent>(event: T): T {
     result.parameters = sanitizeParameters(result.parameters)
   }
 
+  // The intent comes straight from an agent-narrated `context` string, so it
+  // can contain a secret the LLM read aloud. Redact it like any other captured
+  // value rather than shipping it raw as `$mcp_intent`.
+  if (result.userIntent != null) {
+    result.userIntent = sanitizeCapturedValue(result.userIntent) as string
+  }
+
   return result
 }
 

package/src/extensions/tools.ts

@@ -7,11 +7,20 @@ import { log } from './logger'
 
 export const GET_MORE_TOOLS_NAME = 'get_more_tools' as const
 
+/**
+ * The configured name of the `get_more_tools` virtual tool, falling back to the
+ * default. Resolve through here everywhere (inject + detect) so a custom name
+ * can't drift between call sites.
+ */
+export function resolveMissingCapabilityToolName(options?: { missingCapabilityToolName?: string }): string {
+  return options?.missingCapabilityToolName ?? GET_MORE_TOOLS_NAME
+}
+
 type ReportMissingToolDescriptor = ListToolsResult['tools'][number]
 
-export function getReportMissingToolDescriptor(): ReportMissingToolDescriptor {
+export function getReportMissingToolDescriptor(name: string = GET_MORE_TOOLS_NAME): ReportMissingToolDescriptor {
   return {
-    name: GET_MORE_TOOLS_NAME,
+    name,
     description:
       'Check for additional tools whenever your task might benefit from specialized capabilities - even if existing tools could work as a fallback.',
     inputSchema: {
@@ -40,9 +49,13 @@ export function getReportMissingToolDescriptor(): ReportMissingToolDescriptor {
   }
 }
 
-export function handleReportMissing(args: { context: string }): CallToolResult {
-  log(`Missing tool reported: ${JSON.stringify(args)}`)
-
+/**
+ * The canned acknowledgement returned to the agent after it calls
+ * `get_more_tools`. Reply with this from your dispatcher so the agent knows the
+ * report was recorded (custom dispatcher path); the `instrument()` path returns
+ * it automatically.
+ */
+export function getMoreToolsResult(): CallToolResult {
   return {
     content: [
       {
@@ -52,3 +65,8 @@ export function handleReportMissing(args: { context: string }): CallToolResult {
     ],
   }
 }
+
+export function handleReportMissing(args: { context: string }): CallToolResult {
+  log(`Missing tool reported: ${JSON.stringify(args)}`)
+  return getMoreToolsResult()
+}

package/src/index.ts

@@ -166,7 +166,13 @@ export {
   PostHogMCPAnalyticsEvent,
   PostHogMCPAnalyticsProperty,
 } from './extensions/constants'
-export { PostHogMCP } from './extensions/posthog-mcp'
+export { PostHogMCP, type PostHogMCPOptions } from './extensions/posthog-mcp'
+export { getMoreToolsResult } from './extensions/tools'
+export { setLogger } from './extensions/logger'
+// Re-export the posthog-node client so a single import works:
+//   import { PostHog, instrument } from "@posthog/mcp"
+// posthog-node stays a peer dependency, so this resolves the host app's installed copy.
+export { PostHog, type PostHogOptions } from 'posthog-node'
 export type {
   BeforeSendFn,
   CaptureEventData,
@@ -176,7 +182,11 @@ export type {
   MCPAnalyticsContextOptions,
   MCPAnalyticsIntentSource,
   MCPAnalyticsOptions,
+  MissingCapabilityCaptureData,
+  PreparedToolCall,
+  PrepareToolListOptions,
   ToolCallCaptureData,
+  ToolsListCaptureData,
   UserIdentity,
 } from './types'
 export type IdentifyFunction = MCPAnalyticsOptions['identify']

package/src/types.ts

@@ -50,6 +50,12 @@ export interface MCPAnalyticsOptions {
   logger?: LoggerFn
   /** Enable the `get_more_tools` virtual tool so agents can report missing functionality. */
   reportMissing?: boolean
+  /**
+   * Rename the `get_more_tools` virtual tool (the `reportMissing` feature).
+   * Defaults to `get_more_tools`. Set once here so the tool is advertised and
+   * detected under the same name.
+   */
+  missingCapabilityToolName?: string
   /** Enables the `conversation_id` tool parameter + prompt-back loop. */
   enableConversationId?: boolean
   /**
@@ -283,6 +289,19 @@ export interface ToolCallCaptureData extends McpCaptureCommon {
   toolDescription?: string
   /** Product category the tool belongs to (e.g. "Logs") → `$mcp_tool_category`. */
   category?: string
+  /**
+   * The agent's stated intent for this call → `$mcp_intent`. On the custom
+   * dispatcher path, read it off the incoming call with
+   * {@link PostHogMCP.prepareToolCall} (which pulls the injected `context`
+   * argument). Omitted when no intent was captured.
+   */
+  intent?: string
+  /**
+   * Where {@link ToolCallCaptureData.intent} came from → `$mcp_intent_source`.
+   * `context_parameter` when the client supplied it on the call, `inferred` when
+   * the host derived it. Defaults to `context_parameter` when an intent is set.
+   */
+  intentSource?: MCPAnalyticsIntentSource
   /** Captured call arguments → `$mcp_parameters` (sanitized + truncated). */
   parameters?: unknown
   /** Captured tool result → `$mcp_response` (sanitized + truncated). */
@@ -313,3 +332,66 @@ export interface InitializeCaptureData extends McpCaptureCommon {
   /** Wall-clock duration → `$mcp_duration_ms`. */
   durationMs?: number
 }
+
+/** Payload for {@link PostHogMCP.captureToolsList}. Emits `$mcp_tools_list`. */
+export interface ToolsListCaptureData extends McpCaptureCommon {
+  /**
+   * Names of the tools advertised in this `tools/list` response →
+   * `$mcp_listed_tool_names`. Powers "advertised but never called" analysis.
+   */
+  toolNames?: string[]
+  /** Captured request params → `$mcp_parameters` (sanitized + truncated). */
+  parameters?: unknown
+  /** Captured listing result → `$mcp_response` (sanitized + truncated). */
+  response?: unknown
+  /** Wall-clock duration → `$mcp_duration_ms`. */
+  durationMs?: number
+  /** Whether building the listing failed → `$mcp_is_error`. */
+  isError?: boolean
+  /** The thrown value when `isError` is true → fans out an `$exception` sibling. */
+  error?: unknown
+}
+
+/** Options for {@link PostHogMCP.prepareToolList}. */
+export interface PrepareToolListOptions {
+  /**
+   * Inject the `context` argument into every tool so agents state their intent
+   * (captured as `$mcp_intent`). `true` (default) uses the standard prompt;
+   * pass `{ description }` to customize it, or `false` to skip injection.
+   */
+  context?: boolean | MCPAnalyticsContextOptions
+  /**
+   * Append the `get_more_tools` virtual tool so agents can report a missing
+   * capability. Defaults to `false`. When the agent calls it, route the call to
+   * {@link PostHogMCP.captureMissingCapability} and reply with `getMoreToolsResult()`.
+   */
+  reportMissing?: boolean
+}
+
+/**
+ * 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.
+ */
+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. */
+  args?: Record<string, unknown>
+  /** True when `name` is the `get_more_tools` virtual tool. */
+  isMissingCapability: boolean
+}
+
+/** Payload for {@link PostHogMCP.captureMissingCapability}. Emits `$mcp_missing_capability`. */
+export interface MissingCapabilityCaptureData extends McpCaptureCommon {
+  /**
+   * The agent's description of the capability it wanted (the `context` argument
+   * on the `get_more_tools` call) → `$mcp_intent`.
+   */
+  context?: string
+  /** Captured call arguments → `$mcp_parameters` (sanitized + truncated). */
+  parameters?: unknown
+}

package/src/version.ts

@@ -1 +1 @@
-export const version = '0.3.0'
+export const version = '0.4.1'