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

package/src/dashboard/mcp-authorize-route.tsx

@@ -0,0 +1,369 @@
+import { Trans, useLingui } from '@lingui/react/macro';
+import {
+    Alert,
+    AlertDescription,
+    api,
+    Badge,
+    Button,
+    Card,
+    CardContent,
+    CardDescription,
+    CardFooter,
+    CardHeader,
+    CardTitle,
+    ChannelCodeLabel,
+    CopyableText,
+    DashboardRouteDefinition,
+    PermissionGuard,
+    Separator,
+    Skeleton,
+    useAuth,
+    useChannel,
+    useMutation,
+    useQuery,
+    z,
+} from '@vendure/dashboard';
+import { AlertTriangleIcon, ArrowRightIcon, ShieldCheckIcon } from 'lucide-react';
+
+import { OAUTH_ENDPOINT_PATHS } from '../shared/endpoint-paths';
+import { isLoopbackHostname } from '../shared/loopback';
+
+import { TooltipButton } from './components/tooltip-button';
+import { authorizeMcpClientMutation } from './mcp.graphql';
+
+// Mirrors `AuthorizationRequestInfo` from the OAuth service.
+interface AuthRequestInfo {
+    client_id: string;
+    client_id_source: 'cimd' | 'dcr';
+    client_name: string;
+    client_uri?: string;
+    logo_uri?: string;
+    redirect_uri: string;
+    resource: string;
+    toolset: string;
+}
+
+function hostnameOf(uri: string): string | null {
+    try {
+        return new URL(uri).hostname || null;
+    } catch {
+        return null;
+    }
+}
+
+// One shell for loading, failed and real-request states, so the page doesn't jump around.
+function ConsentShell({
+    title,
+    description,
+    children,
+    footer,
+}: {
+    title: React.ReactNode;
+    description?: React.ReactNode;
+    children?: React.ReactNode;
+    footer?: React.ReactNode;
+}) {
+    return (
+        <Card className="w-full max-w-lg">
+            <CardHeader>
+                <CardTitle>{title}</CardTitle>
+                {description ? <CardDescription className="pt-2">{description}</CardDescription> : null}
+            </CardHeader>
+            {children ? <CardContent className="space-y-4">{children}</CardContent> : null}
+            {footer}
+        </Card>
+    );
+}
+
+// Sits by the domain, not the name, because the display name is always chosen by the client itself.
+function HostnameTrustBadge({ verified, metadataUrl }: { verified: boolean; metadataUrl?: string }) {
+    return (
+        <TooltipButton
+            className="inline-flex h-auto p-0"
+            tooltipClassName="max-w-sm space-y-1"
+            tooltip={
+                verified ? (
+                    <>
+                        <p>
+                            <Trans>
+                                The client's details were fetched from this address, so the hostname is
+                                verified. The name above is still chosen by the client itself.
+                            </Trans>
+                        </p>
+                        {metadataUrl ? <p className="font-mono break-all">{metadataUrl}</p> : null}
+                    </>
+                ) : (
+                    <p>
+                        <Trans>
+                            This name and address are reported by the application itself and are not verified.
+                        </Trans>
+                    </p>
+                )
+            }
+        >
+            {verified ? (
+                <Badge variant="success">
+                    <ShieldCheckIcon className="h-3 w-3" />
+                    <Trans>Hostname verified</Trans>
+                </Badge>
+            ) : (
+                <Badge variant="warning">
+                    <Trans>Unverified</Trans>
+                </Badge>
+            )}
+        </TooltipButton>
+    );
+}
+
+// `account`, the signed-in administrator, lets the sentence name whose access is handed over.
+function scopePresentation(toolset: string, account?: { name: string; emailAddress: string }) {
+    if (toolset === 'shop') {
+        return {
+            request: <Trans>wants to access the Shop API of your Vendure server</Trans>,
+            grant: <Trans>Access to the Shop API as a customer.</Trans>,
+        };
+    }
+    const request = <Trans>wants to access the Admin API of your Vendure server</Trans>;
+    if (!account) {
+        return {
+            request,
+            grant: <Trans>Full access to the Admin API as your administrator account.</Trans>,
+        };
+    }
+    const { name, emailAddress } = account;
+    return {
+        request,
+        grant: (
+            <Trans>
+                Full access to the Admin API as {name} ({emailAddress}).
+            </Trans>
+        ),
+    };
+}
+
+function ConsentDetails({
+    info,
+    onApprove,
+    onDeny,
+    isPending,
+    error,
+}: {
+    info: AuthRequestInfo;
+    onApprove: () => void;
+    onDeny: () => void;
+    isPending: boolean;
+    error: Error | null;
+}) {
+    const { t } = useLingui();
+    const { user } = useAuth();
+    // Only used to name the account in the scope sentence.
+    const signedInAccount = user
+        ? { name: `${user.firstName} ${user.lastName}`.trim(), emailAddress: user.emailAddress }
+        : undefined;
+    // The grant is bound to whichever channel the dashboard's channel selector is on.
+    const { activeChannel } = useChannel();
+
+    const redirectHost = hostnameOf(info.redirect_uri);
+    const isCimdClient = info.client_id_source === 'cimd';
+    // A CIMD client's address is the client_id URL its metadata came from; others just report a URI.
+    const clientAddress = isCimdClient ? info.client_id : info.client_uri;
+    const clientDomain = clientAddress ? (hostnameOf(clientAddress) ?? clientAddress) : null;
+    const scope = scopePresentation(info.toolset, signedInAccount);
+    // Amber flags a redirect worth a second look: unverified, plain-http, local, or off the client's host.
+    const isLoopbackRedirect = redirectHost != null && isLoopbackHostname(redirectHost);
+    const clientHost = isCimdClient ? hostnameOf(info.client_id) : null;
+    const redirectLeavesClientHost = clientHost != null && redirectHost !== clientHost;
+    const redirectNeedsWarning =
+        !isCimdClient ||
+        isLoopbackRedirect ||
+        redirectLeavesClientHost ||
+        !info.redirect_uri.startsWith('https://');
+
+    return (
+        <ConsentShell
+            title={info.client_name?.trim() || t`Unnamed application`}
+            description={
+                <div className="space-y-1">
+                    <div className="flex flex-wrap items-center gap-2">
+                        {clientDomain ? <span className="break-all">{clientDomain}</span> : null}
+                        <HostnameTrustBadge
+                            verified={isCimdClient}
+                            metadataUrl={isCimdClient ? info.client_id : undefined}
+                        />
+                    </div>
+                    <div>{scope.request}</div>
+                </div>
+            }
+            footer={
+                <>
+                    {error != null ? (
+                        <CardContent className="w-full pt-0">
+                            <Alert variant="destructive">
+                                <AlertTriangleIcon className="h-4 w-4" />
+                                <AlertDescription>
+                                    <div>
+                                        <Trans>The request could not be completed</Trans>
+                                    </div>
+                                    <div className="break-all">{error.message}</div>
+                                </AlertDescription>
+                            </Alert>
+                        </CardContent>
+                    ) : null}
+                    <CardFooter className="justify-end gap-2">
+                        <Button variant="outline" disabled={isPending} onClick={onDeny}>
+                            <Trans>Deny</Trans>
+                        </Button>
+                        <Button disabled={isPending} onClick={onApprove}>
+                            <Trans>Approve</Trans>
+                        </Button>
+                    </CardFooter>
+                </>
+            }
+        >
+            {/* Only flagged amber when there is something to be wary of, so the warning keeps its meaning. */}
+            <div
+                className={
+                    redirectNeedsWarning
+                        ? 'space-y-2 rounded-md border border-warning/40 bg-warning/5 p-3'
+                        : 'space-y-2 rounded-md border border-border p-3'
+                }
+            >
+                <div className="flex items-start gap-2">
+                    {redirectNeedsWarning ? (
+                        <AlertTriangleIcon className="h-4 w-4 shrink-0 text-warning" />
+                    ) : (
+                        <ArrowRightIcon className="h-4 w-4 shrink-0 text-muted-foreground" />
+                    )}
+                    <CopyableText value={info.redirect_uri}>
+                        <code className="font-mono text-xs break-all">{info.redirect_uri}</code>
+                    </CopyableText>
+                </div>
+                <p className="text-xs text-muted-foreground">
+                    <Trans>
+                        After approval, the authorization code is sent here. Only approve if you recognise
+                        this destination.
+                    </Trans>
+                </p>
+                {isLoopbackRedirect ? (
+                    <p className="text-xs font-medium text-warning">
+                        <Trans>
+                            This destination is on the local machine. Any application running on that machine
+                            could receive the authorization code.
+                        </Trans>
+                    </p>
+                ) : null}
+                {redirectLeavesClientHost ? (
+                    <p className="text-xs font-medium text-warning">
+                        <Trans>
+                            This destination is not on the application's own host ({clientHost}). Only approve
+                            if you expect the code to be sent there.
+                        </Trans>
+                    </p>
+                ) : null}
+            </div>
+
+            <Separator />
+
+            <div className="flex flex-wrap items-center gap-2">
+                <Badge variant="secondary">{info.toolset}</Badge>
+                <span className="text-sm text-muted-foreground">{scope.grant}</span>
+            </div>
+            {info.toolset === 'admin' && activeChannel ? (
+                <p className="text-sm text-muted-foreground">
+                    <Trans>The client will act on this channel:</Trans>{' '}
+                    <span className="font-medium text-foreground">
+                        <ChannelCodeLabel code={activeChannel.code} />
+                    </span>
+                </p>
+            ) : null}
+        </ConsentShell>
+    );
+}
+
+function ConsentCard({ requestToken }: { requestToken: string }) {
+    const { t } = useLingui();
+
+    const {
+        data: info,
+        error,
+        isLoading,
+    } = useQuery({
+        queryKey: ['mcp-authorization-request', requestToken],
+        queryFn: async (): Promise<AuthRequestInfo> => {
+            const res = await fetch(
+                `/${OAUTH_ENDPOINT_PATHS.authorizationRequest}?request_token=${encodeURIComponent(requestToken)}`,
+                { credentials: 'include' },
+            );
+            if (!res.ok) {
+                throw new Error(t`Request failed (${res.status})`);
+            }
+            return res.json() as Promise<AuthRequestInfo>;
+        },
+        // Don't retry: expired/used requests will always fail
+        retry: false,
+        // Clear previous data to avoid showing the wrong app while loading
+        placeholderData: undefined,
+    });
+
+    const authorize = useMutation({
+        mutationFn: (approved: boolean) => api.mutate(authorizeMcpClientMutation, { requestToken, approved }),
+        onSuccess: data => {
+            window.location.href = data.authorizeMcpClient.redirectUrl;
+        },
+    });
+
+    if (isLoading) {
+        return (
+            <ConsentShell
+                title={<Trans>Authorize MCP access</Trans>}
+                description={<Trans>Loading authorization request…</Trans>}
+            >
+                <Skeleton className="h-20 w-full" />
+                <Skeleton className="h-5 w-2/3" />
+            </ConsentShell>
+        );
+    }
+
+    if (error || !info) {
+        return (
+            <ConsentShell title={<Trans>Authorization request could not be loaded</Trans>}>
+                <p className="text-sm">
+                    <Trans>
+                        The link may have expired or already been used. Start the connection again from your
+                        MCP client.
+                    </Trans>
+                </p>
+                {/* Shown as a detail, not the reason, since the response doesn't say why it failed. */}
+                {error?.message ? (
+                    <p className="text-xs text-muted-foreground break-all">{error.message}</p>
+                ) : null}
+            </ConsentShell>
+        );
+    }
+
+    return (
+        <ConsentDetails
+            info={info}
+            onApprove={() => authorize.mutate(true)}
+            onDeny={() => authorize.mutate(false)}
+            isPending={authorize.isPending}
+            error={authorize.error}
+        />
+    );
+}
+
+export const mcpAuthorizeRoute: DashboardRouteDefinition = {
+    path: '/mcp/authorize',
+    loader: () => ({ breadcrumb: () => <Trans>Authorize MCP Client</Trans> }),
+    validateSearch: search => z.object({ request_token: z.string() }).parse(search),
+    component: route => {
+        const { request_token: requestToken } = route.useSearch();
+        return (
+            <PermissionGuard requires={['UpdateMcpServer']}>
+                <div className="flex justify-center p-8">
+                    <ConsentCard requestToken={requestToken} />
+                </div>
+            </PermissionGuard>
+        );
+    },
+};

package/src/dashboard/mcp-grants-route.tsx

@@ -0,0 +1,38 @@
+import { Trans } from '@lingui/react/macro';
+import {
+    DashboardRouteDefinition,
+    Page,
+    PageBlock,
+    PageLayout,
+    PageTitle,
+    PermissionGuard,
+} from '@vendure/dashboard';
+
+import { GrantsBlock } from './components/grants-block';
+
+export const mcpGrantsRoute: DashboardRouteDefinition = {
+    navMenuItem: {
+        sectionId: 'mcp-server',
+        id: 'mcp-server-grants',
+        url: '/mcp-server/grants',
+        title: 'Grants',
+        order: 400,
+        requiresPermission: 'ReadMcpServer',
+    },
+    path: '/mcp-server/grants',
+    loader: () => ({ breadcrumb: () => <Trans>Grants</Trans> }),
+    component: () => (
+        <Page pageId="mcp-server-grants">
+            <PageTitle>
+                <Trans>Grants</Trans>
+            </PageTitle>
+            <PermissionGuard requires={['ReadMcpServer']}>
+                <PageLayout>
+                    <PageBlock column="full" blockId="mcp-grants">
+                        <GrantsBlock />
+                    </PageBlock>
+                </PageLayout>
+            </PermissionGuard>
+        </Page>
+    ),
+};

package/src/dashboard/mcp-overview-route.tsx

@@ -0,0 +1,46 @@
+import { Trans } from '@lingui/react/macro';
+import {
+    ActionBarItem,
+    DashboardRouteDefinition,
+    Page,
+    PageActionBar,
+    PageBlock,
+    PageLayout,
+    PageTitle,
+    PermissionGuard,
+} from '@vendure/dashboard';
+
+import { ConnectionDialog } from './components/connection-dialog';
+import { StatsBlock } from './components/stats-block';
+
+export const mcpOverviewRoute: DashboardRouteDefinition = {
+    navMenuItem: {
+        sectionId: 'mcp-server',
+        id: 'mcp-server-overview',
+        url: '/mcp-server/overview',
+        title: 'Overview',
+        order: 100,
+        requiresPermission: 'ReadMcpServer',
+    },
+    path: '/mcp-server/overview',
+    loader: () => ({ breadcrumb: () => <Trans>Overview</Trans> }),
+    component: () => (
+        <Page pageId="mcp-server-overview">
+            <PageTitle>
+                <Trans>MCP Server</Trans>
+            </PageTitle>
+            <PageActionBar>
+                <ActionBarItem itemId="mcp-connect-client">
+                    <ConnectionDialog />
+                </ActionBarItem>
+            </PageActionBar>
+            <PermissionGuard requires={['ReadMcpServer']}>
+                <PageLayout>
+                    <PageBlock column="full" blockId="mcp-stats" title={<Trans>Health & usage</Trans>}>
+                        <StatsBlock />
+                    </PageBlock>
+                </PageLayout>
+            </PermissionGuard>
+        </Page>
+    ),
+};

package/src/dashboard/mcp-server-redirect-route.tsx

@@ -0,0 +1,15 @@
+import { DashboardRouteDefinition, useNavigate } from '@vendure/dashboard';
+import { useEffect } from 'react';
+
+function McpServerRedirect() {
+    const navigate = useNavigate();
+    useEffect(() => {
+        void navigate({ to: '/mcp-server/overview', replace: true });
+    }, [navigate]);
+    return null;
+}
+
+export const mcpServerRedirectRoute: DashboardRouteDefinition = {
+    path: '/mcp-server',
+    component: () => <McpServerRedirect />,
+};

package/src/dashboard/mcp-tools-route.tsx

@@ -0,0 +1,38 @@
+import { Trans } from '@lingui/react/macro';
+import {
+    DashboardRouteDefinition,
+    Page,
+    PageBlock,
+    PageLayout,
+    PageTitle,
+    PermissionGuard,
+} from '@vendure/dashboard';
+
+import { ToolsBlock } from './components/tools-block';
+
+export const mcpToolsRoute: DashboardRouteDefinition = {
+    navMenuItem: {
+        sectionId: 'mcp-server',
+        id: 'mcp-server-tools',
+        url: '/mcp-server/tools',
+        title: 'Tools',
+        order: 200,
+        requiresPermission: 'ReadMcpServer',
+    },
+    path: '/mcp-server/tools',
+    loader: () => ({ breadcrumb: () => <Trans>Tools</Trans> }),
+    component: () => (
+        <Page pageId="mcp-server-tools">
+            <PageTitle>
+                <Trans>Tools</Trans>
+            </PageTitle>
+            <PermissionGuard requires={['ReadMcpServer']}>
+                <PageLayout>
+                    <PageBlock column="full" blockId="mcp-tools">
+                        <ToolsBlock />
+                    </PageBlock>
+                </PageLayout>
+            </PermissionGuard>
+        </Page>
+    ),
+};

package/src/dashboard/mcp.graphql.ts

@@ -0,0 +1,127 @@
+import { graphql as dashboardGraphql } from '@vendure/dashboard';
+import type { initGraphQLTada } from 'gql.tada';
+import type { introspection } from '../../codegen/generated/graphql-env.d.ts';
+
+// The dashboard's `graphql` is typed against the core Admin API only. It parses a query the same
+// way whatever schema it is typed with, so it is retyped here against this plugin's schema. That
+// keeps the queries typed without asking the project that installs the plugin for an `@/gql` alias.
+const graphql = dashboardGraphql as unknown as ReturnType<
+    typeof initGraphQLTada<{
+        disableMasking: true;
+        introspection: introspection;
+        scalars: {
+            DateTime: string;
+            JSON: any;
+            Money: number;
+        };
+    }>
+>;
+
+// A mismatch with src/api/api-extensions.ts stops the dashboard code compiling.
+
+export const mcpToolsQuery = graphql(`
+    query McpTools {
+        mcpTools {
+            id
+            name
+            toolset
+            description
+            pluginSource
+            behavior
+            enabled
+        }
+    }
+`);
+
+export const mcpServerConfigQuery = graphql(`
+    query McpServerConfig {
+        mcpServerConfig {
+            toolExposure
+            shopAccess
+            oauthConfigured
+            issuer
+        }
+    }
+`);
+
+export const mcpStatsQuery = graphql(`
+    query McpStats($timeRange: String) {
+        mcpStats(timeRange: $timeRange) {
+            totalCalls
+            successRate
+            errorRate
+            p50LatencyMs
+            p95LatencyMs
+            callsPerHour
+            topTools {
+                toolName
+                count
+            }
+        }
+    }
+`);
+
+export const mcpToolCallLogsQuery = graphql(`
+    query McpToolCallLogs($options: McpToolCallLogListOptions) {
+        mcpToolCallLogs(options: $options) {
+            items {
+                id
+                createdAt
+                toolName
+                actor
+                actorType
+                actorName
+                customerId
+                status
+                durationMs
+                pluginSource
+            }
+            totalItems
+        }
+    }
+`);
+
+export const mcpOauthGrantsQuery = graphql(`
+    query McpOauthGrants($options: McpOauthGrantListOptions) {
+        mcpOauthGrants(includeInactive: true, options: $options) {
+            items {
+                id
+                createdAt
+                updatedAt
+                actorId
+                actorType
+                actorName
+                customerId
+                channelId
+                oauthClientName
+                lastActivityAt
+                expiresAt
+                revokedAt
+                status
+            }
+            totalItems
+        }
+    }
+`);
+
+export const setMcpToolEnabledMutation = graphql(`
+    mutation SetMcpToolEnabled($toolName: String!, $toolset: McpToolset!, $enabled: Boolean!) {
+        setMcpToolEnabled(toolName: $toolName, toolset: $toolset, enabled: $enabled) {
+            enabled
+        }
+    }
+`);
+
+export const revokeMcpOauthGrantMutation = graphql(`
+    mutation RevokeMcpOauthGrant($id: ID!) {
+        revokeMcpOauthGrant(id: $id)
+    }
+`);
+
+export const authorizeMcpClientMutation = graphql(`
+    mutation AuthorizeMcpClient($requestToken: String!, $approved: Boolean!) {
+        authorizeMcpClient(requestToken: $requestToken, approved: $approved) {
+            redirectUrl
+        }
+    }
+`);

package/src/dashboard/published-files.spec.ts

@@ -0,0 +1,54 @@
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+/**
+ * The dashboard sources are shipped as-is and compiled by the consumer's Vite build, so every
+ * relative import they make must point at a file that the package.json `files` list publishes.
+ */
+describe('published dashboard sources', () => {
+    const packageRoot = resolve(__dirname, '../..');
+    const dashboardDir = join(packageRoot, 'src/dashboard');
+    // Mirrors the `files` list in package.json: only these source folders reach the published package.
+    const publishedSourceDirs = ['src/dashboard/', 'src/shared/'];
+
+    function isPublished(relativePath: string): boolean {
+        return publishedSourceDirs.some(dir => relativePath.startsWith(dir));
+    }
+
+    function sourceFiles(dir: string): string[] {
+        return readdirSync(dir).flatMap(name => {
+            const full = join(dir, name);
+            if (statSync(full).isDirectory()) {
+                return sourceFiles(full);
+            }
+            return /\.(ts|tsx)$/.test(name) && !name.endsWith('.spec.ts') ? [full] : [];
+        });
+    }
+
+    function resolveImport(fromFile: string, specifier: string): string | undefined {
+        const base = resolve(dirname(fromFile), specifier);
+        for (const candidate of [base, `${base}.ts`, `${base}.tsx`, join(base, 'index.ts'), join(base, 'index.tsx')]) {
+            if (existsSync(candidate) && statSync(candidate).isFile()) {
+                return candidate;
+            }
+        }
+        return undefined;
+    }
+
+    it('only imports files that the package publishes', () => {
+        const unpublished: string[] = [];
+        for (const file of sourceFiles(dashboardDir)) {
+            // The build drops type-only imports, so their targets never need publishing.
+            const source = readFileSync(file, 'utf8').replace(/^import type [^;]+;/gm, '');
+            for (const match of source.matchAll(/from\s+'(\.[^']+)'/g)) {
+                const target = resolveImport(file, match[1]);
+                expect(target, `${relative(packageRoot, file)} imports ${match[1]}`).toBeDefined();
+                if (target && !isPublished(relative(packageRoot, target))) {
+                    unpublished.push(`${relative(packageRoot, file)} -> ${relative(packageRoot, target)}`);
+                }
+            }
+        }
+        expect(unpublished).toEqual([]);
+    });
+});