@salesforce/b2c-dx-mcp 2.0.0 → 2.1.0

package/README.md

@@ -61,30 +61,27 @@ See the [Installation Guide](https://salesforcecommercecloud.github.io/b2c-devel
 
 **Project-level configuration** (recommended for Cursor and GitHub Copilot) automatically detects your project location. For **user-level configuration** or when using explicit paths, set `--project-directory` (or `SFCC_PROJECT_DIRECTORY`). MCP clients spawn from the home directory (`~`), not your project.
 
-| Environment Variable | Description |
-|---------------------|-------------|
+| Environment Variable     | Description                                                   |
+| ------------------------ | ------------------------------------------------------------- |
 | `SFCC_PROJECT_DIRECTORY` | Project directory (enables auto-discovery and config loading) |
-| `SFCC_SERVER` | B2C instance hostname |
-| `SFCC_USERNAME` | Username for WebDAV |
-| `SFCC_PASSWORD` | Password/access key for WebDAV |
-| `SFCC_CLIENT_ID` | OAuth client ID |
-| `SFCC_CLIENT_SECRET` | OAuth client secret |
-| `MRT_API_KEY` | MRT API key (`SFCC_MRT_API_KEY` also supported) |
+| `SFCC_SERVER`            | B2C instance hostname                                         |
+| `SFCC_USERNAME`          | Username for WebDAV                                           |
+| `SFCC_PASSWORD`          | Password/access key for WebDAV                                |
+| `SFCC_CLIENT_ID`         | OAuth client ID                                               |
+| `SFCC_CLIENT_SECRET`     | OAuth client secret                                           |
+| `MRT_API_KEY`            | MRT API key (`SFCC_MRT_API_KEY` also supported)               |
 
 See the [Configuration Guide](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/configuration) for credentials, flags, and toolset selection.
 
 ## Tools
 
-| Toolset | Tools | Docs |
-|---------|-------|------|
-| CARTRIDGES | `cartridge_deploy` | [toolsets#cartridges](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/toolsets#cartridges) |
-| MRT | `mrt_bundle_push` | [toolsets#mrt](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/toolsets#mrt) |
-| SCAPI | `scapi_schemas_list`, `scapi_custom_apis_get_status`, `scapi_custom_api_generate_scaffold` | [toolsets#scapi](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/toolsets#scapi) |
-| STOREFRONTNEXT | `mrt_bundle_push` + SCAPI tools (auto-enabled for Storefront Next projects) | [toolsets#storefrontnext](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/toolsets#storefrontnext) |
-| STOREFRONTNEXT_DEPRECATED ⛔ | `sfnext_get_guidelines`, `sfnext_add_page_designer_decorator`, `sfnext_configure_theme`, `sfnext_start_figma_workflow`, `sfnext_analyze_component`, `sfnext_match_tokens_to_theme` — **deprecated, see note below** | [toolsets#storefrontnext-deprecated](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/toolsets#storefrontnext-deprecated) |
-| PWAV3 | `pwakit_get_guidelines` + SCAPI tools | [toolsets#pwav3](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/toolsets#pwav3) |
-
-> **⛔ `sfnext_*` tools are deprecated.** The Storefront Next MCP tools are **not compatible with the Storefront Next 1.0 GA release** and have been superseded by the [`storefront-next` and `storefront-next-figma` agent-skills plugins](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/agent-skills), which stay current with the GA release. They have moved to the `STOREFRONTNEXT_DEPRECATED` toolset, which is **never auto-enabled** and **excluded from `--toolsets all`**; to use them you must request the toolset explicitly (`--toolsets STOREFRONTNEXT_DEPRECATED --allow-non-ga-tools`). They will be removed in a future release.
+| Toolset        | Tools                                                                                      | Docs                                                                                                                   |
+| -------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
+| CARTRIDGES     | `cartridge_deploy`                                                                         | [toolsets#cartridges](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/toolsets#cartridges)         |
+| MRT            | `mrt_bundle_push`                                                                          | [toolsets#mrt](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/toolsets#mrt)                       |
+| SCAPI          | `scapi_schemas_list`, `scapi_custom_apis_get_status`, `scapi_custom_api_generate_scaffold` | [toolsets#scapi](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/toolsets#scapi)                   |
+| STOREFRONTNEXT | `mrt_bundle_push` + SCAPI tools (auto-enabled for Storefront Next projects)                | [toolsets#storefrontnext](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/toolsets#storefrontnext) |
+| PWAV3          | `pwakit_get_guidelines` + SCAPI tools                                                      | [toolsets#pwav3](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/toolsets#pwav3)                   |
 
 ### cartridge_deploy
 
@@ -121,49 +118,6 @@ Generate new custom SCAPI endpoint in a cartridge. [Details](https://salesforcec
 - "Use the MCP tool to scaffold a new custom API named my-products."
 - "Use the MCP tool to create a custom admin API called customer-trips."
 
-## Deprecated: Storefront Next (`sfnext_*`) tools
-
-> **⛔ Deprecated and not compatible with the Storefront Next 1.0 GA release.** The tools below have been superseded by the [`storefront-next` and `storefront-next-figma` agent-skills plugins](https://salesforcecommercecloud.github.io/b2c-developer-tooling/guide/agent-skills) and will be removed in a future release. They no longer auto-enable for Storefront Next projects and are excluded from `--toolsets all`; to use them, request `--toolsets STOREFRONTNEXT_DEPRECATED --allow-non-ga-tools`. Migrate to the skills plugins.
-
-### sfnext_get_guidelines
-
-Get Storefront Next guidelines and best practices. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/sfnext-get-guidelines)
-
-- "Use the MCP tool to show me critical Storefront Next rules."
-- "Use the MCP tool to get data-fetching and component patterns."
-
-### sfnext_add_page_designer_decorator
-
-Add Page Designer decorators to components. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/sfnext-add-page-designer-decorator)
-
-- "Use the MCP tool to add Page Designer decorators to my component."
-
-### sfnext_configure_theme
-
-Get theming guidelines, questions, and WCAG color validation for Storefront Next. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/sfnext-configure-theme)
-
-- "Use the MCP tool to help me apply my brand colors to my Storefront Next site."
-- "Use the MCP tool to validate my color combinations for accessibility."
-
-### sfnext_start_figma_workflow
-
-Workflow orchestrator for Figma-to-component conversion. Parses Figma URL, returns step-by-step instructions for subsequent tool calls. Requires external Figma MCP server. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/sfnext-start-figma-workflow) — [Figma Setup](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/figma-tools-setup)
-
-- "Use the MCP tool to convert this Figma design to a Storefront Next component: [Figma URL with node-id]"
-- "Use the MCP tool to create this homepage from the Figma design: [Figma URL with node-id]"
-
-### sfnext_analyze_component
-
-Analyze design and discovered components to recommend REUSE, EXTEND, or CREATE strategy. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/sfnext-analyze-component)
-
-- "Use the MCP tool to analyze the Figma design and recommend whether to reuse, extend, or create a component."
-
-### sfnext_match_tokens_to_theme
-
-Map design tokens to existing theme tokens in app.css with confidence scores and suggestions. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/sfnext-match-tokens-to-theme)
-
-- "Use the MCP tool to map these Figma design tokens to my theme."
-
 ### pwakit_get_guidelines
 
 Get PWA Kit v3 guidelines. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/pwakit-get-guidelines)
@@ -187,4 +141,3 @@ For MCP development, testing, and local setup, see [CONTRIBUTING.md](./CONTRIBUT
 ## License
 
 This project is licensed under the Apache License 2.0. See [LICENSE.txt](../../LICENSE.txt) for full details.
-

package/dist/commands/mcp.d.ts

@@ -87,6 +87,7 @@ export default class McpServerCommand extends BaseCommand<typeof McpServerComman
      * 2. Startup --config / SFCC_CONFIG
      * 3. SFCC_CONFIG from the selected project's .env
      * 4. dw.json in the selected project directory
+     * 5. Shared default dw.json from the tooling settings
      *
      * Values are then merged through the normal CLI resolver, including
      * environment, plugin, dw.json, ~/.mobify, and package.json sources.

package/dist/commands/mcp.js

@@ -247,14 +247,15 @@ export default class McpServerCommand extends BaseCommand {
      * 2. Startup --config / SFCC_CONFIG
      * 3. SFCC_CONFIG from the selected project's .env
      * 4. dw.json in the selected project directory
+     * 5. Shared default dw.json from the tooling settings
      *
      * Values are then merged through the normal CLI resolver, including
      * environment, plugin, dw.json, ~/.mobify, and package.json sources.
      */
     async loadConfiguration(projectContext) {
         const mrt = extractMrtFlags(this.flags);
-        const baseOptions = this.getBaseConfigOptions();
-        const effectiveProjectDirectory = projectContext?.projectDirectory ?? baseOptions.projectDirectory;
+        const baseOptions = this.flags ? this.getBaseConfigOptions() : {};
+        const effectiveProjectDirectory = path.resolve(projectContext?.projectDirectory ?? baseOptions.projectDirectory ?? process.cwd());
         const projectEnvironment = this.loadProjectEnvironment(effectiveProjectDirectory);
         const projectConfigPath = projectEnvironment?.SFCC_CONFIG;
         const configPath = (projectContext?.configPath
@@ -270,10 +271,9 @@ export default class McpServerCommand extends BaseCommand {
             ...baseOptions,
             ...mrt.options,
             configPath,
-            ...(projectContext?.projectDirectory && {
-                projectDirectory: projectContext.projectDirectory,
-                workingDirectory: projectContext.projectDirectory,
-            }),
+            instance: projectContext?.instanceName ?? baseOptions.instance,
+            projectDirectory: effectiveProjectDirectory,
+            workingDirectory: effectiveProjectDirectory,
         };
         // Combine B2C instance flags and MRT config flags
         const flagConfig = {
@@ -295,9 +295,39 @@ export default class McpServerCommand extends BaseCommand {
      */
     async loadServices(projectContext) {
         const config = await this.loadConfiguration(projectContext);
-        const effectiveProjectDirectory = projectContext?.projectDirectory ?? this.flags?.['project-directory'];
+        const baseOptions = this.flags ? this.getBaseConfigOptions() : {};
+        const configuredProjectDirectory = baseOptions.projectDirectory;
+        const effectiveProjectDirectory = path.resolve(projectContext?.projectDirectory ?? configuredProjectDirectory ?? process.cwd());
         const projectEnvironment = this.loadProjectEnvironment(effectiveProjectDirectory);
-        return Services.fromResolvedConfig(config, projectEnvironment);
+        const projectConfigPath = projectEnvironment?.SFCC_CONFIG;
+        let primaryConfiguration;
+        if (projectContext?.configPath) {
+            primaryConfiguration = {
+                path: path.resolve(effectiveProjectDirectory, projectContext.configPath),
+                source: 'argument',
+            };
+        }
+        else if (baseOptions.configPath) {
+            primaryConfiguration = { path: path.resolve(baseOptions.configPath), source: 'server' };
+        }
+        else if (projectConfigPath) {
+            primaryConfiguration = {
+                path: path.isAbsolute(projectConfigPath)
+                    ? projectConfigPath
+                    : path.resolve(effectiveProjectDirectory, projectConfigPath),
+                source: 'projectEnvironment',
+            };
+        }
+        else {
+            primaryConfiguration = { path: path.join(effectiveProjectDirectory, 'dw.json'), source: 'projectDirectory' };
+        }
+        return Services.fromResolvedConfig(config, projectEnvironment, {
+            projectDirectory: {
+                path: effectiveProjectDirectory,
+                source: projectContext?.projectDirectory ? 'argument' : configuredProjectDirectory ? 'config' : 'cwd',
+            },
+            primaryConfiguration,
+        });
     }
     /**
      * Main entry point - starts the MCP server.
@@ -360,7 +390,15 @@ export default class McpServerCommand extends BaseCommand {
         this.serverContext = new ServerContext();
         // Register toolsets with loader function that loads config and creates Services on each tool call
         // This allows tools to pick up changes to config files (dw.json, ~/.mobify) between invocations
-        await registerToolsets(startupFlags, server, this.loadServices.bind(this), this.serverContext);
+        const loadServices = this.loadServices.bind(this);
+        const configuredProjectDirectory = this.flags['project-directory'];
+        loadServices.projectContextDefaults = {
+            projectDirectory: {
+                path: path.resolve(configuredProjectDirectory ?? process.cwd()),
+                source: configuredProjectDirectory ? 'config' : 'cwd',
+            },
+        };
+        await registerToolsets(startupFlags, server, loadServices, this.serverContext);
         // Connect to stdio transport
         const transport = new StdioServerTransport();
         await server.connect(transport);

package/dist/registry.d.ts

@@ -2,9 +2,8 @@ import { type ProjectType } from '@salesforce/b2c-tooling-sdk/discovery';
 import { type DocCategory } from '@salesforce/b2c-tooling-sdk/docs';
 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';
+import type { ServicesLoader } from './tools/adapter.js';
 /**
  * Registry of tools organized by toolset.
  * Tools can belong to multiple toolsets via their `toolsets` array.
@@ -18,5 +17,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: (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>;
+export declare function createToolRegistry(loadServices: ServicesLoader, serverContext?: ServerContext, detectedWorkspaces?: readonly ProjectType[], enabledDocCategories?: readonly DocCategory[]): ToolRegistry;
+export declare function registerToolsets(flags: StartupFlags, server: B2CDxMcpServer, loadServices: ServicesLoader, serverContext?: ServerContext): Promise<void>;

package/dist/registry.js

@@ -5,17 +5,17 @@
  */
 import os from 'node:os';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { getLogger } from '@salesforce/b2c-tooling-sdk/logging';
 import { detectWorkspaceType } from '@salesforce/b2c-tooling-sdk/discovery';
 import { DOC_CATEGORIES, resolveEnabledCategories } from '@salesforce/b2c-tooling-sdk/docs';
-import { ALL_TOOLSETS, DEPRECATED_TOOLSETS, TOOLSETS, VALID_TOOLSET_NAMES } from './utils/index.js';
+import { ALL_TOOLSETS, TOOLSETS, VALID_TOOLSET_NAMES } from './utils/index.js';
 import { createCartridgesTools } from './tools/cartridges/index.js';
 import { createDiagnosticsTools } from './tools/diagnostics/index.js';
 import { createDocsTools } from './tools/docs/index.js';
 import { createMrtTools } from './tools/mrt/index.js';
 import { createPwav3Tools } from './tools/pwav3/index.js';
 import { createScapiTools } from './tools/scapi/index.js';
-import { createStorefrontNextTools } from './tools/storefrontnext/index.js';
 /**
  * Base toolsets that are always enabled regardless of detected project type.
  * - SCAPI: SCAPI discovery and custom API scaffolding tools.
@@ -33,9 +33,6 @@ const PROJECT_TYPE_TOOLSETS = {
     // (A SFRA workspace also matches the `cartridges` marker; the union dedupes.)
     sfra: ['CARTRIDGES'],
     'pwa-kit-v3': ['PWAV3', 'MRT'],
-    // Note: STOREFRONTNEXT_DEPRECATED is intentionally NOT auto-activated. The
-    // legacy sfnext_* tools are superseded by the storefront-next agent-skills
-    // plugins and must be explicitly requested via --toolsets.
     'storefront-next': ['STOREFRONTNEXT', 'MRT', 'CARTRIDGES'],
 };
 /**
@@ -84,7 +81,6 @@ export function createToolRegistry(loadServices, serverContext, detectedWorkspac
         PWAV3: [],
         SCAPI: [],
         STOREFRONTNEXT: [],
-        STOREFRONTNEXT_DEPRECATED: [],
     };
     // Collect all tools from all factories
     const allTools = [
@@ -94,7 +90,6 @@ export function createToolRegistry(loadServices, serverContext, detectedWorkspac
         ...createMrtTools(loadServices),
         ...createPwav3Tools(loadServices),
         ...createScapiTools(loadServices),
-        ...createStorefrontNextTools(loadServices),
     ];
     // Organize tools by their declared toolsets (supports multi-toolset)
     for (const tool of allTools) {
@@ -117,6 +112,7 @@ export function createToolRegistry(loadServices, serverContext, detectedWorkspac
  * without descending into unrelated deep trees.
  */
 const DISCOVERY_MAX_DEPTH = 5;
+const MCP_PACKAGE_DIRECTORY = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 /**
  * Returns true when `dir` is a location that should never be recursively
  * scanned for a workspace: the user's home directory or a filesystem root.
@@ -130,7 +126,7 @@ function isUnscannableRoot(dir) {
         return true;
     }
     const home = os.homedir();
-    return Boolean(home) && path.resolve(home) === resolved;
+    return (Boolean(home) && path.resolve(home) === resolved) || resolved === MCP_PACKAGE_DIRECTORY;
 }
 /**
  * Performs workspace auto-discovery and returns appropriate toolsets.
@@ -157,7 +153,7 @@ async function detectProjectTypes(flags) {
     // Never recursively scan a home directory or filesystem root — the scan would
     // be expensive and would not identify a meaningful workspace anyway.
     if (isUnscannableRoot(projectDirectory)) {
-        logger.warn({ projectDirectory }, 'Project directory is a home or root directory; skipping workspace auto-discovery. ' +
+        logger.warn({ projectDirectory }, 'Project directory is a home, filesystem root, or MCP installation directory; skipping workspace auto-discovery. ' +
             'Set --project-directory or SFCC_PROJECT_DIRECTORY to the project path to enable it.');
         return [];
     }
@@ -224,12 +220,9 @@ export async function registerToolsets(flags, server, loadServices, serverContex
     if (invalidToolsets.length > 0) {
         logger.warn({ invalidToolsets, validToolsets: VALID_TOOLSET_NAMES }, `Ignoring invalid toolset(s): "${invalidToolsets.join('", "')}"`);
     }
-    // Determine which toolsets to enable.
-    // `ALL` expands to every toolset EXCEPT deprecated ones — deprecated toolsets
-    // must always be named explicitly.
+    // Determine which toolsets to enable. `ALL` expands to every toolset.
     const validToolsets = toolsets.filter((t) => TOOLSETS.includes(t));
-    const allNonDeprecatedToolsets = TOOLSETS.filter((t) => !DEPRECATED_TOOLSETS.includes(t));
-    const toolsetsToEnable = new Set(toolsets.includes(ALL_TOOLSETS) ? allNonDeprecatedToolsets : validToolsets);
+    const toolsetsToEnable = new Set(toolsets.includes(ALL_TOOLSETS) ? TOOLSETS : validToolsets);
     // Auto-discovery: only when no valid toolsets AND no valid individual tools
     // were provided. This handles both (1) no flags provided, and (2) all
     // provided flags are invalid. Skip workspace detection entirely otherwise —

package/dist/services.d.ts

@@ -40,6 +40,7 @@ import fs from 'node:fs';
 import type { B2CInstance } from '@salesforce/b2c-tooling-sdk';
 import type { AuthStrategy } from '@salesforce/b2c-tooling-sdk/auth';
 import type { ResolvedB2CConfig } from '@salesforce/b2c-tooling-sdk/config';
+import type { ConfigurationResolutionSource, ProjectDirectoryInfo, ToolResolution } from './tools/project-context.js';
 import { WebDavClient, type CustomApisClient, type MetricsClient, type ScapiSchemasClient } from '@salesforce/b2c-tooling-sdk/clients';
 /**
  * MRT (Managed Runtime) configuration.
@@ -67,6 +68,18 @@ export interface ServicesOptions {
     resolvedConfig: ResolvedB2CConfig;
     /** Project-scoped environment parsed from the effective project's .env file. */
     projectEnvironment?: Readonly<Record<string, string | undefined>>;
+    /** Inputs needed to attribute project and primary-configuration selection. */
+    resolution?: ServicesResolutionInputs;
+}
+/** Resolution inputs captured centrally by the MCP command for one tool call. */
+export interface ServicesResolutionInputs {
+    /** Effective project directory and its selection source. */
+    projectDirectory: ProjectDirectoryInfo;
+    /** Primary configuration candidate selected before the SDK resolver runs. */
+    primaryConfiguration?: {
+        path: string;
+        source: Exclude<ConfigurationResolutionSource, 'globalDefault' | 'none'>;
+    };
 }
 /**
  * Services class that provides utilities for MCP tools.
@@ -103,6 +116,7 @@ export declare class Services {
      * @private
      */
     private readonly projectEnvironment;
+    private readonly resolution;
     private readonly resolvedConfig;
     constructor(opts: ServicesOptions);
     /**
@@ -117,7 +131,7 @@ export declare class Services {
      * const services = Services.fromResolvedConfig(this.resolvedConfig);
      * ```
      */
-    static fromResolvedConfig(config: ResolvedB2CConfig, projectEnvironment?: Readonly<Record<string, string | undefined>>): Services;
+    static fromResolvedConfig(config: ResolvedB2CConfig, projectEnvironment?: Readonly<Record<string, string | undefined>>, resolution?: ServicesResolutionInputs): Services;
     /**
      * Check if a file or directory exists.
      *
@@ -175,6 +189,12 @@ export declare class Services {
      * Get OS platform information.
      */
     getPlatform(): NodeJS.Platform;
+    /**
+     * Get compact project and selected-configuration provenance for MCP results.
+     * Detailed source graphs remain available through {@link getResolvedConfig}
+     * for the config_inspect tool.
+     */
+    getResolution(): ToolResolution;
     /**
      * Get the resolved configuration (values, sources, warnings).
      *

package/dist/services.js

@@ -45,6 +45,28 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import { createCustomApisClient, createMetricsClient, createScapiSchemasClient, toOrganizationId, WebDavClient, } from '@salesforce/b2c-tooling-sdk/clients';
+function createToolResolution(config, inputs) {
+    const configuredProjectDirectory = config.values.projectDirectory;
+    const projectDirectory = inputs?.projectDirectory ??
+        (configuredProjectDirectory
+            ? { path: configuredProjectDirectory, source: 'config' }
+            : { path: process.cwd(), source: 'cwd' });
+    const dwJsonSource = config.sources.find((source) => source.name === 'DwJsonSource' && source.location);
+    const configurationSource = dwJsonSource
+        ? dwJsonSource.scope === 'global'
+            ? 'globalDefault'
+            : (inputs?.primaryConfiguration?.source ?? 'projectDirectory')
+        : 'none';
+    return {
+        projectDirectory,
+        configuration: {
+            ...(dwJsonSource?.location ? { path: dwJsonSource.location } : {}),
+            source: configurationSource,
+            ...(config.values.instanceName ? { instanceName: config.values.instanceName } : {}),
+            ...(config.values.hostname ? { hostname: config.values.hostname } : {}),
+        },
+    };
+}
 /**
  * Services class that provides utilities for MCP tools.
  *
@@ -80,12 +102,14 @@ export class Services {
      * @private
      */
     projectEnvironment;
+    resolution;
     resolvedConfig;
     constructor(opts) {
         this.b2cInstance = opts.b2cInstance;
         this.mrtConfig = opts.mrtConfig ?? {};
         this.resolvedConfig = opts.resolvedConfig;
         this.projectEnvironment = opts.projectEnvironment ?? {};
+        this.resolution = createToolResolution(opts.resolvedConfig, opts.resolution);
     }
     /**
      * Creates a Services instance from an already-resolved configuration.
@@ -99,7 +123,7 @@ export class Services {
      * const services = Services.fromResolvedConfig(this.resolvedConfig);
      * ```
      */
-    static fromResolvedConfig(config, projectEnvironment) {
+    static fromResolvedConfig(config, projectEnvironment, resolution) {
         // Build MRT config using factory methods
         const mrtConfig = {
             auth: config.hasMrtConfig() ? config.createMrtAuth() : undefined,
@@ -114,6 +138,7 @@ export class Services {
             mrtConfig,
             resolvedConfig: config,
             projectEnvironment,
+            resolution,
         });
     }
     // ============================================
@@ -216,6 +241,18 @@ export class Services {
     getPlatform() {
         return os.platform();
     }
+    /**
+     * Get compact project and selected-configuration provenance for MCP results.
+     * Detailed source graphs remain available through {@link getResolvedConfig}
+     * for the config_inspect tool.
+     */
+    getResolution() {
+        return {
+            projectDirectory: { ...this.resolution.projectDirectory },
+            ...(this.resolution.configuration ? { configuration: { ...this.resolution.configuration } } : {}),
+            ...(this.resolution.directories ? { directories: { ...this.resolution.directories } } : {}),
+        };
+    }
     /**
      * Get the resolved configuration (values, sources, warnings).
      *

package/dist/tools/adapter.d.ts

@@ -69,7 +69,12 @@ 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';
+import { type DirectoryResolutionInfo, type ProjectContextDefaults, type ProjectContextInput, type ToolResolution } from './project-context.js';
+/** Services loader enriched with registration-time project fallback provenance. */
+export interface ServicesLoader {
+    (projectContext?: ProjectContextInput): Promise<Services> | Services;
+    projectContextDefaults?: ProjectContextDefaults;
+}
 /**
  * Context provided to tool execute functions.
  * Contains the B2CInstance and/or MRT config based on tool requirements.
@@ -96,6 +101,10 @@ export interface ToolExecutionContext {
      * Created once at server startup and shared across all tool invocations.
      */
     serverContext?: ServerContext;
+    /** Compact resolution provenance that will be attached to this tool result. */
+    resolution: ToolResolution;
+    /** Record a specialized directory resolved by the tool. */
+    setResolvedDirectory: (name: string, value: DirectoryResolutionInfo) => void;
 }
 /**
  * Options for creating a tool adapter.
@@ -132,6 +141,12 @@ export interface ToolAdapterOptions<TInput, TOutput> {
      * input and use it while loading Services.
      */
     usesProjectContext?: boolean;
+    /**
+     * Whether this tool selects project configuration without requiring a
+     * B2CInstance or MRT auth object (for example config_inspect or SCAPI clients).
+     * Adds projectDirectory, configPath, and instanceName to the public schema.
+     */
+    usesConfigurationContext?: boolean;
     /**
      * Execute function that performs the tool's operation.
      * Receives validated input and a context with B2CInstance and/or auth based on requirements.
@@ -180,6 +195,8 @@ export declare function errorResult(message: string): ToolResult;
  * ```
  */
 export declare function jsonResult(data: unknown, indent?: number): ToolResult;
+/** Attach compact resolution provenance while preserving existing tool output. */
+export declare function attachResolution(result: ToolResult, resolution: ToolResolution): ToolResult;
 /**
  * Creates an MCP tool from a b2c-tooling function.
  *
@@ -219,4 +236,4 @@ export declare function jsonResult(data: unknown, indent?: number): ToolResult;
  * }, loadServices);
  * ```
  */
-export declare function createToolAdapter<TInput, TOutput>(options: ToolAdapterOptions<TInput, TOutput>, loadServices: (projectContext?: ProjectContextInput) => Promise<Services> | Services, serverContext?: ServerContext): McpTool;
+export declare function createToolAdapter<TInput, TOutput>(options: ToolAdapterOptions<TInput, TOutput>, loadServices: ServicesLoader, serverContext?: ServerContext): McpTool;

package/dist/tools/adapter.js

@@ -70,7 +70,7 @@
  * ```
  */
 import { z } from 'zod';
-import { projectContextInputSchema } from './project-context.js';
+import { createProjectContextInputSchema, } from './project-context.js';
 /**
  * Creates a text-only success result.
  *
@@ -121,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.
  *
@@ -170,10 +189,17 @@ function formatZodErrors(error) {
  * ```
  */
 export function createToolAdapter(options, loadServices, serverContext) {
-    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 }
+    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(effectiveInputSchema);
@@ -190,15 +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 projectContext = effectiveUsesProjectContext ? args : undefined;
+                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;
                 }
@@ -206,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,
@@ -221,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

@@ -46,11 +46,14 @@ function createCartridgeDeployTool(loadServices, injections) {
         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()
@@ -89,7 +92,12 @@ function createCartridgeDeployTool(loadServices, injections) {
                 }
                 // Resolve directory path: relative paths are resolved relative to project directory, absolute paths are used as-is
                 const projectDirectory = context.services.resolveProjectDirectory(args.projectDirectory);
-                const directory = context.services.resolveWithProjectDirectory(args.directory, 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,