OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.
feat(mcp): manage dashboards and reports (#454)
Alvin46473c8be2f3
diff --git a/apps/public/content/docs/mcp/index.mdx b/apps/public/content/docs/mcp/index.mdxindex 5237e1541..fe9a720ce 100644--- a/apps/public/content/docs/mcp/index.mdx+++ b/apps/public/content/docs/mcp/index.mdx@@ -107,9 +107,24 @@ claude mcp add --transport http openpanel "https://api.openpanel.dev/mcp?token=Y| Tool | Description ||------|-------------|| `list_dashboards` | List all dashboards for a project. |+| `get_dashboard` | Get a dashboard with its complete report configurations and saved layouts. || `list_reports` | List all reports in a dashboard with their chart types and tracked events. || `get_report_data` | Execute a saved report and return its data (time-series, funnel, metric, etc.). |+### Dashboard management (root clients)++| Tool | Description |+|------|-------------|+| `create_dashboard` | Create a dashboard in a project. |+| `update_dashboard` | Rename a dashboard. |+| `delete_dashboard` | Delete an empty dashboard, or delete it with its reports using `forceDelete`. |+| `create_report` | Add a saved chart to a dashboard. |+| `update_report` | Replace a saved chart's configuration. |+| `delete_report` | Delete a saved chart. |+| `duplicate_report` | Duplicate a saved chart in its dashboard. |+| `update_report_layout` | Set a saved chart's dashboard grid position and dimensions. |+| `reset_dashboard_layout` | Remove all saved chart layouts from a dashboard. |+### Discovery| Tool | Description |diff --git a/packages/mcp/src/tools/dashboard-management.test.ts b/packages/mcp/src/tools/dashboard-management.test.tsnew file mode 100644index 000000000..e546977cf--- /dev/null+++ b/packages/mcp/src/tools/dashboard-management.test.ts@@ -0,0 +1,492 @@+import { beforeEach, describe, expect, it, vi } from 'vitest';+import { z } from 'zod';++const mockDb = vi.hoisted(() => ({+ $transaction: vi.fn(),+ dashboard: {+ create: vi.fn(),+ findFirst: vi.fn(),+ update: vi.fn(),+ delete: vi.fn(),+ },+ report: {+ create: vi.fn(),+ findFirst: vi.fn(),+ findMany: vi.fn(),+ update: vi.fn(),+ delete: vi.fn(),+ deleteMany: vi.fn(),+ },+ reportLayout: {+ upsert: vi.fn(),+ deleteMany: vi.fn(),+ },+}));++const mockGetDashboardById = vi.hoisted(() => vi.fn());+const mockGetProjectById = vi.hoisted(() => vi.fn());+const mockGetId = vi.hoisted(() => vi.fn());++vi.mock('@openpanel/db', () => ({+ Prisma: { DbNull: { kind: 'DbNull' } },+ db: mockDb,+ getDashboardById: mockGetDashboardById,+ getProjectById: mockGetProjectById,+ getId: mockGetId,+ resolveClientProjectId: vi.fn(+ ({+ clientProjectId,+ inputProjectId,+ }: {+ clientProjectId: string | null;+ inputProjectId?: string;+ }) => Promise.resolve(clientProjectId ?? inputProjectId),+ ),+}));++import type { McpAuthContext } from '../auth';+import { registerDashboardManagementTools } from './dashboard-management';++type Handler = (input: any) => Promise<any>;++function makeServer() {+ const handlers = new Map<string, Handler>();+ const schemas = new Map<string, any>();+ return {+ tool: (+ name: string,+ _description: string,+ schema: any,+ handler: Handler,+ ) => {+ handlers.set(name, handler);+ schemas.set(name, schema);+ },+ invoke: async (name: string, input: any) => {+ const schema = schemas.get(name);+ const parsed = z.object(schema).parse(input);+ const result = await handlers.get(name)!(parsed);+ const text = result.content[0].text;+ return result.isError ? { error: text } : JSON.parse(text);+ },+ schema(name: string) {+ return schemas.get(name);+ },+ names() {+ return [...schemas.keys()];+ },+ };+}++const READ_CONTEXT = {+ projectId: 'project-1',+ organizationId: 'organization-1',+ clientType: 'read' as const,+};++const ROOT_CONTEXT = {+ projectId: null,+ organizationId: 'organization-1',+ clientType: 'root' as const,+};++const DASHBOARD = {+ id: 'dashboard-1',+ projectId: 'project-1',+ organizationId: 'organization-1',+ name: 'Product',+ project: { id: 'project-1' },+};++const REPORT = {+ id: '11111111-1111-4111-8111-111111111111',+ projectId: 'project-1',+ dashboardId: 'dashboard-1',+ name: 'Signups',+ events: [],+ globalFilters: [],+ interval: 'day',+ breakdowns: [],+ chartType: 'linear',+ lineType: 'monotone',+ range: '30d',+ formula: null,+ previous: false,+ unit: null,+ metric: 'sum',+ options: null,+ visibleSeries: [],+ startDate: null,+ endDate: null,+ layout: null,+};++const EVENT_WITH_TYPED_COHORT_FILTER = {+ type: 'event',+ name: 'signup',+ segment: 'event',+ filters: [+ {+ id: 'A',+ name: 'plan',+ operator: 'is',+ value: ['pro'],+ type: 'string',+ cohortId: 'legacy-cohort',+ cohortIds: ['cohort-1', 'cohort-2'],+ },+ ],+};++beforeEach(() => {+ vi.clearAllMocks();+ mockGetDashboardById.mockResolvedValue(DASHBOARD);+ mockGetProjectById.mockResolvedValue({+ id: 'project-1',+ organizationId: 'organization-1',+ });+ mockGetId.mockResolvedValue('dashboard-2');+ mockDb.dashboard.create.mockResolvedValue({ ...DASHBOARD, id: 'dashboard-2' });+ mockDb.dashboard.findFirst.mockResolvedValue(DASHBOARD);+ mockDb.dashboard.update.mockResolvedValue({ ...DASHBOARD, name: 'Renamed' });+ mockDb.report.findFirst.mockResolvedValue(REPORT);+ mockDb.report.findMany.mockResolvedValue([]);+ mockDb.report.create.mockResolvedValue(REPORT);+ mockDb.report.update.mockResolvedValue(REPORT);+ mockDb.report.delete.mockResolvedValue(REPORT);+ mockDb.report.deleteMany.mockResolvedValue({ count: 1 });+ mockDb.reportLayout.upsert.mockResolvedValue({ reportId: REPORT.id, x: 1 });+ mockDb.reportLayout.deleteMany.mockResolvedValue({ count: 1 });+ mockDb.$transaction.mockImplementation(async (callback) => callback(mockDb));+});++function register(context: McpAuthContext = ROOT_CONTEXT) {+ const server = makeServer();+ registerDashboardManagementTools(server as any, context);+ return server;+}++function validReport(overrides: Record<string, unknown> = {}) {+ return {+ name: 'Signups',+ series: [],+ ...overrides,+ };+}++describe('dashboard management registration', () => {+ it('registers only get_dashboard for read credentials', () => {+ expect(register(READ_CONTEXT).names()).toEqual(['get_dashboard']);+ });++ it('registers all management tools for root credentials', () => {+ expect(register().names()).toEqual([+ 'get_dashboard',+ 'create_dashboard',+ 'update_dashboard',+ 'delete_dashboard',+ 'create_report',+ 'update_report',+ 'delete_report',+ 'duplicate_report',+ 'update_report_layout',+ 'reset_dashboard_layout',+ ]);+ });++ it('uses a strict persistable report schema with defaults', () => {+ const server = register();+ const reportSchema = server.schema('create_report').report;++ expect(reportSchema.parse(validReport())).toMatchObject({+ chartType: 'linear',+ interval: 'day',+ range: '30d',+ previous: false,+ metric: 'sum',+ lineType: 'monotone',+ });+ expect(reportSchema.safeParse({ name: 'Missing series' }).success).toBe(false);+ expect(+ reportSchema.safeParse(validReport({ limit: 10 })).success,+ ).toBe(false);+ expect(+ reportSchema.safeParse(validReport({ offset: 10 })).success,+ ).toBe(false);+ });++ it('requires valid ordered dates for custom ranges', () => {+ const reportSchema = register().schema('create_report').report;++ expect(+ reportSchema.safeParse(validReport({ range: 'custom' })).success,+ ).toBe(false);+ expect(+ reportSchema.safeParse(+ validReport({+ range: 'custom',+ startDate: '2026-02-30',+ endDate: '2026-03-01',+ }),+ ).success,+ ).toBe(false);+ expect(+ reportSchema.safeParse(+ validReport({+ range: 'custom',+ startDate: '2026-03-02',+ endDate: '2026-03-01',+ }),+ ).success,+ ).toBe(false);+ });+});++describe('dashboard management project binding', () => {+ it('binds dashboard reads to the resolved project', async () => {+ const server = register(READ_CONTEXT);++ await server.invoke('get_dashboard', {+ projectId: 'another-project',+ dashboardId: 'dashboard-1',+ });++ expect(mockGetDashboardById).toHaveBeenCalledWith('dashboard-1', 'project-1');+ expect(mockDb.report.findMany).toHaveBeenCalledWith({+ where: { dashboardId: 'dashboard-1', projectId: 'project-1' },+ include: { layout: true },+ });+ });++ it('rejects a report id that is not a uuid before touching the database', async () => {+ const server = register();++ await expect(+ server.invoke('delete_report', {+ projectId: 'project-1',+ reportId: 'dashboard-1',+ }),+ ).rejects.toThrow();+ expect(mockDb.report.findFirst).not.toHaveBeenCalled();+ });++ it('does not mutate a report from another project', async () => {+ mockDb.report.findFirst.mockResolvedValue(null);+ const server = register();++ const result = await server.invoke('delete_report', {+ projectId: 'project-1',+ reportId: '22222222-2222-4222-8222-222222222222',+ });++ expect(result.error).toContain('Report not found');+ expect(mockDb.report.delete).not.toHaveBeenCalled();+ expect(mockDb.report.findFirst).toHaveBeenCalledWith({+ where: { id: '22222222-2222-4222-8222-222222222222', projectId: 'project-1' },+ });+ });+});++describe('dashboard management behavior', () => {+ it('persists custom dates and router defaults after schema parsing', async () => {+ const server = register();++ await server.invoke('create_report', {+ projectId: 'project-1',+ dashboardId: 'dashboard-1',+ report: validReport({+ range: 'custom',+ startDate: '2026-01-01',+ endDate: '2026-01-31',+ }),+ });++ expect(mockDb.report.create).toHaveBeenCalledWith({+ data: expect.objectContaining({+ projectId: 'project-1',+ dashboardId: 'dashboard-1',+ globalFilters: [],+ visibleSeries: [],+ startDate: '2026-01-01',+ endDate: '2026-01-31',+ }),+ });+ });++ it('clears optional persisted report values on full replacement', async () => {+ const server = register();++ await server.invoke('update_report', {+ projectId: 'project-1',+ reportId: '11111111-1111-4111-8111-111111111111',+ report: validReport(),+ });++ expect(mockDb.report.update).toHaveBeenCalledWith({+ where: { id: '11111111-1111-4111-8111-111111111111' },+ data: expect.objectContaining({+ formula: null,+ unit: null,+ options: expect.anything(),+ startDate: null,+ endDate: null,+ }),+ });+ });++ it('returns a lossless report configuration for get→update round trips', async () => {+ const report = {+ ...REPORT,+ events: [EVENT_WITH_TYPED_COHORT_FILTER],+ globalFilters: [+ {+ name: 'country',+ operator: 'is',+ value: ['SE'],+ type: 'string',+ cohortIds: ['cohort-global'],+ },+ ],+ };+ mockDb.report.findMany.mockResolvedValue([report]);+ const readServer = register(READ_CONTEXT);+ const dashboard = await readServer.invoke('get_dashboard', {+ dashboardId: 'dashboard-1',+ });+ const configuration = dashboard.reports[0].report;++ expect(configuration.series).toEqual(report.events);+ expect(configuration.globalFilters).toEqual(report.globalFilters);++ const rootServer = register();+ await rootServer.invoke('update_report', {+ projectId: 'project-1',+ reportId: '11111111-1111-4111-8111-111111111111',+ report: configuration,+ });++ expect(mockDb.report.update).toHaveBeenCalledWith({+ where: { id: '11111111-1111-4111-8111-111111111111' },+ data: expect.objectContaining({+ events: report.events,+ globalFilters: report.globalFilters,+ }),+ });+ });++ it('rejects a non-empty dashboard atomically without force', async () => {+ mockDb.report.findMany.mockResolvedValue([+ { id: '11111111-1111-4111-8111-111111111111', projectId: 'project-1' },+ ]);+ const server = register();++ const result = await server.invoke('delete_dashboard', {+ projectId: 'project-1',+ dashboardId: 'dashboard-1',+ });++ expect(result.error).toContain('Cannot delete dashboard with associated reports');+ expect(mockDb.$transaction).toHaveBeenCalled();+ expect(mockDb.dashboard.delete).not.toHaveBeenCalled();+ });++ it('force deletes reports and their layouts in one transaction', async () => {+ mockDb.report.findMany.mockResolvedValue([+ { id: '11111111-1111-4111-8111-111111111111', projectId: 'project-1' },+ ]);+ const server = register();++ await server.invoke('delete_dashboard', {+ projectId: 'project-1',+ dashboardId: 'dashboard-1',+ forceDelete: true,+ });++ expect(mockDb.report.deleteMany).toHaveBeenCalledWith({+ where: { id: { in: ['11111111-1111-4111-8111-111111111111'] } },+ });+ expect(mockDb.reportLayout.deleteMany).toHaveBeenCalledWith({+ where: { reportId: { in: ['11111111-1111-4111-8111-111111111111'] } },+ });+ expect(+ mockDb.reportLayout.deleteMany.mock.invocationCallOrder[0]!,+ ).toBeLessThan(mockDb.report.deleteMany.mock.invocationCallOrder[0]!);+ expect(mockDb.dashboard.delete).toHaveBeenCalledWith({+ where: { id: 'dashboard-1' },+ });+ });++ it('duplicates a bound report without losing custom dates', async () => {+ mockDb.report.findFirst.mockResolvedValue({+ ...REPORT,+ events: [EVENT_WITH_TYPED_COHORT_FILTER],+ range: 'custom',+ startDate: '2026-01-01',+ endDate: '2026-01-31',+ });+ const server = register();++ await server.invoke('duplicate_report', {+ projectId: 'project-1',+ reportId: '11111111-1111-4111-8111-111111111111',+ });++ expect(mockDb.report.create).toHaveBeenCalledWith({+ data: expect.objectContaining({+ name: 'Copy of Signups',+ startDate: '2026-01-01',+ endDate: '2026-01-31',+ events: [EVENT_WITH_TYPED_COHORT_FILTER],+ }),+ });+ });++ it('scopes reset layout deletion to the resolved project dashboard', async () => {+ const server = register();++ await server.invoke('reset_dashboard_layout', {+ projectId: 'project-1',+ dashboardId: 'dashboard-1',+ });++ expect(mockDb.reportLayout.deleteMany).toHaveBeenCalledWith({+ where: {+ report: { dashboardId: 'dashboard-1', projectId: 'project-1' },+ },+ });+ });++ it('rejects invalid layouts before the handler executes and persists valid ones', async () => {+ const server = register();++ await expect(+ server.invoke('update_report_layout', {+ projectId: 'project-1',+ reportId: '11111111-1111-4111-8111-111111111111',+ layout: { x: -1, y: 0, w: 4, h: 3 },+ }),+ ).rejects.toThrow();+ expect(mockDb.reportLayout.upsert).not.toHaveBeenCalled();++ await server.invoke('update_report_layout', {+ projectId: 'project-1',+ reportId: '11111111-1111-4111-8111-111111111111',+ layout: { x: 1, y: 2, w: 4, h: 3, minW: 2, minH: 2, maxW: 8, maxH: 8 },+ });+ expect(mockDb.reportLayout.upsert).toHaveBeenCalledWith({+ where: { reportId: '11111111-1111-4111-8111-111111111111' },+ create: {+ reportId: '11111111-1111-4111-8111-111111111111',+ x: 1,+ y: 2,+ w: 4,+ h: 3,+ minW: 2,+ minH: 2,+ maxW: 8,+ maxH: 8,+ },+ update: { x: 1, y: 2, w: 4, h: 3, minW: 2, minH: 2, maxW: 8, maxH: 8 },+ });+ });+});diff --git a/packages/mcp/src/tools/dashboard-management.ts b/packages/mcp/src/tools/dashboard-management.tsnew file mode 100644index 000000000..f3391136f--- /dev/null+++ b/packages/mcp/src/tools/dashboard-management.ts@@ -0,0 +1,564 @@+import {+ Prisma,+ db,+ getDashboardById,+ getId,+ getProjectById,+} from '@openpanel/db';+import { zReport } from '@openpanel/validation';+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';++const reportSchema = zReport+ .omit({ projectId: true, limit: true, offset: true })+ .strict()+ .superRefine((report, ctx) => {+ if (report.range !== 'custom') {+ return;+ }++ const dates = [+ ['startDate', report.startDate],+ ['endDate', report.endDate],+ ] as const;++ for (const [field, value] of dates) {+ if (!isValidDateOnly(value)) {+ ctx.addIssue({+ code: z.ZodIssueCode.custom,+ path: [field],+ message: `${field} is required in YYYY-MM-DD format for custom ranges`,+ });+ }+ }++ if (+ isValidDateOnly(report.startDate) &&+ isValidDateOnly(report.endDate) &&+ report.startDate! > report.endDate!+ ) {+ ctx.addIssue({+ code: z.ZodIssueCode.custom,+ path: ['endDate'],+ message: 'endDate must be on or after startDate',+ });+ }+ });++const layoutSchema = z.object({+ x: z.number().int().nonnegative(),+ y: z.number().int().nonnegative(),+ w: z.number().int().positive(),+ h: z.number().int().positive(),+ minW: z.number().int().positive().optional(),+ minH: z.number().int().positive().optional(),+ maxW: z.number().int().positive().optional(),+ maxH: z.number().int().positive().optional(),+}).superRefine((layout, ctx) => {+ if (+ layout.minW !== undefined &&+ layout.maxW !== undefined &&+ layout.maxW < layout.minW+ ) {+ ctx.addIssue({+ code: z.ZodIssueCode.custom,+ path: ['maxW'],+ message: 'maxW must be greater than or equal to minW',+ });+ }+ if (layout.minW !== undefined && layout.minW > layout.w) {+ ctx.addIssue({+ code: z.ZodIssueCode.custom,+ path: ['minW'],+ message: 'minW must be less than or equal to w',+ });+ }+ if (layout.maxW !== undefined && layout.maxW < layout.w) {+ ctx.addIssue({+ code: z.ZodIssueCode.custom,+ path: ['maxW'],+ message: 'maxW must be greater than or equal to w',+ });+ }+ if (+ layout.minH !== undefined &&+ layout.maxH !== undefined &&+ layout.maxH < layout.minH+ ) {+ ctx.addIssue({+ code: z.ZodIssueCode.custom,+ path: ['maxH'],+ message: 'maxH must be greater than or equal to minH',+ });+ }+ if (layout.minH !== undefined && layout.minH > layout.h) {+ ctx.addIssue({+ code: z.ZodIssueCode.custom,+ path: ['minH'],+ message: 'minH must be less than or equal to h',+ });+ }+ if (layout.maxH !== undefined && layout.maxH < layout.h) {+ ctx.addIssue({+ code: z.ZodIssueCode.custom,+ path: ['maxH'],+ message: 'maxH must be greater than or equal to h',+ });+ }+});++function isValidDateOnly(value: unknown): value is string {+ if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(value)) {+ return false;+ }++ const date = new Date(`${value}T00:00:00.000Z`);+ return !Number.isNaN(date.getTime()) && date.toISOString().slice(0, 10) === value;+}++function dashboardUrl(organizationId: string, projectId: string, dashboardId: string) {+ return `${dashboardBaseUrl()}/${organizationId}/${projectId}/dashboards/${dashboardId}`;+}++function reportUrl(organizationId: string, projectId: string, reportId: string) {+ return `${dashboardBaseUrl()}/${organizationId}/${projectId}/reports/${reportId}`;+}++function reportData(report: z.infer<typeof reportSchema>) {+ return {+ name: report.name,+ events: report.series,+ globalFilters: report.globalFilters ?? [],+ interval: report.interval,+ breakdowns: report.breakdowns,+ chartType: report.chartType,+ lineType: report.lineType,+ range: report.range,+ formula: report.formula ?? null,+ previous: report.previous ?? false,+ unit: report.unit ?? null,+ metric: report.metric,+ options: report.options ?? Prisma.DbNull,+ visibleSeries: report.visibleSeries ?? [],+ startDate: report.range === 'custom' ? report.startDate : null,+ endDate: report.range === 'custom' ? report.endDate : null,+ };+}++async function requireDashboard(projectId: string, dashboardId: string) {+ const dashboard = await getDashboardById(dashboardId, projectId);+ if (!dashboard) {+ throw new Error('Dashboard not found');+ }+ return dashboard;+}++async function requireReport(projectId: string, reportId: string) {+ const report = await db.report.findFirst({+ where: { id: reportId, projectId },+ });+ if (!report) {+ throw new Error('Report not found');+ }+ return report;+}++function withDashboardUrl(+ organizationId: string,+ projectId: string,+ dashboard: {+ id: string;+ name: string;+ projectId: string;+ organizationId: string;+ createdAt: Date;+ updatedAt: Date;+ },+) {+ // Explicit fields: getDashboardById includes the full project row, which is+ // more than this tool should hand back.+ return {+ id: dashboard.id,+ name: dashboard.name,+ projectId: dashboard.projectId,+ organizationId: dashboard.organizationId,+ createdAt: dashboard.createdAt,+ updatedAt: dashboard.updatedAt,+ dashboard_url: dashboardUrl(organizationId, projectId, dashboard.id),+ };+}++function withReportUrl(+ organizationId: string,+ projectId: string,+ report: { id: string },+) {+ return {+ ...report,+ // Keep the existing MCP report-tool field name for this report URL.+ dashboard_url: reportUrl(organizationId, projectId, report.id),+ };+}++function canonicalReportConfig(report: {+ name: string;+ events: unknown;+ globalFilters: unknown;+ interval: string;+ breakdowns: unknown;+ chartType: string;+ lineType: string;+ range: string;+ formula: string | null;+ previous: boolean;+ unit: string | null;+ metric: string;+ options: unknown;+ visibleSeries: string[];+ startDate: string | null;+ endDate: string | null;+}) {+ return {+ name: report.name,+ series: report.events,+ globalFilters: report.globalFilters,+ interval: report.interval,+ breakdowns: report.breakdowns,+ chartType: report.chartType,+ lineType: report.lineType,+ range: report.range,+ startDate: report.startDate,+ endDate: report.endDate,+ previous: report.previous,+ formula: report.formula ?? undefined,+ metric: report.metric,+ unit: report.unit ?? undefined,+ options: report.options ?? undefined,+ visibleSeries: report.visibleSeries,+ };+}++export function registerDashboardManagementTools(+ server: McpServer,+ context: McpAuthContext,+) {+ server.tool(+ 'get_dashboard',+ 'Get a dashboard, all of its reports, and their saved layouts.',+ {+ projectId: projectIdSchema(context),+ dashboardId: z.string().describe('The dashboard ID to retrieve'),+ },+ async ({ projectId: inputProjectId, dashboardId }) =>+ withErrorHandling(async () => {+ const projectId = await resolveProjectId(context, inputProjectId);+ const dashboard = await requireDashboard(projectId, dashboardId);+ const reports = await db.report.findMany({+ where: { dashboardId, projectId },+ include: { layout: true },+ });+ const reportsWithUrls = reports.map((report) => ({+ id: report.id,+ report: canonicalReportConfig(report),+ layout: report.layout,+ dashboard_url: reportUrl(context.organizationId, projectId, report.id),+ }));++ return {+ dashboard: withDashboardUrl(context.organizationId, projectId, dashboard),+ reports: reportsWithUrls,+ layouts: reportsWithUrls.flatMap((report) =>+ report.layout ? [report.layout] : [],+ ),+ };+ }),+ );++ if (context.clientType !== 'root') {+ return;+ }++ server.tool(+ 'create_dashboard',+ 'Create a dashboard in the resolved project.',+ {+ projectId: projectIdSchema(context),+ name: z.string().describe('The dashboard name'),+ },+ async ({ projectId: inputProjectId, name }) =>+ withErrorHandling(async () => {+ const projectId = await resolveProjectId(context, inputProjectId);+ const project = await getProjectById(projectId);+ if (!project) {+ throw new Error('Project not found');+ }++ const dashboard = await db.dashboard.create({+ data: {+ id: await getId('dashboard', name),+ projectId,+ organizationId: project.organizationId,+ name,+ },+ });++ return {+ dashboard: withDashboardUrl(context.organizationId, projectId, dashboard),+ reports: [],+ layouts: [],+ };+ }),+ );++ server.tool(+ 'update_dashboard',+ 'Rename a dashboard after verifying it belongs to the resolved project.',+ {+ projectId: projectIdSchema(context),+ dashboardId: z.string().describe('The dashboard ID to update'),+ name: z.string().describe('The new dashboard name'),+ },+ async ({ projectId: inputProjectId, dashboardId, name }) =>+ withErrorHandling(async () => {+ const projectId = await resolveProjectId(context, inputProjectId);+ await requireDashboard(projectId, dashboardId);+ const dashboard = await db.dashboard.update({+ where: { id: dashboardId },+ data: { name },+ });++ return {+ dashboard: withDashboardUrl(context.organizationId, projectId, dashboard),+ };+ }),+ );++ server.tool(+ 'delete_dashboard',+ 'Delete a dashboard. Deletion fails when reports exist unless forceDelete is true; forced deletion removes the reports first.',+ {+ projectId: projectIdSchema(context),+ dashboardId: z.string().describe('The dashboard ID to delete'),+ forceDelete: z+ .boolean()+ .optional()+ .describe('Delete all reports in the dashboard before deleting it'),+ },+ async ({ projectId: inputProjectId, dashboardId, forceDelete }) =>+ withErrorHandling(async () => {+ const projectId = await resolveProjectId(context, inputProjectId);+ const dashboard = await requireDashboard(projectId, dashboardId);++ try {+ await db.$transaction(async (transaction) => {+ const current = await transaction.dashboard.findFirst({+ where: { id: dashboardId, projectId },+ });+ if (!current) {+ throw new Error('Dashboard not found');+ }++ const reports = await transaction.report.findMany({+ where: { dashboardId, projectId },+ select: { id: true },+ });+ if (reports.length > 0 && !forceDelete) {+ throw new Error('Cannot delete dashboard with associated reports');+ }++ if (forceDelete && reports.length > 0) {+ const reportIds = reports.map((report) => report.id);+ // Layouts hold the foreign key to reports, so they go first —+ // this order stays correct even if that cascade ever changes.+ await transaction.reportLayout.deleteMany({+ where: { reportId: { in: reportIds } },+ });+ await transaction.report.deleteMany({+ where: { id: { in: reportIds } },+ });+ }++ await transaction.dashboard.delete({ where: { id: dashboardId } });+ });+ } catch (error) {+ if (+ typeof error === 'object' &&+ error !== null &&+ 'code' in error &&+ error.code === 'P2003'+ ) {+ throw new Error('Cannot delete dashboard with associated reports');+ }+ if (error instanceof Error) {+ throw error;+ }+ throw new Error('Unknown error deleting dashboard');+ }++ return {+ deleted: true,+ dashboard: withDashboardUrl(context.organizationId, projectId, dashboard),+ };+ }),+ );++ server.tool(+ 'create_report',+ 'Create a saved chart report in a dashboard using the canonical report configuration shape.',+ {+ projectId: projectIdSchema(context),+ dashboardId: z.string().describe('The dashboard ID for the new report'),+ report: reportSchema.describe('The saved report configuration'),+ },+ async ({ projectId: inputProjectId, dashboardId, report }) =>+ withErrorHandling(async () => {+ const projectId = await resolveProjectId(context, inputProjectId);+ const dashboard = await requireDashboard(projectId, dashboardId);+ const created = await db.report.create({+ data: {+ projectId: dashboard.projectId,+ dashboardId,+ ...reportData(report),+ },+ });++ return {+ report: withReportUrl(context.organizationId, projectId, created),+ };+ }),+ );++ server.tool(+ 'update_report',+ 'Update a saved chart report after verifying it belongs to the resolved project.',+ {+ projectId: projectIdSchema(context),+ reportId: z.string().uuid().describe('The report ID to update'),+ report: reportSchema.describe('The complete saved report configuration'),+ },+ async ({ projectId: inputProjectId, reportId, report }) =>+ withErrorHandling(async () => {+ const projectId = await resolveProjectId(context, inputProjectId);+ await requireReport(projectId, reportId);+ const updated = await db.report.update({+ where: { id: reportId },+ data: reportData(report),+ });++ return {+ report: withReportUrl(context.organizationId, projectId, updated),+ };+ }),+ );++ server.tool(+ 'delete_report',+ 'Delete a saved chart report after verifying it belongs to the resolved project.',+ {+ projectId: projectIdSchema(context),+ reportId: z.string().uuid().describe('The report ID to delete'),+ },+ async ({ projectId: inputProjectId, reportId }) =>+ withErrorHandling(async () => {+ const projectId = await resolveProjectId(context, inputProjectId);+ await requireReport(projectId, reportId);+ const deleted = await db.report.delete({ where: { id: reportId } });++ return {+ deleted: true,+ report: withReportUrl(context.organizationId, projectId, deleted),+ };+ }),+ );++ server.tool(+ 'duplicate_report',+ 'Duplicate a saved report in its existing dashboard.',+ {+ projectId: projectIdSchema(context),+ reportId: z.string().uuid().describe('The report ID to duplicate'),+ },+ async ({ projectId: inputProjectId, reportId }) =>+ withErrorHandling(async () => {+ const projectId = await resolveProjectId(context, inputProjectId);+ const report = await requireReport(projectId, reportId);+ const duplicate = await db.report.create({+ data: {+ projectId: report.projectId,+ dashboardId: report.dashboardId,+ name: `Copy of ${report.name}`,+ events: report.events!,+ globalFilters: report.globalFilters ?? [],+ interval: report.interval,+ breakdowns: report.breakdowns!,+ chartType: report.chartType,+ lineType: report.lineType,+ range: report.range,+ formula: report.formula,+ previous: report.previous,+ unit: report.unit,+ metric: report.metric,+ options: report.options ?? Prisma.DbNull,+ visibleSeries: report.visibleSeries,+ startDate: report.startDate,+ endDate: report.endDate,+ },+ });++ return {+ report: withReportUrl(context.organizationId, projectId, duplicate),+ };+ }),+ );++ server.tool(+ 'update_report_layout',+ 'Save or update the grid layout for a report in the resolved project.',+ {+ projectId: projectIdSchema(context),+ reportId: z.string().uuid().describe('The report ID whose layout should change'),+ layout: layoutSchema.describe('The report grid layout'),+ },+ async ({ projectId: inputProjectId, reportId, layout }) =>+ withErrorHandling(async () => {+ const projectId = await resolveProjectId(context, inputProjectId);+ await requireReport(projectId, reportId);+ return db.reportLayout.upsert({+ where: { reportId },+ create: { reportId, ...layout },+ update: layout,+ });+ }),+ );++ server.tool(+ 'reset_dashboard_layout',+ 'Delete all saved report layouts in a dashboard after binding it to the resolved project.',+ {+ projectId: projectIdSchema(context),+ dashboardId: z.string().describe('The dashboard whose layouts should reset'),+ },+ async ({ projectId: inputProjectId, dashboardId }) =>+ withErrorHandling(async () => {+ const projectId = await resolveProjectId(context, inputProjectId);+ await requireDashboard(projectId, dashboardId);+ const result = await db.reportLayout.deleteMany({+ where: {+ report: {+ dashboardId,+ projectId,+ },+ },+ });++ return {+ dashboardId,+ count: result.count,+ dashboard_url: dashboardUrl(context.organizationId, projectId, dashboardId),+ };+ }),+ );+}diff --git a/packages/mcp/src/tools/index.ts b/packages/mcp/src/tools/index.tsindex 40acdcbcf..6a879e596 100644--- a/packages/mcp/src/tools/index.ts+++ b/packages/mcp/src/tools/index.ts@@ -24,6 +24,7 @@ import { registerGscOverviewTools } from './gsc/overview';import { registerGscPageTools } from './gsc/pages';import { registerGscQueryTools } from './gsc/queries';import { registerDashboardLinkTools } from './dashboard-links';+import { registerDashboardManagementTools } from './dashboard-management';import { registerProjectTools } from './projects';export function registerAllTools(@@ -33,6 +34,7 @@ export function registerAllTools(// Project access — always call first to discover available projectsregisterProjectTools(server, context);registerDashboardLinkTools(server, context);+ registerDashboardManagementTools(server, context);registerReportTools(server, context);// Analytics — discovery (call these first to understand the data)