@W-21105798: Scaffold Custom API MCP Tool #204
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,230 @@ | ||
| /* | ||
| * 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 | ||
| */ | ||
|
|
||
| /** | ||
| * SCAPI Custom API Scaffold tool. | ||
| * | ||
| * Generates a new custom SCAPI endpoint using the SDK's custom-api scaffold | ||
| * (schema.yaml, api.json, script.js). Mirrors CLI: b2c scaffold generate custom-api. | ||
| * | ||
| * @module tools/scapi/scapi-customapi-scaffold | ||
| */ | ||
|
|
||
| import path from 'node:path'; | ||
| import {z} from 'zod'; | ||
| import {createToolAdapter, jsonResult, errorResult} from '../adapter.js'; | ||
| import type {Services} from '../../services.js'; | ||
| import type {McpTool} from '../../utils/index.js'; | ||
| import { | ||
| createScaffoldRegistry, | ||
| generateFromScaffold, | ||
| resolveScaffoldParameters, | ||
| resolveOutputDirectory, | ||
| } from '@salesforce/b2c-tooling-sdk/scaffold'; | ||
| import {findCartridges} from '@salesforce/b2c-tooling-sdk/operations/code'; | ||
|
|
||
| const CUSTOM_API_SCAFFOLD_ID = 'custom-api'; | ||
|
|
||
| /** | ||
| * Input schema for scapi_custom_api_scaffold tool. | ||
| * Parameters match the custom-api scaffold: apiName, apiType, cartridgeName, etc. | ||
| */ | ||
| interface ScaffoldCustomApiInput { | ||
| /** API name (kebab-case, e.g. my-products). Required. */ | ||
| apiName: string; | ||
| /** Cartridge name that will contain the API. Optional; defaults to first cartridge found in project. */ | ||
| cartridgeName?: string; | ||
| /** API type: admin (no siteId) or shopper (siteId, customer-facing). Default: shopper */ | ||
| apiType?: 'admin' | 'shopper'; | ||
| /** Short description of the API. Default: "A custom B2C Commerce API" */ | ||
| apiDescription?: string; | ||
| /** Project root for cartridge discovery and output. Default: MCP working directory */ | ||
| projectRoot?: string; | ||
| /** Output directory override. Default: scaffold default or project root */ | ||
| outputDir?: string; | ||
| } | ||
|
|
||
| /** | ||
| * Output schema for scapi_custom_api_scaffold tool. | ||
| */ | ||
| interface ScaffoldCustomApiOutput { | ||
| scaffold: string; | ||
| outputDir: string; | ||
| dryRun: boolean; | ||
| files: Array<{ | ||
| path: string; | ||
| action: string; | ||
| skipReason?: string; | ||
| }>; | ||
| postInstructions?: string; | ||
| error?: string; | ||
| } | ||
|
|
||
| /** | ||
| * Creates the scapi_custom_api_scaffold tool. | ||
| * | ||
| * Uses @salesforce/b2c-tooling-sdk scaffold: registry, resolveScaffoldParameters, | ||
| * resolveOutputDirectory, generateFromScaffold. cartridgeName must be a cartridge | ||
| * discovered under projectRoot (e.g. from .project or cartridges/). CLI: b2c scaffold generate custom-api. | ||
| */ | ||
| export function createScaffoldCustomApiTool(loadServices: () => Services): McpTool { | ||
| return createToolAdapter<ScaffoldCustomApiInput, ScaffoldCustomApiOutput>( | ||
| { | ||
| name: 'scapi_custom_api_scaffold', | ||
| description: `Generate a new custom SCAPI endpoint (OAS 3.0 schema, api.json, script.js) in an existing cartridge. \ | ||
| Uses the same scaffold as CLI: b2c scaffold generate custom-api. \ | ||
|
||
| Required: apiName (kebab-case). Optional: cartridgeName (defaults to first cartridge found in project), apiType (shopper|admin), apiDescription, includeExampleEndpoints, projectRoot, outputDir. \ | ||
| cartridgeName must be one of the cartridges discovered under projectRoot (--working-directory or SFCC_WORKING_DIRECTORY). \ | ||
| Set projectRoot to override the working directory. \ | ||
| For faster runs, set --working-directory to your cartridge project root (same as where you would run the CLI from). \ | ||
| CLI: b2c scaffold generate custom-api.`, | ||
| toolsets: ['PWAV3', 'SCAPI', 'STOREFRONTNEXT'], | ||
| isGA: false, | ||
| requiresInstance: false, | ||
| inputSchema: { | ||
| apiName: z | ||
| .string() | ||
| .min(1) | ||
| .describe( | ||
| 'API name in kebab-case (e.g. my-products). Must start with lowercase letter, only letters, numbers, hyphens.', | ||
| ), | ||
| cartridgeName: z | ||
| .string() | ||
| .min(1) | ||
| .nullish() | ||
| .describe( | ||
| 'Cartridge name that will contain the API. Optional; omit to use the first cartridge found under working directory (--working-directory or SFCC_WORKING_DIRECTORY).', | ||
| ), | ||
| apiType: z | ||
| .enum(['admin', 'shopper']) | ||
| .optional() | ||
| .describe('Admin (no siteId) or shopper (siteId, customer-facing). Default: shopper'), | ||
| apiDescription: z.string().optional().describe('Short description of the API.'), | ||
| projectRoot: z | ||
| .string() | ||
| .nullish() | ||
| .describe( | ||
| 'Project root for cartridge discovery. Default: working directory. Set to override the working directory.', | ||
| ), | ||
| outputDir: z.string().optional().describe('Output directory override. Default: project root'), | ||
| }, | ||
| async execute(args, {services}) { | ||
| const projectRoot = path.resolve(args.projectRoot ?? services.getWorkingDirectory()); | ||
|
|
||
| const registry = createScaffoldRegistry(); | ||
| const scaffold = await registry.getScaffold(CUSTOM_API_SCAFFOLD_ID, { | ||
| projectRoot, | ||
| }); | ||
|
|
||
| if (!scaffold) { | ||
| return { | ||
| scaffold: CUSTOM_API_SCAFFOLD_ID, | ||
| outputDir: projectRoot, | ||
| dryRun: false, | ||
| files: [], | ||
| error: `Scaffold not found: ${CUSTOM_API_SCAFFOLD_ID}. Ensure @salesforce/b2c-tooling-sdk is installed.`, | ||
| }; | ||
| } | ||
|
|
||
| let cartridgeName = args.cartridgeName; | ||
| // If cartridgeName is not provided, use the first cartridge found in project directory. | ||
| if (!cartridgeName) { | ||
| const cartridges = findCartridges(projectRoot); | ||
| if (cartridges.length === 0) { | ||
| return { | ||
| scaffold: CUSTOM_API_SCAFFOLD_ID, | ||
| outputDir: projectRoot, | ||
| dryRun: false, | ||
| files: [], | ||
| error: | ||
| 'No cartridges found in project. Custom API scaffold requires an existing cartridge. Create a cartridge (directory with .project file) first. You can use the `b2c scaffold cartridge` command to create a cartridge.', | ||
| }; | ||
| } | ||
| cartridgeName = cartridges[0].name; | ||
| } | ||
|
|
||
| const providedVariables: Record<string, boolean | string> = { | ||
| apiName: args.apiName, | ||
| cartridgeName, | ||
| includeExampleEndpoints: true, | ||
| }; | ||
| if (args.apiType !== undefined) providedVariables.apiType = args.apiType; | ||
| if (args.apiDescription !== undefined) providedVariables.apiDescription = args.apiDescription; | ||
|
|
||
| const resolved = await resolveScaffoldParameters(scaffold, { | ||
| providedVariables, | ||
| projectRoot, | ||
| useDefaults: true, | ||
| }); | ||
|
|
||
| if (resolved.errors.length > 0) { | ||
| const message = resolved.errors.map((e) => `${e.parameter}: ${e.message}`).join('; '); | ||
| return { | ||
| scaffold: CUSTOM_API_SCAFFOLD_ID, | ||
| outputDir: projectRoot, | ||
| dryRun: false, | ||
| files: [], | ||
| error: `Parameter validation failed: ${message}`, | ||
| }; | ||
| } | ||
|
|
||
| const missingRequired = resolved.missingParameters.filter((p) => p.required); | ||
| if (missingRequired.length > 0) { | ||
| return { | ||
| scaffold: CUSTOM_API_SCAFFOLD_ID, | ||
| outputDir: projectRoot, | ||
| dryRun: false, | ||
| files: [], | ||
| error: `Missing required parameter: ${missingRequired[0].name}. For cartridgeName, ensure the cartridge exists in the project (under projectRoot).`, | ||
| }; | ||
| } | ||
|
|
||
| const outputDir = resolveOutputDirectory({ | ||
| outputDir: args.outputDir, | ||
| scaffold, | ||
| projectRoot, | ||
| }); | ||
|
|
||
| try { | ||
| const result = await generateFromScaffold(scaffold, { | ||
| outputDir, | ||
| variables: resolved.variables as Record<string, boolean | string>, | ||
| dryRun: false, | ||
| force: false, | ||
| }); | ||
|
|
||
| return { | ||
| scaffold: CUSTOM_API_SCAFFOLD_ID, | ||
| outputDir, | ||
| dryRun: result.dryRun, | ||
| files: result.files.map((f) => ({ | ||
| path: f.path, | ||
| action: f.action, | ||
| skipReason: f.skipReason, | ||
| })), | ||
| postInstructions: result.postInstructions, | ||
| }; | ||
| } catch (error) { | ||
| const message = error instanceof Error ? error.message : String(error); | ||
| return { | ||
| scaffold: CUSTOM_API_SCAFFOLD_ID, | ||
| outputDir, | ||
| dryRun: false, | ||
| files: [], | ||
| error: `Scaffold generation failed: ${message}`, | ||
| }; | ||
| } | ||
| }, | ||
| formatOutput(output) { | ||
| if (output.error) { | ||
| return errorResult(output.error); | ||
| } | ||
| return jsonResult(output); | ||
| }, | ||
| }, | ||
| loadServices, | ||
| ); | ||
| } | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.