@posthog/mcp 0.10.6 → 0.10.8

package/src/extensions/output-instructions.ts

@@ -0,0 +1,231 @@
+import type { LoggerFn } from './logger'
+import { log } from './logger'
+import type { AnalyticsInjectableJsonSchema } from './analytics-parameters'
+
+/**
+ * The `conversation_id` session handle reaches the agent as a text block appended to the
+ * tool result. That block is invisible to any client that reads
+ * `structuredContent` instead of `content` — which is what clients do whenever a
+ * tool declares an `outputSchema`. Measured against Claude Code, correlation for
+ * such tools drops to zero.
+ *
+ * The fix is to mirror the session handle into `structuredContent` as well, which this
+ * module does in two halves that must stay in that order:
+ *
+ *   1. declare `_mcp_instructions` on the tool's advertised `outputSchema`
+ *   2. write it into the result's `structuredContent`
+ *
+ * The declaration is what makes the write safe. The MCP client ajv-validates
+ * `structuredContent` against the schema from `tools/list`, and
+ * `zod-to-json-schema` emits `additionalProperties: false` for a plain
+ * `z.object`, so an undeclared key is not ignored — it fails the entire tool
+ * result. Only tools that got the declaration are ever written to.
+ */
+export const MCP_INSTRUCTIONS_KEY = '_mcp_instructions'
+
+const INSTRUCTIONS_FIELD_DESCRIPTION =
+  'Server-issued handles for this conversation, and what to do with them. Read and follow.'
+
+const CONVERSATION_ID_FIELD_DESCRIPTION =
+  'Echo this exact value as the conversation_id argument on every subsequent tool call.'
+
+export interface OutputInstructionsInjectableTool {
+  name?: string
+  outputSchema?: unknown
+  [key: string]: unknown
+}
+
+/**
+ * True when we can safely declare {@link MCP_INSTRUCTIONS_KEY} on this tool's
+ * advertised output schema.
+ *
+ * Requires a plain-object schema we can extend. A tool with no `outputSchema`
+ * has nothing to mirror into and keeps working through `content`; a composed
+ * schema (`oneOf`/`allOf`/`anyOf`/`$ref`) has no single `properties` bag to add
+ * to. Both stay content-only, matching the policy on the input side.
+ */
+export function canDeclareOutputInstructions(outputSchema: unknown): boolean {
+  if (!outputSchema || typeof outputSchema !== 'object') {
+    return false
+  }
+
+  // Only the JSON Schema a tool advertises can answer this. A Zod schema or raw
+  // shape — what the high-level registry stores — has no `properties` bag, so
+  // every check below would pass vacuously and report `true` for a tool whose
+  // schema we actually skipped. Refuse rather than guess: callers holding a Zod
+  // value must read the recorded answer off the ownership registry instead.
+  if (isSchemaObjectLike(outputSchema)) {
+    return false
+  }
+
+  const schema = outputSchema as AnalyticsInjectableJsonSchema
+  if (schema.$ref || schema.oneOf || schema.allOf || schema.anyOf) {
+    return false
+  }
+
+  // `properties` must be a plain object if it is present at all. A tool that
+  // advertises something else is malformed, and harmlessly so until we try to
+  // declare into it — assigning a key to a boolean throws, and that throw
+  // surfaces inside the `tools/list` wrapper, failing the entire listing over a
+  // schema we only wanted to annotate.
+  const { properties } = schema
+  if (
+    properties !== undefined &&
+    (typeof properties !== 'object' || properties === null || Array.isArray(properties))
+  ) {
+    return false
+  }
+  return !properties || !Object.prototype.hasOwnProperty.call(properties, MCP_INSTRUCTIONS_KEY)
+}
+
+/** A single Zod schema — the internals every version brands its instances with. */
+function isZodLike(entry: unknown): boolean {
+  return !!entry && typeof entry === 'object' && ('_def' in entry || '_zod' in entry || '~standard' in entry)
+}
+
+/**
+ * Whether this is a JSON Schema, judged on the *value* of each marker rather
+ * than the key alone — a raw Zod shape is free to name a field `type` or
+ * `properties`, but its values are Zod schemas, not a string and a property bag.
+ */
+function looksLikeJsonSchema(candidate: Record<string, unknown>): boolean {
+  if (typeof candidate.type === 'string' || typeof candidate.$ref === 'string') {
+    return true
+  }
+  if (Array.isArray(candidate.oneOf) || Array.isArray(candidate.allOf) || Array.isArray(candidate.anyOf)) {
+    return true
+  }
+  const { properties } = candidate
+  return !!properties && typeof properties === 'object' && !isZodLike(properties)
+}
+
+/** A Zod schema, or a raw shape whose values are Zod schemas. */
+function isSchemaObjectLike(value: unknown): boolean {
+  const candidate = value as Record<string, unknown>
+  if (isZodLike(candidate)) {
+    return true
+  }
+
+  // Settle "is this a JSON Schema" before scanning the values, because a schema
+  // may legitimately declare a property named `_def` — and the scan below would
+  // read that property's schema object as a Zod value and skip a tool we could
+  // have annotated perfectly well.
+  if (looksLikeJsonSchema(candidate)) {
+    return false
+  }
+  return Object.values(candidate).some(isZodLike)
+}
+
+/**
+ * Returns a copy of the tool with an optional {@link MCP_INSTRUCTIONS_KEY}
+ * property added to its output schema, or the tool untouched when it has no
+ * output schema to extend.
+ *
+ * The property is never added to `required` — a result without it must stay
+ * valid, since every tool result predating this change lacks it.
+ */
+export function addInstructionsToOutputSchema<TTool extends OutputInstructionsInjectableTool>(
+  tool: TTool,
+  logger: LoggerFn = log
+): TTool {
+  const toolName = tool.name || 'unknown'
+  const original = tool.outputSchema
+
+  // No output schema means the client reads `content`, where the session handle already
+  // rides. Nothing to declare, and nothing broken.
+  if (!original || typeof original !== 'object') {
+    return tool
+  }
+
+  if (!canDeclareOutputInstructions(original)) {
+    const schema = original as AnalyticsInjectableJsonSchema
+    if (schema.properties && Object.prototype.hasOwnProperty.call(schema.properties, MCP_INSTRUCTIONS_KEY)) {
+      logger(
+        `WARN: Tool "${toolName}" already declares '${MCP_INSTRUCTIONS_KEY}' in its output schema. Leaving it alone.`
+      )
+    } else {
+      logger(
+        `WARN: Tool "${toolName}" has a complex output schema (oneOf/allOf/anyOf/$ref). Skipping '${MCP_INSTRUCTIONS_KEY}' declaration; its session handle stays content-only.`
+      )
+    }
+    return tool
+  }
+
+  const modifiedTool = { ...tool }
+  // Deep copy: the server may reuse or freeze the schema object it handed us.
+  const outputSchema = JSON.parse(JSON.stringify(original)) as AnalyticsInjectableJsonSchema
+
+  if (!outputSchema.properties) {
+    outputSchema.properties = {}
+  }
+
+  outputSchema.properties[MCP_INSTRUCTIONS_KEY] = {
+    type: 'object',
+    description: INSTRUCTIONS_FIELD_DESCRIPTION,
+    properties: {
+      conversation_id: {
+        type: 'string',
+        description: CONVERSATION_ID_FIELD_DESCRIPTION,
+      },
+      instructions: { type: 'string' },
+    },
+  }
+
+  modifiedTool.outputSchema = outputSchema
+  return modifiedTool
+}
+
+/**
+ * Declares {@link MCP_INSTRUCTIONS_KEY} across a tool listing. Tools without an
+ * output schema, and tools whose schema we cannot extend, pass through unchanged.
+ */
+export function addInstructionsToOutputSchemas<TTool extends OutputInstructionsInjectableTool>(
+  tools: TTool[],
+  logger: LoggerFn = log
+): TTool[] {
+  return tools.map((tool) => addInstructionsToOutputSchema(tool, logger))
+}
+
+export interface ConversationInstructions {
+  conversation_id: string
+  instructions: string
+}
+
+const ECHO_INSTRUCTION = 'Send this conversation_id as an argument on every subsequent tool call in this conversation.'
+
+/** The payload mirrored into `structuredContent` for a tool we declared the key on. */
+export function buildConversationInstructions(conversationId: string): ConversationInstructions {
+  return { conversation_id: conversationId, instructions: ECHO_INSTRUCTION }
+}
+
+/**
+ * Adds {@link MCP_INSTRUCTIONS_KEY} to a result's `structuredContent`, which is
+ * where clients look once a tool declares an `outputSchema` — the `content` text
+ * block carrying the session handle is invisible to them.
+ *
+ * Unlike the text block, this rides *every* response rather than only the one
+ * that minted the session handle, so an agent that drops it can read it back.
+ *
+ * Returns the result untouched when there is no plain-object `structuredContent`
+ * to extend, or when the tool already produced its own key — customer data wins.
+ * Never mutates the input.
+ */
+export function mirrorInstructionsIntoStructuredContent(result: unknown, conversationId: string): unknown {
+  if (!result || typeof result !== 'object') {
+    return result
+  }
+  const structuredContent = (result as { structuredContent?: unknown }).structuredContent
+  if (!structuredContent || typeof structuredContent !== 'object' || Array.isArray(structuredContent)) {
+    return result
+  }
+  if (Object.prototype.hasOwnProperty.call(structuredContent, MCP_INSTRUCTIONS_KEY)) {
+    return result
+  }
+  return {
+    ...result,
+    structuredContent: {
+      ...structuredContent,
+      [MCP_INSTRUCTIONS_KEY]: buildConversationInstructions(conversationId),
+    },
+  }
+}

package/src/extensions/session.ts

@@ -15,6 +15,7 @@ import { INACTIVITY_TIMEOUT_IN_MINUTES } from './constants'
 import { deterministicPrefixedId, newPrefixedId } from './ids'
 import { getServerTrackingData, setServerTrackingData } from './internal'
 import { decodeSessionId, readMcpSessionHeader } from './session-token'
+import type { SessionTokenPayload } from './session-token'
 
 export function newSessionId(): string {
   return newPrefixedId('ses')
@@ -29,39 +30,77 @@ export function deriveSessionIdFromMCPSession(mcpSessionId: string): string {
 }
 
 /**
- * Resolves the session id for a request: from the replayed session token, from
- * the transport's MCP session id, or — when the request carries nothing — from
- * this instance's memory. Also saves the token's client name/version so events
- * built later in the request can use them (see getSessionInfo).
+ * Derives the SDK session id from the agent's conversation handle. Deterministic
+ * and unsalted on purpose: two pods that never met must agree on the session, and
+ * the 2026-07-28 revision leaves them no shared state to agree through.
+ *
+ * Hashed rather than used verbatim so an MCP session can never collide with a
+ * Session Replay id — a bare uuidv7 would render a "View recording" button that
+ * resolves to nothing.
+ *
+ * Exported because this *is* the cross-SDK contract: posthog-python has to
+ * reproduce it byte for byte or the same conversation splits into two sessions
+ * depending on which SDK served the call.
  */
-export function getSessionId(server: MCPServerLike, extra?: CompatibleRequestHandlerExtra): string {
+export function deriveSessionIdFromConversation(conversationId: string): string {
+  return deterministicPrefixedId('ses', conversationId)
+}
+
+/**
+ * Resolves the session id for a request. Three steps, first match wins:
+ *
+ *   1. the agent carried a `conversation_id` tool argument   — 2026-07-28
+ *   2. the request carried a session id                      — 2025-11-25
+ *   3. nothing was carried, so reuse this instance's own id  — stdio
+ *
+ * The split mirrors the two protocol revisions. 2026-07-28 removed protocol-level
+ * sessions, so the only thing that can carry a session across calls is the agent
+ * itself (1). 2025-11-25 kept the session on the connection, so the request
+ * carries it (2). 3 is for stdio, where neither applies — there is no
+ * HTTP request to carry anything, and no agent handle unless the host opted in.
+ */
+export function getSessionId(
+  server: MCPServerLike,
+  extra?: CompatibleRequestHandlerExtra,
+  conversationId?: string
+): string {
   const data = getServerTrackingData(server)
   if (!data) {
     throw new Error('Server tracking data not found')
   }
 
-  // Our token rides the `mcp-session-id` request header, which stateless
-  // transports ignore — so read it ourselves.
-  const sessionHeader = readMcpSessionHeader(extra?.requestInfo?.headers)
-  const token = decodeSessionId(sessionHeader)
-
-  let sessionId: string
-  if (token) {
-    // Token we minted at `initialize` (see session-token.ts).
-    data.sessionSource = 'token'
-    data.sessionInfo.clientName = token.clientName
-    data.sessionInfo.clientVersion = token.clientVersion
-    data.sessionInfo.protocolVersion = token.protocolVersion
-    sessionId = token.sessionId
-  } else if (extra?.sessionId) {
-    // Session id issued by a stateful transport: hash it so the same MCP
-    // session maps to the same SDK session across restarts.
-    data.sessionSource = 'mcp'
-    sessionId = deriveSessionIdFromMCPSession(extra.sessionId)
-  } else {
-    sessionId = getSessionIdFromMemory(data)
+  // 1. The agent's conversation handle. It outranks both steps below because it
+  // is the only id that survives reconnects, restarts, and the per-request
+  // server instances the 2026-07-28 revision introduces. Hashed rather than used
+  // verbatim so it can never collide with Session Replay ids.
+  //
+  // This returns instead of falling through to the shared-state writes at the
+  // end: the handle belongs to this one request, and persisting it would leak
+  // one chat's session onto a concurrent chat's `tools/list`.
+  //
+  // `lastActivity` therefore does not advance either, so a conversation that
+  // always echoes lets the in-memory fallback age past the inactivity timeout —
+  // and a later call carrying no handle rotates it. That is the honest reading:
+  // the fallback session really has been idle for that whole time.
+  if (conversationId) {
+    // The handle decides the *session*, but the request may still carry our token,
+    // and on a stateless instance that never processed `initialize` its payload is
+    // the only place client identity exists. Restore that before returning: the
+    // early return is about not persisting a session, not about ignoring what the
+    // request told us about the client. Without this, tool calls and `$identify`
+    // go out unattributed on exactly the deployments this branch exists for.
+    applyTokenClientIdentity(data, extra)
+    return deriveSessionIdFromConversation(conversationId)
   }
 
+  // 2. A session id the request itself carried (undefined if it carried none).
+  const carriedByRequest = readSessionIdFromRequest(data, extra)
+
+  // 3. Nothing carried, so fall back to the id this instance already holds.
+  const sessionId = carriedByRequest ?? getSessionIdFromMemory(data)
+
+  // 2 and 3 are connection-scoped, so their result is remembered for the
+  // next request on this instance. 1 never reaches here.
   data.sessionId = sessionId
   data.lastActivity = new Date()
   setServerTrackingData(server, data)
@@ -69,9 +108,69 @@ export function getSessionId(server: MCPServerLike, extra?: CompatibleRequestHan
 }
 
 /**
- * Nothing replayed on this request: keep the id we already have. Only
- * generated sessions roll over on inactivity — token/MCP ids live as long as
- * the client replays them, and regenerating one would split the session.
+ * Restores the client name/version and protocol version baked into our token at
+ * mint time, and hands the decoded token back so the caller can also take the
+ * session id from it.
+ *
+ * Split out from step 2 because the two halves of the token have different
+ * scopes. The session id it carries is per-chat, so a conversation-anchored
+ * request must not adopt it. The client identity is per-connection — the same
+ * client for every request on it — so a conversation-anchored request should,
+ * and on a stateless instance that never saw `initialize` this is the only
+ * source of it.
+ */
+function applyTokenClientIdentity(
+  data: MCPAnalyticsData,
+  extra?: CompatibleRequestHandlerExtra
+): SessionTokenPayload | undefined {
+  const token = decodeSessionId(readMcpSessionHeader(extra?.requestInfo?.headers))
+  if (!token) {
+    return undefined
+  }
+  data.sessionInfo.clientName = token.clientName
+  data.sessionInfo.clientVersion = token.clientVersion
+  data.sessionInfo.protocolVersion = token.protocolVersion
+  return token
+}
+
+/**
+ * 2. The session id a request carried. Two sources, tried in order: our own token
+ * on the `mcp-session-id` header, then the raw session id a stateful transport
+ * issued. Returns undefined when the request carried neither, which is what
+ * sends the caller on to 3.
+ *
+ * Both are 2025-11-25 mechanisms. The 2026-07-28 revision removed that header
+ * outright — servers MUST NOT mint or echo it — so this entire step becomes
+ * legacy-only once era detection lands.
+ */
+function readSessionIdFromRequest(data: MCPAnalyticsData, extra?: CompatibleRequestHandlerExtra): string | undefined {
+  // 2a. A token we minted at `initialize` and the client replayed. It rides the
+  // `mcp-session-id` header, which stateless transports don't surface as
+  // extra.sessionId, so read the header ourselves.
+  const token = applyTokenClientIdentity(data, extra)
+  if (token) {
+    data.sessionSource = 'token'
+    return token.sessionId
+  }
+
+  // 2b. No token, but a stateful transport issued its own session id. Hash it so
+  // the same MCP session maps to the same SDK session across restarts.
+  if (extra?.sessionId) {
+    data.sessionSource = 'mcp'
+    return deriveSessionIdFromMCPSession(extra.sessionId)
+  }
+
+  return undefined
+}
+
+/**
+ * 3. The request carried nothing, so keep the id this instance already holds —
+ * minted once at `instrument()`. This is what groups a stdio server's calls,
+ * where there is no header and no transport session to read.
+ *
+ * Only self-generated ids roll over on inactivity. Token and transport ids live
+ * as long as the client replays them, so regenerating one would split a session
+ * that is still very much alive.
  */
 function getSessionIdFromMemory(data: MCPAnalyticsData): string {
   const timeoutMs = INACTIVITY_TIMEOUT_IN_MINUTES * 60 * 1000
@@ -125,5 +224,5 @@ export function getSessionInfo(
 
   data.sessionInfo = sessionInfo
   setServerTrackingData(server, data)
-  return data.sessionInfo
+  return { ...sessionInfo }
 }

package/src/types.ts

@@ -57,7 +57,21 @@ export interface MCPAnalyticsOptions {
    * detected under the same name.
    */
   missingCapabilityToolName?: string
-  /** Enables the `conversation_id` tool parameter + prompt-back loop. */
+  /**
+   * Opt in to session correlation for the MCP **2026-07-28** revision, which removed
+   * protocol-level sessions: no `initialize`, no `mcp-session-id` header, and a fresh
+   * server instance per HTTP request. With none of those left to anchor on, the only
+   * thing that can carry a session across calls is the agent itself.
+   *
+   * Turning this on injects a `conversation_id` parameter into every tool, mints one
+   * on the first call, asks the agent to echo it back, and derives `$session_id` from
+   * that handle — so calls correlate across reconnects, restarts, and per-request
+   * instances.
+   *
+   * Off by default, and fully inert when off: no parameter is injected, no schema is
+   * touched, no prompt-back is appended, and `$session_id` resolves exactly as it did
+   * before (the request's own session id, else this instance's).
+   */
   enableConversationId?: boolean
   /**
    * Emit a `$exception` event alongside any failed tool call. Defaults to `true`.
@@ -123,6 +137,8 @@ export type RegisteredTool = {
   /** MCP tool `_meta` block (spec-allowed arbitrary metadata, e.g. `category`). */
   _meta?: Record<string, unknown>
   inputSchema?: unknown
+  /** Present when the tool was registered with a declared output schema. */
+  outputSchema?: unknown
   update?: (...args: unknown[]) => unknown
 } & ({ callback: ToolCallback; handler?: never } | { handler: ToolCallback; callback?: never })
 
@@ -274,6 +290,12 @@ export interface SessionInfo {
 export interface AnalyticsParameterOwnership {
   context: boolean
   conversationId: boolean
+  /**
+   * True when we declared `_mcp_instructions` on this tool's advertised output
+   * schema, so writing that key into `structuredContent` will validate. False
+   * for tools with no output schema, or one we could not extend.
+   */
+  outputInstructions: boolean
 }
 
 export interface MCPAnalyticsData {

package/src/version.ts

@@ -1 +1 @@
-export const version = '0.10.6'
+export const version = '0.10.8'