@salesforce/b2c-dx-mcp 2.1.2 → 3.0.1

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

@@ -9,15 +9,14 @@ 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.',
+        effect: 'write',
+        idempotent: true,
+        openWorld: true,
+        description: 'Disconnect and free the instance debugger slot. Always end sessions when finished, including after errors.',
         toolsets: ['CARTRIDGES', 'DIAGNOSTICS', '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.'),
+            session_id: z.string(),
+            clear_breakpoints: z.boolean().optional().describe('Clear breakpoints before disconnecting. Default: false.'),
         },
         async execute(args, context) {
             const entry = getSessionEntry(context, args.session_id);

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

@@ -9,14 +9,16 @@ 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.',
+        effect: 'write',
+        idempotent: false,
+        openWorld: true,
+        description: 'Evaluate JavaScript in a halted thread/frame. Expressions can call functions and change remote state.',
         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.'),
-            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.'),
+            session_id: z.string(),
+            thread_id: z.number().int(),
+            frame_index: z.number().int().min(0).optional().describe('Default: 0 (top frame).'),
+            expression: z.string().describe('JavaScript expression.'),
         },
         async execute(args, context) {
             const entry = getSessionEntry(context, args.session_id);

package/dist/tools/diagnostics/{debug-continue.d.ts → debug-inspect.d.ts}

@@ -1,4 +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;
+export declare function createDebugInspectTool(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext): McpTool;

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

@@ -0,0 +1,70 @@
+/*
+ * 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, } from '@salesforce/b2c-tooling-sdk/operations/debug';
+import { getSessionEntry } from './session-registry.js';
+export function createDebugInspectTool(loadServices, serverContext) {
+    return createToolAdapter({
+        name: 'debug_inspect',
+        effect: 'read',
+        idempotent: true,
+        openWorld: true,
+        description: 'Inspect a halted thread: stack and frame variables. Expand objects with object_path.',
+        toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'SCAPI'],
+        inputSchema: {
+            include: z
+                .array(z.enum(['stack', 'variables']))
+                .min(1)
+                .optional()
+                .describe('Default: both. Object expansion requires variables.'),
+            session_id: z.string(),
+            thread_id: z.number().int(),
+            frame_index: z
+                .number()
+                .int()
+                .min(0)
+                .optional()
+                .describe('Variable frame; ignored for stack-only reads. Default: 0.'),
+            scope: z
+                .enum(['local', 'closure', 'global'])
+                .optional()
+                .describe('Default: all scopes. Not used for object expansion.'),
+            object_path: z.string().optional().describe('Object path, e.g. request.httpParameters; returns child members.'),
+        },
+        async execute(args, context) {
+            const entry = getSessionEntry(context, args.session_id);
+            const frameIndex = args.frame_index ?? 0;
+            const include = args.include ?? ['stack', 'variables'];
+            if (!include.includes('variables') && (args.object_path || args.scope)) {
+                throw new Error('scope and object_path require variables in include.');
+            }
+            if (args.object_path && args.scope)
+                throw new Error('Use scope or object_path, not both.');
+            const output = { thread_id: args.thread_id };
+            if (include.includes('stack')) {
+                const thread = await entry.manager.client.getThread(args.thread_id);
+                output.stack = thread.call_stack.map((frame) => projectFrame(frame, entry.sourceMapper));
+            }
+            if (include.includes('variables')) {
+                if (args.object_path) {
+                    const result = await entry.manager.client.getMembers(args.thread_id, frameIndex, args.object_path);
+                    output.variables = result.object_members.map((m) => projectVariable(m, { includeScope: false }));
+                }
+                else {
+                    const result = await entry.manager.client.getVariables(args.thread_id, frameIndex);
+                    const members = args.scope
+                        ? result.object_members.filter((m) => m.scope === args.scope)
+                        : result.object_members;
+                    output.variables = members.map((m) => projectVariable(m));
+                }
+            }
+            return output;
+        },
+        formatOutput: (output) => jsonResult(output),
+    }, loadServices, serverContext);
+}
+//# sourceMappingURL=debug-inspect.js.map

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

@@ -9,8 +9,10 @@ import { getRegistry } from './session-registry.js';
 export function createDebugListSessionsTool(loadServices, serverContext) {
     return createToolAdapter({
         name: 'debug_list_sessions',
-        description: 'List active script debugger sessions with their breakpoints 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.',
+        effect: 'read',
+        idempotent: true,
+        openWorld: false,
+        description: 'List debugger sessions, breakpoints, and known halted threads.',
         toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'SCAPI'],
         inputSchema: {},
         async execute(_args, context) {

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

@@ -7,27 +7,27 @@ import { z } from 'zod';
 import { createToolAdapter, jsonResult } from '../adapter.js';
 import { projectBreakpoint, resolveBreakpointPath, } from '@salesforce/b2c-tooling-sdk/operations/debug';
 import { getSessionEntry } from './session-registry.js';
+import { MCP_SKILL_REFERENCES } from '../../skill-references.js';
 export function createDebugSetBreakpointsTool(loadServices, serverContext) {
     return createToolAdapter({
         name: 'debug_set_breakpoints',
-        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.',
+        effect: 'write',
+        idempotent: true,
+        openWorld: true,
+        description: 'Replace all session breakpoints. verified means local source mapping, not deployed-code validation. ' +
+            'Workflow: skill://mcp/debugger/SKILL.md.',
         toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'SCAPI'],
         inputSchema: {
-            session_id: z.string().describe('Session ID returned by debug_start_session.'),
+            session_id: z.string(),
             breakpoints: z
-                .array(z.object({
-                file: z
-                    .string()
-                    .describe('Local file path or server script path (e.g. /app_storefront/cartridge/controllers/Cart.js).'),
-                line: z.number().int().positive().describe('Line number for the breakpoint.'),
-                condition: z
-                    .string()
-                    .optional()
-                    .describe('Optional conditional expression. Breakpoint only triggers when this evaluates to true.'),
-            }))
-                .describe('Array of breakpoints to set. Replaces all existing breakpoints.'),
+                .array(z
+                .object({
+                file: z.string().describe('Local, cartridge-prefixed, or absolute server script path.'),
+                line: z.number().int().positive().describe('1-based line number.'),
+                condition: z.string().optional().describe('Halt when this expression is true.'),
+            })
+                .strict())
+                .describe('Replacement set; empty clears all.'),
         },
         async execute(args, context) {
             const entry = getSessionEntry(context, args.session_id);
@@ -48,6 +48,7 @@ export function createDebugSetBreakpointsTool(loadServices, serverContext) {
                     verified: entry.sourceMapper.toLocalPath(bp.script_path) !== undefined,
                 })),
                 warnings: warnings.length > 0 ? warnings : undefined,
+                skillReferences: warnings.length > 0 ? [MCP_SKILL_REFERENCES.debuggerPrerequisites] : undefined,
             };
         },
         formatOutput: (output) => jsonResult(output),

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

@@ -12,8 +12,11 @@ import { getRegistry } from './session-registry.js';
 export function createDebugStartSessionTool(loadServices, serverContext) {
     return createToolAdapter({
         name: 'debug_start_session',
-        description: 'Start a B2C script debugger session and discover cartridge mappings. Returns session_id for follow-up tools. ' +
-            'Debugging halts remote request threads; always call debug_end_session.',
+        effect: 'write',
+        idempotent: false,
+        openWorld: true,
+        description: 'Start a script debugger session and map cartridges; replaces any remote debugger client. Requires BM Basic Auth with WebDAV_Manage_Customization. ' +
+            'Use returned session_id; end with debug_end_session. Workflow: skill://mcp/debugger/SKILL.md.',
         toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'SCAPI'],
         inputSchema: {
             cartridgeDirectory: z

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

@@ -12,17 +12,20 @@ const MAX_TIMEOUT_MS = 120_000;
 export function createDebugWaitForStopTool(loadServices, serverContext) {
     return createToolAdapter({
         name: 'debug_wait_for_stop',
+        effect: 'read',
+        idempotent: true,
+        openWorld: true,
         description: 'Wait for a debugger thread to halt. Returns immediately if already halted; otherwise blocks until a halt or timeout.',
         toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'SCAPI'],
         inputSchema: {
-            session_id: z.string().describe('Session ID returned by debug_start_session.'),
+            session_id: z.string(),
             timeout_ms: z
                 .number()
                 .int()
                 .positive()
                 .max(MAX_TIMEOUT_MS)
                 .optional()
-                .describe(`Timeout in milliseconds (default: ${DEFAULT_TIMEOUT_MS}, max: ${MAX_TIMEOUT_MS}).`),
+                .describe(`Wait timeout in milliseconds. Default: ${DEFAULT_TIMEOUT_MS}; max: ${MAX_TIMEOUT_MS}.`),
         },
         async execute(args, context) {
             const entry = getSessionEntry(context, args.session_id);

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

@@ -3,8 +3,8 @@ import type { Services } from '../../services.js';
 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';
-import { type MrtLogsWatchStartInjections } from './mrt-logs-watch-start.js';
+import { type LogsWatchStartInjections } from './logs-watch.js';
+import { type MrtLogsWatchStartInjections } from './mrt-logs-watch.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

@@ -9,22 +9,16 @@ import { createDebugStartSessionTool } from './debug-start-session.js';
 import { createDebugEndSessionTool } from './debug-end-session.js';
 import { createDebugSetBreakpointsTool } from './debug-set-breakpoints.js';
 import { createDebugWaitForStopTool } from './debug-wait-for-stop.js';
-import { createDebugGetStackTool } from './debug-get-stack.js';
-import { createDebugGetVariablesTool } from './debug-get-variables.js';
+import { createDebugInspectTool } from './debug-inspect.js';
 import { createDebugEvaluateTool } from './debug-evaluate.js';
-import { createDebugContinueTool } from './debug-continue.js';
-import { createDebugStepTools } from './debug-step.js';
+import { createDebugControlTool } from './debug-control.js';
 import { createDebugCaptureAtBreakpointTool } from './debug-capture-at-breakpoint.js';
 import { createLogsListFilesTool } from './logs-list-files.js';
 import { createLogsGetRecentTool } from './logs-get-recent.js';
-import { createLogsWatchStartTool } from './logs-watch-start.js';
+import { createLogsWatchTool } from './logs-watch.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 { createMrtLogsWatchTool } from './mrt-logs-watch.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 [
         createConfigInspectTool(loadServices),
@@ -33,22 +27,16 @@ export function createDiagnosticsTools(loadServices, serverContext, injections)
         createDebugEndSessionTool(loadServices, serverContext),
         createDebugSetBreakpointsTool(loadServices, serverContext),
         createDebugWaitForStopTool(loadServices, serverContext),
-        createDebugGetStackTool(loadServices, serverContext),
-        createDebugGetVariablesTool(loadServices, serverContext),
+        createDebugInspectTool(loadServices, serverContext),
         createDebugEvaluateTool(loadServices, serverContext),
-        createDebugContinueTool(loadServices, serverContext),
-        ...createDebugStepTools(loadServices, serverContext),
+        createDebugControlTool(loadServices, serverContext),
         createDebugCaptureAtBreakpointTool(loadServices, serverContext),
         createLogsListFilesTool(loadServices, serverContext, injections),
         createLogsGetRecentTool(loadServices, serverContext, injections),
-        createLogsWatchStartTool(loadServices, serverContext, injections),
+        createLogsWatchTool(loadServices, serverContext, injections),
         createLogsWatchPollTool(loadServices, serverContext),
-        createLogsWatchStopTool(loadServices, serverContext),
-        createLogsWatchListTool(loadServices, serverContext),
-        createMrtLogsWatchStartTool(loadServices, serverContext, injections),
+        createMrtLogsWatchTool(loadServices, serverContext, injections),
         createMrtLogsWatchPollTool(loadServices, serverContext),
-        createMrtLogsWatchStopTool(loadServices, serverContext),
-        createMrtLogsWatchListTool(loadServices, serverContext),
     ];
 }
 //# sourceMappingURL=index.js.map

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

@@ -21,7 +21,7 @@ export interface LogWatchEntry {
     /** 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). */
+    /** Cumulative deduped list of every file ever discovered (for logs_watch(action: list)). */
     filesDiscovered: LogFile[];
     /** Files discovered since the last poll drain (what logs_watch_poll returns). */
     pendingFilesDiscovered: LogFile[];

package/dist/tools/diagnostics/log-watch-registry.js

@@ -157,7 +157,7 @@ export class LogWatchRegistry {
     getWatchOrThrow(watchId) {
         const w = this.watches.get(watchId);
         if (!w) {
-            throw new Error(`No log watch found with id "${watchId}". Use logs_watch_list to see active watches.`);
+            throw new Error(`No log watch found with id "${watchId}". Use logs_watch(action: list) to see active watches.`);
         }
         w.lastActivityAt = Date.now();
         return w;
@@ -170,7 +170,7 @@ export class LogWatchRegistry {
         const existing = this.findByHostname(hostname);
         if (existing) {
             throw new Error(`A log watch already exists for ${hostname} (watch_id: "${existing.watchId}"). ` +
-                `Stop it with logs_watch_stop first, or poll the existing watch.`);
+                `Stop it with logs_watch(action: stop) first, or poll the existing watch.`);
         }
         const watchId = randomUUID();
         const now = Date.now();

package/dist/tools/diagnostics/logs-get-recent.js

@@ -12,6 +12,9 @@ export function createLogsGetRecentTool(loadServices, serverContext, injections)
     const getRecentLogsFn = injections?.getRecentLogs ?? getRecentLogs;
     return createToolAdapter({
         name: 'logs_get_recent',
+        effect: 'read',
+        idempotent: true,
+        openWorld: true,
         description: 'Fetch recent B2C instance logs. Use for quick lookups; start a log watch before actions whose entries must not be missed.',
         toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'SCAPI'],
         requiresInstance: true,
@@ -20,7 +23,7 @@ export function createLogsGetRecentTool(loadServices, serverContext, injections)
                 .array(z.string())
                 .optional()
                 .describe('Log prefixes. Default: ["error", "customerror"]; paths may include subdirectories.'),
-            count: z.number().int().positive().optional().describe('Maximum number of entries to return. Defaults to 50.'),
+            count: z.number().int().positive().optional().describe('Maximum entries. Default: 50.'),
             since: z
                 .string()
                 .optional()

package/dist/tools/diagnostics/logs-list-files.js

@@ -10,8 +10,10 @@ export function createLogsListFilesTool(loadServices, serverContext, injections)
     const listLogFilesFn = injections?.listLogFiles ?? listLogFiles;
     return createToolAdapter({
         name: 'logs_list_files',
-        description: 'List log files on the configured B2C Commerce instance via WebDAV. ' +
-            'Use this to discover what log prefixes are active (error, customerror, debug, jobs, ...) before fetching entries with logs_get_recent or starting a watch.',
+        effect: 'read',
+        idempotent: true,
+        openWorld: true,
+        description: 'List B2C log files and prefixes available for reading or watching.',
         toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'SCAPI'],
         requiresInstance: true,
         inputSchema: {

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

@@ -11,24 +11,20 @@ const DEFAULT_MAX_ENTRIES = 200;
 export function createLogsWatchPollTool(loadServices, serverContext) {
     return createToolAdapter({
         name: 'logs_watch_poll',
-        description: 'Drain buffered entries from a log watch. If the buffer is empty, blocks up to timeout_ms waiting for ' +
-            'new entries. Returns immediately if entries are already buffered. Set truncated=true if there are more ' +
-            'entries beyond max_entries — call again to get the rest.',
+        effect: 'read',
+        idempotent: true,
+        openWorld: false,
+        description: 'Drain buffered B2C logs; wait when empty. Repeat if truncated. Includes rotation and error events.',
         toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'SCAPI'],
         inputSchema: {
-            watch_id: z.string().describe('Watch id from logs_watch_start.'),
+            watch_id: z.string(),
             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.'),
+                .describe('Wait when empty, in milliseconds. Default: 5000; 0 returns immediately.'),
+            max_entries: z.number().int().positive().optional().describe('Maximum entries. Default: 200.'),
         },
         async execute(args, context) {
             const registry = getLogWatchRegistry(context);

package/dist/tools/diagnostics/{logs-watch-start.d.ts → logs-watch.d.ts}

@@ -6,4 +6,4 @@ import type { ServerContext } from '../../server-context.js';
 export interface LogsWatchStartInjections {
     tailLogs?: (instance: B2CInstance, options?: TailLogsOptions) => Promise<TailLogsResult>;
 }
-export declare function createLogsWatchStartTool(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext, injections?: LogsWatchStartInjections): McpTool;
+export declare function createLogsWatchTool(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext, injections?: LogsWatchStartInjections): McpTool;

package/dist/tools/diagnostics/{logs-watch-start.js → logs-watch.js}

@@ -4,16 +4,19 @@
  * 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 { createWatchLifecycleTool } from './watch-lifecycle.js';
 import { matchesLevel, matchesSearch, tailLogs, } from '@salesforce/b2c-tooling-sdk/operations/logs';
 import { createToolAdapter, jsonResult } from '../adapter.js';
 import { getLogWatchRegistry } from './log-watch-registry.js';
 const DEFAULT_PREFIXES = ['error', 'customerror'];
-export function createLogsWatchStartTool(loadServices, serverContext, injections) {
+function createLogsWatchStartTool(loadServices, serverContext, injections) {
     const tailLogsFn = injections?.tailLogs ?? tailLogs;
     return createToolAdapter({
-        name: 'logs_watch_start',
-        description: 'Start a B2C log watch and return watch_id. Start before the target action, poll with logs_watch_poll, ' +
-            'and always stop with logs_watch_stop. One active watch per hostname.',
+        name: 'logs_watch',
+        effect: 'read',
+        idempotent: true,
+        openWorld: true,
+        description: 'Start, list, or stop B2C log watches. Start before the target action; read with logs_watch_poll. Stop discards unread entries; safe to repeat.',
         toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'SCAPI'],
         requiresInstance: true,
         inputSchema: {
@@ -32,11 +35,8 @@ export function createLogsWatchStartTool(loadServices, serverContext, injections
                 .int()
                 .positive()
                 .optional()
-                .describe('How often the underlying tail polls the WebDAV server. Defaults to 3000ms.'),
-            level: z
-                .array(z.string())
-                .optional()
-                .describe('Server-side filter by log level. Entries not matching are dropped before buffering.'),
+                .describe('WebDAV polling interval, in milliseconds. Default: 3000.'),
+            level: z.array(z.string()).optional().describe('Keep matching levels before buffering.'),
             search: z.string().optional().describe('Case-insensitive substring filter applied as entries arrive.'),
         },
         async execute(args, context) {
@@ -47,7 +47,7 @@ export function createLogsWatchStartTool(loadServices, serverContext, injections
             const existing = registry.findByHostname(hostname);
             if (existing) {
                 throw new Error(`A log watch already exists for ${hostname} (watch_id: "${existing.watchId}"). ` +
-                    `Stop it with logs_watch_stop first, or poll the existing watch.`);
+                    `Stop it with logs_watch(action: stop) first, or poll the existing watch.`);
             }
             const levelFilter = args.level;
             const searchFilter = args.search;
@@ -87,7 +87,7 @@ export function createLogsWatchStartTool(loadServices, serverContext, injections
                 },
             });
             // registerWatch re-checks the hostname and throws on a duplicate. If two
-            // logs_watch_start calls race past the findByHostname check above, the
+            // logs_watch(action: start) calls race past the findByHostname check above, the
             // loser's tailLogs poll is already running in the background — stop it so
             // it isn't orphaned (it would otherwise poll WebDAV until process exit).
             let entry;
@@ -114,4 +114,37 @@ export function createLogsWatchStartTool(loadServices, serverContext, injections
         formatOutput: (output) => jsonResult(output),
     }, loadServices, serverContext);
 }
-//# sourceMappingURL=logs-watch-start.js.map
+export function createLogsWatchTool(loadServices, serverContext, injections) {
+    const getRegistry = () => {
+        if (!serverContext)
+            throw new Error('Server context is required for log watches.');
+        return serverContext.logWatches;
+    };
+    return createWatchLifecycleTool(createLogsWatchStartTool(loadServices, serverContext, injections), () => {
+        return {
+            watches: getRegistry()
+                .listWatches()
+                .map((w) => ({
+                buffered_entries: w.buffer.length,
+                created_at: new Date(w.createdAt).toISOString(),
+                dropped_entries: w.droppedEntries,
+                files_discovered: w.filesDiscovered,
+                hostname: w.hostname,
+                last_activity_at: new Date(w.lastActivityAt).toISOString(),
+                prefixes: w.prefixes,
+                stopped: w.stopped,
+                total_entries_seen: w.totalEntriesSeen,
+                watch_id: w.watchId,
+                resolution: w.resolution,
+            })),
+        };
+    }, async (watchId) => {
+        const registry = getRegistry();
+        const watch = registry.getWatch(watchId);
+        const total = watch?.totalEntriesSeen ?? 0;
+        if (watch)
+            await registry.destroyWatch(watchId);
+        return { watch_id: watchId, stopped_at: new Date().toISOString(), total_entries_seen: total };
+    });
+}
+//# sourceMappingURL=logs-watch.js.map

package/dist/tools/diagnostics/mrt-log-watch-registry.js

@@ -149,7 +149,7 @@ export class MrtLogWatchRegistry {
     getWatchOrThrow(watchId) {
         const w = this.watches.get(watchId);
         if (!w) {
-            throw new Error(`No MRT log watch found with id "${watchId}". Use mrt_logs_watch_list to see active watches.`);
+            throw new Error(`No MRT log watch found with id "${watchId}". Use mrt_logs_watch(action: list) to see active watches.`);
         }
         w.lastActivityAt = Date.now();
         return w;
@@ -176,7 +176,7 @@ export class MrtLogWatchRegistry {
         const existing = this.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.`);
+                `Stop it with mrt_logs_watch(action: stop) first, or poll the existing watch.`);
         }
         const watchId = randomUUID();
         const now = Date.now();

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

@@ -11,23 +11,21 @@ const DEFAULT_MAX_ENTRIES = 200;
 export function createMrtLogsWatchPollTool(loadServices, serverContext) {
     return createToolAdapter({
         name: 'mrt_logs_watch_poll',
+        effect: 'read',
+        idempotent: true,
+        openWorld: false,
         description: 'Drain buffered MRT logs, blocking up to timeout_ms when empty. Repeat if truncated=true. ' +
             'stopped=true means the stream closed; inspect errors.',
         toolsets: ['DIAGNOSTICS', 'PWAV3', 'STOREFRONTNEXT'],
         inputSchema: {
-            watch_id: z.string().describe('Watch id from mrt_logs_watch_start.'),
+            watch_id: z.string(),
             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.'),
+                .describe('Wait when empty, in milliseconds. Default: 5000; 0 returns immediately.'),
+            max_entries: z.number().int().positive().optional().describe('Maximum entries. Default: 200.'),
         },
         async execute(args, context) {
             const registry = getMrtLogWatchRegistry(context);

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

@@ -11,4 +11,4 @@ export interface MrtLogsWatchStartInjections {
         email?: string;
     }>;
 }
-export declare function createMrtLogsWatchStartTool(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext, injections?: MrtLogsWatchStartInjections): McpTool;
+export declare function createMrtLogsWatchTool(loadServices: () => Promise<Services> | Services, serverContext?: ServerContext, injections?: MrtLogsWatchStartInjections): McpTool;