@asif2bd/umami-mcp 0.1.0

package/dist/server.js

@@ -0,0 +1,47 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { UmamiClient } from './client.js';
+import { redactUnknown } from './redact.js';
+import { allTools, isAllowed } from './tools/index.js';
+export const SERVER_NAME = 'umami-mcp';
+export const SERVER_VERSION = '0.1.0';
+export function buildServer(config, client = new UmamiClient(config)) {
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
+    const ctx = { client, config };
+    const registered = [];
+    const withheld = [];
+    for (const tool of allTools) {
+        if (!isAllowed(tool, config)) {
+            withheld.push(tool);
+            continue;
+        }
+        registered.push(tool);
+        server.registerTool(tool.name, {
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.schema,
+            annotations: {
+                readOnlyHint: tool.tier === 'read',
+                destructiveHint: Boolean(tool.destructive),
+                idempotentHint: tool.tier === 'read',
+                openWorldHint: true,
+            },
+        }, async (args) => {
+            try {
+                const result = await tool.handler(ctx, args ?? {});
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+                };
+            }
+            catch (err) {
+                // Surface the failure to the model as an error result rather than
+                // throwing, so it can correct course -- but scrub it first.
+                return {
+                    isError: true,
+                    content: [{ type: 'text', text: `${tool.name} failed: ${redactUnknown(err)}` }],
+                };
+            }
+        });
+    }
+    return { server, registered, withheld };
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAkC,MAAM,kBAAkB,CAAC;AAEvF,MAAM,CAAC,MAAM,WAAW,GAAG,WAAW,CAAC;AACvC,MAAM,CAAC,MAAM,cAAc,GAAG,OAAO,CAAC;AAQtC,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,MAAM,GAAG,IAAI,WAAW,CAAC,MAAM,CAAC;IAC1E,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC,CAAC;IAC7E,MAAM,GAAG,GAAgB,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAE5C,MAAM,UAAU,GAAc,EAAE,CAAC;IACjC,MAAM,QAAQ,GAAc,EAAE,CAAC;IAE/B,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;QAC5B,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC;YAC7B,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACpB,SAAS;QACX,CAAC;QACD,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAEtB,MAAM,CAAC,YAAY,CACjB,IAAI,CAAC,IAAI,EACT;YACE,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,WAAW,EAAE,IAAI,CAAC,MAAM;YACxB,WAAW,EAAE;gBACX,YAAY,EAAE,IAAI,CAAC,IAAI,KAAK,MAAM;gBAClC,eAAe,EAAE,OAAO,CAAC,IAAI,CAAC,WAAW,CAAC;gBAC1C,cAAc,EAAE,IAAI,CAAC,IAAI,KAAK,MAAM;gBACpC,aAAa,EAAE,IAAI;aACpB;SACF,EACD,KAAK,EAAE,IAAyB,EAAE,EAAE;YAClC,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC;gBACnD,OAAO;oBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;iBAC5E,CAAC;YACJ,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,kEAAkE;gBAClE,4DAA4D;gBAC5D,OAAO;oBACL,OAAO,EAAE,IAAI;oBACb,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC,IAAI,YAAY,aAAa,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;iBACzF,CAAC;YACJ,CAAC;QACH,CAAC,CACF,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,CAAC;AAC1C,CAAC"}

package/dist/tools/admin.d.ts

@@ -0,0 +1 @@
+export declare const adminTools: import("./common.js").ToolDef[];

package/dist/tools/admin.js

@@ -0,0 +1,99 @@
+import { z } from 'zod';
+import { defineTool } from './common.js';
+export const adminTools = [
+    defineTool({
+        name: 'umami_list_users',
+        title: 'List users',
+        description: 'List Umami user accounts with their roles. Admin only.',
+        tier: 'admin',
+        schema: {
+            query: z.string().optional().describe('Filter by username (substring match).'),
+            page: z.number().int().min(1).optional(),
+            pageSize: z.number().int().min(1).max(200).optional(),
+        },
+        handler: async ({ client }, args) => client.get('/api/admin/users', { query: args.query, page: args.page, pageSize: args.pageSize }),
+    }),
+    defineTool({
+        name: 'umami_create_user',
+        title: 'Create user',
+        description: 'Create a Umami user account. The password you supply is sent only to your own Umami instance. ' +
+            'Prefer a generated password that the new user changes on first login.',
+        tier: 'admin',
+        schema: {
+            username: z.string().min(1),
+            password: z.string().min(8).describe('At least 8 characters.'),
+            role: z.enum(['admin', 'user', 'view-only']).optional().describe('Default "user".'),
+        },
+        handler: async ({ client }, args) => {
+            const created = await client.post('/api/users', {
+                username: args.username,
+                password: args.password,
+                role: args.role ?? 'user',
+            });
+            // Never echo the password back into the transcript.
+            return { id: created?.id, username: created?.username, role: created?.role, created: true };
+        },
+    }),
+    defineTool({
+        name: 'umami_delete_user',
+        title: 'Delete user',
+        description: 'PERMANENTLY DELETE a user account and the websites they own. Cannot be undone. ' +
+            'Requires admin mode with destructive operations enabled.',
+        tier: 'admin',
+        destructive: true,
+        schema: {
+            userId: z.string().min(1).describe('User UUID from umami_list_users.'),
+            confirmUsername: z.string().min(1).describe('Type the exact username to confirm.'),
+        },
+        handler: async ({ client }, args) => {
+            const user = await client.get(`/api/users/${encodeURIComponent(args.userId)}`);
+            if (!user?.username)
+                throw new Error(`User ${args.userId} not found.`);
+            if (user.username !== args.confirmUsername) {
+                throw new Error(`Refusing to delete: confirmUsername ${JSON.stringify(args.confirmUsername)} does not match ` +
+                    `the account's actual username ${JSON.stringify(user.username)}.`);
+            }
+            await client.del(`/api/users/${encodeURIComponent(args.userId)}`);
+            return { deleted: true, userId: args.userId, username: user.username };
+        },
+    }),
+    defineTool({
+        name: 'umami_list_teams',
+        title: 'List teams',
+        description: 'List teams and their members.',
+        tier: 'read',
+        schema: {
+            query: z.string().optional(),
+            page: z.number().int().min(1).optional(),
+            pageSize: z.number().int().min(1).max(200).optional(),
+        },
+        handler: async ({ client }, args) => client.get('/api/teams', { query: args.query, page: args.page, pageSize: args.pageSize }),
+    }),
+    defineTool({
+        name: 'umami_create_team',
+        title: 'Create team',
+        description: 'Create a team so websites can be shared between users.',
+        tier: 'write',
+        schema: { name: z.string().min(1).describe('Team display name.') },
+        handler: async ({ client }, args) => client.post('/api/teams', { name: args.name }),
+    }),
+    defineTool({
+        name: 'umami_whoami',
+        title: 'Check connection',
+        description: 'Verify that this MCP server can reach the configured Umami instance and report which account it is ' +
+            'authenticated as, plus the permission mode the server is running in. Good first call for diagnosing setup.',
+        tier: 'read',
+        schema: {},
+        handler: async ({ client, config }) => {
+            const user = await client.verify();
+            return {
+                instance: config.url,
+                authenticatedAs: user.username,
+                role: user.role,
+                serverMode: config.mode,
+                destructiveOperations: config.allowDestructive ? 'enabled' : 'disabled',
+            };
+        },
+    }),
+];
+//# sourceMappingURL=admin.js.map

package/dist/tools/admin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.js","sourceRoot":"","sources":["../../src/tools/admin.ts"],"names":[],"mappings":"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"}

package/dist/tools/analytics.d.ts

@@ -0,0 +1 @@
+export declare const analyticsTools: import("./common.js").ToolDef[];

package/dist/tools/analytics.js

@@ -0,0 +1,141 @@
+import { z } from 'zod';
+import { defineTool, periodSchema, resolveRange, websiteIdSchema, METRIC_TYPES } from './common.js';
+export const analyticsTools = [
+    defineTool({
+        name: 'umami_get_stats',
+        title: 'Get summary stats',
+        description: 'Headline totals for a website over a period: pageviews, visitors, visits, bounces and total time on site. ' +
+            'The response also includes a "comparison" block for the equally-long preceding period, so you can report trends.',
+        tier: 'read',
+        schema: { ...websiteIdSchema, ...periodSchema },
+        handler: async ({ client }, args) => {
+            const { startAt, endAt } = resolveRange(args);
+            const data = await client.get(`/api/websites/${encodeURIComponent(args.websiteId)}/stats`, { startAt, endAt });
+            return { range: { startAt, endAt }, ...data };
+        },
+    }),
+    defineTool({
+        name: 'umami_get_pageviews',
+        title: 'Get pageview time series',
+        description: 'Pageviews and sessions bucketed over time, for charting traffic. Returns two parallel series.',
+        tier: 'read',
+        schema: {
+            ...websiteIdSchema,
+            ...periodSchema,
+            unit: z.enum(['hour', 'day', 'month', 'year']).optional().describe('Bucket size, default "day".'),
+            timezone: z.string().optional().describe('IANA timezone for bucket boundaries, e.g. "Asia/Dhaka". Default UTC.'),
+        },
+        handler: async ({ client }, args) => {
+            const { startAt, endAt } = resolveRange(args);
+            const data = await client.get(`/api/websites/${encodeURIComponent(args.websiteId)}/pageviews`, {
+                startAt,
+                endAt,
+                unit: args.unit ?? 'day',
+                timezone: args.timezone ?? 'UTC',
+            });
+            return { range: { startAt, endAt }, unit: args.unit ?? 'day', ...data };
+        },
+    }),
+    defineTool({
+        name: 'umami_get_metrics',
+        title: 'Get metric breakdown',
+        description: 'Top values for one dimension, ranked by visitor count -- top pages, referrers, countries, browsers and so on. ' +
+            'Returns [{x, y}] where x is the value and y is the count. ' +
+            'Note: Umami v3 renamed the v2 "url" type to "path" and "host" to "hostname".',
+        tier: 'read',
+        schema: {
+            ...websiteIdSchema,
+            ...periodSchema,
+            type: z.enum(METRIC_TYPES).describe('Dimension to break down by.'),
+            limit: z.number().int().min(1).max(500).optional().describe('Maximum rows, default 20.'),
+        },
+        handler: async ({ client }, args) => {
+            const { startAt, endAt } = resolveRange(args);
+            const data = await client.get(`/api/websites/${encodeURIComponent(args.websiteId)}/metrics`, {
+                startAt,
+                endAt,
+                type: args.type,
+                limit: args.limit ?? 20,
+            });
+            return { range: { startAt, endAt }, type: args.type, data };
+        },
+    }),
+    defineTool({
+        name: 'umami_get_active_visitors',
+        title: 'Get active visitors',
+        description: 'Number of visitors active on the site in the last few minutes. Cheap; good for a live check.',
+        tier: 'read',
+        schema: { ...websiteIdSchema },
+        handler: async ({ client }, args) => client.get(`/api/websites/${encodeURIComponent(args.websiteId)}/active`),
+    }),
+    defineTool({
+        name: 'umami_get_realtime',
+        title: 'Get realtime activity',
+        description: 'Live snapshot of current activity: recent events with country, URL, browser and device, plus rollups ' +
+            'by country, URL and referrer. Use this to answer "what is happening on the site right now".',
+        tier: 'read',
+        schema: { websiteId: websiteIdSchema.websiteId },
+        handler: async ({ client }, args) => client.get(`/api/realtime/${encodeURIComponent(args.websiteId)}`),
+    }),
+    defineTool({
+        name: 'umami_get_event_stats',
+        title: 'Get custom event stats',
+        description: 'Totals for custom tracked events over a period: event count, unique event names, visitors and visits, ' +
+            'with a comparison against the preceding period.',
+        tier: 'read',
+        schema: {
+            ...websiteIdSchema,
+            ...periodSchema,
+            unit: z.enum(['hour', 'day', 'month', 'year']).optional().describe('Bucket size, default "day".'),
+            timezone: z.string().optional().describe('IANA timezone, default UTC.'),
+        },
+        handler: async ({ client }, args) => {
+            const { startAt, endAt } = resolveRange(args);
+            const data = await client.get(`/api/websites/${encodeURIComponent(args.websiteId)}/events/stats`, {
+                startAt,
+                endAt,
+                unit: args.unit ?? 'day',
+                timezone: args.timezone ?? 'UTC',
+            });
+            return { range: { startAt, endAt }, ...data };
+        },
+    }),
+    defineTool({
+        name: 'umami_list_sessions',
+        title: 'List sessions',
+        description: 'Individual visitor sessions with browser, OS, device, country and region. ' +
+            'Useful for drilling into who visited rather than aggregate counts.',
+        tier: 'read',
+        schema: {
+            ...websiteIdSchema,
+            ...periodSchema,
+            page: z.number().int().min(1).optional(),
+            pageSize: z.number().int().min(1).max(200).optional().describe('Default 20.'),
+        },
+        handler: async ({ client }, args) => {
+            const { startAt, endAt } = resolveRange(args);
+            return client.get(`/api/websites/${encodeURIComponent(args.websiteId)}/sessions`, {
+                startAt,
+                endAt,
+                page: args.page,
+                pageSize: args.pageSize,
+            });
+        },
+    }),
+    defineTool({
+        name: 'umami_get_session_activity',
+        title: 'Get session activity',
+        description: 'The ordered sequence of pageviews and events for one visitor session -- their path through the site.',
+        tier: 'read',
+        schema: {
+            ...websiteIdSchema,
+            sessionId: z.string().min(1).describe('Session UUID from umami_list_sessions.'),
+            ...periodSchema,
+        },
+        handler: async ({ client }, args) => {
+            const { startAt, endAt } = resolveRange(args);
+            return client.get(`/api/websites/${encodeURIComponent(args.websiteId)}/sessions/${encodeURIComponent(args.sessionId)}/activity`, { startAt, endAt });
+        },
+    }),
+];
+//# sourceMappingURL=analytics.js.map

package/dist/tools/analytics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"analytics.js","sourceRoot":"","sources":["../../src/tools/analytics.ts"],"names":[],"mappings":"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"}

package/dist/tools/common.d.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import type { UmamiClient } from '../client.js';
+import type { Config } from '../config.js';
+/**
+ * Tools declare the privilege they need. The server registers only the tools
+ * the operator has enabled, so a tool the operator did not permit is not
+ * merely refused at call time -- it is never advertised to the model at all,
+ * and therefore cannot be invoked by a prompt-injected instruction.
+ */
+export type Tier = 'read' | 'write' | 'admin';
+export interface ToolContext {
+    client: UmamiClient;
+    config: Config;
+}
+export interface ToolDef {
+    name: string;
+    title: string;
+    description: string;
+    tier: Tier;
+    /** Irreversible: deleting a site, wiping its data, removing a user. */
+    destructive?: boolean;
+    schema: z.ZodRawShape;
+    handler: (ctx: ToolContext, args: Record<string, any>) => Promise<unknown>;
+}
+export declare function defineTool(def: ToolDef): ToolDef;
+/** Is `tool` permitted under the operator's configuration? */
+export declare function isAllowed(tool: ToolDef, config: Config): boolean;
+export declare const periodSchema: {
+    period: z.ZodOptional<z.ZodString>;
+    startAt: z.ZodOptional<z.ZodNumber>;
+    endAt: z.ZodOptional<z.ZodNumber>;
+};
+export interface Range {
+    startAt: number;
+    endAt: number;
+}
+export declare function resolveRange(args: {
+    period?: string;
+    startAt?: number;
+    endAt?: number;
+}, now?: number): Range;
+/** Metric dimensions accepted by Umami v3's /metrics endpoint. */
+export declare const METRIC_TYPES: readonly ["path", "title", "referrer", "query", "browser", "os", "device", "screen", "country", "region", "city", "language", "hostname", "event", "tag", "channel"];
+export declare const websiteIdSchema: {
+    websiteId: z.ZodString;
+};

package/dist/tools/common.js

@@ -0,0 +1,86 @@
+import { z } from 'zod';
+export function defineTool(def) {
+    return def;
+}
+const RANK = { read: 0, write: 1, admin: 2 };
+/** Is `tool` permitted under the operator's configuration? */
+export function isAllowed(tool, config) {
+    if (RANK[tool.tier] > RANK[config.mode])
+        return false;
+    if (tool.destructive && !config.allowDestructive)
+        return false;
+    return true;
+}
+/* ------------------------------------------------------------------ *
+ * Date handling
+ *
+ * Umami expects epoch milliseconds. Models are far better at "last 7
+ * days" than at arithmetic on timestamps, and a model that miscalculates
+ * an epoch silently returns data for the wrong period. Accepting a
+ * shorthand removes that whole class of error.
+ * ------------------------------------------------------------------ */
+const RELATIVE = /^(\d+)(h|d|w|m|y)$/i;
+const UNIT_MS = {
+    h: 3_600_000,
+    d: 86_400_000,
+    w: 604_800_000,
+    m: 2_592_000_000, // 30d
+    y: 31_536_000_000, // 365d
+};
+export const periodSchema = {
+    period: z
+        .string()
+        .optional()
+        .describe('Relative time range: "24h", "7d", "30d", "12m", or "today"/"yesterday". ' +
+        'Defaults to "7d". Ignored if startAt/endAt are given.'),
+    startAt: z.number().int().optional().describe('Range start, epoch milliseconds. Overrides period.'),
+    endAt: z.number().int().optional().describe('Range end, epoch milliseconds. Overrides period.'),
+};
+export function resolveRange(args, now = Date.now()) {
+    if (args.startAt !== undefined && args.endAt !== undefined) {
+        if (args.endAt < args.startAt)
+            throw new Error('endAt must be greater than or equal to startAt');
+        return { startAt: args.startAt, endAt: args.endAt };
+    }
+    const period = (args.period ?? '7d').trim().toLowerCase();
+    if (period === 'today') {
+        const d = new Date(now);
+        d.setUTCHours(0, 0, 0, 0);
+        return { startAt: d.getTime(), endAt: now };
+    }
+    if (period === 'yesterday') {
+        const end = new Date(now);
+        end.setUTCHours(0, 0, 0, 0);
+        return { startAt: end.getTime() - UNIT_MS.d, endAt: end.getTime() };
+    }
+    const m = RELATIVE.exec(period);
+    if (!m) {
+        throw new Error(`Unrecognised period ${JSON.stringify(args.period)}. Use e.g. "24h", "7d", "30d", "12m", "today", "yesterday", ` +
+            'or pass explicit startAt/endAt epoch milliseconds.');
+    }
+    const span = Number(m[1]) * UNIT_MS[m[2].toLowerCase()];
+    return { startAt: now - span, endAt: now };
+}
+/** Metric dimensions accepted by Umami v3's /metrics endpoint. */
+export const METRIC_TYPES = [
+    'path',
+    'title',
+    'referrer',
+    'query',
+    'browser',
+    'os',
+    'device',
+    'screen',
+    'country',
+    'region',
+    'city',
+    'language',
+    'hostname',
+    'event',
+    'tag',
+    'channel',
+];
+export const websiteIdSchema = {
+    websiteId: z.string().min(1).describe('Umami website UUID. Use umami_list_websites to find it.'),
+};
+//# sourceMappingURL=common.js.map

package/dist/tools/common.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.js","sourceRoot":"","sources":["../../src/tools/common.ts"],"names":[],"mappings":"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"}

package/dist/tools/index.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDef } from './common.js';
+export declare const allTools: ToolDef[];
+export * from './common.js';

package/dist/tools/index.js

@@ -0,0 +1,7 @@
+import { websiteTools } from './websites.js';
+import { analyticsTools } from './analytics.js';
+import { reportTools } from './reports.js';
+import { adminTools } from './admin.js';
+export const allTools = [...websiteTools, ...analyticsTools, ...reportTools, ...adminTools];
+export * from './common.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAExC,MAAM,CAAC,MAAM,QAAQ,GAAc,CAAC,GAAG,YAAY,EAAE,GAAG,cAAc,EAAE,GAAG,WAAW,EAAE,GAAG,UAAU,CAAC,CAAC;AAEvG,cAAc,aAAa,CAAC"}

package/dist/tools/reports.d.ts

@@ -0,0 +1 @@
+export declare const reportTools: import("./common.js").ToolDef[];

package/dist/tools/reports.js

@@ -0,0 +1,122 @@
+import { z } from 'zod';
+import { defineTool, periodSchema, resolveRange, websiteIdSchema } from './common.js';
+async function runReport({ client }, type, args, parameters) {
+    const { startAt, endAt } = resolveRange(args);
+    const body = {
+        websiteId: args.websiteId,
+        type,
+        filters: args.filters ?? {},
+        parameters: {
+            startDate: new Date(startAt).toISOString(),
+            endDate: new Date(endAt).toISOString(),
+            ...parameters,
+        },
+    };
+    const data = await client.post(`/api/reports/${type}`, body);
+    return { report: type, range: { startAt, endAt }, data };
+}
+const filtersSchema = {
+    filters: z
+        .record(z.any())
+        .optional()
+        .describe('Optional Umami filter object to narrow the report, e.g. {"country":"BD"}.'),
+};
+export const reportTools = [
+    defineTool({
+        name: 'umami_report_utm',
+        title: 'UTM campaign report',
+        description: 'Breakdown of traffic by UTM parameters: source, medium, campaign, term and content. ' +
+            'In Umami v3 UTM data lives here, not in the /metrics endpoint.',
+        tier: 'read',
+        schema: { ...websiteIdSchema, ...periodSchema, ...filtersSchema },
+        handler: (ctx, a) => runReport(ctx, 'utm', a, {}),
+    }),
+    defineTool({
+        name: 'umami_report_funnel',
+        title: 'Funnel report',
+        description: 'Step-by-step conversion funnel. Give an ordered list of steps; the report returns visitors reaching ' +
+            'each step plus the drop-off between them.',
+        tier: 'read',
+        schema: {
+            ...websiteIdSchema,
+            ...periodSchema,
+            ...filtersSchema,
+            steps: z
+                .array(z.object({
+                type: z.enum(['path', 'event']).describe('Match a page path or a custom event name.'),
+                value: z.string().min(1).describe('The path (e.g. "/pricing") or event name.'),
+            }))
+                .min(2)
+                .describe('Ordered funnel steps, at least two.'),
+            window: z.number().int().min(1).optional().describe('Conversion window in minutes, default 60.'),
+        },
+        handler: (ctx, a) => runReport(ctx, 'funnel', a, { steps: a.steps, window: a.window ?? 60 }),
+    }),
+    defineTool({
+        name: 'umami_report_retention',
+        title: 'Retention report',
+        description: 'Cohort retention: of the visitors first seen on a given day, how many returned on each subsequent day.',
+        tier: 'read',
+        schema: { ...websiteIdSchema, ...periodSchema, ...filtersSchema },
+        handler: (ctx, a) => runReport(ctx, 'retention', a, {}),
+    }),
+    defineTool({
+        name: 'umami_report_journey',
+        title: 'User journey report',
+        description: 'Most common ordered paths visitors take through the site, as sequences of pages with a count for each.',
+        tier: 'read',
+        schema: {
+            ...websiteIdSchema,
+            ...periodSchema,
+            ...filtersSchema,
+            steps: z.number().int().min(2).max(10).optional().describe('Journey length in pages, default 5.'),
+        },
+        handler: (ctx, a) => runReport(ctx, 'journey', a, { steps: a.steps ?? 5 }),
+    }),
+    defineTool({
+        name: 'umami_report_goal',
+        title: 'Goal report',
+        description: 'Progress toward a single goal: how many visitors hit a given path or custom event.',
+        tier: 'read',
+        schema: {
+            ...websiteIdSchema,
+            ...periodSchema,
+            ...filtersSchema,
+            type: z.enum(['path', 'event']).describe('Whether the goal is a page path or a custom event.'),
+            value: z.string().min(1).describe('The path (e.g. "/thank-you") or event name.'),
+            operator: z.string().optional().describe('Optional comparison operator supported by Umami.'),
+        },
+        handler: (ctx, a) => runReport(ctx, 'goal', a, { type: a.type, value: a.value, operator: a.operator }),
+    }),
+    defineTool({
+        name: 'umami_report_revenue',
+        title: 'Revenue report',
+        description: 'Revenue over time from events carrying a revenue property, broken down by country, region, referrer and channel. ' +
+            'Requires revenue tracking to be set up in Umami.',
+        tier: 'read',
+        schema: {
+            ...websiteIdSchema,
+            ...periodSchema,
+            ...filtersSchema,
+            currency: z.string().length(3).optional().describe('ISO 4217 currency code, default "USD".'),
+        },
+        handler: (ctx, a) => runReport(ctx, 'revenue', a, { currency: a.currency ?? 'USD' }),
+    }),
+    defineTool({
+        name: 'umami_report_attribution',
+        title: 'Attribution report',
+        description: 'Credits conversions to acquisition channels -- referrer, paid ads and UTM parameters -- under either a ' +
+            'first-click or last-click model.',
+        tier: 'read',
+        schema: {
+            ...websiteIdSchema,
+            ...periodSchema,
+            ...filtersSchema,
+            model: z.enum(['first-click', 'last-click']).describe('Attribution model.'),
+            type: z.enum(['path', 'event']).describe('Whether the conversion is a page path or a custom event.'),
+            step: z.string().min(1).describe('The converting path (e.g. "/checkout") or event name.'),
+        },
+        handler: (ctx, a) => runReport(ctx, 'attribution', a, { model: a.model, type: a.type, step: a.step }),
+    }),
+];
+//# sourceMappingURL=reports.js.map

package/dist/tools/reports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reports.js","sourceRoot":"","sources":["../../src/tools/reports.ts"],"names":[],"mappings":"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"}

package/dist/tools/websites.d.ts

@@ -0,0 +1 @@
+export declare const websiteTools: import("./common.js").ToolDef[];