@posthog/mcp 0.14.1 → 0.16.0

package/src/extensions/sanitization.ts

@@ -4,7 +4,7 @@
 // Licensed under the MIT License: https://github.com/agentcathq/agentcat-typescript-sdk/blob/main/LICENSE
 
 import type { ErrorProperties, Event, McpEvent } from '../types'
-import { redactPii, sanitizeCapturedValue } from './mcp-payloads'
+import { sanitizeCapturedValue, sanitizeFreeText } from './mcp-payloads'
 
 type SanitizedRecord = Record<string, unknown>
 
@@ -32,14 +32,22 @@ export function sanitizeEvent<T extends Event | McpEvent>(event: T): T {
     result.parameters = sanitizeParameters(result.parameters)
   }
 
+  // Every event type, not just `resources/read`: `$identify` and the `$exception`
+  // sibling carry the same name, and a tool or prompt name is free text an
+  // application can spell as a URL too.
+  if (result.resourceName != null) {
+    result.resourceName = sanitizeCapturedValue(result.resourceName) as string
+  }
+
   // The intent comes straight from an agent-narrated `context` string, so it can
   // contain a secret the LLM read aloud or personal data it narrated about the
-  // user. Redact it like any other captured value, then strip structured PII
-  // (emails, phone numbers, IPs, cards, SSNs) rather than shipping it raw as
-  // `$mcp_intent`. PII redaction is scoped to the intent only — structured tool
-  // parameters and responses often hold the same shapes as legitimate data.
+  // user. `sanitizeFreeText` adds structured PII redaction (emails, phone numbers,
+  // IPs, cards, SSNs) to the passes every captured value gets, in the one order
+  // that works — see its doc comment. PII redaction is scoped to the intent only:
+  // structured tool parameters and responses often hold the same shapes as
+  // legitimate data.
   if (result.userIntent != null) {
-    result.userIntent = redactPii(sanitizeCapturedValue(result.userIntent) as string)
+    result.userIntent = sanitizeFreeText(result.userIntent)
   }
 
   if (result.llmModel != null) {

package/src/index.ts

@@ -14,6 +14,7 @@ import { applyMcpLibIdentity } from './extensions/lib-identity'
 import { deriveSessionIdFromMCPSession, getSessionInfo, newSessionId } from './extensions/session'
 import { instrumentLowLevelServer } from './extensions/instrument-lowlevel'
 import { instrumentHighLevelServer } from './extensions/instrument-highlevel'
+import { getFeedbackToolDescriptor, resolveCollectFeedbackOptions } from './extensions/feedback'
 import type {
   CaptureEventData,
   HighLevelMCPServerLike,
@@ -25,9 +26,9 @@ import type {
 } from './types'
 
 /**
- * Instruments an MCP server so PostHog auto-captures tool calls, tool listings, initialize
- * requests, identity, and exceptions. Returns a handle whose `capture()` method records
- * custom events, so you don't pass the server around after wiring it up.
+ * Instruments an MCP server so PostHog auto-captures tool calls, tool and resource listings,
+ * resource reads, initialize requests, identity, and exceptions. Returns a handle whose
+ * `capture()` method records custom events, so you don't pass the server around after wiring it up.
  *
  * **Idempotent per server instance.** Per-server tracking state lives in a module-level
  * `WeakMap<MCPServerLike, MCPAnalyticsData>` (`internal.ts`); a second `instrument()` call
@@ -52,6 +53,17 @@ import type {
  */
 function instrument(server: unknown, posthog: PostHog, options: MCPAnalyticsOptions = {}): McpAnalytics {
   const logger = createLogger(options?.logger)
+
+  // Fail fast on a `collectFeedback` config error (reserved extra key,
+  // undeclared extraRequired). Above the graceful-degradation try so it throws
+  // out of instrument() like PostHogMCP's constructor does — inside the catch it
+  // would silently disable ALL analytics for the server, not just feedback.
+  // `options?.` — untyped JavaScript can pass null options (see logger-isolation.test.ts).
+  const feedbackOptions = resolveCollectFeedbackOptions(options?.collectFeedback)
+  if (feedbackOptions) {
+    getFeedbackToolDescriptor(feedbackOptions)
+  }
+
   try {
     if (!posthog) {
       logger('Warning: No PostHog client passed to instrument(). Events will not be sent anywhere.')
@@ -129,6 +141,7 @@ function getLowLevelServer(server: MCPServerLike | HighLevelMCPServerLike): MCPS
  */
 const DEFAULT_OPTIONS = {
   reportMissing: false,
+  collectFeedback: false,
   enableConversationId: false,
 } satisfies Partial<MCPAnalyticsOptions>
 
@@ -215,14 +228,22 @@ export {
 export { getRequestHeaders } from './extensions/request-headers'
 export { PostHogMCP, type PostHogMCPOptions } from './extensions/posthog-mcp'
 export { getMoreToolsResult } from './extensions/tools'
+export { sendFeedbackResult, SEND_FEEDBACK_TOOL_NAME } from './extensions/feedback'
 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 {
+  FeedbackCaptureData,
+  FeedbackExtraPropertySchema,
+  CollectFeedbackOptions,
+  FeedbackReport,
+  FeedbackSentiment,
+  FeedbackType,
   BeforeSendFn,
   CaptureEventData,
+  CollectFeedbackConfig,
   InitializeCaptureData,
   McpAnalytics,
   McpCaptureCommon,

package/src/types.ts

@@ -70,6 +70,7 @@ export interface MCPRequestParamsLike {
   _meta?: JsonRecord
   arguments?: JsonRecord
   name?: string
+  uri?: string
   [key: string]: unknown
 }
 
@@ -100,6 +101,20 @@ export interface MCPAnalyticsOptions {
   logger?: LoggerFn
   /** Enable the `get_more_tools` virtual tool so agents can report missing functionality. */
   reportMissing?: boolean
+  /**
+   * Inject the `send_feedback` virtual tool so agents can send feedback about
+   * this server to its developers — a missing capability (the priority
+   * category), a tool that failed or confused them, or praise. Calls to it emit
+   * `$mcp_feedback` (never a `$mcp_tool_call`). Off by default.
+   *
+   * `true` uses the defaults; the object form renames the tool, replaces its
+   * description, declares host-specific `extraProperties`, or wires an
+   * `onFeedback` handler that routes reports to a real backend.
+   *
+   * Covers what `reportMissing` covers (as `feedback_type: "missing_capability"`),
+   * so new integrations should enable only one of the two.
+   */
+  collectFeedback?: CollectFeedbackConfig
   /**
    * Rename the `get_more_tools` virtual tool (the `reportMissing` feature).
    * Defaults to `get_more_tools`. Set once here so the tool is advertised and
@@ -185,6 +200,78 @@ export interface MCPAnalyticsContextOptions {
   description?: string
 }
 
+export type FeedbackType = 'missing_capability' | 'issue' | 'praise' | 'other'
+export type FeedbackSentiment = 'positive' | 'neutral' | 'negative' | 'mixed'
+
+/** The `collectFeedback` option: `true` for the defaults, or the object form. */
+export type CollectFeedbackConfig = boolean | CollectFeedbackOptions
+
+/**
+ * A host-declared input-schema fragment for one `send_feedback` extra property —
+ * plain JSON Schema, the same shape the MCP `tools/list` wire format uses.
+ */
+export interface FeedbackExtraPropertySchema {
+  type: string
+  description?: string
+  enum?: string[]
+  [key: string]: unknown
+}
+
+/** Object form of {@link CollectFeedbackConfig}. */
+export interface CollectFeedbackOptions {
+  /**
+   * Rename the `send_feedback` virtual tool. Set once so the tool is advertised
+   * and detected under the same name. Defaults to `send_feedback`.
+   */
+  toolName?: string
+  /** Replace the default tool description. */
+  description?: string
+  /**
+   * Host-specific fields merged into the tool's advertised input schema. Each
+   * declared key is captured as a `$mcp_feedback_<key>` event property (through
+   * the standard sanitize/truncate pipeline); arguments the agent invents beyond
+   * the schema are never captured. A key that collides with a core field or an
+   * SDK-injected argument throws at configuration time.
+   */
+  extraProperties?: Record<string, FeedbackExtraPropertySchema>
+  /** Keys of `extraProperties` to advertise as required. */
+  extraRequired?: string[]
+  /**
+   * Route each report to a real backend (`instrument()` path only — a custom
+   * dispatcher routes reports itself, see {@link PreparedToolCall.isFeedback}).
+   * Return a string to replace the default acknowledgement text. A throw is
+   * logged and falls back to the default reply; the `$mcp_feedback` event is
+   * captured either way. The returned string is captured as `$mcp_response`
+   * through the generic sanitize pipeline only — unlike `$mcp_feedback_summary`
+   * / `details`, it does not get structured-PII redaction, so avoid echoing
+   * the agent's raw report text back in it.
+   */
+  onFeedback?: (report: FeedbackReport) => MaybePromise<string | void>
+}
+
+/** One parsed `send_feedback` call, as handed to `onFeedback` and the dispatcher. */
+export interface FeedbackReport {
+  /** Invalid or missing values fall back to `other`. */
+  feedbackType: FeedbackType
+  /** One-sentence summary; empty string when the agent omitted it. */
+  summary: string
+  sentiment?: FeedbackSentiment
+  frictionPoints?: string
+  suggestedImprovement?: string
+  details?: string
+  /** The existing tool the feedback is about (`tool_name` argument). */
+  toolName?: string
+  taskCompleted?: boolean
+  /**
+   * Values of the declared `extraProperties` fields that match their declared
+   * `type`/`enum`. A value the agent sent with the wrong shape is left out
+   * (find it in `raw` if you need it), so these are safe to trust as declared.
+   */
+  extras: JsonRecord
+  /** The full raw arguments, for the handler only — never captured. */
+  raw: JsonRecord
+}
+
 export interface MCPAnalyticsModelOptions {
   description?: string
 }
@@ -589,6 +676,14 @@ export interface PrepareToolListOptions {
    * {@link PostHogMCP.captureMissingCapability} and reply with `getMoreToolsResult()`.
    */
   reportMissing?: boolean
+  /**
+   * Append the `send_feedback` virtual tool so agents can send feedback.
+   * Defaults to `false`, and requires the `PostHogMCP` constructor's
+   * `collectFeedback` option (the enable switch that also gates detection).
+   * When the agent calls it, route the call to
+   * {@link PostHogMCP.captureFeedback} and reply with `sendFeedbackResult()`.
+   */
+  collectFeedback?: boolean
 }
 
 /** Options for {@link PostHogMCP.prepareToolCall}. */
@@ -620,6 +715,18 @@ export interface PreparedToolCall {
   args?: Record<string, unknown>
   /** True when `name` is the `get_more_tools` virtual tool. */
   isMissingCapability: boolean
+  /**
+   * True when `name` is the `send_feedback` virtual tool AND the constructor's
+   * `collectFeedback` option is set. Always false without that opt-in, so a real
+   * tool that happens to use the name is never shadowed.
+   */
+  isFeedback: boolean
+  /**
+   * The parsed feedback report, set only when {@link PreparedToolCall.isFeedback}
+   * is true. Pass it to {@link PostHogMCP.captureFeedback} and to your own
+   * feedback backend, then reply with `sendFeedbackResult()` or a custom text.
+   */
+  feedbackReport?: FeedbackReport
 }
 
 /** Payload for {@link PostHogMCP.captureMissingCapability}. Emits `$mcp_missing_capability`. */
@@ -636,3 +743,16 @@ export interface MissingCapabilityCaptureData extends McpCaptureCommon {
   /** Captured call arguments → `$mcp_parameters` (sanitized + truncated). */
   parameters?: unknown
 }
+
+/** Payload for {@link PostHogMCP.captureFeedback}. Emits `$mcp_feedback`. */
+export interface FeedbackCaptureData extends McpCaptureCommon {
+  /**
+   * The parsed report (from {@link PreparedToolCall.feedbackReport}) →
+   * `$mcp_feedback_*` properties, with the summary and details as `$mcp_intent`.
+   */
+  report: FeedbackReport
+  /** The calling model id -> `$mcp_llm_model`. */
+  llmModel?: string
+  /** How the model id was obtained -> `$mcp_llm_model_source`. */
+  llmModelSource?: MCPAnalyticsModelSource
+}

package/src/version.ts

@@ -1 +1 @@
-export const version = '0.14.1'
+export const version = '0.16.0'