@salesforce/b2c-dx-mcp 1.10.1 → 2.0.0

package/dist/commands/mcp.d.ts

@@ -1,6 +1,7 @@
 import { BaseCommand } from '@salesforce/b2c-tooling-sdk/cli';
 import type { ResolvedB2CConfig } from '@salesforce/b2c-tooling-sdk/config';
 import { Services } from '../services.js';
+import type { ProjectContextInput } from '../tools/project-context.js';
 /**
  * oclif Command that starts the B2C DX MCP server.
  *
@@ -81,13 +82,16 @@ export default class McpServerCommand extends BaseCommand<typeof McpServerComman
      * - extractInstanceFlags() - B2C instance flags (--server, --username, etc.)
      * - extractMrtFlags() - MRT flags (--api-key, --project, etc.) and loading options
      *
-     * Priority (highest to lowest):
-     * 1. CLI flags (--server, --username, --api-key, etc.)
-     * 2. Environment variables (SFCC_SERVER, SFCC_USERNAME, MRT_API_KEY, etc.)
-     * 3. dw.json file (via --config flag or auto-discovered from --project-directory)
-     * 4. ~/.mobify file (for MRT API key)
+     * Configuration file selection (highest to lowest):
+     * 1. Per-call configPath
+     * 2. Startup --config / SFCC_CONFIG
+     * 3. SFCC_CONFIG from the selected project's .env
+     * 4. dw.json in the selected project directory
+     *
+     * Values are then merged through the normal CLI resolver, including
+     * environment, plugin, dw.json, ~/.mobify, and package.json sources.
      */
-    protected loadConfiguration(): Promise<ResolvedB2CConfig>;
+    protected loadConfiguration(projectContext?: ProjectContextInput): Promise<ResolvedB2CConfig>;
     /**
      * Loads configuration and creates a new Services instance.
      *
@@ -97,7 +101,7 @@ export default class McpServerCommand extends BaseCommand<typeof McpServerComman
      *
      * @returns A new Services instance with loaded configuration
      */
-    protected loadServices(): Promise<Services>;
+    protected loadServices(projectContext?: ProjectContextInput): Promise<Services>;
     /**
      * Main entry point - starts the MCP server.
      *
@@ -125,4 +129,6 @@ export default class McpServerCommand extends BaseCommand<typeof McpServerComman
      * These can be exposed to Services if needed for features like telemetry or caching.
      */
     run(): Promise<void>;
+    /** Parse a project's .env without mutating the long-lived MCP process environment. */
+    private loadProjectEnvironment;
 }

package/dist/commands/mcp.js

@@ -132,8 +132,10 @@
  * { "args": ["--toolsets", "all", "--allow-non-ga-tools", "--debug"] }
  * ```
  */
+import path from 'node:path';
 import { Flags } from '@oclif/core';
 import { BaseCommand, MrtCommand, InstanceCommand, loadConfig, extractInstanceFlags, extractMrtFlags, } from '@salesforce/b2c-tooling-sdk/cli';
+import { EnvSource, readProjectEnvironment } from '@salesforce/b2c-tooling-sdk/config';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { B2CDxMcpServer } from '../server.js';
 import { Services } from '../services.js';
@@ -240,24 +242,47 @@ export default class McpServerCommand extends BaseCommand {
      * - extractInstanceFlags() - B2C instance flags (--server, --username, etc.)
      * - extractMrtFlags() - MRT flags (--api-key, --project, etc.) and loading options
      *
-     * Priority (highest to lowest):
-     * 1. CLI flags (--server, --username, --api-key, etc.)
-     * 2. Environment variables (SFCC_SERVER, SFCC_USERNAME, MRT_API_KEY, etc.)
-     * 3. dw.json file (via --config flag or auto-discovered from --project-directory)
-     * 4. ~/.mobify file (for MRT API key)
+     * Configuration file selection (highest to lowest):
+     * 1. Per-call configPath
+     * 2. Startup --config / SFCC_CONFIG
+     * 3. SFCC_CONFIG from the selected project's .env
+     * 4. dw.json in the selected project directory
+     *
+     * Values are then merged through the normal CLI resolver, including
+     * environment, plugin, dw.json, ~/.mobify, and package.json sources.
      */
-    async loadConfiguration() {
+    async loadConfiguration(projectContext) {
         const mrt = extractMrtFlags(this.flags);
+        const baseOptions = this.getBaseConfigOptions();
+        const effectiveProjectDirectory = projectContext?.projectDirectory ?? baseOptions.projectDirectory;
+        const projectEnvironment = this.loadProjectEnvironment(effectiveProjectDirectory);
+        const projectConfigPath = projectEnvironment?.SFCC_CONFIG;
+        const configPath = (projectContext?.configPath
+            ? path.resolve(effectiveProjectDirectory ?? process.cwd(), projectContext.configPath)
+            : undefined) ??
+            baseOptions.configPath ??
+            (projectConfigPath && effectiveProjectDirectory
+                ? path.isAbsolute(projectConfigPath)
+                    ? projectConfigPath
+                    : path.resolve(effectiveProjectDirectory, projectConfigPath)
+                : undefined);
         const options = {
-            ...this.getBaseConfigOptions(),
+            ...baseOptions,
             ...mrt.options,
+            configPath,
+            ...(projectContext?.projectDirectory && {
+                projectDirectory: projectContext.projectDirectory,
+                workingDirectory: projectContext.projectDirectory,
+            }),
         };
         // Combine B2C instance flags and MRT config flags
         const flagConfig = {
             ...extractInstanceFlags(this.flags),
             ...mrt.config,
         };
-        return loadConfig(flagConfig, options);
+        return loadConfig(flagConfig, options, {
+            before: projectEnvironment ? [new EnvSource(projectEnvironment)] : undefined,
+        });
     }
     /**
      * Loads configuration and creates a new Services instance.
@@ -268,9 +293,11 @@ export default class McpServerCommand extends BaseCommand {
      *
      * @returns A new Services instance with loaded configuration
      */
-    async loadServices() {
-        const config = await this.loadConfiguration();
-        return Services.fromResolvedConfig(config);
+    async loadServices(projectContext) {
+        const config = await this.loadConfiguration(projectContext);
+        const effectiveProjectDirectory = projectContext?.projectDirectory ?? this.flags?.['project-directory'];
+        const projectEnvironment = this.loadProjectEnvironment(effectiveProjectDirectory);
+        return Services.fromResolvedConfig(config, projectEnvironment);
     }
     /**
      * Main entry point - starts the MCP server.
@@ -362,5 +389,19 @@ export default class McpServerCommand extends BaseCommand {
         });
         this.logger.info({ version: this.config.version }, 'MCP Server running on stdio');
     }
+    /** Parse a project's .env without mutating the long-lived MCP process environment. */
+    loadProjectEnvironment(projectDirectory) {
+        if (!projectDirectory)
+            return undefined;
+        const envPath = path.join(projectDirectory, '.env');
+        try {
+            return readProjectEnvironment(projectDirectory);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.logger?.warn({ envPath, error: message }, '[Config] Failed to load project .env file');
+        }
+        return undefined;
+    }
 }
 //# sourceMappingURL=mcp.js.map

package/dist/registry.d.ts

@@ -4,6 +4,7 @@ import type { McpTool, Toolset, StartupFlags } from './utils/index.js';
 import type { B2CDxMcpServer } from './server.js';
 import type { Services } from './services.js';
 import type { ServerContext } from './server-context.js';
+import type { ProjectContextInput } from './tools/project-context.js';
 /**
  * Registry of tools organized by toolset.
  * Tools can belong to multiple toolsets via their `toolsets` array.
@@ -17,5 +18,5 @@ export type ToolRegistry = Record<Toolset, McpTool[]>;
  * @param loadServices - Function that loads configuration and returns Services instance
  * @returns Complete tool registry
  */
-export declare function createToolRegistry(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext, detectedWorkspaces?: readonly ProjectType[], enabledDocCategories?: readonly DocCategory[]): ToolRegistry;
-export declare function registerToolsets(flags: StartupFlags, server: B2CDxMcpServer, loadServices: () => Promise<Services> | Services, serverContext?: ServerContext): Promise<void>;
+export declare function createToolRegistry(loadServices: (projectContext?: ProjectContextInput) => Promise<Services> | Services, serverContext?: ServerContext, detectedWorkspaces?: readonly ProjectType[], enabledDocCategories?: readonly DocCategory[]): ToolRegistry;
+export declare function registerToolsets(flags: StartupFlags, server: B2CDxMcpServer, loadServices: (projectContext?: ProjectContextInput) => Promise<Services> | Services, serverContext?: ServerContext): Promise<void>;

package/dist/server-context.d.ts

@@ -18,7 +18,7 @@ import { DebugSessionRegistry } from './tools/diagnostics/session-registry.js';
  * client would also share the same context. Tools that mutate registries
  * (like the debug tools) should not assume single-tenant access.
  *
- * The registries dedup on a stable key (host:client_id for debug, hostname for
+ * The registries dedup on an internal stable key (host plus MCP-owned debugger client ID, hostname for
  * SFCC log watches, project/environment/origin for MRT log watches), so
  * multi-agent use is functional but agents may see each other's
  * sessions/watches via list tools.

package/dist/server-context.js

@@ -23,7 +23,7 @@ import { DebugSessionRegistry } from './tools/diagnostics/session-registry.js';
  * client would also share the same context. Tools that mutate registries
  * (like the debug tools) should not assume single-tenant access.
  *
- * The registries dedup on a stable key (host:client_id for debug, hostname for
+ * The registries dedup on an internal stable key (host plus MCP-owned debugger client ID, hostname for
  * SFCC log watches, project/environment/origin for MRT log watches), so
  * multi-agent use is functional but agents may see each other's
  * sessions/watches via list tools.

package/dist/services.d.ts

@@ -65,6 +65,8 @@ export interface ServicesOptions {
     mrtConfig?: MrtConfig;
     /** Resolved configuration for access to SCAPI settings */
     resolvedConfig: ResolvedB2CConfig;
+    /** Project-scoped environment parsed from the effective project's .env file. */
+    projectEnvironment?: Readonly<Record<string, string | undefined>>;
 }
 /**
  * Services class that provides utilities for MCP tools.
@@ -100,6 +102,7 @@ export declare class Services {
      * Provides access to shortCode, tenantId, and OAuth credentials.
      * @private
      */
+    private readonly projectEnvironment;
     private readonly resolvedConfig;
     constructor(opts: ServicesOptions);
     /**
@@ -114,7 +117,7 @@ export declare class Services {
      * const services = Services.fromResolvedConfig(this.resolvedConfig);
      * ```
      */
-    static fromResolvedConfig(config: ResolvedB2CConfig): Services;
+    static fromResolvedConfig(config: ResolvedB2CConfig, projectEnvironment?: Readonly<Record<string, string | undefined>>): Services;
     /**
      * Check if a file or directory exists.
      *
@@ -143,6 +146,11 @@ export declare class Services {
      * Get the current working directory.
      */
     getCwd(): string;
+    /**
+     * Read an environment variable with the ambient process environment taking
+     * precedence over the project-scoped .env value.
+     */
+    getEnvironmentVariable(name: string): string | undefined;
     /**
      * Get the user's home directory.
      */

package/dist/services.js

@@ -79,11 +79,13 @@ export class Services {
      * Provides access to shortCode, tenantId, and OAuth credentials.
      * @private
      */
+    projectEnvironment;
     resolvedConfig;
     constructor(opts) {
         this.b2cInstance = opts.b2cInstance;
         this.mrtConfig = opts.mrtConfig ?? {};
         this.resolvedConfig = opts.resolvedConfig;
+        this.projectEnvironment = opts.projectEnvironment ?? {};
     }
     /**
      * Creates a Services instance from an already-resolved configuration.
@@ -97,7 +99,7 @@ export class Services {
      * const services = Services.fromResolvedConfig(this.resolvedConfig);
      * ```
      */
-    static fromResolvedConfig(config) {
+    static fromResolvedConfig(config, projectEnvironment) {
         // Build MRT config using factory methods
         const mrtConfig = {
             auth: config.hasMrtConfig() ? config.createMrtAuth() : undefined,
@@ -111,6 +113,7 @@ export class Services {
             b2cInstance,
             mrtConfig,
             resolvedConfig: config,
+            projectEnvironment,
         });
     }
     // ============================================
@@ -161,6 +164,13 @@ export class Services {
     getCwd() {
         return process.cwd();
     }
+    /**
+     * Read an environment variable with the ambient process environment taking
+     * precedence over the project-scoped .env value.
+     */
+    getEnvironmentVariable(name) {
+        return process.env[name] ?? this.projectEnvironment[name];
+    }
     /**
      * Get the user's home directory.
      */

package/dist/tools/adapter.d.ts

@@ -69,6 +69,7 @@ import type { B2CInstance } from '@salesforce/b2c-tooling-sdk';
 import type { McpTool, ToolResult, Toolset } from '../utils/index.js';
 import type { Services, MrtConfig } from '../services.js';
 import type { ServerContext } from '../server-context.js';
+import { type ProjectContextInput } from './project-context.js';
 /**
  * Context provided to tool execute functions.
  * Contains the B2CInstance and/or MRT config based on tool requirements.
@@ -125,6 +126,12 @@ export interface ToolAdapterOptions<TInput, TOutput> {
      * Defaults to false.
      */
     requiresMrtAuth?: boolean;
+    /**
+     * Whether this tool resolves configuration or files relative to a project.
+     * Project-aware tools automatically expose a per-call `projectDirectory`
+     * input and use it while loading Services.
+     */
+    usesProjectContext?: boolean;
     /**
      * Execute function that performs the tool's operation.
      * Receives validated input and a context with B2CInstance and/or auth based on requirements.
@@ -212,4 +219,4 @@ export declare function jsonResult(data: unknown, indent?: number): ToolResult;
  * }, loadServices);
  * ```
  */
-export declare function createToolAdapter<TInput, TOutput>(options: ToolAdapterOptions<TInput, TOutput>, loadServices: () => Promise<Services> | Services, serverContext?: ServerContext): McpTool;
+export declare function createToolAdapter<TInput, TOutput>(options: ToolAdapterOptions<TInput, TOutput>, loadServices: (projectContext?: ProjectContextInput) => Promise<Services> | Services, serverContext?: ServerContext): McpTool;

package/dist/tools/adapter.js

@@ -70,6 +70,7 @@
  * ```
  */
 import { z } from 'zod';
+import { projectContextInputSchema } from './project-context.js';
 /**
  * Creates a text-only success result.
  *
@@ -169,13 +170,17 @@ function formatZodErrors(error) {
  * ```
  */
 export function createToolAdapter(options, loadServices, serverContext) {
-    const { name, description, inputSchema, toolsets, isGA = true, requiresInstance = false, requiresMrtAuth = false, execute, formatOutput, } = options;
+    const { name, description, inputSchema, toolsets, isGA = true, requiresInstance = false, requiresMrtAuth = false, usesProjectContext = false, execute, formatOutput, } = options;
+    const effectiveUsesProjectContext = usesProjectContext || requiresInstance || requiresMrtAuth;
+    const effectiveInputSchema = effectiveUsesProjectContext
+        ? { ...projectContextInputSchema, ...inputSchema }
+        : inputSchema;
     // Create Zod schema from inputSchema definition
-    const zodSchema = z.object(inputSchema);
+    const zodSchema = z.object(effectiveInputSchema);
     return {
         name,
         description,
-        inputSchema,
+        inputSchema: effectiveInputSchema,
         toolsets,
         isGA,
         async handler(rawArgs) {
@@ -187,7 +192,8 @@ export function createToolAdapter(options, loadServices, serverContext) {
             const args = parseResult.data;
             try {
                 // 2. Load Services to get fresh configuration (re-reads config files)
-                const services = await loadServices();
+                const projectContext = effectiveUsesProjectContext ? args : undefined;
+                const services = await loadServices(projectContext);
                 // 3. Get B2CInstance if required (loaded on each call)
                 let b2cInstance;
                 if (requiresInstance) {

package/dist/tools/cartridges/index.js

@@ -44,6 +44,7 @@ function createCartridgeDeployTool(loadServices, injections) {
         toolsets: ['CARTRIDGES'],
         isGA: true,
         requiresInstance: true,
+        usesProjectContext: true,
         inputSchema: {
             directory: z
                 .string()
@@ -87,7 +88,8 @@ function createCartridgeDeployTool(loadServices, injections) {
                     instance.config.codeVersion = codeVersion;
                 }
                 // Resolve directory path: relative paths are resolved relative to project directory, absolute paths are used as-is
-                const directory = context.services.resolveWithProjectDirectory(args.directory);
+                const projectDirectory = context.services.resolveProjectDirectory(args.projectDirectory);
+                const directory = context.services.resolveWithProjectDirectory(args.directory, args.projectDirectory);
                 // Parse options
                 const options = {
                     include: args.cartridges,
@@ -106,6 +108,7 @@ function createCartridgeDeployTool(loadServices, injections) {
                 const result = await findAndDeployCartridgesFn(instance, directory, options);
                 return {
                     ...result,
+                    projectDirectory,
                     resolvedDirectory: directory,
                     postInstructions: CARTRIDGE_PATH_REMINDER,
                 };

package/dist/tools/diagnostics/config-inspect.js

@@ -20,11 +20,12 @@ export function createConfigInspectTool(loadServices) {
         name: 'config_inspect',
         description: 'Inspect the resolved B2C Commerce configuration the MCP server is using — instance hostname, auth, SCAPI, MRT, and other settings — along with which source (dw.json, environment variables, flags) provided each value. ' +
             'Secrets (passwords, client secrets, API keys) are redacted by default. ' +
-            'The output includes the effective projectDirectory and how it was resolved (explicit --project-directory / SFCC_PROJECT_DIRECTORY vs. the process working directory), which is useful for diagnosing why the server targets the wrong instance or cannot find a project. ' +
+            'Pass projectDirectory and/or configPath to inspect the same project and dw.json-format file a CLI command would use. The output includes the effective projectDirectory and source provenance, which is useful for diagnosing why the server targets the wrong instance or cannot find a project. ' +
             'Use this first when configuration seems wrong, auth is failing, or the server appears to be operating in the wrong directory.',
         toolsets: ['DIAGNOSTICS'],
         isGA: true,
         requiresInstance: false,
+        usesProjectContext: true,
         inputSchema: {
             unmask: z
                 .boolean()
@@ -33,7 +34,7 @@ export function createConfigInspectTool(loadServices) {
         },
         async execute(args, { services }) {
             const resolved = services.getResolvedConfig();
-            const projectDirectory = services.resolveProjectDirectory();
+            const projectDirectory = services.resolveProjectDirectory(args.projectDirectory);
             return {
                 config: redactConfigValues(resolved.values, { unmask: args.unmask ?? false }),
                 projectDirectory,

package/dist/tools/diagnostics/debug-list-sessions.js

@@ -22,7 +22,6 @@ export function createDebugListSessionsTool(loadServices, serverContext) {
                     return {
                         session_id: entry.sessionId,
                         hostname: entry.hostname,
-                        client_id: entry.clientId,
                         halted_threads: entry.manager
                             .getKnownThreads()
                             .filter((t) => t.status === 'halted')

package/dist/tools/diagnostics/debug-start-session.js

@@ -3,6 +3,7 @@
  * 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 { randomUUID } from 'node:crypto';
 import { z } from 'zod';
 import { createToolAdapter, jsonResult } from '../adapter.js';
 import { DebugSessionManager, createSourceMapper, } from '@salesforce/b2c-tooling-sdk/operations/debug';
@@ -12,19 +13,17 @@ export function createDebugStartSessionTool(loadServices, serverContext) {
     return createToolAdapter({
         name: 'debug_start_session',
         description: 'Start a script debugger session on a B2C Commerce instance to debug SFRA controllers, custom API scripts, hooks, jobs, or any server-side script. ' +
+            'Uses projectDirectory to load project configuration and discover cartridges. cartridgeDirectory may override only the cartridge discovery/source-mapping root. ' +
             'Returns a session_id for use with other debug tools, plus discovered cartridge mappings. ' +
             'WARNING: Debug sessions halt remote request threads on the instance. Always call debug_end_session when finished.',
         toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'SCAPI'],
         inputSchema: {
-            cartridge_directory: z
+            cartridgeDirectory: z
                 .string()
                 .optional()
-                .describe('Path to directory containing cartridges. Defaults to project directory.'),
-            client_id: z
-                .string()
-                .optional()
-                .describe('Client ID for the debugger API. Defaults to "b2c-cli". Use a different ID to run concurrent sessions on the same host.'),
+                .describe('Optional cartridge discovery and debugger source-mapping root. Relative paths resolve from projectDirectory. Defaults to projectDirectory.'),
         },
+        usesProjectContext: true,
         async execute(args, context) {
             const registry = getRegistry(context);
             const credentials = context.services.getBasicAuthCredentials();
@@ -33,8 +32,9 @@ export function createDebugStartSessionTool(loadServices, serverContext) {
                     'Set via SFCC_SERVER/SFCC_USERNAME/SFCC_PASSWORD env vars, or dw.json.');
             }
             const { hostname, username, password } = credentials;
-            const clientId = args.client_id ?? 'b2c-cli';
-            const cartridgeDir = context.services.resolveWithProjectDirectory(args.cartridge_directory);
+            const clientId = `b2c-dx-mcp-${randomUUID()}`;
+            const projectDirectory = context.services.resolveProjectDirectory(args.projectDirectory);
+            const cartridgeDir = context.services.resolveWithProjectDirectory(args.cartridgeDirectory, args.projectDirectory);
             const cartridges = findCartridges(cartridgeDir);
             const warnings = [];
             if (cartridges.length === 0) {
@@ -70,6 +70,8 @@ export function createDebugStartSessionTool(loadServices, serverContext) {
                 cartridge_mappings: cartridgeMappings,
                 session_cookie: dwsid ? { name: 'dwsid', value: dwsid } : null,
                 warnings,
+                projectDirectory,
+                cartridgeDirectory: cartridgeDir,
             };
         },
         formatOutput: (output) => jsonResult(output),

package/dist/tools/diagnostics/session-registry.js

@@ -67,9 +67,9 @@ export class DebugSessionRegistry {
         const { hostname, clientId, manager, sourceMapper, cartridges } = opts;
         const existing = this.findByHostAndClientId(hostname, clientId);
         if (existing) {
-            throw new Error(`A debug session already exists for ${hostname} with client ID "${clientId}" ` +
+            throw new Error(`A debug session already exists for ${hostname} ` +
                 `(session_id: "${existing.sessionId}"). ` +
-                `End it with debug_end_session first, or use a different client_id.`);
+                `End it with debug_end_session first.`);
         }
         const sessionId = randomUUID();
         const now = Date.now();

package/dist/tools/mrt/index.js

@@ -127,6 +127,7 @@ function createMrtBundlePushTool(loadServices, injections) {
         isGA: true,
         // MRT operations use ApiKeyStrategy from MRT_API_KEY or ~/.mobify
         requiresMrtAuth: true,
+        usesProjectContext: true,
         inputSchema: {
             buildDirectory: z
                 .string()
@@ -167,12 +168,13 @@ function createMrtBundlePushTool(loadServices, injections) {
             // Get origin from --cloud-origin flag or mrtOrigin config (optional)
             const origin = context.mrtConfig?.origin;
             // Detect project type and get project-type-aware defaults
-            const projectDir = context.services.resolveWithProjectDirectory();
+            const projectDirectory = context.services.resolveProjectDirectory(args.projectDirectory);
+            const projectDir = projectDirectory.path;
             const { projectTypes } = await detectWorkspaceTypeFn(projectDir);
             const defaults = getDefaultsForProjectTypes(projectTypes);
             const ssrOnly = args.ssrOnly ? parseGlobPatterns(args.ssrOnly) : defaults.ssrOnly;
             const ssrShared = args.ssrShared ? parseGlobPatterns(args.ssrShared) : defaults.ssrShared;
-            const buildDirectory = context.services.resolveWithProjectDirectory(args.buildDirectory ?? defaults.buildDirectory);
+            const buildDirectory = context.services.resolveWithProjectDirectory(args.buildDirectory ?? defaults.buildDirectory, args.projectDirectory);
             // Log all computed variables before pushing bundle
             const logger = getLogger();
             logger.debug({
@@ -196,7 +198,11 @@ function createMrtBundlePushTool(loadServices, injections) {
                 target: environment,
                 origin, // MRT API origin URL (optional, defaults to https://cloud.mobify.com)
             }, context.mrtConfig.auth);
-            return result;
+            return {
+                ...result,
+                projectDirectory,
+                resolvedBuildDirectory: buildDirectory,
+            };
         },
         formatOutput: (output) => jsonResult(output),
     }, loadServices);

package/dist/tools/project-context.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+/** Input shared by MCP tools that resolve files or configuration from a project. */
+export interface ProjectContextInput {
+    /** Per-call project directory override. */
+    projectDirectory?: string;
+    /** Per-call explicit dw.json-format configuration path. */
+    configPath?: string;
+}
+/** Effective project directory and the source that selected it. */
+export interface ProjectDirectoryInfo {
+    path: string;
+    source: 'argument' | 'config' | 'cwd';
+}
+/** Shared schema field injected into every project-aware MCP tool. */
+export declare const projectDirectoryInput: z.ZodOptional<z.ZodString>;
+/** Shared explicit dw.json path field injected into every project-aware MCP tool. */
+export declare const configPathInput: z.ZodOptional<z.ZodString>;
+/** Shared schema fields injected into every project-aware MCP tool. */
+export declare const projectContextInputSchema: {
+    projectDirectory: z.ZodOptional<z.ZodString>;
+    configPath: z.ZodOptional<z.ZodString>;
+};

package/dist/tools/project-context.js

@@ -0,0 +1,22 @@
+/*
+ * 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 { z } from 'zod';
+/** Shared schema field injected into every project-aware MCP tool. */
+export const projectDirectoryInput = z
+    .string()
+    .optional()
+    .describe('Absolute project directory for this call. Overrides --project-directory / SFCC_PROJECT_DIRECTORY and the MCP process working directory. Also controls project-local configuration discovery.');
+/** Shared explicit dw.json path field injected into every project-aware MCP tool. */
+export const configPathInput = z
+    .string()
+    .optional()
+    .describe('Explicit path to a dw.json-format configuration file for this call. Overrides startup --config / SFCC_CONFIG and project .env SFCC_CONFIG. Relative paths resolve from projectDirectory.');
+/** Shared schema fields injected into every project-aware MCP tool. */
+export const projectContextInputSchema = {
+    projectDirectory: projectDirectoryInput,
+    configPath: configPathInput,
+};
+//# sourceMappingURL=project-context.js.map

package/dist/tools/scapi/metrics-get.js

@@ -63,6 +63,7 @@ Retrieve observability metrics time-series for a B2C Commerce tenant. Returns me
         toolsets: ['SCAPI'],
         isGA: false,
         requiresInstance: false, // SCAPI uses OAuth directly
+        usesProjectContext: true,
         inputSchema: {
             category: z
                 .enum(['overall', 'sales', 'ecdn', 'third-party', 'scapi', 'scapi-hooks', 'mrt', 'controller', 'ocapi'])

package/dist/tools/scapi/scapi-custom-api-generate-scaffold.d.ts

@@ -1,5 +1,6 @@
 import type { Services } from '../../services.js';
 import type { McpTool } from '../../utils/index.js';
+import type { ProjectContextInput, ProjectDirectoryInfo } from '../project-context.js';
 import type { Scaffold, ResolvedParameters, ResolveParametersOptions } from '@salesforce/b2c-tooling-sdk/scaffold';
 /** Optional overrides for testing (scaffold not found, missing required). */
 export interface ScaffoldCustomApiExecuteOverrides {
@@ -12,7 +13,7 @@ export interface ScaffoldCustomApiExecuteOverrides {
  * Input schema for scapi_custom_api_generate_scaffold tool.
  * Parameters match the custom-api scaffold: apiName, apiType, cartridgeName, etc.
  */
-interface ScaffoldCustomApiInput {
+interface ScaffoldCustomApiInput extends ProjectContextInput {
     /** API name (kebab-case, e.g. my-products). Required. */
     apiName: string;
     /** Cartridge name that will contain the API. Optional; defaults to first cartridge found in project. */
@@ -40,6 +41,8 @@ interface ScaffoldCustomApiOutput {
     }>;
     postInstructions?: string;
     error?: string;
+    projectDirectory: ProjectDirectoryInfo;
+    projectRoot: string;
 }
 /**
  * Core execute logic for the custom API scaffold tool.

package/dist/tools/scapi/scapi-custom-api-generate-scaffold.js

@@ -21,7 +21,8 @@ const CUSTOM_API_SCAFFOLD_ID = 'custom-api';
  * Exported for tests so we can inject getScaffold / resolveScaffoldParameters and cover error branches.
  */
 export async function executeScaffoldCustomApi(args, services, overrides) {
-    const projectRoot = services.resolveWithProjectDirectory(args.projectRoot);
+    const projectDirectory = services.resolveProjectDirectory(args.projectDirectory);
+    const projectRoot = services.resolveWithProjectDirectory(args.projectRoot, args.projectDirectory);
     const getScaffold = overrides?.getScaffold ??
         (async (id, opts) => {
             const registry = createScaffoldRegistry();
@@ -34,6 +35,8 @@ export async function executeScaffoldCustomApi(args, services, overrides) {
             outputDir: projectRoot,
             dryRun: false,
             files: [],
+            projectDirectory,
+            projectRoot,
             error: `Scaffold not found: ${CUSTOM_API_SCAFFOLD_ID}. Ensure @salesforce/b2c-tooling-sdk is installed.`,
         };
     }
@@ -44,6 +47,8 @@ export async function executeScaffoldCustomApi(args, services, overrides) {
             outputDir: projectRoot,
             dryRun: false,
             files: [],
+            projectDirectory,
+            projectRoot,
             error: 'No cartridges found in project. Custom API scaffold requires an existing cartridge. Create a cartridge first: use `b2c scaffold cartridge --name app_custom`, or manually create a directory with a `.project` file (e.g., cartridges/app_custom/.project).',
         };
     }
@@ -73,6 +78,8 @@ export async function executeScaffoldCustomApi(args, services, overrides) {
             outputDir: projectRoot,
             dryRun: false,
             files: [],
+            projectDirectory,
+            projectRoot,
             error: `Parameter validation failed: ${message}`,
         };
     }
@@ -83,6 +90,8 @@ export async function executeScaffoldCustomApi(args, services, overrides) {
             outputDir: projectRoot,
             dryRun: false,
             files: [],
+            projectDirectory,
+            projectRoot,
             error: `Missing required parameter: ${missingRequired[0].name}. For cartridgeName, ensure the cartridge exists in the project (under projectRoot).`,
         };
     }
@@ -108,6 +117,8 @@ export async function executeScaffoldCustomApi(args, services, overrides) {
                 skipReason: f.skipReason,
             })),
             postInstructions: result.postInstructions,
+            projectDirectory,
+            projectRoot,
         };
     }
     catch (error) {
@@ -117,6 +128,8 @@ export async function executeScaffoldCustomApi(args, services, overrides) {
             outputDir,
             dryRun: false,
             files: [],
+            projectDirectory,
+            projectRoot,
             error: `Scaffold generation failed: ${message}`,
         };
     }
@@ -140,6 +153,7 @@ apiDescription, projectRoot, outputDir.`,
         toolsets: ['PWAV3', 'SCAPI', 'STOREFRONTNEXT'],
         isGA: true,
         requiresInstance: false,
+        usesProjectContext: true,
         inputSchema: {
             apiName: z
                 .string()
@@ -158,7 +172,7 @@ apiDescription, projectRoot, outputDir.`,
             projectRoot: z
                 .string()
                 .nullish()
-                .describe('Project root for cartridge discovery. Default: project directory. Set to override the project directory.'),
+                .describe('Optional cartridge discovery/output root, resolved relative to projectDirectory. Defaults to projectDirectory.'),
             outputDir: z.string().optional().describe('Output directory override. Default: project root'),
         },
         async execute(args, { services }) {

package/dist/tools/scapi/scapi-custom-apis-get-status.js

@@ -94,6 +94,7 @@ CLI: b2c scapi custom status`,
         toolsets: ['PWAV3', 'SCAPI', 'STOREFRONTNEXT'],
         isGA: true,
         requiresInstance: false,
+        usesProjectContext: true,
         inputSchema: {
             status: z.enum(['active', 'not_registered']).optional().describe('Filter by status. Omit for all.'),
             groupBy: z.enum(['site', 'type']).optional().describe('Group by siteId or type (Admin/Shopper).'),

package/dist/tools/storefrontnext/figma/figma-to-component/index.d.ts

@@ -12,11 +12,14 @@ import type { Services } from '../../../../services.js';
 export declare const figmaToComponentSchema: z.ZodObject<{
     figmaUrl: z.ZodString;
     workflowFilePath: z.ZodOptional<z.ZodString>;
+    projectDirectory: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
     figmaUrl: string;
+    projectDirectory?: string | undefined;
     workflowFilePath?: string | undefined;
 }, {
     figmaUrl: string;
+    projectDirectory?: string | undefined;
     workflowFilePath?: string | undefined;
 }>;
 export type FigmaToComponentInput = z.infer<typeof figmaToComponentSchema>;

package/dist/tools/storefrontnext/figma/figma-to-component/index.js

@@ -14,6 +14,7 @@
 import { z } from 'zod';
 import { readFileSync, existsSync } from 'node:fs';
 import { createToolAdapter, textResult } from '../../../adapter.js';
+import { projectDirectoryInput } from '../../../project-context.js';
 import { parseFigmaUrl } from './figma-url-parser.js';
 // prettier-ignore
 const DEFAULT_WORKFLOW_CONTENT = `---
@@ -169,7 +170,8 @@ export const figmaToComponentSchema = z
     workflowFilePath: z
         .string()
         .optional()
-        .describe('Optional absolute path to custom workflow .md file. If not provided, uses default built-in workflow.'),
+        .describe('Optional path to a custom workflow .md file, resolved relative to projectDirectory when needed. If omitted, uses the default built-in workflow.'),
+    projectDirectory: projectDirectoryInput,
 })
     .strict();
 function extractWorkflowContent(content) {
@@ -316,9 +318,13 @@ export function createFigmaToComponentTool(loadServices) {
         toolsets: ['STOREFRONTNEXT_DEPRECATED'],
         isGA: false,
         requiresInstance: false,
+        usesProjectContext: true,
         inputSchema: figmaToComponentSchema.shape,
-        async execute(args) {
-            return generateWorkflowResponse(args.figmaUrl, args.workflowFilePath);
+        async execute(args, context) {
+            const workflowFilePath = args.workflowFilePath
+                ? context.services.resolveWithProjectDirectory(args.workflowFilePath, args.projectDirectory)
+                : undefined;
+            return generateWorkflowResponse(args.figmaUrl, workflowFilePath);
         },
         formatOutput: (output) => textResult(output),
     }, loadServices);

package/dist/tools/storefrontnext/figma/generate-component/index.d.ts

@@ -48,6 +48,7 @@ export declare const generateComponentSchema: z.ZodObject<{
         matchType: "name" | "structure" | "visual";
     }>, "many">;
     workspacePath: z.ZodOptional<z.ZodString>;
+    projectDirectory: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
     figmaMetadata: string;
     figmaCode: string;
@@ -59,6 +60,7 @@ export declare const generateComponentSchema: z.ZodObject<{
         similarity: number;
         matchType: "name" | "structure" | "visual";
     }[];
+    projectDirectory?: string | undefined;
     workspacePath?: string | undefined;
 }, {
     figmaMetadata: string;
@@ -71,6 +73,7 @@ export declare const generateComponentSchema: z.ZodObject<{
         similarity: number;
         matchType: "name" | "structure" | "visual";
     }[];
+    projectDirectory?: string | undefined;
     workspacePath?: string | undefined;
 }>;
 export type GenerateComponentInput = z.infer<typeof generateComponentSchema>;

package/dist/tools/storefrontnext/figma/generate-component/index.js

@@ -12,6 +12,7 @@
  */
 import { z } from 'zod';
 import { createToolAdapter, textResult } from '../../../adapter.js';
+import { projectDirectoryInput } from '../../../project-context.js';
 import { analyzeComponentDifferences, determineAction } from './decision.js';
 import { formatRecommendation } from './formatter.js';
 const discoveredComponentSchema = z.object({
@@ -33,6 +34,7 @@ export const generateComponentSchema = z
         .string()
         .optional()
         .describe('Optional workspace root path. Defaults to the MCP server project directory.'),
+    projectDirectory: projectDirectoryInput,
 })
     .strict();
 function analyzeComponent(input) {
@@ -86,11 +88,12 @@ export function createGenerateComponentTool(loadServices) {
         toolsets: ['STOREFRONTNEXT_DEPRECATED'],
         isGA: false,
         requiresInstance: false,
+        usesProjectContext: true,
         inputSchema: generateComponentSchema.shape,
         async execute(args, context) {
             return generateComponentRecommendation({
                 ...args,
-                workspacePath: args.workspacePath ?? context.services.resolveWithProjectDirectory(),
+                workspacePath: context.services.resolveWithProjectDirectory(args.workspacePath, args.projectDirectory),
             });
         },
         formatOutput: (output) => textResult(output),

package/dist/tools/storefrontnext/figma/map-tokens/index.d.ts

@@ -26,6 +26,7 @@ export declare const mapTokensToThemeSchema: z.ZodObject<{
         description?: string | undefined;
     }>, "many">;
     themeFilePath: z.ZodOptional<z.ZodString>;
+    projectDirectory: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
     figmaTokens: {
         type: "color" | "fontFamily" | "fontSize" | "opacity" | "other" | "radius" | "spacing";
@@ -33,6 +34,7 @@ export declare const mapTokensToThemeSchema: z.ZodObject<{
         value: string;
         description?: string | undefined;
     }[];
+    projectDirectory?: string | undefined;
     themeFilePath?: string | undefined;
 }, {
     figmaTokens: {
@@ -41,6 +43,7 @@ export declare const mapTokensToThemeSchema: z.ZodObject<{
         value: string;
         description?: string | undefined;
     }[];
+    projectDirectory?: string | undefined;
     themeFilePath?: string | undefined;
 }>;
 export type MapTokensToThemeInput = z.infer<typeof mapTokensToThemeSchema>;

package/dist/tools/storefrontnext/figma/map-tokens/index.js

@@ -12,6 +12,7 @@
  */
 import { z } from 'zod';
 import { createToolAdapter, textResult } from '../../../adapter.js';
+import { projectDirectoryInput } from '../../../project-context.js';
 import { parseThemeFile } from './css-parser.js';
 import { matchTokens } from './token-matcher.js';
 export const mapTokensToThemeSchema = z
@@ -29,7 +30,8 @@ export const mapTokensToThemeSchema = z
     themeFilePath: z
         .string()
         .optional()
-        .describe('Optional absolute path to theme CSS file. If not provided, will search for app.css in common locations.'),
+        .describe('Optional path to the theme CSS file, resolved relative to projectDirectory when needed. If omitted, searches for app.css in common locations.'),
+    projectDirectory: projectDirectoryInput,
 })
     .strict();
 function formatTokenMatch(match) {
@@ -225,9 +227,14 @@ export function createMapTokensToThemeTool(loadServices) {
         toolsets: ['STOREFRONTNEXT_DEPRECATED'],
         isGA: false,
         requiresInstance: false,
+        usesProjectContext: true,
         inputSchema: mapTokensToThemeSchema.shape,
         async execute(args, context) {
-            return mapFigmaTokensToTheme(args, context.services.resolveWithProjectDirectory());
+            const workspaceRoot = context.services.resolveWithProjectDirectory(undefined, args.projectDirectory);
+            const themeFilePath = args.themeFilePath
+                ? context.services.resolveWithProjectDirectory(args.themeFilePath, args.projectDirectory)
+                : undefined;
+            return mapFigmaTokensToTheme({ ...args, themeFilePath }, workspaceRoot);
         },
         formatOutput: (output) => textResult(output),
     }, loadServices);

package/dist/tools/storefrontnext/page-designer-decorator/index.d.ts

@@ -1,7 +1,10 @@
 import { z } from 'zod';
 import type { McpTool } from '../../../utils/index.js';
 import type { Services } from '../../../services.js';
+import { type ProjectContextInput } from '../../project-context.js';
 export declare const pageDesignerDecoratorSchema: z.ZodObject<{
+    projectDirectory: z.ZodOptional<z.ZodString>;
+    configPath: z.ZodOptional<z.ZodString>;
     component: z.ZodString;
     searchPaths: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     autoMode: z.ZodOptional<z.ZodBoolean>;
@@ -167,6 +170,8 @@ export declare const pageDesignerDecoratorSchema: z.ZodObject<{
     }>>;
 }, "strict", z.ZodTypeAny, {
     component: string;
+    projectDirectory?: string | undefined;
+    configPath?: string | undefined;
     searchPaths?: string[] | undefined;
     autoMode?: boolean | undefined;
     componentId?: string | undefined;
@@ -205,6 +210,8 @@ export declare const pageDesignerDecoratorSchema: z.ZodObject<{
     } | undefined;
 }, {
     component: string;
+    projectDirectory?: string | undefined;
+    configPath?: string | undefined;
     searchPaths?: string[] | undefined;
     autoMode?: boolean | undefined;
     componentId?: string | undefined;
@@ -249,4 +256,4 @@ export type PageDesignerDecoratorInput = z.infer<typeof pageDesignerDecoratorSch
  * @param loadServices - Function that loads configuration and returns Services instance
  * @returns The configured MCP tool
  */
-export declare function createPageDesignerDecoratorTool(loadServices: () => Promise<Services> | Services): McpTool;
+export declare function createPageDesignerDecoratorTool(loadServices: (projectContext?: ProjectContextInput) => Promise<Services> | Services): McpTool;

package/dist/tools/storefrontnext/page-designer-decorator/index.js

@@ -7,6 +7,7 @@ import { z } from 'zod';
 import { componentAnalyzer, generateTypeSuggestions, resolveComponent } from './analyzer.js';
 import { generateDecoratorCode } from './templates/decorator-generator.js';
 import { pageDesignerDecoratorRules } from './rules.js';
+import { projectContextInputSchema } from '../../project-context.js';
 // ============================================================================
 // SCHEMA DEFINITION
 // ============================================================================
@@ -93,6 +94,7 @@ export const pageDesignerDecoratorSchema = z
     })
         .optional()
         .describe('Conversation state for multi-turn interaction'),
+    ...projectContextInputSchema,
 })
     .strict();
 // ============================================================================
@@ -543,8 +545,11 @@ export function createPageDesignerDecoratorTool(loadServices) {
                 const validatedArgs = pageDesignerDecoratorSchema.parse(args);
                 // Use projectDirectory from services to ensure we search in the correct project directory
                 // This prevents searches in the home folder when MCP clients spawn servers from ~
-                const services = await loadServices();
-                const workspaceRoot = services.resolveWithProjectDirectory();
+                const services = await loadServices({
+                    projectDirectory: validatedArgs.projectDirectory,
+                    configPath: validatedArgs.configPath,
+                });
+                const workspaceRoot = services.resolveWithProjectDirectory(undefined, validatedArgs.projectDirectory);
                 if (validatedArgs.autoMode === undefined && !validatedArgs.conversationContext) {
                     const fullPath = resolveComponent(validatedArgs.component, workspaceRoot, validatedArgs.searchPaths);
                     const componentInfo = componentAnalyzer.analyzeComponent(fullPath);

package/dist/tools/storefrontnext/site-theming/index.js

@@ -13,6 +13,7 @@
  */
 import { z } from 'zod';
 import { createToolAdapter, textResult, errorResult } from '../../adapter.js';
+import { projectDirectoryInput } from '../../project-context.js';
 import { siteThemingStore } from './theming-store.js';
 import { mergeGuidance } from './guidance-merger.js';
 import { generateResponse } from './response-builder.js';
@@ -42,7 +43,9 @@ export function createSiteThemingTool(loadServices) {
         toolsets: ['STOREFRONTNEXT_DEPRECATED'],
         isGA: false,
         requiresInstance: false,
+        usesProjectContext: true,
         inputSchema: {
+            projectDirectory: projectDirectoryInput,
             fileKeys: z
                 .array(z.string())
                 .optional()
@@ -63,7 +66,9 @@ export function createSiteThemingTool(loadServices) {
                 .describe('Context from previous conversation rounds'),
         },
         async execute(args, context) {
-            siteThemingStore.initialize(context.services.resolveWithProjectDirectory());
+            siteThemingStore.initialize(context.services.resolveWithProjectDirectory(undefined, args.projectDirectory), {
+                themingFiles: context.services.getEnvironmentVariable('THEMING_FILES'),
+            });
             const defaultFileKeys = ['theming-questions', 'theming-validation', 'theming-accessibility'];
             let fileKeys;
             if (args.fileKeys && args.fileKeys.length > 0) {

package/dist/tools/storefrontnext/site-theming/theming-store.d.ts

@@ -41,6 +41,8 @@ export interface ThemingGuidance {
 export interface InitializeOptions {
     /** Override content directory for default files (used in tests). */
     contentDirOverride?: string;
+    /** Project-scoped THEMING_FILES value. */
+    themingFiles?: string;
 }
 declare class ThemingStore {
     private initializedForRoot;

package/dist/tools/storefrontnext/site-theming/theming-store.js

@@ -365,7 +365,7 @@ class ThemingStore {
                 }
             }
         }
-        const themingFilesEnv = process.env.THEMING_FILES;
+        const themingFilesEnv = options?.themingFiles ?? process.env.THEMING_FILES;
         if (themingFilesEnv) {
             try {
                 this.loadThemingFilesFromEnv(themingFilesEnv, root);

package/dist/tools/storefrontnext/site-theming/types.d.ts

@@ -32,4 +32,5 @@ export interface ConversationContext {
 export interface SiteThemingInput {
     fileKeys?: string[];
     conversationContext?: ConversationContext;
+    projectDirectory?: string;
 }

package/oclif.manifest.json

@@ -429,5 +429,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "1.10.1"
+  "version": "2.0.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@salesforce/b2c-dx-mcp",
   "description": "MCP server for B2C Commerce developer experience tools",
-  "version": "1.10.1",
+  "version": "2.0.0",
   "author": "Salesforce",
   "license": "Apache-2.0",
   "repository": "SalesforceCommerceCloud/b2c-developer-tooling",
@@ -80,7 +80,7 @@
     "yaml": "2.9.0",
     "postcss": "8.5.15",
     "zod": "3.25.76",
-    "@salesforce/b2c-tooling-sdk": "1.23.0"
+    "@salesforce/b2c-tooling-sdk": "1.24.0"
   },
   "devDependencies": {
     "@eslint/compat": "^1",