@salesforce/b2c-dx-mcp 2.1.2 → 3.0.0

package/dist/tools/scapi/scapi-code.js

@@ -0,0 +1,237 @@
+/*
+ * 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 { randomUUID } from 'node:crypto';
+import { loadScapiSchemas, runScapiCode, createScapiRequest, createScapiAuth, loadScapiSnippets, saveScapiSnippet, } from '@salesforce/b2c-tooling-sdk/scapi';
+import { toOrganizationId } from '@salesforce/b2c-tooling-sdk/clients';
+import { getB2CConfigDirectory } from '@salesforce/b2c-tooling-sdk/config';
+import { resolveEffectiveSafetyConfig, loadGlobalSafetyConfig } from '@salesforce/b2c-tooling-sdk/safety';
+import { createProjectContextInputSchema } from '../project-context.js';
+import { jsonResult, attachResolution } from '../adapter.js';
+import { MCP_SKILL_REFERENCES } from '../../skill-references.js';
+const code = z
+    .string()
+    .min(1)
+    .max(32_768)
+    .describe('JavaScript async arrow function. Return concise JSON. No filesystem or shell access.');
+const skillRead = z.boolean().optional().describe('True after reading the linked SCAPI skill.');
+const snippetDescription = `\nSnippets: await codemode.search(query) returns up to 10 names/descriptions/effects; await codemode.describe(name) returns source/inputSchema. Prefixes: builtin/, user/.`;
+function requireScapiSkill(read) {
+    if (read !== true)
+        throw new Error('SCAPI_SKILL_REQUIRED: Read skill://mcp/scapi/SKILL.md through resources or skills_read, then retry with skillRead: true.');
+}
+const searchDescription = `Discover bundled Admin/Shopper SCAPI contracts offline. Prefer dedicated tools when available.
+Read skill://mcp/scapi/SKILL.md first.
+
+Schemas can be huge. Discover operation IDs/paths first; then select required and task-relevant fields. Avoid whole operations or request/response trees. Local refs are expanded; recursive/deep refs remain $ref.
+
+Code objects (execute JavaScript, not these types):
+interface Operation {
+  api: string; operationId: string; summary?: string;
+  parameters: Array<{name: string; in: string; required?: boolean; schema?: unknown}>;
+  requestBody?: {required?: boolean; content: Record<string, {schema: any}>};
+  responses?: Record<string, unknown>;
+  security: Array<Record<string, string[]>>;
+  auth: {types: string[]; schemes: string[]; executable: boolean}; // runtime support, not configured access
+}
+declare const spec: {
+  apis: Array<{id: string; apiFamily: string; apiName: string; apiVersion: string; authTypes: string[]}>;
+  paths: Record<string, Record<string, Operation>>; // full paths, lowercase HTTP methods
+};
+
+Examples:
+// Find product operations
+async () => Object.entries(spec.paths)
+  .filter(([path]) => path.startsWith('/product/products/'))
+  .flatMap(([path, methods]) => Object.entries(methods)
+    .map(([method, op]) => ({method, path, operationId: op.operationId})))
+
+// Inspect only fields needed for creation
+async () => {
+  const op = spec.paths['/product/products/v1/organizations/{organizationId}/products/{productId}'].put;
+  const body = op.requestBody.content['application/json'].schema;
+  const fields = [...new Set([...(body.required ?? []), 'name', 'owningCatalogId', 'onlineFlag'])];
+  return {parameters: op.parameters, required: body.required,
+    fields: Object.fromEntries(fields.map(k => [k, body.properties[k]])), auth: op.auth, security: op.security};
+}`;
+const executeDescription = `Read, create, update, or delete Commerce records through SCAPI Admin APIs when no dedicated tool fits. Discover standard endpoints with scapi_search; for custom APIs, fetch the live contract through scapi.request() in the same program first. Requests authenticate automatically. JSON requests; no Shopper execution or binary transfers.
+Read skill://mcp/scapi/SKILL.md first.
+
+Reuse workflows with await codemode.run(name, input); describe before first use. Snippets share this execution's limits and configuration. async (input) receives the tool's input. executionId enables scapi_snippet_save; inspect the outcome before saving.
+
+Available in your code:
+declare const organizationId: string | undefined; // resolved tenant
+declare const siteId: string | undefined; // configured site
+declare const scapi: {
+  request(options: {method: string; path: string; query?: Record<string, unknown>; body?: unknown}):
+    Promise<{status: number; ok: boolean; data: any; diagnostic?: {code: string; message: string}}>;
+};
+
+Compose known dependent requests in one async arrow function; await requests and pass intermediate results directly. Responses can be huge: filter/map/slice in code; return counts, selected rows, and verification fields. Preserve failures and diagnostics. HTTP failures return ok:false; transport/auth/safety failures throw. SDK safety governs scapi.request. fetch/WebSocket are disabled. Optional auth.accountManager()/auth.slas() export tokens for external clients; see skill. Check writes before retrying.
+
+Example: inspect a campaign's promotions
+async () => codemode.run('builtin/campaign-promotions', {campaignId: 'selected-campaign', limit: 4})`;
+function codeResult(data, resolution) {
+    const result = resolution ? attachResolution(jsonResult(data, 0), resolution, 0) : jsonResult(data, 0);
+    // Code-mode payloads are arbitrary JSON: retain provenance without duplicating the result.
+    delete result.structuredContent;
+    return result;
+}
+function failure(error, resolution) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+        ...codeResult({
+            error: message,
+            ...(/^SCAPI_(ADMIN_|SHOPPER_|AUTH_|SCOPE_)/.test(message)
+                ? { skillReferences: [MCP_SKILL_REFERENCES.scapiAuthentication] }
+                : {}),
+        }, resolution),
+        isError: true,
+    };
+}
+export function createScapiCodeTools(loadServices, snippetDirectory) {
+    // Retain only source for the last 50 completed executions, until this server ends.
+    const executions = new Map();
+    const searchInput = {
+        code,
+        skillRead,
+        api: z.string().optional().describe('Limit schemas to family/name/version. Omit for all standard APIs.'),
+        authType: z
+            .enum(['admin', 'shopper'])
+            .optional()
+            .describe('Filter operations by authentication; mixed operations match either.'),
+    };
+    const executeInput = {
+        ...createProjectContextInputSchema('configuration'),
+        code,
+        skillRead,
+        input: z.unknown().optional().describe('JSON input for async (input); kept separate from saved source.'),
+    };
+    const saveInput = {
+        executionId: z.string().uuid(),
+        name: z.string().regex(/^user\/[a-z0-9][a-z0-9-]{0,79}$/),
+        description: z.string().min(1).max(500),
+        effect: z.enum(['read', 'write', 'destructive']),
+        inputSchema: z.record(z.string(), z.unknown()).describe('JSON Schema for the parameterized program input.'),
+    };
+    return [
+        {
+            name: 'scapi_search',
+            title: 'SCAPI Spec Search',
+            description: searchDescription + snippetDescription,
+            inputSchema: searchInput,
+            toolsets: ['SCAPI', 'PWAV3', 'STOREFRONTNEXT'],
+            effect: 'read',
+            idempotent: true,
+            openWorld: false,
+            async handler(args, context) {
+                try {
+                    const input = z.object(searchInput).strict().parse(args);
+                    requireScapiSkill(input.skillRead);
+                    const documents = loadScapiSchemas().filter((document) => !input.api || document.entry.id === input.api);
+                    if (documents.length === 0)
+                        throw new Error('Unknown schema ID. Omit api to discover available APIs.');
+                    return codeResult({
+                        result: await runScapiCode({
+                            code: input.code,
+                            documents,
+                            authType: input.authType,
+                            signal: context?.signal,
+                            timeoutMs: 10_000,
+                            snippets: loadScapiSnippets(snippetDirectory),
+                        }),
+                    });
+                }
+                catch (error) {
+                    return failure(error);
+                }
+            },
+        },
+        {
+            name: 'scapi_execute',
+            title: 'SCAPI Code Executor',
+            description: executeDescription + snippetDescription,
+            inputSchema: executeInput,
+            toolsets: ['SCAPI', 'PWAV3', 'STOREFRONTNEXT'],
+            effect: 'destructive',
+            idempotent: false,
+            openWorld: true,
+            async handler(args, context) {
+                let resolution;
+                try {
+                    const input = z.object(executeInput).strict().parse(args);
+                    requireScapiSkill(input.skillRead);
+                    const services = await loadServices(input);
+                    resolution = services.getResolution();
+                    const config = services.getResolvedConfig();
+                    const { shortCode, tenantId, siteId } = config.values;
+                    const safetyEnvironment = Object.fromEntries(['SFCC_SAFETY_LEVEL', 'SFCC_SAFETY_CONFIRM', 'SFCC_SAFETY_CONFIG'].map((name) => [
+                        name,
+                        services.getEnvironmentVariable(name),
+                    ]));
+                    let managedRequest;
+                    const request = async (options, signal) => {
+                        if (!shortCode || !tenantId)
+                            throw new Error('SCAPI requires configured shortCode and tenantId. Use config_inspect.');
+                        managedRequest ??= createScapiRequest({
+                            shortCode,
+                            tenantId,
+                            siteId,
+                            auth: () => config.createOAuth(),
+                            documents: loadScapiSchemas(),
+                            safety: resolveEffectiveSafetyConfig(config.values.safety, loadGlobalSafetyConfig(getB2CConfigDirectory(), safetyEnvironment, resolution?.projectDirectory?.path), safetyEnvironment),
+                        });
+                        return managedRequest(options, signal);
+                    };
+                    const result = await runScapiCode({
+                        code: input.code,
+                        request,
+                        auth: createScapiAuth(config.values, resolution.projectDirectory?.path),
+                        organizationId: tenantId ? toOrganizationId(tenantId) : undefined,
+                        siteId,
+                        cwd: resolution.projectDirectory?.path,
+                        signal: context?.signal,
+                        input: input.input,
+                        snippets: loadScapiSnippets(snippetDirectory),
+                    });
+                    const executionId = randomUUID();
+                    executions.set(executionId, input.code);
+                    if (executions.size > 50)
+                        executions.delete(executions.keys().next().value);
+                    return codeResult({ result, executionId }, resolution);
+                }
+                catch (error) {
+                    return failure(error, resolution);
+                }
+            },
+        },
+        {
+            name: 'scapi_snippet_save',
+            title: 'Save SCAPI Workflow',
+            description: 'Save a completed execution as a reusable user/ snippet only when the user asks. Inspect its outcome and source first; source must take variable values through input and contain no credentials. Saves source and metadata, not input or results. Existing names are not overwritten.',
+            inputSchema: saveInput,
+            toolsets: ['SCAPI', 'PWAV3', 'STOREFRONTNEXT'],
+            effect: 'write',
+            idempotent: false,
+            openWorld: false,
+            async handler(args) {
+                try {
+                    const input = z.object(saveInput).strict().parse(args);
+                    const source = executions.get(input.executionId);
+                    if (!source)
+                        throw new Error('SCAPI_EXECUTION_NOT_FOUND: only the last 50 completed executions in this server session can be saved. Do not replay writes just to save a snippet.');
+                    const { executionId: _, ...metadata } = input;
+                    saveScapiSnippet({ ...metadata, code: source }, snippetDirectory);
+                    return codeResult({ result: { name: input.name, saved: true } });
+                }
+                catch (error) {
+                    return failure(error);
+                }
+            },
+        },
+    ];
+}
+//# sourceMappingURL=scapi-code.js.map

package/dist/tools/scapi/scapi-custom-apis-get-status.js

@@ -82,9 +82,11 @@ function buildResponse(withMeta, args, columnList, activeCodeVersion) {
 export function createScapiCustomApisStatusTool(loadServices) {
     return createToolAdapter({
         name: 'scapi_custom_apis_get_status',
+        effect: 'read',
+        idempotent: true,
+        openWorld: true,
         description: 'List Custom SCAPI endpoint registration status per site. Supports filtering, grouping, and selected columns. Requires shortCode, tenantId, and sfcc.custom-apis scope. Use scapi_schemas_list for schemas.',
         toolsets: ['PWAV3', 'SCAPI', 'STOREFRONTNEXT'],
-        isGA: true,
         requiresInstance: false,
         usesConfigurationContext: true,
         inputSchema: {

package/dist/tools/scapi/scapi-schemas-list.js

@@ -64,6 +64,7 @@ async function fetchSpecificSchema(params) {
     const { data, error, response } = await client.GET('/organizations/{organizationId}/schemas/{apiFamily}/{apiName}/{apiVersion}', {
         params: {
             path: { organizationId, apiFamily: apiFamily, apiName: apiName, apiVersion: apiVersion },
+            query: args.expandCustomProperties === false ? undefined : { expand: 'custom_properties' },
         },
     });
     if (error) {
@@ -194,9 +195,11 @@ function getAvailableFilters(schemas) {
 export function createScapiSchemasListTool(loadServices) {
     return createToolAdapter({
         name: 'scapi_schemas_list',
+        effect: 'read',
+        idempotent: true,
+        openWorld: true,
         description: 'List SCAPI schema metadata or fetch an OpenAPI schema. Fetch requires includeSchemas, apiFamily, apiName, and apiVersion. Use scapi_custom_apis_get_status for endpoint status.',
         toolsets: ['PWAV3', 'SCAPI', 'STOREFRONTNEXT'],
-        isGA: true,
         requiresInstance: false, // SCAPI uses OAuth directly, doesn't need B2CInstance (hostname)
         usesConfigurationContext: true,
         inputSchema: {
@@ -215,6 +218,10 @@ export function createScapiSchemasListTool(loadServices) {
                 .boolean()
                 .default(false)
                 .describe('Return full uncompressed schema. Only when includeSchemas=true. Default: false.'),
+            expandCustomProperties: z
+                .boolean()
+                .default(true)
+                .describe('Include tenant custom property definitions when fetching a schema.'),
         },
         async execute(args, { services: svc }) {
             // Get client and organization ID

package/dist/tools/webdav/files.d.ts

@@ -0,0 +1,14 @@
+export declare const MAX_FILE_BYTES: number;
+/** Accept server-returned job paths as well as paths relative to WebDAV Sites. */
+export declare function webdavPath(input: string): string;
+/** Bound downloads even when the response omits or misstates Content-Length. */
+export declare function readFileResponse(response: Response, maxBytes?: number): Promise<Buffer>;
+/** Decode complete UTF-8 characters and leave any split trailing character for the next range. */
+export declare function readTextRange(response: Response, offset: number, maxBytes: number): Promise<{
+    content: string;
+    size: number;
+    offset: number;
+    bytesRead: number;
+    nextOffset: number | null;
+}>;
+export declare function readLocalFile(path: string): Promise<Buffer>;

package/dist/tools/webdav/files.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
+ */
+/* eslint-disable no-await-in-loop -- Streaming reads must advance sequentially. */
+import { open } from 'node:fs/promises';
+import { WEBDAV_ROOTS } from '@salesforce/b2c-tooling-sdk/cli';
+export const MAX_FILE_BYTES = 64 * 1024 * 1024;
+/** Accept server-returned job paths as well as paths relative to WebDAV Sites. */
+export function webdavPath(input) {
+    const stripped = input.replace(/^\/(?:on\/demandware.servlet\/webdav\/)?Sites\//i, '').replace(/^\//, '');
+    const parts = stripped
+        .replace(/\/$/, '')
+        .split('/')
+        .map((part) => decodeURIComponent(part));
+    // eslint-disable-next-line no-control-regex -- Reject control characters in remote paths.
+    if (parts.some((part) => !part || part === '.' || part === '..' || /[\\/\u0000-\u001F%?#:]/.test(part))) {
+        throw new Error('Use a WebDAV path without URLs, traversal, or query parameters.');
+    }
+    const root = Object.values(WEBDAV_ROOTS).find((value) => value.toLowerCase() === parts[0].toLowerCase());
+    if (!root)
+        throw new Error(`Start the path with ${Object.values(WEBDAV_ROOTS).join(', ')}.`);
+    return [root, ...parts.slice(1)].map((part) => encodeURIComponent(part)).join('/');
+}
+/** Bound downloads even when the response omits or misstates Content-Length. */
+export async function readFileResponse(response, maxBytes = MAX_FILE_BYTES) {
+    const limitMessage = maxBytes === MAX_FILE_BYTES
+        ? 'File exceeds the 64 MiB transfer limit.'
+        : 'Server exceeded the requested byte range. Use outputPath to download the file.';
+    if (!response.ok) {
+        await response.body?.cancel();
+        throw new Error(`WebDAV HTTP ${response.status} ${response.statusText}. Check the path and WebDAV permissions.`);
+    }
+    const declared = Number(response.headers.get('content-length'));
+    if (declared > maxBytes) {
+        await response.body?.cancel();
+        throw new Error(limitMessage);
+    }
+    const reader = response.body?.getReader();
+    if (!reader)
+        return Buffer.alloc(0);
+    const chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > maxBytes)
+                throw new Error(limitMessage);
+            chunks.push(Buffer.from(value));
+        }
+    }
+    finally {
+        await reader.cancel();
+    }
+    return Buffer.concat(chunks, size);
+}
+/** Decode complete UTF-8 characters and leave any split trailing character for the next range. */
+export async function readTextRange(response, offset, maxBytes) {
+    const range = /^bytes (\d+)-(\d+)\/(\d+)$/.exec(response.headers.get('content-range') ?? '');
+    const beyondEnd = /^bytes \*\/(\d+)$/.exec(response.headers.get('content-range') ?? '');
+    if (response.status === 416 && beyondEnd && offset >= Number(beyondEnd[1])) {
+        await response.body?.cancel();
+        return { content: '', size: Number(beyondEnd[1]), offset, bytesRead: 0, nextOffset: null };
+    }
+    if ((response.status === 206 && (!range || Number(range[1]) !== offset)) ||
+        (response.status === 200 && offset !== 0)) {
+        await response.body?.cancel();
+        throw new Error('Server did not honor the requested byte range. Use outputPath to download the file.');
+    }
+    const data = await readFileResponse(response, maxBytes);
+    const size = range ? Number(range[3]) : data.length;
+    if (range && (Number(range[2]) + 1 !== offset + data.length || Number(range[2]) >= size)) {
+        throw new Error('Incomplete or invalid WebDAV byte range. Inspect the file size before retrying.');
+    }
+    let content;
+    try {
+        content = new TextDecoder('utf8', { fatal: true, ignoreBOM: true }).decode(data, {
+            stream: offset + data.length < size,
+        });
+    }
+    catch {
+        throw new Error('Range is not valid UTF-8 text. Use a returned nextOffset, or outputPath for a binary download.');
+    }
+    if (content.includes('\0'))
+        throw new Error('File appears binary. Use outputPath to download it.');
+    const end = offset + Buffer.byteLength(content);
+    return { content, size, offset, bytesRead: data.length, nextOffset: end < size ? end : null };
+}
+export async function readLocalFile(path) {
+    const file = await open(path, 'r');
+    try {
+        const stat = await file.stat();
+        if (!stat.isFile() || stat.size > MAX_FILE_BYTES)
+            throw new Error('Source must be a file of at most 64 MiB.');
+        // Read one byte past the limit to detect a growing file without unbounded allocation.
+        const chunks = [];
+        let size = 0;
+        while (true) {
+            const buffer = Buffer.alloc(Math.min(64 * 1024, MAX_FILE_BYTES + 1 - size));
+            const { bytesRead } = await file.read(buffer);
+            if (!bytesRead)
+                break;
+            size += bytesRead;
+            if (size > MAX_FILE_BYTES)
+                throw new Error('Source exceeds the 64 MiB transfer limit.');
+            chunks.push(buffer.subarray(0, bytesRead));
+        }
+        return Buffer.concat(chunks, size);
+    }
+    finally {
+        await file.close();
+    }
+}
+//# sourceMappingURL=files.js.map

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

@@ -0,0 +1,3 @@
+import type { McpTool } from '../../utils/index.js';
+import { type ServicesLoader } from '../adapter.js';
+export declare function createWebDavTools(loadServices: ServicesLoader): McpTool[];

package/dist/tools/webdav/index.js

@@ -0,0 +1,160 @@
+/*
+ * 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 { writeFile } from 'node:fs/promises';
+import { z } from 'zod';
+import { createToolAdapter, jsonResult } from '../adapter.js';
+import { readFileResponse, readLocalFile, readTextRange, webdavPath } from './files.js';
+const pathSchema = z
+    .string()
+    .min(1)
+    .max(2048)
+    .describe('WebDAV Sites-relative path, e.g. Logs/jobs/run.log or Impex/src/import.xml.');
+export function createWebDavTools(loadServices) {
+    return [
+        createToolAdapter({
+            name: 'webdav_list',
+            effect: 'read',
+            idempotent: true,
+            openWorld: true,
+            description: 'List one WebDAV directory with file metadata and pagination. Does not recurse.',
+            toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'SCAPI'],
+            requiresInstance: true,
+            inputSchema: {
+                path: pathSchema,
+                offset: z.number().int().min(0).default(0),
+                limit: z.number().int().min(1).max(100).default(20),
+            },
+            async execute(args, context) {
+                const path = webdavPath(args.path);
+                const entries = (await context.b2cInstance.webdav.propfind(path, '1'))
+                    .map((entry) => {
+                    const pathname = new URL(entry.href, 'https://webdav.invalid').pathname;
+                    return {
+                        path: decodeURIComponent(webdavPath(pathname)),
+                        isCollection: entry.isCollection,
+                        contentLength: entry.contentLength,
+                        lastModified: entry.lastModified,
+                        contentType: entry.contentType,
+                    };
+                })
+                    .filter((entry) => webdavPath(entry.path) !== path)
+                    .sort((a, b) => a.path.localeCompare(b.path));
+                const files = entries.slice(args.offset, args.offset + args.limit);
+                const end = args.offset + files.length;
+                return {
+                    path: decodeURIComponent(path),
+                    total: entries.length,
+                    files,
+                    nextOffset: files.length > 0 && end < entries.length ? end : null,
+                };
+            },
+            formatOutput: jsonResult,
+        }, loadServices),
+        createToolAdapter({
+            name: 'webdav_get',
+            effect: 'read',
+            idempotent: true,
+            openWorld: true,
+            description: 'Read exact WebDAV text using HTTP byte ranges, or download a whole file to the MCP host (maximum 64 MiB).',
+            toolsets: ['CARTRIDGES', 'DIAGNOSTICS', 'SCAPI'],
+            requiresInstance: true,
+            inputSchema: {
+                path: pathSchema,
+                offset: z
+                    .number()
+                    .int()
+                    .min(0)
+                    .default(0)
+                    .describe('Byte offset for text; continue with returned nextOffset.'),
+                maxBytes: z.number().int().min(4).max(8000).default(4000),
+                outputPath: z
+                    .string()
+                    .min(1)
+                    .optional()
+                    .describe('Optional new file on the MCP host, relative to projectDirectory. Never overwrites.'),
+            },
+            async execute(args, context) {
+                const path = webdavPath(args.path);
+                if (args.outputPath && args.offset !== 0)
+                    throw new Error('outputPath downloads the whole file; omit offset.');
+                const response = await context.b2cInstance.webdav.request(path, {
+                    method: 'GET',
+                    redirect: 'error',
+                    signal: AbortSignal.timeout(30_000),
+                    ...(args.outputPath ? {} : { headers: { Range: `bytes=${args.offset}-${args.offset + args.maxBytes - 1}` } }),
+                });
+                const metadata = {
+                    path: decodeURIComponent(path),
+                    contentType: response.headers.get('content-type'),
+                    etag: response.headers.get('etag'),
+                    lastModified: response.headers.get('last-modified'),
+                };
+                if (args.outputPath) {
+                    const data = await readFileResponse(response);
+                    const outputPath = context.services.resolveWithProjectDirectory(args.outputPath, args.projectDirectory);
+                    await writeFile(outputPath, data, { flag: 'wx', mode: 0o600 });
+                    return { ...metadata, size: data.length, outputPath };
+                }
+                return { ...metadata, ...(await readTextRange(response, args.offset, args.maxBytes)) };
+            },
+            formatOutput: jsonResult,
+        }, loadServices),
+        createToolAdapter({
+            name: 'webdav_put',
+            effect: 'destructive',
+            idempotent: true,
+            openWorld: true,
+            description: 'Upload one WebDAV file from text or a local file on the MCP host. Parent directory must exist. Replacement requires overwrite: true.',
+            toolsets: ['CARTRIDGES', 'SCAPI'],
+            requiresInstance: true,
+            inputSchema: {
+                path: pathSchema,
+                content: z
+                    .string()
+                    .max(64 * 1024)
+                    .optional()
+                    .describe('UTF-8 text; supply exactly one of content, sourcePath.'),
+                sourcePath: z
+                    .string()
+                    .min(1)
+                    .optional()
+                    .describe('File on the MCP host, relative to projectDirectory. Maximum 64 MiB.'),
+                contentType: z.string().max(200).optional(),
+                overwrite: z.boolean().default(false),
+            },
+            async execute(args, context) {
+                const path = webdavPath(args.path);
+                if (!path.includes('/'))
+                    throw new Error('A destination file within a WebDAV root is required.');
+                if ([args.content, args.sourcePath].filter((value) => value !== undefined).length !== 1) {
+                    throw new Error('Supply exactly one of content, sourcePath.');
+                }
+                const data = args.content === undefined
+                    ? await readLocalFile(context.services.resolveWithProjectDirectory(args.sourcePath, args.projectDirectory))
+                    : Buffer.from(args.content);
+                const response = await context.b2cInstance.webdav.request(path, {
+                    method: 'PUT',
+                    body: new Uint8Array(data),
+                    redirect: 'error',
+                    signal: AbortSignal.timeout(30_000),
+                    headers: {
+                        'Content-Type': args.contentType ??
+                            (args.content === undefined ? 'application/octet-stream' : 'text/plain; charset=utf-8'),
+                        ...(args.overwrite ? {} : { 'If-None-Match': '*' }),
+                    },
+                });
+                await response.body?.cancel();
+                if (response.status === 412)
+                    throw new Error('Destination exists. Use overwrite: true only to replace it.');
+                if (!response.ok)
+                    throw new Error(`WebDAV PUT HTTP ${response.status} ${response.statusText}. Check parent directory and write permissions.`);
+                return { path: decodeURIComponent(path), size: data.length, status: response.status };
+            },
+            formatOutput: jsonResult,
+        }, loadServices),
+    ];
+}
+//# sourceMappingURL=index.js.map

package/dist/utils/constants.d.ts

@@ -5,11 +5,11 @@ export declare const ALL_TOOLSETS = "ALL";
 /**
  * Available toolsets that can be enabled.
  */
-export declare const TOOLSETS: readonly ["CARTRIDGES", "DIAGNOSTICS", "MRT", "PWAV3", "SCAPI", "STOREFRONTNEXT"];
+export declare const TOOLSETS: readonly ["CARTRIDGES", "DIAGNOSTICS", "MRT", "PWAV3", "SCAPI", "STOREFRONTNEXT", "CIP"];
 /**
  * Valid toolset names including the special "ALL" value.
  */
-export declare const VALID_TOOLSET_NAMES: readonly ["ALL", "CARTRIDGES", "DIAGNOSTICS", "MRT", "PWAV3", "SCAPI", "STOREFRONTNEXT"];
+export declare const VALID_TOOLSET_NAMES: readonly ["ALL", "CARTRIDGES", "DIAGNOSTICS", "MRT", "PWAV3", "SCAPI", "STOREFRONTNEXT", "CIP"];
 /**
  * Type representing a valid toolset name.
  */

package/dist/utils/constants.js

@@ -10,7 +10,7 @@ export const ALL_TOOLSETS = 'ALL';
 /**
  * Available toolsets that can be enabled.
  */
-export const TOOLSETS = ['CARTRIDGES', 'DIAGNOSTICS', 'MRT', 'PWAV3', 'SCAPI', 'STOREFRONTNEXT'];
+export const TOOLSETS = ['CARTRIDGES', 'DIAGNOSTICS', 'MRT', 'PWAV3', 'SCAPI', 'STOREFRONTNEXT', 'CIP'];
 /**
  * Valid toolset names including the special "ALL" value.
  */

package/dist/utils/index.d.ts

@@ -4,4 +4,5 @@
  * @module utils
  */
 export * from './constants.js';
+export * from './tool-effects.js';
 export * from './types.js';

package/dist/utils/index.js

@@ -12,5 +12,6 @@
 // TypeScript resolves .js → .ts at compile time, but the compiled
 // output needs .js extensions to work at runtime with Node.js ESM.
 export * from './constants.js';
+export * from './tool-effects.js';
 export * from './types.js';
 //# sourceMappingURL=index.js.map

package/dist/utils/tool-effects.d.ts

@@ -0,0 +1,4 @@
+import type { ToolAnnotations } from '@modelcontextprotocol/server';
+import type { ToolEffects } from './types.js';
+/** Protocol hints describe effects; they neither authorize calls nor enforce access. */
+export declare function toToolAnnotations({ effect, idempotent, openWorld }: ToolEffects): ToolAnnotations;

package/dist/utils/tool-effects.js

@@ -0,0 +1,15 @@
+/*
+ * 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
+ */
+/** Protocol hints describe effects; they neither authorize calls nor enforce access. */
+export function toToolAnnotations({ effect, idempotent, openWorld }) {
+    return {
+        readOnlyHint: effect === 'read',
+        destructiveHint: effect === 'destructive',
+        idempotentHint: idempotent,
+        openWorldHint: openWorld,
+    };
+}
+//# sourceMappingURL=tool-effects.js.map