@salesforce/b2c-dx-mcp 0.0.1 → 0.3.2

package/dist/services.js

@@ -0,0 +1,191 @@
+/*
+ * 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
+ */
+/**
+ * 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 path from 'node:path';
+import os from 'node:os';
+/**
+ * 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 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.
+     */
+    b2cInstance;
+    /**
+     * Pre-resolved MRT configuration (auth, project, environment, origin).
+     * Resolved once at server startup from MrtCommand flags and ~/.mobify.
+     */
+    mrtConfig;
+    constructor(opts = {}) {
+        this.b2cInstance = opts.b2cInstance;
+        this.mrtConfig = opts.mrtConfig ?? {};
+    }
+    /**
+     * 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) {
+        // Build MRT config using factory methods
+        const mrtConfig = {
+            auth: config.hasMrtConfig() ? config.createMrtAuth() : undefined,
+            project: config.values.mrtProject,
+            environment: config.values.mrtEnvironment,
+            origin: config.values.mrtOrigin,
+        };
+        // Build B2C instance using factory method
+        const b2cInstance = config.hasB2CInstanceConfig() ? config.createB2CInstance() : undefined;
+        return new Services({
+            b2cInstance,
+            mrtConfig,
+        });
+    }
+    // ============================================
+    // Internal OS Resource Access Methods
+    // These are for internal use by tools, not exposed to AI assistants
+    // ============================================
+    /**
+     * Check if a file or directory exists.
+     *
+     * @param targetPath - Path to check
+     * @returns True if exists, false otherwise
+     */
+    exists(targetPath) {
+        return fs.existsSync(targetPath);
+    }
+    /**
+     * Get the current working directory.
+     */
+    getCwd() {
+        return process.cwd();
+    }
+    /**
+     * Get the user's home directory.
+     */
+    getHomeDir() {
+        return os.homedir();
+    }
+    /**
+     * Get OS platform information.
+     */
+    getPlatform() {
+        return os.platform();
+    }
+    /**
+     * Get system temporary directory.
+     */
+    getTmpDir() {
+        return os.tmpdir();
+    }
+    /**
+     * Join path segments.
+     *
+     * @param segments - Path segments to join
+     * @returns Joined path
+     */
+    joinPath(...segments) {
+        return path.join(...segments);
+    }
+    /**
+     * List directory contents.
+     *
+     * @param dirPath - Directory path to list
+     * @returns Array of directory entries
+     */
+    listDirectory(dirPath) {
+        return fs.readdirSync(dirPath, { withFileTypes: true });
+    }
+    /**
+     * 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, encoding = 'utf8') {
+        return fs.readFileSync(filePath, { encoding });
+    }
+    /**
+     * Resolve a path relative to the current working directory.
+     *
+     * @param segments - Path segments to join and resolve
+     * @returns Absolute path
+     */
+    resolvePath(...segments) {
+        return path.resolve(...segments);
+    }
+    /**
+     * Get file or directory stats.
+     *
+     * @param targetPath - Path to get stats for
+     * @returns File stats object
+     */
+    stat(targetPath) {
+        return fs.statSync(targetPath);
+    }
+}
+//# sourceMappingURL=services.js.map

package/dist/tools/adapter.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Tool Adapter for wrapping b2c-tooling-sdk functions as MCP tools.
+ *
+ * This module provides utilities for creating standardized MCP tools that:
+ * - Validate input using Zod schemas
+ * - Inject pre-resolved B2CInstance for WebDAV/OCAPI operations (requiresInstance)
+ * - Inject pre-resolved MRT auth for MRT API operations (requiresMrtAuth)
+ * - Format output consistently (textResult, jsonResult, errorResult)
+ *
+ * ## Configuration Resolution
+ *
+ * Both B2C instance and MRT auth are resolved once at server startup via
+ * {@link Services.fromResolvedConfig} and reused for all tool calls:
+ *
+ * - **B2CInstance**: Resolved from flags + dw.json. Available when `requiresInstance: true`.
+ * - **MRT Auth**: Resolved from --api-key → SFCC_MRT_API_KEY → ~/.mobify. Available when `requiresMrtAuth: true`.
+ *
+ * This "resolve eagerly at startup" pattern provides:
+ * - Fail-fast behavior (configuration errors surface at startup)
+ * - Consistent mental model (both resolved the same way)
+ * - Better performance (no resolution on each tool call)
+ *
+ * @module tools/adapter
+ *
+ * @example B2C Instance tool (WebDAV/OCAPI)
+ * ```typescript
+ * const myTool = createToolAdapter({
+ *   name: 'my_tool',
+ *   description: 'Does something useful',
+ *   toolsets: ['CARTRIDGES'],
+ *   requiresInstance: true,
+ *   inputSchema: {
+ *     cartridgeName: z.string().describe('Name of the cartridge'),
+ *   },
+ *   execute: async (args, { b2cInstance }) => {
+ *     const result = await b2cInstance.webdav.get(`Cartridges/${args.cartridgeName}`);
+ *     return result;
+ *   },
+ *   formatOutput: (output) => textResult(`Fetched: ${output}`),
+ * }, services);
+ * ```
+ *
+ * @example MRT tool (MRT API)
+ * ```typescript
+ * // Services created from already-resolved config at startup
+ * const services = Services.fromResolvedConfig(this.resolvedConfig);
+ *
+ * const mrtTool = createToolAdapter({
+ *   name: 'mrt_bundle_push',
+ *   description: 'Push bundle to MRT',
+ *   toolsets: ['MRT'],
+ *   requiresMrtAuth: true,
+ *   inputSchema: {
+ *     projectSlug: z.string().describe('MRT project slug'),
+ *   },
+ *   execute: async (args, { mrtAuth }) => {
+ *     const result = await pushBundle({ projectSlug: args.projectSlug }, mrtAuth);
+ *     return result;
+ *   },
+ *   formatOutput: (output) => jsonResult(output),
+ * }, services);
+ * ```
+ */
+import { type ZodRawShape } from 'zod';
+import type { B2CInstance } from '@salesforce/b2c-tooling-sdk';
+import type { McpTool, ToolResult, Toolset } from '../utils/index.js';
+import type { Services, MrtConfig } from '../services.js';
+/**
+ * Context provided to tool execute functions.
+ * Contains the B2CInstance and/or MRT config based on tool requirements.
+ */
+export interface ToolExecutionContext {
+    /**
+     * B2CInstance configured with authentication from dw.json and flags.
+     * Provides access to typed API clients (webdav, ocapi).
+     * Only available when requiresInstance is true.
+     */
+    b2cInstance?: B2CInstance;
+    /**
+     * MRT configuration (auth, project, environment, origin).
+     * Pre-resolved at server startup.
+     * Only populated when requiresMrtAuth is true.
+     */
+    mrtConfig?: MrtConfig;
+    /**
+     * Services instance for file system access and other utilities.
+     */
+    services: Services;
+}
+/**
+ * Options for creating a tool adapter.
+ *
+ * @template TInput - The validated input type (inferred from inputSchema)
+ * @template TOutput - The output type from the execute function
+ */
+export interface ToolAdapterOptions<TInput, TOutput> {
+    /** Tool name (used in MCP protocol) */
+    name: string;
+    /** Human-readable description */
+    description: string;
+    /** Zod schema for input validation */
+    inputSchema: ZodRawShape;
+    /** Toolsets this tool belongs to */
+    toolsets: Toolset[];
+    /** Whether this tool is GA (generally available). Defaults to true. */
+    isGA?: boolean;
+    /**
+     * Whether this tool requires a B2CInstance.
+     * Set to false for tools that don't need B2C instance connectivity (e.g., local scaffolding tools).
+     * Defaults to false.
+     */
+    requiresInstance?: boolean;
+    /**
+     * Whether this tool requires MRT API authentication.
+     * When true, creates an ApiKeyStrategy from SFCC_MRT_API_KEY environment variable.
+     * Defaults to false.
+     */
+    requiresMrtAuth?: boolean;
+    /**
+     * Execute function that performs the tool's operation.
+     * Receives validated input and a context with B2CInstance and/or auth based on requirements.
+     */
+    execute: (args: TInput, context: ToolExecutionContext) => Promise<TOutput>;
+    /**
+     * Format function that converts the execute output to a ToolResult.
+     * Use textResult(), jsonResult(), or errorResult() helpers.
+     */
+    formatOutput: (output: TOutput) => ToolResult;
+}
+/**
+ * Creates a text-only success result.
+ *
+ * @param text - The text content to return
+ * @returns A ToolResult with text content
+ *
+ * @example
+ * ```typescript
+ * return textResult('Operation completed successfully');
+ * ```
+ */
+export declare function textResult(text: string): ToolResult;
+/**
+ * Creates an error result.
+ *
+ * @param message - The error message
+ * @returns A ToolResult marked as an error
+ *
+ * @example
+ * ```typescript
+ * return errorResult('Failed to connect to instance');
+ * ```
+ */
+export declare function errorResult(message: string): ToolResult;
+/**
+ * Creates a JSON result with formatted output.
+ *
+ * @param data - The data to serialize as JSON
+ * @param indent - Number of spaces for indentation (default: 2)
+ * @returns A ToolResult with JSON-formatted text content
+ *
+ * @example
+ * ```typescript
+ * return jsonResult({ status: 'success', items: ['a', 'b', 'c'] });
+ * ```
+ */
+export declare function jsonResult(data: unknown, indent?: number): ToolResult;
+/**
+ * Creates an MCP tool from a b2c-tooling function.
+ *
+ * This adapter provides:
+ * - Input validation via Zod schemas
+ * - B2CInstance creation from dw.json with environment variable overrides
+ * - Consistent error handling
+ * - Output formatting utilities
+ *
+ * @template TInput - The validated input type (inferred from inputSchema)
+ * @template TOutput - The output type from the execute function
+ * @param options - Tool adapter configuration
+ * @param services - Services instance for dependency injection
+ * @returns An McpTool ready for registration
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ * import { createToolAdapter, jsonResult, errorResult } from './adapter.js';
+ *
+ * const listCodeVersionsTool = createToolAdapter({
+ *   name: 'code_version_list',
+ *   description: 'List all code versions on the instance',
+ *   toolsets: ['CARTRIDGES'],
+ *   inputSchema: {},
+ *   execute: async (_args, { instance }) => {
+ *     const result = await instance.ocapi.GET('/code_versions', {});
+ *     if (result.error) throw new Error(result.error.message);
+ *     return result.data;
+ *   },
+ *   formatOutput: (data) => jsonResult(data),
+ * }, services);
+ * ```
+ */
+export declare function createToolAdapter<TInput, TOutput>(options: ToolAdapterOptions<TInput, TOutput>, services: Services): McpTool;

package/dist/tools/adapter.js

@@ -0,0 +1,220 @@
+/*
+ * 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
+ */
+/**
+ * Tool Adapter for wrapping b2c-tooling-sdk functions as MCP tools.
+ *
+ * This module provides utilities for creating standardized MCP tools that:
+ * - Validate input using Zod schemas
+ * - Inject pre-resolved B2CInstance for WebDAV/OCAPI operations (requiresInstance)
+ * - Inject pre-resolved MRT auth for MRT API operations (requiresMrtAuth)
+ * - Format output consistently (textResult, jsonResult, errorResult)
+ *
+ * ## Configuration Resolution
+ *
+ * Both B2C instance and MRT auth are resolved once at server startup via
+ * {@link Services.fromResolvedConfig} and reused for all tool calls:
+ *
+ * - **B2CInstance**: Resolved from flags + dw.json. Available when `requiresInstance: true`.
+ * - **MRT Auth**: Resolved from --api-key → SFCC_MRT_API_KEY → ~/.mobify. Available when `requiresMrtAuth: true`.
+ *
+ * This "resolve eagerly at startup" pattern provides:
+ * - Fail-fast behavior (configuration errors surface at startup)
+ * - Consistent mental model (both resolved the same way)
+ * - Better performance (no resolution on each tool call)
+ *
+ * @module tools/adapter
+ *
+ * @example B2C Instance tool (WebDAV/OCAPI)
+ * ```typescript
+ * const myTool = createToolAdapter({
+ *   name: 'my_tool',
+ *   description: 'Does something useful',
+ *   toolsets: ['CARTRIDGES'],
+ *   requiresInstance: true,
+ *   inputSchema: {
+ *     cartridgeName: z.string().describe('Name of the cartridge'),
+ *   },
+ *   execute: async (args, { b2cInstance }) => {
+ *     const result = await b2cInstance.webdav.get(`Cartridges/${args.cartridgeName}`);
+ *     return result;
+ *   },
+ *   formatOutput: (output) => textResult(`Fetched: ${output}`),
+ * }, services);
+ * ```
+ *
+ * @example MRT tool (MRT API)
+ * ```typescript
+ * // Services created from already-resolved config at startup
+ * const services = Services.fromResolvedConfig(this.resolvedConfig);
+ *
+ * const mrtTool = createToolAdapter({
+ *   name: 'mrt_bundle_push',
+ *   description: 'Push bundle to MRT',
+ *   toolsets: ['MRT'],
+ *   requiresMrtAuth: true,
+ *   inputSchema: {
+ *     projectSlug: z.string().describe('MRT project slug'),
+ *   },
+ *   execute: async (args, { mrtAuth }) => {
+ *     const result = await pushBundle({ projectSlug: args.projectSlug }, mrtAuth);
+ *     return result;
+ *   },
+ *   formatOutput: (output) => jsonResult(output),
+ * }, services);
+ * ```
+ */
+import { z } from 'zod';
+/**
+ * Creates a text-only success result.
+ *
+ * @param text - The text content to return
+ * @returns A ToolResult with text content
+ *
+ * @example
+ * ```typescript
+ * return textResult('Operation completed successfully');
+ * ```
+ */
+export function textResult(text) {
+    return {
+        content: [{ type: 'text', text }],
+    };
+}
+/**
+ * Creates an error result.
+ *
+ * @param message - The error message
+ * @returns A ToolResult marked as an error
+ *
+ * @example
+ * ```typescript
+ * return errorResult('Failed to connect to instance');
+ * ```
+ */
+export function errorResult(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+        isError: true,
+    };
+}
+/**
+ * Creates a JSON result with formatted output.
+ *
+ * @param data - The data to serialize as JSON
+ * @param indent - Number of spaces for indentation (default: 2)
+ * @returns A ToolResult with JSON-formatted text content
+ *
+ * @example
+ * ```typescript
+ * return jsonResult({ status: 'success', items: ['a', 'b', 'c'] });
+ * ```
+ */
+export function jsonResult(data, indent = 2) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data, null, indent) }],
+    };
+}
+/**
+ * Formats Zod validation errors into a human-readable string.
+ *
+ * @param error - The Zod error object
+ * @returns Formatted error message
+ */
+function formatZodErrors(error) {
+    return error.errors.map((e) => `${e.path.join('.') || 'input'}: ${e.message}`).join('; ');
+}
+/**
+ * Creates an MCP tool from a b2c-tooling function.
+ *
+ * This adapter provides:
+ * - Input validation via Zod schemas
+ * - B2CInstance creation from dw.json with environment variable overrides
+ * - Consistent error handling
+ * - Output formatting utilities
+ *
+ * @template TInput - The validated input type (inferred from inputSchema)
+ * @template TOutput - The output type from the execute function
+ * @param options - Tool adapter configuration
+ * @param services - Services instance for dependency injection
+ * @returns An McpTool ready for registration
+ *
+ * @example
+ * ```typescript
+ * import { z } from 'zod';
+ * import { createToolAdapter, jsonResult, errorResult } from './adapter.js';
+ *
+ * const listCodeVersionsTool = createToolAdapter({
+ *   name: 'code_version_list',
+ *   description: 'List all code versions on the instance',
+ *   toolsets: ['CARTRIDGES'],
+ *   inputSchema: {},
+ *   execute: async (_args, { instance }) => {
+ *     const result = await instance.ocapi.GET('/code_versions', {});
+ *     if (result.error) throw new Error(result.error.message);
+ *     return result.data;
+ *   },
+ *   formatOutput: (data) => jsonResult(data),
+ * }, services);
+ * ```
+ */
+export function createToolAdapter(options, services) {
+    const { name, description, inputSchema, toolsets, isGA = true, requiresInstance = false, requiresMrtAuth = false, execute, formatOutput, } = options;
+    // Create Zod schema from inputSchema definition
+    const zodSchema = z.object(inputSchema);
+    return {
+        name,
+        description,
+        inputSchema,
+        toolsets,
+        isGA,
+        async handler(rawArgs) {
+            // 1. Validate input with Zod
+            const parseResult = zodSchema.safeParse(rawArgs);
+            if (!parseResult.success) {
+                return errorResult(`Invalid input: ${formatZodErrors(parseResult.error)}`);
+            }
+            const args = parseResult.data;
+            try {
+                // 2. Get B2CInstance if required (pre-resolved at startup)
+                let b2cInstance;
+                if (requiresInstance) {
+                    if (!services.b2cInstance) {
+                        return errorResult('B2C instance error: Instance configuration required. Provide --server flag, set SFCC_SERVER environment variable, or configure dw.json');
+                    }
+                    b2cInstance = services.b2cInstance;
+                }
+                // 3. Get MRT config if required (pre-resolved at startup)
+                let mrtConfig;
+                if (requiresMrtAuth) {
+                    if (!services.mrtConfig.auth) {
+                        return errorResult('MRT auth error: MRT API key required. Provide --api-key, set SFCC_MRT_API_KEY environment variable, or configure ~/.mobify');
+                    }
+                    mrtConfig = {
+                        auth: services.mrtConfig.auth,
+                        project: services.mrtConfig.project,
+                        environment: services.mrtConfig.environment,
+                        origin: services.mrtConfig.origin,
+                    };
+                }
+                // 4. Execute the operation
+                const context = {
+                    b2cInstance,
+                    mrtConfig,
+                    services,
+                };
+                const output = await execute(args, context);
+                // 5. Format output
+                return formatOutput(output);
+            }
+            catch (error) {
+                // Handle execution errors
+                const message = error instanceof Error ? error.message : String(error);
+                return errorResult(`Execution error: ${message}`);
+            }
+        },
+    };
+}
+//# sourceMappingURL=adapter.js.map

package/dist/tools/cartridges/index.d.ts

@@ -0,0 +1,20 @@
+import type { McpTool } from '../../utils/index.js';
+import type { Services } from '../../services.js';
+import type { DeployResult, DeployOptions } from '@salesforce/b2c-tooling-sdk/operations/code';
+import type { B2CInstance } from '@salesforce/b2c-tooling-sdk';
+/**
+ * Optional dependency injections for testing.
+ */
+interface CartridgeToolInjections {
+    /** Mock findAndDeployCartridges function for testing */
+    findAndDeployCartridges?: (instance: B2CInstance, directory: string, options: DeployOptions) => Promise<DeployResult>;
+}
+/**
+ * Creates all tools for the CARTRIDGES toolset.
+ *
+ * @param services - MCP services
+ * @param injections - Optional dependency injections for testing
+ * @returns Array of MCP tools
+ */
+export declare function createCartridgesTools(services: Services, injections?: CartridgeToolInjections): McpTool[];
+export {};