@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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -268,10 +268,11 @@ export default class McpServerCommand extends BaseCommand<typeof McpServerComman | |
| ...mrt.options, | ||
| }; | ||
|
|
||
| // Combine B2C instance flags, MRT config, and working directory so tools use the configured project path | ||
| const flagConfig = { | ||
| ...extractInstanceFlags(this.flags as Record<string, unknown>), | ||
| ...mrt.config, | ||
| workingDirectory: this.flags['working-directory'], | ||
|
Contributor
Contributor
There was a problem hiding this comment. getBaseConfigOptions() already supplies workingDirectory so we do not need it here again. |
||
| }; | ||
|
|
||
| return loadConfig(flagConfig, options); | ||
|
|
||
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,241 @@ | ||
| /* | ||
| * 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_customapi_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; | ||
| /** Include example GET/POST endpoints in schema and script. Default: true */ | ||
| includeExampleEndpoints?: boolean; | ||
|
Contributor
There was a problem hiding this comment. Wonder when agent will set this to false? Do we need this input?
Collaborator
Author
There was a problem hiding this comment. it's default to true. I can remove it. |
||
| /** Project root for cartridge discovery and output. Default: MCP working directory */ | ||
| projectRoot?: string; | ||
| /** Output directory override. Default: scaffold default or project root */ | ||
| outputDir?: string; | ||
| /** If true, preview only (no files written). Default: false */ | ||
| dryRun?: boolean; | ||
|
Contributor
There was a problem hiding this comment. What will happen when dryRun is true? Do we need this? |
||
| /** If true, overwrite existing files. Default: false */ | ||
| force?: boolean; | ||
| } | ||
|
|
||
| /** | ||
| * Output schema for scapi_customapi_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_customapi_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_customapi_scaffold', | ||
|
Contributor
There was a problem hiding this comment. We have scapi_custom_apis_status tool, can we unify the tool name? Maybe scapi_custom_api_scaffold
Collaborator
Author
There was a problem hiding this comment. This name "scapi_custom_api_scaffold" is following the LLD. Once LLD is updated, will update here.
Contributor
There was a problem hiding this comment. @wei-liu-sf I corrected the name in LLD so that it matches the naming with other scapi tools. Please update it to |
||
| 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. \ | ||
|
Contributor
There was a problem hiding this comment. Can we remove LCI from the description? We should try to keep description short and simple. Mention of CLI might confuse agent. |
||
| Required: apiName (kebab-case). Optional: cartridgeName (defaults to first cartridge found in project), apiType (shopper|admin), apiDescription, includeExampleEndpoints, projectRoot, outputDir, dryRun, force. \ | ||
|
Contributor
There was a problem hiding this comment. Description can be improved to avoid duplicated inputs info that is specified in the input schema. Also we probably can skip the mention of CLI since that seems not help agent to use the tool. |
||
| 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.'), | ||
| includeExampleEndpoints: z.boolean().optional().describe('Include example GET/POST endpoints. Default: true'), | ||
| 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'), | ||
| dryRun: z.boolean().optional().describe('If true, preview only (no files written). Default: false'), | ||
| force: z.boolean().optional().describe('If true, overwrite existing files. Default: false'), | ||
| }, | ||
| 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: args.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: args.dryRun ?? false, | ||
| files: [], | ||
| error: | ||
| 'No cartridges found in project. Add a cartridge (directory with .project file) or pass cartridgeName explicitly.', | ||
|
Contributor
There was a problem hiding this comment. Can we give more details so that agent knows how to add a cartridge project? |
||
| }; | ||
| } | ||
| cartridgeName = cartridges[0].name; | ||
| } | ||
|
|
||
| const providedVariables: Record<string, boolean | string> = { | ||
| apiName: args.apiName, | ||
| cartridgeName, | ||
| }; | ||
| if (args.apiType !== undefined) providedVariables.apiType = args.apiType; | ||
| if (args.apiDescription !== undefined) providedVariables.apiDescription = args.apiDescription; | ||
| if (args.includeExampleEndpoints !== undefined) { | ||
| providedVariables.includeExampleEndpoints = args.includeExampleEndpoints; | ||
| } | ||
|
|
||
| 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: args.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: args.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: args.dryRun ?? false, | ||
| force: args.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: args.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
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.