@salesforce/b2c-dx-mcp 1.0.14 → 1.1.1

package/README.md

@@ -8,7 +8,7 @@ Full documentation: [https://salesforcecommercecloud.github.io/b2c-developer-too
 
 ## Installation
 
-**Prerequisites:** Node.js 22.0.0 or higher, MCP client (Cursor, Claude Code, GitHub Copilot, or compatible)
+**Prerequisites:** Node.js 22.16.0 or higher, MCP client (Cursor, Claude Code, GitHub Copilot, or compatible)
 
 **Cursor** (project-level configuration - recommended):
 

package/dist/commands/mcp.d.ts

@@ -39,6 +39,9 @@ export default class McpServerCommand extends BaseCommand<typeof McpServerComman
         'auth-methods': import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'user-auth': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'account-manager-host': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'jwt-cert': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'jwt-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'jwt-passphrase': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'log-level': import("@oclif/core/interfaces").OptionFlag<"trace" | "debug" | "info" | "warn" | "error" | "silent" | undefined, import("@oclif/core/interfaces").CustomOptions>;
         debug: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         json: import("@oclif/core/interfaces").BooleanFlag<boolean>;
@@ -56,6 +59,8 @@ export default class McpServerCommand extends BaseCommand<typeof McpServerComman
         'cloud-origin': import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'credentials-file': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
+    /** Server-scoped persistent state (debug sessions, log watches, etc.) */
+    private serverContext?;
     /** Signal that triggered shutdown (if any) - used to exit process after finally() */
     private shutdownSignal?;
     /** Promise that resolves when stdin closes (MCP client disconnects) */

package/dist/commands/mcp.js

@@ -137,6 +137,7 @@ import { BaseCommand, MrtCommand, InstanceCommand, loadConfig, extractInstanceFl
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { B2CDxMcpServer } from '../server.js';
 import { Services } from '../services.js';
+import { ServerContext } from '../server-context.js';
 import { registerToolsets } from '../registry.js';
 import { TOOLSETS } from '../utils/index.js';
 /**
@@ -199,6 +200,8 @@ export default class McpServerCommand extends BaseCommand {
             default: false,
         }),
     };
+    /** Server-scoped persistent state (debug sessions, log watches, etc.) */
+    serverContext;
     /** Signal that triggered shutdown (if any) - used to exit process after finally() */
     shutdownSignal;
     /** Promise that resolves when stdin closes (MCP client disconnects) */
@@ -315,9 +318,11 @@ export default class McpServerCommand extends BaseCommand {
             },
             telemetry: this.telemetry,
         });
+        // Create server context for persistent state (debug sessions, log watches)
+        this.serverContext = new ServerContext();
         // Register toolsets with loader function that loads config and creates Services on each tool call
         // This allows tools to pick up changes to config files (dw.json, ~/.mobify) between invocations
-        await registerToolsets(startupFlags, server, this.loadServices.bind(this));
+        await registerToolsets(startupFlags, server, this.loadServices.bind(this), this.serverContext);
         // Connect to stdio transport
         const transport = new StdioServerTransport();
         await server.connect(transport);
@@ -326,11 +331,16 @@ export default class McpServerCommand extends BaseCommand {
         this.stdinClosePromise = new Promise((resolve) => {
             const sendStopAndResolve = (signal) => {
                 this.shutdownSignal = signal;
-                this.telemetry?.sendEvent('SERVER_STOPPED', { signal });
-                // Flush telemetry before resolving to ensure SERVER_STOPPED is sent
-                // before finally() proceeds to stop telemetry
-                const flushPromise = this.telemetry?.flush() ?? Promise.resolve();
-                flushPromise.then(() => resolve()).catch(() => resolve());
+                const cleanup = this.serverContext?.destroyAll() ?? Promise.resolve();
+                cleanup
+                    .catch(() => { })
+                    .then(() => {
+                    this.telemetry?.sendEvent('SERVER_STOPPED', { signal });
+                    const flushPromise = this.telemetry?.flush() ?? Promise.resolve();
+                    return flushPromise;
+                })
+                    .then(() => resolve())
+                    .catch(() => resolve());
             };
             // Handle stdin close (MCP client disconnects normally)
             process.stdin.on('close', () => sendStopAndResolve('stdin_close'));

package/dist/registry.d.ts

@@ -1,6 +1,7 @@
 import type { McpTool, Toolset, StartupFlags } from './utils/index.js';
 import type { B2CDxMcpServer } from './server.js';
 import type { Services } from './services.js';
+import type { ServerContext } from './server-context.js';
 /**
  * Registry of tools organized by toolset.
  * Tools can belong to multiple toolsets via their `toolsets` array.
@@ -14,24 +15,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): ToolRegistry;
-/**
- * Register tools with the MCP server based on startup flags.
- *
- * Tool selection logic:
- * 1. If no valid tools result from --toolsets and --tools, perform auto-discovery
- * 2. Start with all tools from --toolsets (or auto-discovered toolsets)
- * 3. Add individual tools from --tools (can be from any toolset)
- *
- * Auto-discovery always enables at least the BASE_TOOLSET (SCAPI), even if no
- * project types are detected in the workspace.
- *
- * Example:
- *   --toolsets STOREFRONTNEXT,MRT --tools cartridge_deploy
- *   This enables STOREFRONTNEXT and MRT toolsets, plus adds cartridge_deploy from CARTRIDGES.
- *
- * @param flags - Startup flags from CLI
- * @param server - B2CDxMcpServer instance
- * @param loadServices - Function that loads configuration and returns Services instance
- */
-export declare function registerToolsets(flags: StartupFlags, server: B2CDxMcpServer, loadServices: () => Promise<Services> | Services): Promise<void>;
+export declare function createToolRegistry(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext): ToolRegistry;
+export declare function registerToolsets(flags: StartupFlags, server: B2CDxMcpServer, loadServices: () => Promise<Services> | Services, serverContext?: ServerContext): Promise<void>;

package/dist/registry.js

@@ -7,6 +7,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 { createCartridgesTools } from './tools/cartridges/index.js';
+import { createDiagnosticsTools } from './tools/diagnostics/index.js';
 import { createMrtTools } from './tools/mrt/index.js';
 import { createPwav3Tools } from './tools/pwav3/index.js';
 import { createScapiTools } from './tools/scapi/index.js';
@@ -61,7 +62,7 @@ function getToolsetsForProjectTypes(projectTypes) {
  * @param loadServices - Function that loads configuration and returns Services instance
  * @returns Complete tool registry
  */
-export function createToolRegistry(loadServices) {
+export function createToolRegistry(loadServices, serverContext) {
     const registry = {
         CARTRIDGES: [],
         MRT: [],
@@ -72,6 +73,7 @@ export function createToolRegistry(loadServices) {
     // Collect all tools from all factories
     const allTools = [
         ...createCartridgesTools(loadServices),
+        ...createDiagnosticsTools(loadServices, serverContext),
         ...createMrtTools(loadServices),
         ...createPwav3Tools(loadServices),
         ...createScapiTools(loadServices),
@@ -134,13 +136,21 @@ async function performAutoDiscovery(flags, reason) {
  * @param server - B2CDxMcpServer instance
  * @param loadServices - Function that loads configuration and returns Services instance
  */
-export async function registerToolsets(flags, server, loadServices) {
+// Guards against accidental double-registration. The MCP SDK throws on duplicate
+// `addTool` names, but tracking servers we've already populated lets callers fail
+// fast with an explicit message instead of a cryptic SDK error.
+const REGISTERED_SERVERS = new WeakSet();
+export async function registerToolsets(flags, server, loadServices, serverContext) {
+    if (REGISTERED_SERVERS.has(server)) {
+        throw new Error('registerToolsets() was called more than once for the same server instance');
+    }
+    REGISTERED_SERVERS.add(server);
     const toolsets = flags.toolsets ?? [];
     const individualTools = flags.tools ?? [];
     const allowNonGaTools = flags.allowNonGaTools ?? false;
     const logger = getLogger();
     // Create the tool registry (all available tools)
-    const toolRegistry = createToolRegistry(loadServices);
+    const toolRegistry = createToolRegistry(loadServices, serverContext);
     // Build flat list of all tools for lookup
     const allTools = Object.values(toolRegistry).flat();
     const allToolsByName = new Map(allTools.map((tool) => [tool.name, tool]));

package/dist/server-context.d.ts

@@ -0,0 +1,27 @@
+import { DebugSessionRegistry } from './tools/diagnostics/session-registry.js';
+/**
+ * Server-scoped persistent state that lives for the lifetime of the MCP
+ * server process. Holds registries for stateful resources (debug sessions,
+ * future log watches) that need to span multiple tool invocations.
+ *
+ * ## Multi-agent / shared-state caveats
+ *
+ * One `ServerContext` is created per MCP server process. With the default
+ * stdio transport, each MCP client connection spawns its own server
+ * subprocess, so this state is naturally isolated per client/agent.
+ *
+ * If this server is ever wired up to a shared transport (e.g. HTTP with
+ * multiple connected clients), `ServerContext` state would be shared
+ * across all connected clients. Sub-agents that run within the same MCP
+ * client would also share the same context. Tools that mutate registries
+ * (like the debug tools) should not assume single-tenant access.
+ *
+ * The debug registry already handles concurrent sessions via session IDs
+ * and host:client_id pairs, so multi-agent use is functional but agents
+ * may see each other's sessions via `debug_list_sessions`.
+ */
+export declare class ServerContext {
+    readonly debugSessions: DebugSessionRegistry;
+    constructor();
+    destroyAll(): Promise<void>;
+}

package/dist/server-context.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 { DebugSessionRegistry } from './tools/diagnostics/session-registry.js';
+/**
+ * Server-scoped persistent state that lives for the lifetime of the MCP
+ * server process. Holds registries for stateful resources (debug sessions,
+ * future log watches) that need to span multiple tool invocations.
+ *
+ * ## Multi-agent / shared-state caveats
+ *
+ * One `ServerContext` is created per MCP server process. With the default
+ * stdio transport, each MCP client connection spawns its own server
+ * subprocess, so this state is naturally isolated per client/agent.
+ *
+ * If this server is ever wired up to a shared transport (e.g. HTTP with
+ * multiple connected clients), `ServerContext` state would be shared
+ * across all connected clients. Sub-agents that run within the same MCP
+ * client would also share the same context. Tools that mutate registries
+ * (like the debug tools) should not assume single-tenant access.
+ *
+ * The debug registry already handles concurrent sessions via session IDs
+ * and host:client_id pairs, so multi-agent use is functional but agents
+ * may see each other's sessions via `debug_list_sessions`.
+ */
+export class ServerContext {
+    debugSessions;
+    constructor() {
+        this.debugSessions = new DebugSessionRegistry();
+    }
+    async destroyAll() {
+        await this.debugSessions.destroyAll();
+    }
+}
+//# sourceMappingURL=server-context.js.map

package/dist/server.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 { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { getLogger } from '@salesforce/b2c-tooling-sdk/logging';
 /**
  * A server implementation that extends the base MCP server.
  *
@@ -53,7 +54,9 @@ export class B2CDxMcpServer extends McpServer {
                     runTimeMs,
                     isError: result.isError ?? false,
                 })
-                    .catch(() => { });
+                    .catch((error_) => {
+                    getLogger().debug({ err: error_, toolName: name }, '[mcp] telemetry sendEventAndFlush failed');
+                });
                 return result;
             }
             catch (error) {
@@ -64,7 +67,9 @@ export class B2CDxMcpServer extends McpServer {
                     runTimeMs,
                     isError: true,
                 })
-                    .catch(() => { });
+                    .catch((error_) => {
+                    getLogger().debug({ err: error_, toolName: name }, '[mcp] telemetry sendEventAndFlush failed');
+                });
                 throw error;
             }
         };

package/dist/services.d.ts

@@ -122,6 +122,15 @@ export declare class Services {
      * @returns True if exists, false otherwise
      */
     exists(targetPath: string): boolean;
+    /**
+     * Get Basic auth credentials for SDAPI operations (script debugger).
+     * Returns undefined if credentials are not configured.
+     */
+    getBasicAuthCredentials(): undefined | {
+        hostname: string;
+        username: string;
+        password: string;
+    };
     /**
      * Get Custom APIs client for managing custom SCAPI endpoints.
      * Requires shortCode, tenantId, and OAuth credentials to be configured.

package/dist/services.js

@@ -126,6 +126,16 @@ export class Services {
     exists(targetPath) {
         return fs.existsSync(targetPath);
     }
+    /**
+     * Get Basic auth credentials for SDAPI operations (script debugger).
+     * Returns undefined if credentials are not configured.
+     */
+    getBasicAuthCredentials() {
+        const { hostname, username, password } = this.resolvedConfig.values;
+        if (!hostname || !username || !password)
+            return undefined;
+        return { hostname, username, password };
+    }
     /**
      * Get Custom APIs client for managing custom SCAPI endpoints.
      * Requires shortCode, tenantId, and OAuth credentials to be configured.

package/dist/tools/adapter.d.ts

@@ -68,6 +68,7 @@ import { type ZodRawShape } from 'zod';
 import type { B2CInstance } from '@salesforce/b2c-tooling-sdk';
 import type { McpTool, ToolResult, Toolset } from '../utils/index.js';
 import type { Services, MrtConfig } from '../services.js';
+import type { ServerContext } from '../server-context.js';
 /**
  * Context provided to tool execute functions.
  * Contains the B2CInstance and/or MRT config based on tool requirements.
@@ -89,6 +90,11 @@ export interface ToolExecutionContext {
      * Services instance for file system access and other utilities.
      */
     services: Services;
+    /**
+     * Server-scoped persistent state (debug sessions, log watches, etc.).
+     * Created once at server startup and shared across all tool invocations.
+     */
+    serverContext?: ServerContext;
 }
 /**
  * Options for creating a tool adapter.
@@ -206,4 +212,4 @@ export declare function jsonResult(data: unknown, indent?: number): ToolResult;
  * }, loadServices);
  * ```
  */
-export declare function createToolAdapter<TInput, TOutput>(options: ToolAdapterOptions<TInput, TOutput>, loadServices: () => Promise<Services> | Services): McpTool;
+export declare function createToolAdapter<TInput, TOutput>(options: ToolAdapterOptions<TInput, TOutput>, loadServices: () => Promise<Services> | Services, serverContext?: ServerContext): McpTool;

package/dist/tools/adapter.js

@@ -168,7 +168,7 @@ function formatZodErrors(error) {
  * }, loadServices);
  * ```
  */
-export function createToolAdapter(options, loadServices) {
+export function createToolAdapter(options, loadServices, serverContext) {
     const { name, description, inputSchema, toolsets, isGA = true, requiresInstance = false, requiresMrtAuth = false, execute, formatOutput, } = options;
     // Create Zod schema from inputSchema definition
     const zodSchema = z.object(inputSchema);
@@ -214,6 +214,7 @@ export function createToolAdapter(options, loadServices) {
                     b2cInstance,
                     mrtConfig,
                     services,
+                    serverContext,
                 };
                 const output = await execute(args, context);
                 // 6. Format output

package/dist/tools/diagnostics/debug-capture-at-breakpoint.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 createDebugCaptureAtBreakpointTool(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext): McpTool;

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

@@ -0,0 +1,118 @@
+/*
+ * 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 { projectFrame, projectVariable, resolveBreakpointPath, } from '@salesforce/b2c-tooling-sdk/operations/debug';
+import { getRegistry, getSessionEntry } from './session-registry.js';
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_TIMEOUT_MS = 120_000;
+export function createDebugCaptureAtBreakpointTool(loadServices, serverContext) {
+    return createToolAdapter({
+        name: 'debug_capture_at_breakpoint',
+        description: 'Set a breakpoint, optionally trigger an HTTP request, wait for the breakpoint to be hit, and capture a diagnostic snapshot (stack, variables, expression results). ' +
+            'Use trigger_url to have the tool fire the request itself (recommended) — this avoids needing to coordinate a separate request while the tool blocks. ' +
+            'Without trigger_url, the tool BLOCKS until the breakpoint is hit or timeout expires and requires the user to trigger a request externally. ' +
+            'For more control, use the non-blocking workflow: debug_set_breakpoints → trigger request → debug_list_sessions (check halted_threads) → debug_get_variables.',
+        toolsets: ['CARTRIDGES', 'SCAPI'],
+        inputSchema: {
+            session_id: z.string().describe('Session ID returned by debug_start_session.'),
+            file: z.string().describe('Local file path or server script path for the breakpoint.'),
+            line: z.number().int().positive().describe('Line number for the breakpoint.'),
+            condition: z.string().optional().describe('Optional conditional expression for the breakpoint.'),
+            expressions: z.array(z.string()).optional().describe('Expressions to evaluate when the breakpoint is hit.'),
+            timeout_ms: z
+                .number()
+                .int()
+                .positive()
+                .max(MAX_TIMEOUT_MS)
+                .optional()
+                .describe(`Timeout in milliseconds waiting for the breakpoint to be hit (default: ${DEFAULT_TIMEOUT_MS}, max: ${MAX_TIMEOUT_MS}).`),
+            auto_continue: z
+                .boolean()
+                .optional()
+                .describe('If true, resume the thread after capturing the snapshot. Defaults to false.'),
+            trigger_url: z
+                .string()
+                .optional()
+                .describe('URL to request after arming the breakpoint. The tool fires this HTTP GET in the background, then waits for the breakpoint to halt. ' +
+                'This is the recommended approach — it avoids needing to coordinate a separate request while the tool blocks.'),
+        },
+        async execute(args, context) {
+            const entry = getSessionEntry(context, args.session_id);
+            const registry = getRegistry(context);
+            const timeout = Math.min(args.timeout_ms ?? DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS);
+            const scriptPath = resolveBreakpointPath(args.file, entry.sourceMapper, entry.cartridges);
+            // Add breakpoint to existing set
+            const allBps = [
+                ...entry.breakpoints.map((bp) => ({
+                    script_path: bp.script_path,
+                    line_number: bp.line_number,
+                    condition: bp.condition,
+                })),
+                { script_path: scriptPath, line_number: args.line, condition: args.condition },
+            ];
+            entry.breakpoints = await entry.manager.setBreakpoints(allBps);
+            const breakpointInfo = {
+                file: entry.sourceMapper.toLocalPath(scriptPath) ?? null,
+                line: args.line,
+                script_path: scriptPath,
+            };
+            // Fire trigger URL in the background (it will hang when the breakpoint halts the thread)
+            const triggerPromise = args.trigger_url
+                ? fetch(args.trigger_url, { redirect: 'follow' })
+                    .then((r) => r.status)
+                    .catch(() => undefined)
+                : undefined;
+            const thread = await registry.waitForHalt(entry, timeout);
+            if (!thread) {
+                return {
+                    breakpoint: breakpointInfo,
+                    halted: false,
+                    timed_out: true,
+                    auto_continued: false,
+                };
+            }
+            const threadDetail = await entry.manager.client.getThread(thread.id);
+            const stack = threadDetail.call_stack.map((frame) => projectFrame(frame, entry.sourceMapper));
+            const varsResult = await entry.manager.client.getVariables(thread.id, 0);
+            const variables = varsResult.object_members.map((m) => projectVariable(m));
+            const evaluations = [];
+            if (args.expressions) {
+                for (const expr of args.expressions) {
+                    try {
+                        // eslint-disable-next-line no-await-in-loop -- sequential: each eval must complete before the next
+                        const evalResult = await entry.manager.client.evaluate(thread.id, 0, expr);
+                        evaluations.push({ expression: evalResult.expression, result: evalResult.result });
+                    }
+                    catch (error) {
+                        evaluations.push({
+                            expression: expr,
+                            result: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                        });
+                    }
+                }
+            }
+            let autoContinued = false;
+            if (args.auto_continue) {
+                await entry.manager.resume(thread.id);
+                autoContinued = true;
+            }
+            const triggerStatus = triggerPromise ? await triggerPromise : undefined;
+            return {
+                breakpoint: breakpointInfo,
+                halted: true,
+                thread_id: thread.id,
+                stack,
+                variables,
+                evaluations: evaluations.length > 0 ? evaluations : undefined,
+                auto_continued: autoContinued,
+                trigger_status: triggerStatus,
+            };
+        },
+        formatOutput: (output) => jsonResult(output),
+    }, loadServices, serverContext);
+}
+//# sourceMappingURL=debug-capture-at-breakpoint.js.map

package/dist/tools/diagnostics/debug-continue.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 createDebugContinueTool(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext): McpTool;

package/dist/tools/diagnostics/debug-continue.js

@@ -0,0 +1,27 @@
+/*
+ * 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 { getSessionEntry } from './session-registry.js';
+export function createDebugContinueTool(loadServices, serverContext) {
+    return createToolAdapter({
+        name: 'debug_continue',
+        description: 'Resume execution of a halted thread. ' +
+            'The thread runs until the next breakpoint or completes the current request.',
+        toolsets: ['CARTRIDGES', 'SCAPI'],
+        inputSchema: {
+            session_id: z.string().describe('Session ID returned by debug_start_session.'),
+            thread_id: z.number().int().describe('Thread ID of the halted thread to resume.'),
+        },
+        async execute(args, context) {
+            const entry = getSessionEntry(context, args.session_id);
+            await entry.manager.resume(args.thread_id);
+            return { thread_id: args.thread_id, status: 'resumed' };
+        },
+        formatOutput: (output) => jsonResult(output),
+    }, loadServices, serverContext);
+}
+//# sourceMappingURL=debug-continue.js.map

package/dist/tools/diagnostics/debug-end-session.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 createDebugEndSessionTool(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext): McpTool;

package/dist/tools/diagnostics/debug-end-session.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 { z } from 'zod';
+import { createToolAdapter, jsonResult } from '../adapter.js';
+import { getRegistry, getSessionEntry } from './session-registry.js';
+export function createDebugEndSessionTool(loadServices, serverContext) {
+    return createToolAdapter({
+        name: 'debug_end_session',
+        description: 'End a script debugger session and free its slot on the instance. ' +
+            'IMPORTANT: Always call this when finished debugging — leaving sessions open can interfere with other debuggers and consumes a debugger client slot.',
+        toolsets: ['CARTRIDGES', 'SCAPI'],
+        inputSchema: {
+            session_id: z.string().describe('Session ID returned by debug_start_session.'),
+            clear_breakpoints: z
+                .boolean()
+                .optional()
+                .describe('If true, delete all breakpoints before disconnecting. Defaults to false.'),
+        },
+        async execute(args, context) {
+            const entry = getSessionEntry(context, args.session_id);
+            if (args.clear_breakpoints) {
+                try {
+                    await entry.manager.client.deleteBreakpoints();
+                }
+                catch {
+                    // Best-effort
+                }
+            }
+            await getRegistry(context).destroySession(args.session_id);
+            return { session_id: args.session_id, status: 'disconnected' };
+        },
+        formatOutput: (output) => jsonResult(output),
+    }, loadServices, serverContext);
+}
+//# sourceMappingURL=debug-end-session.js.map

package/dist/tools/diagnostics/debug-evaluate.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 createDebugEvaluateTool(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext): McpTool;

package/dist/tools/diagnostics/debug-evaluate.js

@@ -0,0 +1,30 @@
+/*
+ * 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 { getSessionEntry } from './session-registry.js';
+export function createDebugEvaluateTool(loadServices, serverContext) {
+    return createToolAdapter({
+        name: 'debug_evaluate',
+        description: 'Evaluate a JavaScript expression in the context of a halted thread and stack frame. ' +
+            'WARNING: Expressions may have side effects (modify variables, call functions). Use with care.',
+        toolsets: ['CARTRIDGES', 'SCAPI'],
+        inputSchema: {
+            session_id: z.string().describe('Session ID returned by debug_start_session.'),
+            thread_id: z.number().int().describe('Thread ID from debug_wait_for_stop or debug_list_sessions.'),
+            frame_index: z.number().int().min(0).optional().describe('Stack frame index (0 = top frame). Defaults to 0.'),
+            expression: z.string().describe('JavaScript expression to evaluate in the frame context.'),
+        },
+        async execute(args, context) {
+            const entry = getSessionEntry(context, args.session_id);
+            const frameIndex = args.frame_index ?? 0;
+            const result = await entry.manager.client.evaluate(args.thread_id, frameIndex, args.expression);
+            return { expression: result.expression, result: result.result };
+        },
+        formatOutput: (output) => jsonResult(output),
+    }, loadServices, serverContext);
+}
+//# sourceMappingURL=debug-evaluate.js.map

package/dist/tools/diagnostics/debug-get-stack.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 createDebugGetStackTool(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext): McpTool;

package/dist/tools/diagnostics/debug-get-stack.js

@@ -0,0 +1,31 @@
+/*
+ * 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 { projectFrame } from '@salesforce/b2c-tooling-sdk/operations/debug';
+import { getSessionEntry } from './session-registry.js';
+export function createDebugGetStackTool(loadServices, serverContext) {
+    return createToolAdapter({
+        name: 'debug_get_stack',
+        description: 'Get the call stack for a halted thread. ' +
+            'Returns frames with mapped local file paths and server script paths.',
+        toolsets: ['CARTRIDGES', 'SCAPI'],
+        inputSchema: {
+            session_id: z.string().describe('Session ID returned by debug_start_session.'),
+            thread_id: z.number().int().describe('Thread ID from debug_wait_for_stop or debug_list_sessions.'),
+        },
+        async execute(args, context) {
+            const entry = getSessionEntry(context, args.session_id);
+            const thread = await entry.manager.client.getThread(args.thread_id);
+            return {
+                thread_id: thread.id,
+                frames: thread.call_stack.map((frame) => projectFrame(frame, entry.sourceMapper)),
+            };
+        },
+        formatOutput: (output) => jsonResult(output),
+    }, loadServices, serverContext);
+}
+//# sourceMappingURL=debug-get-stack.js.map

package/dist/tools/diagnostics/debug-get-variables.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 createDebugGetVariablesTool(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext): McpTool;