@W-20598954 MCP docs edits from PR reviewers

patricksullivansf · patricksullivansf · commit c10c86e0b542 · 2026-02-23T13:04:11.000-08:00
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -44,7 +44,7 @@ Issues labelled `good first contribution`.
 
 # Running the MCP server from source
 
-When developing the B2C DX MCP package (`packages/b2c-dx-mcp`), use `node` with the path to `bin/dev.js` in args. Build to latest (`pnpm run build` from the repo root) so changes that require a rebuild are reflected when you run the server.
+For information on running the MCP server from source and local development, see [packages/b2c-dx-mcp/CONTRIBUTING.md](packages/b2c-dx-mcp/CONTRIBUTING.md).
 
 # Contribution Checklist
 
diff --git a/docs/mcp/installation.md b/docs/mcp/installation.md
@@ -12,11 +12,7 @@ This guide covers installing and configuring the B2C DX MCP Server for various M
 - A B2C Commerce project (for project-specific toolsets)
 - MCP client (Cursor, Claude Desktop, or compatible client)
 
-## Installation Methods
-
-### Option 1: Published Package
-
-Once published to npm, you can use `npx`:
+## Install via npm (Recommended)
 
 ```json
 {
@@ -29,23 +25,6 @@ Once published to npm, you can use `npx`:
 }
 ```
 
-### Option 2: Development Build (Local)
-
-For local development or testing, use the development build directly:
-
-```json
-{
-  "mcpServers": {
-    "b2c-dx": {
-      "command": "node",
-      "args": ["/path/to/packages/b2c-dx-mcp/bin/dev.js", "--working-directory", "${workspaceFolder}", "--allow-non-ga-tools"]
-    }
-  }
-}
-```
-
-Replace `/path/to/packages/b2c-dx-mcp/bin/dev.js` with the actual path to your cloned repository.
-
 ## Cursor Configuration
 
 Cursor supports the `${workspaceFolder}` variable, which automatically resolves to your current workspace directory.
@@ -221,44 +200,6 @@ If no B2C markers are found:
 Projects with multiple markers (e.g., cartridges + PWA Kit) get combined toolsets. For example:
 - Cartridges + PWA Kit → CARTRIDGES, PWAV3, MRT, SCAPI
 
-## Testing the MCP Server Locally
-
-### MCP Inspector
-
-Use MCP Inspector to browse tools and test them in a web UI:
-
-```bash
-cd packages/b2c-dx-mcp
-pnpm run inspect:dev
-```
-
-This runs TypeScript directly (no build needed). Open the localhost URL shown in the terminal, click **Connect**, then **List Tools** to see available tools.
-
-### IDE Integration
-
-Configure your IDE to use the local MCP server. Add this to your IDE's MCP configuration:
-
-```json
-{
-  "mcpServers": {
-    "b2c-dx-local": {
-      "command": "node",
-      "args": [
-        "/full/path/to/packages/b2c-dx-mcp/bin/dev.js",
-        "--toolsets", "all",
-        "--allow-non-ga-tools"
-      ]
-    }
-  }
-}
-```
-
-> **Note:** When developing the B2C DX MCP package (`packages/b2c-dx-mcp`), use `node` with the path to `bin/dev.js` in args. Build to latest (`pnpm run build` from the repo root) so changes that require a rebuild are reflected when you run the server.
->
-> **Note:** Make sure the script is executable: `chmod +x /full/path/to/packages/b2c-dx-mcp/bin/dev.js`
->
-> **Note:** Restart the MCP server in your IDE to pick up code changes.
-
 ## Troubleshooting
 
 ### Server Not Starting
diff --git a/docs/mcp/tools/cartridge-deploy.md b/docs/mcp/tools/cartridge-deploy.md
@@ -34,8 +34,8 @@ Supports two authentication methods:
 
 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
-| `directory` | string | No | Current working directory | Path to directory to search for cartridges. The tool recursively searches for `.project` files to identify cartridges. |
-| `cartridges` | string[] | No | All found cartridges | Array of cartridge names to include in the deployment. Use this to selectively deploy specific cartridges when you have multiple cartridges but only want to update some. |
+| `directory` | string | No | Working directory from --working-directory flag or SFCC_WORKING_DIRECTORY env var (falls back to process.cwd()) | Path to directory to search for cartridges. The tool recursively searches for `.project` files to identify cartridges. |
+| `cartridges` | string[] | No | All found cartridges | Array of cartridge names to include in the deployment. Use this to selectively deploy specific cartridges when you have multiple cartridges but only want to update some. If not specified, all cartridges found in the directory are deployed. |
 | `exclude` | string[] | No | None | Array of cartridge names to exclude from the deployment. Use this to skip deploying certain cartridges, such as third-party or unchanged cartridges. Applied after the include filter. |
 | `reload` | boolean | No | `false` | Whether to reload the code version after deployment. When `true`, the tool triggers a code version reload on the instance. |
 
@@ -77,9 +77,8 @@ Use the MCP tool to deploy cartridges excluding test_cartridge and bm_extensions
 
 Returns a deployment result object containing:
 
-- `cartridges` - Array of cartridge names that were deployed
+- `cartridges` - Array of cartridge mappings that were deployed (each with name, src, dest)
 - `codeVersion` - Code version name used for deployment
-- `hostname` - Instance hostname where cartridges were deployed
 - `reloaded` - Whether the code version was reloaded (if `reload: true`)
 
 ## Requirements
diff --git a/docs/mcp/tools/mrt-bundle-push.md b/docs/mcp/tools/mrt-bundle-push.md
@@ -77,8 +77,8 @@ Use the MCP tool to push the bundle from ./dist directory to Managed Runtime.
 Returns a push result object containing:
 
 - `bundleId` - Unique identifier for the pushed bundle
-- `project` - MRT project slug
-- `environment` - Target environment (if deployed)
+- `projectSlug` - MRT project slug
+- `target` - Target environment (if deployed)
 - `deployed` - Whether the bundle was deployed (if `deploy: true`)
 - `message` - Deployment message (if provided)
 
diff --git a/packages/b2c-dx-mcp/CONTRIBUTING.md b/packages/b2c-dx-mcp/CONTRIBUTING.md
@@ -0,0 +1,58 @@
+# Contributing to B2C DX MCP
+
+For general contributing guidelines, see the [root CONTRIBUTING.md](../../CONTRIBUTING.md).
+
+## Development Build (Local)
+
+For local development or testing, use the development build directly:
+
+```json
+{
+  "mcpServers": {
+    "b2c-dx": {
+      "command": "node",
+      "args": ["/path/to/packages/b2c-dx-mcp/bin/dev.js", "--working-directory", "${workspaceFolder}", "--allow-non-ga-tools"]
+    }
+  }
+}
+```
+
+Replace `/path/to/packages/b2c-dx-mcp/bin/dev.js` with the actual path to your cloned repository.
+
+## Testing the MCP Server Locally
+
+### MCP Inspector
+
+Use MCP Inspector to browse tools and test them in a web UI:
+
+```bash
+cd packages/b2c-dx-mcp
+pnpm run inspect:dev
+```
+
+This runs TypeScript directly (no build needed). Open the localhost URL shown in the terminal, click **Connect**, then **List Tools** to see available tools.
+
+### IDE Integration
+
+Configure your IDE to use the local MCP server. Add this to your IDE's MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "b2c-dx-local": {
+      "command": "node",
+      "args": [
+        "/full/path/to/packages/b2c-dx-mcp/bin/dev.js",
+        "--toolsets", "all",
+        "--allow-non-ga-tools"
+      ]
+    }
+  }
+}
+```
+
+> **Note:** When developing the B2C DX MCP package (`packages/b2c-dx-mcp`), use `node` with the path to `bin/dev.js` in args. Build to latest (`pnpm run build` from the repo root) so changes that require a rebuild are reflected when you run the server.
+>
+> **Note:** Make sure the script is executable: `chmod +x /full/path/to/packages/b2c-dx-mcp/bin/dev.js`
+>
+> **Note:** Restart the MCP server in your IDE to pick up code changes.
diff --git a/packages/b2c-dx-mcp/README.md b/packages/b2c-dx-mcp/README.md
@@ -90,7 +90,7 @@ AI assistants (like Cursor, Claude Desktop) automatically decide which MCP tools
 
 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.
 
-**Good prompts:**
+**Prompt examples:**
 - ✅ "I'm new to Storefront Next. Use the MCP tool to show me the critical rules I need to know."
 - ✅ "I need to build a product detail page. Use the MCP tool to show me best practices for data fetching and component patterns."
 - ✅ "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."
@@ -114,7 +114,7 @@ The `storefront_next_development_guidelines` tool provides critical architecture
 
 ##### PWA Kit Development
 
-**Good prompts:**
+**Prompt examples:**
 - ✅ "I'm starting a new PWA Kit project. Use the MCP tool to get the development guidelines."
 - ✅ "Use the MCP tool to create a new product listing page component in my PWA Kit project."
 - ✅ "Use the MCP tool to recommend React hooks for fetching product data in PWA Kit."
@@ -153,14 +153,14 @@ Get registration status of custom API endpoints deployed on the instance (remote
 
 ##### Cartridge Deployment
 
-**Good prompts:**
+**Prompt examples:**
 - ✅ "Use the MCP tool to deploy my cartridges to the sandbox instance."
 - ✅ "Use the MCP tool to deploy only the app_storefront_base cartridge to production."
 - ✅ "Use the MCP tool to deploy cartridges from the ./cartridges directory and reload the code version."
 
 ##### MRT Bundle Operations
 
-**Good prompts:**
+**Prompt examples:**
 - ✅ "Use the MCP tool to build and push my Storefront Next bundle to staging."
 - ✅ "Use the MCP tool to push the bundle from ./build directory to Managed Runtime."
 - ✅ "Use the MCP tool to deploy my PWA Kit or Storefront Next bundle to production with a deployment message."
