@salesforce/b2c-dx-mcp 1.1.3 → 1.2.0

package/dist/registry.js

@@ -8,18 +8,21 @@ 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 { createDocsTools } from './tools/docs/index.js';
 import { createMrtTools } from './tools/mrt/index.js';
 import { createPwav3Tools } from './tools/pwav3/index.js';
 import { createScapiTools } from './tools/scapi/index.js';
 import { createStorefrontNextTools } from './tools/storefrontnext/index.js';
 /**
- * Base toolset that is always enabled.
- * Provides SCAPI discovery and custom API scaffolding tools.
+ * Base toolsets that are always enabled regardless of detected project type.
+ * - SCAPI: SCAPI discovery and custom API scaffolding tools.
+ * - DIAGNOSTICS: script debugger, log inspection, and docs tools — useful in
+ *   every project type, so they are always available.
  */
-const BASE_TOOLSET = 'SCAPI';
+const BASE_TOOLSETS = ['SCAPI', 'DIAGNOSTICS'];
 /**
  * Toolset mapping by project type.
- * Each project type enables specific toolsets IN ADDITION to the base toolset.
+ * Each project type enables specific toolsets IN ADDITION to the base toolsets.
  */
 const PROJECT_TYPE_TOOLSETS = {
     cartridges: ['CARTRIDGES'],
@@ -27,25 +30,27 @@ const PROJECT_TYPE_TOOLSETS = {
     'storefront-next': ['STOREFRONTNEXT', 'MRT', 'CARTRIDGES'],
 };
 /**
- * Gets toolsets for a project type, always including the base toolset.
+ * Gets toolsets for a project type, always including the base toolsets.
  */
 function getToolsetsForProjectType(projectType) {
     const additionalToolsets = PROJECT_TYPE_TOOLSETS[projectType] ?? [];
-    return [...additionalToolsets, BASE_TOOLSET];
+    return [...additionalToolsets, ...BASE_TOOLSETS];
 }
 /**
  * Maps multiple detected project types to a union of MCP toolsets.
  *
  * Combines toolsets from all matched project types, enabling hybrid
- * project support (e.g., cartridges + pwa-kit-v3 gets CARTRIDGES + PWAV3 + MRT + SCAPI).
+ * project support (e.g., cartridges + pwa-kit-v3 gets CARTRIDGES + PWAV3 + MRT + SCAPI + DIAGNOSTICS).
  *
  * @param projectTypes - Array of detected project types
- * @returns Union of all toolsets for the detected project types (always includes base toolset)
+ * @returns Union of all toolsets for the detected project types (always includes base toolsets)
  */
 function getToolsetsForProjectTypes(projectTypes) {
     const toolsetSet = new Set();
-    // Always include base toolset
-    toolsetSet.add(BASE_TOOLSET);
+    // Always include base toolsets
+    for (const base of BASE_TOOLSETS) {
+        toolsetSet.add(base);
+    }
     // Add toolsets for each detected project type
     for (const projectType of projectTypes) {
         for (const toolset of getToolsetsForProjectType(projectType)) {
@@ -65,6 +70,7 @@ function getToolsetsForProjectTypes(projectTypes) {
 export function createToolRegistry(loadServices, serverContext) {
     const registry = {
         CARTRIDGES: [],
+        DIAGNOSTICS: [],
         MRT: [],
         PWAV3: [],
         SCAPI: [],
@@ -74,6 +80,7 @@ export function createToolRegistry(loadServices, serverContext) {
     const allTools = [
         ...createCartridgesTools(loadServices),
         ...createDiagnosticsTools(loadServices, serverContext),
+        ...createDocsTools(loadServices),
         ...createMrtTools(loadServices),
         ...createPwav3Tools(loadServices),
         ...createScapiTools(loadServices),
@@ -89,7 +96,7 @@ export function createToolRegistry(loadServices, serverContext) {
 }
 /**
  * Performs workspace auto-discovery and returns appropriate toolsets.
- * Always includes BASE_TOOLSET even if no project types are detected.
+ * Always includes the BASE_TOOLSETS even if no project types are detected.
  *
  * @param flags - Startup flags containing projectDirectory
  * @param reason - Reason for triggering auto-discovery (for logging)
@@ -125,8 +132,8 @@ async function performAutoDiscovery(flags, reason) {
  * 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.
+ * Auto-discovery always enables at least the BASE_TOOLSETS (SCAPI + DIAGNOSTICS),
+ * even if no project types are detected in the workspace.
  *
  * Example:
  *   --toolsets STOREFRONTNEXT,MRT --tools cartridge_deploy
@@ -173,7 +180,7 @@ export async function registerToolsets(flags, server, loadServices, serverContex
     // 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 BASE_TOOLSET if no project types are detected.
+    // or at minimum the BASE_TOOLSETS if no project types are detected.
     if (toolsetsToEnable.size === 0 && validIndividualTools.length === 0) {
         const discoveredToolsets = await performAutoDiscovery(flags, 'no valid toolsets or tools');
         for (const toolset of discoveredToolsets) {

package/dist/server-context.d.ts

@@ -1,8 +1,9 @@
+import { LogWatchRegistry } from './tools/diagnostics/log-watch-registry.js';
 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.
+ * log watches) that need to span multiple tool invocations.
  *
  * ## Multi-agent / shared-state caveats
  *
@@ -16,12 +17,13 @@ import { DebugSessionRegistry } from './tools/diagnostics/session-registry.js';
  * client would also share the same context. Tools that mutate registries
  * (like the debug tools) should not assume single-tenant access.
  *
- * The 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`.
+ * 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.
  */
 export declare class ServerContext {
     readonly debugSessions: DebugSessionRegistry;
+    readonly logWatches: LogWatchRegistry;
     constructor();
     destroyAll(): Promise<void>;
 }

package/dist/server-context.js

@@ -3,11 +3,12 @@
  * 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 { LogWatchRegistry } from './tools/diagnostics/log-watch-registry.js';
 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.
+ * log watches) that need to span multiple tool invocations.
  *
  * ## Multi-agent / shared-state caveats
  *
@@ -21,17 +22,19 @@ import { DebugSessionRegistry } from './tools/diagnostics/session-registry.js';
  * client would also share the same context. Tools that mutate registries
  * (like the debug tools) should not assume single-tenant access.
  *
- * The 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`.
+ * 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.
  */
 export class ServerContext {
     debugSessions;
+    logWatches;
     constructor() {
         this.debugSessions = new DebugSessionRegistry();
+        this.logWatches = new LogWatchRegistry();
     }
     async destroyAll() {
-        await this.debugSessions.destroyAll();
+        await Promise.allSettled([this.debugSessions.destroyAll(), this.logWatches.destroyAll()]);
     }
 }
 //# sourceMappingURL=server-context.js.map

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

@@ -16,7 +16,7 @@ export function createDebugCaptureAtBreakpointTool(loadServices, serverContext)
             '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'],
+        toolsets: ['CARTRIDGES', 'DIAGNOSTICS', '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.'),

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

@@ -11,7 +11,7 @@ export function createDebugContinueTool(loadServices, serverContext) {
         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'],
+        toolsets: ['CARTRIDGES', 'DIAGNOSTICS', '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.'),

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

@@ -11,7 +11,7 @@ export function createDebugEndSessionTool(loadServices, serverContext) {
         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'],
+        toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'SCAPI'],
         inputSchema: {
             session_id: z.string().describe('Session ID returned by debug_start_session.'),
             clear_breakpoints: z

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

@@ -11,7 +11,7 @@ export function createDebugEvaluateTool(loadServices, serverContext) {
         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'],
+        toolsets: ['CARTRIDGES', 'DIAGNOSTICS', '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.'),

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

@@ -12,7 +12,7 @@ export function createDebugGetStackTool(loadServices, serverContext) {
         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'],
+        toolsets: ['CARTRIDGES', 'DIAGNOSTICS', '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.'),

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

@@ -12,7 +12,7 @@ export function createDebugGetVariablesTool(loadServices, serverContext) {
         name: 'debug_get_variables',
         description: 'Get variables for a stack frame in a halted thread. ' +
             'Defaults to top-frame locals. Use scope to filter (local/closure/global) or object_path to drill into nested objects.',
-        toolsets: ['CARTRIDGES', 'SCAPI'],
+        toolsets: ['CARTRIDGES', 'DIAGNOSTICS', '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.'),

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

@@ -11,7 +11,7 @@ export function createDebugListSessionsTool(loadServices, serverContext) {
         name: 'debug_list_sessions',
         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', 'SCAPI'],
+        toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'SCAPI'],
         inputSchema: {},
         async execute(_args, context) {
             const registry = getRegistry(context);

package/dist/tools/diagnostics/debug-set-breakpoints.js

@@ -13,7 +13,7 @@ export function createDebugSetBreakpointsTool(loadServices, serverContext) {
         description: 'Set breakpoints in a debug session. Replaces all previously set breakpoints. ' +
             'Accepts local file paths (mapped to server paths via cartridge discovery), cartridge-prefixed paths, or server paths starting with /. ' +
             'Check the "verified" field and "warnings" — unmapped paths are flagged.',
-        toolsets: ['CARTRIDGES', 'SCAPI'],
+        toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'SCAPI'],
         inputSchema: {
             session_id: z.string().describe('Session ID returned by debug_start_session.'),
             breakpoints: z

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

@@ -15,7 +15,7 @@ export function createDebugStartSessionTool(loadServices, serverContext) {
             'Returns a session_id for use with other debug tools, plus discovered cartridge mappings. ' +
             '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.',
-        toolsets: ['CARTRIDGES', 'SCAPI'],
+        toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'SCAPI'],
         inputSchema: {
             cartridge_directory: z
                 .string()

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

@@ -15,7 +15,7 @@ function createStepTool(action, description, loadServices, serverContext) {
     return createToolAdapter({
         name: `debug_${action}`,
         description: description + ' Follow with debug_wait_for_stop to see where execution landed.',
-        toolsets: ['CARTRIDGES', 'SCAPI'],
+        toolsets: ['CARTRIDGES', 'DIAGNOSTICS', '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 step.'),

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

@@ -15,7 +15,7 @@ export function createDebugWaitForStopTool(loadServices, serverContext) {
         description: 'Wait for a thread to halt at a breakpoint or step. ' +
             'Returns immediately if a thread is already halted; otherwise BLOCKS until a halt occurs or the timeout expires. ' +
             'Preferred non-blocking alternative: after debug_set_breakpoints, trigger the request yourself, then use debug_list_sessions to check halted_threads before calling debug_get_stack/debug_get_variables.',
-        toolsets: ['CARTRIDGES', 'SCAPI'],
+        toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'SCAPI'],
         inputSchema: {
             session_id: z.string().describe('Session ID returned by debug_start_session.'),
             timeout_ms: z

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

@@ -1,4 +1,9 @@
 import type { McpTool } from '../../utils/index.js';
 import type { Services } from '../../services.js';
 import type { ServerContext } from '../../server-context.js';
-export declare function createDiagnosticsTools(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext): McpTool[];
+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 {
+}
+export declare function createDiagnosticsTools(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext, injections?: DiagnosticsToolInjections): McpTool[];

package/dist/tools/diagnostics/index.js

@@ -14,7 +14,13 @@ import { createDebugEvaluateTool } from './debug-evaluate.js';
 import { createDebugContinueTool } from './debug-continue.js';
 import { createDebugStepTools } from './debug-step.js';
 import { createDebugCaptureAtBreakpointTool } from './debug-capture-at-breakpoint.js';
-export function createDiagnosticsTools(loadServices, serverContext) {
+import { createLogsListFilesTool } from './logs-list-files.js';
+import { createLogsGetRecentTool } from './logs-get-recent.js';
+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';
+export function createDiagnosticsTools(loadServices, serverContext, injections) {
     return [
         createDebugListSessionsTool(loadServices, serverContext),
         createDebugStartSessionTool(loadServices, serverContext),
@@ -27,6 +33,12 @@ export function createDiagnosticsTools(loadServices, serverContext) {
         createDebugContinueTool(loadServices, serverContext),
         ...createDebugStepTools(loadServices, serverContext),
         createDebugCaptureAtBreakpointTool(loadServices, serverContext),
+        createLogsListFilesTool(loadServices, serverContext, injections),
+        createLogsGetRecentTool(loadServices, serverContext, injections),
+        createLogsWatchStartTool(loadServices, serverContext, injections),
+        createLogsWatchPollTool(loadServices, serverContext),
+        createLogsWatchStopTool(loadServices, serverContext),
+        createLogsWatchListTool(loadServices, serverContext),
     ];
 }
 //# sourceMappingURL=index.js.map

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

@@ -0,0 +1,94 @@
+import type { LogEntry, LogFile, TailLogsResult } from '@salesforce/b2c-tooling-sdk/operations/logs';
+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 LogWatchEntry {
+    watchId: string;
+    hostname: string;
+    prefixes: string[];
+    buffer: LogEntry[];
+    /** Running byte size of `buffer` (raw + message), used for the byte cap. */
+    bufferBytes: number;
+    rotations: LogFile[];
+    /** Cumulative deduped list of every file ever discovered (for logs_watch_list). */
+    filesDiscovered: LogFile[];
+    /** Files discovered since the last poll drain (what logs_watch_poll returns). */
+    pendingFilesDiscovered: LogFile[];
+    errors: Array<{
+        message: string;
+        at: string;
+    }>;
+    totalEntriesSeen: number;
+    droppedEntries: number;
+    bufferCap: number;
+    bufferBytesCap: number;
+    stop: () => Promise<void>;
+    done: Promise<void>;
+    pollWaiters: PollWaiter[];
+    createdAt: number;
+    lastActivityAt: number;
+    stopped: boolean;
+}
+export interface RegisterWatchOptions {
+    hostname: string;
+    prefixes: string[];
+    tailResult: TailLogsResult;
+    bufferCap?: number;
+    bufferBytesCap?: number;
+}
+export declare class LogWatchRegistry {
+    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: LogEntry): void;
+    appendError(watchId: string, err: Error): void;
+    /**
+     * Append a discovered file (deduped by name).
+     */
+    appendFileDiscovered(watchId: string, file: LogFile): void;
+    appendRotation(watchId: string, file: LogFile): void;
+    destroyAll(): Promise<void>;
+    destroyWatch(watchId: string): Promise<void>;
+    /**
+     * Drain buffered entries (up to maxEntries) and any rotation/error events
+     * from the watch. Removes drained items from the underlying buffers.
+     */
+    drain(watchId: string, maxEntries: number): {
+        entries: LogEntry[];
+        errors: Array<{
+            message: string;
+            at: string;
+        }>;
+        filesDiscovered: LogFile[];
+        rotations: LogFile[];
+        truncated: boolean;
+    };
+    findByHostname(hostname: string): LogWatchEntry | undefined;
+    getWatch(watchId: string): LogWatchEntry | undefined;
+    getWatchOrThrow(watchId: string): LogWatchEntry;
+    listWatches(): LogWatchEntry[];
+    registerWatch(opts: RegisterWatchOptions): LogWatchEntry;
+    /**
+     * Wait until at least one entry is buffered (or rotation/error event), or until
+     * timeout elapses. Returns immediately if the buffer is non-empty.
+     */
+    waitForActivity(watchId: string, timeoutMs: number): Promise<void>;
+    private cleanupIdleWatches;
+    private flushWaiters;
+}
+export declare function getLogWatchRegistry(context: ToolExecutionContext): LogWatchRegistry;
+export declare function getLogWatchEntry(context: ToolExecutionContext, watchId: string): LogWatchEntry;