OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.
mcp: describe what the server and its tools actually do
Carl-Gerhard Lindesvärdd0c6422503bd
diff --git a/apps/start/src/components/profiles/profile-metrics.tsx b/apps/start/src/components/profiles/profile-metrics.tsxindex 9f6b038de..f2f560ca1 100644--- a/apps/start/src/components/profiles/profile-metrics.tsx+++ b/apps/start/src/components/profiles/profile-metrics.tsx@@ -2,7 +2,8 @@ import type { IProfileMetrics } from '@openpanel/core';import { OverviewMetricCard } from '@/components/overview/overview-metric-card';type Props = {- data: IProfileMetrics;+ /** `null` when nothing is known about the profile — no row and no events. */+ data: IProfileMetrics | null;};const PROFILE_METRICS = [@@ -100,6 +101,10 @@ const PROFILE_METRICS = [] as const;export const ProfileMetrics = ({ data }: Props) => {+ if (!data) {+ return null;+ }+return (<div className="relative col-span-6 -m-4 mt-0 mb-0 md:m-0"><div className="card grid grid-cols-2 overflow-hidden rounded-md md:grid-cols-4 lg:grid-cols-6">diff --git a/apps/start/src/routes/_app.$organizationId.$projectId.settings._tabs.mcp.tsx b/apps/start/src/routes/_app.$organizationId.$projectId.settings._tabs.mcp.tsxindex 6ff5f07e3..862e3c261 100644--- a/apps/start/src/routes/_app.$organizationId.$projectId.settings._tabs.mcp.tsx+++ b/apps/start/src/routes/_app.$organizationId.$projectId.settings._tabs.mcp.tsx@@ -194,8 +194,9 @@ function Component() {<h2 className="font-semibold text-lg">MCP Server</h2><p className="text-muted-foreground text-sm">Connect any MCP-compatible AI client (Claude, Cursor, Windsurf, …) to- your OpenPanel data. The server is read-only and exposes 38 tools for- querying events, sessions, profiles, funnels, retention and more.+ your OpenPanel data. Most of its tools read — events, sessions,+ profiles, funnels, retention and more — but it can also create, edit+ and delete dashboards and reports, so treat the token as write access.</p></div>diff --git a/packages/core/src/modules/mcp/src/integration/tools.test.ts b/packages/core/src/modules/mcp/src/integration/tools.test.tsindex 03c3eb00f..6c2922395 100644--- a/packages/core/src/modules/mcp/src/integration/tools.test.ts+++ b/packages/core/src/modules/mcp/src/integration/tools.test.ts@@ -480,6 +480,22 @@ describe('get_profile_metrics', () => {expect(res.conversionEvents).toBe(1); // page_view onlyexpect(res.screenViews).toBe(0);});++ // The query aggregates, so an unknown id used to come back as a row of+ // zeros and the tool's not-found branch could never fire — a made-up+ // profile reported confident zeros, indistinguishable from a real but+ // inactive user (ISSUES.md H8e).+ it('reports not found for a profile that does not exist', async () => {+ const server = makeServer();+ registerProfileMetricTools(server as any, TOOLS);+ const res = await server.invoke('get_profile_metrics', {+ projectId: TEST_PROJECT_ID,+ profileId: 'no-such-profile-at-all',+ });++ expect(res.error).toBe('Profile not found or has no events');+ expect(res.totalEvents).toBeUndefined();+ });});// ─── Groups ───────────────────────────────────────────────────────────────────diff --git a/packages/core/src/modules/mcp/src/tools/analytics/retention.ts b/packages/core/src/modules/mcp/src/tools/analytics/retention.tsindex 1c1409e6d..808d6e1e1 100644--- a/packages/core/src/modules/mcp/src/tools/analytics/retention.ts+++ b/packages/core/src/modules/mcp/src/tools/analytics/retention.ts@@ -13,7 +13,7 @@ export function registerRetentionTools() {server.tool('get_retention_cohort',- 'Get a weekly active-user retention cohort for the last 12 weeks. Returns one row per cohort (the week users were first seen), each with `cohort_interval`, `sum` (cohort size), `values` (retained user counts per following week) and `percentages` (retained share, 0-1). The leading "Weighted Average" row summarises all cohorts. Useful for understanding long-term user engagement and product stickiness.',+ 'Get a weekly active-user retention cohort for the last 12 weeks. Returns one row per cohort (the week users were first seen), each with `cohort_interval`, `sum` (cohort size), `values` (users still active in or after each following week — the count is cumulative, not week-by-week) and `percentages` (retained share, 0-1). The leading "Weighted Average" row summarises all cohorts. Useful for understanding long-term user engagement and product stickiness.',{projectId: projectIdSchema(context),},diff --git a/packages/core/src/modules/profile/profile.service.ts b/packages/core/src/modules/profile/profile.service.tsindex 93b449541..970606304 100644--- a/packages/core/src/modules/profile/profile.service.ts+++ b/packages/core/src/modules/profile/profile.service.ts@@ -187,23 +187,36 @@ async function compileProfileFilters(return buildFilterWhere(filters, projectId, PROFILE_FILTER_TARGET);}+/**+ * `null` when nothing is known about the profile — no row in `profiles` and no+ * events. The query aggregates, so an unknown id comes back as a row of zeros+ * rather than as no row at all, and callers that reported those zeros were+ * indistinguishable from a real but inactive user. A profile that exists and+ * simply has no events still returns metrics, with a `firstSeen`.+ */export async function getProfileMetrics(deps: ServiceDeps,profileId: string,projectId: string-): Promise<IProfileMetrics> {+): Promise<IProfileMetrics | null> {const [data] = await chQuery<Omit<IProfileMetrics, 'lastSeen' | 'firstSeen'> & {lastSeen: string;firstSeen: string;}>(deps, profileMetricsQuery({ profileId, projectId }));- const metrics = data!;- return {- ...metrics,- lastSeen: toNullIfDefaultMinDate(metrics.lastSeen),- firstSeen: toNullIfDefaultMinDate(metrics.firstSeen),- };++ if (!data) {+ return null;+ }++ const lastSeen = toNullIfDefaultMinDate(data.lastSeen);+ const firstSeen = toNullIfDefaultMinDate(data.firstSeen);+ if (lastSeen === null && firstSeen === null && data.totalEvents === 0) {+ return null;+ }++ return { ...data, lastSeen, firstSeen };}export async function getProfileById(