@salesforce/b2c-dx-mcp 3.4.0 → 3.5.0

package/content/guidance/index.json

@@ -2073,8 +2073,8 @@
         },
         {
           "path": "references/discover.md",
-          "bytes": 8497,
-          "digest": "sha256:b621643189beba4489a38587a7cbf3304e69139f048a962740d294fb0885a0d6"
+          "bytes": 9083,
+          "digest": "sha256:d11d646cd9c08b617e6043bb51d7e4dbdbb026af15ba11a951bbe3168eadcc9f"
         },
         {
           "path": "references/jobs.md",
@@ -2113,8 +2113,8 @@
         },
         {
           "path": "SKILL.md",
-          "bytes": 5929,
-          "digest": "sha256:c192bf8e28d9b975686386e167e15aee926a7aad723a4304d9a372ccbe1e7c72"
+          "bytes": 6549,
+          "digest": "sha256:671e0b5337b0a1794587115771fa7fa27d5db9b6974ab293998622c1e4766812"
         }
       ],
       "featured": true

package/content/guidance/mcp/b2c-mcp-scapi/SKILL.md

@@ -19,7 +19,11 @@ declare const spec: {
   apis: Array<{id: string; apiFamily: string; apiName: string; apiVersion: string; status: string}>; // id: 'product/catalogs/v1'
   paths: Record<string, Record<string, Operation>>; // fullPath -> lowercase method -> op
   resolve(value: unknown, apiId: string): unknown; // expand local $ref
+  // ranked fuzzy search over summary/description/tags/operationId/path; newest API version only
+  search(query: string, o?: {limit?: number}): Promise<Array<Match>>; // limit default 10, max 50
 };
+// spec.paths[m.path][m.method] is the full op; otherVersions = older versions with the same op
+type Match = {api: string; method: string; path: string; operationId?: string; summary?: string; score: number; otherVersions?: string[]};
 // fullPath = '/' + api id + path, e.g. '/product/catalogs/v1/organizations/{organizationId}/catalogs/{catalogId}'
 interface Operation {
   api: string;
@@ -53,7 +57,7 @@ declare const scapi: {
 ## Rules
 
 - Result cap 24 KB (`SCAPI_RESULT_TOO_LARGE`). Whole op = 6-20 KB. NEVER return `op` or `spec.paths` entries whole. List `{operationId, method, path, summary}`; then return only `parameters`/`requestBody` of ops you will call.
-- Search prose too: `summary`, `description`, `tags`, not only operationId/path.
+- Start with `await spec.search('task words')`; it matches prose (`summary`, `description`, `tags`) and tolerates typos. Regex over `spec.paths` to narrow or enumerate.
 - `scapi_search` default `detail:"outline"` drops nested descriptions/examples. `detail:"full"` restores. Execute sees full.
 - Default corpus = bundled standard. `schemas:"live"` = tenant (`c_*`, custom APIs, newer APIs); falls back to bundled with `warnings`. Tell user if `c_*`/custom APIs matter.
 - `scapi.request` auths itself. Never fetch tokens first. Path `{organizationId}` auto-fills.
@@ -62,7 +66,10 @@ declare const scapi: {
 - Write needing approval pauses for client elicitation. Decline = whole run ends. Never fake approval.
 
 ```js
-// list candidates by prose
+// rank candidates by prose (await it)
+async () => spec.search('apply coupon to basket', {limit: 8});
+
+// enumerate with a filter
 async () =>
   Object.entries(spec.paths)
     .flatMap(([path, methods]) =>

package/content/guidance/mcp/b2c-mcp-scapi/references/discover.md

@@ -1,7 +1,8 @@
 # SCAPI discovery, result limits and tenant schemas
 
 Every operation carries `summary`, `description` and `tags` (plus parameters, security and responses), so
-search the prose as well as `operationId` and path. Descriptions are long: return `op.summary` when listing
+search the prose as well as `operationId` and path. `await spec.search(query, {limit})` does this for you: it ranks
+operations across all of those fields, tolerates typos, and is the quickest way to find an unfamiliar API. Descriptions are long: return `op.summary` when listing
 candidates, and read `op.description` only for the operations you are about to call.
 
 `scapi_search` returns each operation as an outline by default: its own `summary`, `description` and `tags`, with
@@ -11,11 +12,15 @@ sees full operations). Results are capped at 24 KB of JSON for both tools (`SCAP
 typically 6-20 KB and some exceed the cap alone, so never return `op` or `spec.paths` entries unprojected: list
 `{operationId, method, path, summary}`, then return only `parameters` or `requestBody` for the operations you will call.
 
-The `spec` object has exactly three members; there is no `spec.schemas` and no need to probe it:
+The `spec` object has exactly four members; there is no `spec.schemas` and no need to probe it:
 
 - `spec.apis`: array of `{id, apiFamily, apiName, apiVersion, status, origin?}` (`id` is e.g. `product/catalogs/v1`).
 - `spec.paths`: `{[fullPath]: {[method]: operation}}`, where `fullPath` starts with the API id (`/product/catalogs/v1/organizations/{organizationId}/catalogs/{catalogId}`) and methods are lowercase. Operations carry `operationId`, `api`, `summary`, `description`, `tags`, `parameters`, `requestBody`, `responses`, `security` and `auth`.
 - `spec.resolve(value, apiId)`: expands local `$ref`s in a fragment.
+- `spec.search(query, {limit})`: resolves to ranked `{api, method, path, operationId, summary, score, otherVersions?}`
+  matches (default 10, at most 50). `spec.paths[match.path][match.method]` is the operation. Versions of one API
+  collapse into the newest, with older ones in `otherVersions`. It searches the same contracts as `spec.paths`, so
+  `api`, `authType` and `schemas: "live"` apply.
 
 ## Discover
 
@@ -32,7 +37,7 @@ developer-supplied beta contracts (dw.json `scapi-schemas`, `SFCC_SCAPI_SCHEMAS`
 execution. Schemas and responses can be huge.
 Return only what the next decision needs:
 
-1. Find APIs/operations through `spec.apis`/`spec.paths`; return method/path/operationId.
+1. Find operations with `spec.search`, or enumerate `spec.apis`/`spec.paths`; return method/path/operationId.
 2. Narrow by `api` (a family, family/name or full id: `cdn`, `cdn/zones`, `cdn/zones/v1`), path, or `authType`; inspect required inputs and selected fields,
    including `allOf` when present.
 3. Inspect response fields only as needed; avoid whole operations/schema trees.

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

@@ -26,7 +26,7 @@ function requireScapiSkill(read) {
     if (read !== true)
         throw new Error(SCAPI_SKILL_REQUIRED);
 }
-const searchDescription = `Requires reading skill://mcp/b2c-mcp-scapi/SKILL.md first. Search SCAPI Admin/Shopper OpenAPI contracts by running JavaScript over \`spec\` (only spec.apis, spec.paths[fullPath][method] and spec.resolve exist), to find the operationId, path, inputs and scopes for a Commerce API task when no dedicated tool fits. Use cip_* for analytics and webdav_* for files. Searches the bundled contracts by default (offline, no credentials); schemas:"live" fetches the current contracts from the configured instance instead, including tenant c_* fields, custom APIs and APIs newer than the bundle (falls back to the bundled contracts with a warning when live access fails). Operations carry summary, description and tags: match on those, not only operationId. Results are capped at 24 KB: operations are an outline by default (no nested descriptions or examples; detail:"full" restores them), and you should still return fields such as operationId, method, path and summary, not whole operations.`;
+const searchDescription = `Requires reading skill://mcp/b2c-mcp-scapi/SKILL.md first. Search SCAPI Admin/Shopper OpenAPI contracts by running JavaScript over \`spec\` (only spec.apis, spec.paths[fullPath][method], spec.resolve and spec.search exist), to find the operationId, path, inputs and scopes for a Commerce API task when no dedicated tool fits. Use cip_* for analytics and webdav_* for files. Searches the bundled contracts by default (offline, no credentials); schemas:"live" fetches the current contracts from the configured instance instead, including tenant c_* fields, custom APIs and APIs newer than the bundle (falls back to the bundled contracts with a warning when live access fails). Start with await spec.search("words for the task"): it ranks operations across summary, description, tags, operationId and path, tolerates typos, and returns {api, method, path, operationId, summary} that index spec.paths. Use regex filters over spec.paths to narrow further. Results are capped at 24 KB: operations are an outline by default (no nested descriptions or examples; detail:"full" restores them), and you should still return fields such as operationId, method, path and summary, not whole operations.`;
 const executeDescription = `Requires reading skill://mcp/b2c-mcp-scapi/SKILL.md first. Run any SCAPI Admin or Shopper API operation (reads, writes, searches and actions) through scapi.request() in JavaScript. Covers most developer, merchant and administrator tasks: catalogs, products, pricing, promotions, orders, customers, inventory, sites, jobs, code versions, observability, and storefront flows such as baskets. Use it whenever no more specific tool fits. Find operations with scapi_search first. Auth is automatic; Shopper calls run as a per-site guest whose basket persists. Operations are governed by Safety Mode and may ask the user for confirmation.`;
 function codeResult(data, resolution) {
     const result = resolution ? attachResolution(jsonResult(data, 0), resolution, 0) : jsonResult(data, 0);
@@ -249,6 +249,9 @@ export function createScapiCodeTools(loadServices, snippetDirectory, registry =
                         services.getEnvironmentVariable(name),
                     ]));
                     return await registry.start(input, context, async (execution) => {
+                        // Live contracts discovered for this tenant replace bundled ones, and local ones replace both;
+                        // the user owns their accuracy. The same set backs spec in the program and request matching.
+                        const documents = mergeScapiSchemas(loadScapiSchemas(), tenant ? schemaCache.get(tenant) : [], localDocuments);
                         let managedRequest;
                         const request = async (options, signal) => {
                             if (!shortCode || !tenantId)
@@ -265,9 +268,7 @@ export function createScapiCodeTools(loadServices, snippetDirectory, registry =
                                     slasClientId: config.values.slasClientId,
                                     slasClientSecret: config.values.slasClientSecret,
                                 }),
-                                // Live contracts discovered for this tenant replace bundled ones, and local ones replace both;
-                                // the user owns their accuracy.
-                                documents: mergeScapiSchemas(loadScapiSchemas(), tenant ? schemaCache.get(tenant) : [], localDocuments),
+                                documents,
                                 onSchema(document, full) {
                                     // Keep full tenant contracts (custom properties and prose) from being replaced by lighter fetches.
                                     if (tenant && (full || document.entry.apiFamily === 'custom'))
@@ -283,6 +284,7 @@ export function createScapiCodeTools(loadServices, snippetDirectory, registry =
                         try {
                             const result = await runScapiCode({
                                 code: input.code,
+                                documents,
                                 request: (options, signal) => execution.runCall('request', options, () => request(options, signal)),
                                 auth: (operation, options, signal) => execution.runCall('auth', undefined, () => auth(operation, options, signal)),
                                 organizationId: tenantId ? toOrganizationId(tenantId) : undefined,

package/oclif.manifest.json

@@ -493,5 +493,5 @@
       "enableJsonFlag": false
     }
   },
-  "version": "3.4.0"
+  "version": "3.5.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@salesforce/b2c-dx-mcp",
   "description": "MCP server for B2C Commerce developer experience tools",
-  "version": "3.4.0",
+  "version": "3.5.0",
   "author": "Salesforce",
   "license": "Apache-2.0",
   "repository": "SalesforceCommerceCloud/b2c-developer-tooling",
@@ -81,7 +81,7 @@
     "yaml": "2.9.0",
     "zod": "4.5.4",
     "@salesforce/b2c-agent-plugins": "1.12.0",
-    "@salesforce/b2c-tooling-sdk": "2.5.0"
+    "@salesforce/b2c-tooling-sdk": "2.6.0"
   },
   "bundledDependencies": [
     "@modelcontextprotocol/server",