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

package/lib/registry/mcp-tool-registry.service.js

@@ -0,0 +1,668 @@
+"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);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var __rest = (this && this.__rest) || function (s, e) {
+    var t = {};
+    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
+        t[p] = s[p];
+    if (s != null && typeof Object.getOwnPropertySymbols === "function")
+        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
+            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
+                t[p[i]] = s[p[i]];
+        }
+    return t;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpToolRegistryService = void 0;
+const common_1 = require("@nestjs/common");
+const core_1 = require("@nestjs/core");
+const core_2 = require("@vendure/core");
+const mcp_sdk_1 = require("@vendure/mcp-sdk");
+const constants_1 = require("../constants");
+const mcp_tool_call_log_service_1 = require("../logging/mcp-tool-call-log.service");
+const mcp_rate_limiter_service_1 = require("../rate-limit/mcp-rate-limiter.service");
+const mcp_shop_session_service_1 = require("../shop-session/mcp-shop-session.service");
+const bm25_1 = require("./bm25");
+const mcp_tool_schema_service_1 = require("./mcp-tool-schema.service");
+/** Discovery meta-tool names — reserved so user tools cannot collide with them. */
+const SEARCH_TOOLS = 'search_tools';
+const EXECUTE_TOOL = 'execute_tool';
+const RESERVED_META_TOOL_NAMES = new Set([SEARCH_TOOLS, EXECUTE_TOOL]);
+const ALL_TOOLSETS = ['shop', 'admin'];
+// Also stated in the no-results hint and the meta-tool's schema description; keep all three in sync.
+const SEARCH_DEFAULT_LIMIT = 10;
+const SEARCH_MAX_LIMIT = 50;
+// Error types a tool throws on purpose, with a message meant to be read by the caller. Anything
+// else is treated as an internal failure: logged server-side, and the caller gets a generic
+// message instead.
+const CALLER_SAFE_ERROR_TYPES = [
+    core_2.UserInputError,
+    core_2.IllegalOperationError,
+    core_2.EntityNotFoundError,
+    core_2.ForbiddenError,
+    core_2.UnauthorizedError,
+];
+const GENERIC_TOOL_ERROR_MESSAGE = 'The tool failed unexpectedly. This is a server-side fault, not a problem with your ' +
+    'arguments. Do not retry with different arguments; tell the user the operation could not ' +
+    'be completed.';
+// Largest serialized result text a tool may return, in bytes. 100 KB is roughly 25,000 tokens,
+// which is the cap Claude Code applies to a tool response before it truncates the text.
+const MAX_RESULT_BYTES = 100000;
+// The arguments a caller can use to ask for less, and how the size error tells them to. Only the
+// ones a tool actually declares are mentioned, so the advice is always something they can do.
+const NARROWING_ARGUMENT_ADVICE = {
+    limit: 'lower "limit"',
+    offset: 'page with "offset"',
+    filter: 'add a "filter"',
+    query: 'narrow the "query"',
+};
+// Enforce SEP-986 because some MCP clients reject non-conforming tool names.
+const TOOL_NAME_PATTERN = /^[A-Za-z0-9._-]{1,128}$/;
+/**
+ * @description
+ * Single source of truth for discovered `@McpTool` providers. It discovers tools at bootstrap,
+ * compiles their schemas once, and owns visibility, toggles, behavior,
+ * permissions, and execution.
+ */
+let McpToolRegistryService = class McpToolRegistryService {
+    constructor(discoveryService, settingsStoreService, rateLimiter, toolCallLog, toolSchema, shopSession, configService, connection, options) {
+        this.discoveryService = discoveryService;
+        this.settingsStoreService = settingsStoreService;
+        this.rateLimiter = rateLimiter;
+        this.toolCallLog = toolCallLog;
+        this.toolSchema = toolSchema;
+        this.shopSession = shopSession;
+        this.configService = configService;
+        this.connection = connection;
+        this.options = options;
+        this.tools = new Map();
+        this.discoveryMetaTools = [];
+        this.bm25 = new Map();
+        this.toggleCache = new WeakMap();
+    }
+    /** @internal */
+    onApplicationBootstrap() {
+        this.discoverTools();
+        this.discoveryMetaTools = this.buildDiscoveryMetaTools();
+        this.bm25 = this.buildSearchIndexes();
+    }
+    /**
+     * Every registered tool. Consumed by the admin API.
+     *
+     * @internal
+     */
+    getRegistrySnapshot() {
+        return [...this.tools.values()];
+    }
+    /** @internal */
+    async getExposedTools(executionContext, toolset) {
+        if (this.options.toolExposure === 'discovery') {
+            return this.discoveryMetaTools;
+        }
+        return this.visibleTools(executionContext.ctx, toolset);
+    }
+    async callTool(executionContext, toolset, name, input) {
+        if (this.options.toolExposure === 'discovery') {
+            if (name === SEARCH_TOOLS) {
+                return this.searchTools(executionContext, toolset, input);
+            }
+            if (name === EXECUTE_TOOL) {
+                // The SDK validated only the envelope, so the tool's own arguments are validated here.
+                const { name: innerName, arguments: args } = input;
+                return this.callRegisteredTool(executionContext, toolset, innerName, args !== null && args !== void 0 ? args : {}, {
+                    validateInput: true,
+                });
+            }
+        }
+        return this.callRegisteredTool(executionContext, toolset, name, input, { validateInput: false });
+    }
+    async getCallableTools(ctx, toolset) {
+        return (await this.visibleTools(ctx, toolset)).map(tool => this.toolSummary(tool));
+    }
+    /**
+     * Skips the meta-tool routing in {@link callTool}, since a caller using this already knows which tool it wants.
+     *
+     * @internal
+     */
+    callToolDirect(executionContext, toolset, name, input) {
+        return this.callRegisteredTool(executionContext, toolset, name, input, { validateInput: true });
+    }
+    async getToolToggles(ctx) {
+        var _a;
+        const cached = this.toggleCache.get(ctx);
+        if (cached) {
+            return cached;
+        }
+        const toggles = (_a = (await this.settingsStoreService.get(ctx, constants_1.MCP_TOOL_TOGGLES_STORE_KEY))) !== null && _a !== void 0 ? _a : {};
+        this.toggleCache.set(ctx, toggles);
+        return toggles;
+    }
+    /** @internal */
+    isToolEnabled(tool, toggles) {
+        return toggles[this.toolKey(tool.toolset, tool.name)] !== false;
+    }
+    async setToolEnabled(ctx, toolset, name, enabled) {
+        var _a;
+        const key = this.toolKey(toolset, name);
+        const current = await this.getToolToggles(ctx);
+        // Built as a copy so a refused write leaves the cached toggles as they were.
+        const updated = Object.assign(Object.assign({}, current), { [key]: enabled });
+        const saved = await this.settingsStoreService.set(ctx, constants_1.MCP_TOOL_TOGGLES_STORE_KEY, updated);
+        if (!saved.result) {
+            throw new Error(`Could not save the MCP tool toggle for "${key}": ` +
+                `${(_a = saved.error) !== null && _a !== void 0 ? _a : 'the settings store refused the write'}`);
+        }
+        this.toggleCache = new WeakMap();
+        this.toggleCache.set(ctx, updated);
+    }
+    // Also the persisted key in the tool-toggle settings map, so changing the format orphans stored toggles.
+    toolKey(toolset, name) {
+        return `${toolset}:${name}`;
+    }
+    discoverTools() {
+        var _a;
+        this.tools.clear();
+        for (const wrapper of this.discoveryService.getProviders()) {
+            const metadata = this.discoveryService.getMetadataByDecorator(mcp_sdk_1.McpTool, wrapper);
+            const instance = wrapper.instance;
+            if (!metadata || !instance) {
+                continue;
+            }
+            if (!this.isToolHandler(instance)) {
+                throw new Error(`MCP tool provider ${String((_a = wrapper.name) !== null && _a !== void 0 ? _a : metadata.name)} must implement execute()`);
+            }
+            const entry = this.buildRegisteredTool(metadata, instance, this.getPluginSource(wrapper));
+            this.registerTool(entry);
+        }
+        core_2.Logger.info(`Discovered ${this.tools.size} MCP tools`, constants_1.loggerCtx);
+    }
+    isToolHandler(instance) {
+        return typeof instance.execute === 'function';
+    }
+    buildRegisteredTool(metadata, handler, pluginSource) {
+        var _a;
+        this.assertValidToolMetadata(metadata);
+        const resolvedBehavior = (_a = metadata.behavior) !== null && _a !== void 0 ? _a : 'mutating';
+        const acceptsSessionToken = this.acceptsSessionToken(metadata);
+        const schemas = this.toolSchema.prepareToolSchemas({
+            toolName: metadata.name,
+            pluginSource,
+            inputSchema: metadata.inputSchema,
+            outputSchema: metadata.outputSchema,
+            injectedFields: {
+                confirm: resolvedBehavior === 'destructive',
+                sessionToken: acceptsSessionToken,
+            },
+        });
+        return Object.assign(Object.assign(Object.assign({}, metadata), { handler,
+            pluginSource,
+            resolvedBehavior,
+            acceptsSessionToken, annotations: this.deriveAnnotations(metadata, resolvedBehavior) }), schemas);
+    }
+    assertValidToolMetadata(metadata) {
+        var _a, _b, _c;
+        if (typeof metadata.name !== 'string' || !TOOL_NAME_PATTERN.test(metadata.name)) {
+            throw new Error(`MCP tool name "${String(metadata.name)}" must contain 1–128 letters, digits, ` +
+                `periods, hyphens, or underscores.`);
+        }
+        for (const permission of (_a = metadata.permissions) !== null && _a !== void 0 ? _a : []) {
+            if (permission === core_2.Permission.Owner) {
+                throw new Error(`MCP tool "${metadata.name}" declares Permission.Owner, which no MCP caller can ` +
+                    `satisfy. Use Permission.Authenticated and check ownership inside the tool.`);
+            }
+            if (!this.getKnownPermissions().has(permission)) {
+                throw new Error(`MCP tool "${metadata.name}" declares unknown permission "${permission}". ` +
+                    `Register it in authOptions.customPermissions.`);
+            }
+        }
+        if (metadata.usesActiveOrder && metadata.toolset !== 'shop') {
+            throw new Error(`MCP tool "${metadata.name}" usesActiveOrder, which is only valid on a shop tool.`);
+        }
+        if (metadata.toolset === 'admin' && ((_c = (_b = metadata.permissions) === null || _b === void 0 ? void 0 : _b.length) !== null && _c !== void 0 ? _c : 0) === 0) {
+            throw new Error(`Admin MCP tool "${metadata.name}" declares no permissions. Declare the permissions ` +
+                `required to call it, e.g. permissions: [Permission.Authenticated] if any administrator ` +
+                `may call it.`);
+        }
+    }
+    getKnownPermissions() {
+        if (!this.knownPermissions) {
+            this.knownPermissions = new Set([
+                ...Object.values(core_2.Permission),
+                ...this.configService.authOptions.customPermissions.flatMap(definition => definition.getMetadata().map(metadata => metadata.name)),
+            ]);
+        }
+        return this.knownPermissions;
+    }
+    registerTool(tool) {
+        if (RESERVED_META_TOOL_NAMES.has(tool.name)) {
+            throw new Error(`MCP tool name "${tool.name}" is reserved for discovery`);
+        }
+        const key = this.toolKey(tool.toolset, tool.name);
+        const existing = this.tools.get(key);
+        if (existing) {
+            throw new Error(`Duplicate MCP tool name "${tool.name}" (toolset "${tool.toolset}") from ` +
+                `${existing.pluginSource} and ${tool.pluginSource}`);
+        }
+        this.tools.set(key, tool);
+    }
+    async callRegisteredTool(executionContext, toolset, name, input, options) {
+        const admission = await this.admitToolCall(executionContext, toolset, name, input, options);
+        if (admission.kind === 'refused') {
+            return admission.result;
+        }
+        const { tool } = admission;
+        // A destructive tool called without `confirm: true` only describes what it would do.
+        const isConfirmationPreview = tool.resolvedBehavior === 'destructive' && admission.input.confirm !== true;
+        const session = await this.resolveShopSession(executionContext, tool, admission.input, isConfirmationPreview);
+        if (session.kind === 'refused') {
+            return session.result;
+        }
+        const { callContext, sessionToken } = session;
+        // The preview carries the token too, so the confirming call can act on the same cart.
+        if (isConfirmationPreview) {
+            return this.confirmationRequiredResult(tool, sessionToken);
+        }
+        let toolInput = session.input;
+        if (tool.resolvedBehavior === 'destructive') {
+            const { confirm } = toolInput, rest = __rest(toolInput, ["confirm"]);
+            toolInput = rest;
+        }
+        const startedAt = Date.now();
+        try {
+            const output = await this.runToolHandler(tool, callContext, toolInput);
+            return await this.buildToolCallResult({
+                callContext,
+                tool,
+                input: toolInput,
+                output,
+                startedAt,
+                sessionToken,
+            });
+        }
+        catch (e) {
+            return await this.handleToolCallError({
+                error: e,
+                callContext,
+                tool,
+                input: toolInput,
+                startedAt,
+                sessionToken,
+            });
+        }
+    }
+    // The prepared input no longer contains the sessionToken credential, so logs do not either.
+    async resolveShopSession(executionContext, tool, input, isConfirmationPreview) {
+        if (!tool.acceptsSessionToken) {
+            return { kind: 'ready', callContext: executionContext, input, sessionToken: undefined };
+        }
+        const prepared = await this.shopSession.prepareToolCall({
+            ctx: executionContext.ctx,
+            input,
+            isOAuthCall: executionContext.grant != null,
+            // A preview runs no handler, so it must not start a cart of its own.
+            toolWritesToCart: tool.resolvedBehavior !== 'readonly' && !isConfirmationPreview,
+        });
+        if (prepared.kind === 'refused') {
+            return { kind: 'refused', result: this.errorResult(prepared.message) };
+        }
+        return {
+            kind: 'ready',
+            // A copy, not a write-back, since the transport reuses one execution context across a batch.
+            callContext: Object.assign(Object.assign({}, executionContext), { ctx: prepared.ctx }),
+            input: prepared.input,
+            sessionToken: prepared.sessionToken,
+        };
+    }
+    // A writing tool runs in one transaction, so a throw rolls back all its writes.
+    async runToolHandler(tool, callContext, toolInput) {
+        if (tool.resolvedBehavior === 'readonly') {
+            return tool.handler.execute(callContext.ctx, toolInput, this.toCallerInfo(callContext));
+        }
+        // withTransaction needs a promise; some handlers return a plain value.
+        return this.connection.withTransaction(callContext.ctx, txCtx => Promise.resolve(tool.handler.execute(txCtx, toolInput, this.toCallerInfo(callContext))));
+    }
+    async handleToolCallError(call) {
+        const { error, callContext, tool, input, startedAt, sessionToken } = call;
+        const message = error instanceof Error ? error.message : 'MCP tool failed';
+        const callerSafe = CALLER_SAFE_ERROR_TYPES.some(ErrorType => error instanceof ErrorType);
+        const callerMessage = callerSafe && error instanceof core_2.I18nError
+            ? callContext.ctx.translate(error.message, error.variables)
+            : message;
+        if (!callerSafe) {
+            core_2.Logger.error(`MCP tool "${tool.name}" failed: ${message}`, constants_1.loggerCtx, error instanceof Error ? error.stack : undefined);
+        }
+        await this.toolCallLog.logToolCall({
+            executionContext: callContext,
+            tool,
+            input,
+            output: { message },
+            durationMs: Date.now() - startedAt,
+            status: 'error',
+        });
+        return this.errorResult(callerSafe ? callerMessage : GENERIC_TOOL_ERROR_MESSAGE, sessionToken);
+    }
+    async admitToolCall(executionContext, toolset, name, input, options) {
+        var _a;
+        const ctx = executionContext.ctx;
+        const rateLimited = await this.rateLimiter.checkRateLimit({
+            executionContext,
+            endpoint: toolset,
+            subject: name,
+        });
+        if (rateLimited) {
+            return { kind: 'refused', result: this.errorResult(rateLimited.message) };
+        }
+        const tool = this.tools.get(this.toolKey(toolset, name));
+        if (!tool) {
+            return { kind: 'refused', result: this.errorResult(`Unknown MCP tool: ${name}`) };
+        }
+        const toggles = await this.getToolToggles(ctx);
+        if (!this.isToolEnabled(tool, toggles)) {
+            return { kind: 'refused', result: this.errorResult(`MCP tool is disabled: ${name}`) };
+        }
+        if (!this.hasPermissions(ctx, tool)) {
+            return {
+                kind: 'refused',
+                result: this.errorResult(`You do not have permission to call MCP tool: ${name}`),
+            };
+        }
+        let toolInput = (input !== null && input !== void 0 ? input : {});
+        if (options.validateInput) {
+            const validated = await this.toolSchema.validate(tool.compiledInputSchema, toolInput);
+            if (!validated.ok) {
+                return {
+                    kind: 'refused',
+                    result: this.errorResult(`Invalid arguments for tool "${name}": ${validated.message}`),
+                };
+            }
+            toolInput = ((_a = validated.value) !== null && _a !== void 0 ? _a : {});
+        }
+        return { kind: 'admitted', tool, input: toolInput };
+    }
+    async buildToolCallResult(call) {
+        const { callContext, tool, input: toolInput, output, startedAt, sessionToken: sessionTokenForResult, } = call;
+        if ((0, core_2.isGraphQlErrorResult)(output)) {
+            const errorResult = Object.assign({}, output);
+            await this.toolCallLog.logToolCall({
+                executionContext: callContext,
+                tool,
+                input: toolInput,
+                output: errorResult,
+                durationMs: Date.now() - startedAt,
+                status: 'error',
+            });
+            const messageKey = `errorResult.${errorResult.message}`;
+            const translated = callContext.ctx.translate(messageKey, errorResult);
+            const translatedResult = Object.assign(Object.assign({}, errorResult), { message: translated === messageKey ? errorResult.message : translated });
+            return this.vendureErrorResult(this.shopSession.addSessionTokenToResult(translatedResult, sessionTokenForResult));
+        }
+        if (tool.compiledOutputSchema) {
+            const validated = await this.toolSchema.validate(tool.compiledOutputSchema, output);
+            if (!validated.ok) {
+                core_2.Logger.warn(`MCP tool "${tool.name}" returned output that does not match its schema: ${validated.message}`, constants_1.loggerCtx);
+            }
+        }
+        // Serializing before the log row is written so an unserializable value is caught as one error row.
+        const result = this.shopSession.addSessionTokenToResult(output, sessionTokenForResult);
+        const text = JSON.stringify(result !== null && result !== void 0 ? result : null);
+        const bytes = Buffer.byteLength(text, 'utf8');
+        const overLimit = bytes > MAX_RESULT_BYTES;
+        // An oversized read is a failure; an oversized write already changed the data, so only the result is withheld.
+        const refuseAsError = overLimit && tool.resolvedBehavior === 'readonly';
+        const refusalMessage = refuseAsError ? this.tooLargeMessage(tool, bytes) : undefined;
+        await this.toolCallLog.logToolCall({
+            executionContext: callContext,
+            tool,
+            input: toolInput,
+            output: refusalMessage !== undefined ? { message: refusalMessage } : output,
+            durationMs: Date.now() - startedAt,
+            status: refuseAsError ? 'error' : 'success',
+        });
+        if (refusalMessage !== undefined) {
+            return this.errorResult(refusalMessage, sessionTokenForResult);
+        }
+        if (overLimit) {
+            return this.completedTooLargeResult(tool, bytes, sessionTokenForResult);
+        }
+        return this.successResult(result, text);
+    }
+    async searchTools(executionContext, toolset, input) {
+        // Unlike execute_tool, search_tools has no target tool to rate-limit downstream, so it is gated here.
+        const rateLimited = await this.rateLimiter.checkRateLimit({
+            executionContext,
+            endpoint: toolset,
+            subject: SEARCH_TOOLS,
+        });
+        if (rateLimited) {
+            return this.errorResult(rateLimited.message);
+        }
+        const params = (input !== null && input !== void 0 ? input : {});
+        const query = typeof params.query === 'string' ? params.query.toLowerCase() : '';
+        const limit = Math.min(Math.max(typeof params.limit === 'number' ? params.limit : SEARCH_DEFAULT_LIMIT, 1), SEARCH_MAX_LIMIT);
+        const tools = await this.visibleTools(executionContext.ctx, toolset);
+        const index = this.bm25.get(toolset);
+        const matches = tools
+            .map(tool => {
+            var _a;
+            return ({
+                tool,
+                score: query.length === 0 ? 1 : ((_a = index === null || index === void 0 ? void 0 : index.score(tool.name, query)) !== null && _a !== void 0 ? _a : 0),
+            });
+        })
+            .filter(item => item.score > 0)
+            .sort((a, b) => b.score - a.score || a.tool.name.localeCompare(b.tool.name))
+            .slice(0, limit)
+            .map(item => this.toolSummary(item.tool));
+        if (matches.length === 0) {
+            return this.successResult({
+                tools: [],
+                hint: `No ${toolset} tools matched "${query}". ` +
+                    `Try a broader query, or call search_tools with an empty query to list tools by name ` +
+                    `(capped at limit — default ${SEARCH_DEFAULT_LIMIT}, maximum ${SEARCH_MAX_LIMIT}, ` +
+                    `so raise limit to see more).`,
+            });
+        }
+        return this.successResult({ tools: matches });
+    }
+    toolSummary(tool) {
+        return {
+            name: tool.name,
+            title: tool.title,
+            description: tool.description,
+            toolset: tool.toolset,
+            behavior: tool.resolvedBehavior,
+            annotations: tool.annotations,
+            inputSchema: tool.wireJsonSchema,
+        };
+    }
+    buildSearchIndexes() {
+        const indexes = new Map();
+        for (const toolset of ALL_TOOLSETS) {
+            const entries = [...this.tools.values()]
+                .filter(tool => tool.toolset === toolset)
+                .map(tool => {
+                var _a, _b;
+                return ({
+                    id: tool.name,
+                    text: [tool.name, (_a = tool.title) !== null && _a !== void 0 ? _a : '', tool.description, ...((_b = tool.keywords) !== null && _b !== void 0 ? _b : [])].join(' '),
+                });
+            });
+            indexes.set(toolset, new bm25_1.Bm25Index(entries));
+        }
+        return indexes;
+    }
+    buildDiscoveryMetaTools() {
+        const searchSchema = {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Keywords to match against tool names and descriptions.',
+                },
+                limit: {
+                    type: 'number',
+                    description: `Maximum number of results (1-${SEARCH_MAX_LIMIT}, default ${SEARCH_DEFAULT_LIMIT}).`,
+                },
+            },
+            required: ['query'],
+            additionalProperties: false,
+        };
+        const executeSchema = {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'The name of the tool to execute (from search_tools).' },
+                arguments: { type: 'object', description: 'Arguments to pass to the tool.' },
+            },
+            required: ['name'],
+            additionalProperties: false,
+        };
+        return [
+            {
+                name: SEARCH_TOOLS,
+                description: 'Search for available Vendure MCP tools by keyword. Returns matching tools with their ' +
+                    'input schemas so you can then run one via execute_tool.',
+                annotations: { readOnlyHint: true, idempotentHint: true },
+                compiledInputSchema: this.toolSchema.compileJsonSchema(searchSchema, `MCP tool "${SEARCH_TOOLS}" (McpPlugin) inputSchema`),
+            },
+            {
+                name: EXECUTE_TOOL,
+                description: 'Execute a Vendure MCP tool found via search_tools. Provide the tool name and its arguments.',
+                annotations: {},
+                compiledInputSchema: this.toolSchema.compileJsonSchema(executeSchema, `MCP tool "${EXECUTE_TOOL}" (McpPlugin) inputSchema`),
+            },
+        ];
+    }
+    async visibleTools(ctx, toolset) {
+        const toggles = await this.getToolToggles(ctx);
+        return [...this.tools.values()]
+            .filter(tool => tool.toolset === toolset)
+            .filter(tool => this.isToolEnabled(tool, toggles))
+            .filter(tool => this.hasPermissions(ctx, tool))
+            .sort((a, b) => a.name.localeCompare(b.name));
+    }
+    deriveAnnotations(tool, behavior) {
+        return {
+            title: tool.title,
+            readOnlyHint: behavior === 'readonly',
+            destructiveHint: behavior === 'destructive',
+            idempotentHint: behavior === 'readonly',
+        };
+    }
+    hasPermissions(ctx, tool) {
+        var _a;
+        const permissions = (_a = tool.permissions) !== null && _a !== void 0 ? _a : [];
+        if (this.isPubliclyCallable(permissions)) {
+            return true;
+        }
+        return ctx.userHasPermissions(permissions);
+    }
+    // Spelled out because `ctx.userHasPermissions([])` returns false, unlike an empty permissions list here.
+    isPubliclyCallable(permissions) {
+        return permissions.length === 0 || permissions.includes(core_2.Permission.Public);
+    }
+    acceptsSessionToken(tool) {
+        var _a;
+        return (tool.toolset === 'shop' &&
+            tool.usesActiveOrder === true &&
+            this.isPubliclyCallable((_a = tool.permissions) !== null && _a !== void 0 ? _a : []));
+    }
+    toCallerInfo(state) {
+        return {
+            grant: state.grant ? { id: state.grant.id, oauthClientId: state.grant.oauthClientId } : undefined,
+            clientIp: state.clientIp,
+        };
+    }
+    getPluginSource(wrapper) {
+        var _a, _b, _c, _d;
+        return (_c = (_b = (_a = wrapper.host) === null || _a === void 0 ? void 0 : _a.metatype) === null || _b === void 0 ? void 0 : _b.name) !== null && _c !== void 0 ? _c : String((_d = wrapper.name) !== null && _d !== void 0 ? _d : 'unknown');
+    }
+    // The tool path passes the `text` it already built to measure the result, so it is not serialized twice.
+    successResult(output, text = JSON.stringify(output !== null && output !== void 0 ? output : null)) {
+        return {
+            content: [{ type: 'text', text }],
+            structuredContent: output,
+        };
+    }
+    tooLargeMessage(tool, bytes) {
+        var _a;
+        const declared = (_a = tool.wireJsonSchema.properties) !== null && _a !== void 0 ? _a : {};
+        const advice = Object.keys(NARROWING_ARGUMENT_ADVICE)
+            .filter(argument => argument in declared)
+            .map(argument => NARROWING_ARGUMENT_ADVICE[argument]);
+        const size = `The result of "${tool.name}" is ${bytes.toLocaleString('en-US')} bytes, over the ` +
+            `${MAX_RESULT_BYTES.toLocaleString('en-US')}-byte limit for one tool result.`;
+        if (advice.length === 0) {
+            return `${size} Ask for less at a time.`;
+        }
+        return `${size} Ask for less at a time: ${this.joinWithOr(advice)}.`;
+    }
+    // Not an error: the write already saved, so the caller is told to read the outcome back rather than retry.
+    completedTooLargeResult(tool, bytes, sessionToken) {
+        const text = `The call to "${tool.name}" completed, but its result was ${bytes.toLocaleString('en-US')} ` +
+            `bytes, over the ${MAX_RESULT_BYTES.toLocaleString('en-US')}-byte limit, so it was not ` +
+            `returned. Fetch the outcome with a read tool.`;
+        return {
+            content: [{ type: 'text', text }],
+            structuredContent: Object.assign({ status: 'completed_result_too_large' }, (sessionToken !== undefined ? { sessionToken } : {})),
+        };
+    }
+    /** Reads a list of choices as a sentence does: "a", "a or b", "a, b, or c". */
+    joinWithOr(options) {
+        if (options.length < 3) {
+            return options.join(' or ');
+        }
+        return `${options.slice(0, -1).join(', ')}, or ${options[options.length - 1]}`;
+    }
+    errorResult(message, sessionToken) {
+        return Object.assign({ isError: true, content: [{ type: 'text', text: message }] }, (sessionToken !== undefined ? { structuredContent: { sessionToken } } : {}));
+    }
+    // Unlike `errorResult`, the whole object is kept so a caller can act on `errorCode` rather than parse a sentence.
+    vendureErrorResult(output) {
+        return {
+            isError: true,
+            content: [{ type: 'text', text: JSON.stringify(output) }],
+            structuredContent: output,
+        };
+    }
+    confirmationRequiredResult(tool, sessionToken) {
+        // Discovery mode never exposes the tool by name, so the retry has to go through the meta-tool instead.
+        const howToConfirm = this.options.toolExposure === 'discovery'
+            ? `Ask the user to approve it, then call "${EXECUTE_TOOL}" again for "${tool.name}" ` +
+                `with "confirm": true added to its arguments.`
+            : `Ask the user to approve it, then re-call "${tool.name}" with "confirm": true.`;
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `This is a destructive action: ${tool.description} ${howToConfirm}`,
+                },
+            ],
+            structuredContent: Object.assign({ status: 'confirmation_required', confirmed: false }, (sessionToken !== undefined ? { sessionToken } : {})),
+        };
+    }
+};
+exports.McpToolRegistryService = McpToolRegistryService;
+exports.McpToolRegistryService = McpToolRegistryService = __decorate([
+    (0, common_1.Injectable)(),
+    (0, core_2.Instrument)(),
+    __param(8, (0, common_1.Inject)(constants_1.MCP_PLUGIN_OPTIONS)),
+    __metadata("design:paramtypes", [core_1.DiscoveryService,
+        core_2.SettingsStoreService,
+        mcp_rate_limiter_service_1.McpRateLimiterService,
+        mcp_tool_call_log_service_1.McpToolCallLogService,
+        mcp_tool_schema_service_1.McpToolSchemaService,
+        mcp_shop_session_service_1.McpShopSessionService,
+        core_2.ConfigService,
+        core_2.TransactionalConnection, Object])
+], McpToolRegistryService);
+//# sourceMappingURL=mcp-tool-registry.service.js.map