@vendure/mcp-plugin 3.8.0-minor-bootstrap.0

package/src/dashboard/components/connection-dialog.tsx

@@ -0,0 +1,106 @@
+import { Trans } from '@lingui/react/macro';
+import {
+    api,
+    Button,
+    CopyableText,
+    Dialog,
+    DialogClose,
+    DialogContent,
+    DialogDescription,
+    DialogFooter,
+    DialogHeader,
+    DialogTitle,
+    DialogTrigger,
+    Separator,
+    useQuery,
+} from '@vendure/dashboard';
+import { ExternalLinkIcon, PlugIcon } from 'lucide-react';
+
+import { mcpServerConfigQuery } from '../mcp.graphql';
+
+const SETUP_GUIDE_URL = 'https://docs.vendure.io/guides/mcp-server/quick-start/';
+
+function CopyableField({ label, value }: { label: React.ReactNode; value: string }) {
+    return (
+        <div className="space-y-1.5">
+            <div className="text-xs font-medium text-muted-foreground">{label}</div>
+            <CopyableText value={value} className="justify-between rounded-md border bg-muted/50 px-3 py-2">
+                <code className="min-w-0 flex-1 truncate font-mono text-xs select-all" title={value}>
+                    {value}
+                </code>
+            </CopyableText>
+        </div>
+    );
+}
+
+// Behind a header button rather than on the page, so it doesn't compete with the day-to-day blocks.
+export function ConnectionDialog() {
+    const { data, isLoading } = useQuery({
+        queryKey: ['mcp-server-config'],
+        queryFn: () => api.query(mcpServerConfigQuery),
+    });
+    const config = data?.mcpServerConfig;
+    // Clients reach the server on its OAuth issuer origin, which can differ from the dashboard's own origin.
+    const origin = config?.issuer ?? window.location.origin;
+    const adminUrl = `${origin}/mcp/admin`;
+    const shopUrl = `${origin}/mcp/shop`;
+    const inspectorCommand = 'npx @modelcontextprotocol/inspector';
+    // Until the config arrives both endpoints are shown, so the dialog does not flash empty.
+    const showAdminUrl = isLoading || config?.oauthConfigured !== false;
+    const showShopUrl = isLoading || config?.shopAccess !== 'disabled';
+
+    return (
+        <Dialog>
+            <DialogTrigger render={<Button variant="outline" />}>
+                <PlugIcon className="h-4 w-4" />
+                <Trans>Connect a client</Trans>
+            </DialogTrigger>
+            <DialogContent className="sm:max-w-lg">
+                <DialogHeader>
+                    <DialogTitle>
+                        <Trans>Connect a client</Trans>
+                    </DialogTitle>
+                    <DialogDescription>
+                        <Trans>Connect an MCP client to your Vendure server using the endpoints below.</Trans>
+                    </DialogDescription>
+                </DialogHeader>
+
+                <div className="space-y-4">
+                    {showAdminUrl ? (
+                        <CopyableField label={<Trans>Admin API</Trans>} value={adminUrl} />
+                    ) : (
+                        <p className="text-sm text-muted-foreground">
+                            <Trans>
+                                The admin endpoint needs OAuth. Add an oauth block to McpPlugin.init to enable
+                                it.
+                            </Trans>
+                        </p>
+                    )}
+                    {showShopUrl ? (
+                        <CopyableField label={<Trans>Shop API</Trans>} value={shopUrl} />
+                    ) : (
+                        <p className="text-sm text-muted-foreground">
+                            <Trans>The shop endpoint is disabled (shopAccess: 'disabled').</Trans>
+                        </p>
+                    )}
+                    <Separator />
+                    <CopyableField label={<Trans>Test with MCP Inspector</Trans>} value={inspectorCommand} />
+                </div>
+
+                <DialogFooter className="sm:items-center sm:justify-between">
+                    <Button
+                        variant="link"
+                        className="px-0"
+                        render={<a href={SETUP_GUIDE_URL} target="_blank" rel="noreferrer noopener" />}
+                    >
+                        <ExternalLinkIcon className="h-3.5 w-3.5" />
+                        <Trans>Setup guide for connecting MCP clients</Trans>
+                    </Button>
+                    <DialogClose render={<Button variant="outline" />}>
+                        <Trans>Close</Trans>
+                    </DialogClose>
+                </DialogFooter>
+            </DialogContent>
+        </Dialog>
+    );
+}

package/src/dashboard/components/empty-cell.tsx

@@ -0,0 +1,7 @@
+/**
+ * Placeholder for a table cell that has no value, so every empty cell in the
+ * MCP tables looks the same.
+ */
+export function EmptyCell() {
+    return <span className="text-muted-foreground">—</span>;
+}

package/src/dashboard/components/grants-block.tsx

@@ -0,0 +1,218 @@
+import { Trans, useLingui } from '@lingui/react/macro';
+import {
+    Alert,
+    AlertDescription,
+    api,
+    Badge,
+    Button,
+    ConfirmationDialog,
+    DropdownMenu,
+    DropdownMenuContent,
+    DropdownMenuGroup,
+    DropdownMenuItem,
+    DropdownMenuTrigger,
+    PaginatedListDataTable,
+    type ResultOf,
+    toast,
+    useMutation,
+    usePermissions,
+    useQuery,
+} from '@vendure/dashboard';
+import { BanIcon, EllipsisIcon, InfoIcon } from 'lucide-react';
+import { useRef } from 'react';
+
+import { mcpOauthGrantsQuery, mcpServerConfigQuery, revokeMcpOauthGrantMutation } from '../mcp.graphql';
+
+import { ActorCell } from './actor-cell';
+import { EmptyCell } from './empty-cell';
+import { useMcpTableState } from './use-mcp-table-state';
+
+type Grant = ResultOf<typeof mcpOauthGrantsQuery>['mcpOauthGrants']['items'][number];
+
+function GrantStatusBadge({ status }: { status: Grant['status'] }) {
+    if (status === 'revoked') {
+        return (
+            <Badge variant="destructive">
+                <Trans>Revoked</Trans>
+            </Badge>
+        );
+    }
+    if (status === 'expired') {
+        return (
+            <Badge variant="secondary">
+                <Trans>Expired</Trans>
+            </Badge>
+        );
+    }
+    return (
+        <Badge variant="default">
+            <Trans>Active</Trans>
+        </Badge>
+    );
+}
+
+export function GrantsBlock() {
+    const { t } = useLingui();
+    const { hasPermissions } = usePermissions();
+    const canUpdate = hasPermissions(['UpdateMcpServer']);
+    const tableState = useMcpTableState({
+        defaultSorting: [{ id: 'lastActivityAt', desc: true }],
+        defaultVisibility: {
+            id: false,
+            createdAt: false,
+            updatedAt: false,
+            actorId: false,
+            channelId: false,
+            revokedAt: false,
+        },
+    });
+    const refreshTable = useRef<() => void>(() => {
+        /* the table replaces this when it mounts */
+    });
+
+    const { data: configData } = useQuery({
+        queryKey: ['mcp-server-config'],
+        queryFn: () => api.query(mcpServerConfigQuery),
+    });
+    const oauthMissing = configData?.mcpServerConfig.oauthConfigured === false;
+
+    const revoke = useMutation({
+        mutationFn: (vars: { id: string }) => api.mutate(revokeMcpOauthGrantMutation, vars),
+        onSuccess: result => {
+            if (result.revokeMcpOauthGrant) {
+                toast.success(t`Grant revoked`);
+            } else {
+                toast.error(t`The grant could not be revoked; it may have already been removed`);
+            }
+            refreshTable.current();
+        },
+        onError: () => {
+            toast.error(t`Could not revoke grant`);
+        },
+    });
+
+    return (
+        <div className="space-y-4">
+            {oauthMissing ? (
+                <Alert>
+                    <InfoIcon className="h-4 w-4" />
+                    <AlertDescription>
+                        <Trans>
+                            OAuth is not configured, so no client can be granted access. Add an oauth block to
+                            McpPlugin.init to use grants.
+                        </Trans>
+                    </AlertDescription>
+                </Alert>
+            ) : null}
+            <PaginatedListDataTable
+                listQuery={mcpOauthGrantsQuery}
+                registerRefresher={refresher => {
+                    refreshTable.current = refresher;
+                }}
+                {...tableState}
+                includeSelectionColumn={false}
+                customizeColumns={{
+                    oauthClientName: {
+                        header: () => <Trans>Client</Trans>,
+                        cell: ({ row }) =>
+                            row.original.oauthClientName ? (
+                                <span className="font-medium">{row.original.oauthClientName}</span>
+                            ) : (
+                                <EmptyCell />
+                            ),
+                    },
+                    actorName: {
+                        header: () => <Trans>Granted to</Trans>,
+                        meta: { dependencies: ['actorType', 'customerId'] },
+                        // No database column to sort or filter by; it's looked up per row.
+                        enableSorting: false,
+                        enableColumnFilter: false,
+                        cell: ({ row }) => (
+                            <ActorCell
+                                actorType={row.original.actorType ?? null}
+                                actorName={row.original.actorName ?? null}
+                                customerId={row.original.customerId ?? null}
+                            />
+                        ),
+                    },
+                    actorType: {
+                        header: () => <Trans>Actor type</Trans>,
+                        cell: ({ row }) =>
+                            row.original.actorType ? (
+                                <Badge variant="outline">{row.original.actorType}</Badge>
+                            ) : (
+                                <EmptyCell />
+                            ),
+                    },
+                    // Fetched only to feed the "Granted to" cell; no database column to sort or filter by.
+                    customerId: { meta: { disabled: true } },
+                    lastActivityAt: { header: () => <Trans>Last activity</Trans> },
+                    expiresAt: { header: () => <Trans>Expires</Trans> },
+                    status: {
+                        header: () => <Trans>Status</Trans>,
+                        cell: ({ row }) => <GrantStatusBadge status={row.original.status} />,
+                    },
+                }}
+                additionalColumns={{
+                    actions: {
+                        header: () => <Trans>Actions</Trans>,
+                        meta: { dependencies: ['id', 'revokedAt'] },
+                        enableHiding: false,
+                        // Shows a disabled control rather than nothing, so the row doesn't look broken.
+                        cell: ({ row }) =>
+                            row.original.revokedAt != null || !canUpdate ? (
+                                <Button
+                                    variant="ghost"
+                                    size="icon"
+                                    disabled
+                                    aria-label={
+                                        row.original.revokedAt != null
+                                            ? t`No actions available for a revoked grant`
+                                            : t`Revoking needs the UpdateMcpServer permission`
+                                    }
+                                >
+                                    <EllipsisIcon />
+                                </Button>
+                            ) : (
+                                <DropdownMenu>
+                                    <DropdownMenuTrigger render={<Button variant="ghost" size="icon" />}>
+                                        <EllipsisIcon />
+                                    </DropdownMenuTrigger>
+                                    <DropdownMenuContent className="min-w-56">
+                                        <DropdownMenuGroup>
+                                            <ConfirmationDialog
+                                                title={t`Revoke grant`}
+                                                description={t`This immediately revokes the client's access. The client will need to authorize again to reconnect.`}
+                                                confirmText={t`Revoke`}
+                                                onConfirm={() => revoke.mutate({ id: row.original.id })}
+                                            >
+                                                <DropdownMenuItem closeOnClick={false}>
+                                                    <div className="flex items-center gap-2">
+                                                        <BanIcon className="w-4 h-4" />
+                                                        <Trans>Revoke</Trans>
+                                                    </div>
+                                                </DropdownMenuItem>
+                                            </ConfirmationDialog>
+                                        </DropdownMenuGroup>
+                                    </DropdownMenuContent>
+                                </DropdownMenu>
+                            ),
+                    },
+                }}
+                // "actions" must stay last, so every other column is named here rather than left to append after it.
+                defaultColumnOrder={[
+                    'oauthClientName',
+                    'actorName',
+                    'actorType',
+                    'status',
+                    'lastActivityAt',
+                    'expiresAt',
+                    'actorId',
+                    'channelId',
+                    'revokedAt',
+                    'actions',
+                ]}
+            />
+        </div>
+    );
+}

package/src/dashboard/components/stats-block.tsx

@@ -0,0 +1,275 @@
+import { Trans, useLingui } from '@lingui/react/macro';
+import {
+    Alert,
+    AlertDescription,
+    api,
+    Empty,
+    EmptyDescription,
+    EmptyHeader,
+    EmptyMedia,
+    EmptyTitle,
+    Link,
+    Progress,
+    Select,
+    SelectContent,
+    SelectItem,
+    SelectTrigger,
+    SelectValue,
+    Skeleton,
+    useQuery,
+} from '@vendure/dashboard';
+import {
+    ActivityIcon,
+    CircleCheckIcon,
+    CircleXIcon,
+    ClockIcon,
+    GaugeIcon,
+    InfoIcon,
+    TrendingUpIcon,
+    TriangleAlert,
+} from 'lucide-react';
+import { useState } from 'react';
+
+import { mcpStatsQuery } from '../mcp.graphql';
+
+import { TooltipButton } from './tooltip-button';
+
+type TimeRange = '1h' | '24h' | '7d' | '30d';
+
+function StatHint({ children }: { children: React.ReactNode }) {
+    const { t } = useLingui();
+    return (
+        <TooltipButton
+            tooltip={children}
+            label={t`What this number means`}
+            className="ml-1 inline-flex h-4 w-4 min-w-0 p-0 align-text-bottom text-muted-foreground"
+        >
+            <InfoIcon className="h-3 w-3" />
+        </TooltipButton>
+    );
+}
+
+function StatTile({
+    icon,
+    label,
+    value,
+    hint,
+    children,
+}: {
+    icon: React.ReactNode;
+    label: React.ReactNode;
+    value: React.ReactNode;
+    hint?: React.ReactNode;
+    children?: React.ReactNode;
+}) {
+    return (
+        <div className="rounded-md border border-border p-3 space-y-1">
+            <div className="flex items-start gap-1.5 text-xs text-muted-foreground">
+                <span className="mt-px shrink-0">{icon}</span>
+                <span>
+                    {label}
+                    {hint ? <StatHint>{hint}</StatHint> : null}
+                </span>
+            </div>
+            <div className="text-2xl font-semibold tabular-nums">{value}</div>
+            {children}
+        </div>
+    );
+}
+
+const regionsClasses = 'grid gap-4 @4xl:grid-cols-3';
+
+const tilesClasses = '@4xl:col-span-2 grid grid-cols-2 @2xl:grid-cols-3 gap-3';
+
+function StatsSkeleton() {
+    return (
+        <div className={regionsClasses}>
+            <div className={tilesClasses}>
+                {Array.from({ length: 6 }).map((_, index) => (
+                    <Skeleton key={index} className="h-19 w-full" />
+                ))}
+            </div>
+            <div className="space-y-2">
+                <Skeleton className="h-5 w-24" />
+                <Skeleton className="h-6 w-full" />
+            </div>
+        </div>
+    );
+}
+
+function TopToolsList({ tools }: { tools: Array<{ toolName: string; count: number }> }) {
+    const topFive = tools.slice(0, 5);
+    const maxCount = Math.max(...topFive.map(tool => tool.count));
+    return (
+        <div className="space-y-2">
+            {topFive.map(tool => (
+                <div key={tool.toolName} className="space-y-1">
+                    <div className="flex items-baseline justify-between gap-3">
+                        <span className="font-mono text-sm truncate">{tool.toolName}</span>
+                        <span className="text-sm tabular-nums text-muted-foreground">{tool.count}</span>
+                    </div>
+                    <div className="h-1 rounded-full bg-primary/20">
+                        <div
+                            className="h-1 rounded-full bg-primary"
+                            style={{ width: `${(tool.count / maxCount) * 100}%` }}
+                        />
+                    </div>
+                </div>
+            ))}
+        </div>
+    );
+}
+
+function NoCallsRecorded() {
+    return (
+        <Empty className="border border-dashed p-6">
+            <EmptyHeader>
+                <EmptyMedia variant="icon">
+                    <ActivityIcon />
+                </EmptyMedia>
+                <EmptyTitle>
+                    <Trans>No tool calls yet</Trans>
+                </EmptyTitle>
+                <EmptyDescription>
+                    <Trans>No calls recorded in this period.</Trans>
+                </EmptyDescription>
+            </EmptyHeader>
+        </Empty>
+    );
+}
+
+function formatLatency(ms: number | null): string {
+    return ms == null ? '—' : `${ms} ms`;
+}
+
+export function StatsBlock() {
+    const { t } = useLingui();
+    const [timeRange, setTimeRange] = useState<TimeRange>('24h');
+
+    const rangeLabels: Record<TimeRange, string> = {
+        '1h': t`Last hour`,
+        '24h': t`Last 24 hours`,
+        '7d': t`Last 7 days`,
+        '30d': t`Last 30 days`,
+    };
+
+    const { data, isLoading, error } = useQuery({
+        queryKey: ['mcp-stats', timeRange],
+        queryFn: () => api.query(mcpStatsQuery, { timeRange }),
+    });
+
+    const stats = data?.mcpStats;
+
+    if (error) {
+        return (
+            <Alert variant="destructive">
+                <TriangleAlert className="h-4 w-4" />
+                <AlertDescription>
+                    <Trans>Error loading MCP statistics: {error.message}</Trans>
+                </AlertDescription>
+            </Alert>
+        );
+    }
+
+    const successRate = stats?.successRate ?? 0;
+    // The API reports the error rate, not a count, so the tile works the count back out.
+    const failedCalls = Math.round((stats?.totalCalls ?? 0) * (stats?.errorRate ?? 0));
+
+    return (
+        <div className="space-y-4">
+            <div className="flex items-center justify-between gap-2">
+                <div className="text-sm text-muted-foreground">
+                    <Trans>Usage over the selected period</Trans>
+                </div>
+                <Select
+                    items={rangeLabels}
+                    value={timeRange}
+                    onValueChange={value => {
+                        if (value) setTimeRange(value);
+                    }}
+                >
+                    <SelectTrigger className="w-40">
+                        <SelectValue />
+                    </SelectTrigger>
+                    <SelectContent>
+                        {(Object.keys(rangeLabels) as TimeRange[]).map(key => (
+                            <SelectItem key={key} value={key}>
+                                {rangeLabels[key]}
+                            </SelectItem>
+                        ))}
+                    </SelectContent>
+                </Select>
+            </div>
+
+            {isLoading && !stats ? (
+                <StatsSkeleton />
+            ) : (
+                <div className={regionsClasses}>
+                    <div className={tilesClasses}>
+                        <StatTile
+                            icon={<ActivityIcon className="h-3.5 w-3.5" />}
+                            label={<Trans>Total calls</Trans>}
+                            value={stats?.totalCalls ?? 0}
+                        />
+                        <StatTile
+                            icon={<CircleCheckIcon className="h-3.5 w-3.5" />}
+                            label={<Trans>Success rate</Trans>}
+                            value={`${(successRate * 100).toFixed(1)}%`}
+                        >
+                            <Progress className="pt-1" value={successRate * 100} />
+                        </StatTile>
+                        <StatTile
+                            icon={<CircleXIcon className="h-3.5 w-3.5" />}
+                            label={<Trans>Failed calls</Trans>}
+                            value={failedCalls}
+                        />
+                        <StatTile
+                            icon={<GaugeIcon className="h-3.5 w-3.5" />}
+                            label={<Trans>p50 latency</Trans>}
+                            value={formatLatency(stats?.p50LatencyMs ?? null)}
+                            hint={<Trans>Half of the calls in this period finished faster than this.</Trans>}
+                        />
+                        <StatTile
+                            icon={<ClockIcon className="h-3.5 w-3.5" />}
+                            label={<Trans>p95 latency</Trans>}
+                            value={formatLatency(stats?.p95LatencyMs ?? null)}
+                            hint={
+                                <Trans>
+                                    95 out of 100 calls in this period finished faster than this. It shows how
+                                    slow the worst calls are.
+                                </Trans>
+                            }
+                        />
+                        <StatTile
+                            icon={<TrendingUpIcon className="h-3.5 w-3.5" />}
+                            label={<Trans>Calls per hour</Trans>}
+                            value={(stats?.callsPerHour ?? 0).toFixed(1)}
+                            hint={
+                                <Trans>Average number of tool calls per hour over the selected period.</Trans>
+                            }
+                        />
+                    </div>
+
+                    <div className="space-y-2">
+                        <div className="text-sm font-medium">
+                            <Trans>Top tools</Trans>
+                        </div>
+                        {stats && stats.topTools.length > 0 ? (
+                            <>
+                                <TopToolsList tools={stats.topTools} />
+                                <Link
+                                    to="/mcp-server/activity"
+                                    className="inline-block text-sm text-primary hover:underline"
+                                >
+                                    <Trans>See all activity</Trans>
+                                </Link>
+                            </>
+                        ) : (
+                            <NoCallsRecorded />
+                        )}
+                    </div>
+                </div>
+            )}
+        </div>
+    );
+}