@salesforce/b2c-dx-mcp 2.1.2 → 3.0.0

package/dist/registry.js

@@ -3,68 +3,17 @@
  * 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 os from 'node:os';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { getLogger } from '@salesforce/b2c-tooling-sdk/logging';
-import { detectWorkspaceType } from '@salesforce/b2c-tooling-sdk/discovery';
 import { DOC_CATEGORIES, resolveEnabledCategories } from '@salesforce/b2c-tooling-sdk/docs';
-import { ALL_TOOLSETS, TOOLSETS, VALID_TOOLSET_NAMES } from './utils/index.js';
+import { ALL_TOOLSETS, TOOLSETS, VALID_TOOLSET_NAMES, toToolAnnotations } 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';
-/**
- * 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_TOOLSETS = ['SCAPI', 'DIAGNOSTICS'];
-/**
- * Toolset mapping by project type.
- * Each project type enables specific toolsets IN ADDITION to the base toolsets.
- */
-const PROJECT_TYPE_TOOLSETS = {
-    cartridges: ['CARTRIDGES'],
-    // SFRA is a cartridge project, so it enables the same toolset as `cartridges`.
-    // (A SFRA workspace also matches the `cartridges` marker; the union dedupes.)
-    sfra: ['CARTRIDGES'],
-    'pwa-kit-v3': ['PWAV3', 'MRT'],
-    'storefront-next': ['STOREFRONTNEXT', 'MRT', 'CARTRIDGES'],
-};
-/**
- * Gets toolsets for a project type, always including the base toolsets.
- */
-function getToolsetsForProjectType(projectType) {
-    const additionalToolsets = PROJECT_TYPE_TOOLSETS[projectType] ?? [];
-    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 + DIAGNOSTICS).
- *
- * @param projectTypes - Array of detected project types
- * @returns Union of all toolsets for the detected project types (always includes base toolsets)
- */
-function getToolsetsForProjectTypes(projectTypes) {
-    const toolsetSet = new Set();
-    // 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)) {
-            toolsetSet.add(toolset);
-        }
-    }
-    return [...toolsetSet];
-}
+import { createWebDavTools } from './tools/webdav/index.js';
+import { createCipTools } from './tools/cip/index.js';
+import { createGuidanceTool, registerGuidanceResources } from './guidance.js';
 /**
  * Creates the tool registry from all toolset providers.
  * Tools are organized by their declared `toolsets` array, allowing
@@ -80,16 +29,19 @@ export function createToolRegistry(loadServices, serverContext, detectedWorkspac
         MRT: [],
         PWAV3: [],
         SCAPI: [],
+        CIP: [],
         STOREFRONTNEXT: [],
     };
     // Collect all tools from all factories
     const allTools = [
         ...createCartridgesTools(loadServices),
+        ...createWebDavTools(loadServices),
+        ...createCipTools(loadServices),
         ...createDiagnosticsTools(loadServices, serverContext),
         ...createDocsTools(loadServices, { detectedWorkspaces, enabledCategories: enabledDocCategories }),
         ...createMrtTools(loadServices),
-        ...createPwav3Tools(loadServices),
         ...createScapiTools(loadServices),
+        createGuidanceTool(),
     ];
     // Organize tools by their declared toolsets (supports multi-toolset)
     for (const tool of allTools) {
@@ -99,91 +51,11 @@ export function createToolRegistry(loadServices, serverContext, detectedWorkspac
     }
     return registry;
 }
-/**
- * Maximum directory depth workspace auto-discovery recurses when scanning the
- * project directory. Bounding this is what keeps startup fast (and safe) when
- * the server is launched from a broad root: a full `**` walk of a home
- * directory can take many seconds and blocks the MCP handshake, since detection
- * runs before the server connects.
- *
- * Depth is counted in path segments relative to the project directory. 5 covers
- * the common layouts — a cartridge at `cartridges/<name>/.project` (depth 3) and
- * a monorepo cartridge at `packages/<app>/cartridges/<name>/.project` (depth 5) —
- * without descending into unrelated deep trees.
- */
-const DISCOVERY_MAX_DEPTH = 5;
-const MCP_PACKAGE_DIRECTORY = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-/**
- * Returns true when `dir` is a location that should never be recursively
- * scanned for a workspace: the user's home directory or a filesystem root.
- * These are the classic "MCP client spawned the server from ~" cases where an
- * unbounded (or even bounded) scan is both pointless and expensive.
- */
-function isUnscannableRoot(dir) {
-    const resolved = path.resolve(dir);
-    // Filesystem root: parent equals self (handles `/` and Windows drive roots).
-    if (path.dirname(resolved) === resolved) {
-        return true;
-    }
-    const home = os.homedir();
-    return (Boolean(home) && path.resolve(home) === resolved) || resolved === MCP_PACKAGE_DIRECTORY;
-}
-/**
- * Performs workspace auto-discovery and returns appropriate toolsets.
- * Always includes the BASE_TOOLSETS even if no project types are detected.
- *
- * The scan is depth-bounded ({@link DISCOVERY_MAX_DEPTH}) and skipped entirely
- * for home/root directories so it can never fan out across a whole home tree.
- *
- * @param flags - Startup flags containing projectDirectory
- * @returns Array of detected project types (empty if skipped or none found)
- */
-async function detectProjectTypes(flags) {
-    const logger = getLogger();
-    // Project directory from --project-directory flag or SFCC_PROJECT_DIRECTORY env
-    // var, defaulting to cwd. We always attempt detection from cwd rather than
-    // skipping it — the depth bound and home/root guard below make that safe.
-    const projectDirectory = flags.projectDirectory ?? process.cwd();
-    // Warn if project directory wasn't explicitly configured
-    if (!flags.projectDirectory) {
-        logger.warn({ cwd: projectDirectory }, 'No --project-directory flag or SFCC_PROJECT_DIRECTORY env var provided. ' +
-            'MCP clients like Cursor and Claude Code often spawn servers from ~ instead of the project directory. ' +
-            'Set --project-directory or SFCC_PROJECT_DIRECTORY for reliable auto-discovery.');
-    }
-    // Never recursively scan a home directory or filesystem root — the scan would
-    // be expensive and would not identify a meaningful workspace anyway.
-    if (isUnscannableRoot(projectDirectory)) {
-        logger.warn({ projectDirectory }, 'Project directory is a home, filesystem root, or MCP installation directory; skipping workspace auto-discovery. ' +
-            'Set --project-directory or SFCC_PROJECT_DIRECTORY to the project path to enable it.');
-        return [];
-    }
-    const detectionResult = await detectWorkspaceType(projectDirectory, { maxDepth: DISCOVERY_MAX_DEPTH });
-    logger.info({ projectTypes: detectionResult.projectTypes, matchedPatterns: detectionResult.matchedPatterns }, `Workspace detection: project types: ${detectionResult.projectTypes.join(', ') || 'none'}`);
-    return detectionResult.projectTypes;
-}
-/**
- * Register tools with the MCP server based on startup flags.
- *
- * 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_TOOLSETS (SCAPI + DIAGNOSTICS),
- * 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
- */
 // 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();
+/** Register all toolsets by default, or only explicitly selected toolsets/tools. */
 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');
@@ -191,20 +63,14 @@ export async function registerToolsets(flags, server, loadServices, serverContex
     REGISTERED_SERVERS.add(server);
     const toolsets = flags.toolsets ?? [];
     const individualTools = flags.tools ?? [];
-    const allowNonGaTools = flags.allowNonGaTools ?? false;
     const logger = getLogger();
     // Resolve the launch-time docs topic allowlist (bounds the whole docs corpus).
     const enabledDocCategories = resolveEnabledCategories(flags.docsTopics, (invalid) => logger.warn({ invalidTopics: invalid, validTopics: DOC_CATEGORIES }, `Ignoring unknown documentation topic(s) in --docs-topics: "${invalid.join('", "')}"`));
     if (enabledDocCategories) {
         logger.info({ docsTopics: enabledDocCategories }, `Documentation restricted to topics: ${enabledDocCategories.join(', ')}`);
     }
-    // Build the tool registry to validate flag input. The set of available tools
-    // (names, toolsets) does NOT depend on the detected workspace — only the docs
-    // tool descriptions do — so we can resolve flag validity before deciding
-    // whether workspace detection is even needed. If auto-discovery later runs,
-    // we rebuild the registry with the detected workspaces so the docs tools pick
-    // up the workspace hint.
-    let toolRegistry = createToolRegistry(loadServices, serverContext, [], enabledDocCategories);
+    // Tool availability is independent of the workspace. Explicit selection customizes the default catalog.
+    const toolRegistry = createToolRegistry(loadServices, serverContext, [], enabledDocCategories);
     const existingToolNames = new Set(Object.values(toolRegistry)
         .flat()
         .map((tool) => tool.name));
@@ -223,24 +89,10 @@ export async function registerToolsets(flags, server, loadServices, serverContex
     // Determine which toolsets to enable. `ALL` expands to every toolset.
     const validToolsets = toolsets.filter((t) => TOOLSETS.includes(t));
     const toolsetsToEnable = new Set(toolsets.includes(ALL_TOOLSETS) ? TOOLSETS : validToolsets);
-    // Auto-discovery: only when no valid toolsets AND no valid individual tools
-    // were provided. This handles both (1) no flags provided, and (2) all
-    // provided flags are invalid. Skip workspace detection entirely otherwise —
-    // when the user has explicitly chosen toolsets/tools, the filesystem scan
-    // cannot change which tools are registered, so paying for it (and risking a
-    // costly recursive walk) would be pointless.
     if (toolsetsToEnable.size === 0 && validIndividualTools.length === 0) {
-        const detectedWorkspaces = await detectProjectTypes(flags);
-        const discoveredToolsets = getToolsetsForProjectTypes(detectedWorkspaces);
-        logger.info({ projectTypes: detectedWorkspaces, enabledToolsets: discoveredToolsets }, `Auto-discovery: enabling toolsets ${discoveredToolsets.join(', ')}`);
-        for (const toolset of discoveredToolsets) {
+        for (const toolset of TOOLSETS)
             toolsetsToEnable.add(toolset);
-        }
-        // Rebuild so the docs tools reflect the detected workspace in their
-        // descriptions and default workspace resolution.
-        if (detectedWorkspaces.length > 0) {
-            toolRegistry = createToolRegistry(loadServices, serverContext, detectedWorkspaces, enabledDocCategories);
-        }
+        logger.info('No valid tool selection provided; enabling all toolsets.');
     }
     // Build the set of tools to register:
     // 1. Start with tools from enabled toolsets
@@ -257,7 +109,7 @@ export async function registerToolsets(flags, server, loadServices, serverContex
         }
     }
     // Step 2: Add individual tools from --tools (can be from any toolset).
-    // Look up against the final registry (which may have been rebuilt above).
+    // Individual tools can be selected without enabling their entire toolset.
     const allToolsByName = new Map(Object.values(toolRegistry)
         .flat()
         .map((tool) => [tool.name, tool]));
@@ -269,20 +121,20 @@ export async function registerToolsets(flags, server, loadServices, serverContex
         }
     }
     // Register all selected tools
-    await registerTools(toolsToRegister, server, allowNonGaTools);
+    await registerTools(toolsToRegister, server);
+    registerGuidanceResources(server, registeredToolNames.has('skills_read'));
 }
 /**
  * Register a list of tools with the server.
  */
-async function registerTools(tools, server, allowNonGaTools) {
+async function registerTools(tools, server) {
     for (const tool of tools) {
-        // Skip non-GA tools if not allowed
-        if (tool.isGA === false && !allowNonGaTools) {
-            continue;
-        }
-        // Register the tool
         // Register the tool (invocations are tracked by B2CDxMcpServer)
-        server.addTool(tool.name, tool.description, tool.inputSchema, async (args) => tool.handler(args));
+        server.addTool(tool.name, tool.description, tool.inputSchema, async (args, context) => tool.handler(args, context), {
+            title: tool.title,
+            annotations: toToolAnnotations(tool),
+            outputSchema: tool.outputSchema,
+        });
     }
 }
 //# sourceMappingURL=registry.js.map

package/dist/server.d.ts

@@ -1,13 +1,14 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { CallToolResult, Implementation } from '@modelcontextprotocol/sdk/types.js';
-import type { ServerOptions } from '@modelcontextprotocol/sdk/server/index.js';
-import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { McpServer } from '@modelcontextprotocol/server';
+import type { CallToolResult, Implementation, ReadResourceResult, ToolAnnotations, ServerOptions, Transport } from '@modelcontextprotocol/server';
 import { type ZodRawShape } from 'zod';
 import type { Telemetry } from '@salesforce/b2c-tooling-sdk/telemetry';
+import type { McpToolConfig } from './utils/types.js';
 /**
  * Extended server options.
  */
 export interface B2CDxMcpServerOptions extends ServerOptions {
+    /** Release debugger sessions and log watches owned by this server instance. */
+    cleanup?: () => Promise<void>;
     /**
      * Telemetry instance for tracking server and tool events.
      * If not provided, telemetry is disabled.
@@ -20,6 +21,10 @@ export interface B2CDxMcpServerOptions extends ServerOptions {
  * @augments {McpServer}
  */
 export declare class B2CDxMcpServer extends McpServer {
+    private readonly cleanup?;
+    private clientLogged;
+    private closePromise?;
+    private readonly resourceReaders;
     private telemetry?;
     /**
      * Creates a new B2CDxMcpServer instance
@@ -28,6 +33,8 @@ export declare class B2CDxMcpServer extends McpServer {
      * @param options - Optional server configuration
      */
     constructor(serverInfo: Implementation, options?: B2CDxMcpServerOptions);
+    /** Register after resource metadata. Resolve raw URIs before URL dot-segment normalization. */
+    addResourceReader(prefix: string, read: (uri: string) => Promise<ReadResourceResult>): void;
     /**
      * Register a tool with the server.
      *
@@ -38,9 +45,16 @@ export declare class B2CDxMcpServer extends McpServer {
      * @param inputSchema - Zod schema for input validation
      * @param handler - Function to handle tool invocations
      */
-    addTool(name: string, description: string, inputSchema: ZodRawShape, handler: (args: Record<string, unknown>) => Promise<CallToolResult>): void;
+    addTool(name: string, description: string, inputSchema: ZodRawShape, handler: (args: Record<string, unknown>, context?: {
+        signal?: AbortSignal;
+    }) => Promise<CallToolResult>, metadata?: Pick<McpToolConfig, 'outputSchema' | 'title'> & {
+        annotations?: ToolAnnotations;
+    }): void;
+    close(): Promise<void>;
     /**
      * Connect to a transport.
      */
     connect(transport: Transport): Promise<void>;
+    private logClient;
+    private logRequestClient;
 }

package/dist/server.js

@@ -3,8 +3,7 @@
  * 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
  */
-// eslint-disable-next-line import/no-unresolved -- SDK 1.30's types export misresolves runtime .js subpaths.
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { McpServer, ProtocolError, ProtocolErrorCode, CLIENT_INFO_META_KEY, PROTOCOL_VERSION_META_KEY, } from '@modelcontextprotocol/server';
 import { z } from 'zod';
 import { getLogger } from '@salesforce/b2c-tooling-sdk/logging';
 /**
@@ -13,6 +12,10 @@ import { getLogger } from '@salesforce/b2c-tooling-sdk/logging';
  * @augments {McpServer}
  */
 export class B2CDxMcpServer extends McpServer {
+    cleanup;
+    clientLogged = false;
+    closePromise;
+    resourceReaders = new Map();
     telemetry;
     /**
      * Creates a new B2CDxMcpServer instance
@@ -21,11 +24,14 @@ export class B2CDxMcpServer extends McpServer {
      * @param options - Optional server configuration
      */
     constructor(serverInfo, options) {
-        super(serverInfo, options);
-        this.telemetry = options?.telemetry;
+        const { cleanup, telemetry, ...serverOptions } = options ?? {};
+        super(serverInfo, serverOptions);
+        this.cleanup = cleanup;
+        this.telemetry = telemetry;
         // Set up oninitialized handler
         this.server.oninitialized = () => {
             const clientInfo = this.server.getClientVersion();
+            this.logClient(clientInfo);
             if (clientInfo) {
                 this.telemetry?.addAttributes({
                     clientName: clientInfo.name,
@@ -34,6 +40,19 @@ export class B2CDxMcpServer extends McpServer {
             }
         };
     }
+    /** Register after resource metadata. Resolve raw URIs before URL dot-segment normalization. */
+    addResourceReader(prefix, read) {
+        this.resourceReaders.set(prefix, read);
+        this.server.setRequestHandler('resources/read', async (request, context) => {
+            this.logRequestClient(context);
+            const uri = request.params.uri;
+            for (const [registeredPrefix, reader] of this.resourceReaders) {
+                if (uri.startsWith(registeredPrefix))
+                    return reader(uri);
+            }
+            throw new ProtocolError(ProtocolErrorCode.InvalidParams, 'Resource URI is not available.');
+        });
+    }
     /**
      * Register a tool with the server.
      *
@@ -44,11 +63,14 @@ export class B2CDxMcpServer extends McpServer {
      * @param inputSchema - Zod schema for input validation
      * @param handler - Function to handle tool invocations
      */
-    addTool(name, description, inputSchema, handler) {
-        const wrappedHandler = async (args, _extra) => {
+    addTool(name, description, inputSchema, handler, metadata = {}) {
+        const wrappedHandler = async (args, context) => {
+            const clientInfo = this.logRequestClient(context);
+            if (clientInfo)
+                this.telemetry?.addAttributes({ clientName: clientInfo.name, clientVersion: clientInfo.version });
             const startTime = Date.now();
             try {
-                const result = await handler(args);
+                const result = await handler(args, { signal: context.mcpReq?.signal });
                 const runTimeMs = Date.now() - startTime;
                 // Extract error message from CallToolResult content when isError is true
                 const errorMessage = result.isError ? result.content?.find((c) => c.type === 'text')?.text : undefined;
@@ -81,13 +103,31 @@ export class B2CDxMcpServer extends McpServer {
             }
         };
         // Use the new registerTool API (tool() is deprecated)
-        this.registerTool(name, { description, inputSchema: z.object(inputSchema).strict() }, wrappedHandler);
+        this.registerTool(name, {
+            description,
+            inputSchema: z.object(inputSchema).strict(),
+            ...metadata,
+            outputSchema: metadata.outputSchema ? z.object(metadata.outputSchema) : undefined,
+        }, wrappedHandler);
+    }
+    close() {
+        this.closePromise ??= (async () => {
+            try {
+                await this.cleanup?.();
+            }
+            finally {
+                await super.close();
+            }
+        })();
+        return this.closePromise;
     }
     /**
      * Connect to a transport.
      */
     async connect(transport) {
         try {
+            if (this.isConnected())
+                throw new Error('Already connected to a transport. Create a new server instance.');
             await super.connect(transport);
             const statusPromise = this.isConnected()
                 ? this.telemetry?.sendEventAndFlush('SERVER_STATUS', { status: 'started' })
@@ -106,5 +146,22 @@ export class B2CDxMcpServer extends McpServer {
             throw error;
         }
     }
+    logClient(clientInfo, protocolVersion) {
+        if (this.clientLogged)
+            return;
+        getLogger().debug({
+            protocolEra: protocolVersion ? 'modern' : 'legacy',
+            protocolVersion,
+            clientName: clientInfo?.name,
+            clientVersion: clientInfo?.version,
+        }, 'MCP client connected');
+        this.clientLogged = true;
+    }
+    logRequestClient(context) {
+        const envelope = context.mcpReq?.envelope;
+        if (envelope)
+            this.logClient(envelope[CLIENT_INFO_META_KEY], envelope[PROTOCOL_VERSION_META_KEY]);
+        return envelope?.[CLIENT_INFO_META_KEY];
+    }
 }
 //# sourceMappingURL=server.js.map

package/dist/skill-references.d.ts

@@ -0,0 +1,28 @@
+/** Optional detail for an observed condition; never a prerequisite or approval. */
+export interface SkillReference {
+    uri: string;
+    section: string;
+}
+/** Targets must resolve through resources even when skills_read is not selected. */
+export declare const MCP_SKILL_REFERENCES: {
+    configSources: {
+        uri: string;
+        section: string;
+    };
+    debuggerPrerequisites: {
+        uri: string;
+        section: string;
+    };
+    debuggerRecovery: {
+        uri: string;
+        section: string;
+    };
+    scapiAuthentication: {
+        uri: string;
+        section: string;
+    };
+    cipAccess: {
+        uri: string;
+        section: string;
+    };
+};

package/dist/skill-references.js

@@ -0,0 +1,14 @@
+/*
+ * 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
+ */
+/** Targets must resolve through resources even when skills_read is not selected. */
+export const MCP_SKILL_REFERENCES = {
+    configSources: { uri: 'skill://mcp/b2c-config/SKILL.md', section: 'where-configuration-comes-from' },
+    debuggerPrerequisites: { uri: 'skill://mcp/debugger/SKILL.md', section: 'prerequisites' },
+    debuggerRecovery: { uri: 'skill://mcp/debugger/SKILL.md', section: 'recovery' },
+    scapiAuthentication: { uri: 'skill://mcp/scapi/SKILL.md', section: 'authentication' },
+    cipAccess: { uri: 'skill://mcp/cip/SKILL.md', section: 'configuration-and-access' },
+};
+//# sourceMappingURL=skill-references.js.map

package/dist/tools/adapter.d.ts

@@ -26,6 +26,7 @@
  * ```typescript
  * const myTool = createToolAdapter({
  *   name: 'my_tool',
+ *   effect: 'read', idempotent: true, openWorld: true,
  *   description: 'Does something useful',
  *   toolsets: ['CARTRIDGES'],
  *   requiresInstance: true,
@@ -50,6 +51,7 @@
  *
  * const mrtTool = createToolAdapter({
  *   name: 'mrt_bundle_push',
+ *   effect: 'write', idempotent: false, openWorld: true,
  *   description: 'Push bundle to MRT',
  *   toolsets: ['MRT'],
  *   requiresMrtAuth: true,
@@ -66,7 +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 { McpTool, ToolEffects, ToolResult, Toolset } from '../utils/index.js';
 import type { Services, MrtConfig } from '../services.js';
 import type { ServerContext } from '../server-context.js';
 import { type DirectoryResolutionInfo, type ProjectContextInput, type ToolResolution } from './project-context.js';
@@ -111,7 +113,10 @@ export interface ToolExecutionContext {
  * @template TInput - The validated input type (inferred from inputSchema)
  * @template TOutput - The output type from the execute function
  */
-export interface ToolAdapterOptions<TInput, TOutput> {
+export interface ToolAdapterOptions<TInput, TOutput> extends ToolEffects {
+    /** Registration metadata is preserved independently of result enrichment. */
+    title?: McpTool['title'];
+    outputSchema?: McpTool['outputSchema'];
     /** Tool name (used in MCP protocol) */
     name: string;
     /** Human-readable description */
@@ -120,8 +125,6 @@ export interface ToolAdapterOptions<TInput, TOutput> {
     inputSchema: ZodRawShape;
     /** Toolsets this tool belongs to */
     toolsets: Toolset[];
-    /** Whether this tool is GA (generally available). Defaults to true. */
-    isGA?: boolean;
     /**
      * Whether this tool requires a B2CInstance.
      * Set to false for tools that don't need B2C instance connectivity (e.g., local scaffolding tools).
@@ -195,7 +198,7 @@ export declare function errorResult(message: string): ToolResult;
  */
 export declare function jsonResult(data: unknown, indent?: number): ToolResult;
 /** Attach compact resolution provenance while preserving existing tool output. */
-export declare function attachResolution(result: ToolResult, resolution: ToolResolution): ToolResult;
+export declare function attachResolution(result: ToolResult, resolution: ToolResolution, indent?: number): ToolResult;
 /**
  * Creates an MCP tool from a b2c-tooling function.
  *

package/dist/tools/adapter.js

@@ -31,6 +31,7 @@
  * ```typescript
  * const myTool = createToolAdapter({
  *   name: 'my_tool',
+ *   effect: 'read', idempotent: true, openWorld: true,
  *   description: 'Does something useful',
  *   toolsets: ['CARTRIDGES'],
  *   requiresInstance: true,
@@ -55,6 +56,7 @@
  *
  * const mrtTool = createToolAdapter({
  *   name: 'mrt_bundle_push',
+ *   effect: 'write', idempotent: false, openWorld: true,
  *   description: 'Push bundle to MRT',
  *   toolsets: ['MRT'],
  *   requiresMrtAuth: true,
@@ -122,16 +124,22 @@ export function jsonResult(data, indent = 2) {
     };
 }
 /** Attach compact resolution provenance while preserving existing tool output. */
-export function attachResolution(result, resolution) {
+export function attachResolution(result, resolution, indent = 2) {
     let content = result.content;
-    let structuredContent = { ...result.structuredContent, resolution };
+    const original = result.structuredContent;
+    const structured = original !== null && typeof original === 'object' && !Array.isArray(original)
+        ? original
+        : original === undefined
+            ? {}
+            : { value: original };
+    let structuredContent = { ...structured, resolution };
     if (content.length === 1 && content[0]?.type === 'text') {
         try {
             const parsed = JSON.parse(content[0].text);
             if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
                 const output = { ...parsed, resolution };
-                content = [{ ...content[0], text: JSON.stringify(output, null, 2) }];
-                structuredContent = { ...output, ...result.structuredContent, resolution };
+                content = [{ ...content[0], text: JSON.stringify(output, null, indent) }];
+                structuredContent = { ...output, ...structured, resolution };
             }
         }
         catch {
@@ -147,7 +155,7 @@ export function attachResolution(result, resolution) {
  * @returns Formatted error message
  */
 function formatZodErrors(error) {
-    return error.errors.map((e) => `${e.path.join('.') || 'input'}: ${e.message}`).join('; ');
+    return error.issues.map((e) => `${e.path.join('.') || 'input'}: ${e.message}`).join('; ');
 }
 /**
  * Creates an MCP tool from a b2c-tooling function.
@@ -189,7 +197,7 @@ function formatZodErrors(error) {
  * ```
  */
 export function createToolAdapter(options, loadServices, serverContext) {
-    const { name, description, inputSchema, toolsets, isGA = true, requiresInstance = false, requiresMrtAuth = false, usesProjectContext = false, usesConfigurationContext = false, execute, formatOutput, } = options;
+    const { name, description, inputSchema, toolsets, requiresInstance = false, requiresMrtAuth = false, usesProjectContext = false, usesConfigurationContext = false, execute, formatOutput, } = options;
     const projectContextKind = requiresInstance || requiresMrtAuth || usesConfigurationContext
         ? 'configuration'
         : usesProjectContext
@@ -207,8 +215,12 @@ export function createToolAdapter(options, loadServices, serverContext) {
         name,
         description,
         inputSchema: effectiveInputSchema,
+        title: options.title,
+        effect: options.effect,
+        idempotent: options.idempotent,
+        openWorld: options.openWorld,
+        outputSchema: options.outputSchema,
         toolsets,
-        isGA,
         async handler(rawArgs) {
             // 1. Validate input with Zod
             const parseResult = zodSchema.safeParse(rawArgs);