@W-21105798: Scaffold Custom API MCP Tool

docs/mcp/tools/scapi-custom-api-scaffold.md

@@ -0,0 +1,96 @@
+---
+description: Generate a new custom SCAPI endpoint (OAS 3.0 schema, api.json, script.js) in an existing cartridge.
+---
+
+# scapi_custom_api_scaffold
+
+Generate a new custom SCAPI endpoint in an existing cartridge. Creates `schema.yaml` (OAS 3.0 contract), `api.json` (endpoint mapping), and `script.js` (implementation) under the cartridge's `rest-apis/<apiName>/` directory.
+
+## Overview
+
+The `scapi_custom_api_scaffold` tool scaffolds a new custom API using the B2C tooling SDK's `custom-api` scaffold. It:
+
+- Creates an OpenAPI 3.0 schema, API manifest, and script stub in your project.
+- Uses the first cartridge found in the project if you don't specify one.
+- Supports **shopper** (siteId, customer-facing) or **admin** (no siteId) API types.
+
+**No instance or OAuth required** — this tool works locally and only writes files into your project. To check registration status after deployment, use [`scapi_custom_apis_status`](./scapi-custom-apis-status).
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `apiName` | string | Yes | API name in kebab-case (e.g. `my-products`). Must start with a lowercase letter; only letters, numbers, and hyphens. |
+| `cartridgeName` | string | No | Cartridge that will contain the API. Omit to use the first cartridge found under the project (working directory or `projectRoot`). |
+| `apiType` | `"admin"` \| `"shopper"` | No | `shopper` (siteId, customer-facing) or `admin` (no siteId). Default: `shopper`. |
+| `apiDescription` | string | No | Short description of the API. |
+| `projectRoot` | string | No | Project root for cartridge discovery. Default: MCP working directory (`--project-directory` / `SFCC_PROJECT_DIRECTORY`). |
+| `outputDir` | string | No | Output directory override. Default: project root (scaffold writes under cartridge path). |
+
+## Usage Examples
+
+### Create a custom API (default cartridge and type)
+
+```
+Use the MCP tool to create a custom API named my-loyalty-api.
+```
+
+### Create a shopper API with a description
+
+```
+Use the MCP tool to scaffold a custom API named product-recommendations, type shopper, with description "Product recommendations by segment".
+```
+
+### Create an admin API in a specific cartridge
+
+```
+Use the MCP tool to create a custom admin API named inventory-sync in cartridge app_custom.
+```
+
+## Output
+
+### Success
+
+Returns the scaffold ID, output directory, and list of created files:
+
+```json
+{
+  "scaffold": "custom-api",
+  "outputDir": "/path/to/project",
+  "dryRun": false,
+  "files": [
+    { "path": ".../rest-apis/my-custom-api/schema.yaml", "action": "created" },
+    { "path": ".../rest-apis/my-custom-api/api.json", "action": "created" },
+    { "path": ".../rest-apis/my-custom-api/script.js", "action": "created" }
+  ],
+  "postInstructions": "Custom API 'my-custom-api' has been created in cartridge 'app_storefrontnext_base'. ..."
+}
+```
+
+### Errors
+
+- **No cartridges found** — Project has no cartridge (e.g. no `.project` in a cartridge directory). Create a cartridge first (e.g. `b2c scaffold cartridge`).
+- **Scaffold not found** — SDK `custom-api` scaffold is missing; ensure `@salesforce/b2c-tooling-sdk` is installed.
+- **Parameter validation failed** — Invalid `apiName` (e.g. not kebab-case) or other parameter issue.
+
+## Next steps after scaffolding
+
+1. **Edit** `schema.yaml` to define paths, request/response schemas, and operation IDs.
+2. **Edit** `script.js` to implement the endpoint logic.
+3. **Deploy** the cartridge to your instance and **activate** the code version to register the API.
+4. **Verify** with [`scapi_custom_apis_status`](./scapi-custom-apis-status) that endpoints show as `active`.
+
+Shopper APIs are available at:
+`https://{shortCode}.api.commercecloud.salesforce.com/custom/{apiName}/v1/organizations/{organizationId}/...` and require the `siteId` query parameter and ShopperToken authentication.
+
+## Related Tools
+
+- Part of the [SCAPI](../toolsets#scapi), [PWAV3](../toolsets#pwav3), and [STOREFRONTNEXT](../toolsets#storefrontnext) toolsets
+- [`scapi_custom_apis_status`](./scapi-custom-apis-status) — Check custom API endpoint registration status after deployment
+- [`scapi_schemas_list`](./scapi-schemas-list) — List or fetch custom API schemas (use `apiFamily: "custom"`)
+
+## See Also
+
+- [SCAPI Toolset](../toolsets#scapi) — Overview of SCAPI tools
+- [Scaffolding Guide](../../guide/scaffolding#custom-api) — CLI and SDK scaffolding (including `b2c scaffold custom-api`)
+- [CLI Reference](../../cli/scaffold) — `b2c scaffold` commands

docs/mcp/tools/scapi-custom-apis-status.md

@@ -15,7 +15,7 @@ The `scapi_custom_apis_status` tool checks the registration status of custom API
 - Provides per-site details (one row per endpoint per site).
 - Supports filtering, grouping, and column selection.
 
-**Important:** This tool is **remote only** - it queries your live instance. For schema definitions, use [`scapi_schemas_list`](./scapi-schemas-list) with `apiFamily: "custom"`.
+**Important:** This tool is **remote only** - it queries your live instance. For schema definitions, use [`scapi_schemas_list`](./scapi-schemas-list) with `apiFamily: "custom"`. To create a new custom API in your project, use [`scapi_custom_api_scaffold`](./scapi-custom-api-scaffold).
 
 ## Authentication
 

docs/mcp/tools/scapi-schemas-list.md

@@ -164,6 +164,7 @@ Use the MCP tool to show me the full OpenAPI spec for shopper-products v1.
 
 - [SCAPI Toolset](../toolsets#scapi) - Overview of SCAPI discovery tools
 - [scapi_custom_apis_status](./scapi-custom-apis-status) - Check custom API endpoint registration status
+- [scapi_custom_api_scaffold](./scapi-custom-api-scaffold) - Generate a new custom API in a cartridge
 - [Authentication Setup](../../guide/authentication#scapi-authentication) - Set up SCAPI authentication with required roles and scopes
 - [Configuration](../configuration) - Configure OAuth credentials
 - [CLI Reference](../../cli/scapi-schemas) - Equivalent CLI commands: `b2c scapi schemas list` and `b2c scapi schemas get`

docs/mcp/toolsets.md

@@ -62,6 +62,7 @@ PWA Kit v3 development tools for building headless storefronts.
 | Tool | Description | Documentation |
 |------|-------------|---------------|
 | [`scapi_schemas_list`](./tools/scapi-schemas-list) | List or fetch SCAPI schemas (standard and custom). Use apiFamily: "custom" for custom APIs. | [View details](./tools/scapi-schemas-list) |
+| [`scapi_custom_api_scaffold`](./tools/scapi-custom-api-scaffold) | Generate a new custom SCAPI endpoint (schema, api.json, script.js) in an existing cartridge. | [View details](./tools/scapi-custom-api-scaffold) |
 | [`scapi_custom_apis_status`](./tools/scapi-custom-apis-status) | Get registration status of custom API endpoints (active/not_registered). Remote only, requires OAuth. | [View details](./tools/scapi-custom-apis-status) |
 | [`mrt_bundle_push`](./tools/mrt-bundle-push) | Build, push bundle (optionally deploy) | [View details](./tools/mrt-bundle-push) |
 
@@ -78,6 +79,7 @@ Salesforce Commerce API discovery and exploration.
 | Tool | Description | Documentation |
 |------|-------------|---------------|
 | [`scapi_schemas_list`](./tools/scapi-schemas-list) | List or fetch SCAPI schemas (standard and custom). Use apiFamily: "custom" for custom APIs. | [View details](./tools/scapi-schemas-list) |
+| [`scapi_custom_api_scaffold`](./tools/scapi-custom-api-scaffold) | Generate a new custom SCAPI endpoint (schema, api.json, script.js) in an existing cartridge. | [View details](./tools/scapi-custom-api-scaffold) |
 | [`scapi_custom_apis_status`](./tools/scapi-custom-apis-status) | Get registration status of custom API endpoints (active/not_registered). Remote only, requires OAuth. | [View details](./tools/scapi-custom-apis-status) |
 
 ## STOREFRONTNEXT
@@ -95,12 +97,13 @@ Storefront Next development tools for building modern storefronts.
 | `storefront_next_development_guidelines` | Get Storefront Next development guidelines and best practices | — |
 | [`storefront_next_page_designer_decorator`](./tools/storefront-next-page-designer-decorator) | Add Page Designer decorators to Storefront Next components | [View details](./tools/storefront-next-page-designer-decorator) |
 | [`scapi_schemas_list`](./tools/scapi-schemas-list) | List or fetch SCAPI schemas (standard and custom). Use apiFamily: "custom" for custom APIs. | [View details](./tools/scapi-schemas-list) |
+| [`scapi_custom_api_scaffold`](./tools/scapi-custom-api-scaffold) | Generate a new custom SCAPI endpoint (schema, api.json, script.js) in an existing cartridge. | [View details](./tools/scapi-custom-api-scaffold) |
 | [`scapi_custom_apis_status`](./tools/scapi-custom-apis-status) | Get registration status of custom API endpoints (active/not_registered). Remote only, requires OAuth. | [View details](./tools/scapi-custom-apis-status) |
 | [`mrt_bundle_push`](./tools/mrt-bundle-push) | Build, push bundle (optionally deploy) | [View details](./tools/mrt-bundle-push) |
 
 ## Tool Deduplication
 
-Some tools appear in multiple toolsets (for example, `mrt_bundle_push`, `scapi_schemas_list`, `scapi_custom_apis_status`). When using multiple toolsets, tools are automatically deduplicated, so you'll only see each tool once.
+Some tools appear in multiple toolsets (for example, `mrt_bundle_push`, `scapi_schemas_list`, `scapi_custom_api_scaffold`, `scapi_custom_apis_status`). When using multiple toolsets, tools are automatically deduplicated, so you'll only see each tool once.
 
 ## Next Steps
 

packages/b2c-dx-mcp/README.md

@@ -121,7 +121,7 @@ The `storefront_next_development_guidelines` tool provides critical architecture
 
 ##### SCAPI Discovery
 
-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).
+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). Use **scapi_customapi_scaffold** to generate a new custom API in an existing cartridge.
 
 **SCAPI Schemas (tool: `scapi_schemas_list`):**
 
@@ -138,6 +138,14 @@ Discover schema metadata and fetch OpenAPI specs for both standard and custom SC
 - ✅ "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 Scaffold (tool: `scapi_customapi_scaffold`):**
+
+Generate a new custom SCAPI endpoint in an existing cartridge (OAS 3.0 schema.yaml, api.json, script.js with example GET endpoints). Requires **apiName** (kebab-case). Optional: **cartridgeName** (omit to use the first cartridge found under the working directory), **apiType** (shopper | admin; default shopper), **apiDescription**, **projectRoot**, **outputDir**. Set `--working-directory` (or SFCC_WORKING_DIRECTORY) so the server discovers cartridges in your project. Files are always generated (no dry run) and existing files are never overwritten.
+
+- ✅ "Use the MCP tool to scaffold a new custom API named my-products."
+- ✅ "Use the MCP tool to create a custom admin API called customer-trips."
+- ✅ "Use the MCP tool to scaffold a new shopper custom API gift-registry-list in cartridge app_custom."
+
 **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.
@@ -282,6 +290,7 @@ PWA Kit v3 development tools for building headless storefronts.
 |------|-------------|
 | `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` | Generate a new custom SCAPI endpoint (OAS 3.0 schema, api.json, script.js) in an existing cartridge. Required: apiName. Optional: cartridgeName (defaults to first cartridge), apiType, apiDescription, projectRoot, outputDir. |
 | `mrt_bundle_push` | Build, push bundle (optionally deploy) |
 
 #### SCAPI
@@ -292,6 +301,7 @@ Salesforce Commerce API discovery and exploration.
 |------|-------------|
 | `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` | Generate a new custom SCAPI endpoint (OAS 3.0 schema, api.json, script.js) in an existing cartridge. Required: apiName. Optional: cartridgeName (defaults to first cartridge), apiType, apiDescription, projectRoot, outputDir. |
 
 #### STOREFRONTNEXT
 Storefront Next development tools for building modern storefronts.
@@ -303,6 +313,7 @@ Storefront Next development tools for building modern storefronts.
 | `storefront_next_page_designer_decorator` | Add Page Designer decorators to Storefront Next components |
 | `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` | Generate a new custom SCAPI endpoint (OAS 3.0 schema, api.json, script.js) in an existing cartridge. Required: apiName. Optional: cartridgeName (defaults to first cartridge), apiType, apiDescription, projectRoot, outputDir. |
 | `mrt_bundle_push` | Build, push bundle (optionally deploy) |
 
 > **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.

packages/b2c-dx-mcp/src/tools/scapi/index.ts

@@ -8,7 +8,7 @@
  * SCAPI toolset for B2C Commerce.
  *
  * This toolset provides MCP tools for Salesforce Commerce API (SCAPI) discovery and exploration.
- * Includes both standard SCAPI schemas and custom API status tools.
+ * Includes standard SCAPI schemas, custom API status, and custom API scaffold tools.
  *
  * @module tools/scapi
  */
@@ -17,6 +17,7 @@ import type {McpTool} from '../../utils/index.js';
 import type {Services} from '../../services.js';
 import {createScapiSchemasListTool} from './scapi-schemas-list.js';
 import {createScapiCustomApisStatusTool} from './scapi-custom-apis-status.js';
+import {createScaffoldCustomApiTool} from './scapi-custom-api-scaffold.js';
 
 /**
  * Creates all tools for the SCAPI toolset.
@@ -25,5 +26,9 @@ import {createScapiCustomApisStatusTool} from './scapi-custom-apis-status.js';
  * @returns Array of MCP tools
  */
 export function createScapiTools(loadServices: () => Services): McpTool[] {
-  return [createScapiSchemasListTool(loadServices), createScapiCustomApisStatusTool(loadServices)];
+  return [
+    createScapiSchemasListTool(loadServices),
+    createScapiCustomApisStatusTool(loadServices),
+    createScaffoldCustomApiTool(loadServices),
+  ];
 }