@salesforce/b2c-dx-mcp 0.0.1 → 0.3.2

package/dist/registry.d.ts

@@ -0,0 +1,37 @@
+import type { McpTool, Toolset, StartupFlags } from './utils/index.js';
+import type { B2CDxMcpServer } from './server.js';
+import type { Services } from './services.js';
+/**
+ * Registry of tools organized by toolset.
+ * Tools can belong to multiple toolsets via their `toolsets` array.
+ */
+export type ToolRegistry = Record<Toolset, McpTool[]>;
+/**
+ * Creates the tool registry from all toolset providers.
+ * Tools are organized by their declared `toolsets` array, allowing
+ * a single tool to appear in multiple toolsets.
+ *
+ * @param services - Services instance for dependency injection
+ * @returns Complete tool registry
+ */
+export declare function createToolRegistry(services: Services): ToolRegistry;
+/**
+ * Register tools with the MCP server based on startup flags.
+ *
+ * Tool selection logic:
+ * 1. If no valid tools result from --toolsets and --tools, perform auto-discovery
+ * 2. Start with all tools from --toolsets (or auto-discovered toolsets)
+ * 3. Add individual tools from --tools (can be from any toolset)
+ *
+ * Auto-discovery always enables at least the BASE_TOOLSET (SCAPI), even if no
+ * project types are detected in the workspace.
+ *
+ * Example:
+ *   --toolsets STOREFRONTNEXT,MRT --tools cartridge_deploy
+ *   This enables STOREFRONTNEXT and MRT toolsets, plus adds cartridge_deploy from CARTRIDGES.
+ *
+ * @param flags - Startup flags from CLI
+ * @param server - B2CDxMcpServer instance
+ * @param services - Services instance
+ */
+export declare function registerToolsets(flags: StartupFlags, server: B2CDxMcpServer, services: Services): Promise<void>;

package/dist/registry.js

@@ -0,0 +1,212 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+import { getLogger } from '@salesforce/b2c-tooling-sdk/logging';
+import { detectWorkspaceType } from '@salesforce/b2c-tooling-sdk/discovery';
+import { ALL_TOOLSETS, TOOLSETS, VALID_TOOLSET_NAMES } from './utils/index.js';
+import { createCartridgesTools } from './tools/cartridges/index.js';
+import { createMrtTools } from './tools/mrt/index.js';
+import { createPwav3Tools } from './tools/pwav3/index.js';
+import { createScapiTools } from './tools/scapi/index.js';
+import { createStorefrontNextTools } from './tools/storefrontnext/index.js';
+/**
+ * Base toolset that is always enabled.
+ * Provides SCAPI discovery and custom API scaffolding tools.
+ */
+const BASE_TOOLSET = 'SCAPI';
+/**
+ * Toolset mapping by project type.
+ * Each project type enables specific toolsets IN ADDITION to the base toolset.
+ */
+const PROJECT_TYPE_TOOLSETS = {
+    cartridges: ['CARTRIDGES'],
+    'pwa-kit-v3': ['PWAV3', 'MRT'],
+    'storefront-next': ['STOREFRONTNEXT', 'MRT', 'CARTRIDGES'],
+};
+/**
+ * Gets toolsets for a project type, always including the base toolset.
+ */
+function getToolsetsForProjectType(projectType) {
+    const additionalToolsets = PROJECT_TYPE_TOOLSETS[projectType] ?? [];
+    return [...additionalToolsets, BASE_TOOLSET];
+}
+/**
+ * Maps multiple detected project types to a union of MCP toolsets.
+ *
+ * Combines toolsets from all matched project types, enabling hybrid
+ * project support (e.g., cartridges + pwa-kit-v3 gets CARTRIDGES + PWAV3 + MRT + SCAPI).
+ *
+ * @param projectTypes - Array of detected project types
+ * @returns Union of all toolsets for the detected project types (always includes base toolset)
+ */
+function getToolsetsForProjectTypes(projectTypes) {
+    const toolsetSet = new Set();
+    // Always include base toolset
+    toolsetSet.add(BASE_TOOLSET);
+    // Add toolsets for each detected project type
+    for (const projectType of projectTypes) {
+        for (const toolset of getToolsetsForProjectType(projectType)) {
+            toolsetSet.add(toolset);
+        }
+    }
+    return [...toolsetSet];
+}
+/**
+ * Creates the tool registry from all toolset providers.
+ * Tools are organized by their declared `toolsets` array, allowing
+ * a single tool to appear in multiple toolsets.
+ *
+ * @param services - Services instance for dependency injection
+ * @returns Complete tool registry
+ */
+export function createToolRegistry(services) {
+    const registry = {
+        CARTRIDGES: [],
+        MRT: [],
+        PWAV3: [],
+        SCAPI: [],
+        STOREFRONTNEXT: [],
+    };
+    // Collect all tools from all factories
+    const allTools = [
+        ...createCartridgesTools(services),
+        ...createMrtTools(services),
+        ...createPwav3Tools(services),
+        ...createScapiTools(services),
+        ...createStorefrontNextTools(services),
+    ];
+    // Organize tools by their declared toolsets (supports multi-toolset)
+    for (const tool of allTools) {
+        for (const toolset of tool.toolsets) {
+            registry[toolset].push(tool);
+        }
+    }
+    return registry;
+}
+/**
+ * Performs workspace auto-discovery and returns appropriate toolsets.
+ * Always includes BASE_TOOLSET even if no project types are detected.
+ *
+ * @param flags - Startup flags containing workingDirectory
+ * @param reason - Reason for triggering auto-discovery (for logging)
+ * @returns Array of toolsets to enable
+ */
+async function performAutoDiscovery(flags, reason) {
+    const logger = getLogger();
+    // Working directory from --working-directory flag or SFCC_WORKING_DIRECTORY env var
+    const workingDirectory = flags.workingDirectory ?? process.cwd();
+    // Warn if working directory wasn't explicitly configured
+    if (!flags.workingDirectory) {
+        logger.warn({ cwd: workingDirectory }, 'No --working-directory flag or SFCC_WORKING_DIRECTORY env var provided. ' +
+            'MCP clients like Cursor and Claude Desktop often spawn servers from ~ instead of the project directory. ' +
+            'Set --working-directory or SFCC_WORKING_DIRECTORY for reliable auto-discovery.');
+    }
+    const detectionResult = await detectWorkspaceType(workingDirectory);
+    // Map all detected project types to MCP toolsets (union)
+    // Note: getToolsetsForProjectTypes always includes BASE_TOOLSET
+    const mappedToolsets = getToolsetsForProjectTypes(detectionResult.projectTypes);
+    logger.info({
+        reason,
+        projectTypes: detectionResult.projectTypes,
+        matchedPatterns: detectionResult.matchedPatterns,
+        enabledToolsets: mappedToolsets,
+    }, `Auto-discovery (${reason}): project types: ${detectionResult.projectTypes.join(', ') || 'none'}`);
+    return mappedToolsets;
+}
+/**
+ * Register tools with the MCP server based on startup flags.
+ *
+ * Tool selection logic:
+ * 1. If no valid tools result from --toolsets and --tools, perform auto-discovery
+ * 2. Start with all tools from --toolsets (or auto-discovered toolsets)
+ * 3. Add individual tools from --tools (can be from any toolset)
+ *
+ * Auto-discovery always enables at least the BASE_TOOLSET (SCAPI), even if no
+ * project types are detected in the workspace.
+ *
+ * Example:
+ *   --toolsets STOREFRONTNEXT,MRT --tools cartridge_deploy
+ *   This enables STOREFRONTNEXT and MRT toolsets, plus adds cartridge_deploy from CARTRIDGES.
+ *
+ * @param flags - Startup flags from CLI
+ * @param server - B2CDxMcpServer instance
+ * @param services - Services instance
+ */
+export async function registerToolsets(flags, server, services) {
+    const toolsets = flags.toolsets ?? [];
+    const individualTools = flags.tools ?? [];
+    const allowNonGaTools = flags.allowNonGaTools ?? false;
+    const logger = getLogger();
+    // Create the tool registry (all available tools)
+    const toolRegistry = createToolRegistry(services);
+    // Build flat list of all tools for lookup
+    const allTools = Object.values(toolRegistry).flat();
+    const allToolsByName = new Map(allTools.map((tool) => [tool.name, tool]));
+    const existingToolNames = new Set(allToolsByName.keys());
+    // Determine valid individual tools
+    const invalidTools = individualTools.filter((name) => !existingToolNames.has(name));
+    const validIndividualTools = individualTools.filter((name) => existingToolNames.has(name));
+    // Warn about invalid --tools names (but continue with valid ones)
+    if (invalidTools.length > 0) {
+        logger.warn({ invalidTools, validTools: [...existingToolNames] }, `Ignoring invalid tool name(s): "${invalidTools.join('", "')}"`);
+    }
+    // Warn about invalid --toolsets names (but continue with valid ones)
+    const invalidToolsets = toolsets.filter((t) => !VALID_TOOLSET_NAMES.includes(t));
+    if (invalidToolsets.length > 0) {
+        logger.warn({ invalidToolsets, validToolsets: VALID_TOOLSET_NAMES }, `Ignoring invalid toolset(s): "${invalidToolsets.join('", "')}"`);
+    }
+    // Determine which toolsets to enable
+    const validToolsets = toolsets.filter((t) => TOOLSETS.includes(t));
+    const toolsetsToEnable = new Set(toolsets.includes(ALL_TOOLSETS) ? TOOLSETS : validToolsets);
+    // Auto-discovery: If no valid toolsets AND no valid individual tools, detect workspace type.
+    // This handles both: (1) no flags provided, and (2) all provided flags are invalid.
+    // Auto-discovery enables appropriate toolsets based on workspace type,
+    // or at minimum BASE_TOOLSET if no project types are detected.
+    if (toolsetsToEnable.size === 0 && validIndividualTools.length === 0) {
+        const discoveredToolsets = await performAutoDiscovery(flags, 'no valid toolsets or tools');
+        for (const toolset of discoveredToolsets) {
+            toolsetsToEnable.add(toolset);
+        }
+    }
+    // Build the set of tools to register:
+    // 1. Start with tools from enabled toolsets
+    // 2. Add individual tools from --tools
+    const toolsToRegister = [];
+    const registeredToolNames = new Set();
+    // Step 1: Add tools from enabled toolsets
+    for (const toolset of toolsetsToEnable) {
+        for (const tool of toolRegistry[toolset]) {
+            if (!registeredToolNames.has(tool.name)) {
+                toolsToRegister.push(tool);
+                registeredToolNames.add(tool.name);
+            }
+        }
+    }
+    // Step 2: Add individual tools from --tools (can be from any toolset)
+    for (const toolName of validIndividualTools) {
+        const tool = allToolsByName.get(toolName);
+        if (tool && !registeredToolNames.has(toolName)) {
+            toolsToRegister.push(tool);
+            registeredToolNames.add(toolName);
+        }
+    }
+    // Register all selected tools
+    await registerTools(toolsToRegister, server, allowNonGaTools);
+}
+/**
+ * Register a list of tools with the server.
+ */
+async function registerTools(tools, server, allowNonGaTools) {
+    for (const tool of tools) {
+        // Skip non-GA tools if not allowed
+        if (tool.isGA === false && !allowNonGaTools) {
+            continue;
+        }
+        // Register the tool
+        // TODO: Telemetry - Tool registration includes timing/error tracking
+        server.addTool(tool.name, tool.description, tool.inputSchema, async (args) => tool.handler(args));
+    }
+}
+//# sourceMappingURL=registry.js.map

package/dist/server.d.ts

@@ -0,0 +1,46 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CallToolResult, Implementation } from '@modelcontextprotocol/sdk/types.js';
+import type { ServerOptions } from '@modelcontextprotocol/sdk/server/index.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { ZodRawShape } from 'zod';
+import type { Telemetry } from '@salesforce/b2c-tooling-sdk/telemetry';
+/**
+ * Extended server options.
+ */
+export interface B2CDxMcpServerOptions extends ServerOptions {
+    /**
+     * Telemetry instance for tracking server and tool events.
+     * If not provided, telemetry is disabled.
+     */
+    telemetry?: Telemetry;
+}
+/**
+ * A server implementation that extends the base MCP server.
+ *
+ * @augments {McpServer}
+ */
+export declare class B2CDxMcpServer extends McpServer {
+    private telemetry?;
+    /**
+     * Creates a new B2CDxMcpServer instance
+     *
+     * @param serverInfo - The server implementation details
+     * @param options - Optional server configuration
+     */
+    constructor(serverInfo: Implementation, options?: B2CDxMcpServerOptions);
+    /**
+     * Register a tool with the server.
+     *
+     * This method provides a convenient way to register tools.
+     *
+     * @param name - Tool name
+     * @param description - Tool description
+     * @param inputSchema - Zod schema for input validation
+     * @param handler - Function to handle tool invocations
+     */
+    addTool(name: string, description: string, inputSchema: ZodRawShape, handler: (args: Record<string, unknown>) => Promise<CallToolResult>): void;
+    /**
+     * Connect to a transport.
+     */
+    connect(transport: Transport): Promise<void>;
+}

package/dist/server.js

@@ -0,0 +1,98 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * A server implementation that extends the base MCP server.
+ *
+ * @augments {McpServer}
+ */
+export class B2CDxMcpServer extends McpServer {
+    telemetry;
+    /**
+     * Creates a new B2CDxMcpServer instance
+     *
+     * @param serverInfo - The server implementation details
+     * @param options - Optional server configuration
+     */
+    constructor(serverInfo, options) {
+        super(serverInfo, options);
+        this.telemetry = options?.telemetry;
+        // Set up oninitialized handler
+        this.server.oninitialized = () => {
+            const clientInfo = this.server.getClientVersion();
+            if (clientInfo) {
+                this.telemetry?.addAttributes({
+                    clientName: clientInfo.name,
+                    clientVersion: clientInfo.version,
+                });
+            }
+        };
+    }
+    /**
+     * Register a tool with the server.
+     *
+     * This method provides a convenient way to register tools.
+     *
+     * @param name - Tool name
+     * @param description - Tool description
+     * @param inputSchema - Zod schema for input validation
+     * @param handler - Function to handle tool invocations
+     */
+    addTool(name, description, inputSchema, handler) {
+        const wrappedHandler = async (args, _extra) => {
+            const startTime = Date.now();
+            try {
+                const result = await handler(args);
+                const runTimeMs = Date.now() - startTime;
+                await this.telemetry
+                    ?.sendEventAndFlush('TOOL_CALLED', {
+                    toolName: name,
+                    runTimeMs,
+                    isError: result.isError ?? false,
+                })
+                    .catch(() => { });
+                return result;
+            }
+            catch (error) {
+                const runTimeMs = Date.now() - startTime;
+                await this.telemetry
+                    ?.sendEventAndFlush('TOOL_CALLED', {
+                    toolName: name,
+                    runTimeMs,
+                    isError: true,
+                })
+                    .catch(() => { });
+                throw error;
+            }
+        };
+        // Use the new registerTool API (tool() is deprecated)
+        this.registerTool(name, { description, inputSchema }, wrappedHandler);
+    }
+    /**
+     * Connect to a transport.
+     */
+    async connect(transport) {
+        try {
+            await super.connect(transport);
+            const statusPromise = this.isConnected()
+                ? this.telemetry?.sendEventAndFlush('SERVER_STATUS', { status: 'started' })
+                : this.telemetry?.sendEventAndFlush('SERVER_STATUS', {
+                    status: 'error',
+                    errorMessage: 'Server not connected after connect() call',
+                });
+            await (statusPromise ?? Promise.resolve()).catch(() => { });
+        }
+        catch (error) {
+            const errorPromise = this.telemetry?.sendEventAndFlush('SERVER_STATUS', {
+                status: 'error',
+                errorMessage: error instanceof Error ? error.message : String(error),
+            });
+            await (errorPromise ?? Promise.resolve()).catch(() => { });
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=server.js.map

package/dist/services.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Services module providing dependency injection for MCP tools.
+ *
+ * The {@link Services} class is the central dependency container for tools,
+ * providing:
+ * - Pre-resolved B2CInstance for WebDAV/OCAPI operations
+ * - Pre-resolved MRT authentication for Managed Runtime operations
+ * - MRT project/environment configuration
+ * - File system utilities for local operations
+ *
+ * ## Creating Services
+ *
+ * Use {@link Services.fromResolvedConfig} with an already-resolved configuration:
+ *
+ * ```typescript
+ * // In a command that extends BaseCommand
+ * const services = Services.fromResolvedConfig(this.resolvedConfig);
+ * ```
+ *
+ * ## Resolution Pattern
+ *
+ * Both B2CInstance and MRT auth are resolved once at server startup (not on each tool call).
+ * This provides fail-fast behavior and consistent performance.
+ *
+ * **B2C Instance** (for WebDAV/OCAPI tools):
+ * - Flags (highest priority) merged with dw.json (auto-discovered or via --config)
+ *
+ * **MRT Auth** (for Managed Runtime tools):
+ * 1. `--api-key` flag (oclif also checks `SFCC_MRT_API_KEY` env var)
+ * 2. `~/.mobify` config file (or `~/.mobify--[hostname]` if `--cloud-origin` is set)
+ *
+ * **MRT Origin** (for Managed Runtime API URL):
+ * 1. `--cloud-origin` flag (oclif also checks `SFCC_MRT_CLOUD_ORIGIN` env var)
+ * 2. `mrtOrigin` field in dw.json
+ * 3. Default: `https://cloud.mobify.com`
+ *
+ * @module services
+ */
+import fs from 'node:fs';
+import type { B2CInstance } from '@salesforce/b2c-tooling-sdk';
+import type { AuthStrategy } from '@salesforce/b2c-tooling-sdk/auth';
+import type { ResolvedB2CConfig } from '@salesforce/b2c-tooling-sdk/config';
+/**
+ * MRT (Managed Runtime) configuration.
+ * Groups auth, project, environment, and origin settings.
+ */
+export interface MrtConfig {
+    /** Pre-resolved auth strategy for MRT API operations */
+    auth?: AuthStrategy;
+    /** MRT project slug from --project flag or SFCC_MRT_PROJECT env var */
+    project?: string;
+    /** MRT environment from --environment flag or SFCC_MRT_ENVIRONMENT env var */
+    environment?: string;
+    /** MRT API origin URL from --cloud-origin flag, SFCC_MRT_CLOUD_ORIGIN env var, or mrtOrigin in dw.json */
+    origin?: string;
+}
+/**
+ * Options for Services constructor (internal).
+ */
+export interface ServicesOptions {
+    /** Pre-resolved B2C instance (if configured) */
+    b2cInstance?: B2CInstance;
+    /** Pre-resolved MRT configuration (auth, project, environment) */
+    mrtConfig?: MrtConfig;
+}
+/**
+ * Services class that provides utilities for MCP tools.
+ *
+ * Use the static `Services.fromResolvedConfig()` factory method to create
+ * an instance from an already-resolved configuration.
+ *
+ * @example
+ * ```typescript
+ * // In a command that extends BaseCommand
+ * const services = Services.fromResolvedConfig(this.resolvedConfig);
+ *
+ * // Access resolved config
+ * services.b2cInstance;        // B2CInstance | undefined
+ * services.mrtConfig.auth;     // AuthStrategy | undefined
+ * services.mrtConfig.project;  // string | undefined
+ * ```
+ */
+export declare class Services {
+    /**
+     * Pre-resolved B2C instance for WebDAV/OCAPI operations.
+     * Resolved once at server startup from InstanceCommand flags and dw.json.
+     * Undefined if no B2C instance configuration was available.
+     */
+    readonly b2cInstance?: B2CInstance;
+    /**
+     * Pre-resolved MRT configuration (auth, project, environment, origin).
+     * Resolved once at server startup from MrtCommand flags and ~/.mobify.
+     */
+    readonly mrtConfig: MrtConfig;
+    constructor(opts?: ServicesOptions);
+    /**
+     * Creates a Services instance from an already-resolved configuration.
+     *
+     * @param config - Already-resolved configuration from BaseCommand.resolvedConfig
+     * @returns Services instance with resolved config
+     *
+     * @example
+     * ```typescript
+     * // In a command that extends BaseCommand
+     * const services = Services.fromResolvedConfig(this.resolvedConfig);
+     * ```
+     */
+    static fromResolvedConfig(config: ResolvedB2CConfig): Services;
+    /**
+     * Check if a file or directory exists.
+     *
+     * @param targetPath - Path to check
+     * @returns True if exists, false otherwise
+     */
+    exists(targetPath: string): boolean;
+    /**
+     * Get the current working directory.
+     */
+    getCwd(): string;
+    /**
+     * Get the user's home directory.
+     */
+    getHomeDir(): string;
+    /**
+     * Get OS platform information.
+     */
+    getPlatform(): NodeJS.Platform;
+    /**
+     * Get system temporary directory.
+     */
+    getTmpDir(): string;
+    /**
+     * Join path segments.
+     *
+     * @param segments - Path segments to join
+     * @returns Joined path
+     */
+    joinPath(...segments: string[]): string;
+    /**
+     * List directory contents.
+     *
+     * @param dirPath - Directory path to list
+     * @returns Array of directory entries
+     */
+    listDirectory(dirPath: string): fs.Dirent[];
+    /**
+     * Read a file from the filesystem.
+     *
+     * @param filePath - Path to the file
+     * @param encoding - File encoding (default: utf8)
+     * @returns File contents as a string
+     */
+    readFile(filePath: string, encoding?: 'ascii' | 'base64' | 'hex' | 'latin1' | 'utf8'): string;
+    /**
+     * Resolve a path relative to the current working directory.
+     *
+     * @param segments - Path segments to join and resolve
+     * @returns Absolute path
+     */
+    resolvePath(...segments: string[]): string;
+    /**
+     * Get file or directory stats.
+     *
+     * @param targetPath - Path to get stats for
+     * @returns File stats object
+     */
+    stat(targetPath: string): fs.Stats;
+}