: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
feat(mcp): let explain-chart evidence carry a chart of its own numbers (#124615)
Sam Penningtonadbd114ee126
diff --git a/frontend/snapshots.yml b/frontend/snapshots.ymlindex 9f6f583cf4df..274c492475e4 100644--- a/frontend/snapshots.yml+++ b/frontend/snapshots.yml@@ -6442,6 +6442,8 @@ snapshots:hash: v1.k794b7964.8d0d4e81255c25acbe114b45d698a66d4b3ff5be122c97eea1f5cc2066711a72.jx6b5OO_YEIBQZHEUccM0lJ6vaRZBUUWxs3dJgxxwKwmcp-apps-explain-chart--summary--light:hash: v1.k794b7964.8e544f3f6c9e2e43bf03efd6bf30e402e2f24a41ec060922b5e3068643ce4c86.BQcCbMIGeBusavfXWYInYZD6jMZfnN4zr-HV9oOAFHg+ mcp-apps-explain-chart-evidence-chart--line--light:+ hash: v1.k794b7964.d18367c8e6c0db146a8a61c780cca48fd38f21268db89318114be3fb65130bf8.vtgJK_jbQZbEXfmqXJhYI7BnuwvNkc68bAjvqAAlh_Emcp-apps-feature-flags--boolean-flag--light:hash: v1.k794b7964.f3ee0e724e30f350166b5a87d46cd36ba9f982735aa9d7e322aeaf28bc4c9b1c.KzlRVALZdoWS2mlKcnTJRTOo4SmFvIZzKhj6SodWt3Imcp-apps-feature-flags--flag-list--light:diff --git a/products/product_analytics/mcp/apps/explainChart/ExplainChartView.stories.tsx b/products/product_analytics/mcp/apps/explainChart/ExplainChartView.stories.tsxindex f2c3770425f1..1177d0b4935f 100644--- a/products/product_analytics/mcp/apps/explainChart/ExplainChartView.stories.tsx+++ b/products/product_analytics/mcp/apps/explainChart/ExplainChartView.stories.tsx@@ -101,9 +101,9 @@ function StoryChart({ series, overlay }: { series: Series[]; overlay?: ReactNode}const evidenceCharts: StoryEvidenceCharts = {- canShow: () => true,+ canShow: (item) => !!item.query,prefetch: () => {},- render: (_, text) => (+ render: ({ text }) => (<StoryChartseries={BY_REFERRER.map((item, index) =>isSeriesNamedIn([item.label, REFERRERS[index]!], text) ? item : { ...item, color: `${item.color}40` }diff --git a/products/product_analytics/mcp/apps/explainChart/ExplainChartView.tsx b/products/product_analytics/mcp/apps/explainChart/ExplainChartView.tsxindex 17847f70f28b..c0ec8815c985 100644--- a/products/product_analytics/mcp/apps/explainChart/ExplainChartView.tsx+++ b/products/product_analytics/mcp/apps/explainChart/ExplainChartView.tsx@@ -25,11 +25,11 @@ export interface StoryPageChange {}export interface StoryEvidenceCharts {- canShow: (query: Record<string, unknown>) => boolean- prefetch: (queries: Record<string, unknown>[]) => void+ canShow: (item: StoryEvidence) => boolean+ prefetch: (items: StoryEvidence[]) => void/** Draws the chart, fading every series that the evidence's text does not name. */- render: (query: Record<string, unknown>, text: string) => ReactNode- onShow?: (query: Record<string, unknown>) => void+ render: (item: StoryEvidence) => ReactNode+ onShow?: (item: StoryEvidence) => void}export interface ExplainChartViewProps {@@ -81,27 +81,25 @@ export function ExplainChartView({const hasNext = activeIndex + 1 < pages.lengthconst shownEvidence: StoryEvidence | null =shownEvidenceIndex === null ? null : (active.chapter?.evidence[shownEvidenceIndex] ?? null)- const evidenceView =- evidenceCharts && shownEvidence?.query ? { text: shownEvidence.text, query: shownEvidence.query } : null+ const evidenceView = shownEvidence && evidenceCharts?.canShow(shownEvidence) ? shownEvidence : nullconst prefetch = evidenceCharts?.prefetchuseEffect(() => {- const queries = active.chapter?.evidence.flatMap((item) => (item.query ? [item.query] : [])) ?? []- if (queries.length) {- prefetch?.(queries)+ if (active.chapter?.evidence.length) {+ prefetch?.(active.chapter.evidence)}}, [active, prefetch])- const canShowChart = (item: StoryEvidence): boolean => !!item.query && !!evidenceCharts?.canShow(item.query)+ const canShowChart = (item: StoryEvidence): boolean => !!evidenceCharts?.canShow(item)const toggleEvidenceChart = (index: number): void => {- const query = active.chapter?.evidence[index]?.query- if (index === shownEvidenceIndex || !query) {+ const item = active.chapter?.evidence[index]+ if (index === shownEvidenceIndex || !item) {setShownEvidenceIndex(null)return}setShownEvidenceIndex(index)- evidenceCharts?.onShow?.(query)+ evidenceCharts?.onShow?.(item)}const select = (index: number, source: StoryNavigationSource): void => {@@ -143,7 +141,7 @@ export function ExplainChartView({Back to the walkthrough</Button></div>- {evidenceCharts.render(evidenceView.query, evidenceView.text)}+ {evidenceCharts.render(evidenceView)}</>) : (<>diff --git a/products/product_analytics/mcp/apps/explainChart/StoryEvidenceChart.stories.tsx b/products/product_analytics/mcp/apps/explainChart/StoryEvidenceChart.stories.tsxnew file mode 100644index 000000000000..fd0821dccf54--- /dev/null+++ b/products/product_analytics/mcp/apps/explainChart/StoryEvidenceChart.stories.tsx@@ -0,0 +1,51 @@+import type { Meta, StoryFn, StoryObj } from '@storybook/react'+import type { ReactElement } from 'react'++import { McpThemeDecorator } from '@posthog/mcp-ui/storybook/decorator'+import { useChartTheme } from '@posthog/quill-charts'++import { StoryEvidenceChart } from './StoryEvidenceChart'++// The chart measures its box with a ResizeObserver, so give it a definite width.+const FixedWidth = (Story: StoryFn): ReactElement => (+ <div className="w-[680px]">+ <Story />+ </div>+)++const meta: Meta = {+ title: 'MCP Apps/Explain Chart/Evidence chart',+ decorators: [McpThemeDecorator, FixedWidth],+ parameters: { testOptions: { skipDarkMode: true } },+}+export default meta++type Story = StoryObj<{}>++function LineChart(): ReactElement {+ return (+ <StoryEvidenceChart+ className="h-[260px]"+ theme={useChartTheme()}+ chart={{+ type: 'line',+ labels: [+ 'Oct 26 18:00',+ 'Oct 26 19:00',+ 'Oct 26 20:00',+ 'Oct 26 21:00',+ 'Oct 26 22:00',+ 'Oct 26 23:00',+ ],+ series: [+ { name: 'EU hit rate', values: [0.91, 0.9, 0.55, 0.62, 0.7, 0.78] },+ { name: 'US hit rate', values: [0.88, 0.89, 0.52, 0.6, 0.69, 0.8] },+ ],+ }}+ />+ )+}++export const Line: Story = {+ render: () => <LineChart />,+}diff --git a/products/product_analytics/mcp/apps/explainChart/StoryEvidenceChart.tsx b/products/product_analytics/mcp/apps/explainChart/StoryEvidenceChart.tsxnew file mode 100644index 000000000000..1d3ca24121fb--- /dev/null+++ b/products/product_analytics/mcp/apps/explainChart/StoryEvidenceChart.tsx@@ -0,0 +1,37 @@+import type { ReactElement } from 'react'++import { buildYTickFormatter, type ChartTheme, TimeSeriesBarChart, TimeSeriesLineChart } from '@posthog/quill-charts'++import type { StoryEvidenceChartData } from './explainChartTypes'++const Y_AXIS = { tickFormatter: buildYTickFormatter({ format: 'short' }), showGrid: true }++export interface StoryEvidenceChartProps {+ chart: StoryEvidenceChartData+ theme: ChartTheme+ className: string+}++export function StoryEvidenceChart({ chart, theme, className }: StoryEvidenceChartProps): ReactElement {+ const series = chart.series.map((item, index) => ({ key: String(index), label: item.name, data: item.values }))+ const legend = { show: series.length > 1 }+ return (+ <div className={`flex w-full flex-col ${className}`} data-attr="explain-chart-evidence-inline-chart">+ {chart.type === 'bar' ? (+ <TimeSeriesBarChart+ series={series}+ labels={chart.labels}+ theme={theme}+ config={{ yAxis: Y_AXIS, legend, barLayout: 'grouped' }}+ />+ ) : (+ <TimeSeriesLineChart+ series={series}+ labels={chart.labels}+ theme={theme}+ config={{ yAxis: Y_AXIS, legend, showCrosshair: true }}+ />+ )}+ </div>+ )+}diff --git a/products/product_analytics/mcp/apps/explainChart/explainChartTypes.ts b/products/product_analytics/mcp/apps/explainChart/explainChartTypes.tsindex 1a17f099b9d7..88d67f3c6568 100644--- a/products/product_analytics/mcp/apps/explainChart/explainChartTypes.ts+++ b/products/product_analytics/mcp/apps/explainChart/explainChartTypes.ts@@ -1,9 +1,16 @@export type StoryConfidence = 'high' | 'medium' | 'low'+export interface StoryEvidenceChartData {+ type: 'line' | 'bar'+ labels: string[]+ series: { name: string; values: number[] }[]+}+export interface StoryEvidence {text: stringurl: string | nullquery?: Record<string, unknown> | null+ chart?: StoryEvidenceChartData | null}export interface StoryChapter {diff --git a/products/product_analytics/skills/investigate-metric/SKILL.md b/products/product_analytics/skills/investigate-metric/SKILL.mdindex 3550d0df2603..baf626c173c1 100644--- a/products/product_analytics/skills/investigate-metric/SKILL.md+++ b/products/product_analytics/skills/investigate-metric/SKILL.md@@ -97,7 +97,7 @@ When it is a walkthrough:- Add "Show the walkthrough (Step 5)" as the last item of your plan or to-do list.- Keep the `TrendsQuery` behind each finding, such as an event count with a breakdown or a property filter.The walkthrough draws a `TrendsQuery` as a chart beside the finding, and any other query only as a link.- Use SQL for the findings that a `TrendsQuery` cannot express.+ Use SQL for the findings that a `TrendsQuery` cannot express, and pass its numbers as the evidence's `chart` so they draw too.## Step 2 — Common opening moves@@ -159,6 +159,7 @@ Map the investigation onto it:- **Evidence** → `evidence`, each finding with the `query` that produced it, or a `url`for a commit or a deploy. Pass the `TrendsQuery` you ran where you have one: thewalkthrough draws it as a chart, while any other query only becomes a link.+ For a finding from SQL, also pass `chart` with the numbers from its result: `line` over time or `bar` per label, the `labels`, and one `series` per line.- A **headline** of one sentence with no numbers sums up the whole chart.Wrap each name behind a moment, such as the referrer of a spike or the country behind a rise, in `**double asterisks**` so the walkthrough highlights it.Do the same in each `cause`.diff --git a/services/mcp/schema/tool-inputs.json b/services/mcp/schema/tool-inputs.jsonindex cfc25eab86c0..f494fb55892f 100644--- a/services/mcp/schema/tool-inputs.json+++ b/services/mcp/schema/tool-inputs.json@@ -729,6 +729,50 @@},"additionalProperties": {}},+ "chart": {+ "description": "Numbers to draw beside this finding when its query is not a TrendsQuery, such as SQL. Copy them from the result you got.",+ "type": "object",+ "properties": {+ "type": {+ "type": "string",+ "enum": ["line", "bar"],+ "description": "`line` for values over time, `bar` for a value per label."+ },+ "labels": {+ "minItems": 1,+ "maxItems": 200,+ "type": "array",+ "items": {+ "type": "string"+ },+ "description": "The x-axis labels in order, such as hours or referrers, written as the person should read them."+ },+ "series": {+ "minItems": 1,+ "maxItems": 6,+ "type": "array",+ "items": {+ "type": "object",+ "properties": {+ "name": {+ "type": "string",+ "minLength": 1,+ "maxLength": 80+ },+ "values": {+ "type": "array",+ "items": {+ "type": "number"+ },+ "description": "One value per label, in the same order."+ }+ },+ "required": ["name", "values"]+ }+ }+ },+ "required": ["type", "labels", "series"]+ },"url": {"description": "A link to the source when it is not a query, for example a commit, a pull request or a deploy.","type": "string",diff --git a/services/mcp/src/schema/tool-inputs.ts b/services/mcp/src/schema/tool-inputs.tsindex 61e62c5f0e0c..ce20e8e2017c 100644--- a/services/mcp/src/schema/tool-inputs.ts+++ b/services/mcp/src/schema/tool-inputs.ts@@ -587,6 +587,33 @@ const ExplainChartEvidenceSchema = z.object({.describe('The query that found this, as you ran it (for example a TrendsQuery with a breakdown). It becomes a link to that chart, and a TrendsQuery also draws as a chart in the walkthrough.'),+ chart: z+ .object({+ type: z.enum(['line', 'bar']).describe('`line` for values over time, `bar` for a value per label.'),+ labels: z+ .array(z.string())+ .min(1)+ .max(200)+ .describe(+ 'The x-axis labels in order, such as hours or referrers, written as the person should read them.'+ ),+ series: z+ .array(+ z.object({+ name: z.string().min(1).max(80),+ values: z.array(z.number()).describe('One value per label, in the same order.'),+ })+ )+ .min(1)+ .max(6),+ })+ .refine((chart) => chart.series.every((item) => item.values.length === chart.labels.length), {+ message: 'Each series needs one value per label.',+ })+ .optional()+ .describe(+ 'Numbers to draw beside this finding when its query is not a TrendsQuery, such as SQL. Copy them from the result you got.'+ ),url: z.string().url()diff --git a/services/mcp/src/tools/insights/explainChart.ts b/services/mcp/src/tools/insights/explainChart.tsindex 25b68fa27539..949db60079f4 100644--- a/services/mcp/src/tools/insights/explainChart.ts+++ b/services/mcp/src/tools/insights/explainChart.ts@@ -176,6 +176,7 @@ export const explainChartHandler: ToolBase<typeof schema, Result>['handler'] = atext: item.text,url: item.query ? `${baseUrl}${newInsightPath(item.query)}` : (item.url ?? null),query: item.query && redrawSchema.safeParse(item.query).success ? item.query : null,+ chart: item.chart ?? null,})),}})diff --git a/services/mcp/src/ui-apps/hooks/useEvidenceCharts.tsx b/services/mcp/src/ui-apps/hooks/useEvidenceCharts.tsxindex bb453900f596..62b81f2d04a3 100644--- a/services/mcp/src/ui-apps/hooks/useEvidenceCharts.tsx+++ b/services/mcp/src/ui-apps/hooks/useEvidenceCharts.tsx@@ -3,12 +3,15 @@ import { useCallback, useMemo, useRef, useState } from 'react'import { Button, Text } from '@posthog/quill'+import type { StoryEvidence } from 'products/product_analytics/mcp/apps/explainChart/explainChartTypes'import type { StoryEvidenceCharts } from 'products/product_analytics/mcp/apps/explainChart/ExplainChartView'+import { StoryEvidenceChart } from 'products/product_analytics/mcp/apps/explainChart/StoryEvidenceChart'import { isSeriesNamedIn } from 'products/product_analytics/mcp/apps/explainChart/storyNamedSeries'import { capture } from '../analytics/posthog'import { loadRenderUiData } from '../apps/render-ui-data'import { AppLoadingState } from '../components/AppLoadingState'+import { useMcpChartTheme } from '../components/charts/theme'import { TrendsVisualizer } from '../components/TrendsVisualizer'import type { TrendsQuery, TrendsResult, TrendsResultItem } from '../components/types'import { getSeriesLabel } from '../components/utils'@@ -26,7 +29,12 @@ function isTrendsQuery(query: Record<string, unknown>): boolean {return query.kind === 'TrendsQuery' || (query.kind === undefined && Array.isArray(query.series))}+function trendsQueryOf(item: StoryEvidence): Record<string, unknown> | null {+ return item.query && isTrendsQuery(item.query) ? item.query : null+}+export function useEvidenceCharts(app: App | null, chartClassName: string): StoryEvidenceCharts | undefined {+ const theme = useMcpChartTheme()const [charts, setCharts] = useState<Record<string, EvidenceChart>>({})const requested = useRef(new Set<string>())@@ -67,7 +75,13 @@ export function useEvidenceCharts(app: App | null, chartClassName: string): Stor)const prefetch = useCallback(- (queries: Record<string, unknown>[]): void => queries.filter(isTrendsQuery).forEach(load),+ (items: StoryEvidence[]): void =>+ items.forEach((item) => {+ const query = trendsQueryOf(item)+ if (query && !item.chart) {+ load(query)+ }+ }),[load])@@ -76,15 +90,33 @@ export function useEvidenceCharts(app: App | null, chartClassName: string): Storreturn undefined}return {- canShow: isTrendsQuery,+ canShow: (item) => !!item.chart || !!trendsQueryOf(item),prefetch,- onShow: (query) => {+ onShow: (item) => {+ const query = item.chart ? null : trendsQueryOf(item)capture('mcp_ui_app_explain_chart_evidence_chart_shown', {- was_loaded: charts[JSON.stringify(query)]?.status === 'ready',+ was_loaded: !query || charts[JSON.stringify(query)]?.status === 'ready',+ inline: !!item.chart,})- load(query)+ if (query) {+ load(query)+ }},- render: (query, text) => {+ render: (item) => {+ if (item.chart) {+ return (+ <StoryEvidenceChart+ key={JSON.stringify(item.chart)}+ chart={item.chart}+ theme={theme}+ className={chartClassName}+ />+ )+ }+ const query = trendsQueryOf(item)+ if (!query) {+ return null+ }const chart = charts[JSON.stringify(query)]if (chart?.status === 'ready') {return (@@ -92,8 +124,8 @@ export function useEvidenceCharts(app: App | null, chartClassName: string): Storkey={JSON.stringify(query)}query={chart.query}results={chart.results}- highlightedSeries={chart.results.flatMap((item, index) =>- isSeriesNamedIn(seriesNames(item, index), text) ? [index] : []+ highlightedSeries={chart.results.flatMap((result, index) =>+ isSeriesNamedIn(seriesNames(result, index), item.text) ? [index] : [])}showControls={false}showTitle={false}@@ -125,5 +157,5 @@ export function useEvidenceCharts(app: App | null, chartClassName: string): Stor)},}- }, [app, chartClassName, charts, load, prefetch])+ }, [app, chartClassName, charts, load, prefetch, theme])}diff --git a/services/mcp/tests/unit/explain-chart.test.ts b/services/mcp/tests/unit/explain-chart.test.tsindex e6062c0f29c6..5e2a47d0f812 100644--- a/services/mcp/tests/unit/explain-chart.test.ts+++ b/services/mcp/tests/unit/explain-chart.test.ts@@ -1,5 +1,6 @@import { describe, expect, it, vi } from 'vitest'+import { ExplainChartInputSchema } from '@/schema/tool-inputs'import { explainChartHandler } from '@/tools/insights/explainChart'import { findStoryRange, lastBucketInProgress } from '@/tools/insights/storyRanges'import { type Context, POSTHOG_FORMATTED_RESULTS_OVERRIDE_KEY } from '@/tools/types'@@ -131,6 +132,12 @@ describe('explain-chart', () => {})})+ const hitRate = {+ type: 'line' as const,+ labels: ['20:00', '21:00'],+ series: [{ name: 'hit rate', values: [0.9, 0.55] }],+ }+it('keeps a chart only for evidence that query-trends can draw again', async () => {const series = [{ kind: 'EventsNode', event: 'signed_up' }]const drawable = {@@ -156,17 +163,41 @@ describe('explain-chart', () => {evidence: [{ text: 'Chrome sent most of it.', query: drawable },{ text: 'Safari stayed flat.', query: linkOnly },+ {+ text: 'The hit rate fell.',+ query: { kind: 'HogQLQuery', query: 'SELECT 1' },+ chart: hitRate,+ },],},],})- expect(result.chapters[0]!.evidence.map((item) => [item.query !== null, item.url !== null])).toEqual([- [true, true],- [false, true],+ expect(+ result.chapters[0]!.evidence.map((item) => [item.query !== null, item.chart ?? null, item.url !== null])+ ).toEqual([+ [true, null, true],+ [false, null, true],+ [false, hitRate, true],])})+ it('refuses a chart whose series do not have one value per label', () => {+ const parsed = ExplainChartInputSchema.safeParse({+ insightId: 'abc12345',+ headline: 'One day stands out.',+ chapters: [+ {+ title: 'A spike on October 2',+ start: '2026-10-02',+ evidence: [{ text: 'The hit rate fell.', chart: { ...hitRate, labels: ['20:00'] } }],+ },+ ],+ })++ expect(parsed.success).toBe(false)+ })+it.each([['a day that is still running', ['2026-10-17', '2026-10-18'], 'day', 'UTC', '2026-10-18T10:00:00Z', true],['a day that has ended', ['2026-10-16', '2026-10-17'], 'day', 'UTC', '2026-10-18T10:00:00Z', false],