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

package/lib/api/api-extensions.d.ts

@@ -0,0 +1,2 @@
+export declare const adminApiExtensions: import("graphql").DocumentNode;
+export declare const shopApiExtensions: import("graphql").DocumentNode;

package/lib/api/api-extensions.js

@@ -0,0 +1,239 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shopApiExtensions = exports.adminApiExtensions = void 0;
+const graphql_tag_1 = require("graphql-tag");
+exports.adminApiExtensions = (0, graphql_tag_1.gql) `
+    "Which endpoint a tool is served from."
+    enum McpToolset {
+        shop
+        admin
+    }
+
+    "What a tool does to data: readonly tools only read it, mutating tools change it, and destructive tools ask for confirmation first."
+    enum McpToolBehavior {
+        readonly
+        mutating
+        destructive
+    }
+
+    "Whether an administrator or a customer approved an OAuth grant."
+    enum McpGrantUserType {
+        customer
+        admin
+    }
+
+    "Who a tool call ran as. anonymous means nobody was signed in."
+    enum McpActorType {
+        customer
+        admin
+        anonymous
+    }
+
+    "The three states an OAuth grant can be in."
+    enum McpOauthGrantStatus {
+        active
+        expired
+        revoked
+    }
+
+    "Whether a logged tool call succeeded or failed."
+    enum McpToolCallStatus {
+        success
+        error
+    }
+
+    "Whether clients see every tool directly, or only the two discovery tools."
+    enum McpToolExposureMode {
+        direct
+        discovery
+    }
+
+    "Who the shop endpoint accepts: anyone, signed-in customers only, or nobody."
+    enum McpShopAccess {
+        anonymous
+        authenticated
+        disabled
+    }
+
+    "A registered tool and whether it is currently enabled."
+    type McpToolInfo {
+        id: ID!
+        name: String!
+        toolset: McpToolset!
+        description: String!
+        pluginSource: String!
+        behavior: McpToolBehavior!
+        enabled: Boolean!
+    }
+
+    "An OAuth grant, summarised for the admin overview. Revoked and expired grants are included only when requested."
+    type McpOauthGrant implements Node {
+        id: ID!
+        createdAt: DateTime!
+        updatedAt: DateTime!
+        actorId: String
+        actorType: McpGrantUserType
+        "The name of the person who approved the grant. Null when the account no longer exists."
+        actorName: String
+        "The Customer id when the grant was approved by a customer, so the dashboard can link to them. Null otherwise."
+        customerId: ID
+        channelId: ID
+        oauthClientName: String
+        lastActivityAt: DateTime!
+        expiresAt: DateTime!
+        revokedAt: DateTime
+        "Worked out from revokedAt and expiresAt rather than stored, so it is always current."
+        status: McpOauthGrantStatus!
+    }
+
+    type McpOauthGrantList implements PaginatedList {
+        items: [McpOauthGrant!]!
+        totalItems: Int!
+    }
+
+    """
+    One logged tool call. input and output are null unless the server is set to
+    capture full call bodies and the caller also holds the ReadCustomer permission.
+    """
+    type McpToolCallLog implements Node {
+        id: ID!
+        createdAt: DateTime!
+        updatedAt: DateTime!
+        grantId: ID
+        "The id of the Vendure user the call ran as. Null when nobody was signed in."
+        actor: String
+        actorType: McpActorType!
+        "The name of the person the call ran as. Null when nobody was signed in or the account no longer exists."
+        actorName: String
+        "The Customer id when the call ran as a customer, so the dashboard can link to them. Null otherwise."
+        customerId: ID
+        "Stored only when logging.captureClientIp is enabled. Requires the ReadCustomer permission to read."
+        clientIp: String
+        channelId: ID
+        toolName: String!
+        pluginSource: String
+        input: JSON
+        output: JSON
+        durationMs: Int
+        status: McpToolCallStatus!
+        oauthClientId: ID
+    }
+
+    type McpToolCallLogList implements PaginatedList {
+        items: [McpToolCallLog!]!
+        totalItems: Int!
+    }
+
+    type McpTopTool {
+        toolName: String!
+        count: Int!
+    }
+
+    type McpStats {
+        totalCalls: Int!
+        successRate: Float!
+        errorRate: Float!
+        p50LatencyMs: Int
+        p95LatencyMs: Int
+        callsPerHour: Float!
+        topTools: [McpTopTool!]!
+    }
+
+    "How this MCP server is configured, so the dashboard can show only what applies."
+    type McpServerConfig {
+        toolExposure: McpToolExposureMode!
+        shopAccess: McpShopAccess!
+        "Whether an oauth block is configured. Without it the admin endpoint and grants cannot be used."
+        oauthConfigured: Boolean!
+        "The OAuth issuer origin, or null when OAuth is not configured."
+        issuer: String
+    }
+
+    extend type Query {
+        "Every registered tool with its enabled state."
+        mcpTools: [McpToolInfo!]!
+        "OAuth grants, newest activity first. Lists active grants by default; pass includeInactive: true to also include revoked and expired ones."
+        mcpOauthGrants(
+            includeInactive: Boolean! = false
+            options: McpOauthGrantListOptions
+        ): McpOauthGrantList!
+        "The tool-call log, paginated and filterable."
+        mcpToolCallLogs(options: McpToolCallLogListOptions): McpToolCallLogList!
+        "Usage stats for a time window. timeRange is one of 1h, 24h, 7d, 30d (default 24h); other values are rejected."
+        mcpStats(timeRange: String): McpStats!
+        "The server-side configuration the dashboard needs to explain its own pages."
+        mcpServerConfig: McpServerConfig!
+    }
+
+    "Where to send the browser once an administrator has approved or denied an MCP client."
+    type McpAuthorizationResult {
+        redirectUrl: String!
+    }
+
+    extend type Mutation {
+        "Enable or disable a tool. Returns the tool with its new state."
+        setMcpToolEnabled(toolName: String!, toolset: McpToolset!, enabled: Boolean!): McpToolInfo!
+        "Revoke an OAuth grant. Returns false if no grant has that id."
+        revokeMcpOauthGrant(id: ID!): Boolean!
+        "Delete tool-call logs past the retention window. Returns how many were deleted."
+        removeExpiredMcpToolCallLogs: Int!
+        """
+        Records the signed-in administrator's decision on a pending MCP authorization request.
+        Both approval and denial require the UpdateMcpServer permission.
+        """
+        authorizeMcpClient(requestToken: String!, approved: Boolean!): McpAuthorizationResult!
+    }
+
+    # Auto-generated at runtime
+    input McpToolCallLogListOptions
+
+    # Auto-generated at runtime
+    input McpOauthGrantListOptions
+
+    # Vendure builds the sort and filter inputs from these types at run time, but it only offers
+    # scalar fields for sorting. Declaring the enum-typed columns here keeps them sortable; the
+    # generator merges these fields into the input it builds.
+    input McpToolCallLogSortParameter {
+        actorType: SortOrder
+        status: SortOrder
+    }
+
+    input McpOauthGrantSortParameter {
+        actorType: SortOrder
+        status: SortOrder
+    }
+`;
+exports.shopApiExtensions = (0, graphql_tag_1.gql) `
+    "Where to send the browser once a customer has approved or denied an MCP client."
+    type McpAuthorizationResult {
+        redirectUrl: String!
+    }
+
+    "One of the signed-in customer's own active MCP OAuth grants, summarised for a connected-assistants page."
+    type McpCustomerOauthGrantInfo {
+        id: ID!
+        createdAt: DateTime!
+        oauthClientName: String
+        lastActivityAt: DateTime!
+        expiresAt: DateTime!
+    }
+
+    extend type Query {
+        "The signed-in customer's own active (not revoked, not expired) MCP OAuth grants, across every channel."
+        activeMcpClientGrants: [McpCustomerOauthGrantInfo!]!
+    }
+
+    extend type Mutation {
+        """
+        Records the signed-in customer's decision on a pending MCP authorization request.
+        Denial does not require a signed-in customer; approval does.
+        """
+        authorizeMcpClient(requestToken: String!, approved: Boolean!): McpAuthorizationResult!
+        """
+        Revokes one of the signed-in customer's own MCP OAuth grants. Throws if no such grant
+        exists for the signed-in customer.
+        """
+        revokeMcpClientGrant(id: ID!): Boolean!
+    }
+`;
+//# sourceMappingURL=api-extensions.js.map

package/lib/api/api-extensions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api-extensions.js","sourceRoot":"","sources":["../../src/api/api-extensions.ts"],"names":[],"mappings":";;;AAAA,6CAAkC;AAErB,QAAA,kBAAkB,GAAG,IAAA,iBAAG,EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwMpC,CAAC;AAEW,QAAA,iBAAiB,GAAG,IAAA,iBAAG,EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgCnC,CAAC"}

package/lib/api/mcp-actor.service.d.ts

@@ -0,0 +1,19 @@
+import { AdministratorService, CustomerService, ID, RequestContext, RequestContextCacheService } from '@vendure/core';
+import { McpActorType, McpGrantUserType } from '../types';
+interface McpActorIdentity {
+    name: string | null;
+    customerId: ID | null;
+}
+/**
+ * Turns the user id stored on a tool-call log or an OAuth grant into a display name, and into a
+ * Customer id when the user is a customer.
+ */
+export declare class McpActorService {
+    private readonly customerService;
+    private readonly administratorService;
+    private readonly requestContextCache;
+    constructor(customerService: CustomerService, administratorService: AdministratorService, requestContextCache: RequestContextCacheService);
+    resolveIdentity(ctx: RequestContext, userId: ID | string | null | undefined, actorType: McpActorType | McpGrantUserType | null | undefined): Promise<McpActorIdentity>;
+    private lookUpIdentity;
+}
+export {};

package/lib/api/mcp-actor.service.js

@@ -0,0 +1,52 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpActorService = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@vendure/core");
+const NO_ACTOR = { name: null, customerId: null };
+function fullName(person) {
+    return `${person.firstName} ${person.lastName}`.trim();
+}
+/**
+ * Turns the user id stored on a tool-call log or an OAuth grant into a display name, and into a
+ * Customer id when the user is a customer.
+ */
+let McpActorService = class McpActorService {
+    constructor(customerService, administratorService, requestContextCache) {
+        this.customerService = customerService;
+        this.administratorService = administratorService;
+        this.requestContextCache = requestContextCache;
+    }
+    // Cached for the request's lifetime, since a list page asks for the same actor on many rows.
+    resolveIdentity(ctx, userId, actorType) {
+        if (userId == null || actorType == null || actorType === 'anonymous') {
+            return Promise.resolve(NO_ACTOR);
+        }
+        return this.requestContextCache.get(ctx, `McpActorService:${actorType}:${String(userId)}`, () => this.lookUpIdentity(ctx, userId, actorType));
+    }
+    async lookUpIdentity(ctx, userId, actorType) {
+        if (actorType === 'customer') {
+            const customer = await this.customerService.findOneByUserId(ctx, userId);
+            return customer ? { name: fullName(customer), customerId: customer.id } : NO_ACTOR;
+        }
+        const administrator = await this.administratorService.findOneByUserId(ctx, userId);
+        return administrator ? { name: fullName(administrator), customerId: null } : NO_ACTOR;
+    }
+};
+exports.McpActorService = McpActorService;
+exports.McpActorService = McpActorService = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [core_1.CustomerService,
+        core_1.AdministratorService,
+        core_1.RequestContextCacheService])
+], McpActorService);
+//# sourceMappingURL=mcp-actor.service.js.map

package/lib/api/mcp-actor.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-actor.service.js","sourceRoot":"","sources":["../../src/api/mcp-actor.service.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,2CAA4C;AAC5C,wCAMuB;AASvB,MAAM,QAAQ,GAAqB,EAAE,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;AAEpE,SAAS,QAAQ,CAAC,MAA+C;IAC7D,OAAO,GAAG,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC;AAC3D,CAAC;AAED;;;GAGG;AAEI,IAAM,eAAe,GAArB,MAAM,eAAe;IACxB,YACqB,eAAgC,EAChC,oBAA0C,EAC1C,mBAA+C;QAF/C,oBAAe,GAAf,eAAe,CAAiB;QAChC,yBAAoB,GAApB,oBAAoB,CAAsB;QAC1C,wBAAmB,GAAnB,mBAAmB,CAA4B;IACjE,CAAC;IAEJ,6FAA6F;IAC7F,eAAe,CACX,GAAmB,EACnB,MAAsC,EACtC,SAA6D;QAE7D,IAAI,MAAM,IAAI,IAAI,IAAI,SAAS,IAAI,IAAI,IAAI,SAAS,KAAK,WAAW,EAAE,CAAC;YACnE,OAAO,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACrC,CAAC;QACD,OAAO,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,GAAG,EAAE,mBAAmB,SAAS,IAAI,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,CAC5F,IAAI,CAAC,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,CAC9C,CAAC;IACN,CAAC;IAEO,KAAK,CAAC,cAAc,CACxB,GAAmB,EACnB,MAAmB,EACnB,SAA0C;QAE1C,IAAI,SAAS,KAAK,UAAU,EAAE,CAAC;YAC3B,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,eAAe,CAAC,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YACzE,OAAO,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,QAAQ,CAAC,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;QACvF,CAAC;QACD,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC,oBAAoB,CAAC,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACnF,OAAO,aAAa,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,aAAa,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC1F,CAAC;CACJ,CAAA;AAjCY,0CAAe;0BAAf,eAAe;IAD3B,IAAA,mBAAU,GAAE;qCAG6B,sBAAe;QACV,2BAAoB;QACrB,iCAA0B;GAJ3D,eAAe,CAiC3B"}

package/lib/api/mcp-admin.resolver.d.ts

@@ -0,0 +1,105 @@
+import { CacheService, ID, ListQueryBuilder, ListQueryOptions, RequestContext, TransactionalConnection } from '@vendure/core';
+import { McpToolBehavior, McpToolset } from '@vendure/mcp-sdk';
+import { McpOauthGrant, McpToolCallLog } from '../entities';
+import { ResolvedMcpPluginOptions } from '../internal-types';
+import { McpToolCallLogRetentionService } from '../logging/mcp-tool-call-log-retention.service';
+import { McpOauthService } from '../oauth/oauth.service';
+import { McpToolRegistryService } from '../registry/mcp-tool-registry.service';
+import { McpToolExposureMode } from '../types';
+import { McpActorService } from './mcp-actor.service';
+/** A registered tool and whether it is currently enabled. */
+interface McpToolInfo {
+    id: string;
+    name: string;
+    toolset: McpToolset;
+    description: string;
+    pluginSource: string;
+    behavior: McpToolBehavior;
+    enabled: boolean;
+}
+type McpStats = {
+    totalCalls: number;
+    successRate: number;
+    errorRate: number;
+    p50LatencyMs: number | null;
+    p95LatencyMs: number | null;
+    callsPerHour: number;
+    topTools: Array<{
+        toolName: string;
+        count: number;
+    }>;
+};
+/** How this MCP server is configured, so the dashboard can show only what applies. */
+interface McpServerConfig {
+    toolExposure: McpToolExposureMode;
+    shopAccess: NonNullable<ResolvedMcpPluginOptions['shopAccess']>;
+    oauthConfigured: boolean;
+    issuer: string | null;
+}
+export declare class McpAdminResolver {
+    private readonly connection;
+    private readonly registry;
+    private readonly oauthService;
+    private readonly cacheService;
+    private readonly listQueryBuilder;
+    private readonly options;
+    private readonly toolCallLogRetention;
+    constructor(connection: TransactionalConnection, registry: McpToolRegistryService, oauthService: McpOauthService, cacheService: CacheService, listQueryBuilder: ListQueryBuilder, options: ResolvedMcpPluginOptions, toolCallLogRetention: McpToolCallLogRetentionService);
+    mcpTools(ctx: RequestContext): Promise<McpToolInfo[]>;
+    mcpOauthGrants(ctx: RequestContext, args: {
+        includeInactive: boolean;
+        options?: ListQueryOptions<McpOauthGrant>;
+    }): Promise<{
+        items: McpOauthGrant[];
+        totalItems: number;
+    }>;
+    mcpToolCallLogs(ctx: RequestContext, args: {
+        options?: ListQueryOptions<McpToolCallLog>;
+    }): Promise<{
+        items: McpToolCallLog[];
+        totalItems: number;
+    }>;
+    mcpStats(ctx: RequestContext, args: {
+        timeRange?: string;
+    }): Promise<McpStats>;
+    mcpServerConfig(): McpServerConfig;
+    setMcpToolEnabled(ctx: RequestContext, args: {
+        toolName: string;
+        toolset: McpToolset;
+        enabled: boolean;
+    }): Promise<McpToolInfo>;
+    revokeMcpOauthGrant(ctx: RequestContext, args: {
+        id: ID;
+    }): Promise<boolean>;
+    removeExpiredMcpToolCallLogs(ctx: RequestContext): Promise<number>;
+    authorizeMcpClient(ctx: RequestContext, args: {
+        requestToken: string;
+        approved: boolean;
+    }): Promise<{
+        redirectUrl: string;
+    }>;
+    private toToolInfo;
+    private computeStats;
+    private durationPercentiles;
+    private windowedQuery;
+    private limitToWindow;
+    private scopeToChannel;
+    private applyDefaultOrder;
+}
+export declare class McpToolCallLogEntityResolver {
+    private readonly actorService;
+    constructor(actorService: McpActorService);
+    input(log: McpToolCallLog, ctx: RequestContext): unknown;
+    output(log: McpToolCallLog, ctx: RequestContext): unknown;
+    clientIp(log: McpToolCallLog, ctx: RequestContext): string | null;
+    actorName(log: McpToolCallLog, ctx: RequestContext): Promise<string | null>;
+    customerId(log: McpToolCallLog, ctx: RequestContext): Promise<ID | null>;
+}
+export declare class McpOauthGrantEntityResolver {
+    private readonly actorService;
+    constructor(actorService: McpActorService);
+    oauthClientName(grant: McpOauthGrant): string | null;
+    actorName(grant: McpOauthGrant, ctx: RequestContext): Promise<string | null>;
+    customerId(grant: McpOauthGrant, ctx: RequestContext): Promise<ID | null>;
+}
+export {};