:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import { RESOURCE_URI_META_KEY } from '@modelcontextprotocol/ext-apps/server'
import { isEmptyToolResult } from '@/lib/empty-tool-result'
import { estimateTokens } from '@/lib/estimate-tokens'
import { getNextPageHint } from '@/lib/next-page-hint'
import { formatResponse } from '@/lib/response'
import { isPrepareConfirmedActionResult } from '@/tools/confirmed-action-runtime'
import { POSTHOG_FORMATTED_RESULTS_OVERRIDE_KEY, POSTHOG_META_KEY, POSTHOG_TEXT_PROJECTION_KEY } from '@/tools/types'
import { APP_DATA_META_KEY, type AnalyticsMetadata, type WithAnalytics } from '@/ui-apps/types'
export interface ToolResultMeta {
ui?: { resourceUri?: string }
[POSTHOG_META_KEY]?: { outputFormat?: 'optimized' | 'json' }
}
export interface BuildToolResultOptions {
/** Raw return value from the tool handler (object or string). */
handlerResult: unknown
/** Tool-level `_meta` — determines UI app eligibility and JSON response flag. */
toolMeta?: ToolResultMeta | undefined
/** Tool name; embedded in analytics metadata for UI apps. */
toolName: string
/** The input params passed to the tool (used to read `output_format=json` escape hatch). */
params: unknown
/** Whether formatted-result text should win over structuredContent for this client profile. */
suppressStructuredContentForFormattedResults?: boolean | undefined
/**
* For inline-exec UI-app hosts (PostHog Desktop, Claude Code): when a compact
* formatted table is available, drop top-level `structuredContent` toward the model so
* it reads the compact table instead of the verbose JSON, and re-home the app payload
* onto `_meta` for the UI app (see APP_DATA_META_KEY). When there is NO formatted table
* the payload stays in the standard `structuredContent` field and the text channel gets
* a pointer instead of a second copy of it. Overridden by an explicit `output_format`.
*/
forceUiDataToMeta?: boolean | undefined
/** Native widgets need the handler object even when the tool has no MCP UI resource. */
includeAppData?: boolean | undefined
/** PostHog distinctId for analytics metadata (only read when a UI resource is present). */
distinctId?: string | undefined
mcpClientName?: string | undefined
/**
* When set, the inner tool's `_meta.ui.resourceUri` is placed on the response payload
* under both the new (`ui.resourceUri`) and legacy (`ui/resourceUri`) keys. Used by the
* single-exec wrapper to surface UI apps through the generic `exec` tool — clients only
* see `exec` registered, so the UI metadata has to ride on the per-call response.
*/
includeUiResponseMeta?: boolean
includeRenderNote?: boolean
}
/**
* Nominal brand stamped on payloads assembled by the exec wrapper. Detection
* is a field check rather than structural matching so regular tool handlers
* that happen to return a `{content:[{type:'text',…}]}` shape can never
* accidentally short-circuit the `buildToolResultPayload` pipeline.
*/
export const EXEC_BUILT_PAYLOAD = '__execBuiltPayload' as const
export interface ToolResultPayload {
content: Array<{ type: 'text'; text: string }>
structuredContent?: Record<string, unknown>
_meta?: Record<string, unknown>
[EXEC_BUILT_PAYLOAD]?: true
}
/**
* Detects a payload already assembled by the exec wrapper so `MCP.registerTool`
* can pass it through unchanged — re-running `buildToolResultPayload` would
* object-rest-destructure its `content` / `structuredContent` fields.
*
* We require the exec brand (rather than detecting by shape) so future tool
* handlers can't accidentally match and skip the pipeline (coding-agent
* suppression, analytics injection, UI-resourceUri normalization, etc.).
*/
export function isToolCallPayload(value: unknown): value is ToolResultPayload {
return (
typeof value === 'object' && value !== null && (value as Record<string, unknown>)[EXEC_BUILT_PAYLOAD] === true
)
}
interface BuiltResponseText {
structuredContentOnly: boolean
footers: string[]
resultEmpty: boolean
}
const builtResponseText = new WeakMap<ToolResultPayload, BuiltResponseText>()
/** Stamp a payload as exec-built so `isToolCallPayload` recognizes it. */
export function markExecPayload(payload: ToolResultPayload): ToolResultPayload {
const marked: ToolResultPayload = { ...payload, [EXEC_BUILT_PAYLOAD]: true }
const built = builtResponseText.get(payload)
if (built) {
builtResponseText.set(marked, built)
}
return marked
}
export function toolResultAnalyticsProperties(response: ToolResultPayload): Record<string, unknown> {
const built = builtResponseText.get(response)
return built?.resultEmpty ? { mcp_result_empty: true } : {}
}
/**
* Placeholder that replaces the text content when the payload rides in
* `structuredContent` alone (see `buildToolResultPayload`). Kept short and
* literal so the model knows where to read the result from.
*/
export const STRUCTURED_CONTENT_ONLY_TEXT = "Full result is in this response's structuredContent field."
export const UI_APP_RENDER_NOTE =
'The user already sees this result as an interactive view in the conversation. State your conclusion in text and do not repeat this data in your reply.'
/**
* Estimate output tokens from what the client actually receives — the serialized
* TOON/JSON/formatted string, not the raw handler object. TOON is materially
* smaller than JSON for tabular results, so measuring the raw object would
* over-count. `structuredContent` is normally excluded because it duplicates the
* text for UI tools; when the text is only the `STRUCTURED_CONTENT_ONLY_TEXT`
* pointer it duplicates nothing, so the structured payload is what gets counted.
*/
export function estimateResponseTokens(response: ToolResultPayload): number {
const built = builtResponseText.get(response)
if (response.structuredContent && built?.structuredContentOnly) {
return estimateTokens(response.structuredContent) + estimateTokens(built.footers.join('\n\n'))
}
return estimateTokens(response.content.map((part) => part.text).join(''))
}
/**
* Assembles the MCP tool-call response payload.
*
* Response channel choices:
* 1. When the handler returns a primitive string, we pass it through to `formatResponse`
* unchanged. Earlier, object-rest on a string exploded it into a character-indexed
* dict ({"0":"{","1":"\""...}).
* 2. When `formattedResults` is present AND the resolved client profile needs formatted
* text to win AND the caller didn't opt into JSON via `output_format=json`, we drop
* `structuredContent`. Coding agents surface `structuredContent` to the model in
* preference to `content[].text`, so keeping it would hide the formatted table
* behind raw JSON.
* 3. Conversely, a UI tool with no `formattedResults` on an inline-exec UI host keeps
* `structuredContent` and drops the mirrored text, so the payload reaches the agent
* exactly once instead of once per channel.
* 4. Native widgets use app metadata regardless of UI resources. Their models read
* the text channel unless the caller explicitly requests JSON.
*/
export function buildToolResultPayload(opts: BuildToolResultOptions): ToolResultPayload {
const {
handlerResult,
toolMeta,
toolName,
params,
suppressStructuredContentForFormattedResults,
forceUiDataToMeta,
includeAppData,
distinctId,
mcpClientName,
includeUiResponseMeta,
includeRenderNote,
} = opts
const isStringResult = typeof handlerResult === 'string'
const formattedResults: string | undefined = isStringResult
? undefined
: ((handlerResult as Record<string, unknown> | null | undefined)?.[POSTHOG_FORMATTED_RESULTS_OVERRIDE_KEY] as
| string
| undefined)
let rawResult: Record<string, unknown> | unknown[] | string
if (isStringResult) {
rawResult = handlerResult as string
} else if (Array.isArray(handlerResult)) {
rawResult = [...handlerResult]
} else {
const { [POSTHOG_FORMATTED_RESULTS_OVERRIDE_KEY]: _ignored, ...rest } = (handlerResult ?? {}) as Record<
string,
unknown
>
rawResult = rest
}
const resourceUri = toolMeta?.ui?.resourceUri
const hasUiResource = !!resourceUri
// Caller's per-call `output_format` wins over the tool's YAML default in `_meta`.
const callerOutputFormat = (params as { output_format?: 'optimized' | 'json' } | undefined)?.output_format
const effectiveOutputFormat = callerOutputFormat ?? toolMeta?.[POSTHOG_META_KEY]?.outputFormat
const useJson = effectiveOutputFormat === 'json'
const callerWantsJson = callerOutputFormat === 'json'
const isTextProjection =
!isStringResult && (handlerResult as Record<string, unknown> | null)?.[POSTHOG_TEXT_PROJECTION_KEY] === true
let structuredContent: WithAnalytics<typeof rawResult> | typeof rawResult = rawResult
if (hasUiResource && !isStringResult) {
const analyticsMetadata: AnalyticsMetadata = {
distinctId: distinctId ?? '',
toolName,
...(mcpClientName ? { mcpClientName } : {}),
}
structuredContent = {
...(rawResult as Record<string, unknown>),
_analytics: analyticsMetadata,
}
}
// Native widgets read metadata independently of the model's text format, so with app data
// present `structuredContent` would be a third copy of the rows the text and `_meta` already
// carry. MCP UI hosts only suppress it when a compact table can replace it for the model.
const suppressStructuredContent =
!!includeAppData ||
(!callerWantsJson &&
formattedResults !== undefined &&
(!!forceUiDataToMeta || !!suppressStructuredContentForFormattedResults))
// Inline-exec UI hosts surface BOTH `content[].text` and `structuredContent` to the
// model. A UI tool with no compact formatted table has nothing smaller to offer the
// text channel, so mirroring the payload there hands the agent a second full copy of
// the same rows. Carry it once, in `structuredContent` — the field the UI app reads
// from too — and leave a pointer in the text. `output_format` opts back into the
// mirrored serialization for callers that parse the text channel.
const structuredContentOnly =
!includeAppData &&
!!forceUiDataToMeta &&
hasUiResource &&
!isStringResult &&
!useJson &&
formattedResults === undefined
const body = structuredContentOnly
? STRUCTURED_CONTENT_ONLY_TEXT
: ((useJson && (includeAppData || isTextProjection) ? undefined : formattedResults) ??
(useJson ? JSON.stringify(rawResult) : formatResponse(rawResult)))
const footers: string[] = []
if (!isStringResult && !useJson && !structuredContentOnly && !isPrepareConfirmedActionResult(handlerResult)) {
const nextPageHint = getNextPageHint(toolName, rawResult)
if (nextPageHint) {
footers.push(nextPageHint)
}
}
if (includeRenderNote && hasUiResource && !useJson) {
footers.push(UI_APP_RENDER_NOTE)
}
const text = [body, ...footers].join('\n\n')
const payload: ToolResultPayload = {
content: [{ type: 'text', text }],
}
builtResponseText.set(payload, {
structuredContentOnly,
footers,
resultEmpty: isEmptyToolResult(handlerResult, toolName),
})
if (hasUiResource && !suppressStructuredContent) {
payload.structuredContent = structuredContent as Record<string, unknown>
}
if (includeUiResponseMeta && resourceUri) {
payload._meta = {
ui: { resourceUri },
[RESOURCE_URI_META_KEY]: resourceUri,
}
}
// Native widgets and MCP UI apps need the full data even when the model reads
// compact text. Their hosts preserve `_meta` without passing it to the model.
// Directly registered tools already advertise their UI resource in tools/list,
// so their app data must not depend on includeUiResponseMeta.
if ((includeAppData && !isStringResult) || (suppressStructuredContent && hasUiResource)) {
payload._meta = {
...payload._meta,
[APP_DATA_META_KEY]: structuredContent as Record<string, unknown>,
}
}
// `-prepare` tools have no UI resource, so UI apps driving a confirmed action
// read the hash from the app-only `_meta` channel instead of structuredContent.
if (isPrepareConfirmedActionResult(handlerResult)) {
payload._meta = {
...payload._meta,
[APP_DATA_META_KEY]: rawResult as Record<string, unknown>,
}
}
return payload
}