@salesforce/b2c-dx-mcp 1.10.1 → 2.1.0

package/dist/tools/adapter.js

@@ -70,6 +70,7 @@
  * ```
  */
 import { z } from 'zod';
+import { createProjectContextInputSchema, } from './project-context.js';
 /**
  * Creates a text-only success result.
  *
@@ -120,6 +121,25 @@ export function jsonResult(data, indent = 2) {
         content: [{ type: 'text', text: JSON.stringify(data, null, indent) }],
     };
 }
+/** Attach compact resolution provenance while preserving existing tool output. */
+export function attachResolution(result, resolution) {
+    let content = result.content;
+    let structuredContent = { ...result.structuredContent, resolution };
+    if (content.length === 1 && content[0]?.type === 'text') {
+        try {
+            const parsed = JSON.parse(content[0].text);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                const output = { ...parsed, resolution };
+                content = [{ ...content[0], text: JSON.stringify(output, null, 2) }];
+                structuredContent = { ...output, ...result.structuredContent, resolution };
+            }
+        }
+        catch {
+            // Plain-text tools expose resolution through structuredContent only.
+        }
+    }
+    return { ...result, content, structuredContent };
+}
 /**
  * Formats Zod validation errors into a human-readable string.
  *
@@ -169,13 +189,24 @@ 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, usesConfigurationContext = false, execute, formatOutput, } = options;
+    const projectContextKind = requiresInstance || requiresMrtAuth || usesConfigurationContext
+        ? 'configuration'
+        : usesProjectContext
+            ? 'project'
+            : undefined;
+    const effectiveInputSchema = projectContextKind
+        ? {
+            ...createProjectContextInputSchema(projectContextKind, loadServices.projectContextDefaults),
+            ...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) {
@@ -185,14 +216,21 @@ export function createToolAdapter(options, loadServices, serverContext) {
                 return errorResult(`Invalid input: ${formatZodErrors(parseResult.error)}`);
             }
             const args = parseResult.data;
+            let resolution;
             try {
                 // 2. Load Services to get fresh configuration (re-reads config files)
-                const services = await loadServices();
+                const projectContext = projectContextKind ? args : undefined;
+                const services = await loadServices(projectContext);
+                const executionResolution = services.getResolution();
+                if (projectContextKind === 'project') {
+                    delete executionResolution.configuration;
+                }
+                resolution = projectContextKind ? executionResolution : undefined;
                 // 3. Get B2CInstance if required (loaded on each call)
                 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');
+                        return attachResolution(errorResult('B2C instance error: Instance configuration required. Provide --server flag, set SFCC_SERVER environment variable, or configure dw.json'), executionResolution);
                     }
                     b2cInstance = services.b2cInstance;
                 }
@@ -200,7 +238,7 @@ export function createToolAdapter(options, loadServices, serverContext) {
                 let mrtConfig;
                 if (requiresMrtAuth) {
                     if (!services.mrtConfig.auth) {
-                        return errorResult('MRT auth error: MRT API key required. Provide --api-key, set MRT_API_KEY environment variable, or configure ~/.mobify');
+                        return attachResolution(errorResult('MRT auth error: MRT API key required. Provide --api-key, set MRT_API_KEY environment variable, or configure ~/.mobify'), executionResolution);
                     }
                     mrtConfig = {
                         auth: services.mrtConfig.auth,
@@ -215,15 +253,22 @@ export function createToolAdapter(options, loadServices, serverContext) {
                     mrtConfig,
                     services,
                     serverContext,
+                    resolution: executionResolution,
+                    setResolvedDirectory(name, value) {
+                        executionResolution.directories ??= {};
+                        executionResolution.directories[name] = value;
+                    },
                 };
                 const output = await execute(args, context);
                 // 6. Format output
-                return formatOutput(output);
+                const result = formatOutput(output);
+                return resolution ? attachResolution(result, executionResolution) : result;
             }
             catch (error) {
                 // Handle execution errors
                 const message = error instanceof Error ? error.message : String(error);
-                return errorResult(`Execution error: ${message}`);
+                const result = errorResult(`Execution error: ${message}`);
+                return resolution ? attachResolution(result, resolution) : result;
             }
         },
     };

package/dist/tools/cartridges/index.js

@@ -44,12 +44,16 @@ function createCartridgeDeployTool(loadServices, injections) {
         toolsets: ['CARTRIDGES'],
         isGA: true,
         requiresInstance: true,
+        usesProjectContext: true,
         inputSchema: {
+            cartridgeDirectory: z
+                .string()
+                .optional()
+                .describe('Optional cartridge discovery root. Relative paths resolve from projectDirectory. Defaults to projectDirectory.'),
             directory: z
                 .string()
                 .optional()
-                .describe('Path to directory to search for cartridges. Defaults to current project directory if not specified. ' +
-                'The tool will recursively search this directory for .project files to identify cartridges.'),
+                .describe('Deprecated alias for cartridgeDirectory. cartridgeDirectory takes precedence when both are supplied.'),
             cartridges: z
                 .array(z.string())
                 .optional()
@@ -87,7 +91,13 @@ 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 directoryArgument = args.cartridgeDirectory ?? args.directory;
+                const directory = context.services.resolveWithProjectDirectory(directoryArgument, args.projectDirectory);
+                context.setResolvedDirectory('cartridgeDirectory', {
+                    path: directory,
+                    source: directoryArgument ? 'argument' : 'projectDirectory',
+                });
                 // Parse options
                 const options = {
                     include: args.cartridges,
@@ -106,6 +116,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, configPath, and/or instanceName to inspect the same project, configuration catalog, and named instance another tool would use. The detailed source graph is supplemented by the same compact resolution provenance returned by other configuration-aware tools. ' +
             '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,
+        usesConfigurationContext: 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')
@@ -31,6 +30,7 @@ export function createDebugListSessionsTool(loadServices, serverContext) {
                         session_cookie: dwsid ? { name: 'dwsid', value: dwsid } : null,
                         created_at: new Date(entry.createdAt).toISOString(),
                         last_activity_at: new Date(entry.lastActivityAt).toISOString(),
+                        resolution: entry.resolution,
                     };
                 }),
             };

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.'),
         },
+        usesConfigurationContext: true,
         async execute(args, context) {
             const registry = getRegistry(context);
             const credentials = context.services.getBasicAuthCredentials();
@@ -33,8 +32,13 @@ 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);
+            context.setResolvedDirectory('cartridgeDirectory', {
+                path: cartridgeDir,
+                source: args.cartridgeDirectory ? 'argument' : 'projectDirectory',
+            });
             const cartridges = findCartridges(cartridgeDir);
             const warnings = [];
             if (cartridges.length === 0) {
@@ -55,7 +59,14 @@ export function createDebugStartSessionTool(loadServices, serverContext) {
             };
             const manager = new DebugSessionManager({ hostname, username, password, clientId, cartridgeRoots: cartridges }, callbacks);
             await manager.connect();
-            const entry = registry.registerSession({ hostname, clientId, manager, sourceMapper, cartridges });
+            const entry = registry.registerSession({
+                hostname,
+                clientId,
+                manager,
+                sourceMapper,
+                cartridges,
+                resolution: structuredClone(context.resolution),
+            });
             const cartridgeMappings = {};
             for (const c of cartridges)
                 cartridgeMappings[c.name] = c.src;
@@ -70,6 +81,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/log-watch-registry.d.ts

@@ -1,5 +1,6 @@
 import type { LogEntry, LogFile, TailLogsResult } from '@salesforce/b2c-tooling-sdk/operations/logs';
 import type { ToolExecutionContext } from '../adapter.js';
+import type { ToolResolution } from '../project-context.js';
 /** Maximum number of buffered entries before oldest are evicted. */
 export declare const DEFAULT_BUFFER_CAP = 5000;
 /**
@@ -38,6 +39,7 @@ export interface LogWatchEntry {
     createdAt: number;
     lastActivityAt: number;
     stopped: boolean;
+    resolution?: ToolResolution;
 }
 export interface RegisterWatchOptions {
     hostname: string;
@@ -45,6 +47,7 @@ export interface RegisterWatchOptions {
     tailResult: TailLogsResult;
     bufferCap?: number;
     bufferBytesCap?: number;
+    resolution?: ToolResolution;
 }
 export declare class LogWatchRegistry {
     private cleanupTimer;

package/dist/tools/diagnostics/log-watch-registry.js

@@ -194,6 +194,7 @@ export class LogWatchRegistry {
             stopped: false,
             totalEntriesSeen: 0,
             watchId,
+            resolution: opts.resolution,
         };
         this.watches.set(watchId, entry);
         return entry;

package/dist/tools/diagnostics/logs-watch-list.js

@@ -27,6 +27,7 @@ export function createLogsWatchListTool(loadServices, serverContext) {
                     stopped: w.stopped,
                     total_entries_seen: w.totalEntriesSeen,
                     watch_id: w.watchId,
+                    resolution: w.resolution,
                 })),
             };
         },

package/dist/tools/diagnostics/logs-watch-start.js

@@ -97,7 +97,12 @@ export function createLogsWatchStartTool(loadServices, serverContext, injections
             // it isn't orphaned (it would otherwise poll WebDAV until process exit).
             let entry;
             try {
-                entry = registry.registerWatch({ hostname, prefixes, tailResult });
+                entry = registry.registerWatch({
+                    hostname,
+                    prefixes,
+                    tailResult,
+                    resolution: structuredClone(context.resolution),
+                });
             }
             catch (error) {
                 await tailResult.stop().catch(() => { });

package/dist/tools/diagnostics/mrt-log-watch-registry.d.ts

@@ -1,5 +1,6 @@
 import type { MrtLogEntry, TailMrtLogsResult } from '@salesforce/b2c-tooling-sdk/operations/mrt';
 import type { ToolExecutionContext } from '../adapter.js';
+import type { ToolResolution } from '../project-context.js';
 /** Maximum number of buffered entries before oldest are evicted. */
 export declare const DEFAULT_BUFFER_CAP = 5000;
 /**
@@ -42,6 +43,7 @@ export interface MrtLogWatchEntry {
      * watch keeps its buffered entries until drained or idle-reaped.
      */
     stopped: boolean;
+    resolution?: ToolResolution;
 }
 export interface RegisterMrtWatchOptions {
     project: string;
@@ -50,6 +52,7 @@ export interface RegisterMrtWatchOptions {
     tailResult: TailMrtLogsResult;
     bufferCap?: number;
     bufferBytesCap?: number;
+    resolution?: ToolResolution;
 }
 /**
  * Stable dedup key for an MRT log watch. A developer may tail several

package/dist/tools/diagnostics/mrt-logs-watch-list.js

@@ -27,6 +27,7 @@ export function createMrtLogsWatchListTool(loadServices, serverContext) {
                     stopped: w.stopped,
                     total_entries_seen: w.totalEntriesSeen,
                     watch_id: w.watchId,
+                    resolution: w.resolution,
                 })),
             };
         },

package/dist/tools/diagnostics/mrt-logs-watch-start.js

@@ -113,7 +113,13 @@ export function createMrtLogsWatchStartTool(loadServices, serverContext, injecti
             // exit).
             let entry;
             try {
-                entry = registry.registerWatch({ project, environment, origin, tailResult });
+                entry = registry.registerWatch({
+                    project,
+                    environment,
+                    origin,
+                    tailResult,
+                    resolution: structuredClone(context.resolution),
+                });
             }
             catch (error) {
                 tailResult.stop();

package/dist/tools/diagnostics/session-registry.d.ts

@@ -1,6 +1,7 @@
 import type { DebugSessionManager, SourceMapper, SdapiBreakpoint, SdapiScriptThread } from '@salesforce/b2c-tooling-sdk/operations/debug';
 import type { CartridgeMapping } from '@salesforce/b2c-tooling-sdk/operations/code';
 import type { ToolExecutionContext } from '../adapter.js';
+import type { ToolResolution } from '../project-context.js';
 export interface HaltWaiter {
     resolve: (thread: SdapiScriptThread) => void;
     reject: (error: Error) => void;
@@ -17,6 +18,7 @@ export interface DebugSessionEntry {
     haltWaiters: HaltWaiter[];
     createdAt: number;
     lastActivityAt: number;
+    resolution?: ToolResolution;
 }
 export interface RegisterSessionOptions {
     hostname: string;
@@ -24,6 +26,7 @@ export interface RegisterSessionOptions {
     manager: DebugSessionManager;
     sourceMapper: SourceMapper;
     cartridges: CartridgeMapping[];
+    resolution?: ToolResolution;
 }
 export declare class DebugSessionRegistry {
     private cleanupTimer;

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

@@ -64,12 +64,12 @@ export class DebugSessionRegistry {
         return [...this.sessions.values()];
     }
     registerSession(opts) {
-        const { hostname, clientId, manager, sourceMapper, cartridges } = opts;
+        const { hostname, clientId, manager, sourceMapper, cartridges, resolution } = 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();
@@ -84,6 +84,7 @@ export class DebugSessionRegistry {
             haltWaiters: [],
             createdAt: now,
             lastActivityAt: now,
+            resolution,
         };
         this.sessions.set(sessionId, entry);
         return entry;

package/dist/tools/index.d.ts

@@ -14,4 +14,3 @@ export * from './docs/index.js';
 export * from './mrt/index.js';
 export * from './pwav3/index.js';
 export * from './scapi/index.js';
-export * from './storefrontnext/index.js';

package/dist/tools/index.js

@@ -21,5 +21,4 @@ export * from './docs/index.js';
 export * from './mrt/index.js';
 export * from './pwav3/index.js';
 export * from './scapi/index.js';
-export * from './storefrontnext/index.js';
 //# sourceMappingURL=index.js.map

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,17 @@ 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);
+            context.setResolvedDirectory('buildDirectory', {
+                path: buildDirectory,
+                source: args.buildDirectory ? 'argument' : 'projectDirectory',
+            });
             // Log all computed variables before pushing bundle
             const logger = getLogger();
             logger.debug({
@@ -196,7 +202,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,53 @@
+import { z, type ZodRawShape } 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 primary dw.json-format configuration path. */
+    configPath?: string;
+    /** Per-call named instance selection. */
+    instanceName?: string;
+}
+/** Effective project directory and the source that selected it. */
+export interface ProjectDirectoryInfo {
+    path: string;
+    source: 'argument' | 'config' | 'cwd';
+}
+/** How the selected dw.json file entered the configuration resolver. */
+export type ConfigurationResolutionSource = 'argument' | 'globalDefault' | 'none' | 'projectDirectory' | 'projectEnvironment' | 'server';
+/** Compact selected-configuration provenance returned by project-aware tools. */
+export interface ConfigurationResolutionInfo {
+    hostname?: string;
+    instanceName?: string;
+    path?: string;
+    source: ConfigurationResolutionSource;
+}
+/** Provenance for a specialized project-relative directory. */
+export interface DirectoryResolutionInfo {
+    path: string;
+    source: 'argument' | 'projectDirectory';
+}
+/** Compact, common provenance block returned by project/config-aware tools. */
+export interface ToolResolution {
+    configuration?: ConfigurationResolutionInfo;
+    directories?: Record<string, DirectoryResolutionInfo>;
+    projectDirectory: ProjectDirectoryInfo;
+}
+/** Defaults known when MCP tool schemas are registered. */
+export interface ProjectContextDefaults {
+    projectDirectory: ProjectDirectoryInfo;
+}
+/** Whether a tool needs only a project root or full configuration selection. */
+export type ProjectContextKind = 'configuration' | 'project';
+/** Build the canonical project-directory field with the effective fallback embedded in its description. */
+export declare function createProjectDirectoryInput(defaults?: ProjectContextDefaults): z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+/** Build the canonical explicit primary dw.json field. */
+export declare function createConfigPathInput(): z.ZodOptional<z.ZodString>;
+/** Build the canonical named-instance selection field. */
+export declare function createInstanceNameInput(): z.ZodOptional<z.ZodString>;
+/** Build flat canonical schema fields for a local-project or configuration-aware tool. */
+export declare function createProjectContextInputSchema(kind: ProjectContextKind, defaults?: ProjectContextDefaults): ZodRawShape;
+/** Static field for schemas declared outside the shared adapter. */
+export declare const projectDirectoryInput: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+/** Static configuration schema for legacy/manual tool definitions. */
+export declare const projectContextInputSchema: z.ZodRawShape;

package/dist/tools/project-context.js

@@ -0,0 +1,55 @@
+/*
+ * 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 path from 'node:path';
+import { z } from 'zod';
+function defaultProjectContext() {
+    return { projectDirectory: { path: process.cwd(), source: 'cwd' } };
+}
+/** Build the canonical project-directory field with the effective fallback embedded in its description. */
+export function createProjectDirectoryInput(defaults = defaultProjectContext()) {
+    const fallback = defaults.projectDirectory;
+    const sourceDescription = fallback.source === 'cwd'
+        ? 'the MCP process working directory'
+        : 'the server-level --project-directory / SFCC_PROJECT_DIRECTORY value';
+    return z
+        .string()
+        .refine((value) => path.isAbsolute(value), 'projectDirectory must be an absolute path')
+        .optional()
+        .describe(`Optional absolute project root for this call. Overrides the server-level project directory. ` +
+        `When omitted, uses ${sourceDescription}: ${fallback.path}`);
+}
+/** Build the canonical explicit primary dw.json field. */
+export function createConfigPathInput() {
+    return z
+        .string()
+        .optional()
+        .describe('Optional path to a dw.json-format configuration file. Relative paths resolve from projectDirectory. ' +
+        'Selects the primary file ahead of server and project automatic selection; the shared default dw.json remains available as a fallback and for named-instance lookup.');
+}
+/** Build the canonical named-instance selection field. */
+export function createInstanceNameInput() {
+    return z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Optional named instance to select from the resolved primary and default dw.json files. The primary file is searched first. When omitted, the active/default instance is used.');
+}
+/** Build flat canonical schema fields for a local-project or configuration-aware tool. */
+export function createProjectContextInputSchema(kind, defaults = defaultProjectContext()) {
+    const project = { projectDirectory: createProjectDirectoryInput(defaults) };
+    if (kind === 'project')
+        return project;
+    return {
+        ...project,
+        configPath: createConfigPathInput(),
+        instanceName: createInstanceNameInput(),
+    };
+}
+/** Static field for schemas declared outside the shared adapter. */
+export const projectDirectoryInput = createProjectDirectoryInput();
+/** Static configuration schema for legacy/manual tool definitions. */
+export const projectContextInputSchema = createProjectContextInputSchema('configuration');
+//# 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
+        usesConfigurationContext: 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. */
@@ -22,8 +23,12 @@ interface ScaffoldCustomApiInput {
     /** Short description of the API. Default: "A custom B2C Commerce API" */
     apiDescription?: string;
     /** Project root for cartridge discovery and output. Default: MCP project directory */
+    cartridgeDirectory?: string;
+    /** @deprecated Use cartridgeDirectory. */
     projectRoot?: string;
     /** Output directory override. Default: scaffold default or project root */
+    outputDirectory?: string;
+    /** @deprecated Use outputDirectory. */
     outputDir?: string;
 }
 /**
@@ -40,6 +45,8 @@ interface ScaffoldCustomApiOutput {
     }>;
     postInstructions?: string;
     error?: string;
+    projectDirectory: ProjectDirectoryInfo;
+    projectRoot: string;
 }
 /**
  * Core execute logic for the custom API scaffold tool.