@W-20593322 Developer Guidelines Tool

[yhsieh1]

Summary

This PR adds the storefront_next_development_guidelines MCP tool with multi-section selection support, allowing developers to retrieve multiple related documentation sections in a single call. This improves contextual learning by combining related topics (e.g., authentication + components + data-fetching) rather than requiring separate tool invocations.

Changes

Available Sections

The tool supports 12 documentation sections:

1. quick-reference (default) - Critical rules, architecture principles, and quick patterns
2. data-fetching - Data loading patterns with loaders, actions, and useScapiFetcher
3. state-management - Client-side state management with Zustand
4. auth - Authentication and session management
5. config - Configuration management system
6. i18n - Internationalization patterns
7. components - Component patterns and best practices
8. page-designer - Page Designer integration and component registry
9. performance - Performance optimization techniques
10. testing - Testing strategy and patterns
11. extensions - Extension development guide
12. pitfalls - Common pitfalls and how to avoid them

Test Plan

Prerequisites

• MCP server running with STOREFRONTNEXT toolset enabled
• Working directory set to a Storefront Next project
• MCP configured in Claude Desktop or Cursor

MCP Configuration:

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

1. Default Behavior

Test 1.1: No parameters

Prompt: "I'm new to Storefront Next. Use the MCP tool to show me the critical rules I need to know."

Expected: Returns quick-reference section (default), no --- separator

Verify:

• MCP tool storefront_next_development_guidelines is called
• Content is returned
• Single section output (no separators)

---

Test 1.2: Single section

Prompt: "Use the MCP tool to show me the data fetching patterns for Storefront Next."

Expected: Returns data-fetching section only, no --- separator

Verify:

• MCP tool storefront_next_development_guidelines is called
• Content is returned
• Single section output

---

2. Multi-Section Feature

Test 2.1: Multiple sections

Prompt: "I need to build a product detail page. Use the MCP tool to show me best practices for data fetching and component patterns."

Expected: Returns data-fetching, components, and performance sections

Verify:

• MCP tool storefront_next_development_guidelines is called
• Content is returned
• All requested sections present
• --- separators between sections
• Sections complete and in order

---

Test 2.2: Related topics

Prompt: "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."

Expected: Returns data-fetching, auth, and i18n sections

Verify:

• MCP tool storefront_next_development_guidelines is called
• Content is returned
• All three sections present with separators

---

3. Edge Cases

Test 3.1: Invalid section

Prompt: "Use the MCP tool to show me the guidelines for invalid-section-name."

Expected: Falls back to quick-reference (default), no error

Verify:

• MCP tool storefront_next_development_guidelines is called
• Content is returned
• Single section (no separator)

---

Test 3.2: All sections

Prompt: "Show me all available Storefront Next development guidelines."

Expected: Returns all 12 sections

Verify:

• MCP tool storefront_next_development_guidelines is called
• Content is returned
• All 12 sections present
• 11 --- separators

---

---

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

[clavery]

Will the source markdown files be accessible in the built npm package? You may want to look at the SDK and how we store markdown assets.

[yhsieh1]

@clavery Thanks for catching this. package.json is updated and md files are moved to content folder and verified the package has the md files. Thanks!

[wei-liu-sf]

should we mention where to override vars?

[wei-liu-sf]

This is no longer used, being replaced by PUBLIC__app__commerce__sites

[yhsieh1]

Thank you! My branch is behind a few commits. I will update it. We will need to have final update and review to match up latest implementation when release.

[wei-liu-sf]

ditto

[wei-liu-sf]

ditto

[wei-liu-sf]

Do you consider moving these md files to storefront-next's template instead of mcp? MCP can still find them through app dir configured.

[yhsieh1]

These are short version of the long README-XX.md on storefront-next's template. The purpose is to give a quick over view of the important feature/architecture. Each of these md also provides a reference to the detailed README-XX.md for quick reference. It still have values to keep them but as agentic IDE progresses this might change.