@salesforce/b2c-dx-mcp 1.4.1 → 1.5.0

package/dist/commands/mcp.d.ts

@@ -21,6 +21,7 @@ export default class McpServerCommand extends BaseCommand<typeof McpServerComman
     static flags: {
         toolsets: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         tools: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'docs-topics': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'allow-non-ga-tools': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         server: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'webdav-server': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
@@ -34,7 +35,7 @@ export default class McpServerCommand extends BaseCommand<typeof McpServerComman
         'client-id': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'client-secret': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'auth-scope': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        'short-code': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'short-code': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'tenant-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'auth-methods': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'user-auth': import("@oclif/core/interfaces").BooleanFlag<boolean>;

package/dist/commands/mcp.js

@@ -193,6 +193,12 @@ export default class McpServerCommand extends BaseCommand {
             env: 'SFCC_TOOLS',
             parse: async (input) => input.toLowerCase(),
         }),
+        '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. ' +
+                'Bounds the whole docs corpus; per-call category/storefront narrow within it. Unknown names are ignored.',
+            env: 'SFCC_DOCS_TOPICS',
+        }),
         // Feature flags
         'allow-non-ga-tools': Flags.boolean({
             description: 'Enable non-GA (experimental) tools',
@@ -302,6 +308,8 @@ 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'],
         };
         // Add toolsets to telemetry attributes
         if (this.telemetry && startupFlags.toolsets) {

package/dist/registry.d.ts

@@ -1,3 +1,5 @@
+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';
@@ -15,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): ToolRegistry;
+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>;

package/dist/registry.js

@@ -5,6 +5,7 @@
  */
 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 { createCartridgesTools } from './tools/cartridges/index.js';
 import { createDiagnosticsTools } from './tools/diagnostics/index.js';
@@ -26,6 +27,9 @@ const BASE_TOOLSETS = ['SCAPI', 'DIAGNOSTICS'];
  */
 const PROJECT_TYPE_TOOLSETS = {
     cartridges: ['CARTRIDGES'],
+    // SFRA is a cartridge project, so it enables the same toolset as `cartridges`.
+    // (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
@@ -70,7 +74,7 @@ function getToolsetsForProjectTypes(projectTypes) {
  * @param loadServices - Function that loads configuration and returns Services instance
  * @returns Complete tool registry
  */
-export function createToolRegistry(loadServices, serverContext) {
+export function createToolRegistry(loadServices, serverContext, detectedWorkspaces = [], enabledDocCategories) {
     const registry = {
         CARTRIDGES: [],
         DIAGNOSTICS: [],
@@ -84,7 +88,7 @@ export function createToolRegistry(loadServices, serverContext) {
     const allTools = [
         ...createCartridgesTools(loadServices),
         ...createDiagnosticsTools(loadServices, serverContext),
-        ...createDocsTools(loadServices),
+        ...createDocsTools(loadServices, { detectedWorkspaces, enabledCategories: enabledDocCategories }),
         ...createMrtTools(loadServices),
         ...createPwav3Tools(loadServices),
         ...createScapiTools(loadServices),
@@ -106,7 +110,7 @@ export function createToolRegistry(loadServices, serverContext) {
  * @param reason - Reason for triggering auto-discovery (for logging)
  * @returns Array of toolsets to enable
  */
-async function performAutoDiscovery(flags, reason) {
+async function detectProjectTypes(flags) {
     const logger = getLogger();
     // Project directory from --project-directory flag or SFCC_PROJECT_DIRECTORY env var
     const projectDirectory = flags.projectDirectory ?? process.cwd();
@@ -117,16 +121,8 @@ async function performAutoDiscovery(flags, reason) {
             'Set --project-directory or SFCC_PROJECT_DIRECTORY for reliable auto-discovery.');
     }
     const detectionResult = await detectWorkspaceType(projectDirectory);
-    // Map all detected project types to MCP toolsets (union)
-    // Note: getToolsetsForProjectTypes always includes BASE_TOOLSET
-    const mappedToolsets = getToolsetsForProjectTypes(detectionResult.projectTypes);
-    logger.info({
-        reason,
-        projectTypes: detectionResult.projectTypes,
-        matchedPatterns: detectionResult.matchedPatterns,
-        enabledToolsets: mappedToolsets,
-    }, `Auto-discovery (${reason}): project types: ${detectionResult.projectTypes.join(', ') || 'none'}`);
-    return mappedToolsets;
+    logger.info({ projectTypes: detectionResult.projectTypes, matchedPatterns: detectionResult.matchedPatterns }, `Workspace detection: project types: ${detectionResult.projectTypes.join(', ') || 'none'}`);
+    return detectionResult.projectTypes;
 }
 /**
  * Register tools with the MCP server based on startup flags.
@@ -160,8 +156,18 @@ 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);
+    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]));
@@ -184,12 +190,13 @@ 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, detect workspace type.
-    // This handles both: (1) no flags provided, and (2) all provided flags are invalid.
-    // Auto-discovery enables appropriate toolsets based on workspace type,
-    // or at minimum the BASE_TOOLSETS if no project types are detected.
+    // 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.
     if (toolsetsToEnable.size === 0 && validIndividualTools.length === 0) {
-        const discoveredToolsets = await performAutoDiscovery(flags, 'no valid toolsets or tools');
+        const discoveredToolsets = getToolsetsForProjectTypes(detectedWorkspaces);
+        logger.info({ projectTypes: detectedWorkspaces, enabledToolsets: discoveredToolsets }, `Auto-discovery: enabling toolsets ${discoveredToolsets.join(', ')}`);
         for (const toolset of discoveredToolsets) {
             toolsetsToEnable.add(toolset);
         }

package/dist/server.js

@@ -48,11 +48,14 @@ export class B2CDxMcpServer extends McpServer {
             try {
                 const result = await handler(args);
                 const runTimeMs = Date.now() - startTime;
+                // Extract error message from CallToolResult content when isError is true
+                const errorMessage = result.isError ? result.content?.find((c) => c.type === 'text')?.text : undefined;
                 await this.telemetry
                     ?.sendEventAndFlush('TOOL_CALLED', {
                     toolName: name,
                     runTimeMs,
                     isError: result.isError ?? false,
+                    ...(errorMessage ? { errorMessage } : {}),
                 })
                     .catch((error_) => {
                     getLogger().debug({ err: error_, toolName: name }, '[mcp] telemetry sendEventAndFlush failed');
@@ -66,6 +69,8 @@ export class B2CDxMcpServer extends McpServer {
                     toolName: name,
                     runTimeMs,
                     isError: true,
+                    errorMessage: error instanceof Error ? error.message : String(error),
+                    ...(error instanceof Error && error.cause ? { errorCause: String(error.cause) } : {}),
                 })
                     .catch((error_) => {
                     getLogger().debug({ err: error_, toolName: name }, '[mcp] telemetry sendEventAndFlush failed');

package/dist/tools/diagnostics/debug-capture-at-breakpoint.js

@@ -9,6 +9,9 @@ import { projectFrame, projectVariable, resolveBreakpointPath, } from '@salesfor
 import { getRegistry, getSessionEntry } from './session-registry.js';
 const DEFAULT_TIMEOUT_MS = 30_000;
 const MAX_TIMEOUT_MS = 120_000;
+const TIMEOUT_HINT = 'Breakpoint not hit. First confirm the triggered request actually exercised this code path and the breakpoint line is reachable. ' +
+    'In some production instance group configurations (which can run multiple app servers — this never applies to sandboxes), a breakpoint may be missed because the request landed on a different app server than the one holding the debug session. ' +
+    'Only in that specific case, retrieve session_cookie from debug_list_sessions and resend the triggering request with that cookie (Cookie: <name>=<value>) to pin it to the app server holding the session.';
 export function createDebugCaptureAtBreakpointTool(loadServices, serverContext) {
     return createToolAdapter({
         name: 'debug_capture_at_breakpoint',
@@ -73,6 +76,7 @@ export function createDebugCaptureAtBreakpointTool(loadServices, serverContext)
                     halted: false,
                     timed_out: true,
                     auto_continued: false,
+                    hint: TIMEOUT_HINT,
                 };
             }
             const threadDetail = await entry.manager.client.getThread(thread.id);

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

@@ -9,8 +9,8 @@ import { getRegistry } from './session-registry.js';
 export function createDebugListSessionsTool(loadServices, serverContext) {
     return createToolAdapter({
         name: 'debug_list_sessions',
-        description: 'List active script debugger sessions with their breakpoints, any halted threads, and the session_cookie (e.g. dwsid). ' +
-            'Use this to discover orphaned sessions, check whether breakpoints are armed, poll for halted threads in the non-blocking debug workflow, and retrieve the session cookie to pin a triggering request (Cookie: <name>=<value>) to the app server holding the session.',
+        description: 'List active script debugger sessions with their breakpoints and any halted threads. ' +
+            'Use this to discover orphaned sessions, check whether breakpoints are armed, and poll for halted threads in the non-blocking debug workflow.',
         toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'SCAPI'],
         inputSchema: {},
         async execute(_args, context) {

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

@@ -13,9 +13,7 @@ export function createDebugStartSessionTool(loadServices, serverContext) {
         name: 'debug_start_session',
         description: 'Start a script debugger session on a B2C Commerce instance to debug SFRA controllers, custom API scripts, hooks, jobs, or any server-side script. ' +
             'Returns a session_id for use with other debug tools, plus discovered cartridge mappings. ' +
-            'Also returns session_cookie (e.g. dwsid): to reliably hit a breakpoint on a multi-app-server instance, send the request that triggers your code (storefront page load, SCAPI/OCAPI call) with this cookie (Cookie: <name>=<value>) so it lands on the same app server holding the debug session. ' +
-            'WARNING: Debug sessions halt remote request threads on the instance. Always call debug_end_session when finished. ' +
-            'Requires Basic auth credentials (username/password) and the script debugger enabled in Business Manager.',
+            'WARNING: Debug sessions halt remote request threads on the instance. Always call debug_end_session when finished.',
         toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'SCAPI'],
         inputSchema: {
             cartridge_directory: z
@@ -31,8 +29,8 @@ export function createDebugStartSessionTool(loadServices, serverContext) {
             const registry = getRegistry(context);
             const credentials = context.services.getBasicAuthCredentials();
             if (!credentials) {
-                throw new Error('Basic auth credentials (hostname, username, password) are required for the script debugger. ' +
-                    'Set via SFCC_SERVER/SFCC_USERNAME/SFCC_PASSWORD env vars, or configure in dw.json.');
+                throw new Error('Basic auth credentials (username/password) are required for the script debugger. ' +
+                    'Set via SFCC_SERVER/SFCC_USERNAME/SFCC_PASSWORD env vars, or dw.json.');
             }
             const { hostname, username, password } = credentials;
             const clientId = args.client_id ?? 'b2c-cli';

package/dist/tools/diagnostics/debug-wait-for-stop.js

@@ -9,6 +9,9 @@ import { projectThreadLocation } from '@salesforce/b2c-tooling-sdk/operations/de
 import { getRegistry, getSessionEntry } from './session-registry.js';
 const DEFAULT_TIMEOUT_MS = 30_000;
 const MAX_TIMEOUT_MS = 120_000;
+const TIMEOUT_HINT = 'Breakpoint not hit. First confirm the request actually exercised this code path and the breakpoint line is reachable. ' +
+    'In some production instance group configurations (which can run multiple app servers — this never applies to sandboxes), a breakpoint may be missed because the request landed on a different app server than the one holding the debug session. ' +
+    'Only in that specific case, retrieve session_cookie from debug_list_sessions and resend the triggering request with that cookie (Cookie: <name>=<value>) to pin it to the app server holding the session.';
 export function createDebugWaitForStopTool(loadServices, serverContext) {
     return createToolAdapter({
         name: 'debug_wait_for_stop',
@@ -31,7 +34,7 @@ export function createDebugWaitForStopTool(loadServices, serverContext) {
             const timeout = Math.min(args.timeout_ms ?? DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS);
             const thread = await getRegistry(context).waitForHalt(entry, timeout);
             if (!thread)
-                return { halted: false, timed_out: true };
+                return { halted: false, timed_out: true, hint: TIMEOUT_HINT };
             const location = projectThreadLocation(thread, entry.sourceMapper);
             return {
                 halted: true,

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

@@ -1,3 +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 createDocsListTool(loadServices: () => Promise<Services> | Services): McpTool;
+export declare function createDocsListTool(loadServices: () => Promise<Services> | Services, detectedWorkspaces?: readonly ProjectType[], enabledCategories?: readonly DocCategory[]): McpTool;

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

@@ -3,18 +3,78 @@
  * 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 { listDocs } from '@salesforce/b2c-tooling-sdk/docs';
+import { z } from 'zod';
+import { listDocs, categoriesForWorkspace } from '@salesforce/b2c-tooling-sdk/docs';
 import { createToolAdapter, jsonResult } from '../adapter.js';
-export function createDocsListTool(loadServices) {
+import { categoryEnumValues, enabledCategoriesNote } from './topics.js';
+import { WORKSPACE_VALUES, detectedWorkspaceNote, resolveWorkspace } from './storefront.js';
+/** Default page size for a filtered listing. Bounds payload size (large corpora hold 500+ entries). */
+const DEFAULT_LIMIT = 100;
+/** Projects a full entry to the table-of-contents shape. */
+function toListEntry(entry) {
+    return { id: entry.id, title: entry.title, category: entry.category };
+}
+export function createDocsListTool(loadServices, detectedWorkspaces = [], enabledCategories) {
     return createToolAdapter({
         name: 'docs_list',
-        description: 'List every available Script API documentation entry (id + title). ' +
-            'Output is large; prefer docs_search for targeted lookups.',
+        description: 'Enumerate B2C Commerce documentation entries (id + title + category only) for a category or workspace. ' +
+            'Prefer docs_search for questions — this tool is for browsing a known category. Without a category or ' +
+            'workspace it returns just a category directory (counts), not the full corpus. Results are a table of ' +
+            'contents; paginated via limit/offset. Use docs_read for content.' +
+            enabledCategoriesNote(enabledCategories) +
+            detectedWorkspaceNote(detectedWorkspaces),
         toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'MRT', 'PWAV3', 'SCAPI', 'STOREFRONTNEXT'],
-        inputSchema: {},
-        async execute() {
-            const entries = listDocs();
-            return { count: entries.length, entries };
+        inputSchema: {
+            category: z
+                .enum(categoryEnumValues(enabledCategories))
+                .optional()
+                .describe('Restrict the listing to one documentation category.'),
+            workspace: z
+                .enum(WORKSPACE_VALUES)
+                .optional()
+                .describe('Limit to a workspace\'s relevant categories. "auto" uses the auto-detected workspace; ' +
+                'or name a type. Omit for the category directory.'),
+            limit: z.number().int().positive().optional().describe(`Max entries per page. Defaults to ${DEFAULT_LIMIT}.`),
+            offset: z.number().int().nonnegative().optional().describe('Number of entries to skip (for pagination).'),
+        },
+        async execute(args) {
+            // Explicit category wins; otherwise a workspace narrows to its relevant categories.
+            const workspace = resolveWorkspace(args.workspace, detectedWorkspaces);
+            const filter = args.category ??
+                (args.workspace && args.workspace !== 'all' && workspace ? categoriesForWorkspace(workspace) : undefined);
+            // No filter at all → return a compact directory of categories + counts,
+            // never the whole corpus (which would blow the inline payload budget).
+            // The directory itself is bounded by the launch-time allowlist.
+            if (!filter) {
+                const counts = new Map();
+                for (const e of listDocs(undefined, enabledCategories)) {
+                    if (e.category)
+                        counts.set(e.category, (counts.get(e.category) ?? 0) + 1);
+                }
+                const categories = [...counts.entries()]
+                    .map(([category, count]) => ({ category, count }))
+                    .sort((a, b) => b.count - a.count);
+                const total = categories.reduce((sum, c) => sum + c.count, 0);
+                return {
+                    note: 'Pass a category (or workspace) to list its entries, or use docs_search for a query.',
+                    total,
+                    categories,
+                };
+            }
+            const all = listDocs(filter, enabledCategories);
+            const offset = args.offset ?? 0;
+            const limit = args.limit ?? DEFAULT_LIMIT;
+            const page = all.slice(offset, offset + limit).map((e) => toListEntry(e));
+            const end = offset + page.length;
+            const truncated = end < all.length;
+            return {
+                category: filter,
+                total: all.length,
+                offset,
+                count: page.length,
+                entries: page,
+                ...(truncated && { truncated: true, nextOffset: end }),
+            };
         },
         formatOutput: (output) => jsonResult(output),
     }, loadServices);

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

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

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

@@ -6,18 +6,56 @@
 import { z } from 'zod';
 import { readDocByQuery } from '@salesforce/b2c-tooling-sdk/docs';
 import { createToolAdapter, errorResult, jsonResult } from '../adapter.js';
-export function createDocsReadTool(loadServices) {
+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) {
     return createToolAdapter({
         name: 'docs_read',
-        description: 'Read full Script API documentation (markdown) for a B2C Commerce class or module. ' +
-            'Accepts an exact id (e.g., "dw.catalog.ProductMgr") or fuzzy query — best match wins. ' +
-            'Content can be large; if you do not know the id, call docs_search first to narrow down.',
+        description: 'Read B2C Commerce documentation (markdown) for a class, module, job step, or guide. ' +
+            '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 ' +
+            'truncated to maxLength chars; page with offset when truncated=true. The returned entry ' +
+            'includes the canonical url for citation.' +
+            enabledCategoriesNote(enabledCategories),
         toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'MRT', 'PWAV3', 'SCAPI', 'STOREFRONTNEXT'],
         inputSchema: {
-            query: z.string().min(1).describe('Exact id ("dw.catalog.ProductMgr") or fuzzy query ("ProductMgr").'),
+            query: z
+                .string()
+                .min(1)
+                .describe('Exact id ("dw.catalog.ProductMgr", "sfnext/sfnext-get-started") or fuzzy query.'),
+            offset: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe('Character offset to start reading from (for paging long docs). Defaults to 0.'),
+            maxLength: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe(`Maximum characters of content to return. Defaults to ${DEFAULT_MAX_LENGTH}.`),
         },
         async execute(args) {
-            return readDocByQuery(args.query);
+            const found = await readDocByQuery(args.query, { enabledCategories });
+            if (!found)
+                return null;
+            const totalLength = found.content.length;
+            const offset = Math.min(args.offset ?? 0, totalLength);
+            const maxLength = args.maxLength ?? DEFAULT_MAX_LENGTH;
+            const slice = found.content.slice(offset, offset + maxLength);
+            const end = offset + slice.length;
+            const truncated = end < totalLength;
+            return {
+                entry: found.entry,
+                content: slice,
+                totalLength,
+                offset,
+                ...(truncated && { truncated: true, nextOffset: end }),
+            };
         },
         formatOutput: (output) => output ? jsonResult(output) : errorResult('No documentation found. Try docs_search to find candidates.'),
     }, loadServices);

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

@@ -1,3 +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 createDocsSearchTool(loadServices: () => Promise<Services> | Services): McpTool;
+export declare function createDocsSearchTool(loadServices: () => Promise<Services> | Services, detectedWorkspaces?: readonly ProjectType[], enabledCategories?: readonly DocCategory[]): McpTool;

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

@@ -6,20 +6,81 @@
 import { z } from 'zod';
 import { searchDocs } from '@salesforce/b2c-tooling-sdk/docs';
 import { createToolAdapter, jsonResult } from '../adapter.js';
-export function createDocsSearchTool(loadServices) {
+import { categoryEnumValues, enabledCategoriesNote } from './topics.js';
+import { WORKSPACE_VALUES, detectedWorkspaceNote, resolveWorkspace } from './storefront.js';
+/** Default number of results returned when `limit` is not supplied. Kept small to bound payload size for agents. */
+const DEFAULT_LIMIT = 5;
+/**
+ * Projects a search hit to the payload returned to an agent. By default we keep
+ * only the triage-critical fields (id, title, category, summary, score) and drop
+ * `keywords` (index-tuning metadata) and `url` (derivable / returned on read),
+ * which together roughly double the payload. `verbose` restores them.
+ */
+function leanResult(entry, score, verbose) {
+    const base = {
+        id: entry.id,
+        title: entry.title,
+        category: entry.category,
+        score,
+    };
+    if (entry.summary)
+        base.summary = entry.summary;
+    if (verbose) {
+        if (entry.keywords && entry.keywords.length > 0)
+            base.keywords = entry.keywords;
+        if (entry.url)
+            base.url = entry.url;
+        if (entry.sourceUrl)
+            base.sourceUrl = entry.sourceUrl;
+    }
+    return base;
+}
+export function createDocsSearchTool(loadServices, detectedWorkspaces = [], enabledCategories) {
     return createToolAdapter({
         name: 'docs_search',
-        description: 'Fuzzy-search the bundled B2C Commerce Script API documentation by class, module, or partial name ' +
-            '(e.g., "ProductMgr", "dw.catalog", "Status"). Returns matching ids + relevance score. ' +
-            'Use this BEFORE docs_read when you do not know the exact id.',
+        description: 'PRIMARY entry point for B2C Commerce docs: Script API reference (e.g. "ProductMgr"), standard job steps, ' +
+            'Developer Center guides (commerce-api, pwa-kit-managed-runtime, sfnext, sfra, b2c-commerce), and this ' +
+            "tooling's own guides. Use for ANY B2C Commerce developer or admin question not already grounded in a " +
+            'loaded skill or the current project. Content-aware ranking — pass a natural-language query (prefer this ' +
+            'over docs_list, which only enumerates). Optionally restrict by category or workspace. Returns id, title, ' +
+            'category, summary, and score for triage; pass verbose=true for keywords+url. Call this BEFORE docs_read ' +
+            'when you do not know the exact id.' +
+            enabledCategoriesNote(enabledCategories) +
+            detectedWorkspaceNote(detectedWorkspaces),
         toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'MRT', 'PWAV3', 'SCAPI', 'STOREFRONTNEXT'],
         inputSchema: {
-            query: z.string().min(1).describe('Search query (class name, module path, or partial match).'),
-            limit: z.number().int().positive().optional().describe('Maximum number of results to return. Defaults to 20.'),
+            query: z.string().min(1).describe('Search query (class name, topic, or natural-language phrase).'),
+            category: z.enum(categoryEnumValues(enabledCategories)).optional().describe('Restrict results to one corpus.'),
+            workspace: z
+                .enum(WORKSPACE_VALUES)
+                .optional()
+                .describe('Workspace context. "auto" (default) favors the auto-detected workspace\'s docs; ' +
+                '"all" disables the preference; or name a type (cartridges, sfra, pwa-kit-v3, storefront-next).'),
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe(`Maximum number of results to return. Defaults to ${DEFAULT_LIMIT}.`),
+            verbose: z
+                .boolean()
+                .optional()
+                .describe('Include keywords and canonical url on each result (larger payload). Defaults to false.'),
         },
         async execute(args) {
-            const results = searchDocs(args.query, args.limit ?? 20);
-            return { query: args.query, results };
+            const workspace = resolveWorkspace(args.workspace, detectedWorkspaces);
+            const results = searchDocs(args.query, {
+                limit: args.limit ?? DEFAULT_LIMIT,
+                category: args.category,
+                workspace,
+                enabledCategories,
+            });
+            return {
+                query: args.query,
+                ...(args.category && { category: args.category }),
+                ...(workspace && { workspace }),
+                results: results.map((r) => leanResult(r.entry, r.score, args.verbose ?? false)),
+            };
         },
         formatOutput: (output) => jsonResult(output),
     }, loadServices);

package/dist/tools/docs/index.d.ts

@@ -1,3 +1,25 @@
+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 createDocsTools(loadServices: () => Promise<Services> | Services): McpTool[];
+/**
+ * Server-startup context baked into the documentation tools.
+ */
+export interface DocsToolContext {
+    /**
+     * Workspace type(s) detected at startup. Baked into the search/list
+     * tool descriptions and used as the default workspace context so results
+     * favor the current workspace.
+     */
+    detectedWorkspaces?: readonly ProjectType[];
+    /**
+     * A launch-time allowlist of documentation categories (from `--docs-topics`).
+     * When set, the docs tools expose ONLY these categories — a hard boundary the
+     * per-call `category`/`workspace` narrowing operates within.
+     */
+    enabledCategories?: readonly DocCategory[];
+}
+/**
+ * Builds the documentation tools with the given server-startup context.
+ */
+export declare function createDocsTools(loadServices: () => Promise<Services> | Services, context?: DocsToolContext): McpTool[];

package/dist/tools/docs/index.js

@@ -9,11 +9,15 @@ import { createDocsSchemaListTool } from './docs-schema-list.js';
 import { createDocsSchemaReadTool } from './docs-schema-read.js';
 import { createDocsSchemaSearchTool } from './docs-schema-search.js';
 import { createDocsSearchTool } from './docs-search.js';
-export function createDocsTools(loadServices) {
+/**
+ * Builds the documentation tools with the given server-startup context.
+ */
+export function createDocsTools(loadServices, context = {}) {
+    const { detectedWorkspaces = [], enabledCategories } = context;
     return [
-        createDocsSearchTool(loadServices),
-        createDocsReadTool(loadServices),
-        createDocsListTool(loadServices),
+        createDocsSearchTool(loadServices, detectedWorkspaces, enabledCategories),
+        createDocsReadTool(loadServices, enabledCategories),
+        createDocsListTool(loadServices, detectedWorkspaces, enabledCategories),
         createDocsSchemaSearchTool(loadServices),
         createDocsSchemaReadTool(loadServices),
         createDocsSchemaListTool(loadServices),

package/dist/tools/docs/storefront.d.ts

@@ -0,0 +1,27 @@
+import type { ProjectType } from '@salesforce/b2c-tooling-sdk/discovery';
+/**
+ * Human-readable label for each detected workspace/project type, used in the
+ * docs tool descriptions so an agent can see what was auto-detected.
+ */
+export declare const PROJECT_TYPE_LABELS: Record<ProjectType, string>;
+/**
+ * Accepted values for the docs tools' `workspace` parameter. Mirrors the CLI
+ * `--workspace` vocabulary: `auto` uses the auto-detected workspace, `all`
+ * disables the preference, or name a concrete type.
+ */
+export declare const WORKSPACE_VALUES: readonly ["auto", "all", "cartridges", "sfra", "pwa-kit-v3", "storefront-next"];
+export type WorkspaceParam = (typeof WORKSPACE_VALUES)[number];
+/**
+ * Resolves the `workspace` tool parameter into the concrete project type(s) to
+ * pass to the SDK search, given what was auto-detected at server startup.
+ *
+ * - `all` → undefined (no workspace preference)
+ * - `auto` (or unset) → the detected workspace(s), if any
+ * - an explicit type → that type
+ */
+export declare function resolveWorkspace(param: undefined | WorkspaceParam, detected: readonly ProjectType[]): ProjectType[] | undefined;
+/**
+ * Builds a short sentence describing the detected workspace for a tool
+ * description, or an empty string when nothing was detected.
+ */
+export declare function detectedWorkspaceNote(detected: readonly ProjectType[]): string;

package/dist/tools/docs/storefront.js

@@ -0,0 +1,48 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+/**
+ * Human-readable label for each detected workspace/project type, used in the
+ * docs tool descriptions so an agent can see what was auto-detected.
+ */
+export const PROJECT_TYPE_LABELS = {
+    cartridges: 'Cartridges',
+    sfra: 'SFRA (cartridges)',
+    'pwa-kit-v3': 'PWA Kit (Composable Storefront)',
+    'storefront-next': 'Storefront Next',
+};
+/**
+ * Accepted values for the docs tools' `workspace` parameter. Mirrors the CLI
+ * `--workspace` vocabulary: `auto` uses the auto-detected workspace, `all`
+ * disables the preference, or name a concrete type.
+ */
+export const WORKSPACE_VALUES = ['auto', 'all', 'cartridges', 'sfra', 'pwa-kit-v3', 'storefront-next'];
+/**
+ * Resolves the `workspace` tool parameter into the concrete project type(s) to
+ * pass to the SDK search, given what was auto-detected at server startup.
+ *
+ * - `all` → undefined (no workspace preference)
+ * - `auto` (or unset) → the detected workspace(s), if any
+ * - an explicit type → that type
+ */
+export function resolveWorkspace(param, detected) {
+    if (param === 'all')
+        return undefined;
+    if (param && param !== 'auto')
+        return [param];
+    // 'auto' or unset: default to the detected workspace(s)
+    return detected.length > 0 ? [...detected] : undefined;
+}
+/**
+ * Builds a short sentence describing the detected workspace for a tool
+ * description, or an empty string when nothing was detected.
+ */
+export function detectedWorkspaceNote(detected) {
+    if (detected.length === 0)
+        return '';
+    const labels = detected.map((t) => PROJECT_TYPE_LABELS[t] ?? t).join(' + ');
+    return ` Detected workspace: ${labels} — by default results favor this workspace's docs (pass workspace="all" to disable).`;
+}
+//# sourceMappingURL=storefront.js.map

package/dist/tools/docs/topics.d.ts

@@ -0,0 +1,21 @@
+import { type DocCategory } from '@salesforce/b2c-tooling-sdk/docs';
+/**
+ * Helpers for the launch-time documentation "topics" allowlist (`--docs-topics`),
+ * shared across the docs search/list/read tools so the enabled-category boundary
+ * is described and enforced consistently.
+ */
+/**
+ * The category values a docs tool's `category` parameter should accept, given
+ * the optional launch-time allowlist. When an allowlist is configured the enum
+ * is narrowed to it (so the schema itself reflects what is reachable); otherwise
+ * every category is accepted.
+ *
+ * Always returns a non-empty tuple so `z.enum(...)` is happy — an allowlist that
+ * somehow filtered to nothing falls back to the full set.
+ */
+export declare function categoryEnumValues(enabledCategories?: readonly DocCategory[]): [DocCategory, ...DocCategory[]];
+/**
+ * A sentence for a tool description noting the corpus is restricted to the
+ * configured topics, or an empty string when there is no restriction.
+ */
+export declare function enabledCategoriesNote(enabledCategories?: readonly DocCategory[]): string;

package/dist/tools/docs/topics.js

@@ -0,0 +1,38 @@
+/*
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
+ */
+import { DOC_CATEGORIES } from '@salesforce/b2c-tooling-sdk/docs';
+/**
+ * Helpers for the launch-time documentation "topics" allowlist (`--docs-topics`),
+ * shared across the docs search/list/read tools so the enabled-category boundary
+ * is described and enforced consistently.
+ */
+/**
+ * The category values a docs tool's `category` parameter should accept, given
+ * the optional launch-time allowlist. When an allowlist is configured the enum
+ * is narrowed to it (so the schema itself reflects what is reachable); otherwise
+ * every category is accepted.
+ *
+ * Always returns a non-empty tuple so `z.enum(...)` is happy — an allowlist that
+ * somehow filtered to nothing falls back to the full set.
+ */
+export function categoryEnumValues(enabledCategories) {
+    const all = [...DOC_CATEGORIES];
+    if (!enabledCategories || enabledCategories.length === 0) {
+        return all;
+    }
+    const allowed = all.filter((c) => enabledCategories.includes(c));
+    return (allowed.length > 0 ? allowed : all);
+}
+/**
+ * A sentence for a tool description noting the corpus is restricted to the
+ * configured topics, or an empty string when there is no restriction.
+ */
+export function enabledCategoriesNote(enabledCategories) {
+    if (!enabledCategories || enabledCategories.length === 0)
+        return '';
+    return ` Documentation is restricted at startup to: ${enabledCategories.join(', ')}.`;
+}
+//# sourceMappingURL=topics.js.map

package/dist/utils/types.d.ts

@@ -42,4 +42,10 @@ export interface StartupFlags {
     configPath?: string;
     /** Project project directory for tools (auto-discovery, scaffolding, etc.) */
     projectDirectory?: string;
+    /**
+     * Comma-separated allowlist of documentation categories the docs tools may
+     * expose (from `--docs-topics` / `SFCC_DOCS_TOPICS`). Bounds the whole docs
+     * corpus at startup; unset means all categories.
+     */
+    docsTopics?: string;
 }

package/oclif.manifest.json

@@ -402,6 +402,14 @@
           "multiple": false,
           "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.",
+          "env": "SFCC_DOCS_TOPICS",
+          "name": "docs-topics",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "allow-non-ga-tools": {
           "description": "Enable non-GA (experimental) tools",
           "env": "SFCC_ALLOW_NON_GA_TOOLS",
@@ -420,5 +428,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "1.4.1"
+  "version": "1.5.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@salesforce/b2c-dx-mcp",
   "description": "MCP server for B2C Commerce developer experience tools",
-  "version": "1.4.1",
+  "version": "1.5.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.17.0"
+    "@salesforce/b2c-tooling-sdk": "1.18.0"
   },
   "devDependencies": {
     "@eslint/compat": "^1",
@@ -123,10 +123,10 @@
     "inspect": "mcp-inspector node bin/run.js --toolsets all --allow-non-ga-tools",
     "inspect:dev": "mcp-inspector node --conditions development bin/dev.js --toolsets all --allow-non-ga-tools",
     "pretest": "tsc --noEmit -p test",
-    "test": "c8 mocha --forbid-only --ignore 'test/e2e/**' \"test/**/*.test.ts\"",
-    "test:ci": "c8 mocha --forbid-only --reporter json --reporter-option output=test-results.json --ignore 'test/e2e/**' \"test/**/*.test.ts\"",
-    "test:ci:win": "c8 --check-coverage=false mocha --forbid-only --reporter json --reporter-option output=test-results.json --ignore 'test/e2e/**' \"test/**/*.test.ts\"",
-    "test:agent": "mocha --forbid-only --reporter min --ignore 'test/e2e/**' \"test/**/*.test.ts\"",
+    "test": "c8 mocha --forbid-only --ignore \"test/e2e/**\" \"test/**/*.test.ts\"",
+    "test:ci": "c8 mocha --forbid-only --reporter json --reporter-option output=test-results.json --ignore \"test/e2e/**\" \"test/**/*.test.ts\"",
+    "test:ci:win": "c8 --check-coverage=false mocha --forbid-only --reporter json --reporter-option output=test-results.json --ignore \"test/e2e/**\" \"test/**/*.test.ts\"",
+    "test:agent": "mocha --forbid-only --reporter min --ignore \"test/e2e/**\" \"test/**/*.test.ts\"",
     "test:e2e": "mocha --forbid-only \"test/e2e/**/*.test.ts\"",
     "test:e2e:ci": "mocha --forbid-only --reporter json --reporter-option output=test-results-e2e.json \"test/e2e/**/*.test.ts\"",
     "coverage": "c8 report",