OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.
fix(mcp): bound tool response sizes with columnar tables and rollups
Carl-Gerhard Lindesvärd0c7a087a674a
diff --git a/packages/mcp/src/integration/tools.test.ts b/packages/mcp/src/integration/tools.test.tsindex 635a6c9b7..01441c720 100644--- a/packages/mcp/src/integration/tools.test.ts+++ b/packages/mcp/src/integration/tools.test.ts@@ -76,6 +76,21 @@ function makeServer() {};}+/**+ * Re-hydrate a columnar TableResult into row objects.+ *+ * Tools return `{ columns, rows }` so column names are stated once instead of+ * on every row; assertions read better against objects, so we invert it here.+ */+function rowsOf(result: {+ columns: string[];+ rows: unknown[][];+}): any[] {+ return result.rows.map((row) =>+ Object.fromEntries(result.columns.map((column, i) => [column, row[i]]))+ );+}+// ─── Discovery ────────────────────────────────────────────────────────────────describe('list_event_names', () => {@@ -128,7 +143,7 @@ describe('query_events', () => {startDate: '2000-01-01',endDate: '2099-01-01',});- expect(res.length).toBe(8);+ expect(rowsOf(res).length).toBe(8);});it('filters by eventName — only returns purchase events', async () => {@@ -140,10 +155,11 @@ describe('query_events', () => {endDate: '2099-01-01',eventNames: ['purchase'],});- expect(res.length).toBe(1);- expect(res[0].name).toBe('purchase');- expect(res[0].profile_id).toBe(FIXTURE.profiles.charlie);- expect(res[0].revenue).toBe(9900);+ const events = rowsOf(res);+ expect(events.length).toBe(1);+ expect(events[0].name).toBe('purchase');+ expect(events[0].profile_id).toBe(FIXTURE.profiles.charlie);+ expect(events[0].revenue).toBe(9900);});it('filters by profileId — returns only alice events', async () => {@@ -155,10 +171,11 @@ describe('query_events', () => {endDate: '2099-01-01',profileId: FIXTURE.profiles.alice,});- expect(res.length).toBe(3);- expect(res.every((e: any) => e.profile_id === FIXTURE.profiles.alice)).toBe(- true- );+ const events = rowsOf(res);+ expect(events.length).toBe(3);+ expect(+ events.every((e) => e.profile_id === FIXTURE.profiles.alice)+ ).toBe(true);});it('filters by browser', async () => {@@ -170,8 +187,9 @@ describe('query_events', () => {endDate: '2099-01-01',browser: 'Firefox',});- expect(res.length).toBe(5);- expect(res.every((e: any) => e.browser === 'Firefox')).toBe(true);+ const events = rowsOf(res);+ expect(events.length).toBe(5);+ expect(events.every((e) => e.browser === 'Firefox')).toBe(true);});// Note: read-context resolveProjectId ignores the input projectId and always@@ -187,7 +205,7 @@ describe('query_sessions', () => {startDate: '2000-01-01',endDate: '2099-01-01',});- expect(res.length).toBe(3);+ expect(rowsOf(res).length).toBe(3);});it('filters by profileId — charlie has 2 sessions', async () => {@@ -199,9 +217,10 @@ describe('query_sessions', () => {endDate: '2099-01-01',profileId: FIXTURE.profiles.charlie,});- expect(res.length).toBe(2);+ const sessions = rowsOf(res);+ expect(sessions.length).toBe(2);expect(- res.every((s: any) => s.profile_id === FIXTURE.profiles.charlie)+ sessions.every((s) => s.profile_id === FIXTURE.profiles.charlie)).toBe(true);});@@ -214,8 +233,9 @@ describe('query_sessions', () => {endDate: '2099-01-01',browser: 'Chrome',});- expect(res.length).toBe(1);- expect(res[0].profile_id).toBe(FIXTURE.profiles.alice);+ const sessions = rowsOf(res);+ expect(sessions.length).toBe(1);+ expect(sessions[0].profile_id).toBe(FIXTURE.profiles.alice);});});@@ -228,7 +248,7 @@ describe('find_profiles', () => {const res = await server.invoke('find_profiles', {projectId: TEST_PROJECT_ID,});- expect(res.length).toBe(3);+ expect(rowsOf(res).length).toBe(3);});it('filters by email partial match', async () => {@@ -238,8 +258,9 @@ describe('find_profiles', () => {projectId: TEST_PROJECT_ID,email: 'alice@',});- expect(res.length).toBe(1);- expect(res[0].email).toBe('[email protected]');+ const profiles = rowsOf(res);+ expect(profiles.length).toBe(1);+ expect(profiles[0].email).toBe('[email protected]');});it('filters by name — matches first_name and last_name', async () => {@@ -249,15 +270,15 @@ describe('find_profiles', () => {projectId: TEST_PROJECT_ID,name: 'Charlie',});- expect(byFirst.length).toBe(1);- expect(byFirst[0].first_name).toBe('Charlie');+ expect(rowsOf(byFirst).length).toBe(1);+ expect(rowsOf(byFirst)[0].first_name).toBe('Charlie');const byLast = await server.invoke('find_profiles', {projectId: TEST_PROJECT_ID,name: 'Smith',});- expect(byLast.length).toBe(1);- expect(byLast[0].last_name).toBe('Smith');+ expect(rowsOf(byLast).length).toBe(1);+ expect(rowsOf(byLast)[0].last_name).toBe('Smith');});it('filters by country property', async () => {@@ -267,8 +288,9 @@ describe('find_profiles', () => {projectId: TEST_PROJECT_ID,country: 'SE',});- expect(res.length).toBe(1);- expect(res[0].email).toBe('[email protected]');+ const profiles = rowsOf(res);+ expect(profiles.length).toBe(1);+ expect(profiles[0].email).toBe('[email protected]');});it('inactiveDays=7 excludes alice (active 2 days ago) but includes bob (no events)', async () => {@@ -278,7 +300,7 @@ describe('find_profiles', () => {projectId: TEST_PROJECT_ID,inactiveDays: 7,});- const emails = res.map((p: any) => p.email);+ const emails = rowsOf(res).map((p) => p.email);expect(emails).not.toContain('[email protected]');expect(emails).not.toContain('[email protected]');expect(emails).toContain('[email protected]');@@ -291,8 +313,9 @@ describe('find_profiles', () => {projectId: TEST_PROJECT_ID,minSessions: 2,});- expect(res.length).toBe(1);- expect(res[0].first_name).toBe('Charlie');+ const profiles = rowsOf(res);+ expect(profiles.length).toBe(1);+ expect(profiles[0].first_name).toBe('Charlie');});it('performedEvent=purchase returns only charlie', async () => {@@ -302,8 +325,9 @@ describe('find_profiles', () => {projectId: TEST_PROJECT_ID,performedEvent: 'purchase',});- expect(res.length).toBe(1);- expect(res[0].first_name).toBe('Charlie');+ const profiles = rowsOf(res);+ expect(profiles.length).toBe(1);+ expect(profiles[0].first_name).toBe('Charlie');});// Note: read-context resolveProjectId ignores the input projectId and always@@ -320,8 +344,7 @@ describe('get_profile', () => {});expect(res.profile.first_name).toBe('Charlie');expect(res.profile.email).toBe('[email protected]');- expect(Array.isArray(res.recent_events)).toBe(true);- expect(res.recent_events.length).toBe(5); // all charlie events+ expect(rowsOf(res.recent_events).length).toBe(5); // all charlie events});});@@ -333,9 +356,10 @@ describe('get_profile_sessions', () => {projectId: TEST_PROJECT_ID,profileId: FIXTURE.profiles.charlie,});- expect(res.sessions.length).toBe(2);+ const sessions = rowsOf(res);+ expect(sessions.length).toBe(2);expect(- res.sessions.every((s: any) => s.profile_id === FIXTURE.profiles.charlie)+ sessions.every((s) => s.profile_id === FIXTURE.profiles.charlie)).toBe(true);});});@@ -390,13 +414,14 @@ describe('list_group_types', () => {});describe('find_groups', () => {- it('returns empty array (no groups in fixtures)', async () => {+ it('returns an empty table (no groups in fixtures)', async () => {const server = makeServer();registerGroupTools(server as any, CTX);const res = await server.invoke('find_groups', {projectId: TEST_PROJECT_ID,});- expect(Array.isArray(res)).toBe(true);+ expect(rowsOf(res)).toEqual([]);+ expect(res.total_rows).toBe(0);});});@@ -425,8 +450,7 @@ describe('get_analytics_overview', () => {endDate: '2099-01-01',});expect(res).toHaveProperty('summary');- expect(res).toHaveProperty('series');- expect(Array.isArray(res.series)).toBe(true);+ expect(Array.isArray(rowsOf(res.series))).toBe(true);});});@@ -439,8 +463,7 @@ describe('get_top_pages', () => {startDate: '2000-01-01',endDate: '2099-01-01',});- expect(Array.isArray(res)).toBe(true);- const paths = res.map((p: any) => p.path);+ const paths = rowsOf(res).map((p) => p.path);// getTopPages queries screen_view events only — Charlie's /shop appears;// Alice's /home is a page_view (not screen_view) so it won't show here.expect(paths).toContain('/shop');@@ -457,7 +480,8 @@ describe('get_entry_exit_pages', () => {endDate: '2099-01-01',mode: 'entry',});- expect(Array.isArray(res)).toBe(true);+ expect(res.mode).toBe('entry');+ expect(Array.isArray(rowsOf(res))).toBe(true);});it('returns exit pages array', async () => {@@ -469,12 +493,13 @@ describe('get_entry_exit_pages', () => {endDate: '2099-01-01',mode: 'exit',});- expect(Array.isArray(res)).toBe(true);+ expect(res.mode).toBe('exit');+ expect(Array.isArray(rowsOf(res))).toBe(true);});});describe('get_page_performance', () => {- it('returns pages array with seo_signals on each page', async () => {+ it('returns a page table plus the shared seo thresholds', async () => {const server = makeServer();registerPagePerformanceTools(server as any, CTX);const res = await server.invoke('get_page_performance', {@@ -482,20 +507,20 @@ describe('get_page_performance', () => {startDate: '2000-01-01',endDate: '2099-01-01',});- expect(typeof res.total_pages).toBe('number');- expect(typeof res.shown).toBe('number');- expect(Array.isArray(res.pages)).toBe(true);- for (const page of res.pages) {- expect(page).toHaveProperty('seo_signals');- expect(typeof page.seo_signals.high_bounce).toBe('boolean');- expect(typeof page.seo_signals.low_engagement).toBe('boolean');- expect(typeof page.seo_signals.good_landing_page).toBe('boolean');+ // The thresholds are stated once instead of re-derived onto every row.+ expect(res.seo_thresholds).toHaveProperty('high_bounce');+ expect(res.seo_thresholds).toHaveProperty('low_engagement');+ expect(res.seo_thresholds).toHaveProperty('good_landing_page');+ expect(typeof res.total_rows).toBe('number');+ for (const page of rowsOf(res)) {+ expect(typeof page.bounce_rate).toBe('number');+ expect(typeof page.avg_duration).toBe('number');}});});describe('get_top_referrers', () => {- it('returns array', async () => {+ it('returns a columnar table', async () => {const server = makeServer();registerTrafficTools(server as any, CTX);const res = await server.invoke('get_top_referrers', {@@ -503,7 +528,9 @@ describe('get_top_referrers', () => {startDate: '2000-01-01',endDate: '2099-01-01',});- expect(Array.isArray(res)).toBe(true);+ expect(res.columns).toContain('name');+ expect(res.columns).toContain('sessions');+ expect(Array.isArray(res.rows)).toBe(true);});});@@ -516,9 +543,8 @@ describe('get_country_breakdown', () => {startDate: '2000-01-01',endDate: '2099-01-01',});- expect(Array.isArray(res)).toBe(true);// getTopGeneric returns { name, sessions, pageviews } — field is 'name'- const countries = res.map((r: any) => r.name);+ const countries = rowsOf(res).map((r) => r.name);expect(countries).toContain('US');});});@@ -532,9 +558,8 @@ describe('get_device_breakdown', () => {startDate: '2000-01-01',endDate: '2099-01-01',});- expect(Array.isArray(res)).toBe(true);// getTopGeneric returns { name, sessions, pageviews } — field is 'name'- const devices = res.map((r: any) => r.name);+ const devices = rowsOf(res).map((r) => r.name);expect(devices).toContain('desktop');});});@@ -592,8 +617,8 @@ describe('get_user_flow', () => {});expect(res.mode).toBe('after');expect(res.startEvent).toBe('session_start');- expect(Array.isArray(res.nodes)).toBe(true);- expect(Array.isArray(res.links)).toBe(true);+ expect(Array.isArray(rowsOf(res.nodes))).toBe(true);+ expect(Array.isArray(rowsOf(res.links))).toBe(true);expect(typeof res.node_count).toBe('number');expect(typeof res.link_count).toBe('number');});@@ -623,7 +648,7 @@ describe('get_rolling_active_users', () => {});expect(res.label).toBe('DAU');expect(res.window_days).toBe(1);- expect(Array.isArray(res.series)).toBe(true);+ expect(Array.isArray(rowsOf(res.series))).toBe(true);});it('uses correct label for WAU and MAU', async () => {@@ -649,12 +674,12 @@ describe('get_weekly_retention_series', () => {const res = await server.invoke('get_weekly_retention_series', {projectId: TEST_PROJECT_ID,});- expect(Array.isArray(res)).toBe(true);- if (res.length > 0) {- expect(res[0]).toHaveProperty('date');- expect(res[0]).toHaveProperty('active_users');- expect(res[0]).toHaveProperty('retained_users');- expect(res[0]).toHaveProperty('retention');+ const weeks = rowsOf(res);+ if (weeks.length > 0) {+ expect(weeks[0]).toHaveProperty('date');+ expect(weeks[0]).toHaveProperty('active_users');+ expect(weeks[0]).toHaveProperty('retained_users');+ expect(weeks[0]).toHaveProperty('retention');}});});@@ -692,6 +717,19 @@ describe('get_user_last_seen_distribution', () => {expect(res.summary.active_last_7_days).toBe(2);expect(res.summary.active_8_to_14_days).toBe(0);expect(res.summary.churned_60_plus_days).toBe(0);- expect(Array.isArray(res.distribution)).toBe(true);+ // The raw per-day histogram is opt-in — the buckets above answer the+ // question in a fraction of the size.+ expect(res.distribution).toBeUndefined();+ });++ it('returns the raw histogram when includeDistribution is set', async () => {+ const server = makeServer();+ registerEngagementTools(server as any, CTX);+ const res = await server.invoke('get_user_last_seen_distribution', {+ projectId: TEST_PROJECT_ID,+ includeDistribution: true,+ });+ expect(res.distribution.columns).toEqual(['days', 'users']);+ expect(Array.isArray(res.distribution.rows)).toBe(true);});});diff --git a/packages/mcp/src/tools/analytics/active-users.ts b/packages/mcp/src/tools/analytics/active-users.tsindex b48806cb6..4400a3939 100644--- a/packages/mcp/src/tools/analytics/active-users.ts+++ b/packages/mcp/src/tools/analytics/active-users.ts@@ -4,18 +4,34 @@ import { z } from 'zod';import type { McpAuthContext } from '../../auth';import {projectIdSchema,-+ resolveProjectId,+ table,withErrorHandling,- resolveProjectId+ zLimit,} from '../shared';+/**+ * Both underlying queries return a project's entire history with no date bound,+ * so the response grows forever as the project ages. Trends are read from the+ * recent end, so we keep the most recent points and say how many we dropped.+ */+const DEFAULT_DAILY_POINTS = 90;+const MAX_DAILY_POINTS = 730;+const DEFAULT_WEEKLY_POINTS = 26;+const MAX_WEEKLY_POINTS = 260;++/** Keep the tail (most recent) rather than the head, then restore date order. */+function mostRecent<T>(rows: T[], take: number): T[] {+ return rows.length <= take ? rows : rows.slice(rows.length - take);+}+export function registerActiveUserTools(server: McpServer,context: McpAuthContext,) {server.tool('get_rolling_active_users',- 'Get a time series of unique active users using a rolling window. Use days=1 for DAU, days=7 for WAU, days=30 for MAU. Shows how your active user count trends over time.',+ `Get a time series of unique active users using a rolling window. Use days=1 for DAU, days=7 for WAU, days=30 for MAU. Shows how your active user count trends over time. Returns the most recent ${DEFAULT_DAILY_POINTS} days by default.`,{projectId: projectIdSchema(context),days: z@@ -24,29 +40,58 @@ export function registerActiveUserTools(.min(1).max(90).describe('Rolling window in days. 1 = DAU, 7 = WAU, 30 = MAU.'),+ limit: zLimit(DEFAULT_DAILY_POINTS, MAX_DAILY_POINTS),},- async ({ projectId: inputProjectId, days }) =>+ async ({ projectId: inputProjectId, days, limit }) =>withErrorHandling(async () => {const projectId = await resolveProjectId(context, inputProjectId);+ const take = limit ?? DEFAULT_DAILY_POINTS;const data = await getRollingActiveUsers({ projectId, days });+ const recent = mostRecent(data, take);return {window_days: days,label: days === 1 ? 'DAU' : days === 7 ? 'WAU' : days === 30 ? 'MAU' : `${days}d active`,- series: data,+ ...(data.length > recent.length+ ? {+ series_note: `Showing the most recent ${recent.length} of ${data.length} days. Raise \`limit\` for more history.`,+ }+ : {}),+ series: table(recent, {+ limit: take,+ columns: ['date', 'users'],+ sortedBy: 'date',+ unit: 'days',+ }),};}),);server.tool('get_weekly_retention_series',- 'Get week-over-week user retention as a time series. For each week, shows how many users were active that week and how many returned the following week. Useful for understanding whether your product retains users.',+ `Get week-over-week user retention as a time series. For each week, shows how many users were active that week and how many returned the following week. Useful for understanding whether your product retains users. Returns the most recent ${DEFAULT_WEEKLY_POINTS} weeks by default.`,{projectId: projectIdSchema(context),+ limit: zLimit(DEFAULT_WEEKLY_POINTS, MAX_WEEKLY_POINTS),},- async ({ projectId: inputProjectId }) =>+ async ({ projectId: inputProjectId, limit }) =>withErrorHandling(async () => {const projectId = await resolveProjectId(context, inputProjectId);- return getRetentionSeries({ projectId });+ const take = limit ?? DEFAULT_WEEKLY_POINTS;+ const data = await getRetentionSeries({ projectId });+ const recent = mostRecent(data, take);+ return {+ ...(data.length > recent.length+ ? {+ series_note: `Showing the most recent ${recent.length} of ${data.length} weeks. Raise \`limit\` for more history.`,+ }+ : {}),+ ...table(recent, {+ limit: take,+ columns: ['date', 'active_users', 'retained_users', 'retention'],+ sortedBy: 'date',+ unit: 'weeks',+ }),+ };}),);}diff --git a/packages/mcp/src/tools/analytics/columns.ts b/packages/mcp/src/tools/analytics/columns.tsnew file mode 100644index 000000000..f982fe986--- /dev/null+++ b/packages/mcp/src/tools/analytics/columns.ts@@ -0,0 +1,81 @@+/**+ * Column sets for the raw event/session rows returned by several tools.+ *+ * A ClickHouse event carries 31 fields and a session 35. Most are dead weight+ * to a reader: `project_id` is constant for the whole call, and `longitude`/+ * `latitude`/`imported_at`/`sdk_*`/`*_version`/`brand`/`model`/`device_id`+ * answer questions nobody asks of a 20-row sample. Tools return the useful+ * subset by default and let the caller opt into the rest via a `fields`+ * argument, rather than paying for every field on every call.+ */++export const EVENT_COLUMNS_DEFAULT = [+ 'created_at',+ 'name',+ 'path',+ 'profile_id',+ 'session_id',+ 'country',+ 'device',+ 'browser',+ 'os',+ 'referrer_name',+ 'referrer_type',+ 'duration',+ 'revenue',+ 'properties',+] as const;++export const EVENT_COLUMNS_EXTRA = [+ 'id',+ 'origin',+ 'referrer',+ 'city',+ 'region',+ 'os_version',+ 'browser_version',+ 'brand',+ 'model',+ 'device_id',+ 'sdk_name',+ 'sdk_version',+ 'groups',+] as const;++export const SESSION_COLUMNS_DEFAULT = [+ 'id',+ 'created_at',+ 'duration',+ 'event_count',+ 'screen_view_count',+ 'is_bounce',+ 'entry_path',+ 'exit_path',+ 'profile_id',+ 'country',+ 'device',+ 'browser',+ 'referrer_name',+ 'referrer_type',+ 'revenue',+] as const;++export const SESSION_COLUMNS_EXTRA = [+ 'ended_at',+ 'entry_origin',+ 'exit_origin',+ 'referrer',+ 'city',+ 'region',+ 'os',+ 'os_version',+ 'browser_version',+ 'brand',+ 'model',+ 'device_id',+ 'utm_source',+ 'utm_medium',+ 'utm_campaign',+ 'utm_content',+ 'utm_term',+] as const;diff --git a/packages/mcp/src/tools/analytics/engagement.test.ts b/packages/mcp/src/tools/analytics/engagement.test.tsindex 3912e7c43..a5173fdd5 100644--- a/packages/mcp/src/tools/analytics/engagement.test.ts+++ b/packages/mcp/src/tools/analytics/engagement.test.ts@@ -70,15 +70,38 @@ describe('get_user_last_seen_distribution — bucketing', () => {expect(content.summary.churned_60_plus_days).toBe(0);});- it('passes raw distribution alongside the summary', async () => {- const raw = [{ days: 1, users: 5 }];- mockGetRetentionLastSeenSeries.mockResolvedValue(raw);+ it('omits the raw distribution unless it is asked for', async () => {+ mockGetRetentionLastSeenSeries.mockResolvedValue([{ days: 1, users: 5 }]);const server = makeServer() as any;registerEngagementTools(server, READ_CTX);const result = await server.invoke({ projectId: READ_CTX.projectId }) as any;const content = JSON.parse(result.content[0].text);- expect(content.distribution).toEqual(raw);+ // One row per distinct "days ago" is unbounded; the buckets answer the+ // question, so the histogram is opt-in.+ expect(content.distribution).toBeUndefined();+ expect(content.summary.active_last_7_days).toBe(5);+ });++ it('returns the raw distribution as a table when includeDistribution is set', async () => {+ mockGetRetentionLastSeenSeries.mockResolvedValue([+ { days: 1, users: 5 },+ { days: 40, users: 2 },+ ]);++ const server = makeServer() as any;+ registerEngagementTools(server, READ_CTX);+ const result = await server.invoke({+ projectId: READ_CTX.projectId,+ includeDistribution: true,+ }) as any;+ const content = JSON.parse(result.content[0].text);++ expect(content.distribution.columns).toEqual(['days', 'users']);+ expect(content.distribution.rows).toEqual([+ [1, 5],+ [40, 2],+ ]);});});diff --git a/packages/mcp/src/tools/analytics/engagement.ts b/packages/mcp/src/tools/analytics/engagement.tsindex 435227c00..5e9070c30 100644--- a/packages/mcp/src/tools/analytics/engagement.ts+++ b/packages/mcp/src/tools/analytics/engagement.ts@@ -1,21 +1,35 @@import { getRetentionLastSeenSeries } from '@openpanel/db';import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';+import { z } from 'zod';import type { McpAuthContext } from '../../auth';-import { projectIdSchema, withErrorHandling,- resolveProjectId+import {+ projectIdSchema,+ resolveProjectId,+ table,+ withErrorHandling,} from '../shared';+/** Guard for the opt-in raw histogram: one row per distinct "days ago" value. */+const MAX_DISTRIBUTION_ROWS = 200;+export function registerEngagementTools(server: McpServer,context: McpAuthContext,) {server.tool('get_user_last_seen_distribution',- 'Get a histogram of how many users were last active N days ago. Shows the distribution of user recency — how many users are still fresh (0-7 days), somewhat stale (8-30 days), or churned (30+ days). Great for churn analysis and understanding overall engagement health.',+ 'Get a summary of how recently users were last active: how many are still fresh (0-7 days), somewhat stale (8-30 days), or churned (30+ days). Great for churn analysis and understanding overall engagement health. Pass includeDistribution to also get the raw per-day histogram.',{projectId: projectIdSchema(context),+ includeDistribution: z+ .boolean()+ .default(false)+ .optional()+ .describe(+ 'Include the raw per-day histogram (one row per distinct "days since last seen"). Off by default — the bucketed summary answers the question in a fraction of the size.',+ ),},- async ({ projectId: inputProjectId }) =>+ async ({ projectId: inputProjectId, includeDistribution }) =>withErrorHandling(async () => {const projectId = await resolveProjectId(context, inputProjectId);const raw = await getRetentionLastSeenSeries({ projectId });@@ -46,7 +60,17 @@ export function registerEngagementTools(inactive_31_to_60_days: active_31_60,churned_60_plus_days: churned_60_plus,},- distribution: raw,+ ...(includeDistribution+ ? {+ distribution: table(raw, {+ limit: MAX_DISTRIBUTION_ROWS,+ columns: ['days', 'users'],+ sum: ['users'],+ sortedBy: 'days',+ unit: 'buckets',+ }),+ }+ : {}),};}),);diff --git a/packages/mcp/src/tools/analytics/events.ts b/packages/mcp/src/tools/analytics/events.tsindex 1df91a07b..8f248c69a 100644--- a/packages/mcp/src/tools/analytics/events.ts+++ b/packages/mcp/src/tools/analytics/events.ts@@ -2,19 +2,27 @@ import { queryEventsCore } from '@openpanel/db';import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';import { z } from 'zod';import type { McpAuthContext } from '../../auth';+import {+ EVENT_COLUMNS_DEFAULT,+ EVENT_COLUMNS_EXTRA,+} from './columns';import {projectIdSchema,- resolveDateRange,-+ resolveProjectId,+ table,withErrorHandling,zDateRange,- resolveProjectId+ zLimit,} from '../shared';+const DEFAULT_EVENT_LIMIT = 20;+const MAX_EVENT_LIMIT = 100;++export function registerEventTools(server: McpServer, context: McpAuthContext) {server.tool('query_events',- 'Query raw analytics events with optional filters. Returns individual event records including path, device, country, referrer, and custom properties. Defaults to the last 30 days.',+ `Query raw analytics events with optional filters. Returns individual event records as a columnar table. Defaults to the last 30 days and the ${DEFAULT_EVENT_LIMIT} most relevant events, with a commonly-useful field set — pass \`fields\` to add columns like origin, city, or sdk_name.`,{projectId: projectIdSchema(context),...zDateRange,@@ -56,18 +64,30 @@ export function registerEventTools(server: McpServer, context: McpAuthContext) {.record(z.string(), z.string()).optional().describe('Filter by custom event properties (key-value pairs)'),- limit: z- .number()- .min(1)- .max(100)- .default(20)+ fields: z+ .array(z.enum(EVENT_COLUMNS_EXTRA)).optional()- .describe('Maximum number of events to return (1-100, default 20)'),+ .describe(+ `Extra columns to include beyond the default set (${EVENT_COLUMNS_DEFAULT.join(', ')}). Only request what you need — every extra column costs rows of output.`,+ ),+ limit: zLimit(DEFAULT_EVENT_LIMIT, MAX_EVENT_LIMIT),},- async ({ projectId: inputProjectId, ...input }) =>+ async ({ projectId: inputProjectId, fields, ...input }) =>withErrorHandling(async () => {const projectId = await resolveProjectId(context, inputProjectId);- return queryEventsCore({ projectId, ...input });+ const take = input.limit ?? DEFAULT_EVENT_LIMIT;+ const events = await queryEventsCore({+ ...input,+ projectId,+ limit: take + 1,+ });+ return table(events.slice(0, take), {+ limit: take,+ columns: [...EVENT_COLUMNS_DEFAULT, ...(fields ?? [])],+ sortedBy: 'created_at desc',+ unit: 'events',+ moreAvailable: events.length > take,+ });}),);}diff --git a/packages/mcp/src/tools/analytics/groups.ts b/packages/mcp/src/tools/analytics/groups.tsindex 91c8808a7..edf47d8e0 100644--- a/packages/mcp/src/tools/analytics/groups.ts+++ b/packages/mcp/src/tools/analytics/groups.ts@@ -2,10 +2,22 @@ import { getGroupById, getGroupList, getGroupMemberProfiles, getGroupTypes } froimport type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';import { z } from 'zod';import type { McpAuthContext } from '../../auth';-import { projectIdSchema, withErrorHandling,- resolveProjectId+import {+ projectIdSchema,+ resolveProjectId,+ table,+ withErrorHandling,+ zLimit,} from '../shared';+const DEFAULT_GROUP_LIMIT = 20;+const MAX_GROUP_LIMIT = 100;+const DEFAULT_MEMBER_LIMIT = 10;+const MAX_MEMBER_LIMIT = 50;++const GROUP_COLUMNS = ['id', 'type', 'name', 'createdAt', 'properties'] as const;+const MEMBER_COLUMNS = ['id', 'firstName', 'lastName', 'email', 'lastSeenAt'] as const;+export function registerGroupTools(server: McpServer,context: McpAuthContext,@@ -26,7 +38,7 @@ export function registerGroupTools(server.tool('find_groups',- 'Search for groups (companies, teams, accounts) by name, ID, or type. Groups are B2B entities that profiles (users) belong to.',+ `Search for groups (companies, teams, accounts) by name, ID, or type. Groups are B2B entities that profiles (users) belong to. Defaults to ${DEFAULT_GROUP_LIMIT} groups.`,{projectId: projectIdSchema(context),type: z@@ -37,19 +49,19 @@ export function registerGroupTools(.string().optional().describe('Partial match against group name or ID'),- limit: z- .number()- .int()- .min(1)- .max(100)- .default(20)- .optional()- .describe('Maximum number of groups to return (default 20)'),+ limit: zLimit(DEFAULT_GROUP_LIMIT, MAX_GROUP_LIMIT),},async ({ projectId: inputProjectId, type, search, limit }) =>withErrorHandling(async () => {const projectId = await resolveProjectId(context, inputProjectId);- return getGroupList({ projectId, type, search, take: limit ?? 20 });+ const take = limit ?? DEFAULT_GROUP_LIMIT;+ const groups = await getGroupList({ projectId, type, search, take: take + 1 });+ return table(groups.slice(0, take), {+ limit: take,+ columns: GROUP_COLUMNS,+ unit: 'groups',+ moreAvailable: groups.length > take,+ });}),);@@ -59,24 +71,18 @@ export function registerGroupTools({projectId: projectIdSchema(context),groupId: z.string().describe('The group ID to look up'),- memberLimit: z- .number()- .int()- .min(1)- .max(50)- .default(10)- .optional()- .describe('Max number of member profiles to include (default 10)'),+ memberLimit: zLimit(DEFAULT_MEMBER_LIMIT, MAX_MEMBER_LIMIT),},async ({ projectId: inputProjectId, groupId, memberLimit }) =>withErrorHandling(async () => {const projectId = await resolveProjectId(context, inputProjectId);+ const take = memberLimit ?? DEFAULT_MEMBER_LIMIT;const [group, members] = await Promise.all([getGroupById(groupId, projectId),getGroupMemberProfiles({projectId,groupId,- take: memberLimit ?? 10,+ take,}),]);@@ -87,7 +93,13 @@ export function registerGroupTools(return {group,member_count: members.count,- members: members.data,+ members: table(members.data, {+ limit: take,+ columns: MEMBER_COLUMNS,+ unit: 'members',+ // `count` is the true total; the fetched page is capped at `take`.+ moreAvailable: members.count > members.data.length,+ }),};}),);diff --git a/packages/mcp/src/tools/analytics/overview.ts b/packages/mcp/src/tools/analytics/overview.tsindex 227d9e20d..8100c127a 100644--- a/packages/mcp/src/tools/analytics/overview.ts+++ b/packages/mcp/src/tools/analytics/overview.ts@@ -5,19 +5,92 @@ import type { McpAuthContext } from '../../auth';import {projectIdSchema,resolveDateRange,-+ resolveProjectId,+ table,withErrorHandling,zDateRange,- resolveProjectId} from '../shared';+type Interval = 'hour' | 'day' | 'week' | 'month';++/** Coarsest-to-finest, so we can step down when a request is too fine-grained. */+const INTERVAL_ORDER: Interval[] = ['hour', 'day', 'week', 'month'];++const POINTS_PER_DAY: Record<Interval, number> = {+ hour: 24,+ day: 1,+ week: 1 / 7,+ month: 1 / 30,+};++/**+ * The most points we'll return in one series.+ *+ * A 30-day range at `interval: "hour"` is 720 points of 8 metrics each. That is+ * not a chart an LLM can read — it's a wall of numbers that buries the summary+ * the caller actually asked for.+ */+const MAX_SERIES_POINTS = 180;++const SERIES_COLUMNS = [+ 'date',+ 'unique_visitors',+ 'total_sessions',+ 'total_screen_views',+ 'bounce_rate',+ 'avg_session_duration',+ 'views_per_session',+ 'total_revenue',+] as const;++/**+ * Pick the finest interval that fits the point budget for this date range.+ *+ * Coarsening beats truncating for a time series: returning the most recent 180+ * of 720 hourly points silently answers a different question than the one asked+ * ("the last week" instead of "the last 30 days"). Stepping the interval down+ * keeps the window intact and only loses resolution, which we say out loud.+ */+function fitInterval(+ requested: Interval,+ startDate: string,+ endDate: string,+): { interval: Interval; note?: string } {+ const days =+ Math.max(+ 0,+ (new Date(endDate).getTime() - new Date(startDate).getTime()) / 86_400_000,+ ) + 1;+ const points = (i: Interval) => Math.ceil(days * POINTS_PER_DAY[i]);++ if (points(requested) <= MAX_SERIES_POINTS) {+ return { interval: requested };+ }++ const start = INTERVAL_ORDER.indexOf(requested);+ for (const candidate of INTERVAL_ORDER.slice(start + 1)) {+ if (points(candidate) <= MAX_SERIES_POINTS) {+ return {+ interval: candidate,+ note: `Requested interval "${requested}" would return ~${points(requested)} points over this range, above the ${MAX_SERIES_POINTS}-point limit. Coarsened to "${candidate}" (~${points(candidate)} points) — the date range is unchanged. Narrow the range to get "${requested}" resolution.`,+ };+ }+ }++ const coarsest = INTERVAL_ORDER[INTERVAL_ORDER.length - 1] as Interval;+ return {+ interval: coarsest,+ note: `Requested interval "${requested}" is far too fine for this range; coarsened to "${coarsest}". Narrow the date range for finer resolution.`,+ };+}+export function registerOverviewTools(server: McpServer,context: McpAuthContext,) {server.tool('get_analytics_overview',- 'Get key analytics metrics for a date range: unique visitors, total pageviews, sessions, bounce rate, average session duration, and views per session. Optionally includes a time-series breakdown by interval.',+ 'Get key analytics metrics for a date range: unique visitors, total pageviews, sessions, bounce rate, average session duration, and views per session. Includes a time-series breakdown by interval — the interval is automatically coarsened if the requested one would produce an unreadably long series, and the response says so when that happens.',{projectId: projectIdSchema(context),...zDateRange,@@ -26,17 +99,48 @@ export function registerOverviewTools(.default('day').optional().describe('Time interval for the series breakdown (default: day)'),+ includeSeries: z+ .boolean()+ .default(true)+ .optional()+ .describe(+ 'Set false to get only the summary totals and skip the per-interval series. Do this when you just need the headline numbers.',+ ),},- async ({ projectId: inputProjectId, startDate: sd, endDate: ed, interval }) =>+ async ({ projectId: inputProjectId, startDate: sd, endDate: ed, interval, includeSeries }) =>withErrorHandling(async () => {const projectId = await resolveProjectId(context, inputProjectId);const { startDate, endDate } = resolveDateRange(sd, ed);- return getAnalyticsOverviewCore({+ const fitted = fitInterval(interval ?? 'day', startDate, endDate);++ const result = await getAnalyticsOverviewCore({projectId,startDate,endDate,- interval,+ interval: fitted.interval,});++ if (includeSeries === false) {+ return {+ summary: result.summary,+ startDate,+ endDate,+ };+ }++ return {+ summary: result.summary,+ interval: fitted.interval,+ startDate,+ endDate,+ ...(fitted.note ? { interval_note: fitted.note } : {}),+ series: table(result.series, {+ limit: MAX_SERIES_POINTS,+ columns: SERIES_COLUMNS,+ sortedBy: 'date',+ unit: 'intervals',+ }),+ };}),);}diff --git a/packages/mcp/src/tools/analytics/page-conversions.test.ts b/packages/mcp/src/tools/analytics/page-conversions.test.tsindex ca623ffe8..bc00c6a60 100644--- a/packages/mcp/src/tools/analytics/page-conversions.test.ts+++ b/packages/mcp/src/tools/analytics/page-conversions.test.ts@@ -31,6 +31,13 @@ function makeServer() {const READ_CTX = { projectId: 'proj-1', organizationId: 'org-1', clientType: 'read' as const };+/** Re-hydrate the columnar table the tool returns into row objects. */+function rowsOf(result: { columns: string[]; rows: unknown[][] }): any[] {+ return result.rows.map((row) =>+ Object.fromEntries(result.columns.map((column, i) => [column, row[i]])),+ );+}+function makePage(overrides: Record<string, unknown> = {}) {return {path: '/pricing',@@ -58,7 +65,7 @@ describe('get_page_conversions — output structure', () => {})) as any;const content = JSON.parse(result.content[0].text);- expect(content.pages[0]).toMatchObject({+ expect(rowsOf(content)[0]).toMatchObject({path: '/pricing',origin: 'https://example.com',unique_converters: 10,@@ -80,7 +87,7 @@ describe('get_page_conversions — output structure', () => {expect(content.conversion_event).toBe('purchase');expect(content.window_hours).toBe(24);- expect(content.total_pages).toBe(1);+ expect(content.total_rows).toBe(1);});it('returns empty pages array when no conversions found', async () => {@@ -94,8 +101,8 @@ describe('get_page_conversions — output structure', () => {})) as any;const content = JSON.parse(result.content[0].text);- expect(content.pages).toEqual([]);- expect(content.total_pages).toBe(0);+ expect(content.rows).toEqual([]);+ expect(content.total_rows).toBe(0);});});@@ -153,7 +160,7 @@ describe('get_page_conversions — arguments forwarding', () => {expect(content.window_hours).toBe(168);});- it('defaults limit to 50 when not provided', async () => {+ it('defaults limit to 25, fetching one extra row to detect a tail', async () => {mockGetPageConversionsCore.mockResolvedValue([]);const server = makeServer() as any;@@ -164,7 +171,7 @@ describe('get_page_conversions — arguments forwarding', () => {});expect(mockGetPageConversionsCore).toHaveBeenCalledWith(- expect.objectContaining({ limit: 50 }),+ expect.objectContaining({ limit: 26 }),);});@@ -199,7 +206,7 @@ describe('get_page_conversions — total_pages count', () => {})) as any;const content = JSON.parse(result.content[0].text);- expect(content.total_pages).toBe(7);- expect(content.pages).toHaveLength(7);+ expect(content.total_rows).toBe(7);+ expect(rowsOf(content)).toHaveLength(7);});});diff --git a/packages/mcp/src/tools/analytics/page-conversions.ts b/packages/mcp/src/tools/analytics/page-conversions.tsindex a18d86f42..67ac65609 100644--- a/packages/mcp/src/tools/analytics/page-conversions.ts+++ b/packages/mcp/src/tools/analytics/page-conversions.ts@@ -5,15 +5,20 @@ import type { McpAuthContext } from '../../auth';import {projectIdSchema,resolveDateRange,+ resolveProjectId,+ table,withErrorHandling,zDateRange,- resolveProjectId,+ zLimit,} from '../shared';+const DEFAULT_CONVERSION_LIMIT = 25;+const MAX_CONVERSION_LIMIT = 500;+export function registerPageConversionTools(server: McpServer, context: McpAuthContext) {server.tool('get_page_conversions',- 'Find which pages drive the most conversions. Given a conversion event (e.g. "sign_up", "purchase"), returns pages ranked by how many unique visitors went on to convert within a configurable time window after the page view. Includes total_visitors and conversion_rate per page. Useful for identifying high-value content and optimizing landing pages.',+ `Find which pages drive the most conversions. Given a conversion event (e.g. "sign_up", "purchase"), returns pages ranked by how many unique visitors went on to convert within a configurable time window after the page view. Includes total_visitors and conversion_rate per page. Useful for identifying high-value content and optimizing landing pages. Defaults to the top ${DEFAULT_CONVERSION_LIMIT} pages.`,{projectId: projectIdSchema(context),...zDateRange,@@ -31,15 +36,7 @@ export function registerPageConversionTools(server: McpServer, context: McpAuthC.describe('How many hours after a page view a conversion still counts (default: 24). Use 1 for same-session, 168 for 7-day window.',),- limit: z- .number()- .min(1)- .max(500)- .default(50)- .optional()- .describe(- 'Maximum pages to return, sorted by unique_converters descending (default: 50)',- ),+ limit: zLimit(DEFAULT_CONVERSION_LIMIT, MAX_CONVERSION_LIMIT),},async ({projectId: inputProjectId,@@ -52,19 +49,27 @@ export function registerPageConversionTools(server: McpServer, context: McpAuthCwithErrorHandling(async () => {const projectId = await resolveProjectId(context, inputProjectId);const { startDate, endDate } = resolveDateRange(sd, ed);+ const take = limit ?? DEFAULT_CONVERSION_LIMIT;const pages = await getPageConversionsCore({projectId,startDate,endDate,conversionEvent,windowHours: windowHours ?? 24,- limit: limit ?? 50,+ limit: take + 1,});return {conversion_event: conversionEvent,window_hours: windowHours ?? 24,- total_pages: pages.length,- pages,+ // SQL-limited, so there's no countable tail to roll up — the extra+ // fetched row just flags that more pages exist.+ ...table(pages.slice(0, take), {+ limit: take,+ columns: ['path', 'origin', 'unique_converters', 'total_visitors', 'conversion_rate'],+ sortedBy: 'unique_converters',+ unit: 'pages',+ moreAvailable: pages.length > take,+ }),};}),);diff --git a/packages/mcp/src/tools/analytics/page-performance.test.ts b/packages/mcp/src/tools/analytics/page-performance.test.tsindex 8f4e25b10..5aeae05d7 100644--- a/packages/mcp/src/tools/analytics/page-performance.test.ts+++ b/packages/mcp/src/tools/analytics/page-performance.test.ts@@ -31,6 +31,13 @@ function makeServer() {const READ_CTX = { projectId: 'proj-1', organizationId: 'org-1', clientType: 'read' as const };+/** Re-hydrate the columnar table the tool returns into row objects. */+function rowsOf(result: { columns: string[]; rows: unknown[][] }): any[] {+ return result.rows.map((row) =>+ Object.fromEntries(result.columns.map((column, i) => [column, row[i]])),+ );+}+function makePage(overrides: Record<string, unknown> = {}) {return {path: '/page',@@ -48,8 +55,8 @@ beforeEach(() => {mockGetSettingsForProject.mockResolvedValue({ timezone: 'UTC' });});-describe('get_page_performance — seo_signals annotation', () => {- it('marks high_bounce when bounce_rate > 70', async () => {+describe('get_page_performance — seo thresholds', () => {+ it('states the classification rules once instead of per row', async () => {mockGetTopPages.mockResolvedValue([makePage({ bounce_rate: 80 })]);const server = makeServer() as any;@@ -57,55 +64,29 @@ describe('get_page_performance — seo_signals annotation', () => {const result = await server.invoke({ projectId: READ_CTX.projectId }) as any;const content = JSON.parse(result.content[0].text);- expect(content.pages[0].seo_signals.high_bounce).toBe(true);- expect(content.pages[0].seo_signals.low_engagement).toBe(false);- expect(content.pages[0].seo_signals.good_landing_page).toBe(false);- });-- it('does not mark high_bounce when bounce_rate is exactly 70', async () => {- mockGetTopPages.mockResolvedValue([makePage({ bounce_rate: 70 })]);-- const server = makeServer() as any;- registerPagePerformanceTools(server, READ_CTX);- const result = await server.invoke({ projectId: READ_CTX.projectId }) as any;- const content = JSON.parse(result.content[0].text);-- expect(content.pages[0].seo_signals.high_bounce).toBe(false);+ expect(content.seo_thresholds).toEqual({+ high_bounce: 'bounce_rate > 70',+ low_engagement: 'avg_duration < 1 (minutes)',+ good_landing_page: 'bounce_rate < 40 AND avg_duration > 2',+ });});- it('marks low_engagement when avg_duration < 1', async () => {- mockGetTopPages.mockResolvedValue([makePage({ avg_duration: 0.5, bounce_rate: 30 })]);+ it('returns the raw inputs the thresholds are applied to', async () => {+ mockGetTopPages.mockResolvedValue([+ makePage({ bounce_rate: 80, avg_duration: 0.5 }),+ ]);const server = makeServer() as any;registerPagePerformanceTools(server, READ_CTX);const result = await server.invoke({ projectId: READ_CTX.projectId }) as any;const content = JSON.parse(result.content[0].text);- expect(content.pages[0].seo_signals.low_engagement).toBe(true);- });-- it('marks good_landing_page when bounce_rate < 40 and avg_duration > 2', async () => {- mockGetTopPages.mockResolvedValue([makePage({ bounce_rate: 25, avg_duration: 3 })]);-- const server = makeServer() as any;- registerPagePerformanceTools(server, READ_CTX);- const result = await server.invoke({ projectId: READ_CTX.projectId }) as any;- const content = JSON.parse(result.content[0].text);-- expect(content.pages[0].seo_signals.good_landing_page).toBe(true);- expect(content.pages[0].seo_signals.high_bounce).toBe(false);- expect(content.pages[0].seo_signals.low_engagement).toBe(false);- });-- it('does not mark good_landing_page when bounce_rate is exactly 40', async () => {- mockGetTopPages.mockResolvedValue([makePage({ bounce_rate: 40, avg_duration: 3 })]);-- const server = makeServer() as any;- registerPagePerformanceTools(server, READ_CTX);- const result = await server.invoke({ projectId: READ_CTX.projectId }) as any;- const content = JSON.parse(result.content[0].text);-- expect(content.pages[0].seo_signals.good_landing_page).toBe(false);+ // The booleans were pure functions of these two columns, so the columns+ // are all the reader needs.+ expect(rowsOf(content)[0]).toMatchObject({+ bounce_rate: 80,+ avg_duration: 0.5,+ });});});@@ -123,7 +104,7 @@ describe('get_page_performance — sorting', () => {registerPagePerformanceTools(server, READ_CTX);const result = await server.invoke({ projectId: READ_CTX.projectId }) as any;const content = JSON.parse(result.content[0].text);- const paths = content.pages.map((p: any) => p.path);+ const paths = rowsOf(content).map((p) => p.path);expect(paths).toEqual(['/b', '/c', '/a']);});@@ -135,7 +116,7 @@ describe('get_page_performance — sorting', () => {registerPagePerformanceTools(server, READ_CTX);const result = await server.invoke({ projectId: READ_CTX.projectId, sortBy: 'bounce_rate', sortOrder: 'desc' }) as any;const content = JSON.parse(result.content[0].text);- const paths = content.pages.map((p: any) => p.path);+ const paths = rowsOf(content).map((p) => p.path);expect(paths).toEqual(['/b', '/c', '/a']);});@@ -147,7 +128,7 @@ describe('get_page_performance — sorting', () => {registerPagePerformanceTools(server, READ_CTX);const result = await server.invoke({ projectId: READ_CTX.projectId, sortBy: 'bounce_rate', sortOrder: 'asc' }) as any;const content = JSON.parse(result.content[0].text);- const paths = content.pages.map((p: any) => p.path);+ const paths = rowsOf(content).map((p) => p.path);expect(paths).toEqual(['/a', '/c', '/b']);});@@ -160,14 +141,15 @@ describe('get_page_performance — sorting', () => {const result = await server.invoke({ projectId: READ_CTX.projectId, limit: 2 }) as any;const content = JSON.parse(result.content[0].text);- expect(content.pages).toHaveLength(2);- expect(content.shown).toBe(2);- expect(content.total_pages).toBe(3);+ // 2 kept rows plus the "(other)" rollup for the third.+ expect(content.rows).toHaveLength(3);+ expect(content.total_rows).toBe(3);+ expect(content.rows[2][0]).toBe('(other: 1 pages)');});});describe('get_page_performance — metadata', () => {- it('returns total_pages and shown counts', async () => {+ it('reports the true total and rolls the tail up so sessions reconcile', async () => {const manyPages = Array.from({ length: 10 }, (_, i) =>makePage({ path: `/page-${i}` }),);@@ -178,8 +160,14 @@ describe('get_page_performance — metadata', () => {const result = await server.invoke({ projectId: READ_CTX.projectId, limit: 5 }) as any;const content = JSON.parse(result.content[0].text);- expect(content.total_pages).toBe(10);- expect(content.shown).toBe(5);+ expect(content.total_rows).toBe(10);+ // 5 kept rows plus the rollup.+ expect(content.rows).toHaveLength(6);+ const totalSessions = content.rows.reduce(+ (acc: number, row: unknown[]) => acc + (row[2] as number),+ 0,+ );+ expect(totalSessions).toBe(10 * 100);});it('returns empty pages array when no data', async () => {@@ -190,7 +178,7 @@ describe('get_page_performance — metadata', () => {const result = await server.invoke({ projectId: READ_CTX.projectId }) as any;const content = JSON.parse(result.content[0].text);- expect(content.pages).toEqual([]);- expect(content.total_pages).toBe(0);+ expect(content.rows).toEqual([]);+ expect(content.total_rows).toBe(0);});});diff --git a/packages/mcp/src/tools/analytics/page-performance.ts b/packages/mcp/src/tools/analytics/page-performance.tsindex 416a12bd1..1633300ca 100644--- a/packages/mcp/src/tools/analytics/page-performance.ts+++ b/packages/mcp/src/tools/analytics/page-performance.ts@@ -5,21 +5,37 @@ import type { McpAuthContext } from '../../auth';import {projectIdSchema,resolveDateRange,-+ resolveProjectId,+ table,withErrorHandling,zDateRange,- resolveProjectId+ zLimit,} from '../shared';const pagesService = new PagesService(ch);+const DEFAULT_PERFORMANCE_LIMIT = 25;+const MAX_PERFORMANCE_LIMIT = 500;++/**+ * Thresholds the tool used to stamp onto every row as a `seo_signals` object of+ * three booleans. They're pure functions of `bounce_rate` and `avg_duration`,+ * both of which are already columns — so we state the rule once instead of+ * re-deriving it 25 times at ~50 tokens a row.+ */+const SEO_THRESHOLDS = {+ high_bounce: 'bounce_rate > 70',+ low_engagement: 'avg_duration < 1 (minutes)',+ good_landing_page: 'bounce_rate < 40 AND avg_duration > 2',+} as const;+export function registerPagePerformanceTools(server: McpServer,context: McpAuthContext,) {server.tool('get_page_performance',- 'Get per-page performance metrics including bounce rate, avg session duration, sessions, and pageviews. Sort by bounce_rate to find high-bounce landing pages, or by avg_duration to find low-engagement content. Essential for SEO and CRO analysis.',+ `Get per-page performance metrics including bounce rate, avg session duration (minutes), sessions, and pageviews. Sort by bounce_rate to find high-bounce landing pages, or by avg_duration to find low-engagement content. Essential for SEO and CRO analysis. Returns the top ${DEFAULT_PERFORMANCE_LIMIT} pages; apply the returned \`seo_thresholds\` yourself to classify each row.`,{projectId: projectIdSchema(context),...zDateRange,@@ -37,14 +53,7 @@ export function registerPagePerformanceTools(.default('desc').optional().describe('Sort direction (default: desc)'),- limit: z- .number()- .int()- .min(1)- .max(500)- .default(50)- .optional()- .describe('Maximum number of pages to return (default 50)'),+ limit: zLimit(DEFAULT_PERFORMANCE_LIMIT, MAX_PERFORMANCE_LIMIT),},async ({ projectId: inputProjectId, startDate: sd, endDate: ed, search, sortBy, sortOrder, limit }) =>withErrorHandling(async () => {@@ -64,22 +73,18 @@ export function registerPagePerformanceTools(const col = sortBy ?? 'sessions';const dir = sortOrder === 'asc' ? 1 : -1;const sorted = [...pages].sort((a, b) => dir * ((a[col] ?? 0) < (b[col] ?? 0) ? -1 : 1));- const results = sorted.slice(0, limit ?? 50);-- // Annotate with SEO signals- const annotated = results.map((p) => ({- ...p,- seo_signals: {- high_bounce: p.bounce_rate > 70,- low_engagement: p.avg_duration < 1,- good_landing_page: p.bounce_rate < 40 && p.avg_duration > 2,- },- }));return {- total_pages: pages.length,- shown: annotated.length,- pages: annotated,+ seo_thresholds: SEO_THRESHOLDS,+ // Only sessions and pageviews roll up: bounce_rate and avg_duration+ // are ratios, and summing them would produce a confident lie.+ ...table(sorted, {+ limit: limit ?? DEFAULT_PERFORMANCE_LIMIT,+ columns: ['path', 'title', 'sessions', 'pageviews', 'bounce_rate', 'avg_duration'],+ sum: ['sessions', 'pageviews'],+ sortedBy: col,+ unit: 'pages',+ }),};}),);diff --git a/packages/mcp/src/tools/analytics/pages.ts b/packages/mcp/src/tools/analytics/pages.tsindex 4ca06c828..503a1eac9 100644--- a/packages/mcp/src/tools/analytics/pages.ts+++ b/packages/mcp/src/tools/analytics/pages.ts@@ -6,42 +6,62 @@ import type { McpAuthContext } from '../../auth';import {projectIdSchema,resolveDateRange,-+ resolveProjectId,+ table,withErrorHandling,zDateRange,- resolveProjectId+ zLimit,} from '../shared';-const DEFAULT_PAGE_LIMIT = 50;+const DEFAULT_PAGE_LIMIT = 25;const MAX_PAGE_LIMIT = 500;+type PageRow = {+ origin: string;+ path: string;+ sessions: number;+ pageviews: number;+ revenue?: number;+};++/**+ * Both page queries push their limit into ClickHouse, so we can't count the+ * tail to roll it up. Fetch one extra row instead: its presence is enough to+ * tell the model the list is capped, which stops it reporting "you have 25+ * pages" for a site with three thousand.+ */+function pageTable(rows: PageRow[], limit: number) {+ const hasRevenue = rows.some((row) => row.revenue !== undefined);+ return table(rows.slice(0, limit), {+ limit,+ columns: ['path', 'origin', 'sessions', 'pageviews', ...(hasRevenue ? (['revenue'] as const) : [])],+ sortedBy: 'sessions',+ unit: 'pages',+ moreAvailable: rows.length > limit,+ });+}+export function registerPageTools(server: McpServer, context: McpAuthContext) {server.tool('get_top_pages',- `Get the most visited pages ranked by page views, with unique visitor counts and other engagement metrics. Defaults to the top ${DEFAULT_PAGE_LIMIT} pages.`,+ `Get the most visited pages ranked by sessions, with pageview counts. Defaults to the top ${DEFAULT_PAGE_LIMIT} pages.`,{projectId: projectIdSchema(context),...zDateRange,- limit: z- .number()- .int()- .min(1)- .max(MAX_PAGE_LIMIT)- .optional()- .describe(- `Max pages to return (default ${DEFAULT_PAGE_LIMIT}, max ${MAX_PAGE_LIMIT}). Lower this if you're hitting response-size limits.`,- ),+ limit: zLimit(DEFAULT_PAGE_LIMIT, MAX_PAGE_LIMIT),},async ({ projectId: inputProjectId, startDate: sd, endDate: ed, limit }) =>withErrorHandling(async () => {const projectId = await resolveProjectId(context, inputProjectId);const { startDate, endDate } = resolveDateRange(sd, ed);- return getTopPagesCore({+ const take = limit ?? DEFAULT_PAGE_LIMIT;+ const rows = await getTopPagesCore({projectId,startDate,endDate,- limit: limit ?? DEFAULT_PAGE_LIMIT,+ limit: take + 1,});+ return pageTable(rows as PageRow[], take);}),);@@ -56,15 +76,7 @@ export function registerPageTools(server: McpServer, context: McpAuthContext) {.describe('"entry" for pages visitors land on first, "exit" for pages they leave from',),- limit: z- .number()- .int()- .min(1)- .max(MAX_PAGE_LIMIT)- .optional()- .describe(- `Max pages to return (default ${DEFAULT_PAGE_LIMIT}, max ${MAX_PAGE_LIMIT}). Lower this if you're hitting response-size limits.`,- ),+ limit: zLimit(DEFAULT_PAGE_LIMIT, MAX_PAGE_LIMIT),},async ({projectId: inputProjectId,@@ -76,13 +88,15 @@ export function registerPageTools(server: McpServer, context: McpAuthContext) {withErrorHandling(async () => {const projectId = await resolveProjectId(context, inputProjectId);const { startDate, endDate } = resolveDateRange(sd, ed);- return getEntryExitPagesCore({+ const take = limit ?? DEFAULT_PAGE_LIMIT;+ const rows = await getEntryExitPagesCore({projectId,startDate,endDate,mode,- limit: limit ?? DEFAULT_PAGE_LIMIT,+ limit: take + 1,});+ return { mode, ...pageTable(rows as PageRow[], take) };}),);}diff --git a/packages/mcp/src/tools/analytics/profiles.ts b/packages/mcp/src/tools/analytics/profiles.tsindex 9a24b436d..b5c198084 100644--- a/packages/mcp/src/tools/analytics/profiles.ts+++ b/packages/mcp/src/tools/analytics/profiles.ts@@ -3,13 +3,32 @@ import { findProfilesCore, getProfileSessionsCore, getProfileWithEvents } from 'import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';import { z } from 'zod';import type { McpAuthContext } from '../../auth';-import { profileUrl, sessionUrl } from '../dashboard-links';+import { profileUrl, dashboardBaseUrl } from '../dashboard-links';import {projectIdSchema,-+ resolveProjectId,+ table,withErrorHandling,- resolveProjectId+ zLimit,} from '../shared';+import { EVENT_COLUMNS_DEFAULT, SESSION_COLUMNS_DEFAULT } from './columns';++const DEFAULT_PROFILE_LIMIT = 20;+const MAX_PROFILE_LIMIT = 100;+const DEFAULT_EVENT_LIMIT = 20;+const DEFAULT_SESSION_LIMIT = 20;++// findProfilesCore returns the raw ClickHouse row, which is snake_case —+// unlike getGroupMemberProfiles, which returns the camelCase service shape.+const PROFILE_COLUMNS = [+ 'id',+ 'first_name',+ 'last_name',+ 'email',+ 'created_at',+ 'last_seen_at',+ 'is_external',+] as const;export function registerProfileTools(server: McpServer,@@ -17,7 +36,7 @@ export function registerProfileTools() {server.tool('find_profiles',- 'Search and filter user profiles. Supports filtering by name, email, location, inactivity, session count, and whether they performed a specific event. Defaults to the 20 most recently created profiles.',+ `Search and filter user profiles. Supports filtering by name, email, location, inactivity, session count, and whether they performed a specific event. Defaults to the ${DEFAULT_PROFILE_LIMIT} most recently created profiles. Build a dashboard link for any row by substituting its \`id\` into the returned \`profile_url_template\`.`,{projectId: projectIdSchema(context),name: z@@ -63,22 +82,28 @@ export function registerProfileTools(.default('desc').optional().describe('Sort direction for created_at (default: desc = newest first)'),- limit: z- .number()- .min(1)- .max(100)- .default(20)- .optional()- .describe('Maximum number of profiles to return (1-100, default 20)'),+ limit: zLimit(DEFAULT_PROFILE_LIMIT, MAX_PROFILE_LIMIT),},async ({ projectId: inputProjectId, ...input }) =>withErrorHandling(async () => {const projectId = await resolveProjectId(context, inputProjectId);- const profiles = await findProfilesCore({ projectId, ...input });- return profiles.map((p) => ({- ...p,- dashboard_url: profileUrl(context.organizationId, projectId, p.id),- }));+ const take = input.limit ?? DEFAULT_PROFILE_LIMIT;+ const profiles = await findProfilesCore({+ ...input,+ projectId,+ limit: take + 1,+ });+ return {+ // One template instead of a ~90-character absolute URL on every row.+ profile_url_template: `${dashboardBaseUrl()}/${context.organizationId}/${projectId}/profiles/{id}`,+ ...table(profiles.slice(0, take), {+ limit: take,+ columns: PROFILE_COLUMNS,+ sortedBy: 'created_at',+ unit: 'profiles',+ moreAvailable: profiles.length > take,+ }),+ };}),);@@ -88,54 +113,53 @@ export function registerProfileTools({projectId: projectIdSchema(context),profileId: z.string().describe('The profile ID to look up'),- eventLimit: z- .number()- .min(1)- .max(100)- .default(20)- .optional()- .describe('Number of recent events to include (1-100, default 20)'),+ eventLimit: zLimit(DEFAULT_EVENT_LIMIT, 100),},async ({ projectId: inputProjectId, profileId, eventLimit }) =>withErrorHandling(async () => {const projectId = await resolveProjectId(context, inputProjectId);- const result = await getProfileWithEvents(projectId, profileId, eventLimit);+ const take = eventLimit ?? DEFAULT_EVENT_LIMIT;+ const result = await getProfileWithEvents(projectId, profileId, take);if (!result.profile) {return { error: 'Profile not found', profileId };}return {- ...result,+ profile: result.profile,dashboard_url: profileUrl(context.organizationId, projectId, profileId),+ recent_events: table(result.recent_events, {+ limit: take,+ columns: EVENT_COLUMNS_DEFAULT,+ sortedBy: 'created_at desc',+ unit: 'events',+ }),};}),);server.tool('get_profile_sessions',- 'Get all sessions for a specific user profile, ordered by most recent first. Each session includes duration, entry/exit pages, device info, and referrer.',+ 'Get sessions for a specific user profile, ordered by most recent first. Each session includes duration, entry/exit pages, device info, and referrer.',{projectId: projectIdSchema(context),profileId: z.string().describe('The profile ID to fetch sessions for'),- limit: z- .number()- .min(1)- .max(100)- .default(20)- .optional()- .describe('Maximum number of sessions to return (1-100, default 20)'),+ limit: zLimit(DEFAULT_SESSION_LIMIT, 100),},async ({ projectId: inputProjectId, profileId, limit }) =>withErrorHandling(async () => {const projectId = await resolveProjectId(context, inputProjectId);- const sessions = await getProfileSessionsCore(projectId, profileId, limit);+ const take = limit ?? DEFAULT_SESSION_LIMIT;+ const sessions = await getProfileSessionsCore(projectId, profileId, take + 1);return {profileId,dashboard_url: profileUrl(context.organizationId, projectId, profileId),- session_count: sessions.length,- sessions: sessions.map((s) => ({- ...s,- dashboard_url: sessionUrl(context.organizationId, projectId, s.id),- })),+ session_url_template: `${dashboardBaseUrl()}/${context.organizationId}/${projectId}/sessions/{id}`,+ ...table(sessions.slice(0, take), {+ limit: take,+ columns: SESSION_COLUMNS_DEFAULT,+ sortedBy: 'created_at desc',+ unit: 'sessions',+ moreAvailable: sessions.length > take,+ }),};}),);diff --git a/packages/mcp/src/tools/analytics/property-values.ts b/packages/mcp/src/tools/analytics/property-values.tsindex c0f2ce868..6fa8f2143 100644--- a/packages/mcp/src/tools/analytics/property-values.ts+++ b/packages/mcp/src/tools/analytics/property-values.ts@@ -4,26 +4,71 @@ import { z } from 'zod';import type { McpAuthContext } from '../../auth';import {projectIdSchema,-+ resolveProjectId,withErrorHandling,- resolveProjectId+ zLimit,} from '../shared';+const DEFAULT_PROPERTY_LIMIT = 50;+const MAX_PROPERTY_LIMIT = 500;+const DEFAULT_VALUE_LIMIT = 50;+const MAX_VALUE_LIMIT = 500;++/**+ * Collapse the raw property-key rows into a discovery list.+ *+ * The raw rows are ordered alphabetically and capped at 500, which is the worst+ * possible shape for this: a single property with dynamic sub-paths (`__query`,+ * `data`) explodes into hundreds of `__query.<uuid>` rows that sort first and+ * push real properties like `country` off the end. Collapsing to the root+ * segment and ranking by how many sub-keys fall under it turns 500 near-useless+ * rows into a few dozen useful ones.+ *+ * The in-app chat agent solves the same problem in+ * `apps/api/src/agents/tools/helpers.ts`; kept as a local copy rather than a+ * shared abstraction since the two consumers may want to diverge.+ */+function compactPropertyKeys(+ rows: Array<{ property_key: string }>,+ max: number,+): { properties: string[]; total: number; note?: string } {+ const counts = new Map<string, number>();+ for (const row of rows) {+ const dot = row.property_key.indexOf('.');+ const root = dot >= 0 ? row.property_key.slice(0, dot) : row.property_key;+ counts.set(root, (counts.get(root) ?? 0) + 1);+ }++ const sorted = Array.from(counts.entries())+ .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))+ .map(([key]) => key);++ if (sorted.length <= max) {+ return { properties: sorted, total: sorted.length };+ }+ return {+ properties: sorted.slice(0, max),+ total: sorted.length,+ note: `Showing the ${max} most prominent of ${sorted.length} property roots. Raise \`limit\` to see the rest.`,+ };+}+export function registerPropertyValueTools(server: McpServer,context: McpAuthContext,) {server.tool('list_event_properties',- 'List fields available for filtering or breaking down events. Returns `columns` (top-level event columns like `path`, `country`, `device` — use the bare name in filters) and `properties` (custom JSON keys — use prefixed as `properties.<key>` in filters). Use this to discover what data is available before filtering or breaking down.',+ 'List fields available for filtering or breaking down events. Returns `columns` (top-level event columns like `path`, `country`, `device` — use the bare name in filters) and `properties` (custom JSON keys — use prefixed as `properties.<key>` in filters). Dotted sub-keys are rolled up to their root and ranked by prominence, so `properties.__query.utm_source` appears as `__query`; you can still filter on the exact full key. Use this to discover what data is available before filtering or breaking down.',{projectId: projectIdSchema(context),eventName: z.string().optional().describe('Filter to a specific event name. Omit to list properties across all events.'),+ limit: zLimit(DEFAULT_PROPERTY_LIMIT, MAX_PROPERTY_LIMIT),},- async ({ projectId: inputProjectId, eventName }) =>+ async ({ projectId: inputProjectId, eventName, limit }) =>withErrorHandling(async () => {const projectId = await resolveProjectId(context, inputProjectId);// GROUP BY rather than DISTINCT so the epv_keys projection can serve@@ -47,13 +92,17 @@ export function registerPropertyValueTools(}const rows = await builder.execute();- return { columns: EVENT_COLUMNS, properties: rows };+ return {+ ...(eventName ? { event_name: eventName } : {}),+ columns: EVENT_COLUMNS,+ ...compactPropertyKeys(rows, limit ?? DEFAULT_PROPERTY_LIMIT),+ };}),);server.tool('get_event_property_values',- 'Get all distinct values for a specific event property. Use this to understand what values exist before filtering (e.g. what plans exist in "plan" property, what countries, what status values).',+ `Get the distinct values seen for a specific event property, most recent first. Use this to understand what values exist before filtering (e.g. what plans exist in "plan" property, what countries, what status values). Returns up to ${DEFAULT_VALUE_LIMIT} distinct values by default.`,{projectId: projectIdSchema(context),eventName: z@@ -62,10 +111,15 @@ export function registerPropertyValueTools(propertyKey: z.string().describe('The property key to get values for (e.g. "plan", "country", "status")'),+ limit: zLimit(DEFAULT_VALUE_LIMIT, MAX_VALUE_LIMIT),},- async ({ projectId: inputProjectId, eventName, propertyKey }) =>+ async ({ projectId: inputProjectId, eventName, propertyKey, limit }) =>withErrorHandling(async () => {const projectId = await resolveProjectId(context, inputProjectId);+ const take = limit ?? DEFAULT_VALUE_LIMIT;+ // The MV holds one row per (property, value, day), so the same value+ // recurs across the window — dedupe before counting against the limit,+ // otherwise a single stable value can fill the whole response.const rows = await clix(ch).select<{ value: string }>(['property_value as value']).from(TABLE_NAMES.event_property_values_mv)@@ -73,13 +127,27 @@ export function registerPropertyValueTools(.where('name', '=', eventName).where('property_key', '=', propertyKey).orderBy('created_at', 'DESC')- .limit(200)+ .limit(2000).execute();+ const distinct: string[] = [];+ const seen = new Set<string>();+ for (const row of rows) {+ if (seen.has(row.value)) continue;+ seen.add(row.value);+ distinct.push(row.value);+ }+return {event: eventName,property: propertyKey,- values: rows.map((r) => r.value),+ values: distinct.slice(0, take),+ total_distinct: distinct.length,+ ...(distinct.length > take+ ? {+ note: `Showing ${take} of ${distinct.length} distinct values. This property is high-cardinality — it is a poor breakdown dimension. Raise \`limit\` if you need more.`,+ }+ : {}),};}),);diff --git a/packages/mcp/src/tools/analytics/reports.ts b/packages/mcp/src/tools/analytics/reports.tsindex 65739d31c..3b23238b6 100644--- a/packages/mcp/src/tools/analytics/reports.ts+++ b/packages/mcp/src/tools/analytics/reports.ts@@ -11,7 +11,20 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';import { z } from 'zod';import type { McpAuthContext } from '../../auth';import { dashboardBaseUrl } from '../dashboard-links';-import { projectIdSchema, resolveProjectId, withErrorHandling } from '../shared';+import {+ projectIdSchema,+ resolveProjectId,+ table,+ withErrorHandling,+ zLimit,+} from '../shared';++const DEFAULT_SERIES_LIMIT = 25;+const MAX_SERIES_LIMIT = 200;+/** How many series get their full per-date values in the pivoted `data` block. */+const DEFAULT_PLOTTED_SERIES = 5;+const MAX_PLOTTED_SERIES = 25;+const MAX_DATA_POINTS = 180;function reportUrl(organizationId: string, projectId: string, reportId: string) {return `${dashboardBaseUrl()}/${organizationId}/${projectId}/reports/${reportId}`;@@ -21,6 +34,94 @@ function dashboardUrl(organizationId: string, projectId: string, dashboardId: streturn `${dashboardBaseUrl()}/${organizationId}/${projectId}/dashboards/${dashboardId}`;}+type ChartSeries = {+ id: string;+ names: string[];+ metrics: { sum: number; average: number; min: number; max: number; count?: number };+ data: Array<{ date: string; count: number }>;+};++/**+ * Reshape a chart result into something a reader can hold in their head.+ *+ * The raw `FinalChart` is one object per point per series: a breakdown report+ * with 50 series over 90 days is 4,500 `{date, count, previous}` objects — a+ * few hundred kilobytes to describe a picture. Two structures replace it:+ *+ * - a `series` table, one row per series with its summary metrics, so nothing+ * is silently dropped from the ranking; and+ * - a `data` block pivoted to `date × series`, covering only the top few+ * series, which is the densest honest form of a multi-series time chart.+ */+function shapeChart(+ chart: { series: ChartSeries[]; metrics: unknown },+ options: { seriesLimit: number; plotSeries: number },+) {+ const { seriesLimit, plotSeries } = options;+ const summaries = chart.series.map((serie) => ({+ name: serie.names.join(' / '),+ sum: serie.metrics.sum,+ average: serie.metrics.average,+ min: serie.metrics.min,+ max: serie.metrics.max,+ }));++ const plotted = chart.series.slice(0, plotSeries);++ // The engine zero-fills every series onto the same date grid, but take the+ // union anyway so a short series can't silently truncate the axis.+ const dates: string[] = [];+ const seenDates = new Set<string>();+ for (const serie of plotted) {+ for (const point of serie.data) {+ if (seenDates.has(point.date)) continue;+ seenDates.add(point.date);+ dates.push(point.date);+ }+ }+ dates.sort();++ const trimmedDates =+ dates.length > MAX_DATA_POINTS ? dates.slice(dates.length - MAX_DATA_POINTS) : dates;++ const byDate = plotted.map((serie) => {+ const lookup = new Map(serie.data.map((point) => [point.date, point.count]));+ return lookup;+ });++ return {+ metrics: chart.metrics,+ series: table(summaries, {+ limit: seriesLimit,+ columns: ['name', 'sum', 'average', 'min', 'max'],+ sum: ['sum'],+ sortedBy: 'sum',+ unit: 'series',+ }),+ data: {+ columns: ['date', ...plotted.map((serie) => serie.names.join(' / '))],+ rows: trimmedDates.map((date) => [+ date,+ ...byDate.map((lookup) => lookup.get(date) ?? 0),+ ]),+ ...(chart.series.length > plotted.length || dates.length > trimmedDates.length+ ? {+ note: [+ chart.series.length > plotted.length+ ? `Per-date values shown for the top ${plotted.length} of ${chart.series.length} series (raise \`plotSeries\`); every series still appears in the \`series\` summary table.`+ : null,+ dates.length > trimmedDates.length+ ? `Showing the most recent ${trimmedDates.length} of ${dates.length} intervals.`+ : null,+ ]+ .filter(Boolean)+ .join(' '),+ }+ : {}),+ },+ };+}+export function registerReportTools(server: McpServer,context: McpAuthContext,@@ -48,7 +149,7 @@ export function registerReportTools(server.tool('list_reports',- 'List all reports in a dashboard. Returns report IDs, names, chart types, and the events/metrics they track. Use get_report_data to execute a report and retrieve its actual data.',+ 'List all reports in a dashboard. Returns report IDs, names, chart types, and the events/metrics they track. Use get_report_data to execute a report and retrieve its actual data. Build a link for any row by substituting its `id` into the returned `report_url_template`.',{projectId: projectIdSchema(context),dashboardId: z.string().describe('The dashboard ID to list reports for'),@@ -60,7 +161,7 @@ export function registerReportTools(if (reports.some((r) => r.projectId !== projectId)) {throw new Error('Dashboard does not belong to this project');}- return reports.map((r) => ({+ const rows = reports.map((r) => ({id: r.id,name: r.name,chartType: r.chartType,@@ -79,22 +180,63 @@ export function registerReportTools(},),breakdowns: r.breakdowns,- dashboard_url: reportUrl(context.organizationId, projectId, r.id),}));+ return {+ report_url_template: `${dashboardBaseUrl()}/${context.organizationId}/${projectId}/reports/{id}`,+ ...table(rows, {+ limit: MAX_SERIES_LIMIT,+ columns: ['id', 'name', 'chartType', 'range', 'interval', 'metric', 'series', 'breakdowns'],+ unit: 'reports',+ }),+ };}),);server.tool('get_report_data',- 'Execute a saved report and return its data. Works for all chart types: linear/bar/area/pie/map (time-series or breakdowns), metric (aggregate numbers), and funnel (conversion steps). Pass the report ID from list_reports.',+ 'Execute a saved report and return its data. Works for all chart types: linear/bar/area/pie/map (time-series or breakdowns), metric (aggregate numbers), and funnel (conversion steps). Time-series results come back as a `series` summary table plus a `data` block pivoted to date × series for the highest-volume series. Pass the report ID from list_reports.',{projectId: projectIdSchema(context),reportId: z.string().describe('The report ID to execute'),+ seriesLimit: zLimit(DEFAULT_SERIES_LIMIT, MAX_SERIES_LIMIT),+ plotSeries: z+ .number()+ .int()+ .min(1)+ .max(MAX_PLOTTED_SERIES)+ .optional()+ .describe(+ `How many of the top series get per-date values in the \`data\` block (default ${DEFAULT_PLOTTED_SERIES}, max ${MAX_PLOTTED_SERIES}). Every series appears in the summary table regardless.`,+ ),},- async ({ projectId: inputProjectId, reportId }) =>+ async ({ projectId: inputProjectId, reportId, seriesLimit, plotSeries }) =>withErrorHandling(async () => {const projectId = await resolveProjectId(context, inputProjectId);- return runReport({ organizationId: context.organizationId, projectId, reportId });+ const result = await runReport({+ organizationId: context.organizationId,+ projectId,+ reportId,+ });++ if ('error' in result) {+ return result;+ }++ // Funnel and metric results are already small and have their own shape;+ // only the multi-series charts need reshaping.+ const chart = result.data as { series?: ChartSeries[]; metrics?: unknown };+ if (result.chartType === 'funnel' || result.chartType === 'metric' || !Array.isArray(chart.series)) {+ return result;+ }++ const { data: _raw, ...meta } = result;+ return {+ ...meta,+ ...shapeChart(chart as { series: ChartSeries[]; metrics: unknown }, {+ seriesLimit: seriesLimit ?? DEFAULT_SERIES_LIMIT,+ plotSeries: plotSeries ?? DEFAULT_PLOTTED_SERIES,+ }),+ };}),);}@@ -105,8 +247,10 @@ export function registerReportTools(* - metric → AggregateChartEngine.execute* - others → ChartEngine.execute*- * Exported so the in-app chat (apps/api/src/chat/tools/base.ts) can reuse the- * dispatch without going through MCP.+ * Exported so the in-app chat (apps/api/src/agents/tools/base.ts) can reuse the+ * dispatch without going through MCP. Deliberately returns the raw engine+ * output — the MCP tool reshapes it for LLM consumption, the chat renderer+ * needs the full chart.*/export async function runReport(input: {organizationId: string;diff --git a/packages/mcp/src/tools/analytics/sessions.ts b/packages/mcp/src/tools/analytics/sessions.tsindex 4b1b40e1c..e13b5d22e 100644--- a/packages/mcp/src/tools/analytics/sessions.ts+++ b/packages/mcp/src/tools/analytics/sessions.ts@@ -2,22 +2,31 @@ import { querySessionsCore } from '@openpanel/db';import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';import { z } from 'zod';import type { McpAuthContext } from '../../auth';-import { sessionUrl } from '../dashboard-links';+import { dashboardBaseUrl } from '../dashboard-links';+import {+ SESSION_COLUMNS_DEFAULT,+ SESSION_COLUMNS_EXTRA,+} from './columns';import {projectIdSchema,-+ resolveProjectId,+ table,withErrorHandling,zDateRange,- resolveProjectId+ zLimit,} from '../shared';+const DEFAULT_SESSION_LIMIT = 20;+const MAX_SESSION_LIMIT = 100;++export function registerSessionTools(server: McpServer,context: McpAuthContext,) {server.tool('query_sessions',- 'Query user sessions with optional filters. Each session represents a single visit with duration, entry/exit pages, bounce status, and attribution data. Defaults to the last 30 days.',+ `Query user sessions with optional filters. Each session represents a single visit with duration, entry/exit pages, bounce status, and attribution data. Defaults to the last 30 days and ${DEFAULT_SESSION_LIMIT} sessions. Build a dashboard link for any row by substituting its \`id\` into the returned \`session_url_template\`.`,{projectId: projectIdSchema(context),...zDateRange,@@ -42,22 +51,35 @@ export function registerSessionTools(.string().optional().describe('Filter sessions for a specific user profile ID'),- limit: z- .number()- .min(1)- .max(100)- .default(20)+ fields: z+ .array(z.enum(SESSION_COLUMNS_EXTRA)).optional()- .describe('Maximum number of sessions to return (1-100, default 20)'),+ .describe(+ 'Extra columns to include beyond the default set. Only request what you need — every extra column costs rows of output.',+ ),+ limit: zLimit(DEFAULT_SESSION_LIMIT, MAX_SESSION_LIMIT),},- async ({ projectId: inputProjectId, ...input }) =>+ async ({ projectId: inputProjectId, fields, ...input }) =>withErrorHandling(async () => {const projectId = await resolveProjectId(context, inputProjectId);- const sessions = await querySessionsCore({ projectId, ...input });- return sessions.map((s) => ({- ...s,- dashboard_url: sessionUrl(context.organizationId, projectId, s.id),- }));+ const take = input.limit ?? DEFAULT_SESSION_LIMIT;+ const sessions = await querySessionsCore({+ ...input,+ projectId,+ limit: take + 1,+ });+ return {+ // One template beats stamping a ~90-character absolute URL onto every+ // row — the model can substitute `id` itself.+ session_url_template: `${dashboardBaseUrl()}/${context.organizationId}/${projectId}/sessions/{id}`,+ ...table(sessions.slice(0, take), {+ limit: take,+ columns: [...SESSION_COLUMNS_DEFAULT, ...(fields ?? [])],+ sortedBy: 'created_at desc',+ unit: 'sessions',+ moreAvailable: sessions.length > take,+ }),+ };}),);}diff --git a/packages/mcp/src/tools/analytics/traffic.ts b/packages/mcp/src/tools/analytics/traffic.tsindex 1c9fa2147..1c4765817 100644--- a/packages/mcp/src/tools/analytics/traffic.ts+++ b/packages/mcp/src/tools/analytics/traffic.ts@@ -5,19 +5,59 @@ import type { McpAuthContext } from '../../auth';import {projectIdSchema,resolveDateRange,-+ resolveProjectId,+ table,withErrorHandling,zDateRange,- resolveProjectId+ zLimit,} from '../shared';+const DEFAULT_BREAKDOWN_LIMIT = 25;+const MAX_BREAKDOWN_LIMIT = 500;++/** Rows come back as `{ prefix?, name, sessions, pageviews, revenue? }`. */+type BreakdownRow = {+ prefix?: string;+ name: string | null;+ sessions: number;+ pageviews: number;+ revenue?: number;+};++/**+ * Every breakdown here is a ranked long-tail distribution: on openpanel.dev+ * `referrer_name` returns 740 rows where the top 10 are 91% of sessions and 596+ * rows have two sessions or fewer. Returning the whole tail costs ~23k tokens to+ * say nothing, so we keep the head and roll the rest into one `(other)` row —+ * which keeps the totals correct, unlike a plain truncation.+ */+function breakdownTable(rows: BreakdownRow[], limit: number, unit: string) {+ const hasPrefix = rows.some((row) => row.prefix !== undefined);+ const hasRevenue = rows.some((row) => row.revenue !== undefined);+ const columns: (keyof BreakdownRow & string)[] = [+ 'name',+ ...(hasPrefix ? (['prefix'] as const) : []),+ 'sessions',+ 'pageviews',+ ...(hasRevenue ? (['revenue'] as const) : []),+ ];++ return table(rows, {+ limit,+ columns,+ sum: ['sessions', 'pageviews', ...(hasRevenue ? (['revenue'] as const) : [])],+ sortedBy: 'sessions',+ unit,+ });+}+export function registerTrafficTools(server: McpServer,context: McpAuthContext,) {server.tool('get_top_referrers',- 'Get the top traffic sources driving visitors to the site, broken down by referrer name and type.',+ `Get the top traffic sources driving visitors to the site, broken down by referrer name and type. Returns the top ${DEFAULT_BREAKDOWN_LIMIT} sources by sessions; the long tail is aggregated into a trailing "(other)" row so totals still add up. A null name means direct traffic.`,{projectId: projectIdSchema(context),...zDateRange,@@ -28,23 +68,29 @@ export function registerTrafficTools(.describe('How to group referrers: by name (Google, Twitter), type (search, social), full URL, or UTM params',),+ limit: zLimit(DEFAULT_BREAKDOWN_LIMIT, MAX_BREAKDOWN_LIMIT),},- async ({ projectId: inputProjectId, startDate: sd, endDate: ed, breakdown }) =>+ async ({ projectId: inputProjectId, startDate: sd, endDate: ed, breakdown, limit }) =>withErrorHandling(async () => {const projectId = await resolveProjectId(context, inputProjectId);const { startDate, endDate } = resolveDateRange(sd, ed);- return getTrafficBreakdownCore({+ const rows = await getTrafficBreakdownCore({projectId,startDate,endDate,column: (breakdown ?? 'referrer_name') as TrafficColumn,});+ return breakdownTable(+ rows as BreakdownRow[],+ limit ?? DEFAULT_BREAKDOWN_LIMIT,+ 'sources',+ );}),);server.tool('get_country_breakdown',- 'Get visitor counts broken down by country, region, or city.',+ `Get visitor counts broken down by country, region, or city. Returns the top ${DEFAULT_BREAKDOWN_LIMIT} by sessions with the tail aggregated into a trailing "(other)" row.`,{projectId: projectIdSchema(context),...zDateRange,@@ -53,17 +99,23 @@ export function registerTrafficTools(.default('country').optional().describe('Geographic grouping level (default: country)'),+ limit: zLimit(DEFAULT_BREAKDOWN_LIMIT, MAX_BREAKDOWN_LIMIT),},- async ({ projectId: inputProjectId, startDate: sd, endDate: ed, breakdown }) =>+ async ({ projectId: inputProjectId, startDate: sd, endDate: ed, breakdown, limit }) =>withErrorHandling(async () => {const projectId = await resolveProjectId(context, inputProjectId);const { startDate, endDate } = resolveDateRange(sd, ed);- return getTrafficBreakdownCore({+ const rows = await getTrafficBreakdownCore({projectId,startDate,endDate,column: (breakdown ?? 'country') as TrafficColumn,});+ return breakdownTable(+ rows as BreakdownRow[],+ limit ?? DEFAULT_BREAKDOWN_LIMIT,+ 'locations',+ );}),);@@ -80,17 +132,23 @@ export function registerTrafficTools(.describe('Device dimension: "device" (desktop/mobile/tablet), "browser" (Chrome/Firefox), or "os" (Windows/macOS)',),+ limit: zLimit(DEFAULT_BREAKDOWN_LIMIT, MAX_BREAKDOWN_LIMIT),},- async ({ projectId: inputProjectId, startDate: sd, endDate: ed, breakdown }) =>+ async ({ projectId: inputProjectId, startDate: sd, endDate: ed, breakdown, limit }) =>withErrorHandling(async () => {const projectId = await resolveProjectId(context, inputProjectId);const { startDate, endDate } = resolveDateRange(sd, ed);- return getTrafficBreakdownCore({+ const rows = await getTrafficBreakdownCore({projectId,startDate,endDate,column: (breakdown ?? 'device') as TrafficColumn,});+ return breakdownTable(+ rows as BreakdownRow[],+ limit ?? DEFAULT_BREAKDOWN_LIMIT,+ 'devices',+ );}),);}diff --git a/packages/mcp/src/tools/analytics/user-flow.ts b/packages/mcp/src/tools/analytics/user-flow.tsindex 48e9035ea..36b179e53 100644--- a/packages/mcp/src/tools/analytics/user-flow.ts+++ b/packages/mcp/src/tools/analytics/user-flow.ts@@ -6,19 +6,23 @@ import type { McpAuthContext } from '../../auth';import {projectIdSchema,resolveDateRange,-+ resolveProjectId,+ table,withErrorHandling,zDateRange,- resolveProjectId+ zLimit,} from '../shared';+const DEFAULT_FLOW_NODES = 60;+const MAX_FLOW_NODES = 500;+export function registerUserFlowTools(server: McpServer,context: McpAuthContext,) {server.tool('get_user_flow',- 'Visualize user navigation flows as a Sankey diagram. Shows what events/pages users visit in sequence. Use mode "after" to see what happens after an event, "before" to see what leads up to it, or "between" to map paths from one event to another.',+ 'Map user navigation flows as a graph of nodes and links (a Sankey diagram). Shows what events/pages users visit in sequence. Use mode "after" to see what happens after an event, "before" to see what leads up to it, or "between" to map paths from one event to another. Wide flows are trimmed to the highest-volume nodes — use `exclude`/`include` or fewer `steps` to focus the graph rather than raising the limit.',{projectId: projectIdSchema(context),...zDateRange,@@ -51,12 +55,50 @@ export function registerUserFlowTools(.array(z.string()).optional().describe('If set, only show these event names in the flow'),+ limit: zLimit(DEFAULT_FLOW_NODES, MAX_FLOW_NODES),},- async ({ projectId: inputProjectId, startDate: sd, endDate: ed, startEvent, endEvent, mode, steps, exclude, include }) =>+ async ({ projectId: inputProjectId, startDate: sd, endDate: ed, startEvent, endEvent, mode, steps, exclude, include, limit }) =>withErrorHandling(async () => {const projectId = await resolveProjectId(context, inputProjectId);const { startDate, endDate } = resolveDateRange(sd, ed);- return getUserFlowCore({ projectId, startDate, endDate, startEvent, endEvent, mode, steps, exclude, include });+ const take = limit ?? DEFAULT_FLOW_NODES;+ const flow = await getUserFlowCore({ projectId, startDate, endDate, startEvent, endEvent, mode, steps, exclude, include });++ // Trim to the highest-volume nodes, then drop links that would dangle —+ // a link pointing at a node we cut is worse than no link at all.+ const nodes = [...flow.nodes]+ .sort((a, b) => (b.value ?? 0) - (a.value ?? 0))+ .slice(0, take);+ const kept = new Set(nodes.map((node) => node.id));+ const links = flow.links.filter(+ (link) => kept.has(link.source) && kept.has(link.target),+ );++ return {+ mode: flow.mode,+ startEvent: flow.startEvent,+ endEvent: flow.endEvent,+ node_count: flow.node_count,+ link_count: flow.link_count,+ ...(flow.nodes.length > nodes.length+ ? {+ flow_note: `Trimmed to the ${nodes.length} highest-volume of ${flow.nodes.length} nodes; ${flow.links.length - links.length} links referencing dropped nodes were removed. Use \`include\`/\`exclude\` or fewer \`steps\` to focus the flow.`,+ }+ : {}),+ // nodeColor is a UI concern and carries no meaning for a reader.+ nodes: table(nodes, {+ limit: take,+ columns: ['id', 'label', 'step', 'value', 'percentage'],+ sortedBy: 'value',+ unit: 'nodes',+ }),+ links: table(links, {+ limit: MAX_FLOW_NODES * 4,+ columns: ['source', 'target', 'value'],+ sortedBy: 'value',+ unit: 'links',+ }),+ };}),);}diff --git a/packages/mcp/src/tools/gsc/cannibalization.ts b/packages/mcp/src/tools/gsc/cannibalization.tsindex a5c570fd1..a397b4d59 100644--- a/packages/mcp/src/tools/gsc/cannibalization.ts+++ b/packages/mcp/src/tools/gsc/cannibalization.ts@@ -1,14 +1,14 @@import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';import { getGscCannibalization } from '@openpanel/db';-import { z } from 'zod';import type { McpAuthContext } from '../../auth';import {projectIdSchema,resolveDateRange,-+ resolveProjectId,+ table,withErrorHandling,zDateRange,- resolveProjectId+ zLimit,} from '../shared';// Cap pages per query in the MCP response. The core function keeps the@@ -16,6 +16,12 @@ import {// response size for sites with heavy cannibalization (100KB+).const DEFAULT_PAGES_PER_QUERY = 5;const MAX_PAGES_PER_QUERY = 20;+const DEFAULT_QUERY_LIMIT = 25;+/** The core function already caps its own output at 50 queries. */+const MAX_QUERY_LIMIT = 50;++/** Column order for the nested per-page tuples, declared once for the response. */+const PAGE_COLUMNS = ['page', 'clicks', 'impressions', 'ctr', 'position'] as const;export function registerGscCannibalizationTools(server: McpServer,@@ -23,40 +29,48 @@ export function registerGscCannibalizationTools() {server.tool('gsc_get_cannibalization',- `Identify keyword cannibalization: search queries where multiple pages on your site compete against each other in Google. Returns queries where 2+ pages rank, sorted by total impressions (capped at 50 queries). Each query's pages list is truncated to the top ${DEFAULT_PAGES_PER_QUERY} by position. High cannibalization can hurt rankings.`,+ `Identify keyword cannibalization: search queries where multiple pages on your site compete against each other in Google. Returns queries where 2+ pages rank, sorted by total impressions. Each row's \`pages\` cell is a list of tuples in the order given by the top-level \`page_columns\`, capped at the top ${DEFAULT_PAGES_PER_QUERY} pages by position. High cannibalization can hurt rankings.`,{projectId: projectIdSchema(context),...zDateRange,- pagesPerQuery: z- .number()- .int()- .min(1)- .max(MAX_PAGES_PER_QUERY)- .optional()- .describe(- `Max pages to include per query (default ${DEFAULT_PAGES_PER_QUERY}, max ${MAX_PAGES_PER_QUERY}). Each query can rank many pages; this trims the tail to keep the response small.`,- ),+ pagesPerQuery: zLimit(DEFAULT_PAGES_PER_QUERY, MAX_PAGES_PER_QUERY),+ limit: zLimit(DEFAULT_QUERY_LIMIT, MAX_QUERY_LIMIT),},async ({projectId: inputProjectId,startDate: sd,endDate: ed,pagesPerQuery,+ limit,}) =>withErrorHandling(async () => {const projectId = await resolveProjectId(context, inputProjectId);const { startDate, endDate } = resolveDateRange(sd, ed);- const cap = pagesPerQuery ?? DEFAULT_PAGES_PER_QUERY;+ const pageCap = pagesPerQuery ?? DEFAULT_PAGES_PER_QUERY;const rows = await getGscCannibalization(projectId, startDate, endDate);- return rows.map((row) => {- if (row.pages.length <= cap) return row;- return {- ...row,- pages: row.pages.slice(0, cap),- pagesTruncated: true,- totalPages: row.pages.length,- };- });++ // Positional tuples rather than page objects: the five keys are stated+ // once in `page_columns` instead of on every page of every query.+ const shaped = rows.map((row) => ({+ query: row.query,+ totalImpressions: row.totalImpressions,+ totalClicks: row.totalClicks,+ page_count: row.pages.length,+ pages: row.pages+ .slice(0, pageCap)+ .map((page) => PAGE_COLUMNS.map((column) => page[column])),+ }));++ return {+ page_columns: PAGE_COLUMNS,+ ...table(shaped, {+ limit: limit ?? DEFAULT_QUERY_LIMIT,+ columns: ['query', 'totalImpressions', 'totalClicks', 'page_count', 'pages'],+ sum: ['totalImpressions', 'totalClicks'],+ sortedBy: 'totalImpressions',+ unit: 'queries',+ }),+ };}));}diff --git a/packages/mcp/src/tools/gsc/overview.ts b/packages/mcp/src/tools/gsc/overview.tsindex 9fd74238f..ec2eed586 100644--- a/packages/mcp/src/tools/gsc/overview.ts+++ b/packages/mcp/src/tools/gsc/overview.ts@@ -5,19 +5,22 @@ import type { McpAuthContext } from '../../auth';import {projectIdSchema,resolveDateRange,-+ resolveProjectId,+ table,withErrorHandling,zDateRange,- resolveProjectId} from '../shared';+/** A daily series longer than this stops being readable and starts being noise. */+const MAX_SERIES_POINTS = 180;+export function registerGscOverviewTools(server: McpServer,context: McpAuthContext) {server.tool('gsc_get_overview',- 'Get Google Search Console performance over time: clicks, impressions, CTR, and average position. Requires GSC to be connected for the project.',+ 'Get Google Search Console performance over time: clicks, impressions, CTR, and average position, plus totals for the range. Requires GSC to be connected for the project.',{projectId: projectIdSchema(context),...zDateRange,@@ -26,12 +29,20 @@ export function registerGscOverviewTools(.default('day').optional().describe('Time interval for aggregation (default: day)'),+ includeSeries: z+ .boolean()+ .default(true)+ .optional()+ .describe(+ 'Set false to get only the summary totals and skip the per-interval series.',+ ),},async ({projectId: inputProjectId,startDate: sd,endDate: ed,interval,+ includeSeries,}) =>withErrorHandling(async () => {const projectId = await resolveProjectId(context, inputProjectId);@@ -42,25 +53,50 @@ export function registerGscOverviewTools(endDate,interval ?? 'day');+ const summary = {+ total_clicks: data.reduce((s, r) => s + r.clicks, 0),+ total_impressions: data.reduce((s, r) => s + r.impressions, 0),+ avg_ctr:+ data.length > 0+ ? Math.round(+ (data.reduce((s, r) => s + r.ctr, 0) / data.length) * 10_000+ ) / 100+ : 0,+ avg_position:+ data.length > 0+ ? Math.round(+ (data.reduce((s, r) => s + r.position, 0) / data.length) * 10+ ) / 10+ : 0,+ };++ if (includeSeries === false) {+ return { summary, startDate, endDate, interval: interval ?? 'day' };+ }++ // Keep the recent end of an over-long series — the summary above still+ // covers the whole range, so nothing is lost from the totals.+ const recent =+ data.length > MAX_SERIES_POINTS+ ? data.slice(data.length - MAX_SERIES_POINTS)+ : data;+return {- data,- summary: {- total_clicks: data.reduce((s, r) => s + r.clicks, 0),- total_impressions: data.reduce((s, r) => s + r.impressions, 0),- avg_ctr:- data.length > 0- ? Math.round(- (data.reduce((s, r) => s + r.ctr, 0) / data.length) * 10_000- ) / 100- : 0,- avg_position:- data.length > 0- ? Math.round(- (data.reduce((s, r) => s + r.position, 0) / data.length) *- 10- ) / 10- : 0,- },+ summary,+ startDate,+ endDate,+ interval: interval ?? 'day',+ ...(data.length > recent.length+ ? {+ series_note: `Showing the most recent ${recent.length} of ${data.length} intervals; \`summary\` still covers the full range. Use a coarser \`interval\` or a shorter range for full coverage.`,+ }+ : {}),+ series: table(recent, {+ limit: MAX_SERIES_POINTS,+ columns: ['date', 'clicks', 'impressions', 'ctr', 'position'],+ sortedBy: 'date',+ unit: 'intervals',+ }),};}));diff --git a/packages/mcp/src/tools/gsc/pages.ts b/packages/mcp/src/tools/gsc/pages.tsindex 0602e0d5e..5efe6aab2 100644--- a/packages/mcp/src/tools/gsc/pages.ts+++ b/packages/mcp/src/tools/gsc/pages.ts@@ -5,41 +5,57 @@ import type { McpAuthContext } from '../../auth';import {projectIdSchema,resolveDateRange,-+ resolveProjectId,+ table,withErrorHandling,zDateRange,- resolveProjectId+ zLimit,} from '../shared';+const DEFAULT_GSC_LIMIT = 25;+const MAX_GSC_LIMIT = 1000;+const MAX_TIMESERIES_POINTS = 180;+const DEFAULT_DETAIL_QUERIES = 25;++/**+ * `ctr` and `position` are averages — summing them across a rolled-up tail+ * would produce a confident lie, so only the two counts are additive.+ */+const GSC_ADDITIVE = ['clicks', 'impressions'] as const;+export function registerGscPageTools(server: McpServer,context: McpAuthContext,) {server.tool('gsc_get_top_pages',- 'Get the top-performing pages from Google Search Console, ranked by clicks. Includes impressions, CTR, and average position for each page.',+ `Get the top-performing pages from Google Search Console, ranked by clicks. Includes impressions, CTR, and average position for each page. Returns the top ${DEFAULT_GSC_LIMIT}; the tail is aggregated into a trailing "(other)" row for clicks and impressions.`,{projectId: projectIdSchema(context),...zDateRange,- limit: z- .number()- .min(1)- .max(1000)- .default(100)- .optional()- .describe('Maximum number of pages to return (1-1000, default 100)'),+ limit: zLimit(DEFAULT_GSC_LIMIT, MAX_GSC_LIMIT),},async ({ projectId: inputProjectId, startDate: sd, endDate: ed, limit }) =>withErrorHandling(async () => {const projectId = await resolveProjectId(context, inputProjectId);const { startDate, endDate } = resolveDateRange(sd, ed);- return getGscPages(projectId, startDate, endDate, limit ?? 100);+ const take = limit ?? DEFAULT_GSC_LIMIT;+ // Fetch the full ranked set (capped) so the tail can be rolled up+ // rather than silently cut — GSC totals are the whole point here.+ const pages = await getGscPages(projectId, startDate, endDate, MAX_GSC_LIMIT);+ return table(pages, {+ limit: take,+ columns: ['page', 'clicks', 'impressions', 'ctr', 'position'],+ sum: [...GSC_ADDITIVE],+ sortedBy: 'clicks',+ unit: 'pages',+ });}),);server.tool('gsc_get_page_details',- 'Get detailed Search Console performance for a specific page: time-series of clicks/impressions/CTR/position plus all queries that drive traffic to that page.',+ 'Get detailed Search Console performance for a specific page: a time-series of clicks/impressions/CTR/position plus the queries that drive traffic to that page.',{projectId: projectIdSchema(context),...zDateRange,@@ -47,12 +63,29 @@ export function registerGscPageTools(.string().url().describe('The full page URL to get details for (e.g. https://example.com/blog/post)'),+ limit: zLimit(DEFAULT_DETAIL_QUERIES, MAX_GSC_LIMIT),},- async ({ projectId: inputProjectId, startDate: sd, endDate: ed, page }) =>+ async ({ projectId: inputProjectId, startDate: sd, endDate: ed, page, limit }) =>withErrorHandling(async () => {const projectId = await resolveProjectId(context, inputProjectId);const { startDate, endDate } = resolveDateRange(sd, ed);- return getGscPageDetails(projectId, page, startDate, endDate);+ const details = await getGscPageDetails(projectId, page, startDate, endDate);+ return {+ page,+ timeseries: table(details.timeseries, {+ limit: MAX_TIMESERIES_POINTS,+ columns: ['date', 'clicks', 'impressions', 'ctr', 'position'],+ sortedBy: 'date',+ unit: 'days',+ }),+ queries: table(details.queries, {+ limit: limit ?? DEFAULT_DETAIL_QUERIES,+ columns: ['query', 'clicks', 'impressions', 'ctr', 'position'],+ sum: [...GSC_ADDITIVE],+ sortedBy: 'clicks',+ unit: 'queries',+ }),+ };}),);}diff --git a/packages/mcp/src/tools/gsc/queries.ts b/packages/mcp/src/tools/gsc/queries.tsindex 64a4e1713..979af3af3 100644--- a/packages/mcp/src/tools/gsc/queries.ts+++ b/packages/mcp/src/tools/gsc/queries.ts@@ -6,12 +6,23 @@ import type { McpAuthContext } from '../../auth';import {projectIdSchema,resolveDateRange,-+ resolveProjectId,+ table,withErrorHandling,zDateRange,- resolveProjectId+ zLimit,} from '../shared';+const DEFAULT_GSC_LIMIT = 25;+const MAX_GSC_LIMIT = 1000;+const MAX_TIMESERIES_POINTS = 180;+const DEFAULT_DETAIL_PAGES = 25;+const DEFAULT_OPPORTUNITY_LIMIT = 25;+const MAX_OPPORTUNITY_LIMIT = 200;++/** `ctr` and `position` are averages — only the counts can be summed. */+const GSC_ADDITIVE = ['clicks', 'impressions'] as const;+function computeOpportunities(queries: Array<{query: string;@@ -20,6 +31,7 @@ function computeOpportunities(ctr: number;position: number;}>,+ limit: number,): GscQueryOpportunity[] {const ctrBenchmarks: Record<string, number> = {'1': 0.28,@@ -68,7 +80,7 @@ function computeOpportunities(};}).sort((a, b) => b.opportunity_score - a.opportunity_score)- .slice(0, 50);+ .slice(0, limit);}export function registerGscQueryTools(@@ -77,29 +89,32 @@ export function registerGscQueryTools() {server.tool('gsc_get_top_queries',- 'Get the top search queries driving traffic from Google Search, ranked by clicks. Includes impressions, CTR, and average position for each query.',+ `Get the top search queries driving traffic from Google Search, ranked by clicks. Includes impressions, CTR, and average position for each query. Returns the top ${DEFAULT_GSC_LIMIT}; the tail is aggregated into a trailing "(other)" row for clicks and impressions.`,{projectId: projectIdSchema(context),...zDateRange,- limit: z- .number()- .min(1)- .max(1000)- .default(100)- .optional()- .describe('Maximum number of queries to return (1-1000, default 100)'),+ limit: zLimit(DEFAULT_GSC_LIMIT, MAX_GSC_LIMIT),},async ({ projectId: inputProjectId, startDate: sd, endDate: ed, limit }) =>withErrorHandling(async () => {const projectId = await resolveProjectId(context, inputProjectId);const { startDate, endDate } = resolveDateRange(sd, ed);- return getGscQueries(projectId, startDate, endDate, limit ?? 100);+ // Fetch the full ranked set (capped) so the tail can be rolled up+ // rather than silently cut.+ const queries = await getGscQueries(projectId, startDate, endDate, MAX_GSC_LIMIT);+ return table(queries, {+ limit: limit ?? DEFAULT_GSC_LIMIT,+ columns: ['query', 'clicks', 'impressions', 'ctr', 'position'],+ sum: [...GSC_ADDITIVE],+ sortedBy: 'clicks',+ unit: 'queries',+ });}),);server.tool('gsc_get_query_opportunities',- 'Identify low-hanging-fruit SEO opportunities: queries ranking on positions 4-20 with meaningful search volume where small improvements could yield significant traffic gains. Ranked by opportunity score.',+ `Identify low-hanging-fruit SEO opportunities: queries ranking on positions 4-20 with meaningful search volume where small improvements could yield significant traffic gains. Ranked by opportunity score. Returns the top ${DEFAULT_OPPORTUNITY_LIMIT}.`,{projectId: projectIdSchema(context),...zDateRange,@@ -111,39 +126,65 @@ export function registerGscQueryTools(.describe('Minimum impression threshold to filter out low-volume queries (default: 50)',),+ limit: zLimit(DEFAULT_OPPORTUNITY_LIMIT, MAX_OPPORTUNITY_LIMIT),},- async ({ projectId: inputProjectId, startDate: sd, endDate: ed, minImpressions }) =>+ async ({ projectId: inputProjectId, startDate: sd, endDate: ed, minImpressions, limit }) =>withErrorHandling(async () => {const projectId = await resolveProjectId(context, inputProjectId);const { startDate, endDate } = resolveDateRange(sd, ed);+ const take = limit ?? DEFAULT_OPPORTUNITY_LIMIT;const queries = await getGscQueries(projectId, startDate, endDate, 5000);const filtered = queries.filter((q) => q.impressions >= (minImpressions ?? 50),);- const opportunities = computeOpportunities(filtered);+ // Compute one past the limit so the table can flag that more exist.+ const opportunities = computeOpportunities(filtered, take + 1);return {- opportunities,total_analyzed: filtered.length,min_impressions: minImpressions ?? 50,+ ...table(opportunities.slice(0, take), {+ limit: take,+ columns: ['query', 'clicks', 'impressions', 'ctr', 'position', 'opportunity_score', 'reason'],+ sortedBy: 'opportunity_score',+ unit: 'opportunities',+ moreAvailable: opportunities.length > take,+ }),};}),);server.tool('gsc_get_query_details',- 'Get detailed Search Console data for a specific search query: time-series performance plus all pages that rank for that query.',+ 'Get detailed Search Console data for a specific search query: a time-series of performance plus the pages that rank for that query.',{projectId: projectIdSchema(context),...zDateRange,query: z.string().describe('The search query to get details for (e.g. "best analytics tools")'),+ limit: zLimit(DEFAULT_DETAIL_PAGES, MAX_GSC_LIMIT),},- async ({ projectId: inputProjectId, startDate: sd, endDate: ed, query }) =>+ async ({ projectId: inputProjectId, startDate: sd, endDate: ed, query, limit }) =>withErrorHandling(async () => {const projectId = await resolveProjectId(context, inputProjectId);const { startDate, endDate } = resolveDateRange(sd, ed);- return getGscQueryDetails(projectId, query, startDate, endDate);+ const details = await getGscQueryDetails(projectId, query, startDate, endDate);+ return {+ query,+ timeseries: table(details.timeseries, {+ limit: MAX_TIMESERIES_POINTS,+ columns: ['date', 'clicks', 'impressions', 'ctr', 'position'],+ sortedBy: 'date',+ unit: 'days',+ }),+ pages: table(details.pages, {+ limit: limit ?? DEFAULT_DETAIL_PAGES,+ columns: ['page', 'clicks', 'impressions', 'ctr', 'position'],+ sum: [...GSC_ADDITIVE],+ sortedBy: 'clicks',+ unit: 'pages',+ }),+ };}),);}diff --git a/packages/mcp/src/tools/shared.test.ts b/packages/mcp/src/tools/shared.test.tsindex 20c232dbd..6414b87a5 100644--- a/packages/mcp/src/tools/shared.test.ts+++ b/packages/mcp/src/tools/shared.test.ts@@ -1,7 +1,7 @@import { resolveClientProjectId } from '@openpanel/db';import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';import type { McpAuthContext } from '../auth';-import { resolveDateRange } from './shared';+import { MAX_RESPONSE_CHARS, resolveDateRange, table, toText } from './shared';const READ_CTX: McpAuthContext = {projectId: 'proj-abc',@@ -72,3 +72,116 @@ describe('resolveClientProjectId', () => {})).rejects.toThrow('projectId is required');});});++describe('table', () => {+ const rows = [+ { name: 'Google', sessions: 100, pageviews: 500, rate: 0.5 },+ { name: 'GitHub', sessions: 50, pageviews: 200, rate: 0.4 },+ { name: 'Reddit', sessions: 10, pageviews: 20, rate: 0.9 },+ { name: 'Hacker News', sessions: 1, pageviews: 2, rate: 0.1 },+ ];++ it('emits columns once and rows positionally', () => {+ const result = table(rows, { limit: 10 });+ expect(result.columns).toEqual(['name', 'sessions', 'pageviews', 'rate']);+ expect(result.rows[0]).toEqual(['Google', 100, 500, 0.5]);+ expect(result.total_rows).toBe(4);+ expect(result.note).toBeUndefined();+ });++ it('honours an explicit column order and drops unlisted fields', () => {+ const result = table(rows, { limit: 10, columns: ['sessions', 'name'] });+ expect(result.columns).toEqual(['sessions', 'name']);+ expect(result.rows[0]).toEqual([100, 'Google']);+ });++ it('rolls the tail into an (other) row that keeps totals reconcilable', () => {+ const result = table(rows, {+ limit: 2,+ sum: ['sessions', 'pageviews'],+ unit: 'sources',+ });+ // 2 kept rows + 1 rollup row+ expect(result.rows).toHaveLength(3);+ expect(result.total_rows).toBe(4);+ const other = result.rows[2] as unknown[];+ expect(other[0]).toBe('(other: 2 sources)');+ expect(other[1]).toBe(11); // 10 + 1 sessions+ expect(other[2]).toBe(22); // 20 + 2 pageviews+ // The head plus the rollup accounts for every session.+ const totalSessions = result.rows.reduce(+ (acc, row) => acc + (row[1] as number),+ 0+ );+ expect(totalSessions).toBe(161);+ });++ it('leaves non-additive columns null on the rollup row rather than summing them', () => {+ const result = table(rows, { limit: 2, sum: ['sessions'] });+ const other = result.rows[2] as unknown[];+ // `rate` is an average — summing it would be a confident lie.+ expect(other[3]).toBeNull();+ expect(other[2]).toBeNull(); // pageviews not declared additive either+ });++ it('notes the omission when no additive columns are declared', () => {+ const result = table(rows, { limit: 2, unit: 'sources' });+ expect(result.rows).toHaveLength(2);+ expect(result.note).toContain('The remaining 2 were omitted');+ });++ it('warns that a SQL-capped result is not the full set', () => {+ const result = table(rows, { limit: 4, unit: 'pages', moreAvailable: true });+ expect(result.rows).toHaveLength(4);+ expect(result.note).toContain('capped query');+ });++ it('handles an empty result without inventing columns', () => {+ const result = table([], { limit: 10 });+ expect(result.columns).toEqual([]);+ expect(result.rows).toEqual([]);+ expect(result.total_rows).toBe(0);+ });+});++describe('toText', () => {+ const parse = (data: unknown) =>+ JSON.parse(toText(data).content[0].text) as Record<string, unknown>;++ it('serializes compactly — no indentation', () => {+ const { text } = toText({ a: 1, b: [1, 2] }).content[0];+ expect(text).toBe('{"a":1,"b":[1,2]}');+ });++ it('shrinks an oversized table instead of returning it whole', () => {+ const rows = Array.from({ length: 5000 }, (_, i) => ({+ name: `source-number-${i}-with-a-fairly-long-label`,+ sessions: i,+ }));+ const oversized = table(rows, { limit: 5000 });+ const { text } = toText(oversized).content[0];+ expect(text.length).toBeLessThanOrEqual(MAX_RESPONSE_CHARS);+ const parsed = JSON.parse(text) as { rows: unknown[]; note: string };+ expect(parsed.rows.length).toBeLessThan(5000);+ expect(parsed.note).toContain('fit the response size limit');+ });++ it('shrinks a table nested inside a wrapper object', () => {+ const rows = Array.from({ length: 5000 }, (_, i) => ({+ path: `/some/quite/long/path/segment/${i}`,+ sessions: i,+ }));+ const parsed = parse({+ summary: { total: 5000 },+ pages: table(rows, { limit: 5000 }),+ }) as { summary: unknown; pages: { rows: unknown[] } };+ expect(parsed.summary).toEqual({ total: 5000 });+ expect(parsed.pages.rows.length).toBeLessThan(5000);+ });++ it('degrades to a explanatory error when nothing is shrinkable', () => {+ const parsed = parse({ blob: 'x'.repeat(MAX_RESPONSE_CHARS + 1) });+ expect(parsed.error).toBe('response_too_large');+ expect(parsed.message).toContain('Narrow the request');+ });+});diff --git a/packages/mcp/src/tools/shared.ts b/packages/mcp/src/tools/shared.tsindex e60c6049f..fc1e16bf9 100644--- a/packages/mcp/src/tools/shared.ts+++ b/packages/mcp/src/tools/shared.ts@@ -71,14 +71,224 @@ export function resolveDateRange(return { startDate: start, endDate: end };}+/**+ * Standard `limit` input for any tool that returns a list.+ *+ * Every list-returning tool must expose one of these. The default is what the+ * model gets when it doesn't think about size — which is almost always — so it+ * has to be an LLM-sized number, not a dashboard-sized one.+ */+export function zLimit(defaultLimit: number, max: number) {+ return z+ .number()+ .int()+ .min(1)+ .max(max)+ .optional()+ .describe(+ `Max rows to return (default ${defaultLimit}, max ${max}). Results are ranked, so the default covers the meaningful head of the distribution; only raise it if you specifically need the long tail.`+ );+}++/**+ * Ceiling on a single serialized tool response.+ *+ * ~24k characters is roughly 6.5k tokens. A tool result is one turn's worth of+ * evidence, not a data export — past this the model starts losing the thread of+ * the actual question. `toText` enforces it as a hard backstop so no tool can+ * blow up a client's context window regardless of what it returns.+ */+export const MAX_RESPONSE_CHARS = 24_000;++/**+ * A tabular result in columnar form.+ *+ * Row-of-objects JSON repeats every key on every row: 740 referrers cost 23k+ * tokens as pretty-printed objects and 234 as this. Column names are stated+ * once, values are positional, and it stays valid JSON so clients can still+ * parse it.+ */+export interface TableResult {+ columns: string[];+ rows: unknown[][];+ /** Rows matched before the limit was applied. */+ total_rows: number;+ /** Present only when rows were dropped or rolled up — explains what's missing. */+ note?: string;+}++function isTableResult(value: unknown): value is TableResult {+ if (value === null || typeof value !== 'object') return false;+ const candidate = value as Partial<TableResult>;+ return Array.isArray(candidate.columns) && Array.isArray(candidate.rows);+}++export interface TableOptions<T> {+ /** Rows to keep. The tail beyond this is dropped or rolled up. */+ limit: number;+ /**+ * Column order. Defaults to the keys of the first row — pass it explicitly+ * to drop noisy fields or pin the order.+ */+ columns?: readonly (keyof T & string)[];+ /**+ * Additive columns to total into a trailing `(other)` row, so the numbers+ * still reconcile after truncation.+ *+ * Deliberately explicit: summing a rate, a position or an average produces a+ * confidently wrong number, and there is no safe way to tell those apart from+ * a column name. Columns not listed here are left null on the rollup row.+ * Omit entirely to drop the tail with only a note.+ */+ sum?: readonly (keyof T & string)[];+ /** What the rows are ranked by, for the truncation note (e.g. "sessions"). */+ sortedBy?: string;+ /** Plural noun for the rollup label (e.g. "sources" → "(other: 715 sources)"). */+ unit?: string;+ /**+ * Set when the limit was pushed into SQL, so `rows` is already capped and the+ * true total is unknown. Without this the model reads a SQL-limited result as+ * the complete set and reports "you have 25 pages" for a site with 3000.+ */+ moreAvailable?: boolean;+}++/**+ * Turn an array of row objects into a compact columnar table, capped at+ * `limit` rows, with the remainder rolled up rather than silently dropped.+ *+ * The rollup row matters more than the size saving: without it the model reads+ * a truncated list as the whole picture and its percentages are wrong. With it,+ * the totals still add up and the model can see for itself that the tail is+ * negligible.+ */+export function table<T extends object>(+ rows: readonly T[],+ options: TableOptions<T>+): TableResult {+ const { limit, sum, sortedBy, unit = 'rows', moreAvailable } = options;+ const columns: (keyof T & string)[] = options.columns+ ? [...options.columns]+ : rows.length > 0+ ? (Object.keys(rows[0] as object) as (keyof T & string)[])+ : [];++ const head = rows.slice(0, limit);+ const tail = rows.slice(limit);+ const toRow = (row: T) => columns.map((column) => row[column] ?? null);+ const out: unknown[][] = head.map(toRow);++ const rankedBy = sortedBy ? ` by ${sortedBy}` : '';++ if (tail.length === 0) {+ return {+ columns,+ rows: out,+ total_rows: rows.length,+ ...(moreAvailable+ ? {+ note: `Showing the top ${head.length} ${unit}${rankedBy}. This is a capped query — more ${unit} exist beyond the limit, so do not read ${head.length} as the total. Raise \`limit\` or narrow the range to see the rest.`,+ }+ : {}),+ };+ }++ if (!sum || sum.length === 0) {+ return {+ columns,+ rows: out,+ total_rows: rows.length,+ note: `Showing the top ${head.length} of ${rows.length} ${unit}${rankedBy}. The remaining ${tail.length} were omitted — raise \`limit\` to see them.`,+ };+ }++ const totals = new Map<string, number>();+ for (const column of sum) {+ let total = 0;+ for (const row of tail) {+ const value = row[column];+ if (typeof value === 'number' && Number.isFinite(value)) total += value;+ }+ totals.set(column, total);+ }++ const [labelColumn] = columns;+ out.push(+ columns.map((column) => {+ if (column === labelColumn) return `(other: ${tail.length} ${unit})`;+ return totals.has(column) ? totals.get(column) : null;+ })+ );++ const summed = sum.join(' + ');+ return {+ columns,+ rows: out,+ total_rows: rows.length,+ note: `Showing the top ${head.length} of ${rows.length} ${unit}${rankedBy}. The remaining ${tail.length} are aggregated into the final \`(other)\` row (${summed} summed; other columns null), so totals still reconcile. Raise \`limit\` to see them individually.`,+ };+}++/**+ * Walk a payload and shrink the largest embedded table by half.+ * Returns false when there is nothing left to shrink.+ */+function shrinkLargestTable(payload: unknown): boolean {+ let largest: TableResult | undefined;++ const visit = (node: unknown) => {+ if (node === null || typeof node !== 'object') return;+ if (isTableResult(node)) {+ if (!largest || node.rows.length > largest.rows.length) largest = node;+ return;+ }+ for (const value of Object.values(node as Record<string, unknown>)) {+ visit(value);+ }+ };+ visit(payload);++ if (!largest || largest.rows.length <= 1) return false;++ const kept = Math.max(1, Math.floor(largest.rows.length / 2));+ largest.rows = largest.rows.slice(0, kept);+ largest.note = `Truncated to ${kept} rows (of ${largest.total_rows} matched) to fit the response size limit. Narrow the date range or add a filter to see more.`;+ return true;+}+/*** Serialize a tool result to MCP content format.+ *+ * Compact — no indentation. Pretty-printing was 26% of the payload on a real+ * `get_top_referrers` call and buys an LLM reader nothing.+ *+ * Enforces `MAX_RESPONSE_CHARS` as a last-resort backstop: tools are expected+ * to size their own output via `table`, but a tool that returns something+ * unexpectedly large must degrade to a smaller answer rather than flood the+ * caller's context.*/export function toText(data: unknown): {content: [{ type: 'text'; text: string }];} {+ let text = JSON.stringify(data);++ while (text.length > MAX_RESPONSE_CHARS && shrinkLargestTable(data)) {+ text = JSON.stringify(data);+ }++ if (text.length > MAX_RESPONSE_CHARS) {+ logger.warn(+ { chars: text.length },+ 'MCP response exceeded size limit with no shrinkable table'+ );+ text = JSON.stringify({+ error: 'response_too_large',+ message: `This tool produced ${text.length} characters, over the ${MAX_RESPONSE_CHARS} limit, and could not be reduced automatically. Narrow the request — a shorter date range, a filter, or a more specific breakdown — and try again.`,+ });+ }+return {- content: [{ type: 'text' as const, text: JSON.stringify(data, null, 2) }],+ content: [{ type: 'text' as const, text }],};}