Skip to content

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.tsx
index 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.tsx
index 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.ts
index 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 only
expect(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.ts
index 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.ts
index 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(