Skip to content

Commit eee5dbc

Browse files
yhsieh1yhsieh1
authored
@W-21197996 Update MCP docs (#217)
1 parent 8798335 commit eee5dbc

File tree

5 files changed

+250
-1
lines changed

5 files changed

+250
-1
lines changed

‎.changeset/mcp-tool-reference-docs.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'@salesforce/b2c-dx-docs': patch
3+
---
4+
5+
Add MCP tool reference documentation for pwakit_development_guidelines and storefront_next_development_guidelines; MCP Server sidebar, Tools Reference, and nav updates in config

‎docs/.vitepress/config.mts‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,6 +51,15 @@ const guideSidebar = [
5151
{text: 'Storefront Next', link: '/guide/storefront-next'},
5252
],
5353
},
54+
{
55+
text: 'MCP Server',
56+
items: [
57+
{text: 'Overview', link: '/mcp/'},
58+
{text: 'Installation', link: '/mcp/installation'},
59+
{text: 'Configuration', link: '/mcp/configuration'},
60+
{text: 'Toolsets & Tools', link: '/mcp/toolsets'},
61+
],
62+
},
5463
{
5564
text: 'Extending',
5665
items: [
@@ -83,6 +92,18 @@ const guideSidebar = [
8392
{text: 'Logging', link: '/cli/logging'},
8493
],
8594
},
95+
{
96+
text: 'Tools Reference',
97+
items: [
98+
{text: 'cartridge_deploy', link: '/mcp/tools/cartridge-deploy'},
99+
{text: 'mrt_bundle_push', link: '/mcp/tools/mrt-bundle-push'},
100+
{text: 'pwakit_development_guidelines', link: '/mcp/tools/pwakit-development-guidelines'},
101+
{text: 'scapi_schemas_list', link: '/mcp/tools/scapi-schemas-list'},
102+
{text: 'scapi_custom_apis_status', link: '/mcp/tools/scapi-custom-apis-status'},
103+
{text: 'storefront_next_development_guidelines', link: '/mcp/tools/storefront-next-development-guidelines'},
104+
{text: 'storefront_next_page_designer_decorator', link: '/mcp/tools/storefront-next-page-designer-decorator'},
105+
],
106+
},
86107
];
87108

88109
// Script to force hard navigation for version switching links
@@ -133,6 +154,7 @@ export default defineConfig({
133154
{text: 'Guide', link: '/guide/'},
134155
{text: 'CLI Reference', link: '/cli/'},
135156
{text: 'API Reference', link: '/api/'},
157+
{text: 'MCP Server', link: '/mcp/'},
136158
{
137159
text: isDevBuild ? 'Dev' : 'Latest',
138160
items: getVersionItems(),
@@ -147,6 +169,7 @@ export default defineConfig({
147169
sidebar: {
148170
'/guide/': guideSidebar,
149171
'/cli/': guideSidebar,
172+
'/mcp/': guideSidebar,
150173
'/api/': [
151174
{
152175
text: 'API Reference',

‎docs/mcp/tools/pwakit-development-guidelines.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
---
2+
description: Get PWA Kit v3 development guidelines and best practices for React, Chakra UI, and Commerce API.
3+
---
4+
5+
# pwakit_development_guidelines
6+
7+
Returns critical architecture rules, coding standards, and best practices for building PWA Kit v3 applications with React, Chakra UI, and Commerce API. **Use this tool first** before writing any PWA Kit code.
8+
9+
## Overview
10+
11+
The `pwakit_development_guidelines` tool provides essential development guidance for PWA Kit v3. It:
12+
13+
1. Returns comprehensive guidelines by default (quick-reference plus key sections).
14+
2. Supports retrieving specific topic sections on demand.
15+
3. Loads content from markdown files covering components, data fetching, routing, configuration, and more.
16+
17+
**Important:** This tool is the **essential first step** for PWA Kit v3 development. Use it before writing any code to understand non-negotiable patterns for React components, data fetching, routing, configuration, and framework constraints.
18+
19+
This tool is part of the PWAV3 toolset and is auto-enabled for PWA Kit v3 projects (detected by `@salesforce/pwa-kit-*` dependencies).
20+
21+
## Authentication
22+
23+
No authentication required. This tool operates on local content only—guidelines are loaded from markdown files bundled with the MCP server.
24+
25+
## Parameters
26+
27+
| Parameter | Type | Required | Default | Description |
28+
|-----------|------|----------|---------|-------------|
29+
| `sections` | string[] | No | `['quick-reference', 'components', 'data-fetching', 'routing']` | Optional array of specific sections to retrieve. If not specified, returns comprehensive guidelines. Pass an empty array to return an empty string. |
30+
31+
### Available Sections
32+
33+
| Section | Topics Covered |
34+
|---------|----------------|
35+
| `quick-reference` | Critical rules, architecture principles, quick patterns |
36+
| `components` | Component patterns, Chakra UI, special components (_app, _app-config, _error), React Hooks |
37+
| `data-fetching` | React Query, commerce-sdk-react hooks, useCustomQuery/useCustomMutation, custom APIs, caching |
38+
| `routing` | Express.js, React Router, configureRoutes, SSR/CSR navigation, withReactQuery, getProps patterns |
39+
| `config` | Configuration files, environment variables, file precedence, proxy setup, multi-site |
40+
| `state-management` | Context API, useReducer, Redux integration, AppConfig methods |
41+
| `extensibility` | Template extension, ccExtensibility configuration, overrides directory |
42+
| `testing` | Jest, React Testing Library, MSW, test organization, coverage |
43+
| `i18n` | React Intl, translation extraction/compilation, multi-locale support |
44+
| `styling` | Chakra UI theming, Emotion CSS-in-JS, responsive design |
45+
46+
## Usage Examples
47+
48+
### Default (Comprehensive Guidelines)
49+
50+
Get the default comprehensive set (quick-reference, components, data-fetching, routing):
51+
52+
```
53+
Use the MCP tool to get PWA Kit development guidelines before I start coding.
54+
```
55+
56+
### Single Section
57+
58+
Retrieve a specific topic:
59+
60+
```
61+
Use the MCP tool to get PWA Kit guidelines for data-fetching patterns.
62+
```
63+
64+
### Multiple Related Sections
65+
66+
Combine related sections in one call:
67+
68+
```
69+
Use the MCP tool to get PWA Kit guidelines for components, routing, and config.
70+
```
71+
72+
### All Sections
73+
74+
Retrieve all available sections:
75+
76+
```
77+
Use the MCP tool to get all PWA Kit development guidelines.
78+
```
79+
80+
## Output
81+
82+
Returns text content with guidelines for the requested section(s):
83+
84+
- **Single section**: Returns content directly (no separators or instructions).
85+
- **Multiple sections**: Returns content with `---` separators between sections, prefixed with instructions to display full content without summarization.
86+
87+
The returned content includes:
88+
89+
- Critical rules and best practices
90+
- Code examples (correct ✅ and incorrect ❌ patterns)
91+
- Quick reference snippets
92+
- Framework-specific patterns for React, Chakra UI, and commerce-sdk-react
93+
94+
## Requirements
95+
96+
- PWA Kit v3 project or general PWA Kit development context
97+
- No credentials or instance configuration needed
98+
99+
## Related Tools
100+
101+
- Part of the [PWAV3](../toolsets#pwav3) toolset
102+
- Auto-enabled for PWA Kit v3 projects (detected by `@salesforce/pwa-kit-*` dependencies)
103+
- [`mrt_bundle_push`](./mrt-bundle-push) - Build and push bundles to Managed Runtime
104+
105+
## See Also
106+
107+
- [PWAV3 Toolset](../toolsets#pwav3) - Overview of PWA Kit v3 tools
108+
- [Configuration](../configuration) - Configure MCP server and toolset selection

‎docs/mcp/tools/storefront-next-development-guidelines.md‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
---
2+
description: Get Storefront Next development guidelines and best practices for React Server Components, data loading, and framework constraints.
3+
---
4+
5+
# storefront_next_development_guidelines
6+
7+
Returns critical architecture rules, coding standards, and best practices for building Storefront Next applications with React Server Components. **Use this tool first** before writing any Storefront Next code.
8+
9+
## Overview
10+
11+
The `storefront_next_development_guidelines` tool provides essential development guidance for Storefront Next. It:
12+
13+
1. Returns comprehensive guidelines by default (quick-reference plus key sections).
14+
2. Supports retrieving specific topic sections on demand.
15+
3. Loads content from markdown files covering architecture, data fetching, components, testing, and more.
16+
17+
**Important:** This tool is the **essential first step** for Storefront Next development. Use it before writing any code to understand non-negotiable patterns for React Server Components, data loading, and framework constraints.
18+
19+
This tool is part of the STOREFRONTNEXT toolset and is auto-enabled for Storefront Next projects (detected by `@salesforce/storefront-next*` dependencies).
20+
21+
## Authentication
22+
23+
No authentication required. This tool operates on local content only—guidelines are loaded from markdown files bundled with the MCP server.
24+
25+
## Parameters
26+
27+
| Parameter | Type | Required | Default | Description |
28+
|-----------|------|----------|---------|-------------|
29+
| `sections` | string[] | No | `['quick-reference', 'data-fetching', 'components', 'testing']` | Optional array of specific sections to retrieve. If not specified, returns comprehensive guidelines. Pass an empty array to return an empty string. |
30+
31+
### Available Sections
32+
33+
| Section | Topics Covered |
34+
|---------|----------------|
35+
| `quick-reference` | Critical rules, architecture principles, quick patterns |
36+
| `data-fetching` | Server-only data loading (no client loaders), synchronous loaders for streaming, data fetching patterns |
37+
| `state-management` | State management patterns |
38+
| `auth` | Authentication and session management |
39+
| `config` | Configuration system |
40+
| `i18n` | i18n patterns and internationalization |
41+
| `components` | Component best practices |
42+
| `styling` | Tailwind CSS 4, Shadcn/ui, styling guidelines |
43+
| `page-designer` | Page Designer integration |
44+
| `performance` | Performance optimization |
45+
| `testing` | Testing strategies |
46+
| `extensions` | Framework extensions |
47+
| `pitfalls` | Common pitfalls to avoid |
48+
49+
## Usage Examples
50+
51+
### Default (Comprehensive Guidelines)
52+
53+
Get the default comprehensive set (quick-reference, data-fetching, components, testing):
54+
55+
```
56+
Use the MCP tool to get Storefront Next development guidelines before I start coding.
57+
```
58+
59+
### Single Section
60+
61+
Retrieve a specific topic:
62+
63+
```
64+
Use the MCP tool to get Storefront Next guidelines for data-fetching patterns.
65+
```
66+
67+
### Multiple Related Sections
68+
69+
Combine related sections in one call:
70+
71+
```
72+
Use the MCP tool to get Storefront Next guidelines for data-fetching, components, and performance.
73+
```
74+
75+
### All Sections
76+
77+
Retrieve all available sections:
78+
79+
```
80+
Use the MCP tool to get all Storefront Next development guidelines.
81+
```
82+
83+
## Output
84+
85+
Returns text content with guidelines for the requested section(s):
86+
87+
- **Single section**: Returns content directly (no separators or instructions).
88+
- **Multiple sections**: Returns content with `---` separators between sections, prefixed with instructions to display full content without summarization.
89+
90+
The returned content includes:
91+
92+
- Critical rules and best practices
93+
- Code examples (correct ✅ and incorrect ❌ patterns)
94+
- Quick reference snippets
95+
- Framework-specific patterns for React Server Components
96+
97+
## Requirements
98+
99+
- Storefront Next project or general Storefront Next development context
100+
- No credentials or instance configuration needed
101+
102+
## Related Tools
103+
104+
- Part of the [STOREFRONTNEXT](../toolsets#storefrontnext) toolset
105+
- Auto-enabled for Storefront Next projects
106+
- [`storefront_next_page_designer_decorator`](./storefront-next-page-designer-decorator) - Add Page Designer decorators to components
107+
108+
## See Also
109+
110+
- [STOREFRONTNEXT Toolset](../toolsets#storefrontnext) - Overview of Storefront Next tools
111+
- [Storefront Next Guide](../../guide/storefront-next) - User guide for Storefront Next
112+
- [Configuration](../configuration) - Configure MCP server and toolset selection

‎docs/mcp/toolsets.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,7 @@ PWA Kit v3 development tools for building headless storefronts.
6161

6262
| Tool | Description | Documentation |
6363
|------|-------------|---------------|
64+
| [`pwakit_development_guidelines`](./tools/pwakit-development-guidelines) | Get PWA Kit v3 development guidelines and best practices | [View details](./tools/pwakit-development-guidelines) |
6465
| [`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) |
6566
| [`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) |
6667
| [`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) |
@@ -94,7 +95,7 @@ Storefront Next development tools for building modern storefronts.
9495

9596
| Tool | Description | Documentation |
9697
|------|-------------|---------------|
97-
| `storefront_next_development_guidelines` | Get Storefront Next development guidelines and best practices | — |
98+
| [`storefront_next_development_guidelines`](./tools/storefront-next-development-guidelines) | Get Storefront Next development guidelines and best practices | [View details](./tools/storefront-next-development-guidelines) |
9899
| [`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) |
99100
| [`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) |
100101
| [`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) |

0 commit comments

Comments
 (0)