@W-20592464 SCAPI Schemas List and SCAPI Custom APIs Status MCP tools (#133)

Author: yhsieh1

.changeset/scapi-discovery-tools.md

@@ -0,0 +1,12 @@
+---
+'@salesforce/b2c-dx-mcp': minor
+'@salesforce/b2c-tooling-sdk': minor
+---
+
+# Add new MCP tools
+
+- `scapi-schemas-list`: List and fetch SCAPI schemas (standard and custom)
+- `scapi-custom-apis-status`: Check custom API endpoint registration status
+- `mrt_bundle_push`: Push and deploy a pre-built Storefront Next  PWA Kit project to Managed Runtime
+- `cartridge_deploy`: Find and deploy cartridges to a B2C Commerce instance via WebDAV
+- `storefront_next_development_guidelines`: Get critical architecture rules, coding standards, and best practices for Storefront Next development

.github/workflows/ci.yml

@@ -63,18 +63,18 @@ jobs:
         working-directory: packages/b2c-tooling-sdk
         run: pnpm run pretest && pnpm run test:ci && pnpm run lint
 
-      - name: Run CLI tests
-        id: cli-test
-        if: always() && steps.sdk-test.conclusion != 'cancelled'
-        working-directory: packages/b2c-cli
-        run: pnpm run pretest && pnpm run test:ci && pnpm run lint
-
       - name: Run MCP tests
         id: mcp-test
         if: always() && steps.sdk-test.conclusion != 'cancelled'
         working-directory: packages/b2c-dx-mcp
         run: pnpm run pretest && pnpm run test:ci && pnpm run lint
 
+      - name: Run CLI tests
+        id: cli-test
+        if: always() && steps.mcp-test.conclusion != 'cancelled'
+        working-directory: packages/b2c-cli
+        run: pnpm run pretest && pnpm run test:ci && pnpm run lint
+
       - name: Test Report
         uses: dorny/test-reporter@fe45e9537387dac839af0d33ba56eed8e24189e8  # v2.3.0
         if: always() && steps.sdk-test.conclusion != 'cancelled'

packages/b2c-cli/src/commands/scapi/custom/status.ts

@@ -11,27 +11,11 @@ import {
   toOrganizationId,
   type CustomApisComponents,
 } from '@salesforce/b2c-tooling-sdk';
+import {getApiType} from '@salesforce/b2c-tooling-sdk/schemas';
 import {t, withDocs} from '../../../i18n/index.js';
 
 type CustomApiEndpoint = CustomApisComponents['schemas']['CustomApiEndpoint'];
 
-/**
- * Maps security scheme to human-readable API type.
- */
-function getApiType(securityScheme?: string): string {
-  switch (securityScheme) {
-    case 'AmOAuth2': {
-      return 'Admin';
-    }
-    case 'ShopperToken': {
-      return 'Shopper';
-    }
-    default: {
-      return securityScheme || '-';
-    }
-  }
-}
-
 /**
  * Rolled-up endpoint with sites combined.
  * Multiple endpoints with same API/version/path/method are grouped, with siteIds combined.

packages/b2c-dx-mcp/.c8rc.json

@@ -0,0 +1,12 @@
+{
+  "all": true,
+  "src": ["src"],
+  "exclude": ["test/**", "**/*.d.ts", "**/index.ts"],
+  "reporter": ["text", "text-summary", "html", "lcov"],
+  "report-dir": "coverage",
+  "check-coverage": true,
+  "lines": 80,
+  "functions": 80,
+  "branches": 80,
+  "statements": 80
+}

packages/b2c-dx-mcp/.mocharc.json

@@ -6,6 +6,7 @@
   "reporter": "spec",
   "timeout": 60000,
   "node-option": [
-    "import=tsx"
+    "import=tsx",
+    "conditions=development"
   ]
 }

packages/b2c-dx-mcp/README.md

@@ -120,15 +120,38 @@ The `storefront_next_development_guidelines` tool provides critical architecture
 - ✅ "I'm starting a new PWA Kit project. Use the MCP tool to get the development guidelines."
 - ✅ "Use the MCP tool to create a new product listing page component in my PWA Kit project."
 - ✅ "Use the MCP tool to recommend React hooks for fetching product data in PWA Kit."
-- ✅ "Use the MCP tool to explore the SCAPI Shop API endpoints available for my PWA Kit storefront."
 
 ##### SCAPI Discovery
 
-**Good prompts:**
-- ✅ "Use the MCP tool to discover what SCAPI endpoints are available for product data."
-- ✅ "Use the MCP tool to discover custom SCAPI APIs in my B2C instance."
-- ✅ "Use the MCP tool to show me all available SCAPI endpoints and their capabilities."
-- ✅ "Use the MCP tool to scaffold a new custom SCAPI API for order management."
+Use **scapi_schemas_list** for both standard SCAPI (Shop, Admin, Shopper APIs) and custom APIs. Use **scapi_custom_apis_status** for endpoint-level registration status (active/not_registered).
+
+**SCAPI Schemas (tool: `scapi_schemas_list`):**
+
+Discover schema metadata and fetch OpenAPI specs for both standard and custom SCAPI:
+
+**Standard SCAPI:**
+- ✅ "Use the MCP tool to list all available SCAPI schemas." → list mode (no includeSchemas).
+- ✅ "Use the MCP tool to show me what checkout APIs exist." → list with apiFamily: checkout.
+- ✅ "Use the MCP tool to discover SCAPI product endpoints." → list with apiFamily: product.
+- ✅ "Use the MCP tool to get the OpenAPI schema for shopper-baskets v1." → fetch with apiFamily, apiName, apiVersion, includeSchemas: true.
+- ✅ "Use the MCP tool to show me the full OpenAPI spec for shopper-products v1." → fetch with includeSchemas: true, expandAll: true.
+
+**Custom APIs (use apiFamily: "custom"):**
+- ✅ "Use the MCP tool to list custom API definitions." → list with apiFamily: custom.
+- ✅ "Use the MCP tool to show me the loyalty-points custom API schema." → apiFamily: custom, apiName: loyalty-points, apiVersion: v1, includeSchemas: true.
+
+**Custom API Endpoint Status (tool: `scapi_custom_apis_status`):**
+
+Get registration status of custom API endpoints deployed on the instance (remote only). Returns individual HTTP endpoints (e.g., GET /hello, POST /items/{id}) with registration status (active/not_registered), one row per endpoint per site. Requires OAuth with `sfcc.custom-apis` scope.
+
+- ✅ "Use the MCP tool to list custom SCAPI endpoints on my instance."
+- ✅ "Use the MCP tool to show which custom APIs are active vs not registered."
+- ✅ "Use the MCP tool to list custom API endpoints grouped by site." → groupBy: site
+- ✅ "Use the MCP tool to list custom API endpoints grouped by type." → groupBy: type
+- ✅ "Use the MCP tool to list only active custom API endpoints." → status: active
+- ✅ "Use the MCP tool to find custom API endpoints that failed to register." → status: not_registered
+- ✅ "Use the MCP tool to show endpoint details with all fields." → extended: true
+- ✅ "Use the MCP tool to show only apiName and status for active endpoints." → status: active, columns: "apiName,status"
 
 ##### Cartridge Deployment
 
@@ -157,7 +180,7 @@ Credentials can be provided via **config files** (recommended), **environment va
 
 | Toolset | Required Credentials |
 |---------|---------------------|
-| **SCAPI** | `hostname` + `client-id` + `client-secret` |
+| **SCAPI** | `hostname` + `client-id` + `client-secret` (for `scapi_custom_apis_status`: requires `sfcc.custom-apis` scope) |
 | **CARTRIDGES** | `hostname` + `username` + `password` (or OAuth) |
 | **MRT** | `api-key` + `project` (optionally `environment`) |
 | **PWAV3** | `--working-directory` only (+ MRT config for deployments) |
@@ -264,20 +287,19 @@ PWA Kit v3 development tools for building headless storefronts.
 | `pwakit_recommend_hooks` | Recommend appropriate React hooks for PWA Kit use cases |
 | `pwakit_run_site_test` | Run site tests for PWA Kit project |
 | `pwakit_install_agent_rules` | Install AI agent rules for PWA Kit development |
-| `pwakit_explore_scapi_shop_api` | Explore SCAPI Shop API endpoints and capabilities |
-| `scapi_discovery` | Discover available SCAPI endpoints and capabilities |
-| `scapi_custom_api_discovery` | Discover custom SCAPI API endpoints |
+| `scapi_schemas_list` | List or fetch SCAPI schemas (standard and custom). Use apiFamily: "custom" for custom APIs. |
+| `scapi_custom_apis_status` | Get registration status of custom API endpoints (active/not_registered). Remote only, requires OAuth. |
 | `mrt_bundle_push` | Build, push bundle (optionally deploy) |
 
 #### SCAPI
 Salesforce Commerce API discovery and exploration.
-- **Status:** 🚧 Placeholder
+- **Status:** 🚧 Early Access
 
 | Tool | Description |
 |------|-------------|
-| `scapi_discovery` | Discover available SCAPI endpoints and capabilities |
-| `scapi_customapi_scaffold` | Scaffold a new custom SCAPI API |
-| `scapi_custom_api_discovery` | Discover custom SCAPI API endpoints |
+| `scapi_schemas_list` | List or fetch SCAPI schemas (standard and custom). Use apiFamily: "custom" for custom APIs. |
+| `scapi_custom_apis_status` | Get registration status of custom API endpoints (active/not_registered). Remote only, requires OAuth. |
+| `scapi_customapi_scaffold` | Scaffold a new custom SCAPI API (not yet implemented) |
 
 #### STOREFRONTNEXT
 Storefront Next development tools for building modern storefronts.
@@ -292,11 +314,11 @@ Storefront Next development tools for building modern storefronts.
 | `storefront_next_map_tokens_to_theme` | Map design tokens to Storefront Next theme configuration |
 | `storefront_next_design_decorator` | Apply design decorators to Storefront Next components |
 | `storefront_next_generate_page_designer_metadata` | Generate Page Designer metadata for Storefront Next components |
-| `scapi_discovery` | Discover available SCAPI endpoints and capabilities |
-| `scapi_custom_api_discovery` | Discover custom SCAPI API endpoints |
+| `scapi_schemas_list` | List or fetch SCAPI schemas (standard and custom). Use apiFamily: "custom" for custom APIs. |
+| `scapi_custom_apis_status` | Get registration status of custom API endpoints (active/not_registered). Remote only, requires OAuth. |
 | `mrt_bundle_push` | Build, push bundle (optionally deploy) |
 
-> **Note:** Some tools appear in multiple toolsets (e.g., `mrt_bundle_push`, `scapi_discovery`). When using multiple toolsets, tools are automatically deduplicated.
+> **Note:** Some tools appear in multiple toolsets (e.g., `mrt_bundle_push`, `scapi_schemas_list`, `scapi_custom_apis_status`). When using multiple toolsets, tools are automatically deduplicated.
 
 ## Telemetry
 

packages/b2c-dx-mcp/package.json

@@ -84,9 +84,10 @@
     "inspect": "mcp-inspector node bin/run.js --toolsets all --allow-non-ga-tools",
     "inspect:dev": "mcp-inspector node --conditions development bin/dev.js --toolsets all --allow-non-ga-tools",
     "pretest": "tsc --noEmit -p test",
-    "test": "mocha --forbid-only \"test/**/*.test.ts\"",
+    "test": "c8 mocha --forbid-only \"test/**/*.test.ts\"",
+    "test:ci": "c8 mocha --forbid-only --reporter json --reporter-option output=test-results.json \"test/**/*.test.ts\"",
     "test:agent": "mocha --forbid-only --reporter min \"test/**/*.test.ts\"",
-    "test:ci": "mocha --forbid-only --reporter json --reporter-option output=test-results.json \"test/**/*.test.ts\"",
+    "coverage": "c8 report",
     "posttest": "pnpm run lint",
     "prepack": "oclif manifest",
     "postpack": "shx rm -f oclif.manifest.json"
@@ -95,6 +96,7 @@
     "@modelcontextprotocol/sdk": "1.26.0",
     "@oclif/core": "4.8.0",
     "@salesforce/b2c-tooling-sdk": "workspace:*",
+    "yaml": "^2.8.1",
     "zod": "3.25.76"
   },
   "devDependencies": {
@@ -107,6 +109,7 @@
     "@types/mocha": "^10",
     "@types/node": "^22.16.5",
     "@types/sinon": "^21.0.0",
+    "c8": "^10.1.3",
     "chai": "^4",
     "eslint": "^9",
     "eslint-config-oclif": "^6",