@salesforce/b2c-dx-mcp 1.5.0 → 1.7.0

package/dist/registry.js

@@ -3,6 +3,8 @@
  * 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 { 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';
@@ -102,17 +104,49 @@ 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;
+/**
+ * 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;
+}
 /**
  * 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
- * @param reason - Reason for triggering auto-discovery (for logging)
- * @returns Array of toolsets to enable
+ * @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
+    // 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) {
@@ -120,7 +154,14 @@ async function detectProjectTypes(flags) {
             '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.');
     }
-    const detectionResult = await detectWorkspaceType(projectDirectory);
+    // 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 or root 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;
 }
@@ -156,22 +197,21 @@ export async function registerToolsets(flags, server, loadServices, serverContex
     const individualTools = flags.tools ?? [];
     const allowNonGaTools = flags.allowNonGaTools ?? false;
     const logger = getLogger();
-    // Detect the workspace type once up front. It informs both the
-    // docs tools (favoring the current workspace's docs and surfacing it in the
-    // tool descriptions) and toolset auto-discovery below, so we only hit the
-    // filesystem a single time.
-    const detectedWorkspaces = await detectProjectTypes(flags);
     // 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(', ')}`);
     }
-    // Create the tool registry (all available tools)
-    const toolRegistry = createToolRegistry(loadServices, serverContext, detectedWorkspaces, enabledDocCategories);
-    // Build flat list of all tools for lookup
-    const allTools = Object.values(toolRegistry).flat();
-    const allToolsByName = new Map(allTools.map((tool) => [tool.name, tool]));
-    const existingToolNames = new Set(allToolsByName.keys());
+    // 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);
+    const existingToolNames = new Set(Object.values(toolRegistry)
+        .flat()
+        .map((tool) => tool.name));
     // Determine valid individual tools
     const invalidTools = individualTools.filter((name) => !existingToolNames.has(name));
     const validIndividualTools = individualTools.filter((name) => existingToolNames.has(name));
@@ -190,16 +230,24 @@ export async function registerToolsets(flags, server, loadServices, serverContex
     const validToolsets = toolsets.filter((t) => TOOLSETS.includes(t));
     const allNonDeprecatedToolsets = TOOLSETS.filter((t) => !DEPRECATED_TOOLSETS.includes(t));
     const toolsetsToEnable = new Set(toolsets.includes(ALL_TOOLSETS) ? allNonDeprecatedToolsets : validToolsets);
-    // Auto-discovery: If no valid toolsets AND no valid individual tools, map the
-    // already-detected workspace type(s) to toolsets. This handles both: (1) no
-    // flags provided, and (2) all provided flags are invalid. Always enables at
-    // least the BASE_TOOLSETS even if no project types are detected.
+    // 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) {
             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);
+        }
     }
     // Build the set of tools to register:
     // 1. Start with tools from enabled toolsets
@@ -215,7 +263,11 @@ export async function registerToolsets(flags, server, loadServices, serverContex
             }
         }
     }
-    // Step 2: Add individual tools from --tools (can be from any toolset)
+    // Step 2: Add individual tools from --tools (can be from any toolset).
+    // Look up against the final registry (which may have been rebuilt above).
+    const allToolsByName = new Map(Object.values(toolRegistry)
+        .flat()
+        .map((tool) => [tool.name, tool]));
     for (const toolName of validIndividualTools) {
         const tool = allToolsByName.get(toolName);
         if (tool && !registeredToolNames.has(toolName)) {

package/dist/services.d.ts

@@ -40,7 +40,7 @@ import fs from 'node:fs';
 import type { B2CInstance } from '@salesforce/b2c-tooling-sdk';
 import type { AuthStrategy } from '@salesforce/b2c-tooling-sdk/auth';
 import type { ResolvedB2CConfig } from '@salesforce/b2c-tooling-sdk/config';
-import { WebDavClient, type CustomApisClient, type ScapiSchemasClient } from '@salesforce/b2c-tooling-sdk/clients';
+import { WebDavClient, type CustomApisClient, type MetricsClient, type ScapiSchemasClient } from '@salesforce/b2c-tooling-sdk/clients';
 /**
  * MRT (Managed Runtime) configuration.
  * Groups auth, project, environment, and origin settings.
@@ -147,6 +147,14 @@ export declare class Services {
      * Get the user's home directory.
      */
     getHomeDir(): string;
+    /**
+     * Get Metrics client for accessing SCAPI observability metrics.
+     * Requires shortCode, tenantId, and OAuth credentials to be configured.
+     *
+     * @throws Error if shortCode, tenantId, or OAuth credentials are missing
+     * @returns Typed Metrics client
+     */
+    getMetricsClient(): MetricsClient;
     /**
      * Get organization ID for SCAPI API calls.
      * Ensures the tenant ID has the required f_ecom_ prefix.

package/dist/services.js

@@ -44,7 +44,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
-import { createCustomApisClient, createScapiSchemasClient, toOrganizationId, WebDavClient, } from '@salesforce/b2c-tooling-sdk/clients';
+import { createCustomApisClient, createMetricsClient, createScapiSchemasClient, toOrganizationId, WebDavClient, } from '@salesforce/b2c-tooling-sdk/clients';
 /**
  * Services class that provides utilities for MCP tools.
  *
@@ -167,6 +167,25 @@ export class Services {
     getHomeDir() {
         return os.homedir();
     }
+    /**
+     * Get Metrics client for accessing SCAPI observability metrics.
+     * Requires shortCode, tenantId, and OAuth credentials to be configured.
+     *
+     * @throws Error if shortCode, tenantId, or OAuth credentials are missing
+     * @returns Typed Metrics client
+     */
+    getMetricsClient() {
+        const { shortCode, tenantId } = this.resolvedConfig.values;
+        if (!shortCode) {
+            throw new Error('SCAPI short code required. Provide --short-code, set SFCC_SHORTCODE, or configure short-code in dw.json.');
+        }
+        if (!tenantId) {
+            throw new Error('Tenant ID required. Provide --tenant-id, set SFCC_TENANT_ID, or configure tenant-id in dw.json.');
+        }
+        // This will throw if OAuth credentials are missing
+        const oauthStrategy = this.getOAuthStrategy();
+        return createMetricsClient({ shortCode, tenantId }, oauthStrategy);
+    }
     /**
      * Get organization ID for SCAPI API calls.
      * Ensures the tenant ID has the required f_ecom_ prefix.

package/dist/tools/scapi/index.js

@@ -3,9 +3,10 @@
  * 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 { createScapiSchemasListTool } from './scapi-schemas-list.js';
-import { createScapiCustomApisStatusTool } from './scapi-custom-apis-get-status.js';
+import { createMetricsGetTool } from './metrics-get.js';
 import { createScaffoldCustomApiTool } from './scapi-custom-api-generate-scaffold.js';
+import { createScapiCustomApisStatusTool } from './scapi-custom-apis-get-status.js';
+import { createScapiSchemasListTool } from './scapi-schemas-list.js';
 /**
  * Creates all tools for the SCAPI toolset.
  *
@@ -14,9 +15,10 @@ import { createScaffoldCustomApiTool } from './scapi-custom-api-generate-scaffol
  */
 export function createScapiTools(loadServices) {
     return [
-        createScapiSchemasListTool(loadServices),
-        createScapiCustomApisStatusTool(loadServices),
+        createMetricsGetTool(loadServices),
         createScaffoldCustomApiTool(loadServices),
+        createScapiCustomApisStatusTool(loadServices),
+        createScapiSchemasListTool(loadServices),
     ];
 }
 //# sourceMappingURL=index.js.map

package/dist/tools/scapi/metrics-get.d.ts

@@ -0,0 +1,25 @@
+import type { Services } from '../../services.js';
+import type { McpTool } from '../../utils/index.js';
+/**
+ * Creates the metrics_get tool.
+ *
+ * Retrieves observability metrics time-series for a B2C Commerce tenant by category:
+ * - **overall**: Aggregate site metrics (requests, response times, errors)
+ * - **sales**: Sales and order metrics
+ * - **ecdn**: Edge CDN performance metrics
+ * - **third-party**: External service integration metrics (filter by thirdPartyServiceId)
+ * - **scapi**: SCAPI endpoint metrics (filter by apiFamily, apiName)
+ * - **scapi-hooks**: SCAPI hooks execution metrics
+ * - **mrt**: Managed Runtime (PWA Kit) metrics
+ * - **controller**: Controller execution metrics
+ * - **ocapi**: OCAPI endpoint metrics (filter by ocapiCategory, ocapiApi)
+ *
+ * Returns time-series data with metric metadata (title, description, unit) and data points
+ * (timestamp, value) grouped by series (e.g., 2xx, 4xx, 5xx response codes).
+ *
+ * **Requirements:** OAuth with `sfcc.metrics` scope.
+ *
+ * @param loadServices - Function that loads configuration and returns Services instance
+ * @returns MCP tool for retrieving metrics
+ */
+export declare function createMetricsGetTool(loadServices: () => Promise<Services> | Services): McpTool;

package/dist/tools/scapi/metrics-get.js

@@ -0,0 +1,144 @@
+/*
+ * 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
+ */
+/**
+ * Metrics Get tool.
+ *
+ * Retrieves observability metrics time-series data for B2C Commerce tenants via SCAPI
+ * observability/metrics/v1. Returns metrics data grouped by category (overall, sales, ecdn,
+ * third-party, scapi, scapi-hooks, mrt, controller, ocapi).
+ *
+ * @module tools/scapi/metrics-get
+ */
+import { z } from 'zod';
+import { createToolAdapter, jsonResult } from '../adapter.js';
+import { getMetricsByCategory, resolveMetricsWindow, enrichMetricsTags, } from '@salesforce/b2c-tooling-sdk';
+/**
+ * Creates the metrics_get tool.
+ *
+ * Retrieves observability metrics time-series for a B2C Commerce tenant by category:
+ * - **overall**: Aggregate site metrics (requests, response times, errors)
+ * - **sales**: Sales and order metrics
+ * - **ecdn**: Edge CDN performance metrics
+ * - **third-party**: External service integration metrics (filter by thirdPartyServiceId)
+ * - **scapi**: SCAPI endpoint metrics (filter by apiFamily, apiName)
+ * - **scapi-hooks**: SCAPI hooks execution metrics
+ * - **mrt**: Managed Runtime (PWA Kit) metrics
+ * - **controller**: Controller execution metrics
+ * - **ocapi**: OCAPI endpoint metrics (filter by ocapiCategory, ocapiApi)
+ *
+ * Returns time-series data with metric metadata (title, description, unit) and data points
+ * (timestamp, value) grouped by series (e.g., 2xx, 4xx, 5xx response codes).
+ *
+ * **Requirements:** OAuth with `sfcc.metrics` scope.
+ *
+ * @param loadServices - Function that loads configuration and returns Services instance
+ * @returns MCP tool for retrieving metrics
+ */
+export function createMetricsGetTool(loadServices) {
+    return createToolAdapter({
+        name: 'metrics_get',
+        description: `CLOSED BETA: the Metrics API must be enabled for your organization, and its behavior, output, and OAuth scopes may change without notice.
+
+Retrieve observability metrics time-series for a B2C Commerce tenant. Returns metrics data grouped by category with time-series data points.
+
+**Categories:**
+- overall: Aggregate site metrics (requests, response times, errors)
+- sales: Sales and order metrics
+- ecdn: Edge CDN performance metrics
+- third-party: External service metrics (use thirdPartyServiceId filter)
+- scapi: SCAPI endpoint metrics (use apiFamily/apiName filters)
+- scapi-hooks: SCAPI hooks execution metrics
+- mrt: Managed Runtime (PWA Kit) metrics
+- controller: Controller execution metrics
+- ocapi: OCAPI endpoint metrics (use ocapiCategory/ocapiApi filters)
+
+**Time window:** Provide "from" and/or "to" as a relative duration ("1h", "7d" — interpreted as ago) or an ISO 8601 timestamp, and/or "window" as a duration ("1h", "30m"). The tool always sends an explicit from+to range, defaulting to a 24-hour window: from + window → to = from + window; to + window → from = to - window; window alone → the last <window>; from alone → 24h forward from it (capped at now); to alone → 24h back from it; nothing → the last 24h. Do not supply from, to, and window together. The API caps a window at 24h and retains 30 days; an explicit range wider than 24h is sent as-is and the API returns a clear error.
+
+**Response:** { query, data } — "query" echoes the resolved from/to (ISO + epoch seconds), filters, and defaultedWindow/clampedFrom flags; "data[]" contains metricId, title, description, unit, and dataSeries[] with time-series points (timestamp in epoch milliseconds, value). Each series also carries a structured "tags" object (realm, environment, any applied filters, and per-series dimensions like apiFamily/host/cacheStatus) parsed client-side from the packed series id — use these to group/filter rather than parsing the series id string.
+
+**Requirements:** OAuth with sfcc.metrics scope.`,
+        toolsets: ['SCAPI'],
+        isGA: false,
+        requiresInstance: false, // SCAPI uses OAuth directly
+        inputSchema: {
+            category: z
+                .enum(['overall', 'sales', 'ecdn', 'third-party', 'scapi', 'scapi-hooks', 'mrt', 'controller', 'ocapi'])
+                .describe('Metrics category: overall (aggregate), sales, ecdn (CDN), third-party (external), scapi (SCAPI APIs), scapi-hooks, mrt (PWA Kit), controller, ocapi'),
+            from: z
+                .string()
+                .optional()
+                .describe('Start bound: relative ("1h", "7d" ago) or ISO 8601. Alone → a 24h window forward (capped at now).'),
+            to: z
+                .string()
+                .optional()
+                .describe('End bound: relative ("6h" ago) or ISO 8601. Alone → a 24h window back from it.'),
+            window: z
+                .string()
+                .optional()
+                .describe('Window duration ("1h", "30m", "2d"). With from → to=from+window; with to → from=to-window; alone → the last <window>. Defaults to 24h.'),
+            thirdPartyServiceId: z
+                .string()
+                .optional()
+                .describe('Filter by third-party service ID (third-party category only)'),
+            apiFamily: z.string().optional().describe('Filter by SCAPI API family (scapi category only)'),
+            apiName: z.string().optional().describe('Filter by SCAPI API name (scapi category only)'),
+            ocapiCategory: z.string().optional().describe('Filter by OCAPI category (ocapi category only)'),
+            ocapiApi: z.string().optional().describe('Filter by OCAPI API (ocapi category only)'),
+        },
+        async execute(args, { services: svc }) {
+            // Get client and tenant ID
+            const client = svc.getMetricsClient();
+            const tenantId = svc.getTenantId();
+            if (!tenantId) {
+                throw new Error('Tenant ID required. Provide --tenant-id, set SFCC_TENANT_ID, or configure tenant-id in dw.json.');
+            }
+            // Resolve the requested bounds into an explicit from+to range, filling any
+            // open bound from the 24-hour default window (the API caps a window at 24h
+            // and pairs a missing `to` with its own `now`). Throws a clear error on
+            // unparseable/over-specified input before the request.
+            const window = resolveMetricsWindow({ from: args.from, to: args.to, window: args.window });
+            const raw = await getMetricsByCategory(client, tenantId, args.category, {
+                from: window.from,
+                to: window.to,
+                thirdPartyServiceId: args.thirdPartyServiceId,
+                apiFamily: args.apiFamily,
+                apiName: args.apiName,
+                ocapiCategory: args.ocapiCategory,
+                ocapiApi: args.ocapiApi,
+            });
+            // Enrich each series with a structured `tags` object (realm/environment
+            // from the request, applied filters, and per-series dimensions parsed
+            // from the packed id). Additive and always-on for this machine consumer.
+            const response = enrichMetricsTags(raw, args.category, {
+                tenantId,
+                apiFamily: args.apiFamily,
+                apiName: args.apiName,
+                ocapiCategory: args.ocapiCategory,
+                ocapiApi: args.ocapiApi,
+                thirdPartyServiceId: args.thirdPartyServiceId,
+            });
+            return {
+                ...response,
+                query: {
+                    category: args.category,
+                    from: window.fromIso,
+                    to: window.toIso,
+                    fromEpochSeconds: window.fromEpochSeconds,
+                    toEpochSeconds: window.toEpochSeconds,
+                    clampedFrom: window.clampedFrom || undefined,
+                    defaultedWindow: window.defaultedWindow || undefined,
+                    thirdPartyServiceId: args.thirdPartyServiceId,
+                    apiFamily: args.apiFamily,
+                    apiName: args.apiName,
+                    ocapiCategory: args.ocapiCategory,
+                    ocapiApi: args.ocapiApi,
+                },
+            };
+        },
+        formatOutput: (output) => jsonResult(output),
+    }, loadServices);
+}
+//# sourceMappingURL=metrics-get.js.map

package/oclif.manifest.json

@@ -428,5 +428,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "1.5.0"
+  "version": "1.7.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@salesforce/b2c-dx-mcp",
   "description": "MCP server for B2C Commerce developer experience tools",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "author": "Salesforce",
   "license": "Apache-2.0",
   "repository": "SalesforceCommerceCloud/b2c-developer-tooling",
@@ -80,7 +80,7 @@
     "yaml": "2.9.0",
     "postcss": "8.5.15",
     "zod": "3.25.76",
-    "@salesforce/b2c-tooling-sdk": "1.18.0"
+    "@salesforce/b2c-tooling-sdk": "1.19.1"
   },
   "devDependencies": {
     "@eslint/compat": "^1",