Skip to content

: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.

6.7 KB
Raw Blame
import { RESOURCE_URI_META_KEY } from '@modelcontextprotocol/ext-apps/server'
import type { Tool as McpTool } from '@modelcontextprotocol/sdk/types.js'
import { z } from 'zod'

import { markExecPayload, type ToolResultPayload } from '@/lib/build-tool-result'
import { DISPATCHABLE_APP_KEYS, RENDER_UI_RESOURCE_URI, URI_MAP, type UiAppKey } from '@/resources/ui-apps.generated'
import RENDER_UI_EXPLAIN_CHART from '@/templates/render-ui-explain-chart.md'
import RENDER_UI_PROMPT from '@/templates/render-ui-prompt.md'
import { APP_DATA_META_KEY } from '@/ui-apps/types'

import { type Context, type Tool, type ZodObjectAny } from './types'

export const RENDER_UI_TOOL_NAME = 'render-ui'
export const RENDER_UI_TOOL_TITLE = 'Render a PostHog visualization'
export const RENDER_UI_TOOL_DESCRIPTION = RENDER_UI_PROMPT.trim()

// OpenAI's plugin review rejects a tools/list entry without these hints.
export const RENDER_UI_TOOL_ANNOTATIONS = {
    destructiveHint: false,
    idempotentHint: true,
    openWorldHint: false,
    readOnlyHint: true,
} as const

export function renderUiDescription(renderableNames: string[]): string {
    return renderableNames.includes('explain-chart')
        ? `${RENDER_UI_TOOL_DESCRIPTION}\n\n${RENDER_UI_EXPLAIN_CHART.trim()}`
        : RENDER_UI_TOOL_DESCRIPTION
}

// Reverse of URI_MAP so a tool's `_meta.ui.resourceUri` resolves back to its app key.
const URI_TO_APP_KEY = new Map<string, UiAppKey>(
    Object.entries(URI_MAP).map(([appKey, uri]) => [uri, appKey as UiAppKey])
)

const DISPATCHABLE = new Set<UiAppKey>(DISPATCHABLE_APP_KEYS)

/** The dispatchable app key for a tool, or undefined when it has no renderable UI app. */
function toDispatchableAppKey(tool: Pick<McpTool, '_meta'>): UiAppKey | undefined {
    const ui = tool._meta?.ui
    if (!ui || typeof ui !== 'object' || !('resourceUri' in ui) || typeof ui.resourceUri !== 'string') {
        return undefined
    }
    const appKey = URI_TO_APP_KEY.get(ui.resourceUri)
    return appKey && DISPATCHABLE.has(appKey) ? appKey : undefined
}

/**
 * Names of the tools `render-ui` can render — those whose UI app exposes a reusable view.
 * Restricted to read-only tools: `render-ui` is annotated read-only, so it must not be a
 * back door for dispatching state-changing tools (e.g. `survey-launch`, `workflows-create`).
 */
export function getRenderableToolNames(allTools: Pick<McpTool, 'name' | 'annotations' | '_meta'>[]): string[] {
    return allTools
        .filter((tool) => tool.annotations?.readOnlyHint && toDispatchableAppKey(tool) !== undefined)
        .map((tool) => tool.name)
}

/** OpenAI caches the advertised catalog across accounts, so execution must
 *  validate the same input shape against the current account's allowed tools. */
export function makeRenderUiSchema(
    toolNames: [string, ...string[]]
): z.ZodObject<{ tool_name: z.ZodEnum<Record<string, string>>; tool_input: z.ZodOptional<z.ZodRecord> }> {
    return z.object({
        tool_name: z
            .enum(toolNames)
            .describe('A tool that has a UI app — its visualization will be rendered for the user.'),
        tool_input: z
            .record(z.string(), z.unknown())
            .optional()
            .describe('The generated input for that tool. The UI app uses it to fetch and render the visualization.'),
    })
}

type RenderUiSchema = ReturnType<typeof makeRenderUiSchema>

export type RenderUiAppDataLoader = (
    toolName: string,
    toolInput: Record<string, unknown>,
    appKey: UiAppKey
) => Promise<unknown>

/**
 * Builds the `render-ui` umbrella tool. Returns `null` when no tool in `allTools`
 * has a renderable UI app (a `z.enum` needs at least one value, and there is
 * nothing to render anyway). It emits a render directive (`{ tool_name, tool_input,
 * app_key }` + the render-ui resourceUri) for the model, and the data from
 * `loadAppData` on the app-only `_meta` key. The UI app fetches the data itself when
 * none was preloaded.
 */
export function createRenderUiTool(
    allTools: Tool<ZodObjectAny>[],
    context: Context,
    mcpClientName?: string,
    loadAppData?: RenderUiAppDataLoader
): Tool<RenderUiSchema> | null {
    const renderableNames = getRenderableToolNames(allTools)
    if (renderableNames.length === 0) {
        return null
    }
    const schema = makeRenderUiSchema(renderableNames as [string, ...string[]])

    return {
        name: RENDER_UI_TOOL_NAME,
        title: RENDER_UI_TOOL_TITLE,
        description: renderUiDescription(renderableNames),
        schema,
        scopes: [],
        annotations: { ...RENDER_UI_TOOL_ANNOTATIONS },
        // Advertise the umbrella UI resource on the tool definition itself.
        // MCP Apps hosts (e.g. Claude) discover renderable tools from `tools/list`
        // `_meta.ui.resourceUri`, pre-fetch the template, and only mount the iframe
        // for a tool declared this way — the result-level `_meta` alone is ignored.
        // `registerTool` back-fills the legacy `ui/resourceUri` key from this.
        _meta: {
            ui: { resourceUri: RENDER_UI_RESOURCE_URI },
            [RESOURCE_URI_META_KEY]: RENDER_UI_RESOURCE_URI,
        },
        handler: async (_context: Context, params: z.infer<RenderUiSchema>) => {
            const tool = allTools.find((t) => t.name === params.tool_name)
            const appKey = tool ? toDispatchableAppKey(tool) : undefined
            if (!tool || !appKey) {
                throw new Error(`Tool "${params.tool_name}" does not have a renderable UI app.`)
            }

            const toolInput = params.tool_input ?? {}
            const [distinctId, appData] = await Promise.all([
                context.getDistinctId(),
                loadAppData?.(tool.name, toolInput, appKey),
            ])

            const payload: ToolResultPayload = {
                content: [
                    {
                        type: 'text',
                        text: [`Rendering the ${tool.name} visualization for the user.`, tool.renderedNote]
                            .filter(Boolean)
                            .join(' '),
                    },
                ],
                structuredContent: {
                    tool_name: tool.name,
                    tool_input: toolInput,
                    app_key: appKey,
                    _analytics: {
                        distinctId,
                        toolName: RENDER_UI_TOOL_NAME,
                        ...(mcpClientName ? { mcpClientName } : {}),
                    },
                },
                _meta: {
                    ui: { resourceUri: RENDER_UI_RESOURCE_URI },
                    [RESOURCE_URI_META_KEY]: RENDER_UI_RESOURCE_URI,
                    ...(appData === undefined ? {} : { [APP_DATA_META_KEY]: appData }),
                },
            }
            return markExecPayload(payload)
        },
    }
}