@salesforce/b2c-dx-mcp 1.6.0 → 1.8.0

package/dist/commands/mcp.js

@@ -195,7 +195,8 @@ export default class McpServerCommand extends BaseCommand {
         }),
         'docs-topics': Flags.string({
             description: 'Limit the documentation exposed by the docs tools to these categories (comma-separated allowlist). ' +
-                'Options: script-api, job-step, commerce-api, pwa-kit-managed-runtime, sfnext, sfra, b2c-commerce, tooling. ' +
+                'Options: script-api, job-step, commerce-api, pwa-kit-managed-runtime, sfnext, sfra, b2c-commerce, tooling, ' +
+                'help-admin, help-merchant. ' +
                 'Bounds the whole docs corpus; per-call category/storefront narrow within it. Unknown names are ignored.',
             env: 'SFCC_DOCS_TOPICS',
         }),
@@ -308,8 +309,10 @@ export default class McpServerCommand extends BaseCommand {
             configPath: this.flags.config,
             // Project directory for auto-discovery. oclif handles flag with env fallback.
             projectDirectory: this.flags['project-directory'],
-            // Docs topic allowlist (bounds the docs corpus at startup).
-            docsTopics: this.flags['docs-topics'],
+            // Docs topic allowlist (bounds the docs corpus at startup). Flag first
+            // (--docs-topics / SFCC_DOCS_TOPICS), else config `docsCategories`
+            // (dw.json `docs-categories`, SFCC_DOCS_CATEGORIES, package.json).
+            docsTopics: this.flags['docs-topics'] ?? this.resolvedConfig?.values.docsCategories?.join(','),
         };
         // Add toolsets to telemetry attributes
         if (this.telemetry && startupFlags.toolsets) {

package/dist/registry.js

@@ -3,6 +3,8 @@
  * 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 os from 'node:os';
+import path from 'node:path';
 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';
@@ -102,17 +104,49 @@ export function createToolRegistry(loadServices, serverContext, detectedWorkspac
     }
     return registry;
 }
+/**
+ * Maximum directory depth workspace auto-discovery recurses when scanning the
+ * project directory. Bounding this is what keeps startup fast (and safe) when
+ * the server is launched from a broad root: a full `**` walk of a home
+ * directory can take many seconds and blocks the MCP handshake, since detection
+ * runs before the server connects.
+ *
+ * Depth is counted in path segments relative to the project directory. 5 covers
+ * the common layouts — a cartridge at `cartridges/<name>/.project` (depth 3) and
+ * a monorepo cartridge at `packages/<app>/cartridges/<name>/.project` (depth 5) —
+ * without descending into unrelated deep trees.
+ */
+const DISCOVERY_MAX_DEPTH = 5;
+/**
+ * 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.
+ * These are the classic "MCP client spawned the server from ~" cases where an
+ * unbounded (or even bounded) scan is both pointless and expensive.
+ */
+function isUnscannableRoot(dir) {
+    const resolved = path.resolve(dir);
+    // Filesystem root: parent equals self (handles `/` and Windows drive roots).
+    if (path.dirname(resolved) === resolved) {
+        return true;
+    }
+    const home = os.homedir();
+    return Boolean(home) && path.resolve(home) === resolved;
+}
 /**
  * Performs workspace auto-discovery and returns appropriate toolsets.
  * Always includes the BASE_TOOLSETS even if no project types are detected.
  *
+ * The scan is depth-bounded ({@link DISCOVERY_MAX_DEPTH}) and skipped entirely
+ * for home/root directories so it can never fan out across a whole home tree.
+ *
  * @param flags - Startup flags containing projectDirectory
- * @param reason - Reason for triggering auto-discovery (for logging)
- * @returns Array of toolsets to enable
+ * @returns Array of detected project types (empty if skipped or none found)
  */
 async function detectProjectTypes(flags) {
     const logger = getLogger();
-    // Project directory from --project-directory flag or SFCC_PROJECT_DIRECTORY env var
+    // Project directory from --project-directory flag or SFCC_PROJECT_DIRECTORY env
+    // var, defaulting to cwd. We always attempt detection from cwd rather than
+    // skipping it — the depth bound and home/root guard below make that safe.
     const projectDirectory = flags.projectDirectory ?? process.cwd();
     // Warn if project directory wasn't explicitly configured
     if (!flags.projectDirectory) {
@@ -120,7 +154,14 @@ async function detectProjectTypes(flags) {
             'MCP clients like Cursor and Claude Code often spawn servers from ~ instead of the project directory. ' +
             'Set --project-directory or SFCC_PROJECT_DIRECTORY for reliable auto-discovery.');
     }
-    const detectionResult = await detectWorkspaceType(projectDirectory);
+    // 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. ' +
+            'Set --project-directory or SFCC_PROJECT_DIRECTORY to the project path to enable it.');
+        return [];
+    }
+    const detectionResult = await detectWorkspaceType(projectDirectory, { maxDepth: DISCOVERY_MAX_DEPTH });
     logger.info({ projectTypes: detectionResult.projectTypes, matchedPatterns: detectionResult.matchedPatterns }, `Workspace detection: project types: ${detectionResult.projectTypes.join(', ') || 'none'}`);
     return detectionResult.projectTypes;
 }
@@ -156,22 +197,21 @@ export async function registerToolsets(flags, server, loadServices, serverContex
     const individualTools = flags.tools ?? [];
     const allowNonGaTools = flags.allowNonGaTools ?? false;
     const logger = getLogger();
-    // Detect the workspace type once up front. It informs both the
-    // docs tools (favoring the current workspace's docs and surfacing it in the
-    // tool descriptions) and toolset auto-discovery below, so we only hit the
-    // filesystem a single time.
-    const detectedWorkspaces = await detectProjectTypes(flags);
     // Resolve the launch-time docs topic allowlist (bounds the whole docs corpus).
     const enabledDocCategories = resolveEnabledCategories(flags.docsTopics, (invalid) => logger.warn({ invalidTopics: invalid, validTopics: DOC_CATEGORIES }, `Ignoring unknown documentation topic(s) in --docs-topics: "${invalid.join('", "')}"`));
     if (enabledDocCategories) {
         logger.info({ docsTopics: enabledDocCategories }, `Documentation restricted to topics: ${enabledDocCategories.join(', ')}`);
     }
-    // Create the tool registry (all available tools)
-    const toolRegistry = createToolRegistry(loadServices, serverContext, detectedWorkspaces, enabledDocCategories);
-    // Build flat list of all tools for lookup
-    const allTools = Object.values(toolRegistry).flat();
-    const allToolsByName = new Map(allTools.map((tool) => [tool.name, tool]));
-    const existingToolNames = new Set(allToolsByName.keys());
+    // Build the tool registry to validate flag input. The set of available tools
+    // (names, toolsets) does NOT depend on the detected workspace — only the docs
+    // tool descriptions do — so we can resolve flag validity before deciding
+    // whether workspace detection is even needed. If auto-discovery later runs,
+    // we rebuild the registry with the detected workspaces so the docs tools pick
+    // up the workspace hint.
+    let toolRegistry = createToolRegistry(loadServices, serverContext, [], enabledDocCategories);
+    const existingToolNames = new Set(Object.values(toolRegistry)
+        .flat()
+        .map((tool) => tool.name));
     // Determine valid individual tools
     const invalidTools = individualTools.filter((name) => !existingToolNames.has(name));
     const validIndividualTools = individualTools.filter((name) => existingToolNames.has(name));
@@ -190,16 +230,24 @@ export async function registerToolsets(flags, server, loadServices, serverContex
     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);
-    // Auto-discovery: If no valid toolsets AND no valid individual tools, map the
-    // already-detected workspace type(s) to toolsets. This handles both: (1) no
-    // flags provided, and (2) all provided flags are invalid. Always enables at
-    // least the BASE_TOOLSETS even if no project types are detected.
+    // 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 —
+    // when the user has explicitly chosen toolsets/tools, the filesystem scan
+    // cannot change which tools are registered, so paying for it (and risking a
+    // costly recursive walk) would be pointless.
     if (toolsetsToEnable.size === 0 && validIndividualTools.length === 0) {
+        const detectedWorkspaces = await detectProjectTypes(flags);
         const discoveredToolsets = getToolsetsForProjectTypes(detectedWorkspaces);
         logger.info({ projectTypes: detectedWorkspaces, enabledToolsets: discoveredToolsets }, `Auto-discovery: enabling toolsets ${discoveredToolsets.join(', ')}`);
         for (const toolset of discoveredToolsets) {
             toolsetsToEnable.add(toolset);
         }
+        // Rebuild so the docs tools reflect the detected workspace in their
+        // descriptions and default workspace resolution.
+        if (detectedWorkspaces.length > 0) {
+            toolRegistry = createToolRegistry(loadServices, serverContext, detectedWorkspaces, enabledDocCategories);
+        }
     }
     // Build the set of tools to register:
     // 1. Start with tools from enabled toolsets
@@ -215,7 +263,11 @@ export async function registerToolsets(flags, server, loadServices, serverContex
             }
         }
     }
-    // Step 2: Add individual tools from --tools (can be from any toolset)
+    // Step 2: Add individual tools from --tools (can be from any toolset).
+    // Look up against the final registry (which may have been rebuilt above).
+    const allToolsByName = new Map(Object.values(toolRegistry)
+        .flat()
+        .map((tool) => [tool.name, tool]));
     for (const toolName of validIndividualTools) {
         const tool = allToolsByName.get(toolName);
         if (tool && !registeredToolNames.has(toolName)) {

package/dist/tools/docs/docs-read.d.ts

@@ -1,4 +1,5 @@
 import { type DocCategory } from '@salesforce/b2c-tooling-sdk/docs';
+import type { ProjectType } from '@salesforce/b2c-tooling-sdk/discovery';
 import type { McpTool } from '../../utils/index.js';
 import type { Services } from '../../services.js';
-export declare function createDocsReadTool(loadServices: () => Promise<Services> | Services, enabledCategories?: readonly DocCategory[]): McpTool;
+export declare function createDocsReadTool(loadServices: () => Promise<Services> | Services, enabledCategories?: readonly DocCategory[], detectedWorkspaces?: readonly ProjectType[]): McpTool;

package/dist/tools/docs/docs-read.js

@@ -9,14 +9,15 @@ import { createToolAdapter, errorResult, jsonResult } from '../adapter.js';
 import { enabledCategoriesNote } from './topics.js';
 /** Default maximum characters of content returned per read call, to bound the inline payload. */
 const DEFAULT_MAX_LENGTH = 12_000;
-export function createDocsReadTool(loadServices, enabledCategories) {
+export function createDocsReadTool(loadServices, enabledCategories, detectedWorkspaces = []) {
     return createToolAdapter({
         name: 'docs_read',
-        description: 'Read B2C Commerce documentation (markdown) for a class, module, job step, or guide. ' +
+        description: 'Read B2C Commerce documentation (markdown) for a class, module, job step, guide, or Help article. ' +
             'Accepts an exact id (e.g. "dw.catalog.ProductMgr", "sfnext/sfnext-get-started") or a fuzzy ' +
-            'query — best match wins. Script API / job-step content is bundled; Developer Center guide ' +
-            'content is fetched from its published URL on demand (with a summary/headings fallback if the ' +
-            'network is unavailable). If you do not know the id, call docs_search first. Long docs are ' +
+            'query — best match wins (a fuzzy query favors the detected workspace, matching docs_search). ' +
+            'Job-step content is bundled; Script API, Developer Center guide, and Salesforce Help content is ' +
+            'fetched from its published URL on demand and cached locally (with a summary/headings fallback if ' +
+            'the network is unavailable). If you do not know the id, call docs_search first. Long docs are ' +
             'truncated to maxLength chars; page with offset when truncated=true. The returned entry ' +
             'includes the canonical url for citation.' +
             enabledCategoriesNote(enabledCategories),
@@ -40,7 +41,12 @@ export function createDocsReadTool(loadServices, enabledCategories) {
                 .describe(`Maximum characters of content to return. Defaults to ${DEFAULT_MAX_LENGTH}.`),
         },
         async execute(args) {
-            const found = await readDocByQuery(args.query, { enabledCategories });
+            // Favor the detected workspace when resolving a fuzzy query so a read
+            // picks the same top hit docs_search ranks first. Exact id matches
+            // short-circuit inside readDocByQuery before searching, so the boost
+            // only affects fuzzy resolution.
+            const workspace = detectedWorkspaces.length > 0 ? [...detectedWorkspaces] : undefined;
+            const found = await readDocByQuery(args.query, { enabledCategories, workspace });
             if (!found)
                 return null;
             const totalLength = found.content.length;

package/dist/tools/docs/index.js

@@ -16,7 +16,7 @@ export function createDocsTools(loadServices, context = {}) {
     const { detectedWorkspaces = [], enabledCategories } = context;
     return [
         createDocsSearchTool(loadServices, detectedWorkspaces, enabledCategories),
-        createDocsReadTool(loadServices, enabledCategories),
+        createDocsReadTool(loadServices, enabledCategories, detectedWorkspaces),
         createDocsListTool(loadServices, detectedWorkspaces, enabledCategories),
         createDocsSchemaSearchTool(loadServices),
         createDocsSchemaReadTool(loadServices),

package/oclif.manifest.json

@@ -403,7 +403,7 @@
           "type": "option"
         },
         "docs-topics": {
-          "description": "Limit the documentation exposed by the docs tools to these categories (comma-separated allowlist). Options: script-api, job-step, commerce-api, pwa-kit-managed-runtime, sfnext, sfra, b2c-commerce, tooling. Bounds the whole docs corpus; per-call category/storefront narrow within it. Unknown names are ignored.",
+          "description": "Limit the documentation exposed by the docs tools to these categories (comma-separated allowlist). Options: script-api, job-step, commerce-api, pwa-kit-managed-runtime, sfnext, sfra, b2c-commerce, tooling, help-admin, help-merchant. Bounds the whole docs corpus; per-call category/storefront narrow within it. Unknown names are ignored.",
           "env": "SFCC_DOCS_TOPICS",
           "name": "docs-topics",
           "hasDynamicHelp": false,
@@ -428,5 +428,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "1.6.0"
+  "version": "1.8.0"
 }

package/package.json

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