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.

feat(mcp): hint typed query runners after simple sql aggregates (#126255)

Daniel Parkerbc767d914f72
diff --git a/services/mcp/src/hono/guidance/engine.ts b/services/mcp/src/hono/guidance/engine.ts
index d2890413fe25..80c7339592a8 100644
--- a/services/mcp/src/hono/guidance/engine.ts
+++ b/services/mcp/src/hono/guidance/engine.ts
@@ -44,6 +44,10 @@ function readArgPath(args: Record<string, unknown> | undefined, path: string): u
}, args)
}
+function isSet(value: unknown): boolean {
+ return value !== undefined && value !== null && value !== ''
+}
+
export function triggerMatches(rule: GuidanceRule, call: GuidanceCall): boolean {
const { trigger } = rule
if (trigger.tool !== undefined && !matchesToolPattern(trigger.tool, call.toolName)) {
@@ -58,9 +62,15 @@ export function triggerMatches(rule: GuidanceRule, call: GuidanceCall): boolean
if (trigger.outcome === 'error' && !call.isError) {
return false
}
+ if (trigger.excludeArgs?.some((path) => isSet(readArgPath(call.args, path)))) {
+ return false
+ }
if (trigger.argPattern !== undefined) {
const value = trigger.argPath === undefined ? call.args : readArgPath(call.args, trigger.argPath)
const text = typeof value === 'string' ? value : value === undefined ? '' : JSON.stringify(value)
+ if (trigger.argMaxLength !== undefined && text.length > trigger.argMaxLength) {
+ return false
+ }
return trigger.argPattern.test(text)
}
return true
diff --git a/services/mcp/src/hono/guidance/rules.ts b/services/mcp/src/hono/guidance/rules.ts
index df5e883d415c..0f36c5e4dd6e 100644
--- a/services/mcp/src/hono/guidance/rules.ts
+++ b/services/mcp/src/hono/guidance/rules.ts
@@ -16,6 +16,10 @@ const guidanceRuleSchema = z.object({
/** Dot path into the call arguments whose string value `argPattern` must match. */
argPath: z.string().min(1).optional(),
argPattern: z.instanceof(RegExp).optional(),
+ /** A longer `argPath` value never matches, so `argPattern` only runs on bounded input. */
+ argMaxLength: z.number().int().min(1).optional(),
+ /** Call arguments that rule the call out when they are set, such as a target outside the project. */
+ excludeArgs: z.array(z.string().min(1)).optional(),
outcome: z.enum(['any', 'success', 'error']),
presets: z.array(z.enum(scopePresets)).min(1),
}),
@@ -35,6 +39,35 @@ export type GuidanceRule = z.infer<typeof guidanceRuleSchema>
export const MCP_GUIDANCE_REPLAY_VISION_FLAG = 'mcp-guidance-replay-vision'
export const MCP_GUIDANCE_SQL_SCHEMA_FLAG = 'mcp-guidance-sql-schema'
+export const MCP_GUIDANCE_SQL_TYPED_RUNNER_FLAG = 'mcp-guidance-sql-typed-runner'
+
+const TYPED_RUNNER_TOOLS = [
+ 'query-trends',
+ 'query-funnel',
+ 'query-retention',
+ 'query-stickiness',
+ 'query-paths',
+ 'query-lifecycle',
+]
+
+// A query with any of these constructs needs SQL, so the typed-runner hint stays silent. A first or
+// last timestamp grouped by event is an event inventory, which `read-data-schema` answers. The scans
+// after `max(timestamp` and `GROUP BY` are bounded, because an unbounded scan takes quadratic time.
+const SQL_ONLY_CONSTRUCTS = [
+ String.raw`\b(JOIN|WITH|OVER|UNION|HAVING)\b`,
+ String.raw`\bFROM\s+events\b(?:\s+(?:AS\s+)?\w+)?\s*,`,
+ String.raw`\bsystem\.`,
+ String.raw`\(\s*SELECT\b`,
+ String.raw`\barray\w*\s*\(`,
+ String.raw`\b(groupArray|groupUniqArray|argMax|argMin|dateDiff|date_diff)\w*\s*\(`,
+ String.raw`\b(max|min)(If)?\s*\(\s*(\w+\.)?timestamp\b(?![\s\S]{0,1000}\bGROUP\s+BY\s+event\b)`,
+ String.raw`\bGROUP\s+BY\b(?:(?!\b(ORDER|LIMIT)\b)[\s\S]){0,300}?\b(person_id|distinct_id|session_id)\b`,
+ String.raw`(\bSELECT\b|,)\s*(DISTINCT\s+)?(\w+\.)*\$?(person_id|distinct_id|session_id)\b\s*(AS\s+\w+\s*)?(,|\bFROM\b)`,
+]
+const SIMPLE_EVENTS_AGGREGATE = new RegExp(
+ String.raw`^(?![\s\S]*(${SQL_ONLY_CONSTRUCTS.join('|')}))(?=[\s\S]*\bFROM\s+events\b)(?=[\s\S]*\b(count|uniq)\w*\s*\()`,
+ 'i'
+)
const RULES: GuidanceRule[] = [
{
@@ -87,6 +120,33 @@ const RULES: GuidanceRule[] = [
'event and property names. Then rewrite the query against that schema.',
].join(' '),
},
+ {
+ id: 'sql-aggregate-to-typed-runner',
+ flag: MCP_GUIDANCE_SQL_TYPED_RUNNER_FLAG,
+ trigger: {
+ tool: 'execute-sql',
+ argPath: 'query',
+ argPattern: SIMPLE_EVENTS_AGGREGATE,
+ argMaxLength: 4000,
+ // A direct warehouse connection has its own `events` table, which typed runners cannot query.
+ excludeArgs: ['connectionId'],
+ outcome: 'success',
+ presets: ['user'],
+ },
+ threshold: 1,
+ maxPerSession: 1,
+ suppressIfCalled: TYPED_RUNNER_TOOLS,
+ requiresTool: ['query-trends', 'query-funnel', 'read-data-schema'],
+ text: [
+ 'This SQL is a simple aggregate over events.',
+ 'Before you report these numbers, run the same calculation with `query-trends`,',
+ 'or with `query-funnel` for conversion between steps, and report that result.',
+ "The typed runner applies the project's default test account filter, which raw SQL does not apply,",
+ 'so the numbers can differ.',
+ 'Keep this SQL only when the user asked for SQL or the runners cannot express the calculation.',
+ 'To only check that an event or property exists, use `read-data-schema`.',
+ ].join(' '),
+ },
]
export const GUIDANCE_RULES: readonly GuidanceRule[] = z.array(guidanceRuleSchema).parse(RULES)
diff --git a/services/mcp/tests/hono/guidance-engine.test.ts b/services/mcp/tests/hono/guidance-engine.test.ts
index 5880d49ddd4c..06c56ab9aaa0 100644
--- a/services/mcp/tests/hono/guidance-engine.test.ts
+++ b/services/mcp/tests/hono/guidance-engine.test.ts
@@ -231,23 +231,74 @@ describe('GuidanceEngine', () => {
})
it.each([
- ['session_replay_events', true],
- ['raw_session_replay_events', true],
- ['session_replay_features', true],
- ['console_logs_log_entries', true],
- ['system.session_recordings', true],
- ['log_entries', false],
- ['batch_export_log_entries', false],
- ['sessions', false],
- ['events', false],
- ])('the replay rule matches SQL over %s: %s', (table, expected) => {
- const replayRule = GUIDANCE_RULES.find((r) => r.id === 'replay-sql-to-vision')!
- const call: GuidanceCall = {
- toolName: 'execute-sql',
- args: { query: `select 1 from ${table}` },
- isError: false,
- }
- expect(triggerMatches(replayRule, call)).toBe(expected)
+ ['replay-sql-to-vision', 'select 1 from session_replay_events', true],
+ ['replay-sql-to-vision', 'select 1 from raw_session_replay_events', true],
+ ['replay-sql-to-vision', 'select 1 from session_replay_features', true],
+ ['replay-sql-to-vision', 'select 1 from console_logs_log_entries', true],
+ ['replay-sql-to-vision', 'select 1 from system.session_recordings', true],
+ ['replay-sql-to-vision', 'select 1 from log_entries', false],
+ ['replay-sql-to-vision', 'select 1 from batch_export_log_entries', false],
+ ['replay-sql-to-vision', 'select 1 from sessions', false],
+ ['replay-sql-to-vision', 'select 1 from events', false],
+ [
+ 'sql-aggregate-to-typed-runner',
+ "SELECT toDate(timestamp) AS day, count() FROM events WHERE event = 'signup' GROUP BY day",
+ true,
+ ],
+ ['sql-aggregate-to-typed-runner', 'select properties.$browser, uniq(person_id)\nfrom events\ngroup by 1', true],
+ ['sql-aggregate-to-typed-runner', "SELECT countIf(event = 'a') FROM events", true],
+ ['sql-aggregate-to-typed-runner', 'SELECT event, timestamp FROM events LIMIT 10', false],
+ ['sql-aggregate-to-typed-runner', 'SELECT count() FROM events e JOIN persons p ON e.person_id = p.id', false],
+ ['sql-aggregate-to-typed-runner', 'WITH x AS (SELECT 1) SELECT count() FROM events', false],
+ ['sql-aggregate-to-typed-runner', 'SELECT count() OVER (PARTITION BY event) FROM events', false],
+ ['sql-aggregate-to-typed-runner', 'SELECT count() FROM (SELECT person_id FROM events)', false],
+ [
+ 'sql-aggregate-to-typed-runner',
+ 'SELECT count() FROM events WHERE person_id IN (SELECT id FROM persons)',
+ false,
+ ],
+ [
+ 'sql-aggregate-to-typed-runner',
+ 'SELECT event, count(), max(timestamp) AS last_seen FROM events GROUP BY event',
+ true,
+ ],
+ [
+ 'sql-aggregate-to-typed-runner',
+ 'SELECT event, uniq(person_id) FROM events GROUP BY event ORDER BY uniq(person_id) DESC',
+ true,
+ ],
+ ['sql-aggregate-to-typed-runner', "SELECT max(timestamp), count() FROM events WHERE event = 'a'", false],
+ ['sql-aggregate-to-typed-runner', 'SELECT person_id, count() FROM events GROUP BY person_id', false],
+ ['sql-aggregate-to-typed-runner', 'SELECT uniq(person_id), groupArray(event) FROM events', false],
+ ['sql-aggregate-to-typed-runner', "SELECT count(), avg(dateDiff('hour', timestamp, now())) FROM events", false],
+ [
+ 'sql-aggregate-to-typed-runner',
+ 'SELECT event, count() FROM events GROUP BY event HAVING count() > 10',
+ false,
+ ],
+ ['sql-aggregate-to-typed-runner', 'SELECT count() FROM events e, persons p WHERE e.person_id = p.id', false],
+ ['sql-aggregate-to-typed-runner', 'SELECT person_id, count() FROM events GROUP BY 1', false],
+ [
+ 'sql-aggregate-to-typed-runner',
+ 'SELECT properties.$session_id AS sid, count() FROM events GROUP BY sid',
+ false,
+ ],
+ ['sql-aggregate-to-typed-runner', 'SELECT count(), max(e.timestamp) FROM events e', false],
+ ['sql-aggregate-to-typed-runner', 'SELECT count() FROM system.insights', false],
+ ['sql-aggregate-to-typed-runner', 'SELECT count() FROM posthog.ai_events', false],
+ ['sql-aggregate-to-typed-runner', 'SELECT count() FROM events_archive', false],
+ ])('the %s rule matches %j: %s', (ruleId, query, expected) => {
+ const rule = GUIDANCE_RULES.find((r) => r.id === ruleId)!
+ const call: GuidanceCall = { toolName: 'execute-sql', args: { query }, isError: false }
+ expect(triggerMatches(rule, call)).toBe(expected)
+ })
+
+ it.each([
+ ['a direct warehouse connection', { query: 'SELECT count() FROM events', connectionId: 'conn-1' }],
+ ['a query longer than the cap', { query: `SELECT count() FROM events /* ${'x'.repeat(5000)} */` }],
+ ])('the sql-aggregate-to-typed-runner rule skips %s', (_label, args) => {
+ const rule = GUIDANCE_RULES.find((r) => r.id === 'sql-aggregate-to-typed-runner')!
+ expect(triggerMatches(rule, { toolName: 'execute-sql', args, isError: false })).toBe(false)
})
it('ships every rule with a distinct id and flag', () => {