Skip to content

Commit 96aa8c3

Browse files
yhsieh1yhsieh1
authored
@W-20593322 Developer Guidelines Tool (#92)
1 parent 31b410c commit 96aa8c3

20 files changed

Lines changed: 2846 additions & 24 deletions

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

Lines changed: 88 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,86 @@ Override auto-discovery by specifying toolsets explicitly:
7171
"args": ["--working-directory", "${workspaceFolder}", "--toolsets", "CARTRIDGES,MRT", "--allow-non-ga-tools"]
7272
```
7373

74+
### Prompting Tips and Examples
75+
76+
AI assistants (like Cursor, Claude Desktop) automatically decide which MCP tools to use based on your prompts. To get the best results, use clear, specific prompts that describe what you want to accomplish.
77+
78+
> ⚠️ **IMPORTANT**: **Explicitly mention "Use the MCP tool"** in your prompts for reliable tool usage. While AI assistants (like Cursor's Composer) can automatically select MCP tools based on context, explicit instructions ensure the assistant prioritizes MCP tools over general knowledge, especially when multiple approaches are possible. This is particularly important for getting project-specific, up-to-date information rather than generic responses.
79+
80+
#### Best Practices
81+
82+
1. **Always explicitly request MCP tool usage** (see warning above): Start prompts with "Use the MCP tool to..." or include "Use the MCP tool" in your request.
83+
2. **Be specific about your goal**: Instead of "help me with Storefront Next", say "Use the MCP tool to show me how to build a product detail page with authentication"
84+
3. **Mention the tool or domain explicitly**: Reference the framework (Storefront Next, PWA Kit), operation (deploy, discover), or domain (SCAPI, cartridges)
85+
4. **Use natural language**: Describe what you want to achieve, not the tool name
86+
5. **Provide context**: Mention your project type, what you're building, or what you need to learn
87+
6. **Ask for guidelines first**: When starting a new project or learning a framework, ask for development guidelines before writing code
88+
89+
#### Examples by Tool Category
90+
91+
##### Storefront Next Development Guidelines
92+
93+
The `storefront_next_development_guidelines` tool provides critical architecture rules and best practices. **Use this tool first** when starting new Storefront Next development or when you need architecture guidance.
94+
95+
**Good prompts:**
96+
- ✅ "I'm new to Storefront Next. Use the MCP tool to show me the critical rules I need to know."
97+
- ✅ "I need to build a product detail page. Use the MCP tool to show me best practices for data fetching and component patterns."
98+
- ✅ "I need to build a checkout form with authentication and validation. Use the MCP tool to show me how to handle form submissions, authentication, and internationalized error messages."
99+
- ✅ "Use the MCP tool to show me the data fetching patterns for Storefront Next."
100+
- ✅ "Show me all available Storefront Next development guidelines."
101+
102+
**Available sections:**
103+
- `quick-reference` - Critical rules and architecture principles (default)
104+
- `data-fetching` - Data loading patterns with loaders
105+
- `state-management` - Client-side state management
106+
- `auth` - Authentication and session management
107+
- `components` - Component patterns and best practices
108+
- `styling` - Tailwind CSS 4, Shadcn/ui, styling guidelines
109+
- `page-designer` - Page Designer integration
110+
- `performance` - Performance optimization
111+
- `testing` - Testing strategies
112+
- `i18n` - Internationalization patterns
113+
- `config` - Configuration management
114+
- `extensions` - Extension development
115+
- `pitfalls` - Common pitfalls
116+
117+
##### PWA Kit Development
118+
119+
**Good prompts:**
120+
- ✅ "I'm starting a new PWA Kit project. Use the MCP tool to get the development guidelines."
121+
- ✅ "Use the MCP tool to create a new product listing page component in my PWA Kit project."
122+
- ✅ "Use the MCP tool to recommend React hooks for fetching product data in PWA Kit."
123+
- ✅ "Use the MCP tool to explore the SCAPI Shop API endpoints available for my PWA Kit storefront."
124+
125+
##### SCAPI Discovery
126+
127+
**Good prompts:**
128+
- ✅ "Use the MCP tool to discover what SCAPI endpoints are available for product data."
129+
- ✅ "Use the MCP tool to discover custom SCAPI APIs in my B2C instance."
130+
- ✅ "Use the MCP tool to show me all available SCAPI endpoints and their capabilities."
131+
- ✅ "Use the MCP tool to scaffold a new custom SCAPI API for order management."
132+
133+
##### Cartridge Deployment
134+
135+
**Good prompts:**
136+
- ✅ "Use the MCP tool to deploy my cartridges to the sandbox instance."
137+
- ✅ "Use the MCP tool to deploy only the app_storefront_base cartridge to production."
138+
- ✅ "Use the MCP tool to deploy cartridges from the ./cartridges directory and reload the code version."
139+
140+
##### MRT Bundle Operations
141+
142+
**Good prompts:**
143+
- ✅ "Use the MCP tool to build and push my Storefront Next bundle to staging."
144+
- ✅ "Use the MCP tool to push the bundle from ./build directory to Managed Runtime."
145+
- ✅ "Use the MCP tool to deploy my PWA Kit bundle to production with a deployment message."
146+
147+
#### Tips for Better Results
148+
149+
- **Start with guidelines**: When learning a new framework, ask for development guidelines first using "Use the MCP tool to get..."
150+
- **Combine related topics**: Ask for multiple related sections (e.g., "data fetching and components") in one request
151+
- **Provide project context**: Mention your project type (Storefront Next, PWA Kit, cartridges) for better tool selection
152+
- **Specify operations clearly**: For deployment operations, mention the target (sandbox, staging, production) and what to deploy
153+
74154
### Configuration
75155

76156
Credentials can be provided via **config files** (recommended), **environment variables**, or **flags**. Priority: Flags > Env vars > Config files.
@@ -205,13 +285,13 @@ Storefront Next development tools for building modern storefronts.
205285

206286
| Tool | Description |
207287
|------|-------------|
208-
| `sfnext_development_guidelines` | Get Storefront Next development guidelines and best practices |
209-
| `sfnext_site_theming` | Configure and manage site theming for Storefront Next |
210-
| `sfnext_figma_to_component_workflow` | Convert Figma designs to Storefront Next components |
211-
| `sfnext_generate_component` | Generate a new Storefront Next component |
212-
| `sfnext_map_tokens_to_theme` | Map design tokens to Storefront Next theme configuration |
213-
| `sfnext_design_decorator` | Apply design decorators to Storefront Next components |
214-
| `sfnext_generate_page_designer_metadata` | Generate Page Designer metadata for Storefront Next components |
288+
| `storefront_next_development_guidelines` | Get Storefront Next development guidelines and best practices |
289+
| `storefront_next_site_theming` | Configure and manage site theming for Storefront Next |
290+
| `storefront_next_figma_to_component_workflow` | Convert Figma designs to Storefront Next components |
291+
| `storefront_next_generate_component` | Generate a new Storefront Next component |
292+
| `storefront_next_map_tokens_to_theme` | Map design tokens to Storefront Next theme configuration |
293+
| `storefront_next_design_decorator` | Apply design decorators to Storefront Next components |
294+
| `storefront_next_generate_page_designer_metadata` | Generate Page Designer metadata for Storefront Next components |
215295
| `scapi_discovery` | Discover available SCAPI endpoints and capabilities |
216296
| `scapi_custom_api_discovery` | Discover custom SCAPI API endpoints |
217297
| `mrt_bundle_push` | Build, push bundle (optionally deploy) |
@@ -287,7 +367,7 @@ npx mcp-inspector --cli node bin/dev.js --toolsets all --allow-non-ga-tools --me
287367
# Call a specific tool
288368
npx mcp-inspector --cli node bin/dev.js --toolsets all --allow-non-ga-tools \
289369
--method tools/call \
290-
--tool-name sfnext_design_decorator
370+
--tool-name storefront_next_design_decorator
291371
```
292372

293373
#### 2. IDE Integration

‎packages/b2c-dx-mcp/content/auth.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Authentication & Session Management
2+
3+
## Architecture
4+
5+
Split-cookie architecture with server/client contexts:
6+
7+
- **Server middleware** (`auth.server.ts`): Manages SLAS tokens, writes cookies
8+
- **Client middleware** (`auth.client.ts`): Reads cookies, maintains cache
9+
- **React Context** (`AuthProvider`): Provides auth state to components
10+
11+
## Cookie Design
12+
13+
| Cookie Name | Purpose | User Type | Expiry | HttpOnly |
14+
|-------------|---------|-----------|--------|----------|
15+
| `cc-nx-g` | Guest refresh token | Guest | 30 days | No |
16+
| `cc-nx` | Registered refresh token | Registered | 90 days | No |
17+
| `cc-at` | Access token | Both | 30 min | No |
18+
| `usid` | User session ID | Both | Matches refresh | No |
19+
| `customerId` | Customer ID | Registered | Matches refresh | No |
20+
21+
**Key Points**:
22+
23+
- Only ONE refresh token exists (guest OR registered, never both)
24+
- User type derived from which refresh token exists
25+
- Cookies auto-namespaced with `siteId`
26+
- Tokens auto-refresh when expired
27+
28+
## Usage in Loaders/Actions
29+
30+
```typescript
31+
import { getAuth } from '@/middlewares/auth.server';
32+
33+
export function loader({ context }: LoaderFunctionArgs) {
34+
const auth = getAuth(context);
35+
36+
// Access auth properties
37+
const accessToken = auth.access_token;
38+
const customerId = auth.customer_id;
39+
const isGuest = auth.userType === 'guest';
40+
const isRegistered = auth.userType === 'registered';
41+
42+
return { isGuest, customerId };
43+
}
44+
```
45+
46+
## Usage in Components
47+
48+
```typescript
49+
import { useAuth } from '@/providers/auth';
50+
51+
export function MyComponent() {
52+
const auth = useAuth();
53+
54+
if (auth?.userType === 'guest') {
55+
return <LoginPrompt />;
56+
}
57+
58+
return <div>Welcome, customer {auth?.customer_id}</div>;
59+
}
60+
```
61+
62+
**Reference:** See README-AUTH.md for complete authentication documentation.

‎packages/b2c-dx-mcp/content/components.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
# Component Patterns
2+
3+
## Use the `createPage` HOC
4+
5+
The `createPage` higher-order component standardizes page patterns with built-in Suspense and page key handling:
6+
7+
```typescript
8+
import { use } from 'react';
9+
import { createPage } from '@/components/create-page';
10+
11+
// Define your view component
12+
function ProductView({
13+
product,
14+
category
15+
}: {
16+
product: Promise<Product>;
17+
category?: Promise<Category>
18+
}) {
19+
const productData = use(product);
20+
const categoryData = category ? use(category) : null;
21+
22+
return (
23+
<div>
24+
<h1>{productData.name}</h1>
25+
{categoryData && <p>Category: {categoryData.name}</p>}
26+
</div>
27+
);
28+
}
29+
30+
// Create page with fallback
31+
const ProductPage = createPage({
32+
component: ProductView,
33+
fallback: <ProductSkeleton />
34+
});
35+
36+
export default ProductPage;
37+
```
38+
39+
**Benefits:**
40+
41+
- Eliminates repetitive Suspense/Await boilerplate
42+
- Consistent loading states across pages
43+
- Built-in page key management for navigation transitions
44+
- Type-safe with full TypeScript support
45+
46+
## shadcn/ui Components
47+
48+
**RULES**:
49+
50+
- ✅ Add via: `npx shadcn@latest add <component-name>`
51+
- ❌ DO NOT modify `src/components/ui/` directly
52+
- ✅ Create custom components elsewhere
53+
54+
## Suspense Boundaries
55+
56+
Use granular Suspense boundaries for better UX:
57+
58+
```typescript
59+
// ✅ RECOMMENDED - Multiple Suspense boundaries
60+
export default function ProductPage({ loaderData: { product, reviews } }) {
61+
return (
62+
<div>
63+
<Suspense fallback={<ProductHeaderSkeleton />}>
64+
<Await resolve={product}>
65+
{(data) => <ProductHeader product={data} />}
66+
</Await>
67+
</Suspense>
68+
69+
<Suspense fallback={<ReviewsSkeleton />}>
70+
<Await resolve={reviews}>
71+
{(data) => <ProductReviews reviews={data} />}
72+
</Await>
73+
</Suspense>
74+
</div>
75+
);
76+
}
77+
78+
// ⚠️ OK - Single Suspense boundary (less granular)
79+
export default createPage({
80+
component: ProductView,
81+
fallback: <ProductPageSkeleton />
82+
});
83+
```
84+
85+
## File Organization
86+
87+
```
88+
src/components/product-tile/
89+
├── index.tsx # Component
90+
├── index.test.tsx # Tests
91+
└── stories/
92+
├── index.stories.tsx # Storybook stories
93+
└── __snapshots__/ # Storybook snapshots (optional)
94+
└── product-tile-snapshot.tsx.snap
95+
96+
# Skeleton components are separate components
97+
src/components/product-skeleton/
98+
├── index.tsx
99+
├── index.test.tsx
100+
└── stories/
101+
└── index.stories.tsx
102+
```
103+
104+
## Styling
105+
106+
**Tailwind CSS 4** is the only styling approach allowed. Use utility classes directly in components.
107+
108+
**Key rules:**
109+
110+
- ✅ Use Tailwind utility classes
111+
- ✅ Use `cn()` utility for conditional classes
112+
- ❌ NO inline styles, NO CSS modules, NO separate CSS files
113+
114+
**See `styling` section for:** Tailwind CSS 4, Shadcn/ui components, icons, responsive design, theme configuration, dark mode, best practices
115+
116+
## Best Practices
117+
118+
1. **Extract view components** - Separate data handling from presentation
119+
2. **Type safety** - Define proper TypeScript interfaces
120+
3. **Consistent fallbacks** - Reusable skeleton components
121+
4. **Colocate tests** - Keep tests next to components
122+
5. **Story coverage** - Create stories for all reusable components
123+
6. **Tailwind utilities only** - Use Tailwind CSS classes, avoid inline styles or CSS modules

0 commit comments

Comments
 (0)