@salesforce/b2c-dx-mcp 1.10.1 → 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

@@ -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,17 @@ 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
+     * 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.
      */
-    protected loadConfiguration(): Promise<ResolvedB2CConfig>;
+    protected loadConfiguration(projectContext?: ProjectContextInput): Promise<ResolvedB2CConfig>;
     /**
      * Loads configuration and creates a new Services instance.
      *
@@ -97,7 +102,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 +130,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
+     * 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() {
+    async loadConfiguration(projectContext) {
         const mrt = extractMrtFlags(this.flags);
+        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
+            ? 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,
+            instance: projectContext?.instanceName ?? baseOptions.instance,
+            projectDirectory: effectiveProjectDirectory,
+            workingDirectory: effectiveProjectDirectory,
         };
         // 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,41 @@ 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 baseOptions = this.flags ? this.getBaseConfigOptions() : {};
+        const configuredProjectDirectory = baseOptions.projectDirectory;
+        const effectiveProjectDirectory = path.resolve(projectContext?.projectDirectory ?? configuredProjectDirectory ?? process.cwd());
+        const projectEnvironment = this.loadProjectEnvironment(effectiveProjectDirectory);
+        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.
@@ -333,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);
@@ -362,5 +427,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

@@ -2,8 +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 { ServicesLoader } from './tools/adapter.js';
 /**
  * Registry of tools organized by toolset.
  * Tools can belong to multiple toolsets via their `toolsets` array.
@@ -17,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: () => 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: 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/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

@@ -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.
@@ -65,6 +66,20 @@ 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>>;
+    /** 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.
@@ -100,6 +115,8 @@ export declare class Services {
      * Provides access to shortCode, tenantId, and OAuth credentials.
      * @private
      */
+    private readonly projectEnvironment;
+    private readonly resolution;
     private readonly resolvedConfig;
     constructor(opts: ServicesOptions);
     /**
@@ -114,7 +131,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>>, resolution?: ServicesResolutionInputs): Services;
     /**
      * Check if a file or directory exists.
      *
@@ -143,6 +160,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.
      */
@@ -167,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.
  *
@@ -79,11 +101,15 @@ export class Services {
      * Provides access to shortCode, tenantId, and OAuth credentials.
      * @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.
@@ -97,7 +123,7 @@ export class Services {
      * const services = Services.fromResolvedConfig(this.resolvedConfig);
      * ```
      */
-    static fromResolvedConfig(config) {
+    static fromResolvedConfig(config, projectEnvironment, resolution) {
         // Build MRT config using factory methods
         const mrtConfig = {
             auth: config.hasMrtConfig() ? config.createMrtAuth() : undefined,
@@ -111,6 +137,8 @@ export class Services {
             b2cInstance,
             mrtConfig,
             resolvedConfig: config,
+            projectEnvironment,
+            resolution,
         });
     }
     // ============================================
@@ -161,6 +189,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.
      */
@@ -206,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,6 +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 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.
@@ -95,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.
@@ -125,6 +135,18 @@ 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;
+    /**
+     * 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.
@@ -173,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.
  *
@@ -212,4 +236,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: ServicesLoader, serverContext?: ServerContext): McpTool;