@salesforce/b2c-dx-mcp 1.2.1 → 1.3.0

package/README.md

@@ -80,9 +80,12 @@ See the [Configuration Guide](https://salesforcecommercecloud.github.io/b2c-deve
 | 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 | `sfnext_get_guidelines`, `sfnext_add_page_designer_decorator`, `sfnext_configure_theme`, `sfnext_start_figma_workflow`, `sfnext_analyze_component`, `sfnext_match_tokens_to_theme` | [toolsets#storefrontnext](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/toolsets#storefrontnext) |
+| 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.
+
 ### cartridge_deploy
 
 Deploy cartridges to a B2C Commerce instance. [Details](https://salesforcecommercecloud.github.io/b2c-developer-tooling/mcp/tools/cartridge-deploy)
@@ -118,6 +121,10 @@ 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)

package/dist/registry.js

@@ -5,7 +5,7 @@
  */
 import { getLogger } from '@salesforce/b2c-tooling-sdk/logging';
 import { detectWorkspaceType } from '@salesforce/b2c-tooling-sdk/discovery';
-import { ALL_TOOLSETS, TOOLSETS, VALID_TOOLSET_NAMES } from './utils/index.js';
+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';
 import { createDocsTools } from './tools/docs/index.js';
@@ -27,6 +27,9 @@ const BASE_TOOLSETS = ['SCAPI', 'DIAGNOSTICS'];
 const PROJECT_TYPE_TOOLSETS = {
     cartridges: ['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'],
 };
 /**
@@ -75,6 +78,7 @@ export function createToolRegistry(loadServices, serverContext) {
         PWAV3: [],
         SCAPI: [],
         STOREFRONTNEXT: [],
+        STOREFRONTNEXT_DEPRECATED: [],
     };
     // Collect all tools from all factories
     const allTools = [
@@ -174,9 +178,12 @@ 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
+    // Determine which toolsets to enable.
+    // `ALL` expands to every toolset EXCEPT deprecated ones — deprecated toolsets
+    // must always be named explicitly.
     const validToolsets = toolsets.filter((t) => TOOLSETS.includes(t));
-    const toolsetsToEnable = new Set(toolsets.includes(ALL_TOOLSETS) ? TOOLSETS : validToolsets);
+    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,

package/dist/server-context.d.ts

@@ -1,4 +1,5 @@
 import { LogWatchRegistry } from './tools/diagnostics/log-watch-registry.js';
+import { MrtLogWatchRegistry } from './tools/diagnostics/mrt-log-watch-registry.js';
 import { DebugSessionRegistry } from './tools/diagnostics/session-registry.js';
 /**
  * Server-scoped persistent state that lives for the lifetime of the MCP
@@ -17,13 +18,15 @@ 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.
  *
- * Both registries dedup on a stable key (host:client_id for debug,
- * hostname for log watches), so multi-agent use is functional but agents
- * may see each other's sessions/watches via list tools.
+ * The registries dedup on a stable key (host:client_id for debug, 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.
  */
 export declare class ServerContext {
     readonly debugSessions: DebugSessionRegistry;
     readonly logWatches: LogWatchRegistry;
+    readonly mrtLogWatches: MrtLogWatchRegistry;
     constructor();
     destroyAll(): Promise<void>;
 }

package/dist/server-context.js

@@ -4,6 +4,7 @@
  * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
  */
 import { LogWatchRegistry } from './tools/diagnostics/log-watch-registry.js';
+import { MrtLogWatchRegistry } from './tools/diagnostics/mrt-log-watch-registry.js';
 import { DebugSessionRegistry } from './tools/diagnostics/session-registry.js';
 /**
  * Server-scoped persistent state that lives for the lifetime of the MCP
@@ -22,19 +23,26 @@ 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.
  *
- * Both registries dedup on a stable key (host:client_id for debug,
- * hostname for log watches), so multi-agent use is functional but agents
- * may see each other's sessions/watches via list tools.
+ * The registries dedup on a stable key (host:client_id for debug, 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.
  */
 export class ServerContext {
     debugSessions;
     logWatches;
+    mrtLogWatches;
     constructor() {
         this.debugSessions = new DebugSessionRegistry();
         this.logWatches = new LogWatchRegistry();
+        this.mrtLogWatches = new MrtLogWatchRegistry();
     }
     async destroyAll() {
-        await Promise.allSettled([this.debugSessions.destroyAll(), this.logWatches.destroyAll()]);
+        await Promise.allSettled([
+            this.debugSessions.destroyAll(),
+            this.logWatches.destroyAll(),
+            this.mrtLogWatches.destroyAll(),
+        ]);
     }
 }
 //# sourceMappingURL=server-context.js.map

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

@@ -4,6 +4,7 @@ import type { ServerContext } from '../../server-context.js';
 import { type LogsListFilesInjections } from './logs-list-files.js';
 import { type LogsGetRecentInjections } from './logs-get-recent.js';
 import { type LogsWatchStartInjections } from './logs-watch-start.js';
-export interface DiagnosticsToolInjections extends LogsGetRecentInjections, LogsListFilesInjections, LogsWatchStartInjections {
+import { type MrtLogsWatchStartInjections } from './mrt-logs-watch-start.js';
+export interface DiagnosticsToolInjections extends LogsGetRecentInjections, LogsListFilesInjections, LogsWatchStartInjections, MrtLogsWatchStartInjections {
 }
 export declare function createDiagnosticsTools(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext, injections?: DiagnosticsToolInjections): McpTool[];

package/dist/tools/diagnostics/index.js

@@ -20,6 +20,10 @@ import { createLogsWatchStartTool } from './logs-watch-start.js';
 import { createLogsWatchPollTool } from './logs-watch-poll.js';
 import { createLogsWatchStopTool } from './logs-watch-stop.js';
 import { createLogsWatchListTool } from './logs-watch-list.js';
+import { createMrtLogsWatchStartTool } from './mrt-logs-watch-start.js';
+import { createMrtLogsWatchPollTool } from './mrt-logs-watch-poll.js';
+import { createMrtLogsWatchStopTool } from './mrt-logs-watch-stop.js';
+import { createMrtLogsWatchListTool } from './mrt-logs-watch-list.js';
 export function createDiagnosticsTools(loadServices, serverContext, injections) {
     return [
         createDebugListSessionsTool(loadServices, serverContext),
@@ -39,6 +43,10 @@ export function createDiagnosticsTools(loadServices, serverContext, injections)
         createLogsWatchPollTool(loadServices, serverContext),
         createLogsWatchStopTool(loadServices, serverContext),
         createLogsWatchListTool(loadServices, serverContext),
+        createMrtLogsWatchStartTool(loadServices, serverContext, injections),
+        createMrtLogsWatchPollTool(loadServices, serverContext),
+        createMrtLogsWatchStopTool(loadServices, serverContext),
+        createMrtLogsWatchListTool(loadServices, serverContext),
     ];
 }
 //# sourceMappingURL=index.js.map

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

@@ -0,0 +1,115 @@
+import type { MrtLogEntry, TailMrtLogsResult } from '@salesforce/b2c-tooling-sdk/operations/mrt';
+import type { ToolExecutionContext } from '../adapter.js';
+/** Maximum number of buffered entries before oldest are evicted. */
+export declare const DEFAULT_BUFFER_CAP = 5000;
+/**
+ * Maximum cumulative bytes buffered before oldest entries are evicted.
+ * Guards against a small number of pathologically large entries (e.g. multi-MB
+ * stack traces) blowing past the count cap's intended memory bound.
+ */
+export declare const DEFAULT_BUFFER_BYTES_CAP: number;
+export interface PollWaiter {
+    resolve: () => void;
+    timer: ReturnType<typeof setTimeout>;
+}
+export interface MrtLogWatchEntry {
+    watchId: string;
+    /** MRT project slug being tailed. */
+    project: string;
+    /** MRT environment slug being tailed. */
+    environment: string;
+    /** MRT API origin URL (used for the logs WebSocket host). */
+    origin?: string;
+    buffer: MrtLogEntry[];
+    /** Running byte size of `buffer` (raw + message), used for the byte cap. */
+    bufferBytes: number;
+    errors: Array<{
+        message: string;
+        at: string;
+    }>;
+    totalEntriesSeen: number;
+    droppedEntries: number;
+    bufferCap: number;
+    bufferBytesCap: number;
+    stop: () => void;
+    done: Promise<void>;
+    pollWaiters: PollWaiter[];
+    createdAt: number;
+    lastActivityAt: number;
+    /**
+     * True once the underlying WebSocket has closed — either via stop() or
+     * because the server closed/failed the connection on its own. A stopped
+     * watch keeps its buffered entries until drained or idle-reaped.
+     */
+    stopped: boolean;
+}
+export interface RegisterMrtWatchOptions {
+    project: string;
+    environment: string;
+    origin?: string;
+    tailResult: TailMrtLogsResult;
+    bufferCap?: number;
+    bufferBytesCap?: number;
+}
+/**
+ * Stable dedup key for an MRT log watch. A developer may tail several
+ * (project, environment, origin) tuples concurrently — unlike the SFCC log
+ * watch which keys on hostname — so all three components form the key. A space
+ * separator is safe since project/environment slugs are URL-safe (no spaces).
+ */
+export declare function mrtWatchKey(project: string, environment: string, origin?: string): string;
+/**
+ * In-memory registry of background MRT log-tail streams.
+ *
+ * Mirrors `LogWatchRegistry` (SFCC instance logs) but adapted for the MRT
+ * logging WebSocket: there are no log files, prefixes, or rotations — just a
+ * single live stream per (project, environment, origin). The stream can also
+ * close on its own (idle timeout, auth expiry, server restart), which is
+ * recorded as `stopped: true` plus a buffered error so a poll can surface it.
+ */
+export declare class MrtLogWatchRegistry {
+    private cleanupTimer;
+    private readonly watches;
+    constructor();
+    /**
+     * Append a log entry to a watch buffer. Evicts oldest if over cap.
+     * Resolves any pending poll waiters.
+     */
+    appendEntry(watchId: string, entry: MrtLogEntry): void;
+    appendError(watchId: string, err: Error): void;
+    destroyAll(): Promise<void>;
+    destroyWatch(watchId: string): Promise<void>;
+    /**
+     * Drain buffered entries (up to maxEntries) and any error events from the
+     * watch. Removes drained items from the underlying buffers.
+     */
+    drain(watchId: string, maxEntries: number): {
+        entries: MrtLogEntry[];
+        errors: Array<{
+            message: string;
+            at: string;
+        }>;
+        truncated: boolean;
+    };
+    findByKey(project: string, environment: string, origin?: string): MrtLogWatchEntry | undefined;
+    getWatch(watchId: string): MrtLogWatchEntry | undefined;
+    getWatchOrThrow(watchId: string): MrtLogWatchEntry;
+    listWatches(): MrtLogWatchEntry[];
+    /**
+     * Mark a watch's stream as closed (the WebSocket ended on its own or via
+     * stop). Keeps the entry so buffered entries can still be drained and the
+     * `stopped` flag is observable on the next poll; idle cleanup removes it
+     * later. Resolves any blocked pollers so they return promptly.
+     */
+    markStreamClosed(watchId: string): void;
+    registerWatch(opts: RegisterMrtWatchOptions): MrtLogWatchEntry;
+    /**
+     * Wait until at least one entry is buffered (or an error event arrives, or
+     * the stream stops), or until timeout elapses. Returns immediately if there
+     * is already activity to report.
+     */
+    waitForActivity(watchId: string, timeoutMs: number): Promise<void>;
+    private cleanupIdleWatches;
+    private flushWaiters;
+}
+export declare function getMrtLogWatchRegistry(context: ToolExecutionContext): MrtLogWatchRegistry;

package/dist/tools/diagnostics/mrt-logs-watch-list.d.ts

@@ -0,0 +1,4 @@
+import type { McpTool } from '../../utils/index.js';
+import type { Services } from '../../services.js';
+import type { ServerContext } from '../../server-context.js';
+export declare function createMrtLogsWatchListTool(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext): McpTool;

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

@@ -0,0 +1,36 @@
+/*
+ * 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 { createToolAdapter, jsonResult } from '../adapter.js';
+import { getMrtLogWatchRegistry } from './mrt-log-watch-registry.js';
+export function createMrtLogsWatchListTool(loadServices, serverContext) {
+    return createToolAdapter({
+        name: 'mrt_logs_watch_list',
+        description: 'List all active MRT log watches with their status. Use this to find an orphaned watch_id (e.g., after a ' +
+            'crashed agent run) so you can resume polling or stop it.',
+        toolsets: ['DIAGNOSTICS', 'PWAV3', 'STOREFRONTNEXT'],
+        inputSchema: {},
+        async execute(_args, context) {
+            const registry = getMrtLogWatchRegistry(context);
+            const entries = registry.listWatches();
+            return {
+                watches: entries.map((w) => ({
+                    buffered_entries: w.buffer.length,
+                    created_at: new Date(w.createdAt).toISOString(),
+                    dropped_entries: w.droppedEntries,
+                    environment: w.environment,
+                    last_activity_at: new Date(w.lastActivityAt).toISOString(),
+                    origin: w.origin,
+                    project: w.project,
+                    stopped: w.stopped,
+                    total_entries_seen: w.totalEntriesSeen,
+                    watch_id: w.watchId,
+                })),
+            };
+        },
+        formatOutput: (output) => jsonResult(output),
+    }, loadServices, serverContext);
+}
+//# sourceMappingURL=mrt-logs-watch-list.js.map

package/dist/tools/diagnostics/mrt-logs-watch-poll.d.ts

@@ -0,0 +1,4 @@
+import type { McpTool } from '../../utils/index.js';
+import type { Services } from '../../services.js';
+import type { ServerContext } from '../../server-context.js';
+export declare function createMrtLogsWatchPollTool(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext): McpTool;

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

@@ -0,0 +1,59 @@
+/*
+ * 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 { z } from 'zod';
+import { createToolAdapter, jsonResult } from '../adapter.js';
+import { getMrtLogWatchRegistry } from './mrt-log-watch-registry.js';
+const DEFAULT_TIMEOUT_MS = 5000;
+const DEFAULT_MAX_ENTRIES = 200;
+export function createMrtLogsWatchPollTool(loadServices, serverContext) {
+    return createToolAdapter({
+        name: 'mrt_logs_watch_poll',
+        description: 'Drain buffered entries from an MRT log watch. If the buffer is empty, blocks up to timeout_ms waiting for ' +
+            'new entries. Returns immediately if entries are already buffered or the stream has stopped. Set ' +
+            'truncated=true if there are more entries beyond max_entries — call again to get the rest. When ' +
+            'stopped=true the underlying WebSocket has closed (stopped, idle-timed-out, or connection lost); check ' +
+            'errors for the reason.',
+        toolsets: ['DIAGNOSTICS', 'PWAV3', 'STOREFRONTNEXT'],
+        inputSchema: {
+            watch_id: z.string().describe('Watch id from mrt_logs_watch_start.'),
+            timeout_ms: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe('Max time to block waiting for new entries when buffer is empty. Defaults to 5000ms.'),
+            max_entries: z
+                .number()
+                .int()
+                .positive()
+                .optional()
+                .describe('Maximum entries to return per call. Defaults to 200.'),
+        },
+        async execute(args, context) {
+            const registry = getMrtLogWatchRegistry(context);
+            const watch = registry.getWatchOrThrow(args.watch_id);
+            const timeoutMs = args.timeout_ms ?? DEFAULT_TIMEOUT_MS;
+            const maxEntries = args.max_entries ?? DEFAULT_MAX_ENTRIES;
+            if (watch.buffer.length === 0 && watch.errors.length === 0 && !watch.stopped && timeoutMs > 0) {
+                await registry.waitForActivity(args.watch_id, timeoutMs);
+            }
+            const drained = registry.drain(args.watch_id, maxEntries);
+            const droppedSnapshot = watch.droppedEntries;
+            watch.droppedEntries = 0;
+            return {
+                buffered_remaining: watch.buffer.length,
+                dropped_entries: droppedSnapshot,
+                entries: drained.entries,
+                errors: drained.errors,
+                stopped: watch.stopped,
+                truncated: drained.truncated,
+                watch_id: args.watch_id,
+            };
+        },
+        formatOutput: (output) => jsonResult(output),
+    }, loadServices, serverContext);
+}
+//# sourceMappingURL=mrt-logs-watch-poll.js.map

package/dist/tools/diagnostics/mrt-logs-watch-start.d.ts

@@ -0,0 +1,14 @@
+import type { TailMrtLogsOptions, TailMrtLogsResult } from '@salesforce/b2c-tooling-sdk/operations/mrt';
+import type { AuthStrategy } from '@salesforce/b2c-tooling-sdk/auth';
+import type { McpTool } from '../../utils/index.js';
+import type { Services } from '../../services.js';
+import type { ServerContext } from '../../server-context.js';
+export interface MrtLogsWatchStartInjections {
+    tailMrtLogs?: (options: TailMrtLogsOptions, auth: AuthStrategy) => Promise<TailMrtLogsResult>;
+    getProfile?: (options: {
+        origin?: string;
+    }, auth: AuthStrategy) => Promise<{
+        email?: string;
+    }>;
+}
+export declare function createMrtLogsWatchStartTool(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext, injections?: MrtLogsWatchStartInjections): McpTool;

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

@@ -0,0 +1,133 @@
+/*
+ * 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 { z } from 'zod';
+import { getProfile, tailMrtLogs } from '@salesforce/b2c-tooling-sdk/operations/mrt';
+import { createToolAdapter, jsonResult } from '../adapter.js';
+import { getMrtLogWatchRegistry } from './mrt-log-watch-registry.js';
+/**
+ * Case-insensitive substring match against an entry's message and raw text.
+ * Mirrors the SFCC `matchesSearch` semantics. The CLI `mrt tail-logs` command
+ * treats `search` as a regex, but MCP tool consumers get the safer substring
+ * filter (no ReDoS surface, predictable behavior).
+ */
+function matchesSearch(entry, search) {
+    const lower = search.toLowerCase();
+    return entry.message.toLowerCase().includes(lower) || entry.raw.toLowerCase().includes(lower);
+}
+function matchesLevel(entry, levels) {
+    return Boolean(entry.level && levels.has(entry.level.toUpperCase()));
+}
+export function createMrtLogsWatchStartTool(loadServices, serverContext, injections) {
+    const tailMrtLogsFn = injections?.tailMrtLogs ?? tailMrtLogs;
+    const getProfileFn = injections?.getProfile ?? getProfile;
+    return createToolAdapter({
+        name: 'mrt_logs_watch_start',
+        description: "Start a background tail of a Managed Runtime (MRT) environment's application logs over a WebSocket. " +
+            'Returns a watch_id immediately. MRT logs are always a live stream — there is no historical fetch — so ' +
+            'call mrt_logs_watch_start BEFORE triggering the request/SSR action you want to capture, then call ' +
+            'mrt_logs_watch_poll to drain buffered entries (it blocks up to timeout_ms). Always call ' +
+            'mrt_logs_watch_stop when done. Requires MRT project + environment (from --project/--environment flags, ' +
+            'MRT_PROJECT/MRT_ENVIRONMENT env vars, or dw.json). Only one active watch per project/environment/origin ' +
+            '— use mrt_logs_watch_list to find an existing one.',
+        toolsets: ['DIAGNOSTICS', 'PWAV3', 'STOREFRONTNEXT'],
+        requiresMrtAuth: true,
+        inputSchema: {
+            level: z
+                .array(z.string())
+                .optional()
+                .describe('Filter by log level (ERROR, WARN, INFO, DEBUG, etc.). Entries not matching are dropped before buffering.'),
+            search: z
+                .string()
+                .optional()
+                .describe('Case-insensitive substring filter applied to message and raw text as entries arrive.'),
+        },
+        async execute(args, context) {
+            const registry = getMrtLogWatchRegistry(context);
+            const project = context.mrtConfig?.project;
+            const environment = context.mrtConfig?.environment;
+            const origin = context.mrtConfig?.origin;
+            const auth = context.mrtConfig.auth;
+            if (!project) {
+                throw new Error('MRT project is required. Provide --project flag, set MRT_PROJECT, or set mrtProject in dw.json.');
+            }
+            if (!environment) {
+                throw new Error('MRT environment is required. Provide --environment flag, set MRT_ENVIRONMENT, or set mrtEnvironment in dw.json.');
+            }
+            // Fail fast on a duplicate before opening a WebSocket.
+            const existing = registry.findByKey(project, environment, origin);
+            if (existing) {
+                throw new Error(`An MRT log watch already exists for ${project}/${environment} (watch_id: "${existing.watchId}"). ` +
+                    `Stop it with mrt_logs_watch_stop first, or poll the existing watch.`);
+            }
+            const levelFilter = args.level && args.level.length > 0 ? new Set(args.level.map((l) => l.toUpperCase())) : null;
+            const searchFilter = args.search;
+            // Best-effort user email for the WebSocket connection (matches the CLI).
+            let user;
+            try {
+                const profile = await getProfileFn({ origin }, auth);
+                user = profile.email;
+            }
+            catch {
+                // Non-fatal: proceed without user email.
+            }
+            // The callbacks need the watchId, but it is only minted by registerWatch
+            // (which itself needs the tailResult). Close over a mutable holder filled
+            // in after registration.
+            const ref = {};
+            const tailResult = await tailMrtLogsFn({
+                projectSlug: project,
+                environmentSlug: environment,
+                origin,
+                user,
+                onEntry(entry) {
+                    if (!ref.id)
+                        return;
+                    if (levelFilter && !matchesLevel(entry, levelFilter))
+                        return;
+                    if (searchFilter && !matchesSearch(entry, searchFilter))
+                        return;
+                    registry.appendEntry(ref.id, entry);
+                },
+                onError(err) {
+                    if (!ref.id)
+                        return;
+                    registry.appendError(ref.id, err);
+                },
+                onClose() {
+                    if (!ref.id)
+                        return;
+                    registry.markStreamClosed(ref.id);
+                },
+            }, auth);
+            // tailMrtLogs rejects `done` on a non-clean WebSocket close. Attach a
+            // no-op catch up front so neither the registration-failure path below
+            // nor a later connection drop produces an unhandled rejection.
+            // destroyWatch awaits the same promise for real cleanup.
+            tailResult.done.catch(() => { });
+            // registerWatch re-checks the dedup key and throws on a duplicate. If two
+            // starts race past findByKey above, the loser's WebSocket is already open
+            // — stop it so it isn't orphaned (it would otherwise stream until process
+            // exit).
+            let entry;
+            try {
+                entry = registry.registerWatch({ project, environment, origin, tailResult });
+            }
+            catch (error) {
+                tailResult.stop();
+                throw error;
+            }
+            ref.id = entry.watchId;
+            return {
+                environment,
+                project,
+                started_at: new Date(entry.createdAt).toISOString(),
+                watch_id: entry.watchId,
+            };
+        },
+        formatOutput: (output) => jsonResult(output),
+    }, loadServices, serverContext);
+}
+//# sourceMappingURL=mrt-logs-watch-start.js.map

package/dist/tools/diagnostics/mrt-logs-watch-stop.d.ts

@@ -0,0 +1,4 @@
+import type { McpTool } from '../../utils/index.js';
+import type { Services } from '../../services.js';
+import type { ServerContext } from '../../server-context.js';
+export declare function createMrtLogsWatchStopTool(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext): McpTool;

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

@@ -0,0 +1,37 @@
+/*
+ * 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 { z } from 'zod';
+import { createToolAdapter, jsonResult } from '../adapter.js';
+import { getMrtLogWatchRegistry } from './mrt-log-watch-registry.js';
+export function createMrtLogsWatchStopTool(loadServices, serverContext) {
+    return createToolAdapter({
+        name: 'mrt_logs_watch_stop',
+        description: 'Stop an MRT log watch and close its WebSocket. Idempotent on already-stopped watches (returns success ' +
+            'with stopped_at). Always pair with mrt_logs_watch_start so streaming connections do not accumulate on ' +
+            'the server.',
+        toolsets: ['DIAGNOSTICS', 'PWAV3', 'STOREFRONTNEXT'],
+        inputSchema: {
+            watch_id: z.string().describe('Watch id from mrt_logs_watch_start.'),
+        },
+        async execute(args, context) {
+            const registry = getMrtLogWatchRegistry(context);
+            // Idempotent: a watch that was already stopped (and removed) returns a
+            // success response rather than throwing, so retry/cleanup paths are safe.
+            const watch = registry.getWatch(args.watch_id);
+            const totalSeen = watch?.totalEntriesSeen ?? 0;
+            if (watch) {
+                await registry.destroyWatch(args.watch_id);
+            }
+            return {
+                stopped_at: new Date().toISOString(),
+                total_entries_seen: totalSeen,
+                watch_id: args.watch_id,
+            };
+        },
+        formatOutput: (output) => jsonResult(output),
+    }, loadServices, serverContext);
+}
+//# sourceMappingURL=mrt-logs-watch-stop.js.map

package/dist/tools/storefrontnext/figma/figma-to-component/index.js

@@ -305,14 +305,15 @@ export function generateWorkflowResponse(figmaUrl, workflowFilePath) {
 export function createFigmaToComponentTool(loadServices) {
     return createToolAdapter({
         name: 'sfnext_start_figma_workflow',
-        description: 'WORKFLOW ORCHESTRATOR: Call this tool FIRST when converting Figma designs. ' +
+        description: '[DEPRECATED] Superseded by the storefront-next and storefront-next-figma agent-skills plugins and NOT compatible with the Storefront Next 1.0 GA release. Will be removed in a future release. ' +
+            'WORKFLOW ORCHESTRATOR: Call this tool FIRST when converting Figma designs. ' +
             'Parses Figma URL to extract fileKey and nodeId, returns step-by-step workflow instructions ' +
             'and parameters for subsequent tool calls. ' +
             'CRITICAL: This is only the FIRST step. After calling this tool, you MUST continue executing ' +
             'the complete workflow: 1) Call Figma MCP tools, 2) Discover similar components, ' +
             '3) Call sfnext_analyze_component tool, 4) Call sfnext_match_tokens_to_theme tool, ' +
             '5) Show both outputs to the user then implement the recommended approach.',
-        toolsets: ['STOREFRONTNEXT'],
+        toolsets: ['STOREFRONTNEXT_DEPRECATED'],
         isGA: false,
         requiresInstance: false,
         inputSchema: figmaToComponentSchema.shape,

package/dist/tools/storefrontnext/figma/generate-component/index.js

@@ -76,13 +76,14 @@ export function generateComponentRecommendation(input) {
 export function createGenerateComponentTool(loadServices) {
     return createToolAdapter({
         name: 'sfnext_analyze_component',
-        description: 'Analyzes Figma design and discovered components to recommend component generation strategy. ' +
+        description: '[DEPRECATED] Superseded by the storefront-next and storefront-next-figma agent-skills plugins and NOT compatible with the Storefront Next 1.0 GA release. Will be removed in a future release. ' +
+            'Analyzes Figma design and discovered components to recommend component generation strategy. ' +
             'Workflow: 1) Discover similar components using Glob/Grep/Read tools, ' +
             '2) Call this tool with the discoveredComponents parameter, ' +
             '3) Tool analyzes differences and recommends REUSE/EXTEND/CREATE action, ' +
             '4) Tool provides formatted recommendation with code examples and workflow steps. ' +
             'Call this tool AFTER retrieving Figma design data and discovering similar components.',
-        toolsets: ['STOREFRONTNEXT'],
+        toolsets: ['STOREFRONTNEXT_DEPRECATED'],
         isGA: false,
         requiresInstance: false,
         inputSchema: generateComponentSchema.shape,

package/dist/tools/storefrontnext/figma/map-tokens/index.js

@@ -216,12 +216,13 @@ export function mapFigmaTokensToTheme(args, workspaceRoot) {
 export function createMapTokensToThemeTool(loadServices) {
     return createToolAdapter({
         name: 'sfnext_match_tokens_to_theme',
-        description: 'Maps Figma design tokens to existing StorefrontNext theme tokens in app.css. ' +
+        description: '[DEPRECATED] Superseded by the storefront-next and storefront-next-figma agent-skills plugins and NOT compatible with the Storefront Next 1.0 GA release. Will be removed in a future release. ' +
+            'Maps Figma design tokens to existing StorefrontNext theme tokens in app.css. ' +
             'Analyzes Figma design tokens (colors, spacing, radius, etc.) and finds exact matches, ' +
             'provides fuzzy matches with confidence scores, suggests new token names for unmatched values, ' +
             'and recommends where to add new tokens in the CSS file. ' +
             'Use this tool after retrieving design variables from Figma MCP to ensure components use theme tokens instead of hardcoded values.',
-        toolsets: ['STOREFRONTNEXT'],
+        toolsets: ['STOREFRONTNEXT_DEPRECATED'],
         isGA: false,
         requiresInstance: false,
         inputSchema: mapTokensToThemeSchema.shape,

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

@@ -1,7 +1,13 @@
 /**
- * Storefront Next toolset for B2C Commerce.
+ * Storefront Next (deprecated) toolset for B2C Commerce.
  *
- * This toolset provides MCP tools for Storefront Next development.
+ * **DEPRECATED:** These `sfnext_*` tools are superseded by the `storefront-next`
+ * and `storefront-next-figma` agent-skills plugins and are NOT compatible with
+ * the Storefront Next 1.0 GA release. They now live in the
+ * `STOREFRONTNEXT_DEPRECATED` toolset, which is never auto-activated by project
+ * detection and is excluded from `--toolsets ALL`. To use them you must request
+ * the toolset explicitly (`--toolsets STOREFRONTNEXT_DEPRECATED`). They will be
+ * removed in a future release.
  *
  * **Implemented Tools:**
  * - `sfnext_get_guidelines` - Get development guidelines and best practices
@@ -11,18 +17,12 @@
  * - `sfnext_analyze_component` - Analyze design and recommend REUSE/EXTEND/CREATE
  * - `sfnext_match_tokens_to_theme` - Match design tokens to theme
  *
- * Note: mrt_bundle_push is defined in the MRT toolset and appears in STOREFRONTNEXT.
- *
  * @module tools/storefrontnext
  */
 import type { McpTool } from '../../utils/index.js';
 import type { Services } from '../../services.js';
 /**
- * Creates all tools for the STOREFRONTNEXT toolset.
- *
- * Note: mrt_bundle_push is defined in the MRT toolset with
- * toolsets: ["MRT", "PWAV3", "STOREFRONTNEXT"] and will
- * automatically appear in STOREFRONTNEXT.
+ * Creates all tools for the deprecated STOREFRONTNEXT_DEPRECATED toolset.
  *
  * @param loadServices - Function that loads configuration and returns Services instance
  * @returns Array of MCP tools

package/dist/tools/storefrontnext/index.js

@@ -10,11 +10,7 @@ import { createFigmaToComponentTool } from './figma/figma-to-component/index.js'
 import { createGenerateComponentTool } from './figma/generate-component/index.js';
 import { createMapTokensToThemeTool } from './figma/map-tokens/index.js';
 /**
- * Creates all tools for the STOREFRONTNEXT toolset.
- *
- * Note: mrt_bundle_push is defined in the MRT toolset with
- * toolsets: ["MRT", "PWAV3", "STOREFRONTNEXT"] and will
- * automatically appear in STOREFRONTNEXT.
+ * Creates all tools for the deprecated STOREFRONTNEXT_DEPRECATED toolset.
  *
  * @param loadServices - Function that loads configuration and returns Services instance
  * @returns Array of MCP tools

package/dist/tools/storefrontnext/page-designer-decorator/index.js

@@ -528,13 +528,14 @@ function handleAutoMode(args, workspaceRoot) {
 export function createPageDesignerDecoratorTool(loadServices) {
     return {
         name: 'sfnext_add_page_designer_decorator',
-        description: 'Adds Page Designer decorators (@Component, @AttributeDefinition, @RegionDefinition) to React components. ' +
+        description: '[DEPRECATED] Superseded by the storefront-next and storefront-next-figma agent-skills plugins and NOT compatible with the Storefront Next 1.0 GA release. Will be removed in a future release. ' +
+            'Adds Page Designer decorators (@Component, @AttributeDefinition, @RegionDefinition) to React components. ' +
             'Two modes: autoMode=true for quick setup with defaults, or interactive mode via conversationContext.step. ' +
             'Component discovery uses --project-directory flag or SFCC_PROJECT_DIRECTORY env var. ' +
             'Auto mode: selects suitable props, infers types, generates code immediately. ' +
             'Interactive mode: multi-step workflow (analyze → select_props → configure_attrs → configure_regions → confirm_generation).',
         inputSchema: pageDesignerDecoratorSchema.shape,
-        toolsets: ['STOREFRONTNEXT'],
+        toolsets: ['STOREFRONTNEXT_DEPRECATED'],
         isGA: false,
         async handler(args) {
             try {

package/dist/tools/storefrontnext/sfnext-development-guidelines.js

@@ -83,13 +83,14 @@ const DEFAULT_SECTIONS = ['quick-reference', 'data-fetching', 'components', 'tes
 export function createDeveloperGuidelinesTool(loadServices) {
     return createToolAdapter({
         name: 'sfnext_get_guidelines',
-        description: 'ESSENTIAL FIRST STEP for Storefront Next development. Returns critical architecture rules, coding standards, and best practices. ' +
+        description: '[DEPRECATED] Superseded by the storefront-next and storefront-next-figma agent-skills plugins and NOT compatible with the Storefront Next 1.0 GA release. Will be removed in a future release. ' +
+            'ESSENTIAL FIRST STEP for Storefront Next development. Returns critical architecture rules, coding standards, and best practices. ' +
             'Use this tool FIRST before writing any Storefront Next code to understand non-negotiable patterns for React Server Components, ' +
             'data loading, and framework constraints. Returns comprehensive guidelines by default (quick-reference + key sections); ' +
             'supports retrieving specific topic sections. ' +
             'CRITICAL INSTRUCTION: ALWAYS present ALL returned content in FULL - DO NOT SUMMARIZE, DO NOT ADD SUMMARIES, ' +
             'DO NOT ADD OVERVIEWS. The returned content IS the complete answer - display it exactly as provided.',
-        toolsets: ['STOREFRONTNEXT'],
+        toolsets: ['STOREFRONTNEXT_DEPRECATED'],
         isGA: false,
         requiresInstance: false,
         inputSchema: {

package/dist/tools/storefrontnext/site-theming/index.js

@@ -29,7 +29,8 @@ import { generateResponse } from './response-builder.js';
 export function createSiteThemingTool(loadServices) {
     return createToolAdapter({
         name: 'sfnext_configure_theme',
-        description: '⚠️ MANDATORY: Call this tool FIRST before implementing any theming changes. ' +
+        description: '[DEPRECATED] Superseded by the storefront-next and storefront-next-figma agent-skills plugins and NOT compatible with the Storefront Next 1.0 GA release. Will be removed in a future release. ' +
+            '⚠️ MANDATORY: Call this tool FIRST before implementing any theming changes. ' +
             'Provides theming guidelines, questions, and automatic validation. ' +
             'CRITICAL RULES: Call immediately when user requests theming (even if colors/fonts provided). ' +
             'NEVER implement without calling this tool first. NEVER skip question-answer workflow. ' +
@@ -38,7 +39,7 @@ export function createSiteThemingTool(loadServices) {
             'DEFAULT FILES: theming-questions, theming-validation, theming-accessibility. ' +
             'Use fileKeys to add custom files. ' +
             'WORKFLOW: Call tool → Ask questions → Call with colorMapping (validation) → Present findings → Wait confirmation → Implement',
-        toolsets: ['STOREFRONTNEXT'],
+        toolsets: ['STOREFRONTNEXT_DEPRECATED'],
         isGA: false,
         requiresInstance: false,
         inputSchema: {

package/dist/utils/constants.d.ts

@@ -5,11 +5,22 @@ export declare const ALL_TOOLSETS = "ALL";
 /**
  * Available toolsets that can be enabled.
  */
-export declare const TOOLSETS: readonly ["CARTRIDGES", "DIAGNOSTICS", "MRT", "PWAV3", "SCAPI", "STOREFRONTNEXT"];
+export declare const TOOLSETS: readonly ["CARTRIDGES", "DIAGNOSTICS", "MRT", "PWAV3", "SCAPI", "STOREFRONTNEXT", "STOREFRONTNEXT_DEPRECATED"];
+/**
+ * Deprecated toolsets. These can only be enabled by explicitly naming them via
+ * `--toolsets`; they are never auto-activated by project detection and are NOT
+ * included when `--toolsets ALL` is used.
+ *
+ * `STOREFRONTNEXT_DEPRECATED` holds the legacy `sfnext_*` MCP tools. They are
+ * superseded by the `storefront-next` and `storefront-next-figma` agent-skills
+ * plugins and are not compatible with the Storefront Next 1.0 GA release. They
+ * will be removed in a future release.
+ */
+export declare const DEPRECATED_TOOLSETS: readonly ["STOREFRONTNEXT_DEPRECATED"];
 /**
  * Valid toolset names including the special "ALL" value.
  */
-export declare const VALID_TOOLSET_NAMES: readonly ["ALL", "CARTRIDGES", "DIAGNOSTICS", "MRT", "PWAV3", "SCAPI", "STOREFRONTNEXT"];
+export declare const VALID_TOOLSET_NAMES: readonly ["ALL", "CARTRIDGES", "DIAGNOSTICS", "MRT", "PWAV3", "SCAPI", "STOREFRONTNEXT", "STOREFRONTNEXT_DEPRECATED"];
 /**
  * Type representing a valid toolset name.
  */

package/dist/utils/constants.js

@@ -10,7 +10,26 @@ export const ALL_TOOLSETS = 'ALL';
 /**
  * Available toolsets that can be enabled.
  */
-export const TOOLSETS = ['CARTRIDGES', 'DIAGNOSTICS', 'MRT', 'PWAV3', 'SCAPI', 'STOREFRONTNEXT'];
+export const TOOLSETS = [
+    'CARTRIDGES',
+    'DIAGNOSTICS',
+    'MRT',
+    'PWAV3',
+    'SCAPI',
+    'STOREFRONTNEXT',
+    'STOREFRONTNEXT_DEPRECATED',
+];
+/**
+ * Deprecated toolsets. These can only be enabled by explicitly naming them via
+ * `--toolsets`; they are never auto-activated by project detection and are NOT
+ * included when `--toolsets ALL` is used.
+ *
+ * `STOREFRONTNEXT_DEPRECATED` holds the legacy `sfnext_*` MCP tools. They are
+ * superseded by the `storefront-next` and `storefront-next-figma` agent-skills
+ * plugins and are not compatible with the Storefront Next 1.0 GA release. They
+ * will be removed in a future release.
+ */
+export const DEPRECATED_TOOLSETS = ['STOREFRONTNEXT_DEPRECATED'];
 /**
  * Valid toolset names including the special "ALL" value.
  */

package/oclif.manifest.json

@@ -387,7 +387,7 @@
           "type": "boolean"
         },
         "toolsets": {
-          "description": "Toolsets to enable (comma-separated). Options: all, CARTRIDGES, DIAGNOSTICS, MRT, PWAV3, SCAPI, STOREFRONTNEXT",
+          "description": "Toolsets to enable (comma-separated). Options: all, CARTRIDGES, DIAGNOSTICS, MRT, PWAV3, SCAPI, STOREFRONTNEXT, STOREFRONTNEXT_DEPRECATED",
           "env": "SFCC_TOOLSETS",
           "name": "toolsets",
           "hasDynamicHelp": false,
@@ -420,5 +420,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "1.2.1"
+  "version": "1.3.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@salesforce/b2c-dx-mcp",
   "description": "MCP server for B2C Commerce developer experience tools",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "author": "Salesforce",
   "license": "Apache-2.0",
   "repository": "SalesforceCommerceCloud/b2c-developer-tooling",
@@ -80,7 +80,7 @@
     "yaml": "2.8.1",
     "postcss": "8.5.6",
     "zod": "3.25.76",
-    "@salesforce/b2c-tooling-sdk": "1.13.0"
+    "@salesforce/b2c-tooling-sdk": "1.14.0"
   },
   "devDependencies": {
     "@eslint/compat": "^1",
@@ -99,7 +99,7 @@
     "eslint-config-prettier": "^10",
     "eslint-plugin-header": "^3.1.1",
     "eslint-plugin-prettier": "^5.5.5",
-    "mocha": "^10",
+    "mocha": "^11",
     "oclif": "^4",
     "prettier": "^3.8.3",
     "shx": "^0.3.3",
@@ -125,6 +125,7 @@
     "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: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\"",