@W-20592464 SCAPI Schemas List and SCAPI Custom APIs Status MCP tools by yhsieh1 · Pull Request #133 · SalesforceCommerceCloud/b2c-developer-tooling

yhsieh1 · 2026-02-10T23:23:51Z

Summary

This PR defines the scapi_custom_apis_status MCP tool to get the status of Custom API endpoints (which are active, which failed to register). Remote only—no local cartridge scan or schema retrieval. Requires OAuth (sfcc.custom-apis scope). For listing/fetching SCAPI schemas (standard APIs), use scapi_schemas_list.

Test coverage script is enabled.

Two SCAPI Tools (Scope of This PR)

The MCP exposes two SCAPI-related tools. This PR and doc cover only the second one:

Tool	Purpose	When to use
`scapi_schemas_list`	List or fetch SCAPI schemas (both standard and custom). Two modes: discovery (metadata) and fetch (full OpenAPI schema). Use `apiFamily: "custom"` for custom APIs.	"What SCAPI APIs are available?", "Show me shopper-products schema", "List custom API definitions", filtering by apiFamily / apiName / apiVersion.
`scapi_custom_apis_status` (this PR)	Get registration status of Custom API endpoints (active / not_registered). Remote only.	"What's the status of my custom API endpoints?", "Which endpoints are active?"

Test Plan

Prerequisites

MCP server built: pnpm --filter @salesforce/b2c-dx-mcp run build
MCP server running with a toolset that includes the tool (e.g. SCAPI, PWAV3, or STOREFRONTNEXT)
For remote tests: Valid OAuth configured (tenantId, shortCode, sfcc.custom-apis scope), e.g. via dw.json, env vars, or CLI args
MCP configured in Claude Desktop or Cursor

MCP configuration example:

{
  "mcpServers": {
    "b2c-dx": {
      "command": "/path/to/packages/b2c-dx-mcp/bin/dev.js",
      "args": [
        "--working-directory",
        "/path/to/your-cartridge-or-storefront-project",
        "--toolsets",
        "SCAPI",
        "--allow-non-ga-tools"
      ]
    }
  }
}

Test Cases

1. Basic Functionality

Scenario: List custom APIs with default parameters.

Test: Prompt "What custom APIs are in this project?" or "List custom SCAPI endpoints."

Expected Behavior:

Tool returns merged remote + local endpoints (if OAuth configured)

2. Status Filtering

Scenario: Filter endpoints by deployment status.

Test: Prompt "Show me only active custom APIs" or "Which custom APIs failed to deploy?"

Expected Behavior:

With status: "active": Returns only active endpoints (remote-sourced endpoints have status: "active"; local-only may still appear as "not_registered")
With status: "not_registered": Returns only non-registered endpoints (includes local-only and failed remote registrations)
Filtering applies correctly to merged results

3. Schema Inclusion

Scenario: Include full OpenAPI schemas in response.

Test: Prompt "Get custom APIs with full OpenAPI schemas" or "List custom APIs and include their schema definitions."

Expected Behavior:

Tool called with includeSchemas: true
Each endpoint includes schema field with OpenAPI YAML content
Response includes schemasRetrieved count
Large schemas are capped appropriately; invalid YAML skipped without breaking response
If WebDAV fails for remote: webdavError may be set; local schemas still included

4. Error Handling

Scenario: Handle missing credentials and empty results gracefully.

Test Cases:

No OAuth: Working directory with local cartridges → returns local endpoints only, remoteError set, remoteCount: 0
No local APIs: OAuth configured, no local schemas → returns remote endpoints only, localCount: 0
No APIs at all: No OAuth, no local schemas → empty result with total: 0, appropriate error message

Expected Behavior:

No crashes on missing credentials or empty results
Clear error messages via remoteError or message fields
Tool handles all edge cases gracefully

Tests pass (pnpm test)
Code is formatted (pnpm run format)

Resolved conflicts: - packages/b2c-tooling-sdk/package.json: Kept both ./operations/scapi and ./operations/content exports - packages/b2c-dx-mcp/package.json: Kept yaml dependency from branch Co-authored-by: Cursor <cursoragent@cursor.com>

clavery · 2026-02-11T02:24:27Z

nit: can you add a changeset

patricksullivansf

Aside:

Tool Selection
Scenario: Ensure correct tool is used for schemas vs endpoint status.

Rather than part of a tool implementation PR, I think tool selection testing is more reliably to be done as a separate task, ideally with dozens of tools enabled.

patricksullivansf · 2026-02-11T03:10:54Z

+        columns: z
+          .string()
+          .optional()
+          .describe(
+            'Comma-separated fields to return, e.g. type,apiName,status,siteId. Valid: type, apiName, apiVersion, cartridgeName, endpointPath, httpMethod, status, siteId, securityScheme, operationId, schemaFile, implementationScript, errorReason, id.',
+          ),
+        extended: z
+          .boolean()
+          .optional()
+          .describe(
+            'If true, return all available fields (14 fields total). If false or omitted, return default columns only (6 fields: type, apiName, endpointPath, httpMethod, status, siteId). Use extended: true when you need additional details like apiVersion, cartridgeName, securityScheme, operationId, schemaFile, implementationScript, errorReason, or id. Note: If you only need specific fields, use columns parameter instead for more control.',


columns and extended seem to do largely the same thing: decide what columns are returned. We could make the LLM have an easier chore by giving them one option instead of two.

From the convenience and token usage perspective, more thinking and more data means more token. I will simplify it so that agent can get common default or specific columns.

patricksullivansf · 2026-02-11T03:13:46Z

+  return createToolAdapter<CustomListInput, CustomListOutput>(
+    {
+      name: 'scapi_custom_apis_status',
+      description: `List Custom SCAPI API endpoints and their registration status (active vs not_registered). Returns individual HTTP endpoints (e.g., GET /hello, POST /items/{id}) with deployment status, one row per endpoint per site. Use this for developer-defined custom APIs only.


although i like the extended description, we should keep in mind that tool descriptions eat context tokens for EVERY request, even when not used. Across dozens if tools this can get unwieldy.We might want to ask if the LLM can compress this a bit.

That's true. Definitely will compact these.

patricksullivansf · 2026-02-11T03:15:02Z

+const DEFAULT_COLUMNS = ['type', 'apiName', 'endpointPath', 'httpMethod', 'status', 'siteId'] as const;
+const ALL_COLUMN_KEYS = [


weird to me these aren't defined at the SDK level.

I do not need these. Removed them.

patricksullivansf · 2026-02-11T03:17:42Z

+  const {apiFamily, apiName, apiVersion, expandAll, status} = args;
+
+  // Warn if status filter was provided (it's ignored in fetch mode)
+  const warning = status


for my info, what does the LLM typically do when it gets this warning mixed into the response?

It usually do nothing to it. We have description on when to send status and I do not see agent send it by mistake. This is extra info.

patricksullivansf · 2026-02-11T03:19:01Z

+
+**Requirements:** Instance must have shortCode, tenantId, and OAuth with sfcc.scapi-schemas scope.`,
+      toolsets: ['PWAV3', 'SCAPI', 'STOREFRONTNEXT'],
+      isGA: true,


do we really want to go straight to GA?

Oops, I will update this. Thanks!

patricksullivansf · 2026-02-11T03:20:15Z

+          .enum(['current', 'deprecated'])
+          .optional()
+          .describe(
+            'Filter by schema status. "current" returns only active schemas, "deprecated" returns deprecated ones. Only works in discovery mode.',


which is better, default, etc? or does the LLM do a good job of guessing?

Agent does a good job but I can improve it by setting a default.

patricksullivansf · 2026-02-11T03:20:45Z

+          .boolean()
+          .optional()
+          .describe(
+            'Include full OpenAPI schemas. Requires all three identifiers (apiFamily, apiName, apiVersion). Default false (returns metadata only). WARNING: Slower and increases response size.',


love this performance call out.

patricksullivansf · 2026-02-11T03:28:05Z

+
+  describe('handler', () => {
+    it('should return endpoints and total when API returns data', async () => {
+      mockGet.resolves({


I would rather MCP tests didn't include the SDK, but there are arguments either way.

pro to mocking API response - guarantees integration from API response to MCP output is verified.

con makes the MCP tests brittle and sensitive to SDK implementation, instead of relying on SDK to enforce it's contract with consumers to adapt and hide API changes.

I agree. If you can mock the SDK the better. We have good test coverage there. Coverage here should be on MCP linnes

Since its mono repo and its very easy to detect SDK changes. I will refactor the test to focus on MCP side test only. Thanks!

yhsieh1 · 2026-02-11T12:32:43Z

Aside:

Tool Selection
Scenario: Ensure correct tool is used for schemas vs endpoint status.

Rather than part of a tool implementation PR, I think tool selection testing is more reliably to be done as a separate task, ideally with dozens of tools enabled.

Yes, agent makes decision on which tool to use and the section just to see if the agent use both tools correctly. I will update the section. Thanks.

yhsieh1 · 2026-02-11T16:24:09Z

Both tools description is compacted to save token when agent uses it. Also removed redundant extended option to avoid agent thinks too much.

patricksullivansf · 2026-02-11T20:34:53Z

hmm. i didn't include this in my #110 and #114. should i have? should we address those here?

I guess we can address that later. This is the first one we have in MCP. We probably need to add them all.

You can add them later, and you can add multiple at once. it just might not tag it to the original PR

@patricksullivansf changeset is updated. Please check.

Co-authored-by: Cursor <cursoragent@cursor.com>

yhsieh1 added 6 commits February 8, 2026 16:25

@W-20592464 scapi and custom api list mcp tool

46debf3

clean up

87df5b1

add test coverage

f12d960

refactor

1c68b2c

revert package.json

2becc5e

update pnpm-lock.yaml

15937a7

yhsieh1 requested review from clavery and patricksullivansf as code owners February 10, 2026 23:23

yhsieh1 requested a review from allison-grady February 10, 2026 23:24

Merge origin/main into t/commerce/W-20592464

cd8fc0b

Resolved conflicts: - packages/b2c-tooling-sdk/package.json: Kept both ./operations/scapi and ./operations/content exports - packages/b2c-dx-mcp/package.json: Kept yaml dependency from branch Co-authored-by: Cursor <cursoragent@cursor.com>

patricksullivansf reviewed Feb 11, 2026

View reviewed changes

yhsieh1 added 2 commits February 11, 2026 10:09

refactor and simplify tools

4b51a41

add changelog and minor description update

f31ec2e

yhsieh1 requested a review from patricksullivansf February 11, 2026 16:24

Merge branch 'main' into t/commerce/W-20592464

f6213db

patricksullivansf previously approved these changes Feb 11, 2026

View reviewed changes

yhsieh1 added 2 commits February 12, 2026 08:48

Merge branch 'main' into t/commerce/W-20592464

32c5181

update changeset

1b6aa2c

yhsieh1 dismissed patricksullivansf’s stale review via 1b6aa2c February 12, 2026 14:09

yhsieh1 requested a review from patricksullivansf February 12, 2026 14:15

update changeset

270ef24

clavery reviewed Feb 12, 2026

View reviewed changes

Comment thread packages/b2c-tooling-sdk/src/schemas/security-schemes.ts

yhsieh1 added 2 commits February 12, 2026 10:14

move getApiType to schemas module

a3d86d1

correct the test file

8677a80

patricksullivansf previously approved these changes Feb 12, 2026

View reviewed changes

yhsieh1 requested a review from clavery February 12, 2026 19:19

Merge main into feature branch - resolve package.json conflict

5886485

Co-authored-by: Cursor <cursoragent@cursor.com>

yhsieh1 dismissed patricksullivansf’s stale review via 5886485 February 13, 2026 13:07

yhsieh1 requested a review from patricksullivansf February 13, 2026 13:08

clavery previously approved these changes Feb 13, 2026

View reviewed changes

updste .mocharc.json

3f7ff43

yhsieh1 dismissed clavery’s stale review via 3f7ff43 February 13, 2026 13:36

yhsieh1 added 2 commits February 13, 2026 08:44

update test:ci

186a59b

fix c8 coverage

76baae5

clavery previously approved these changes Feb 13, 2026

View reviewed changes

fix c8 config

bc4744c

yhsieh1 dismissed clavery’s stale review via bc4744c February 13, 2026 13:59

yhsieh1 added 6 commits February 13, 2026 09:29

add unit test coverage

73f4e25

update coverage thresholds

40195a8

disable check coverage

f3f9c8a

remove mcp unit test from ci

86fcd1b

enable mcp unit test

bce4d1f

disable mcp unit test

fdd0c38

clavery previously approved these changes Feb 13, 2026

View reviewed changes

enable mcp test and fix test

2f26600

yhsieh1 dismissed clavery’s stale review via 2f26600 February 13, 2026 15:11

Merge branch 'main' into t/commerce/W-20592464

aeb26b3

yhsieh1 requested a review from clavery February 13, 2026 15:18

clavery approved these changes Feb 13, 2026

View reviewed changes

yhsieh1 enabled auto-merge (squash) February 13, 2026 17:21

Merge branch 'main' into t/commerce/W-20592464

d8b0ffa

wei-liu-sf approved these changes Feb 13, 2026

View reviewed changes

patricksullivansf approved these changes Feb 13, 2026

View reviewed changes

yhsieh1 merged commit 1485923 into main Feb 13, 2026
3 checks passed

yhsieh1 deleted the t/commerce/W-20592464 branch February 13, 2026 18:16

github-actions Bot mentioned this pull request Feb 13, 2026

Next Release: changelog and version packages #145

Merged

patricksullivansf mentioned this pull request Feb 13, 2026

add page-designer-decorator tool for Storefront Next #150

Merged

2 tasks

		const DEFAULT_COLUMNS = ['type', 'apiName', 'endpointPath', 'httpMethod', 'status', 'siteId'] as const;
		const ALL_COLUMN_KEYS = [

Uh oh!

Conversation

yhsieh1 commented Feb 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Two SCAPI Tools (Scope of This PR)

Test Plan

Prerequisites

Test Cases

1. Basic Functionality

2. Status Filtering

3. Schema Inclusion

4. Error Handling

Uh oh!

clavery commented Feb 11, 2026

Uh oh!

patricksullivansf left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yhsieh1 Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yhsieh1 Feb 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

yhsieh1 commented Feb 11, 2026

Uh oh!

yhsieh1 commented Feb 11, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

yhsieh1 commented Feb 10, 2026 •

edited

Loading

yhsieh1 Feb 11, 2026 •

edited

Loading

yhsieh1 Feb 11, 2026 •

edited

Loading