Skip to content

Commit e2392b3

Browse files
yhsieh1yhsieh1
authored
@W-20590941 B2C DX MCP Server Foundation (#16)
1 parent a5ae91c commit e2392b3

File tree

28 files changed

+4522
-19
lines changed

28 files changed

+4522
-19
lines changed

‎.gitignore‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,12 @@
22
*-error.log
33
**/.DS_Store
44
/.idea
5-
/dist
5+
dist
66
/tmp
7-
/node_modules
7+
node_modules
88
/coverage
99
oclif.manifest.json
10+
*.tsbuildinfo
1011

1112

1213
yarn.lock

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

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
{
2+
"watch-extensions": [
3+
"ts"
4+
],
5+
"recursive": true,
6+
"reporter": "spec",
7+
"timeout": 60000,
8+
"node-option": [
9+
"import=tsx"
10+
]
11+
}
12+

‎packages/b2c-dx-mcp/README.md‎

Lines changed: 283 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,283 @@
1+
# @salesforce/b2c-dx-mcp
2+
3+
MCP (Model Context Protocol) server for Salesforce B2C Commerce Cloud developer experience tools.
4+
5+
> ⚠️ **Active Development**: This package is under active development. All tools are currently **placeholder implementations** that return mock responses. Tool implementations will be added incrementally.
6+
7+
## Overview
8+
9+
This package provides an MCP server that exposes B2C Commerce developer tools for AI assistants. Built with [oclif](https://oclif.io/) for robust CLI handling with auto-generated help and environment variable support.
10+
11+
## Usage
12+
13+
Since the package is not yet published to npm, see the [Development](#development) section for local setup instructions.
14+
15+
### Supported Flags
16+
17+
#### MCP-Specific Flags
18+
19+
| Flag | Description |
20+
|------|-------------|
21+
| `--toolsets` | Comma-separated toolsets to enable (case-insensitive) |
22+
| `--tools` | Comma-separated individual tools to enable (case-insensitive) |
23+
| `--allow-non-ga-tools` | Enable experimental (non-GA) tools |
24+
25+
#### Global Flags (inherited from SDK)
26+
27+
| Flag | Description |
28+
|------|-------------|
29+
| `--config` | Path to dw.json config file (auto-discovered if not provided) |
30+
| `--instance` | Instance name from configuration file |
31+
| `--log-level` | Set logging verbosity (trace, debug, info, warn, error, silent) |
32+
| `--debug` | Enable debug logging |
33+
| `--json` | Output logs as JSON lines |
34+
| `--lang` | Language for messages |
35+
36+
### Configuration Examples
37+
38+
```json
39+
// Enable specific toolsets
40+
"args": ["--toolsets", "CARTRIDGES,MRT"]
41+
42+
// Enable specific tools
43+
"args": ["--tools", "cartridge_deploy,mrt_bundle_push"]
44+
45+
// Combine toolsets and tools
46+
"args": ["--toolsets", "CARTRIDGES", "--tools", "mrt_bundle_push"]
47+
48+
// Explicit config file path
49+
"args": ["--toolsets", "all", "--config", "/path/to/dw.json"]
50+
51+
// Enable experimental tools (required for placeholder tools)
52+
"args": ["--toolsets", "all", "--allow-non-ga-tools"]
53+
54+
// Enable debug logging
55+
"args": ["--toolsets", "all", "--debug"]
56+
```
57+
58+
### Available Toolsets and Tools
59+
60+
Use `--toolsets all` to enable all toolsets, or select specific ones with `--toolsets CARTRIDGES,MRT`.
61+
62+
> **Note:** All tools are currently placeholder implementations. Use `--allow-non-ga-tools` flag to enable them.
63+
64+
#### CARTRIDGES
65+
Code deployment and version management.
66+
- **Status:** 🚧 Placeholder
67+
68+
| Tool | Description |
69+
|------|-------------|
70+
| `cartridge_deploy` | Deploy cartridges to a B2C Commerce instance |
71+
72+
#### MRT
73+
Managed Runtime operations for PWA Kit and Storefront Next deployments.
74+
- **Status:** 🚧 Placeholder
75+
76+
| Tool | Description |
77+
|------|-------------|
78+
| `mrt_bundle_push` | Build, push bundle (optionally deploy) |
79+
80+
#### PWAV3
81+
PWA Kit v3 development tools for building headless storefronts.
82+
- **Status:** 🚧 Placeholder
83+
84+
| Tool | Description |
85+
|------|-------------|
86+
| `pwakit_create_storefront` | Create a new PWA Kit storefront project |
87+
| `pwakit_create_page` | Create a new page component in PWA Kit project |
88+
| `pwakit_create_component` | Create a new React component in PWA Kit project |
89+
| `pwakit_get_dev_guidelines` | Get PWA Kit development guidelines and best practices |
90+
| `pwakit_recommend_hooks` | Recommend appropriate React hooks for PWA Kit use cases |
91+
| `pwakit_run_site_test` | Run site tests for PWA Kit project |
92+
| `pwakit_install_agent_rules` | Install AI agent rules for PWA Kit development |
93+
| `pwakit_explore_scapi_shop_api` | Explore SCAPI Shop API endpoints and capabilities |
94+
| `scapi_discovery` | Discover available SCAPI endpoints and capabilities |
95+
| `scapi_custom_api_discovery` | Discover custom SCAPI API endpoints |
96+
| `mrt_bundle_push` | Build, push bundle (optionally deploy) |
97+
98+
#### SCAPI
99+
Salesforce Commerce API discovery and exploration.
100+
- **Status:** 🚧 Placeholder
101+
102+
| Tool | Description |
103+
|------|-------------|
104+
| `scapi_discovery` | Discover available SCAPI endpoints and capabilities |
105+
| `scapi_customapi_scaffold` | Scaffold a new custom SCAPI API |
106+
| `scapi_custom_api_discovery` | Discover custom SCAPI API endpoints |
107+
108+
#### STOREFRONTNEXT
109+
Storefront Next development tools for building modern storefronts.
110+
- **Status:** 🚧 Placeholder
111+
112+
| Tool | Description |
113+
|------|-------------|
114+
| `sfnext_development_guidelines` | Get Storefront Next development guidelines and best practices |
115+
| `sfnext_site_theming` | Configure and manage site theming for Storefront Next |
116+
| `sfnext_figma_to_component_workflow` | Convert Figma designs to Storefront Next components |
117+
| `sfnext_generate_component` | Generate a new Storefront Next component |
118+
| `sfnext_map_tokens_to_theme` | Map design tokens to Storefront Next theme configuration |
119+
| `sfnext_design_decorator` | Apply design decorators to Storefront Next components |
120+
| `sfnext_generate_page_designer_metadata` | Generate Page Designer metadata for Storefront Next components |
121+
| `scapi_discovery` | Discover available SCAPI endpoints and capabilities |
122+
| `scapi_custom_api_discovery` | Discover custom SCAPI API endpoints |
123+
| `mrt_bundle_push` | Build, push bundle (optionally deploy) |
124+
125+
> **Note:** Some tools appear in multiple toolsets (e.g., `mrt_bundle_push`, `scapi_discovery`). When using multiple toolsets, tools are automatically deduplicated.
126+
127+
128+
## Development
129+
130+
### Quick Start
131+
132+
```bash
133+
# Install dependencies (from monorepo root)
134+
pnpm install
135+
136+
# Navigate to the package directory
137+
cd packages/b2c-dx-mcp
138+
139+
# Build the package
140+
pnpm run build
141+
142+
# Run tests (includes linting)
143+
pnpm run test
144+
145+
# Launch MCP Inspector (builds first, then opens web UI)
146+
pnpm run inspect
147+
148+
# Format code
149+
pnpm run format
150+
151+
# Run linter only
152+
pnpm run lint
153+
154+
# Clean build artifacts
155+
pnpm run clean
156+
```
157+
158+
### Working Directory
159+
160+
Commands should be run from the `packages/b2c-dx-mcp` directory:
161+
162+
```bash
163+
cd packages/b2c-dx-mcp
164+
```
165+
166+
Or use pnpm's filter flag from the monorepo root:
167+
168+
```bash
169+
pnpm --filter @salesforce/b2c-dx-mcp run <script>
170+
```
171+
172+
### Testing the MCP Server Locally
173+
174+
#### 1. MCP Inspector
175+
176+
Use MCP Inspector to browse tools and test them in a web UI:
177+
178+
```bash
179+
pnpm run inspect
180+
```
181+
182+
This automatically builds before starting the inspector. Open the localhost URL shown in the terminal, click **Connect**, then **List Tools** to see available tools.
183+
184+
For CLI-based testing:
185+
186+
```bash
187+
# List all tools
188+
npx mcp-inspector --cli node bin/run.js --toolsets all --allow-non-ga-tools --method tools/list
189+
190+
# Call a specific tool
191+
npx mcp-inspector --cli node bin/run.js --toolsets all --allow-non-ga-tools \
192+
--method tools/call \
193+
--tool-name sfnext_design_decorator
194+
```
195+
196+
#### 2. IDE Integration
197+
198+
Configure your IDE to use the local server. Choose development mode (no build required) or production mode (requires build).
199+
200+
**Development Mode** (recommended for active development - uses TypeScript source directly):
201+
202+
```json
203+
{
204+
"mcpServers": {
205+
"b2c-dx-local": {
206+
"command": "/full/path/to/packages/b2c-dx-mcp/bin/dev.js",
207+
"args": ["--toolsets", "all", "--allow-non-ga-tools"]
208+
}
209+
}
210+
}
211+
```
212+
213+
**Production Mode** (uses compiled JavaScript - run `pnpm run build` first):
214+
215+
```json
216+
{
217+
"mcpServers": {
218+
"b2c-dx-local": {
219+
"command": "/full/path/to/packages/b2c-dx-mcp/bin/run.js",
220+
"args": ["--toolsets", "all", "--allow-non-ga-tools"]
221+
}
222+
}
223+
}
224+
```
225+
226+
> **Note:** For production mode, run `pnpm run build` after code changes and restart your IDE. Development mode picks up changes automatically.
227+
228+
#### 3. JSON-RPC via stdin
229+
230+
Send raw MCP protocol messages:
231+
232+
```bash
233+
# List all tools (--allow-non-ga-tools required for placeholder tools)
234+
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node bin/run.js --toolsets all --allow-non-ga-tools
235+
236+
# Call a specific tool
237+
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"cartridge_deploy","arguments":{}}}' | node bin/run.js --toolsets all --allow-non-ga-tools
238+
```
239+
240+
### Configuration
241+
242+
> **Note:** Configuration is not currently required as all tools are placeholder implementations. This section will be relevant once tools are fully implemented.
243+
244+
Tools that interact with B2C Commerce instances (e.g., MRT, SCAPI, cartridge deployment) require credentials, which can be provided via **environment variables**, a **`.env` file**, a **`dw.json` file**, or the **`--config`** flag. Local tools (e.g., scaffolding, development guidelines) work without configuration.
245+
246+
**Priority order** (highest to lowest):
247+
1. Environment variables (`SFCC_*`) — includes `.env` file if present (shell env vars override `.env`)
248+
2. `dw.json` file (auto-discovered or via `--config`)
249+
250+
#### Option 1: Environment Variables
251+
252+
Set environment variables directly or create a `.env` file in your project root:
253+
254+
```bash
255+
# .env file or shell exports
256+
SFCC_HOSTNAME="your-sandbox.demandware.net"
257+
SFCC_USERNAME="your.username"
258+
SFCC_PASSWORD="your-access-key"
259+
SFCC_CLIENT_ID="your-client-id"
260+
SFCC_CLIENT_SECRET="your-client-secret"
261+
SFCC_CODE_VERSION="version1"
262+
```
263+
264+
#### Option 2: dw.json File
265+
266+
Create a `dw.json` file in your project root (auto-discovered by searching upward from current working directory):
267+
268+
```json
269+
{
270+
"hostname": "your-sandbox.demandware.net",
271+
"username": "your.username",
272+
"password": "your-access-key",
273+
"client-id": "your-client-id",
274+
"client-secret": "your-client-secret",
275+
"code-version": "version1"
276+
}
277+
```
278+
279+
> **Note:** Environment variables take precedence over `dw.json` values.
280+
281+
## License
282+
283+
Apache-2.0

‎packages/b2c-dx-mcp/bin/dev.cmd‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
@echo off
2+
3+
node --conditions development --import tsx "%~dp0\dev" %*
4+

‎packages/b2c-dx-mcp/bin/dev.js‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
#!/usr/bin/env -S node --conditions development --import tsx
2+
/*
3+
* Copyright (c) 2025, Salesforce, Inc.
4+
* SPDX-License-Identifier: Apache-2
5+
* For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
6+
*/
7+
/* global process */
8+
9+
/**
10+
* Development entry point for MCP server using oclif.
11+
*
12+
* This uses oclif's development mode which:
13+
* - Uses TypeScript source directly (via tsx loader in shebang)
14+
* - Supports the 'development' condition for exports
15+
* - Loads .env file if present for local configuration
16+
* - Provides better error messages and stack traces
17+
*
18+
* Run directly: ./bin/dev.js mcp --toolsets all
19+
* Or with node: node --conditions development --import tsx bin/dev.js mcp --toolsets all
20+
*/
21+
22+
// Load .env file if present (Node.js native support)
23+
try {
24+
process.loadEnvFile();
25+
} catch {
26+
// .env file not found or not readable, continue without it
27+
}
28+
29+
import {execute} from '@oclif/core';
30+
31+
await execute({development: true, dir: import.meta.url});

‎packages/b2c-dx-mcp/bin/run.cmd‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
@echo off
2+
3+
node "%~dp0\run" %*
4+

‎packages/b2c-dx-mcp/bin/run.js‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
#!/usr/bin/env node
2+
/*
3+
* Copyright (c) 2025, Salesforce, Inc.
4+
* SPDX-License-Identifier: Apache-2
5+
* For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
6+
*/
7+
/* global process */
8+
9+
/**
10+
* Production entry point for MCP server using oclif.
11+
*
12+
* This uses oclif's production mode which:
13+
* - Uses compiled JavaScript from dist/
14+
* - Loads .env file if present for local configuration
15+
*
16+
* Run directly: ./bin/run.js mcp --toolsets all
17+
* Or with node: node bin/run.js mcp --toolsets all
18+
*/
19+
20+
// Load .env file if present (Node.js native support)
21+
try {
22+
process.loadEnvFile();
23+
} catch {
24+
// .env file not found or not readable, continue without it
25+
}
26+
27+
import {execute} from '@oclif/core';
28+
29+
await execute({dir: import.meta.url});

0 commit comments

Comments
 (0)