: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
#!/usr/bin/env tsx
/**
* Generates UI app entry points and resource registry from YAML definitions.
*
* Reads ui_apps sections from definitions/*.yaml and products/X/mcp/tools.yaml.
*
* Produces:
* - src/ui-apps/apps/generated/app-name.tsx — entry point per detail/list app
* - src/resources/ui-apps.generated.ts — URI constants, UiAppKey type, withUiApp, UI_APPS
*
* Custom apps (type: custom) get registry entries but no generated entry point.
*
* Convention-based defaults: most fields are derived from the app key + product dir.
* See resolveDetailApp() and resolveListApp() for the full derivation logic.
*/
import { spawnSync } from 'node:child_process'
import * as fs from 'node:fs'
import * as path from 'node:path'
import { fileURLToPath } from 'node:url'
import { parse as parseYaml } from 'yaml'
import { discoverDefinitions, isToolsConfig } from './lib/definitions.mjs'
import { type ToolInputSchema, validateListAppToolCall } from './lib/validate-ui-app-tool-call'
import { MCP_ROOT_DIR, ROOT_DIR } from './utils'
import {
type CategoryConfig,
CategoryConfigSchema,
type ResolvedCustomUiApp,
type ResolvedDetailUiApp,
type ResolvedListUiApp,
type UiAppConfig,
} from './yaml-config-schema'
const DEFINITIONS_DIR = path.resolve(MCP_ROOT_DIR, 'definitions')
const PRODUCTS_DIR = path.resolve(ROOT_DIR, 'products')
const GENERATED_APPS_DIR = path.resolve(MCP_ROOT_DIR, 'src/ui-apps/apps/generated')
const GENERATED_REGISTRY_PATH = path.resolve(MCP_ROOT_DIR, 'src/resources/ui-apps.generated.ts')
// The render-ui umbrella app dispatches a tool result to its matching view. This
// module imports React view components, so it must live OUTSIDE src/ui-apps/apps/
// (where `discoverApps` would otherwise build it as a standalone app bundle).
const GENERATED_DISPATCH_DIR = path.resolve(MCP_ROOT_DIR, 'src/ui-apps/generated')
const GENERATED_DISPATCH_PATH = path.resolve(GENERATED_DISPATCH_DIR, 'render-dispatch.generated.tsx')
const AUTO_GENERATED_HEADER = '// AUTO-GENERATED by generate-ui-apps.ts — do not edit\n'
// ------------------------------------------------------------------
// Convention-based default resolution
// ------------------------------------------------------------------
function kebabToPascal(s: string): string {
return s
.split('-')
.map((part) => part.charAt(0).toUpperCase() + part.slice(1))
.join('')
}
function kebabToTitle(s: string): string {
return s
.split('-')
.map((part) => part.charAt(0).toUpperCase() + part.slice(1))
.join(' ')
}
/**
* Derive the component import path from the YAML file location.
* For products/actions/mcp/tools.yaml -> products/actions/mcp/apps
* For services/mcp/definitions/core.yaml -> null (no product dir)
*/
function deriveComponentImport(yamlFilePath: string): string | null {
const mcpDir = path.dirname(yamlFilePath)
if (mcpDir.includes('/products/')) {
return path.relative(ROOT_DIR, path.join(mcpDir, 'apps'))
}
return null
}
function resolveDetailApp(
appKey: string,
raw: Extract<UiAppConfig, { type: 'detail' }>,
componentImport: string
): ResolvedDetailUiApp {
const pascal = kebabToPascal(appKey)
return {
type: 'detail',
view_prop: raw.view_prop,
app_name: raw.app_name ?? `PostHog ${kebabToTitle(appKey)}`,
description: raw.description ?? `${kebabToTitle(appKey)} detail view`,
component_import: raw.component_import ?? componentImport,
data_type: raw.data_type ?? `${pascal}Data`,
view_component: raw.view_component ?? `${pascal}View`,
...(raw.link_prop ? { link_prop: raw.link_prop } : {}),
}
}
function resolveListApp(
appKey: string,
raw: Extract<UiAppConfig, { type: 'list' }>,
componentImport: string
): ResolvedListUiApp {
// Strip -list suffix to get the singular entity key
const singularKey = appKey.replace(/-list$/, '')
const singularPascal = kebabToPascal(singularKey)
const pascal = kebabToPascal(appKey)
return {
type: 'list',
detail_tool: raw.detail_tool,
detail_args: raw.detail_args ?? '{ id: item.id }',
item_name_field: raw.item_name_field ?? 'name',
click_prop: raw.click_prop ?? `on${singularPascal}Click`,
entity_label: raw.entity_label ?? singularKey.replace(/-/g, ' '),
app_name: raw.app_name ?? `PostHog ${kebabToTitle(appKey)}`,
description: raw.description ?? `${kebabToTitle(appKey)} view`,
component_import: raw.component_import ?? componentImport,
list_data_type: raw.list_data_type ?? `${singularPascal}ListData`,
item_data_type: raw.item_data_type ?? `${singularPascal}Data`,
view_component: raw.view_component ?? `${pascal}View`,
}
}
function resolveCustomApp(raw: Extract<UiAppConfig, { type: 'custom' }>): ResolvedCustomUiApp {
return {
type: 'custom',
app_name: raw.app_name,
description: raw.description,
...(raw.resource_domains ? { resource_domains: raw.resource_domains } : {}),
...(raw.render_ui ? { render_ui: raw.render_ui } : {}),
}
}
// ------------------------------------------------------------------
// Entry point generators
// ------------------------------------------------------------------
function generateDetailApp(appKey: string, config: ResolvedDetailUiApp): string {
const pascalName = kebabToPascal(appKey)
const renderProp = config.link_prop
? `({ data, openLink }) => <${config.view_component} ${config.view_prop}={data!} ${config.link_prop}={openLink} />`
: `({ data }) => <${config.view_component} ${config.view_prop}={data!} />`
return `${AUTO_GENERATED_HEADER}import '../../styles/tailwind.css'
import { createRoot } from 'react-dom/client'
import { type ${config.data_type}, ${config.view_component} } from '${config.component_import}'
import { AppWrapper } from '../../components/AppWrapper'
function ${pascalName}App(): JSX.Element {
return (
<AppWrapper<${config.data_type}> appName="${config.app_name}">
{${renderProp}}
</AppWrapper>
)
}
const container = document.getElementById('root')
if (container) {
createRoot(container).render(<${pascalName}App />)
}
`
}
/**
* The list-to-detail `Content` component for a list app — owns the click handler
* that fetches a single item via `callServerTool` and the chat fallback. Shared by
* the standalone list entry point and the render-ui dispatch module so the
* drill-down behavior can't drift between them.
*/
function buildListContentComponent(appKey: string, config: ResolvedListUiApp): string {
const pascalName = kebabToPascal(appKey)
return `function ${pascalName}Content({ data, app }: { data: ${config.list_data_type}; app: App | null }): JSX.Element {
const fallbackToChat = useCallback(
(name: string) => {
app?.sendMessage({
role: 'user',
content: [{ type: 'text', text: \`Show me the details for ${config.entity_label} "\${name}"\` }],
})
},
[app]
)
const handleClick = useCallback(
async (item: ${config.item_data_type}): Promise<${config.item_data_type} | null> => {
if (!app) {
fallbackToChat(item.${config.item_name_field})
return null
}
try {
const result = await app.callServerTool({
name: '${config.detail_tool}',
arguments: ${config.detail_args},
})
if (result.isError || !result.structuredContent) {
fallbackToChat(item.${config.item_name_field})
return null
}
return result.structuredContent as unknown as ${config.item_data_type}
} catch {
fallbackToChat(item.${config.item_name_field})
return null
}
},
[app, fallbackToChat]
)
return <${config.view_component} data={data} ${config.click_prop}={handleClick} />
}`
}
function generateListApp(appKey: string, config: ResolvedListUiApp): string {
const pascalName = kebabToPascal(appKey)
return `${AUTO_GENERATED_HEADER}import '../../styles/tailwind.css'
import type { App } from '@modelcontextprotocol/ext-apps'
import { useCallback } from 'react'
import { createRoot } from 'react-dom/client'
import { type ${config.item_data_type}, type ${config.list_data_type}, ${config.view_component} } from '${config.component_import}'
import { AppWrapper } from '../../components/AppWrapper'
function ${pascalName}App(): JSX.Element {
return (
<AppWrapper<${config.list_data_type}> appName="${config.app_name}">
{({ data, app }) => <${pascalName}Content data={data!} app={app} />}
</AppWrapper>
)
}
${buildListContentComponent(appKey, config)}
const container = document.getElementById('root')
if (container) {
createRoot(container).render(<${pascalName}App />)
}
`
}
// ------------------------------------------------------------------
// Render-ui dispatch module generator
// ------------------------------------------------------------------
type DispatchApp =
| { appKey: string; type: 'detail'; config: ResolvedDetailUiApp }
| { appKey: string; type: 'list'; config: ResolvedListUiApp }
| {
appKey: string
type: 'custom'
config: ResolvedCustomUiApp & { render_ui: NonNullable<ResolvedCustomUiApp['render_ui']> }
}
/**
* Generates the dispatch module consumed by the `render-ui` umbrella app. It maps
* each app key with a reusable view to a render function so `render-ui` can fetch
* a tool result and mount the matching view. Custom apps opt in by declaring
* `render_ui` because their entry points have no convention view component.
*/
function generateDispatchModule(apps: DispatchApp[]): string {
// Merge named imports per component_import path (multiple apps from the same
// product share one import line, e.g. survey + survey-list + survey-stats).
const importsByPath = new Map<string, Set<string>>()
const addImport = (importPath: string, spec: string): void => {
const specs = importsByPath.get(importPath) ?? new Set<string>()
specs.add(spec)
importsByPath.set(importPath, specs)
}
for (const app of apps) {
if (app.type === 'detail') {
addImport(app.config.component_import, `type ${app.config.data_type}`)
addImport(app.config.component_import, app.config.view_component)
} else if (app.type === 'list') {
addImport(app.config.component_import, `type ${app.config.item_data_type}`)
addImport(app.config.component_import, `type ${app.config.list_data_type}`)
addImport(app.config.component_import, app.config.view_component)
} else {
const { component_import, data_type, view_component } = app.config.render_ui
if (data_type) {
addImport(component_import, `type ${data_type}`)
}
addImport(component_import, view_component)
}
}
const componentImports = [...importsByPath.entries()]
.sort(([a], [b]) => a.localeCompare(b))
.map(([importPath, specs]) => `import { ${[...specs].sort().join(', ')} } from '${importPath}'`)
.join('\n')
const hasListApp = apps.some((app) => app.type === 'list')
const listContents = apps
.filter((app): app is Extract<DispatchApp, { type: 'list' }> => app.type === 'list')
.map((app) => buildListContentComponent(app.appKey, app.config))
.join('\n\n')
const entries = apps
.map((app) => {
if (app.type === 'detail') {
const { view_component, view_prop, data_type, link_prop } = app.config
if (link_prop) {
return ` '${app.appKey}': ({ data, openLink }) => <${view_component} ${view_prop}={data as ${data_type}} ${link_prop}={openLink} />,`
}
return ` '${app.appKey}': ({ data }) => <${view_component} ${view_prop}={data as ${data_type}} />,`
}
if (app.type === 'custom') {
const { data_type, view_component, view_prop, link_prop, app_prop } = app.config.render_ui
const dataExpression = data_type ? `data as ${data_type}` : 'data'
const args = ['data', ...(link_prop ? ['openLink'] : []), ...(app_prop ? ['app'] : [])].join(', ')
const extraProps = `${link_prop ? ` ${link_prop}={openLink}` : ''}${app_prop ? ` ${app_prop}={app}` : ''}`
return ` '${app.appKey}': ({ ${args} }) => <${view_component} ${view_prop}={${dataExpression}}${extraProps} />,`
}
const pascalName = kebabToPascal(app.appKey)
return ` '${app.appKey}': ({ data, app }) => <${pascalName}Content data={data as ${app.config.list_data_type}} app={app} />,`
})
.join('\n')
const reactImport = hasListApp ? "import { useCallback } from 'react'\n\n" : ''
const listBlock = listContents ? `${listContents}\n\n` : ''
return `${AUTO_GENERATED_HEADER}import type { App } from '@modelcontextprotocol/ext-apps'
${reactImport}${componentImports}
import type { UiAppKey } from '../../resources/ui-apps.generated'
export interface RenderDispatchProps {
data: unknown
app: App | null
openLink: (url: string) => void
}
${listBlock}export const RENDER_DISPATCH: Partial<Record<UiAppKey, (props: RenderDispatchProps) => JSX.Element>> = {
${entries}
}
`
}
// ------------------------------------------------------------------
// Registry generator
// ------------------------------------------------------------------
interface RegistryEntry {
appKey: string
appDir: string
constName: string
uri: string
name: string
description: string
resourceDomains?: string[]
}
function toConstName(appKey: string): string {
return appKey.toUpperCase().replace(/-/g, '_') + '_RESOURCE_URI'
}
function toUri(appKey: string): string {
return `ui://posthog/${appKey}.html`
}
function generateRegistry(entries: RegistryEntry[], dispatchableKeys: string[]): string {
const constants = entries.map((e) => `export const ${e.constName} = '${e.uri}'`).join('\n')
const keyUnion = entries.map((e) => `'${e.appKey}'`).join(' | ')
const uriMapEntries = entries.map((e) => ` '${e.appKey}': ${e.constName}`).join(',\n')
const appEntries = entries
.map(
(e) =>
` {\n name: '${e.name}',\n uri: ${e.constName},\n description: '${e.description}',\n appDir: '${e.appDir}',${e.resourceDomains ? `\n resourceDomains: ${JSON.stringify(e.resourceDomains)},` : ''}\n }`
)
.join(',\n')
const dispatchableEntries = [...dispatchableKeys]
.sort()
.map((key) => ` '${key}'`)
.join(',\n')
return `${AUTO_GENERATED_HEADER}
${constants}
export type UiAppKey = ${keyUnion}
export const URI_MAP: Record<UiAppKey, string> = {
${uriMapEntries},
}
/**
* App keys with a reusable view that the \`render-ui\` umbrella tool can render.
* Custom apps are included only when they explicitly configure \`render_ui\`.
*/
export const DISPATCHABLE_APP_KEYS: UiAppKey[] = [
${dispatchableEntries},
]
export const UI_APPS: Array<{
name: string
uri: string
description: string
appDir: string
resourceDomains?: string[]
}> = [
${appEntries},
]
`
}
// ------------------------------------------------------------------
// Main
// ------------------------------------------------------------------
const TOOL_SCHEMA_SNAPSHOTS_DIR = path.join(MCP_ROOT_DIR, 'tests', 'unit', '__snapshots__', 'tool-schemas')
// The snapshot test writes one JSON schema per registered tool, so the generator
// can read tool inputs without loading the server bundle.
function readToolInputSchema(toolName: string): ToolInputSchema | undefined {
const snapshotPath = path.join(TOOL_SCHEMA_SNAPSHOTS_DIR, `${toolName}.json`)
if (!fs.existsSync(snapshotPath)) {
return undefined
}
return JSON.parse(fs.readFileSync(snapshotPath, 'utf-8'))
}
function main(): void {
const definitionSources = discoverDefinitions({ definitionsDir: DEFINITIONS_DIR, productsDir: PRODUCTS_DIR })
fs.mkdirSync(GENERATED_APPS_DIR, { recursive: true })
const registryEntries: RegistryEntry[] = []
const dispatchApps: DispatchApp[] = []
const generatedFiles: string[] = []
// Collect all ui_app keys for cross-referencing with tool ui_app fields
const allUiAppKeys = new Set<string>()
for (const def of definitionSources) {
const content = fs.readFileSync(def.filePath, 'utf-8')
const parsed = parseYaml(content)
// Only continue if we detect this is a tool config file
if (!isToolsConfig(parsed)) {
continue
}
const result = CategoryConfigSchema.safeParse(parsed)
if (!result.success) {
console.error(`Invalid YAML config in ${def.filePath}:`)
for (const issue of result.error.issues) {
console.error(` ${issue.path.join('.')}: ${issue.message}`)
}
process.exit(1)
}
const config: CategoryConfig = result.data
if (!config.ui_apps) {
continue
}
const componentImport = deriveComponentImport(def.filePath)
for (const [appKey, appConfig] of Object.entries(config.ui_apps)) {
allUiAppKeys.add(appKey)
const constName = toConstName(appKey)
const uri = toUri(appKey)
if (appConfig.type === 'detail') {
if (!componentImport && !appConfig.component_import) {
console.error(
`detail app "${appKey}" in ${def.filePath}: cannot derive component_import (not in a product dir). Set component_import explicitly.`
)
process.exit(1)
}
const resolved = resolveDetailApp(appKey, appConfig, componentImport!)
const code = generateDetailApp(appKey, resolved)
const outPath = path.join(GENERATED_APPS_DIR, `${appKey}.tsx`)
fs.writeFileSync(outPath, code)
generatedFiles.push(outPath)
dispatchApps.push({ appKey, type: 'detail', config: resolved })
registryEntries.push({
appKey,
appDir: `generated/${appKey}`,
constName,
uri,
name: resolved.app_name,
description: resolved.description,
})
} else if (appConfig.type === 'list') {
if (!componentImport && !appConfig.component_import) {
console.error(
`list app "${appKey}" in ${def.filePath}: cannot derive component_import (not in a product dir). Set component_import explicitly.`
)
process.exit(1)
}
const resolved = resolveListApp(appKey, appConfig, componentImport!)
validateListAppToolCall(appKey, resolved, readToolInputSchema(resolved.detail_tool))
const code = generateListApp(appKey, resolved)
const outPath = path.join(GENERATED_APPS_DIR, `${appKey}.tsx`)
fs.writeFileSync(outPath, code)
generatedFiles.push(outPath)
dispatchApps.push({ appKey, type: 'list', config: resolved })
registryEntries.push({
appKey,
appDir: `generated/${appKey}`,
constName,
uri,
name: resolved.app_name,
description: resolved.description,
})
} else {
// type: custom — entry point is handwritten, appDir matches appKey directly
const resolved = resolveCustomApp(appConfig)
if (resolved.render_ui) {
dispatchApps.push({
appKey,
type: 'custom',
config: { ...resolved, render_ui: resolved.render_ui },
})
}
registryEntries.push({
appKey,
appDir: appKey,
constName,
uri,
name: appConfig.app_name,
description: appConfig.description,
resourceDomains: resolved.resource_domains,
})
}
}
}
// Validate ui_app references in tools
for (const def of definitionSources) {
const content = fs.readFileSync(def.filePath, 'utf-8')
const parsed = parseYaml(content)
// Only continue if we detect this is a tool config file
if (!isToolsConfig(parsed)) {
continue
}
const config = CategoryConfigSchema.parse(parsed)
for (const [toolName, toolConfig] of Object.entries(config.tools)) {
if (toolConfig.ui_app && !allUiAppKeys.has(toolConfig.ui_app)) {
console.error(
`Tool "${toolName}" references ui_app "${toolConfig.ui_app}" which is not defined in any ui_apps section.`
)
process.exit(1)
}
}
}
// Sort entries alphabetically for stable output
registryEntries.sort((a, b) => a.appKey.localeCompare(b.appKey))
dispatchApps.sort((a, b) => a.appKey.localeCompare(b.appKey))
// Write registry (with the render-ui dispatchable key list)
const registryCode = generateRegistry(
registryEntries,
dispatchApps.map((a) => a.appKey)
)
fs.writeFileSync(GENERATED_REGISTRY_PATH, registryCode)
generatedFiles.push(GENERATED_REGISTRY_PATH)
// Write the render-ui dispatch module
fs.mkdirSync(GENERATED_DISPATCH_DIR, { recursive: true })
fs.writeFileSync(GENERATED_DISPATCH_PATH, generateDispatchModule(dispatchApps))
generatedFiles.push(GENERATED_DISPATCH_PATH)
process.stdout.write(
`Generated ${generatedFiles.length - 2} UI app entry point(s) + registry + dispatch (${registryEntries.length} app(s))\n`
)
formatOutput(generatedFiles)
}
function formatOutput(generatedFiles: string[]): void {
// Run oxlint + oxfmt directly instead of going through `bin/hogli format:js`,
// which requires `uv` (Python) and fails in environments like Cloudflare Pages
// where the uv version doesn't match pyproject.toml's required-version.
const oxlintResult = spawnSync('pnpm', ['oxlint', '--fix', '--fix-suggestions', '--quiet', ...generatedFiles], {
stdio: 'inherit',
cwd: ROOT_DIR,
})
if (oxlintResult.status && oxlintResult.status !== 0) {
process.exit(oxlintResult.status)
}
const oxfmtResult = spawnSync('pnpm', ['exec', 'oxfmt', '--no-error-on-unmatched-pattern', ...generatedFiles], {
stdio: 'inherit',
cwd: ROOT_DIR,
})
if (oxfmtResult.status && oxfmtResult.status !== 0) {
process.exit(oxfmtResult.status)
}
}
// Export for testing
export {
type DispatchApp,
buildListContentComponent,
generateDetailApp,
generateDispatchModule,
generateListApp,
generateRegistry,
kebabToPascal,
resolveCustomApp,
resolveDetailApp,
resolveListApp,
toConstName,
toUri,
}
// Run main when executed directly
function stripExt(filePath: string): string {
return filePath.replace(/\.[jt]s$/, '')
}
const isDirectRun =
typeof process !== 'undefined' &&
process.argv[1] &&
stripExt(path.resolve(process.argv[1])) === stripExt(fileURLToPath(import.meta.url))
if (isDirectRun) {
main()
}