use BaseCommand class and update dev.js run.js to use import tsx

Author: yhsieh1

packages/b2c-dx-mcp/README.md

@@ -90,21 +90,36 @@ Add to `claude_desktop_config.json`:
 // Combine toolsets and tools
 "args": ["-y", "@salesforce/b2c-dx-mcp", "--toolsets", "CARTRIDGES", "--tools", "job_run"]
 
-// Explicit dw.json path
-"args": ["-y", "@salesforce/b2c-dx-mcp", "--toolsets", "all", "--dw-json", "/path/to/dw.json"]
+// Explicit config file path
+"args": ["-y", "@salesforce/b2c-dx-mcp", "--toolsets", "all", "--config", "/path/to/dw.json"]
 
 // Enable experimental tools
 "args": ["-y", "@salesforce/b2c-dx-mcp", "--toolsets", "all", "--allow-non-ga-tools"]
+
+// Enable debug logging
+"args": ["-y", "@salesforce/b2c-dx-mcp", "--toolsets", "all", "--debug"]
 ```
 
 ### Supported Flags
 
+#### MCP-Specific Flags
+
 | Flag | Short | Description |
 |------|-------|-------------|
 | `--toolsets` | `-s` | Comma-separated toolsets to enable (case-insensitive) |
 | `--tools` | `-t` | Comma-separated individual tools to enable (case-insensitive) |
 | `--allow-non-ga-tools` | | Enable experimental (non-GA) tools |
-| `--dw-json` | | Path to dw.json (optional, auto-discovered) |
+
+#### Global Flags (inherited from SDK)
+
+| Flag | Short | Description |
+|------|-------|-------------|
+| `--config` | | Path to dw.json config file (auto-discovered if not provided) |
+| `--instance` | `-i` | Instance name from configuration file |
+| `--log-level` | | Set logging verbosity (trace, debug, info, warn, error, silent) |
+| `--debug` | `-D` | Enable debug logging |
+| `--json` | | Output logs as JSON lines |
+| `--lang` | `-L` | Language for messages |
 
 ### Available Toolsets
 
@@ -216,37 +231,35 @@ npx mcp-inspector --cli node bin/run.js -s all --allow-non-ga-tools \
 
 #### 2. IDE Integration
 
-Configure your IDE to use the local build. First, build the package:
+Configure your IDE to use the local server. Choose development mode (no build required) or production mode (requires build).
 
-```bash
-pnpm run build
-```
+**Development Mode** (recommended for active development - uses TypeScript source directly):
 
-**Cursor** (`.cursor/mcp.json`):
 ```json
 {
   "mcpServers": {
     "b2c-dx-local": {
-      "command": "node",
-      "args": ["/full/path/to/packages/b2c-dx-mcp/bin/run.js", "-s", "all"]
+      "command": "/full/path/to/packages/b2c-dx-mcp/bin/dev.js",
+      "args": ["-s", "all"]
     }
   }
 }
 ```
 
-**Claude Desktop** (`claude_desktop_config.json`):
+**Production Mode** (uses compiled JavaScript - run `pnpm run build` first):
+
 ```json
 {
   "mcpServers": {
     "b2c-dx-local": {
-      "command": "node",
-      "args": ["/full/path/to/packages/b2c-dx-mcp/bin/run.js", "-s", "all"]
+      "command": "/full/path/to/packages/b2c-dx-mcp/bin/run.js",
+      "args": ["-s", "all"]
     }
   }
 }
 ```
 
-> **Note:** After making code changes, run `pnpm run build` and restart your IDE to pick up the changes.
+> **Note:** For production mode, run `pnpm run build` after code changes and restart your IDE. Development mode picks up changes automatically.
 
 #### 3. JSON-RPC via stdin
 

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

@@ -0,0 +1,4 @@
+@echo off
+
+node --conditions development --import tsx "%~dp0\dev" %*
+

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

@@ -1,32 +1,31 @@
-#!/usr/bin/env -S node --loader ts-node/esm --disable-warning=ExperimentalWarning
+#!/usr/bin/env -S node --conditions development --import tsx
 /*
- * Copyright 2025, Salesforce, Inc.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
  */
+/* global process */
 
 /**
  * Development entry point for MCP server using oclif.
  *
  * This uses oclif's development mode which:
- * - Uses TypeScript source directly (via ts-node/esm loader in shebang)
+ * - Uses TypeScript source directly (via tsx loader in shebang)
  * - Supports the 'development' condition for exports
+ * - Loads .env file if present for local configuration
  * - Provides better error messages and stack traces
  *
- * Run directly: ./bin/dev.js -s all
- * Or with node: node bin/dev.js -s all (uses compiled dist/ files)
+ * Run directly: ./bin/dev.js mcp -s all
+ * Or with node: node --conditions development --import tsx bin/dev.js mcp -s all
  */
 
-import { execute } from "@oclif/core";
+// Load .env file if present (Node.js native support)
+try {
+  process.loadEnvFile();
+} catch {
+  // .env file not found or not readable, continue without it
+}
+
+import {execute} from '@oclif/core';
 
-await execute({ development: true, dir: import.meta.url });
+await execute({development: true, dir: import.meta.url});

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

@@ -0,0 +1,4 @@
+@echo off
+
+node "%~dp0\run" %*
+

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

@@ -1,27 +1,29 @@
 #!/usr/bin/env node
 /*
- * Copyright 2025, Salesforce, Inc.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
+ * Copyright (c) 2025, Salesforce, Inc.
+ * SPDX-License-Identifier: Apache-2
+ * For full license text, see the license.txt file in the repo root or http://www.apache.org/licenses/LICENSE-2.0
  */
+/* global process */
 
 /**
  * Production entry point for MCP server using oclif.
  *
- * This uses oclif's single-command strategy to parse arguments
- * and start the MCP server with proper flag handling.
+ * This uses oclif's production mode which:
+ * - Uses compiled JavaScript from dist/
+ * - Loads .env file if present for local configuration
+ *
+ * Run directly: ./bin/run.js mcp -s all
+ * Or with node: node bin/run.js mcp -s all
  */
 
-import { execute } from "@oclif/core";
+// Load .env file if present (Node.js native support)
+try {
+  process.loadEnvFile();
+} catch {
+  // .env file not found or not readable, continue without it
+}
+
+import {execute} from '@oclif/core';
 
-await execute({ dir: import.meta.url });
+await execute({dir: import.meta.url});

packages/b2c-dx-mcp/package.json

@@ -95,7 +95,6 @@
     "oclif": "^4",
     "prettier": "^3.6.2",
     "shx": "^0.3.3",
-    "ts-node": "^10",
     "tsx": "^4",
     "typescript": "^5",
     "typescript-eslint": "^8"

packages/b2c-dx-mcp/src/commands/mcp.ts

@@ -23,17 +23,27 @@
  *
  * ## Flags
  *
+ * ### MCP-Specific Flags
  * | Flag | Short | Description |
  * |------|-------|-------------|
  * | `--toolsets` | `-s` | Comma-separated toolsets to enable (case-insensitive) |
  * | `--tools` | `-t` | Comma-separated individual tools to enable (case-insensitive) |
  * | `--allow-non-ga-tools` | | Enable experimental/non-GA tools |
- * | `--dw-json` | | Path to dw.json (optional, auto-discovered if not provided) |
+ *
+ * ### Global Flags (inherited from BaseCommand)
+ * | Flag | Short | Description |
+ * |------|-------|-------------|
+ * | `--config` | | Path to dw.json config file (auto-discovered if not provided) |
+ * | `--instance` | `-i` | Instance name from configuration file |
+ * | `--log-level` | | Set logging verbosity (trace, debug, info, warn, error, silent) |
+ * | `--debug` | `-D` | Enable debug logging |
+ * | `--json` | | Output logs as JSON lines |
+ * | `--lang` | `-L` | Language for messages |
  *
  * ## Configuration Priority
  *
  * 1. Environment variables (SFCC_*) - highest priority, override dw.json
- * 2. dw.json file (explicit path via --dw-json, or auto-discovered)
+ * 2. dw.json file (explicit path via --config, or auto-discovered)
  * 3. Auto-discovery (searches upward from cwd)
  *
  * ## Toolset Validation
@@ -61,13 +71,19 @@
  * b2c-dx-mcp -s SCAPI -t cartridge_deploy
  * ```
  *
- * @example Specify dw.json location
+ * @example Specify config file location
+ * ```bash
+ * b2c-dx-mcp -s all --config /path/to/dw.json
+ * ```
+ *
+ * @example Enable debug logging
  * ```bash
- * b2c-dx-mcp -s all --dw-json /path/to/dw.json
+ * b2c-dx-mcp -s all -D
  * ```
  */
 
-import { Command, Flags } from "@oclif/core";
+import { Flags } from "@oclif/core";
+import { BaseCommand } from "@salesforce/b2c-tooling-sdk/cli";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { B2CDxMcpServer } from "../server.js";
 import { Services } from "../services.js";
@@ -78,12 +94,15 @@ import { TOOLSETS, type StartupFlags } from "../utils/index.js";
  * oclif Command that starts the B2C DX MCP server.
  *
  * Uses oclif's single-command strategy - this IS the CLI, not a subcommand.
- * Inherits from oclif's Command class which provides:
+ * Extends BaseCommand from @salesforce/b2c-tooling-sdk which provides:
+ * - Global flags for config, logging, and debugging
+ * - Structured pino logging via `this.logger`
+ * - Automatic dw.json loading via `this.resolvedConfig`
  * - `this.config` - package.json metadata and standard config paths
- * - `this.parse()` - type-safe flag parsing
- * - `this.error()` - formatted error output
  */
-export default class McpServerCommand extends Command {
+export default class McpServerCommand extends BaseCommand<
+  typeof McpServerCommand
+> {
   static description =
     "Salesforce B2C Commerce Cloud Developer Experience MCP Server - Expose B2C Commerce Developer Experience tools to AI assistants";
 
@@ -92,7 +111,8 @@ export default class McpServerCommand extends Command {
     "<%= config.bin %> <%= command.id %> --toolsets STOREFRONTNEXT,MRT",
     "<%= config.bin %> <%= command.id %> --tools sfnext_deploy,mrt_bundle_push",
     "<%= config.bin %> <%= command.id %> --toolsets STOREFRONTNEXT --tools sfnext_deploy",
-    "<%= config.bin %> <%= command.id %> --toolsets MRT --dw-json /path/to/dw.json",
+    "<%= config.bin %> <%= command.id %> --toolsets MRT --config /path/to/dw.json",
+    "<%= config.bin %> <%= command.id %> --toolsets all --debug",
   ];
 
   static flags = {
@@ -116,20 +136,13 @@ export default class McpServerCommand extends Command {
       env: "SFCC_ALLOW_NON_GA_TOOLS",
       default: false,
     }),
-
-    // Configuration
-    "dw-json": Flags.string({
-      description:
-        "Path to dw.json (optional, auto-discovered if not provided)",
-      env: "SFCC_DW_JSON",
-    }),
   };
 
   /**
    * Main entry point - starts the MCP server.
    *
    * Execution flow:
-   * 1. Parse flags using oclif (with case normalization)
+   * 1. BaseCommand.init() parses flags and loads config
    * 2. Filter and validate toolsets (invalid ones are skipped with warning)
    * 3. Create B2CDxMcpServer instance
    * 4. Create Services for dependency injection (config, file system access)
@@ -140,26 +153,30 @@ export default class McpServerCommand extends Command {
    * @throws Never throws - invalid toolsets are filtered, not rejected
    *
    * @remarks
+   * BaseCommand provides:
+   * - `this.flags` - Parsed flags including global flags (config, debug, log-level, etc.)
+   * - `this.resolvedConfig` - Loaded dw.json configuration
+   * - `this.logger` - Structured pino logger
+   *
    * oclif provides standard config paths via `this.config`:
    * - `this.config.configDir` - User config (~/.config/b2c-dx-mcp)
    * - `this.config.dataDir` - User data (~/.local/share/b2c-dx-mcp)
    * - `this.config.cacheDir` - Cache (~/.cache/b2c-dx-mcp)
    * These can be exposed to Services if needed for features like telemetry or caching.
    */
   async run(): Promise<void> {
-    const { flags } = await this.parse(McpServerCommand);
-
+    // Flags are already parsed by BaseCommand.init()
     // Parse toolsets and tools from comma-separated strings
     // Note: toolsets are uppercased, tools are lowercased by their parse functions
     const startupFlags: StartupFlags = {
-      toolsets: flags.toolsets
-        ? flags.toolsets.split(",").map((s) => s.trim())
+      toolsets: this.flags.toolsets
+        ? this.flags.toolsets.split(",").map((s) => s.trim())
         : undefined,
-      tools: flags.tools
-        ? flags.tools.split(",").map((s) => s.trim())
+      tools: this.flags.tools
+        ? this.flags.tools.split(",").map((s) => s.trim())
         : undefined,
-      allowNonGaTools: flags["allow-non-ga-tools"],
-      dwJsonPath: flags["dw-json"],
+      allowNonGaTools: this.flags["allow-non-ga-tools"],
+      configPath: this.flags.config,
     };
 
     // TODO: Telemetry - Initialize telemetry unless disabled
@@ -191,8 +208,9 @@ export default class McpServerCommand extends Command {
     );
 
     // Create services for dependency injection
+    // Pass the config path for tools that need to load configuration
     const services = new Services({
-      dwJsonPath: startupFlags.dwJsonPath,
+      configPath: this.flags.config,
     });
 
     // Register toolsets
@@ -202,11 +220,14 @@ export default class McpServerCommand extends Command {
     const transport = new StdioServerTransport();
     await server.connect(transport);
 
-    // Log startup message to stderr (not stdout, which is for MCP protocol)
-    console.error(`✅ MCP Server v${this.config.version} running on stdio`);
-    console.error(`   Available toolsets: ${TOOLSETS.join(", ")}`);
-    console.error(
-      `   Enabled: ${(startupFlags.toolsets ?? []).join(", ") || "(none specified)"}`,
+    // Log startup message using the structured logger
+    this.logger.info(
+      { version: this.config.version, toolsets: TOOLSETS },
+      "MCP Server running on stdio",
+    );
+    this.logger.info(
+      { enabled: startupFlags.toolsets ?? [] },
+      "Enabled toolsets",
     );
   }
 }